mkunit link

Link an existing unit file to systemd.

mkunit link <file> [flags]

Description

The link command creates a symbolic link from your systemd unit directory to an existing unit file. This is ideal for keeping unit files in version control (git) while still having them active in systemd.

Instead of copying the unit file, mkunit creates a symlink so changes to your source file are immediately reflected. This enables a workflow where you can:

Arguments

Argument Description
<file> Path to the unit file (must have valid extension: .service, .timer, .path, .socket, .mount, .target)

Flags

Flag Description Default
--system Link as a system unit (to /etc/systemd/system) false
--install, -i Enable the unit after linking false
--start Start the unit after enabling false
--force, -f Overwrite existing symlink or file false
--dry-run Show what would happen without making changes false

Examples

Basic usage

# Link a unit file from current directory
mkunit link ./myapp.service

Link and enable

# Link and enable the unit to start on boot
mkunit link ./myapp.service --install

Link, enable, and start

# Link, enable, and start immediately
mkunit link ./myapp.service --install --start

System service (requires sudo)

# Link as a system service
sudo mkunit link ./myapp.service --system --install

Preview without making changes

# See what would happen
mkunit link ./myapp.service --dry-run

Overwrite existing link

# Replace an existing symlink
mkunit link ./myapp.service --force --install

Version Control Workflow

The recommended workflow for managing unit files with git:

1. Create unit file in your repository

# Generate the unit file to a local directory
mkunit service myapp \
  --exec "/usr/bin/myapp" \
  --output ./systemd/myapp.service \
  --no-interactive

2. Commit to version control

git add systemd/myapp.service
git commit -m "Add myapp systemd unit"

3. Link on deployment

# On each machine after cloning the repo
mkunit link ./systemd/myapp.service --install

# For system services
sudo mkunit link ./systemd/myapp.service --system --install

How It Works

When you run mkunit link:

  1. Validates the source file exists and has a valid unit extension
  2. Resolves the source path to an absolute path
  3. Creates a symbolic link in the systemd directory:
    • User units: ~/.config/systemd/user/
    • System units: /etc/systemd/system/
  4. Runs systemctl daemon-reload to pick up the new unit
  5. Optionally enables and starts the unit

See Also