Friday, December 27, 2013

What Is Systemd and How It Works (Part 2)

Hello everyone,
Today, I continue the systemd discussion, part2. If you haven't read or missed part 1, you can find it in the following link: http://ktaraghi.blogspot.ca/2013/11/what-is-systemd-and-how-it-works-part-1.html.
In part 1, I said and explained that the common configuration items (in unit files) are configured in the generic [Unit] and [Install] sections. Now, I am going to explain the specific configuration options such as [Service], [Socket] in Unit files.

As you know, from part 1, a unit configuration file whose name ends in .service encodes information about a process controlled and supervised by systemd. A good example could be rsyslog.service or httpd.service.The service specific configuration options are configured in the [Service] section (Figure 1).

                                                                               Figure 1

According to man page, the important options specific to the [Service] section of service units are the following:

Type= 
Configures the process start-up type for this service unit. One of simple, forking, oneshot, dbus, notify or idle.
If set to simple, it is expected that the process configured with ExecStart= is the main process of the service. In this mode, as I explained in part 1, if the process offers functionality to other processes on the system, its communication channels should be installed before the daemon is started up (e.g. sockets set up by systemd, via socket activation), as systemd will immediately proceed starting follow-up units.
If set to forking it is expected that the process configured with ExecStart= will call fork() as part of its start-up. The parent process is expected to exit when start-up is complete and all communication channels set up. The child continues to run as the main daemon process. This is the behavior of traditional UNIX daemons. If this setting is used, it is recommended to also use the PIDFile=
option, so that systemd can identify the main process of the daemon. systemd will proceed starting follow-up units as soon as the parent process exits.
Behavior of dbus is similar to simple, however it is expected that the daemon acquires a name on the D-Bus bus, as configured by BusName=. systemd will proceed starting follow-up units after the D-Bus bus name has been acquired.
Behavior of notify is similar to simple, however it is expected that the daemon sends a notification message via sd_notify(3) or an equivalent call when it finished starting up. systemd will proceed starting follow-up units after this notification message has been sent.

PIDFile=
Takes an absolute file name pointing to the PID file of this daemon. Use of this option is recommended for services where Type= is set to forking. systemd will read the PID of the main process of the daemon after start-up of the service.

BusName=
Takes a D-Bus bus name, that this service is reachable as. This option is mandatory for services where Type= is set to dbus.

ExecStart=
Commands with their arguments that are executed when this service is started. The first argument must be an absolute path name. Basic environment variable substitution is supported. Use ${FOO} as part of a word, or as a word of its own on the command line, in which case it will be replaced by the value of the environment variable including all whitespace it contains, resulting in a single argument. Note that this setting does not directly support shell command lines. If shell command lines are to be used they need to be passed explicitly to a shell implementation of some kind. Example:   ExecStart=/bin/sh -c 'dmesg | tac'

ExecStartPre=, ExecStartPost=  
Additional commands that are executed before or after the command in ExecStart=, respectively. Syntax is the same as for ExecStart=

ExecReload=
Commands to execute to trigger a configuration reload in the service.

ExecStop=
Commands to execute to stop the service started via ExecStart=.

TimeoutStartSec=
Time to wait before starting the ExecStart=.

Restart=
Configures whether the service shall be restarted when the service process exits, is killed, or a timeout is reached. Takes one of no, on-success, on-failure, on-abort, or always. If set to no (the default) the service will not be restarted. If set to on-success it will be restarted only when the service process exits cleanly. In this context, a clean exit means an exit code of 0, or one of the signals SIGHUP, SIGINT, SIGTERM, or SIGPIPE. If set to on-failure the service will be restarted when the process exits with an nonzero exit code, is terminated by a signal (including on core dump), when an operation (such as service reload) times out, and when the configured watchdog timeout is triggered.
If set to on-abort the service will be restarted only if the service process exits due to an uncaught signal not specified as a clean exit status. If set to always the service will be restarted regardless whether it exited cleanly or not, got terminated abnormally by a signal or hit a timeout.

PermissionsStartOnly=
Boolean value, if true the permission based options are applied, such as User.

RootDirectoryStartOnly=
Boolean value, if true, the RootDirectory option applies only to the ExecStart option.

Let's see some examples (Figure 2 and 3):

                                                                           Figure 2


                                                                          Figure 3


Now, according to man page, a unit configuration file whose name ends in .socket encodes information about an IPC or network socket or a file system FIFO controlled and supervised by systemd, for socket-based activation. Socket units may be used to implement on-demand starting of services, as well as parallelized starting of services.
For each socket file a matching service file must exist, describing the service to start on incoming
traffic on the socket. Depending on the setting of Accept= (see below), this must either be named like the socket unit, but with the suffix replaced; or it must be a template file named the same way. Example: a socket file foo.socket needs a matching service foo.service if Accept=false is set. If Accept=true is set a service template file foo@.service must exist from which services are instantiated for each incoming connection.

