symlink
symlink manages one symbolic link on a node: the link's path and the text
of its target, or the link's removal. The symlink module replaces or removes
links, and replace_existing_file: true also permits replacing a regular file.
The symlink module never modifies the link's target. To manage a regular
file, use file; to delete a directory, use
directory.
Inputs
path(string; required): absolutetarget(string; required): stored literally and may dangle; omit with absentreplace_existing_file(boolean; defaultfalse): true: a regular file at path is replaced by the link in one atomic rename; a directory at path is always an errorstate(presentorabsent; defaultpresent): absent accepts only path and state
Outputs
The node task's result holds these fields. A later node task reads them as .node_tasks.<id>.<field>, where <id> is the node task's id.
statuschange
What a dryrun reports
Supported; previews the link action, including a regular file the link would replace; not_checked while the parent directory is missing, unless an earlier node task of the dryrun would create it.
Retries and time limits
Bounded automatic retries by default; retry: false turns them off.
The node task takes the time limits time_limit and time_limit_per_try; without them, the project's node_task_defaults apply. mmx describe-module task describes the settings every node task accepts.
Examples
Create a link, and remove one
- symlink:
path: /etc/myapp/enabled.conf
target: available.conf
- symlink:
path: /etc/myapp/old-link.conf
state: absent
On the node, the first task makes /etc/myapp/enabled.conf a link to
available.conf. A relative link target starts at the link's parent
directory, here /etc/myapp. A link may point to something that does not
exist yet. The second task removes the link /etc/myapp/old-link.conf.
Replace a file that a package installed
A package sometimes installs a regular file where you want a link. Add
replace_existing_file: true, and the link replaces that file in one atomic
rename:
- symlink:
path: /etc/nginx/sites-enabled/default
target: /etc/nginx/sites-available/myapp
replace_existing_file: true
Dryrun reports that the file would be replaced. Without
replace_existing_file: true, a regular file at the link's path fails the
node task. MMX therefore never deletes a file nobody asked MMX to delete.
A directory at the path is always an error.
Switch a release
A tracked symlink in a node task block switches a service to the release
directory that unpack_archive
or git put in place. The switch restarts the service, also after
an interrupted run.
How it works
path is absolute. The target is stored literally, as written, and may
dangle. Creation and retargeting replace the link atomically; removal unlinks
only the link. state: absent accepts only path and state.
Within a node task block, link target changes contribute to the service configuration hash: the record used to decide whether a service must load new configuration. Link tracking does not follow targets or scan directory trees. Declare the target files too if MMX manages their contents.
Dryrun shows link actions; Preview file changes describes the previews.
Tested on
Distributions: Debian 12 and 13, Ubuntu 24.04 and 26.04, Arch Linux, openSUSE Leap 16.1, Rocky Linux 9, AlmaLinux 10, Fedora 45.
The base suite covers this module (file_resources.py) and runs on every tested distribution.
This page is docs/reference/modules/symlink.md in the MMX repository.