Skip to content

linux-ln-tutorial.md

Latest commit

 

History

History
199 lines (139 loc) · 8.46 KB

linux-ln-tutorial.md

File metadata and controls

199 lines (139 loc) · 8.46 KB
Raw
title Linux Command Tutorial: ln
date 2026-09-12 00:00:00 +0000
categories
Technology
tags
Linux
GNU Coreutils
ln
Linux Command Tutorial
draft false
slug linux-ln-tutorial
description Authoritative reference tutorial for ln (GNU Coreutils), detailing hard links, symbolic links, atomic replacement (-sf), relative targets, and POSIX portability.
upstream_suite gnu-coreutils
upstream_version GNU Coreutils 9.11
posix_standard POSIX.1-2024
research_date 2026-09-12

The Linux Command Tutorial series provides rigorous, upstream-verified references for essential system commands across Linux distributions and UNIX-like environments. Each article focuses on a single executable, combining exhaustive option documentation, verified real-world examples, security boundaries, and best practices directly derived from official source documentation and POSIX standards.

1. Introduction

Upstream: GNU Coreutils 9.11 | POSIX: POSIX.1-2024 (with GNU extensions) | Safety Tier: unprivileged-filesystem-write | Scope: Hard link creation, symbolic link aliasing & atomic release switching

ln creates links between files. It creates either hard links (additional directory entries pointing to an existing filesystem inode) or symbolic links (soft links storing a text path string pointing to another filesystem location).

  • Upstream Project & Provenance: Distributed in GNU Coreutils (coreutils).
  • Portability & Standards Baseline: Standardized in IEEE Std 1003.1-2024 (POSIX.1-2024). GNU ln adds atomic replacement options (-f), relative target generation (-r), and directory protections (-T).
  • Target Research Implementation: Audited against GNU Coreutils 9.11 (ln(1)).
  • Applicability & Lifecycle: The foundational command for library aliasing, zero-downtime release pointing, and deduplication.

2. Syntax and Command Model

2.1 Canonical Synopsis

# Create a link to TARGET with specified LINK_NAME:
ln [OPTION]... [-T] TARGET LINK_NAME

# Create a link to TARGET in the current directory:
ln [OPTION]... TARGET

# Create links to multiple TARGETs in DIRECTORY:
ln [OPTION]... TARGET... DIRECTORY
ln [OPTION]... -t DIRECTORY TARGET...

2.2 Hard Links vs Symbolic Links

Characteristic Hard Link (ln) Symbolic Link (ln -s)
Mechanism Creates new directory entry sharing identical inode number. Creates new inode of type S_IFLNK containing path string.
Cross-Filesystem No (restricted to the same filesystem/mount). Yes (can point to any path or unmounted device).
Directory Targets Restricted to root on non-standard setups; generally forbidden. Permitted.
Dangling Pointers Cannot dangle (storage persists until all hard links are deleted). Can dangle if target file is renamed or deleted.

3. Options

3.1 Primary Operational Flags

Short Flag Long Flag Description POSIX Defined
-s --symbolic Make symbolic links instead of hard links. Yes
-f --force Remove existing destination files before creating link. Yes
-n --no-dereference Treat LINK_NAME as a normal file if it is a symlink to a directory. No
-r --relative Create symbolic links relative to link location. No
-v --verbose Print name of each linked file. No
-T --no-target-directory Treat LINK_NAME as a normal file always. No
-t --target-directory=DIR Specify directory in which to create links. No
N/A --backup[=CONTROL] Make a backup of each existing destination file. No

4. Basic Usage

4.1 Quick Reference & Common Invocations