The options specific to the [Socket] section of socket units are the following:

ListenStream=, ListenDatagram=, ListenSequentialPacket=
Specifies an address to listen on for a stream (SOCK_STREAM), datagram (SOCK_DGRAM), or sequential packet (SOCK_SEQPACKET) socket respectively. The address can be written in various formats (The address can be a port number, path name for a socket device, or IPv4 or IPv6 address and port number):
If the address starts with a slash (/), it is read as file system socket in the AF_UNIX socket family.
If the address starts with an at symbol (@) it is read as abstract namespace socket in the AF_UNIX family. The @ is replaced with a NUL character before binding.
If the address string is a single number it is read as port number to listen on via IPv6. Depending on the value of BindIPv6Only=  this might result in the service being available via both IPv6 and IPv4 (default) or just via IPv6.
If the address string is a string in the format v.w.x.y:z it is read as IPv4 specifier for listening on an address v.w.x.y on a port z.

Accept=
Takes a boolean argument. If true, a service instance is spawned for each incoming connection and only the connection socket is passed to it. If false, all listening sockets themselves are passed to the started service unit, and only one service unit is spawned for all connections.
 
MaxConnections=
The maximum number of connections to simultaneously run services instances for, when Accept=true is set. If more concurrent connections are coming in, they will be refused until at least one existing connection is terminated. This setting has no effect for sockets configured with Accept=false or datagram sockets. Defaults to 64.

Service= Specifies the service unit name to activate on incoming traffic. This defaults to the service that bears the same name as the socket.

Let's see an example (Figure 4 and 5):

                                                                              Figure 4

                                                                             Figure 5

And that's it for today. In part 3, I will continue and talk about Template unit files and special targets in systemd. Don't miss it.
Thanks all,
Khosro Taraghi

Friday, November 29, 2013

What Is Systemd and How It Works (Part 1)



systemd is a system and service manager and recent Fedora is using systemd (Fedora 18 and above, I think). System startup is managed by systemd now and all original System V (init system for starting individual services) and Upstart service has been deprecated and phased out.

The old System V was using different scripts(daemons) sequentially in different runlevels. For example, System V starts ssh service in runlevel 5 after firewall and network service because ssh service depends on network service. This sequentially running of services make a slow startup and that’s why System V has been phased out.

The new Systemd starts daemons at same time and this parallel running of daemons means a very fast startup. How come? Well, systemd uses sockets for all services. It sets up sockets for daemons and coordinates between them as they start up. So, when a daemon requires support from another daemon, systemd coordinate the data from their sockets . For example, daemon A starts and it needs a support from daemon B, however, daemon B has not started yet . Therefore, systemd writes daemon A’s request to daemon B’s socket(buffering) and it continues. So daemon A doesn’t need to wait for daemon B. As soon as daemon B starts, it will read its socket. This means parallel processing and system boots very fast. The socket activation was designed by Apple’s OS X system.

systemd is compatible with System V and actually systemd uses System V’s configurations and scripts as additional information files. If there is no any configuration file for systemd already, systemd will use System V scripts and configuration files to generate a corresponding configuration files. However, systemd configuration files always take precedence. For example, systemd uses /etc/fstab to generate corresponding systemd configuration file system or looks at /etc/rc.d directory to finds start and stop files and determines dependencies.

Configuration for systemd tasks are defined in unit files. Therefore, systemd defines different units files for different tasks and each unit file has its own configuration file. Unit files are divided to the following categories:

service 
target 
socket 
device 
mount 
automount 
path 
snapshot 
swap 
timer

So, those unit files that are related to “service” have “.service” extension or unit files related to “mount” have “.mount” extension and so forth. An good example can be boot.mount or smb.service.

Now, inside each unit file, there are directives and configuration options. Some of these directives and options are common to all units and you can find it in systemd.unit man page.

man systemd.unit

According to man page, this man page(systemd.unit) lists the common configuration options of all the unit types. These options need to be configured in the [Unit] or [Install] sections of the unit files.

In addition, you can find a list of configuration options shared by services, sockets, mount and swap unit types in systemd.exec man page:

man systemd.exec

The execution specific configuration options are configured in the [Service], [Socket], [Mount], or [Swap] sections in the unit files, depending on the unit type.

Unit file syntax


