Skip to content

Unit Files Syntax

Systemd unit files are configuration files that define how services, sockets, timers, and other units should behave in a systemd-managed system. These files are written in a structured key-value format and dictate the lifecycle, dependencies, and runtime parameters for systemd units. Understanding their structure is critical for customizing and debugging systemd-based services.

Structure of a Unit File

A typical unit file contains multiple [Section] blocks, each defining specific aspects of the unit. The most common sections are [Unit], [Service], and [Install], though other sections like [Socket] or [Timer] exist for specialized unit types.

[Unit] Section

The [Unit] section provides metadata and dependencies. Key directives include: - Description: A human-readable description of the unit. - After: Specifies units that must start before this one. - Requires: Ensures dependent units are started. - Conflicts: Defines units that cannot run simultaneously.

Example: 

[Unit]
Description=My Custom Service
After=network.target
Requires=network-online.target

[Service] Section

The [Service] section defines how the service should run. Key directives include: - ExecStart: The command to start the service. - WorkingDirectory: The directory to run the service from. - Restart: Specifies restart policies (e.g., always, on-failure). - User and Group: The user and group to run the service as.

Example: 

[Service]
ExecStart=/usr/bin/myapp --flag
WorkingDirectory=/opt/myapp
Restart=always
User=myuser
Group=mygroup

[Install] Section

The [Install] section determines how the unit is linked to systemd's service management. Key directives include: - WantedBy: Specifies the target (e.g., multi-user.target) to enable the service. - Alias: Provides an alternative name for the unit.

Example: 

[Install]
WantedBy=multi-user.target
Alias=myapp.service

Other Unit Types

Socket Units

Socket units manage socket activation. They define how systemd should listen for connections and spawn the service when needed. Key directives include: - SocketMode: Permissions for the socket file. - ListenStream: Specifies TCP/UDP sockets. - PassThrough: Controls whether the socket is passed to the service.

Example: 

[Socket]
ListenStream=8080
SocketMode=0666
PassThrough=socket

Timer Units

Timer units schedule services to run at specific intervals. They use a [Timer] section with directives like: - OnCalendar: Defines the schedule (e.g., *-*-* 12:00:00 for daily at noon). - Unit: Links the timer to a service unit.

Example: 

[Timer]
OnCalendar=daily
Unit=myapp.service

Managing Unit Files

  • Viewing Unit Files: Use systemctl cat <unit-name> to inspect the contents of a unit file.
  • Overriding Defaults: Use systemctl edit <unit-name> to create override files in /etc/systemd/system/.
  • Validating Syntax: Run systemd-analyze verify <unit-file> to check for syntax errors.

Key Takeaways

  • Unit files define the behavior of systemd units through structured sections like [Unit], [Service], and [Install].
  • Different unit types (e.g., socket, timer) use specialized sections to manage their unique functionality.
  • Always validate unit files for syntax errors and test changes in a controlled environment.
  • Overrides and custom unit files in /etc/systemd/system/ allow fine-grained control over systemd behavior.