Task / Scenario Command Key Flags / Behavior
Create symbolic link (soft) ln -s /path/to/target link_name Creates symlink pointing to target
Create hard link ln original.txt hardlink.txt Creates directory entry referencing same inode
Overwrite existing symlink ln -sfn /new/release /app/current -f unlinks old; -n prevents descending
Automatic relative symlink ln -sr /usr/local/bin/app /usr/bin/app -r computes ../ relative path automatically
Force overwrite regular file ln -sf target.txt existing_link -f removes destination before creating link
Atomic link swap with protection ln -sfnT /var/www/v2 /var/www/active -T guarantees destination is treated as a file
Link multiple files to directory ln -s -t /opt/bin/ /opt/apps/* -t sets destination directory upfront

4.2 Creating a Hard Link

ln original.txt hardlink.txt

4.3 Creating a Symbolic Link

ln -s /etc/nginx/sites-available/app.conf /etc/nginx/sites-enabled/app.conf

5. Practical Operations

5.1 Atomic Symlink Replacement (Zero-Downtime Deployments)

Updating an active release symlink pointing to a new build:

ln -sfn /opt/releases/v2.4.0 /opt/releases/current
  • Technical Analysis:
    • -s: Symbolic link.
    • -f: Unlink existing destination /opt/releases/current.
    • -n: Treat destination as a symlink itself, rather than dereferencing it and creating /opt/releases/current/v2.4.0.

5.2 Creating Automatic Relative Symlinks

Creating portable symlinks between relative directory trees without calculating relative ../ offsets manually:

ln -s -r /usr/local/bin/custom_node /usr/bin/node
  • GNU ln -r automatically computes the relative path and stores ../local/bin/custom_node inside the symlink.

6. Advanced Usage

6.1 Avoiding Directory Traps with -T

When pointing a symlink to an existing directory without accidental nesting:

ln -sfnT /var/www/v2 /var/www/active
  • With -T, ln treats /var/www/active strictly as a file target rather than a directory, cleanly replacing the symlink.

7. Exit Status, Environment, and Configuration

7.1 Exit Status Codes

Exit Code Meaning
0 Success: all links created successfully.
>0 An error occurred (destination exists without -f, cross-device hard link attempt).

8. Safety, Security, and Portability

8.1 Symlink Race Attacks in /tmp

Warning

Symlink Race Vulnerability in Sticky Directories: In world-writable directories such as /tmp, malicious local users can create symlinks pointing to sensitive files (such as /etc/shadow or application configs) to hijack administrative writes.

Modern Linux kernels mitigate this with the fs.protected_symlinks=1 sysctl parameter (/proc/sys/fs/protected_symlinks), which prevents following symlinks in sticky directories unless the caller owns either the symlink or the containing directory.

8.2 Hard Link Cross-Filesystem Limitations

Note

Hard links share underlying inode numbers within a single filesystem. Attempting to create a hard link across separate mount points or filesystem partitions fails with EXDEV (Invalid cross-device link). Use symbolic links (-s) for cross-device paths.

9. Best Practices

  1. Always Combine -sfn When Overwriting Directory Symlinks:

    [!IMPORTANT] Guidance: Use ln -sfn <target> <link> when re-pointing deployment links. Authoritative Justification: GNU documentation explains that -n stops ln from descending into the directory targeted by the existing link.

  2. Use -r for Portable Relative Symlinks:

    [!TIP] Guidance: Generate relative symlinks using ln -sr. Authoritative Justification: Prevents broken symlinks when chrooted or mounted under different root prefixes.

  3. Never Attempt Hard Links Across Mount Boundaries:

    [!IMPORTANT] Guidance: Use symbolic links (-s) whenever paths might span different filesystems or partitions. Authoritative Justification: Hard links require shared inode tables; cross-device hard links are rejected at the VFS layer (EXDEV).

References

  1. GNU Coreutils ln Manual: https://www.gnu.org/software/coreutils/manual/html_node/ln-invocation.html
  2. POSIX.1-2024 ln Specification: The Open Group Base Specifications Issue 8. https://pubs.opengroup.org/onlinepubs/9799919799/utilities/ln.html
  3. Linux symlink(2) System Call: https://man7.org/linux/man-pages/man2/symlink.2.html