Well, a very comprehensive explanation exist in man page (man systemd.unit) for your reference. Here is a short, still very useful, explanation of [Unit] section in each unit files. Remember this part is common to all of them. Some common options under [Unit] section are:

[Unit]
Description= A descriptive information along with the unit name 
Documentation= A list of man pages referencing for this unit or its configuration 
Requires= According to man page, this configures requirement dependencies on other units. If this unit gets activated, the units listed here will be activated as well. If one of the other units gets deactivated or its activation fails, this unit will be deactivated. Note that requirement dependencies do not influence the order in which services are started or stopped. This has to be configured independently with the After= or Before= options. 
Wants= A weaker version of Requires=. A unit listed in this option will be started if the configuring unit is. However, if the listed unit fails to start up or cannot be added to the transaction this has no impact on the validity of the transaction as a whole. 
Conflicts= Configures negative requirement dependencies. If a unit has a Conflicts= setting on another unit, starting the former will stop the latter and vice versa.  
Before= Configures ordering dependencies between units. If a unit foo.service contains a setting “Before=bar.service” and both units are being started, bar.service's start-up is delayed until foo.service is started up.  
After= It is the inverse of “Before=”  
AllowIsolate= If true this unit may be used with the “systemctl isolate” command. Otherwise this will be refused.  
ConditionPathExists= a file existence condition is checked before a unit is started. If the specified absolute path name does not exist the condition will fail  
ConditionPathIsDirectory= is similar to ConditionPathExists= but verifies whether a certain path exists and is a directory

 
Some common options under [Install] section are:

 
[Install]  
Alias=Additional names this unit shall be installed under. The names listed here must have the same suffix (i.e. type) as the unit file name.  
Also= Additional units to install/deinstall when this unit is installed/deinstalled  
WantedBy=, RequiredBy=  This option creates a symbolic link to the unit in a “.wants” subdirectory for the WantedBy unit. For example, assume the you enabled the rsyslog service. “WantedBy=multi-user.target” directive in syslog.service unit file creates a symbolic link in /etc/systemd/system/multi-user.target.wants/rsyslog.service to the actual rsyslog.service. Then, this unit file (rsyslog.service) is wanted/needed by multi-user.target unit file. In other words, all units that multi-user.target wants it would be in multi-user.target.wants directory. As you can see here, all WantsBy symbolic links are setup in the /etc/systemd/system directory. These symbolic links can be changed as you enable/disable a service. if you disable a service, it will remove the link.RequiredBy is a much stronger dependency.

                                                                            Figure 1

Also, as I mentioned above, there are some configuration options shared by these four units as well: services, sockets, mount and swap (man systemd.exec). The execution specific configuration options are configured in the [Service], [Socket], [Mount], or [Swap] sections, depending on the unit type. Let’s take a look:

WorkingDirectory= Takes an absolute directory path. Sets the working directory for executed processes.  
RootDirectory= Takes an absolute directory path. Sets the root directory for executed processes, with the chroot system call.  
User=, Group= Sets the Unix user or group that the processes are executed as, respectively.  
Nice= Sets the default nice level (scheduling priority) for executed processes. CPUSchedulingPriority= Sets the CPU scheduling priority for executed processes.  
UMask= Controls the file mode creation mask. Default is 022.  
Environment= Sets environment variables for executed processes. Takes a space-separated list of variable assignments.  
EnvironmentFile= Similar to Environment= but reads the environment variables from a text file. The text file should contain new-line separated variable assignments. Empty lines and lines starting with ; or # will be ignored, which may be used for commenting. The argument passed should be an absolute file name or wildcard expression, optionally prefixed with "-", which indicates that if the file does not exist it won't be read and no error or warning message is logged.  
StandardOutput= Set output to a log, console, or null.  
SyslogFacility= Sets the syslog facility to use when logging to syslog. One of kern, user, mail, daemon, auth, syslog, lpr, news, uucp, cron, authpriv, ftp, local0, local1, local2, local3, local4, local5, local6 or local7.  
SyslogLevel= Default syslog level to use when logging to syslog or the kernel log buffer. One of emerg, alert, crit, err, warning, notice, info, debug.  
MemoryLimit= Limit the overall memory usage of the executed processes to a certain size. DeviceAllow=, DeviceDeny= Control access to specific device nodes by the executed processes. 

Now, let’s take a look at some examples.

                                                                           Figure 2

Don’t worry about [service] section on this example now. I will explain specific configuration options in the [Service], [Socket], [Mount], and [Swap] sections in part 2.

Another example:

                                                                              Figure 3

and

                                                                             Figure 4

and pretty much that’s it. I will explain the rest options and commands in part 2. Don’t forget to follow it. Hope you enjoyed. 

Khosro Taraghi