Chapter 1. Working with systemd unit files

Procedure

1. To create a custom service, prepare the executable file with the service. The file can contain a custom-created script, or an executable delivered by a software provider. If required, prepare a PID file to hold a constant PID for the main process of the custom service. You can also include environment files to store shell variables for the service. Make sure the source script is executable (by executing the chmod a+x) and is not interactive.

2. Create a unit file in the /etc/systemd/system/ directory and make sure it has correct file permissions. Execute as root:

   # touch /etc/systemd/system/<name>.service
   
   # chmod 644 /etc/systemd/system/<name>.service

   Copy to Clipboard Toggle word wrap

   Replace <name> with a name of the service you want to create. Note that the file does not need to be executable.

3. Open the created <name>.service file and add the service configuration options. You can use various options depending on the type of service you wish to create, see Unit file structure.

   The following is an example unit configuration for a network-related service:

   [Unit]
   Description=<service_description>
   After=network.target
   
   [Service]
   ExecStart=<path_to_executable>
   Type=forking
   PIDFile=<path_to_pidfile>
   
   [Install]
   WantedBy=default.target

   Copy to Clipboard Toggle word wrap
   • <service_description> is an informative description that is displayed in journal log files and in the output of the systemctl status command.
   • The After setting ensures that the service is started only after the network is running. Add a space-separated list of other relevant services or targets.
   • path_to_executable stands for the path to the actual service executable.
   • Type=forking is used for daemons that make the fork system call. The main process of the service is created with the PID specified in path_to_pidfile. Find other startup types in Important [Service] section options.
   • WantedBy states the target or targets that the service should be started under. Think of these targets as of a replacement of the older concept of runlevels.

4. Notify systemd that a new <name>.service file exists:

   # systemctl daemon-reload
   
   # systemctl start <name>.service

   Copy to Clipboard Toggle word wrap
   Warning

   Always execute the systemctl daemon-reload command after creating new unit files or modifying existing unit files. Otherwise, the systemctl start or systemctl enable commands could fail due to a mismatch between states of systemd and actual service unit files on disk. Note, that on systems with a large number of units this can take a long time, as the state of each unit has to be serialized and subsequently deserialized during the reload.

1. Create a copy of the sshd_config file that the second daemon will use:

   # cp /etc/ssh/sshd{,-second}_config

   Copy to Clipboard Toggle word wrap

2. Edit the sshd-second_config file created in the previous step to assign a different port number and PID file to the second daemon:

   Port 22220
   PidFile /var/run/sshd-second.pid

   Copy to Clipboard Toggle word wrap

   See the sshd_config(5) manual page for more information about Port and PidFile options. Make sure the port you choose is not in use by any other service. The PID file does not have to exist before running the service, it is generated automatically on service start.

3. Create a copy of the systemd unit file for the sshd service:

   # cp /usr/lib/systemd/system/sshd.service /etc/systemd/system/sshd-second.service

   Copy to Clipboard Toggle word wrap

4. Alter the created sshd-second.service:

   1. Modify the Description option:

      Description=OpenSSH server second instance daemon

      Copy to Clipboard Toggle word wrap

   2. Add sshd.service to services specified in the After option, so that the second instance starts only after the first one has already started:

      After=syslog.target network.target auditd.service sshd.service

      Copy to Clipboard Toggle word wrap
   3. Remove the ExecStartPre=/usr/sbin/sshd-keygen line, the first instance of sshd includes key generation.

   4. Add the -f /etc/ssh/sshd-second_config parameter to the sshd command, so that the alternative configuration file is used:

      ExecStart=/usr/sbin/sshd -D -f /etc/ssh/sshd-second_config $OPTIONS

      Copy to Clipboard Toggle word wrap

   5. After the modifications, the sshd-second.service unit file contains the following settings:

      [Unit]
      Description=OpenSSH server second instance daemon
      After=syslog.target network.target auditd.service sshd.service
      
      [Service]
      EnvironmentFile=/etc/sysconfig/sshd
      ExecStart=/usr/sbin/sshd -D -f /etc/ssh/sshd-second_config $OPTIONS
      ExecReload=/bin/kill -HUP $MAINPID
      KillMode=process
      Restart=on-failure
      RestartSec=42s
      
      [Install]
      WantedBy=multi-user.target

      Copy to Clipboard Toggle word wrap

