X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd.special.xml;h=863a029fe3bd74213de0eec931353e2164360092;hp=3f9286d4b4e4a13434007ec7d0af0b889959e873;hb=86198b2788e56fd05959c2dce670d1646bf99bcd;hpb=9f23530860942a8f94b7c535ead80c38f02424b1 diff --git a/man/systemd.special.xml b/man/systemd.special.xml index 3f9286d4b..863a029fe 100644 --- a/man/systemd.special.xml +++ b/man/systemd.special.xml @@ -8,16 +8,16 @@ Copyright 2010 Lennart Poettering systemd is free software; you can redistribute it and/or modify it - under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. systemd is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - General Public License for more details. + Lesser General Public License for more details. - You should have received a copy of the GNU General Public License + You should have received a copy of the GNU Lesser General Public License along with systemd; If not, see . --> @@ -44,26 +44,67 @@ systemd.special - special systemd units + Special systemd units - emergency.service - local-fs.target - network.target - nss-lookup.target - remote-fs.target - rpcbind.target - rtc-set.target - shutdown.target - sigpwr.target - sockets.target - swap.target - syslog.target - systemd-initctl.service - systemd-initctl.socket - systemd-logger.service - systemd-logger.socket + basic.target, + bluetooth.target, + ctrl-alt-del.target, + cryptsetup.target, + dbus.service, + dbus.socket, + default.target, + display-manager.service, + emergency.target, + exit.target, + final.target, + getty.target, + graphical.target, + halt.target, + hibernate.target, + hybrid-sleep.target, + initrd-fs.target, + kbrequest.target, + kexec.target, + local-fs.target, + local-fs-pre.target, + multi-user.target, + network.target, + network-online.target, + nss-lookup.target, + nss-user-lookup.target, + paths.target, + poweroff.target, + printer.target, + reboot.target, + remote-fs.target, + remote-fs-pre.target, + rescue.target, + initrd-root-fs.target, + rpcbind.target, + runlevel2.target, + runlevel3.target, + runlevel4.target, + runlevel5.target, + shutdown.target, + sigpwr.target, + sleep.target, + smartcard.target, + sockets.target, + sound.target, + suspend.target, + swap.target, + sysinit.target, + syslog.socket, + system-update.target, + time-sync.target, + timers.target, + umount.target, + -.slice, + system.slice, + user.slice, + machine.slice @@ -79,104 +120,452 @@ - emergency.service + basic.target - A special service unit + A special target unit + covering basic boot-up. + systemd automatically + adds dependencies of the types + Requires= + and After= + for this target unit to all + services (except for those + with + DefaultDependencies=no). + + Usually this should + pull-in all mount points, swap + devices, sockets, timers, and + path units and other basic + initialization necessary for + general purpose + daemons. + + + + ctrl-alt-del.target + + systemd starts this + target whenever + Control+Alt+Del is pressed on + the console. Usually this + should be aliased (symlinked) + to + reboot.target. + + + + cryptsetup.target + + A target that pulls in + setup services for all + encrypted block + devices. + + + + dbus.service + + A special unit for the + D-Bus bus daemon. As soon as + this service is fully started + up systemd will connect to it + and register its + service. + + + + dbus.socket + + A special unit for the + D-Bus system bus socket. All + units with + Type=dbus + automatically gain a + dependency on this + unit. + + + + default.target + + The default unit systemd + starts at bootup. Usually this + should be aliased (symlinked) + to + multi-user.target + or + graphical.target. + + The default unit systemd + starts at bootup can be + overridden with the + systemd.unit= + kernel command line option. + + + + display-manager.service + + The display manager + service. Usually this should + be aliased (symlinked) to + gdm.service + or a similar display manager + service. + + + + emergency.target + + A special target unit that starts an emergency shell on the main console. This unit is supposed to be used with the kernel command line option - systemd.default= + systemd.unit= and has otherwise little use. + + final.target + + A special target unit + that is used during the + shutdown logic and may be used + to pull in late services after + all normal services are + already terminated and all + mounts unmounted. + + + + + getty.target + + A special target unit + that pulls in statically + configured local TTY + getty + instances. + + + + + graphical.target + + A special target unit + for setting up a graphical + login screen. This pulls in + multi-user.target. + + Units that are needed + for graphical logins shall add + Wants= + dependencies for their unit to + this unit (or + multi-user.target) + during installation. This is + best configured via + WantedBy=graphical.target + in the unit's + [Install] + section. + + + + hibernate.target + + A special target unit + for hibernating the + system. This pulls in + sleep.target. + + + + hybrid-sleep.target + + A special target unit + for hibernating and suspending the + system at the same time. This pulls in + sleep.target. + + + + halt.target + + A special target unit + for shutting down and halting + the system. Note that this + target is distinct from + poweroff.target + in that it generally really + just halts the system rather + than powering it down. + + Applications wanting to + halt the system should start + this unit. + + + + initrd-fs.target + + systemd-fstab-generator3 + automatically adds + dependencies of type + Before= to + sysroot-usr.mount + and all mount points found in + /etc/fstab + that have the + and + + mount options set. + + + + + kbrequest.target + + systemd starts this + target whenever Alt+ArrowUp is + pressed on the console. This + is a good candidate to be + aliased (symlinked) to + rescue.target. + + + + kexec.target + + A special target unit + for shutting down and rebooting the system via kexec. + + Applications wanting to + reboot the system with kexec should start + this unit. + + local-fs.target - systemd automatically - adds dependencies of type - After to all mount units that - refer to local mount - points. In addition, systemd + systemd-fstab-generator3 + automatically adds + dependencies of type + Before= to + all mount units that refer to + local mount points for this + target unit. In addition, it adds dependencies of type - Wants to those mounts listed - in + Wants= to + this target unit for those + mounts listed in /etc/fstab that have the - auto and - comment=systemd.mount - mount options set. + mount + option set. + + + + multi-user.target + + A special target unit + for setting up a multi-user + system (non-graphical). This + is pulled in by + graphical.target. - systemd automatically - adds dependencies of type - After to this target unit for - all SysV init scripts with an - LSB header referring to the - $local_fs - facility. + Units that are needed + for a multi-user system shall + add Wants= + dependencies for their unit to + this unit during + installation. This is best + configured via + WantedBy=multi-user.target + in the unit's + [Install] + section. - network.target + network-online.target - systemd automatically - adds dependencies of type - After to this target unit for - all SysV init scripts with an - LSB header referring to the - $network - facility. + Units that strictly + require a configured network + connection should pull in + network-online.target + (via a + Wants= type + dependency) and order + themselves after it. This + target unit is intended to + pull in a service that delays + further execution until the + network is sufficiently set + up. What precisely this + requires is left to the + implementation of the network + managing service. + + Note the distinction + between this unit and + network.target. This + unit is an active unit + (i.e. pulled in by the + consumer rather than the + provider of this + functionality) and pulls in a + service which possibly adds + substantial delays to further + execution. In contrast, + network.target + is a passive unit (i.e. pulled + in by the provider of the + functionality, rather than the + consumer) that usually does + not delay execution + much. Usually, + network.target + is part of the boot of most + systems, while + network-online.target + is not, except when at least + one unit requires it. Also see + Running + Services After the Network is + up for more + information. + + All mount units for + remote network file systems + automatically pull in this + unit, and order themselves + after it. Note that networking + daemons that simply provide + functionality to other hosts + generally do not need to pull + this in. + + + + paths.target + + A special target unit + that sets up all path units + (see + systemd.path5 + for details) that shall be + active after boot. + + It is recommended that + path units installed by + applications get pulled in via + Wants= + dependencies from this + unit. This is best configured + via a + WantedBy=paths.target + in the path unit's + [Install] + section. - nss-lookup.target + poweroff.target - systemd automatically - adds dependencies of type - After to this target unit for - all SysV init scripts with an - LSB header referring to the - $named - facility. + A special target unit + for shutting down and powering off the system. + + Applications wanting to + power off the system should start + this unit. + + runlevel0.target + is an alias for this target + unit, for compatibility with SysV. + + + + reboot.target + + A special target unit + for shutting down and rebooting the system. + + Applications wanting to + reboot the system should start + this unit. + + runlevel6.target + is an alias for this target + unit, for compatibility with SysV. remote-fs.target - Similar to local-fs.target, but for remote mount points. + Similar to + local-fs.target, + but for remote mount + points. + systemd automatically adds dependencies of type - After to this target unit for - all SysV init scripts with an - LSB header referring to the - $remote-fs + After= for + this target unit to all SysV + init script service units with + an LSB header referring to the + $remote_fs facility. - rpcbind.target + rescue.target - systemd automatically - adds dependencies of type - After to this target unit for - all SysV init scripts with an - LSB header referring to the - $rpcbind - facility. + A special target unit + for setting up the base system + and a rescue shell. + + runlevel1.target + is an alias for this target + unit, for compatibility with SysV. - rtc-set.target + initrd-root-fs.target - systemd automatically - adds dependencies of type - After to this target unit for - all SysV init scripts with an - LSB header referring to the - $time - facility. + systemd-fstab-generator3 + automatically adds + dependencies of type + Before= to + the + sysroot.mount + unit, which is generated from + the kernel command line. + + + + + runlevel2.target + runlevel3.target + runlevel4.target + runlevel5.target + + These are targets that + are called whenever the SysV + compatibility code asks for + runlevel 2, 3, 4, 5, + respectively. It is a good + idea to make this an alias for + (i.e. symlink to) + multi-user.target + (for runlevel 2) or + graphical.target + (the others). @@ -188,17 +577,12 @@ Services that shall be terminated on system shutdown - shall add Wants dependencies - from this unit to their - service unit during - installation. - - systemd automatically - adds dependencies of type - Conflicts to this target unit - for all SysV init scripts that - shall be terminated in SysV - runlevels 0 or 6. + shall add Conflicts= + dependencies to this unit for + their service unit, which is + implicitly done when + DefaultDependencies=yes + is set (the default). @@ -208,22 +592,54 @@ started when systemd receives the SIGPWR process signal, which is normally sent by the - kernel or UPS daemons when the + kernel or UPS daemons when power fails. + + sleep.target + + A special target unit + that is pulled in by + suspend.target, + hibernate.target + and + hybrid-sleep.target + and may be used to hook units + into the sleep state + logic. + + sockets.target A special target unit - that sets up all service - sockets. + that sets up all socket + units.(see + systemd.socket5 + for details) that shall be + active after boot. Services that can be socket-activated shall add - Wants dependencies from this - unit to their socket unit - during installation. + Wants= + dependencies to this unit for + their socket unit during + installation. This is best + configured via a + WantedBy=sockets.target + in the socket unit's + [Install] + section. + + + + suspend.target + + A special target unit + for suspending the + system. This pulls in + sleep.target. @@ -236,89 +652,448 @@ - syslog.target + sysinit.target + + A special target unit + covering early boot-up scripts. + + + + syslog.socket + + The socket unit + syslog implementations should + listen on. All userspace log + messages will be made + available on this socket. For + more information about syslog + integration, please consult + the Syslog + Interface + document. + + + + system-update.target + + A special target unit + that is used for off-line + system updates. + systemd-system-update-generator8 + will redirect the boot process + to this target if + /system-update + exists. For more information + see the System + Updates + Specification. + + + + timers.target + + A special target unit + that sets up all timer + units (see + systemd.timer5 + for details) that shall be + active after boot. + + It is recommended that + timer units installed by + applications get pulled in via + Wants= + dependencies from this + unit. This is best configured + via + WantedBy=timers.target + in the timer unit's + [Install] + section. + + + + umount.target + + A special target unit + that umounts all mount and + automount points on system + shutdown. + + Mounts that shall be + unmounted on system shutdown + shall add Conflicts + dependencies to this unit for + their mount unit, which is + implicitly done when + DefaultDependencies=yes + is set (the default). + + + + + + + + Special System Units for Devices + + Some target units are automatically pulled in as + devices of certain kinds show up in the system. These + may be used to automatically activate various services + based on the specific type of the available + hardware. + + + + bluetooth.target + + This target is started + automatically as soon as a + Bluetooth controller is + plugged in or becomes + available at boot. + + This may be used to pull + in Bluetooth management + daemons dynamically when + Bluetooth hardware is + found. + + + + printer.target + + This target is started + automatically as soon as a + printer is plugged in or + becomes available at + boot. + + This may be used to pull + in printer management + daemons dynamically when + printer hardware is + found. + + + + smartcard.target + + This target is started + automatically as soon as a + smartcard controller is + plugged in or becomes + available at boot. + + This may be used to pull + in smartcard management + daemons dynamically when + smartcard hardware is + found. + + + + sound.target + + This target is started + automatically as soon as a + sound card is plugged in or + becomes available at + boot. + + This may be used to pull + in audio management daemons + dynamically when audio + hardware is found. + + + + + + + Special Passive System Units + + A number of special system targets are defined + that can be used to properly order boot-up of optional + services. These targets are generally not part of the + initial boot transaction, unless they are explicitly + pulled in by one of the implementing services. Note + specifically, that these passive + target units are generally not pulled in by the + consumer of a service, but by the provider of the + service. This means: a consuming service should order + itself after these targets (as appropriate), but not + pull it in. A providing service should order itself + before these targets (as appropriate) and pull it in + (via a Wants= type + dependency). + + Note that these passive units cannot be started + manually, i.e. systemctl start + time-sync.target will fail with an + error. They can only be pulled in by dependency. This + is enforced since they exist for ordering purposes + only and thus are not useful as only unit within a + transaction. + + + + local-fs-pre.target + + This target unit is + automatically ordered before + all local mount points marked + with + (see above). It can be used to + execute certain units before + all local mounts. + + + + network.target + This unit is supposed to + indicate when network + functionality is available, + but it is only very weakly + defined what that is supposed + to mean, with one exception: + at shutdown, a unit that is + ordered after + network.target + will be stopped before the + network -- to whatever level + it might be set up then -- is + shut down. Also see Running + Services After the Network is + up for more + information. Also see + network-online.target + described above. + systemd automatically adds dependencies of type - After to this target unit for - all SysV init scripts with an - LSB header referring to the - $syslog + After= for + this target unit to all SysV + init script service units with + an LSB header referring to the + $network facility. - Administrators should - ensure that this target pulls - in a service unit with the - name or alias of - @SPECIAL_SYSLOG_NAME@ (or a - socket unit that activates - this service). - systemd-initctl.service + nss-lookup.target - This provides - compatibility with the SysV - /dev/initctl file system FIFO - for communication with the - init system. - This is a - socket-activated service, see - system-initctl.socket. + A target that should be + used as synchronization point + for all host/network name + service lookups. Note that + this is independent of + user/group name lookups for + which + nss-user-lookup.target + should be used. systemd + automatically adds + dependencies of type + After= for + this target unit to all SysV + init script service units with + an LSB header referring to the + $named + facility. - systemd-initctl.socket + nss-user-lookup.target - Socket activation unit - for - system-initctl.service. + A target that should be + used as synchronization point + for all user/group name + service lookups. Note that + this is independent of + host/network name lookups for + which + nss-lookup.target + should be used. - systemd-logger.service + remote-fs-pre.target - This is used internally - by systemd to provide syslog - logging to started - processes. - This is a - socket-activated service, see - system-logger.socket. + This target unit is + automatically ordered before + all remote mount point units + (see above). It can be used to + run certain units before the + remote mounts are + established. Note that this + unit is generally not part of + the initial transaction, + unless the unit that wants to + be ordered before all remote + mounts pulls it in via a + Wants= type + dependency. If the unit wants + to be pulled in by the first + remote mount showing up, it + should use + network-online.target + (see above). + + Again, this target unit + is not + suitable for pulling in other + units, it is only useful for + ordering. - systemd-logger.socket + rpcbind.target - Socket activation unit - for - system-logger.service. + systemd automatically + adds dependencies of type + After= for + this target unit to all SysV + init script service units with + an LSB header referring to the + $portmap + facility. + + + + time-sync.target + + systemd automatically + adds dependencies of type + After= for + this target unit to all SysV + init script service units with + an LSB header referring to the + $time + facility. - Special Session Units + Special User Units - When systemd runs as a service instance, the + When systemd runs as a user instance, the following special units are available, which have similar definitions as their system counterparts: - local-fs.target, - remote-fs.target, + default.target, shutdown.target, sockets.target, - swap.target. + timers.target, + paths.target, + bluetooth.target, + printer.target, + smartcard.target, + sound.target. + + In addition the following special unit is + understood only when systemd runs as service instance: + + + + exit.target + + A special service unit + for shutting down the + user service manager. + + Applications wanting to + terminate the user service + manager should start this + unit. If systemd receives + SIGTERM or SIGINT when running + as user service daemon, it will + start this unit. + + Normally, this pulls in + shutdown.target + which in turn should be + conflicted by all units that + want to be shut down on + user service manager exit. + + + + + + + Special Slice Units + + There are four .slice units + which form the basis of the hierarchy for assignment + of resources for services, users, and virtual machines + or containers. + + + + -.slice + + The root slice is the + root of the hierarchy. It + usually does not contain units + directly, but may be used to + set defaults for the whole + tree. + + + + + system.slice + + By default, all services + services started by + systemd are + found in this slice. + + + + + user.slice + + By default, all user + processes and services started + on behalf of the user, + including the per-user systemd + instance are found in this + slice. + + + + + machine.slice + + By defalt, all virtual + machines and containers + registered with + systemd-machined + are found in this slice. + + + + See Also - systemd.unit5 - systemd.service5 - systemd.socket5 - systemd.target5 + systemd1, + systemd.unit5, + systemd.service5, + systemd.socket5, + systemd.target5, + systemd.slice5, + bootup7, + systemd-fstab-generator8