Skip to content
Documentation
State Modules
link

link

Manages a symbolic or hard link at a path. Complements the file module by adding dedicated hard-link support and a focused two-state model when the link itself is the resource. Idempotent: re-applying an unchanged declaration reports no change.

Category: Storage

States

StateMeaning
presentA link exists at the path pointing at target — a symlink (kind: symlink, the default) or a hard link (kind: hard).
absentNothing exists at the path; an existing link or file is removed. A directory is left in place with an error (use the file module).

Parameters

ParameterTypeRequiredDescription
targetstringyesWhat the link points at. Required for state: present; rejected for state: absent. Symlink targets are stored verbatim and not resolved against the link’s directory.
kindstringsymlink (default) for a symbolic link, or hard for a hard link. A hard-link target must exist and be on the same filesystem. Only meaningful with state: present. Default: symlink.
forceboolReplace an existing non-matching file at the path. A directory is never auto-removed. Default: false.

Examples

Symbolic link 

link:
  /usr/local/bin/myapp:
    state: present
    target: /opt/myapp/bin/myapp

Hard link, replacing any existing file

The target must exist and live on the same filesystem.

link:
  /var/lib/myapp/current:
    state: present
    target: /var/lib/myapp/releases/v1.0.0
    kind: hard
    force: true

Remove a link 

link:
  /etc/myapp/old.conf:
    state: absent

Notes

  • Filesystem-agnostic: Linux and macOS in v1.0; Windows links are out of scope.
  • target is required for state: present and rejected for state: absent.
  • Symlink targets are compared and stored verbatim; relative targets are not normalised or canonicalised.
  • For owner/group on the link itself, use the file module’s symlink state.
disklvm