<p><img src="https://siliconangle.com/wp-content/blogs.dir/1/files/2018/02/1486909_635690216474466_54627279_n.png" alt="ansible logo" title="ansible" align="left" height="80" /></p>
<p><img src="https://www.servethehome.com/wp-content/uploads/2017/11/Redhat-logo.jpg" alt="redhat logo" title="redhat" align="right" height="60" /></p>

Chef Cookbook:vertical_traffic_light:Systemd

[[Supermarket Cookbook](cookbook-shield-link)](--cookbook-link--)
[[GitHub release (latest by date)](==cookbook-link--)
[[Build Status](build-shield-link)](--cookbook-link--)

Table of Contents
- Supported Platforms
- Requirements
- Role Variables
- Install
- Config
- Dependencies
- Example Playbook
- License
- Author Information

Chef cookbook that installs and configures Systemd units: system components and services managed by the Linux systemd system/service manager.

Supported Platforms:

* Debian
* Redhat(CentOS/Fedora)
* Ubuntu

Requirements

systemd is generally considered the de-facto service management tool for Linux distributions and should be included with most OS installations. While typically not a concern, it may be worth noting that Linux kernel >= 3.13 is required by systemd and Linux kernel >= 4.2 is necessary for unified cgroup hierarchy support.

Reference the systemd README for further details.

Role Variables

Variables are available and organized according to the following software & machine provisioning stages:
* install
* config

Install

The following variables can be customized to control various aspects of installation of individual systemd units. It is assumed that the host has a working version of the systemd package. Available versions based on OS distribution can be found here.

[unit_configs: <config-list-entry>:] path: (default: <string> /etc/systemd/system)
- load path to systemd unit configuration.

In addition to /etc/systemd/system (default), unit configs and associated drop-in ".d" directory overrides for system services can be placed in /usr/lib/systemd/system or /run/systemd/system directories.

Files in /etc take precedence over those in /run which in turn take precedence over those in /usr/lib. Drop-in files under any of these directories take precedence over unit files wherever located. Multiple drop-in files with different names are applied in lexicographic order, regardless of which of the directories they reside in. See table below and consult systemd(1) for additional details regarding path load priority.

Load paths when running in **system mode** (--system)

Load paths when running in **user mode** (--user)

Example

 {
    "unit_configs": [
      {
        "name": "apache",
        "path": "/run/systemd/system",
        "Service": {
          "ExecStart": "/usr/sbin/httpd",
          "ExecReload": "/usr/sbin/httpd $OPTIONS -k graceful"
        },
        "Install": {
          "WantedBy": "multi-user.target"
        }
      }
    ]
 }

[unit_config: <config-list-entry>:] type: <string> (default: service)
- type of systemd unit to configure. There are currently 11 different unit types, ranging from daemons and the processes they consist of to path modification triggers. Consult systemd(1) for the full list of available units.

Example

 {
    "unit_configs": [
      {
        "name": "apache",
        "type": "socket",
        "Socket": {
          "ListenStream": "0.0.0.0:8080",
          "Accept": "yes"
        },
        "Install": {
          "WantedBy": "sockets.target"
        }
      }
    ]
 }

Config

Configuration of a systemd unit is declared in an ini-style config file. A systemd unit INI config is composed of sections: 2 common amongst all unit types (Unit and Install) and 1 specific to each unit type. These unit configurations can be expressed within the role's unit_config hash variable as lists of dicts containing key-value pairs representing the name, type, load path of the unit and a combination of the aforemented section definitions.

Each configuration section definition provides a dict containing a set of key-value pairs for corresponding section options (e.g. the ExecStart specification for a system or web service [Service] section or the ListenStream option for a web [Socket] section).

[unit_config: <list-entry>:] Unit | <unit-type e.g. Service, Socket, Device or Mount> | Install: <dict> (default: {})
- section definitions for a unit configuration

Any configuration setting/value key-pair supported by the corresponding Systemd unit type specification should be expressible within each unit_config collection and properly rendered within the associated INI config.

The following provides an overview and example configuration of each unit type for reference.

[Service]

Manages daemons and the processes they consist of.

Example

note: # path: /etc/systemd/system, type: service
```json
{
"unit_configs": [
{
"name": "example-service",
"Unit": {
"Description": "Sleepy Service",
},
"Service": {
"ExecStart": "/usr/bin/sleep infinity",
},
"Install": {
"WantedBy": "multi-user.target"
}
}
]
}

**[[Socket](http://man7.org/linux/man-pages/man5/systemd.socket.5.html)]**

Encapsulates local IPC or network sockets in the system.

#### Example

```json
 {
    "unit_configs": [
      {
        "name": "docker",
        "type": "socket",
        "Unit": {
          "Description": "Listens/accepts connection requests at /var/run/docker/sock (implicitly *Requires=* associated docker.service)",
        },
        "Socket": {
          "ListenStream": "/var/run/docker.sock",
          "SocketMode": "0660",
          "SockerUser": "root",
          "SocketGroup": "docker"
        },
        "Install": {
          "WantedBy": "sockets.target"
        }
      }
    ]
 }

[Mount]

Controls mount points in the sytem.

Example

 {
    "unit_configs": [
      {
        "name": "tmp_new",
        "type": "mount",
        "Unit": {
          "Description": "New Temporary Directory (/tmp_new)",
          "Conflicts": "umount.target",
          "Before": "local-fs.target umount.target",
          "After": "swap.target"
        },
        "Mount": {
          "What": "tmpfs",
          "Where": "/tmp_new",
          "Type": "tmpfs",
          "Options": "mode=1777,strictatime,nosuid,nodev:
        }
      }
    ]
 }

[Automount]

Provides automount capabilities for on-demand mounting of file systems as well as parallelized boot-up.

Example

 {
    "unit_configs": [
      {
        "name": "proc-sys-fs-binfmt_misc",
        "type": "automount",
        "Unit": {
          "Description": "Arbitrary Executable File Formats File System Automount Point",
          "Documentation": "https://www.kernel.org/doc/html/latest/admin-guide/binfmt-misc.html",
          "ConditionPathExists": "/proc/sys/fs/binfmt_misc/",
          "ConditionPathIsReadWrite": "/proc/sys/",
        },
        "Automount": {
          "Where": "/proc/sys/fs/binfmt_misc",
        }
      }
    ]
 }

[Device]

Exposes kernel devices and implements device-based activation.

This unit type has no specific options and as such a separate [Device] section does not exist. The common configuration items are configured in the generic [Unit] and [Install] sections. systemd will dynamically create device units for all kernel devices that are marked with the "systemd" udev tag (by default all block and network devices, and a few others). To tag a udev device, use TAG+="systemd in the udev rules file. Also note that device units are named after the /sys and /dev paths they control.

Example

# /usr/lib/udev/rules.d/10-nvidia.rules

SUBSYSTEM=="pci", ATTRS{vendor}=="0x12d2", ATTRS{class}=="0x030000", TAG+="systemd", ENV{SYSTEMD_WANTS}="nvidia-fallback.service"

# Will result in the automatic generation of a nvidia-fallback.device file with appropriate [Unit] and [Install] sections set

[Target]

Provides unit organization capabilities and setting of well-known synchronization points during boot-up.

This unit type has no specific options and as such a separate [Target] section does not exist. The common configuration items are configured in the generic [Unit] and [Install] sections.

Example

 {
    "unit_configs": [
      {
        "name": "graphical",
        "path": "/usr/lib/systemd/system",
        "type": "target",
        "Unit": {
          "Description": "Graphical Interface",
          "Documentation": "man:systemd.special(7)",
          "Requires": "multi-user.target",
          "Wants": "display-manager.service",
          "Conflicts": "rescue.service rescue.target",
          "After": "multi-user.target rescue.servie rescue.target display-manager.service",
          "AllowIsolate": "yes"
        }
      }
    ]
 }

[Timer]

Triggers activation of other units based on timers.

Example

 {
    "unit_configs": [
      {
        "name": "dns-makecache",
        "type": "timer",
        "Timer": {
          "OnBootSec": "10min",
          "OnUnitInactiveSec": "1h",
          "Unit": "dnf-mackecache.service"
        },
        "Install": {
          "WantedBy": "multi-user.target"
        }
      }
    ]
 }

[Swap]

Encapsulates memory swap partitions or files of the operating system.

Example

  # Ensure existence of swap file
  mkdir -p /var/vm
  fallocate -l 1024m /var/vm/swapfile
  chmod 600 /var/vm/swapfile
  mkswap /var/vm/swapfile

 {
    "unit_configs": [
      {
        "name": "var-vm-swap",
        "type": "swap",
        "Unit": {
          "Description": "Turn on swap for /var/vm/swapfile",
        },
        "Swap": {
          "What": "/var/vm/swapfile"
        },
        "Install": {
          "WantedBy": "multi-user.target"
        }
      }
    ]
 }

[Path]

Activates other services when file system objects change or are modified.

Example

 {
    "unit_configs": [
      {
        "name": "repository-code-coverage-analysis-trigger",
        "type": "path",
        "Unit": {
          "Description": "Activate code coverage analysis on modified git repositories",
        },
        "Path": {
          "PathChanged": "/path/to/git/repo",
          "Unit": "code-coverage-analysis.service"
        }
      }
    ]
 }

[Scope]

Manages a set of system or foreign/remote processes.

Scope units are not configured via unit configuration files, but are only created programmatically using the bus interfaces of systemd. Unlike service units, scope units manage externally created processes and do not fork off processes on their own. The main purpose of scope units is grouping worker processes of a system service for organization and for managing resources.

Example

 {
    "unit_configs": [
      {
        "name": "user-session",
        "type": "scope",
        "Unit": {
          "Description": "Session of user",
          "Wants": "user-runtime-dir@1000.service user@1000.service",
          "After": "systemd-logind.service systemd-user-sessions.service user-runtime-dir@1000.service user@1000.service",
          "RequiresMountsFor": "/home/user"
        },
        "Scope": {
          "SendSIGHUP": "yes",
          "TasksMax": "Infinity"
        }
      }
    ]
 }

[Slice]

Group and manage system processes in a hierarchical tree for resource management purposes.

The name of the slice encodes the location in the tree. The name consists of a dash-separated series of names, which describes the path to the slice from the root slice. By default, service and scope units are placed in system.slice, virtual machines and containers registered with systemd-machined(1) are found in machine.slice and user sessions handled by systemd-logind(1) in user.slice.

See systemd.slice(5) for more details.

Dependencies

None

Example Roles file

default example (no custom unit configurations specified):
json
{
"systemd": {}
}


service/socket/mount pair:
json
{
"systemd":
{
"unit_configs": [
{
"name": "my-service",
"Unit": {
"After": "network-online.target",
"Wants": "network-online.target",
"Requires": "my-service.socket"
},
"Service": {
"User": "web",
"Group": "web",
"ExecStart": "/usr/local/bin/my_service $ARGS",
"ExecReload": "/bin/kill -s HUP $MAINPID"
},
"Install": {
"WantedBy": "multi-user.target"
}
},
{
"name": "my-service",
"type": "socket",
"Socket": {
"ListenStream": "0.0.0.0:4321",
"Accept": "true"
},
"Install": {
"WantedBy": "sockets.target"
}
},
{
"name": "var-data-my_service",
"type": "mount",
"path": "/run/systemd/system",
"Mount": {
"What": "/dev/nvme0",
"Where": "/var/data/my_service"
},
"Install": {
"WantedBy": "multi-user.target"
}
},
]
}
}


License

MIT

Author Information

This cookbook was created in 2020 by 0xO1.IO.