view release on metacpan or  search on metacpan

lib/Config/Model/models/Systemd/Section/Unit.pl  view on Meta::CPAN

        'value_type' => 'uniline',
        'warn' => 'Unexpected systemd parameter. Please contact cme author to update systemd model.'
      }
    ],
    'class_description' => "A unit file is a plain text ini-style file that encodes information about a service, a
socket, a device, a mount point, an automount point, a swap file or partition, a start-up
target, a watched file system path, a timer controlled and supervised by
L<systemd(1)>, a
resource management slice or a group of externally created processes. See
L<systemd.syntax(7)>
for a general description of the syntax.

This man page 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 to the generic [Unit] and [Install] sections
described here, each unit may have a type-specific section, e.g.
[Service] for a service unit. See the respective man pages for
more information:
L<systemd.service(5)>,
L<systemd.socket(5)>,
L<systemd.device(5)>,
L<systemd.mount(5)>,
L<systemd.automount(5)>,
L<systemd.swap(5)>,
L<systemd.target(5)>,
L<systemd.path(5)>,
L<systemd.timer(5)>,
L<systemd.slice(5)>,
L<systemd.scope(5)>.


Unit files are loaded from a set of paths determined during compilation, described in the next
section.

Valid unit names consist of a \"unit name prefix\", and a suffix specifying the unit type which
begins with a dot. The \"unit name prefix\" must consist of one or more valid characters (ASCII letters,
digits, C<:>, C<->, C<_>, C<.>, and
C<\\>). The total length of the unit name including the suffix must not exceed 255
characters. The unit type suffix must be one of C<.service>, C<.socket>,
C<.device>, C<.mount>, C<.automount>,
C<.swap>, C<.target>, C<.path>,
C<.timer>, C<.slice>, or C<.scope>.

Unit names can be parameterized by a single argument called the \"instance name\". The unit is then
constructed based on a \"template file\" which serves as the definition of multiple services or other
units. A template unit must have a single C<\@> at the end of the unit name prefix (right
before the type suffix). The name of the full unit is formed by inserting the instance name between
C<\@> and the unit type suffix. In the unit file itself, the instance parameter may be
referred to using C<%i> and other specifiers, see below.

Unit files may contain additional options on top of those listed here. If systemd encounters an
unknown option, it will write a warning log message but continue loading the unit. If an option or
section name is prefixed with C<X->, it is ignored completely by systemd. Options within an
ignored section do not need the prefix. Applications may use this to include additional information in
the unit files. To access those options, applications need to parse the unit files on their own.

Units can be aliased (have an alternative name), by creating a symlink from the new name to the
existing name in one of the unit search paths. For example, C<systemd-networkd.service>
has the alias C<dbus-org.freedesktop.network1.service>, created during installation as
a symlink, so when systemd is asked through D-Bus to load
C<dbus-org.freedesktop.network1.service>, it'll load
C<systemd-networkd.service>. As another example, C<default.target> \x{2014}
the default system target started at boot \x{2014} is commonly aliased to either
C<multi-user.target> or C<graphical.target> to select what is started
by default. Alias names may be used in commands like disable,
start, stop, status, and similar, and in all
unit dependency directives, including C<Wants>, C<Requires>,
C<Before>, C<After>. Aliases cannot be used with the
preset command.

Aliases obey the following restrictions: a unit of a certain type (C<.service>,
C<.socket>, \x{2026}) can only be aliased by a name with the same type suffix. A plain unit (not
a template or an instance), may only be aliased by a plain name. A template instance may only be aliased
by another template instance, and the instance part must be identical. A template may be aliased by
another template (in which case the alias applies to all instances of the template). As a special case, a
template instance (e.g. C<alias\@inst.service>) may be a symlink to different template
(e.g. C<template\@inst.service>). In that case, just this specific instance is aliased,
while other instances of the template (e.g. C<alias\@foo.service>,
C<alias\@bar.service>) are not aliased. Those rules preserve the requirement that the
instance (if any) is always uniquely defined for a given unit and all its aliases. The target of alias
symlink must point to a valid unit file location, i.e. the symlink target name must match the symlink
source name as described, and the destination path must be in one of the unit search paths, see UNIT FILE
LOAD PATH section below for more details. Note that the target file might not exist, i.e. the symlink may
be dangling.

Unit files may specify aliases through the C<Alias> directive in the [Install]
section. When the unit is enabled, symlinks will be created for those names, and removed when the unit is
disabled. For example, C<reboot.target> specifies
C<Alias=ctrl-alt-del.target>, so when enabled, the symlink
C</etc/systemd/system/ctrl-alt-del.target> pointing to the
C<reboot.target> file will be created, and when
CtrlAltDel is invoked,
systemd will look for C<ctrl-alt-del.target>, follow the symlink to
C<reboot.target>, and execute C<reboot.service> as part of that target.
systemd does not look at the [Install] section at all during normal operation, so any
directives in that section only have an effect through the symlinks created during enablement.

Along with a unit file C<foo.service>, the directory
C<foo.service.wants/> may exist. All unit files symlinked from such a directory are
implicitly added as dependencies of type C<Wants> to the unit. Similar functionality
exists for C<Requires> type dependencies as well, the directory suffix is
C<.requires/> in this case. This functionality is useful to hook units into the
start-up of other units, without having to modify their unit files. For details about the semantics of
C<Wants> and C<Requires>, see below. The preferred way to create
symlinks in the C<.wants/> or C<.requires/> directories is by
specifying the dependency in [Install] section of the target unit, and creating the symlink in the file
system with the enable or preset commands of
L<systemctl(1)>.  The
target can be a normal unit (either plain or a specific instance of a template unit). In case when the
source unit is a template, the target can also be a template, in which case the instance will be
\"propagated\" to the target unit to form a valid unit instance. The target of symlinks in
C<.wants/> or C<.requires/> must thus point to a valid unit file
location, i.e. the symlink target name must satisfy the described requirements, and the destination path
must be in one of the unit search paths, see UNIT FILE LOAD PATH section below for more details. Note
that the target file might not exist, i.e. the symlink may be dangling.

Along with a unit file C<foo.service>, a \"drop-in\" directory
C<foo.service.d/> may exist. All files with the suffix
C<.conf> from this directory will be merged in the alphanumeric order and parsed
after the main unit file itself has been parsed. This is useful to alter or add configuration
settings for a unit, without having to modify unit files. Each drop-in file must contain appropriate