How do I fix 'ln reports invalid cross-device link'?

Likely cause: Hard links cannot span filesystems. Fix: Use a symbolic link instead, or keep both names on the same mount.

How do I fix 'Symlink shows as red/dangling in ls'?

Likely cause: Its target was moved or deleted. Fix: Recreate the target or repoint with ln -sfn; find dangling links with find -xtype l.

How do I fix 'ln -sf followed the old link into a directory'?

Likely cause: Without -n, ln dereferences a symlink that points to a directory. Fix: Always use ln -sfn for the atomic swap pattern.

How do I fix 'Hard link edits appear in both names unexpectedly'?

Likely cause: That is correct behavior: both names share one inode. Fix: Copy (cp) instead of linking when you need independent files.

How do I fix 'readlink shows a relative path that resolves wrongly'?

Likely cause: Relative symlinks resolve from the link's directory, not your cwd. Fix: Prefer absolute targets for system paths like /srv/current.

Linux Hard & Soft Links: Hands-On Tutorial

I worked through hard versus symbolic links by inspecting inodes and link counts with ls -i and stat. Symlinks enabled atomic configuration swaps (the current-release pointer pattern) while hard links shared data without duplication.

Objective & Context

Links are how Linux references the same data from multiple paths. This lab clarifies that hard links share an inode (same data, multiple names) while symlinks are pointers to a path, then applies symlinks for zero-downtime config and release switching.

Learning Objectives

Explain the difference between hard links and symbolic links using inodes.
Create hard links and verify shared inodes and link counts with ls -li.
Create symbolic links and inspect their targets with stat and readlink.
Identify dangling symlinks and clean them up safely.
Perform an atomic release switch with ln -sfn for zero-downtime deploys.

Environment & Prerequisites

Prerequisites

Any Linux shell with GNU coreutils (ln, ls, stat are preinstalled everywhere).
A filesystem that supports hard links for step 1 (ext4, xfs, btrfs all qualify; FAT and most network mounts do not).
Sample files to link and a scratch directory such as ~/lab/links.
Basic familiarity with ls -l output from the file management lab.

flowchart LR N1[name A] --> I[(inode + data)] N2[hard link B] --> I S[symlink] -->|path pointer| N1

Step-by-Step Execution

1. Compare inodes of a hard link

echo hello > file.txt && ln file.txt hard.txt && ls -li file.txt hard.txt

Expected output:

524301 -rw-r--r-- 2 taki taki 6 2026-06-17 09:12 file.txt
524301 -rw-r--r-- 2 taki taki 6 2026-06-17 09:12 hard.txt

What this teaches: Identical inode numbers prove both names point to the same data blocks; the link count of 2 shows two directory entries reference that inode. Deleting one name only decrements the count, and the data survives until the count reaches zero.

2. Create a symlink and inspect it

ln -s /srv/releases/v2 /srv/current && stat /srv/current

Expected output:

  File: /srv/current -> /srv/releases/v2
  Size: 15              Blocks: 0          IO Block: 4096   symbolic link

What this teaches: stat reveals a symlink is its own tiny file holding a path string (Size 15, Blocks 0); readlink -f resolves the full chain to the real target.

3. Atomic release switch

ln -sfn /srv/releases/v3 /srv/current

Expected output:

(no output on success; verify with: readlink /srv/current)
/srv/releases/v3

What this teaches: The -n flag stops ln from dereferencing an existing symlink to a directory, and -f replaces it; together they swap the pointer atomically so readers never see a half-updated path. This needs sudo when /srv is root-owned.

How It Works

A Unix filesystem separates names from data. The inode holds the data blocks, permissions, and timestamps; a directory is just a table mapping names to inode numbers. A hard link adds another name for the same inode, so both names are equal peers and the data survives until the last name is removed and the last open descriptor closes.

A symbolic link is a different object entirely: a small file whose content is a path string. The kernel resolves it at open time, which means symlinks can point across filesystems and to directories, but also means they break (dangle) when the target moves. Tools like readlink and stat -c %N expose the link layer so you can tell names apart from data.

The atomic swap works because renaming a symlink is a single filesystem operation. ln -sfn creates the new link and renames it over the old one in one step, so a web server reading /srv/current either gets the old release or the new one, never a missing path. This is the same mechanism behind zero-downtime deployment tools.

flowchart LR subgraph HL["Hard links"] N1["name A"] --> I["inode 524301"] N2["name B"] --> I I --> D["data blocks"] end subgraph SL["Symlink"] N3["/srv/current"] --> P["path string: /srv/releases/v3"] P --> I2["inode 778812"] --> D2["release data"] end

Validation & Testing

Delete the original name of a hard-linked file and confirm the data survives via the other name; repoint a symlink and confirm consumers see the new target atomically. Pass criteria: hard links share an inode and survive original deletion; symlink swap is instantaneous.

Troubleshooting

Symptom	Likely cause	Fix
ln reports invalid cross-device link	Hard links cannot span filesystems	Use a symbolic link instead, or keep both names on the same mount
Symlink shows as red/dangling in ls	Its target was moved or deleted	Recreate the target or repoint with ln -sfn; find dangling links with find -xtype l
ln -sf followed the old link into a directory	Without -n, ln dereferences a symlink that points to a directory	Always use ln -sfn for the atomic swap pattern
Hard link edits appear in both names unexpectedly	That is correct behavior: both names share one inode	Copy (cp) instead of linking when you need independent files
readlink shows a relative path that resolves wrongly	Relative symlinks resolve from the link's directory, not your cwd	Prefer absolute targets for system paths like /srv/current
Too many levels of symbolic links error	Symlinks form a loop pointing at each other	Break the cycle by removing one link and repointing it correctly

Advanced: Troubleshooting

Cross-filesystem hard link fails: hard links cannot span filesystems; use a symlink.
Dangling symlink: the target moved or was deleted; recreate or repoint.
Non-atomic swap: use ln -sfn to replace a symlink in one step.

Key Results

Demonstrated shared-inode behaviour of hard links with link counts.
Implemented zero-downtime release switching with atomic symlink swaps.
Distinguished symlink path-pointers from inode-sharing hard links.
Avoided data duplication for shared references via hard links.

Key Takeaways

Hard links are extra names for one inode; symlinks are path pointers stored as tiny files.
Same inode plus a link count above 1 identifies hard-linked names.
Symlinks can cross filesystems and point to directories; hard links cannot.
ln -sfn swaps a symlink atomically, which enables zero-downtime releases.
Relative symlink targets resolve from the link's own directory.

Practice Challenges

Challenge 1: Prove shared data

Goal: create a hard link, append text through one name, and show it appears through the other; then delete the original and show the data survives.

Hint: compare inode numbers with ls -li.

Challenge 2: Hunt dangling links

Goal: find every broken symlink under /etc and /srv, then decide for each whether to repoint or remove it.

Hint: find has a -xtype l test for this exact job.

Working with Hard and Symbolic Links via inodes

Objective & Context

Learning Objectives

Environment & Prerequisites

Prerequisites

Step-by-Step Execution

1. Compare inodes of a hard link

2. Create a symlink and inspect it

3. Atomic release switch

How It Works

Validation & Testing

Troubleshooting

Key Results

Key Takeaways

Practice Challenges

Challenge 1: Prove shared data

Challenge 2: Hunt dangling links

Related Labs