5. If using SELinux, add the port for the second instance of sshd to SSH ports, otherwise the second instance of sshd will be rejected to bind to the port:

   # semanage port -a -t ssh_port_t -p tcp 22220

   Copy to Clipboard Toggle word wrap

6. Enable sshd-second.service to start automatically on boot:

   # systemctl enable sshd-second.service

   Copy to Clipboard Toggle word wrap
7. Verify if the sshd-second.service is running by using the systemctl status command.

8. Verify if the port is enabled correctly by connecting to the service:

   $ ssh -p 22220 user@server

   Copy to Clipboard Toggle word wrap

   Make sure you configure firewall to allow connections to the second instance of sshd.

Procedure

1. Depending on the extent of the required changes, pick one of the following approaches:

   • Create a directory for supplementary configuration files at /etc/systemd/system/<unit>.d/. This method is recommended for most use cases. You can extend the default configuration with additional functionality, while still referring to the original unit file. Changes to the default unit introduced with a package upgrade are therefore applied automatically. See Extending the default unit configuration for more information.
   • Create a copy of the original unit file from /usr/lib/systemd/system/`directory in the `/etc/systemd/system/ directory and make changes there. The copy overrides the original file, therefore changes introduced with the package update are not applied. This method is useful for making significant unit changes that should persist regardless of package updates. See Overriding the default unit configuration for details.
2. To return to the default configuration of the unit, delete custom-created configuration files in the /etc/systemd/system/ directory.

3. Apply changes to unit files without rebooting the system:

   # systemctl daemon-reload

   Copy to Clipboard Toggle word wrap

   The daemon-reload option reloads all unit files and recreates the entire dependency tree, which is needed to immediately apply any change to a unit file. As an alternative, you can achieve the same result with the following command:

   # init q

   Copy to Clipboard Toggle word wrap

4. If the modified unit file belongs to a running service, restart the service:

   # systemctl restart <name>.service

   Copy to Clipboard Toggle word wrap

Procedure

1. Create a configuration directory in /etc/systemd/system/:

   # mkdir /etc/systemd/system/<name>.service.d/

   Copy to Clipboard Toggle word wrap

   Replace <name> with the name of the service you want to extend. The syntax applies to all unit types.

2. Create a configuration file with the .conf suffix:

   # touch /etc/systemd/system/name.service.d/<config_name>.conf

   Copy to Clipboard Toggle word wrap

   Replace <config_name> with the name of the configuration file. This file adheres to the normal unit file structure and you have to specify all directives in the appropriate sections, see Unit file structure.

   For example, to add a custom dependency, create a configuration file with the following content:

   [Unit]
   Requires=<new_dependency>
   After=<new_dependency>

   Copy to Clipboard Toggle word wrap

   The <new_dependency> stands for the unit to be marked as a dependency. Another example is a configuration file that restarts the service after its main process exited, with a delay of 30 seconds:

   [Service]
   Restart=always
   RestartSec=30

   Copy to Clipboard Toggle word wrap

   Create small configuration files focused only on one task. Such files can be easily moved or linked to configuration directories of other services.

3. Apply changes to the unit:

   # systemctl daemon-reload
   # systemctl restart <name>.service

   Copy to Clipboard Toggle word wrap

Procedure

1. Copy the unit file to the /etc/systemd/system/ directory by entering the following command as root:

   # cp /usr/lib/systemd/system/<name>.service /etc/systemd/system/<name>.service

   Copy to Clipboard Toggle word wrap
2. Open the copied file with a text editor, and make changes.

3. Apply unit changes:

   # systemctl daemon-reload
   # systemctl restart <name>.service

   Copy to Clipboard Toggle word wrap

1. Copy the httpd unit file to the /etc/systemd/system/ directory:

   # cp /usr/lib/systemd/system/httpd.service /etc/systemd/system/httpd.service

   Copy to Clipboard Toggle word wrap

2. Open the /etc/systemd/system/httpd.service file and specify the TimeoutStartUSec value in the [Service] section:

   ...
   [Service]
   ...
   PrivateTmp=true
   TimeoutStartSec=10
   
   [Install]
   WantedBy=multi-user.target
   ...

   Copy to Clipboard Toggle word wrap

3. Reload the systemd daemon:

   # systemctl daemon-reload

   Copy to Clipboard Toggle word wrap