systemctl-link

Link a unit file to make it available for systemd commands

$ systemctl link [path/to/service]

$ systemctl link [path/to/service1 path/to/service2 ...]

systemctl [OPTIONS] link PATH...

PATH...
    One or more absolute paths to unit files (e.g., .service, .socket, .timer) or directories containing unit files. These files will be symbolically linked into systemd's configuration directories.

--user
    Operate on the user systemd instance rather than the system-wide instance. Units will be linked into ~/.config/systemd/user/.

--runtime
    Link units temporarily into /run/systemd/system/ (or /run/user//systemd/ for user units), which are lost upon system reboot or user logout. This option is useful for testing without making permanent changes.

--force
    Overwrite existing symbolic links at the target location if they already exist. Use with caution as this can replace manually managed links.

The systemctl link command is a powerful utility within systemd used to integrate unit files located outside of systemd's default search paths directly into the system's unit configuration. Instead of copying a unit file (e.g., a service, socket, or timer) into a standard directory like /etc/systemd/system/ or /usr/lib/systemd/system/, systemctl link creates symbolic links to the original unit file(s) from a specified path.

These symlinks are typically created in /etc/systemd/system/ for system-wide units, or in ~/.config/systemd/user/ if the --user option is specified. This functionality is particularly useful for developers, for testing custom unit files, or for scenarios where unit files are managed by a version control system and should not be moved from their source location. After linking, systemctl daemon-reload must be executed to make systemd aware of the new units. Once linked and reloaded, these units can then be managed (started, stopped, enabled, disabled) like any other systemd unit. The command can accept one or more paths, which can be individual unit files or directories containing unit files.

Persistence: systemctl link creates symbolic links; it does not copy or move the unit files. If the original unit file is moved or deleted from its source location, the symlink will break, and systemd will no longer be able to manage the unit.

Reload Required: After executing systemctl link, a systemctl daemon-reload command is necessary for the systemd manager to rescan its unit files and recognize the newly linked units.

Permissions: Linking into system-wide directories (e.g., /etc/systemd/system/) typically requires root privileges. Linking into user directories (with --user) requires appropriate user permissions.

Path Resolution: Ensure the PATH provided is an absolute path. Relative paths might lead to unexpected behavior or broken links if systemd's working directory changes.

Activation: systemctl link makes a unit available to systemd; it does not automatically start or enable the unit to run on boot. You still need to use systemctl start and systemctl enable after linking and reloading.

Systemd searches for unit files in a defined order across several directories. When systemctl link is used, it typically creates symlinks in /etc/systemd/system/ (for system units) or ~/.config/systemd/user/ (for user units). Units in /etc/systemd/system/ take precedence over units of the same name found in /run/systemd/system/ and /usr/lib/systemd/system/. Understanding this hierarchy is crucial for troubleshooting unit conflicts or unexpected behavior.

systemctl link can link entire directories containing multiple unit files. When a directory path is provided, systemd attempts to create symlinks for all valid unit files found within that directory. This streamlines the process of integrating a collection of related services or configurations.

To link a custom service file located at /opt/my-app/my-service.service:
sudo systemctl link /opt/my-app/my-service.service
Then, reload systemd to recognize it:
sudo systemctl daemon-reload
And finally, enable and start the service:
sudo systemctl enable my-service.service
sudo systemctl start my-service.service

The systemctl command is an integral part of systemd, which was initially released in 2010 to replace the traditional SysVinit and Upstart init systems in Linux distributions. The link subcommand has been a fundamental feature since early versions of systemd, providing a flexible way for administrators and developers to integrate custom unit files without requiring them to be physically copied into systemd's standard directories. This capability became increasingly important as systemd gained widespread adoption, emphasizing modularity and simplified service management through symlinks rather than direct file manipulation in system directories. Its design reflects systemd's broader philosophy of relying on standard filesystem features (like symlinks) for configuration and management.

systemctl(1), systemctl enable(1), systemctl disable(1), systemctl start(1), systemctl stop(1), systemctl daemon-reload(1)