Creat ing Cust om Unit Files

There are several use cases for creating unit files from scratch: you could run a custom daemon, create a second instance of some existing service (as in Example 8.17, “ Creating a second instance of the sshd service”), or import a SysV init script (more in Section 8.6.3, “ Converting SysV Init Scripts to Unit Files”). On the other hand, if you intend just to modify of extend the behavior of an existing unit, use the instructions from Section 8.6.4, “ Modifying Existing Unit Files”. The following procedure describes the general process of creating a custom service:

[a] Fo r a co mp lete list o f o p tio ns co nfig urab le in the [Install] sectio n, see the systemd . uni t(5) manual p ag e.

1. Prepare the executable file with the custom service. This can be 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. It is also possible to include environment files to store shell variables for the service. Make sure the source script is executable (by executing the chmo d 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 ro o t:

to uch /etc/systemd /system/name. servi ce chmo d 6 6 4 /etc/systemd /system/name. servi ce

Replace name with a name of the service to be created. Note that file does not need to be executable.

3. Open the name. servi ce file created in the previous step, and add the service configuration options. There is a variety of options that can be used depending on the type of service you wish to create, see Section 8.6.1, “ Understanding the 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 Where:

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.

T ype= fo rki ng 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 Table 8.10, “ Important [Service] Section Options”.

Wanted By 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, see Section 8.3,

“ Working with systemd Targets” for details.

4. Notify systemd that a new name. servi ce file exists by executing the following command as ro o t:

systemctl d aemo n-rel o ad systemctl start name. servi ce

The name.service unit can now be managed as any other system service with commands described in Section 8.2, “ Managing System Services”.

Examp le 8.16 . Creat in g t h e emacs.service File

When using the Emacs text editor, it is often faster and more convenient to have it running in the background instead of starting a new instance of the program whenever editing a file. The following steps show how to create a unit file for Emacs, so that it can be handled like a service.

1. Create unit file in the /etc/systemd /system/ directory and make sure it has correct file permissions. Execute as ro o t:

~]# to uch /etc/systemd /system/emacs. servi ce

~]# chmo d 6 6 4 /etc/systemd /system/emacs. servi ce 2. Add the following content to the file:

[Unit]

Description=Emacs: the extensible, self-documenting text editor

[Service]

Type=forking

ExecStart=/usr/bin/emacs --daemon

ExecStop=/usr/bin/emacsclient --eval "(kill-emacs)"

Environment=SSH_AUTH_SOCK=%t/keyring/ssh Restart=always

[Install]

WantedBy=default.target

With the above configuration, the /usr/bi n/emacs executable is started in daemon mode on service start. The SSH_AUTH_SOCK environment variable is set using the "% t" unit specifier that stands for the runtime directory. The service also restarts the emacs process if it exits unexpectedly.

3. Execute the following commands to reload the configuration and start the custom service:

~]# systemctl d aemo n-rel o ad

~]# systemctl start emacs. servi ce

As the editor is now registered as a systemd service, you can use all standard systemctl commands, such as systemctl status emacs to display its status systemctl enabl e emacs or to start it automatically on system boot.

Examp le 8.17. Creat in g a seco n d in st an ce o f t h e ssh d service

System Administrators often need to configure and run multiple instances of a service. This is done by creating copies of the original service configuration files and modifying certain parameters to avoid conflicts with the primary instance of the service. The following procedure shows how to create a second instance of the sshd service:

1. Create a copy of the sshd _co nfi g file that will be used by the second daemon:

~]# cp /etc/ssh/sshd {,-seco nd }_co nfi g

2. Edit the sshd -seco nd _co nfi g 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

See the sshd _co nfi g(5) manual page for more information on P o rt and P i d Fi l e 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/l i b/systemd /system/sshd {,-seco nd }. servi ce 4. Alter the sshd -seco nd . servi ce created in the previous step as follows:

a. Modify the D escri pti o n option:

Description=OpenSSH server second instance daemon

b. 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

c. The first instance of sshd includes key generation, therefore remove the ExecStartPre=/usr/sbin/sshd-keygen line.

d. Add the -f /etc/ssh/sshd -seco nd _co nfi g 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

e. After the above modifications, the sshd-second.service should look as follows:

[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

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:

~]# semanag e po rt -a -t ssh_po rt_t -p tcp 22220 6. Enable sshd-second.service, so that it starts automatically upon boot:

~]# systemctl enabl e sshd -seco nd . servi ce

Verify if the sshd-second.service is running by using the systemctl status command.

Also, verify if the port is enabled correctly by connecting to the service:

~]$ ssh -p 22220 user@ server

If firewall is in use, please make sure that it is configured appropriately in order to allow connections to the second instance of sshd.