diff options
Diffstat (limited to 'man')
61 files changed, 17129 insertions, 0 deletions
diff --git a/man/Makefile b/man/Makefile new file mode 120000 index 000000000..bd1047548 --- /dev/null +++ b/man/Makefile @@ -0,0 +1 @@ +../src/Makefile
\ No newline at end of file diff --git a/man/binfmt.d.xml b/man/binfmt.d.xml new file mode 100644 index 000000000..f5ec805e2 --- /dev/null +++ b/man/binfmt.d.xml @@ -0,0 +1,111 @@ +<?xml version="1.0"?> +<!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- + This file is part of systemd. + + Copyright 2011 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> +<refentry id="binfmt.d"> + + <refentryinfo> + <title>binfmt.d</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>binfmt.d</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>binfmt.d</refname> + <refpurpose>Configure additional binary formats at boot</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/binfmt.d/*.conf</filename></para> + <para><filename>/run/binfmt.d/*.conf</filename></para> + <para><filename>/usr/lib/binfmt.d/*.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd</command> uses + files from the above directories to configure + additional binary formats to register during boot in + the kernel.</para> + </refsect1> + + <refsect1> + <title>Configuration Format</title> + + <para>Each file contains a list of binfmt_misc kernel + binary format rules. Consult <ulink + url="http://www.kernel.org/doc/Documentation/binfmt_misc.txt">binfmt_misc.txt</ulink> + for more information on registration of additional + binary formats and how to write rules.</para> + + <para>Empty lines and lines beginning with ; and # are + ignored. Note that this means you may not use ; and # + as delimiter in binary format rules.</para> + + <para>Each configuration file is named in the style of + <filename><program>.conf</filename>. + Files in <filename>/etc/</filename> overwrite + files with the same name in <filename>/usr/lib/</filename>. + Files in <filename>/run</filename> overwrite files with + the same name in <filename>/etc/</filename> and + <filename>/usr/lib/</filename>. Packages should install their + configuration files in <filename>/usr/lib/</filename>, files + in <filename>/etc/</filename> are reserved for the local + administration, which possibly decides to overwrite the + configurations installed from packages. All files are sorted + by filename in alphabetical order, regardless in which of the + directories they reside, to ensure that a specific + configuration file takes precedence over another file with + an alphabetically later name.</para> + </refsect1> + + <refsect1> + <title>Example</title> + <example> + <title>/etc/binfmt.d/wine.conf example:</title> + + <programlisting># Start WINE on Windows executables +:DOSWin:M::MZ::/usr/bin/wine:</programlisting> + </example> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>wine</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/custom-html.xsl b/man/custom-html.xsl new file mode 100644 index 000000000..2d2f45879 --- /dev/null +++ b/man/custom-html.xsl @@ -0,0 +1,29 @@ +<?xml version='1.0'?> <!--*-nxml-*--> + +<!-- + This file is part of systemd. + + Copyright 2011 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> + +<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl"/> + +<!-- Switch things to UTF-8, ISO-8859-1 is soo yesteryear --> +<xsl:output method="html" encoding="UTF-8" indent="no"/> + +</xsl:stylesheet> diff --git a/man/daemon.xml b/man/daemon.xml new file mode 100644 index 000000000..997ee5b25 --- /dev/null +++ b/man/daemon.xml @@ -0,0 +1,948 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="daemon"> + + <refentryinfo> + <title>daemon</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>daemon</refentrytitle> + <manvolnum>7</manvolnum> + </refmeta> + + <refnamediv> + <refname>daemon</refname> + <refpurpose>Writing and Packaging System Daemons</refpurpose> + </refnamediv> + + <refsect1> + <title>Description</title> + + <para>A daemon is a service process that runs in the + background and supervises the system or provides + functionality to other processes. Traditionally, + daemons are implemented following a scheme originating + in SysV Unix. Modern daemons should follow a simpler + yet more powerful scheme (here called "new-style" + daemons), as implemented by + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>. This + manual page covers both schemes, and in + particular includes recommendations for daemons that + shall be included in the systemd init system.</para> + + <refsect2> + <title>SysV Daemons</title> + + <para>When a traditional SysV daemon + starts, it should execute the following steps + as part of the initialization. Note that these + steps are unnecessary for new-style daemons (see below), + and should only be implemented if compatibility + with SysV is essential.</para> + + <orderedlist> + <listitem><para>Close all open file + descriptors except STDIN, STDOUT, + STDERR (i.e. the first three file + descriptors 0, 1, 2). This ensures + that no accidentally passed file + descriptor stays around in the daemon + process. On Linux this is best + implemented by iterating through + <filename>/proc/self/fd</filename>, + with a fallback of iterating from file + descriptor 3 to the value returned by + <function>getrlimit()</function> for + RLIMIT_NOFILE.</para></listitem> + + <listitem><para>Reset all signal + handlers to their default. This is + best done by iterating through the + available signals up to the limit of + _NSIG and resetting them to + SIG_DFL.</para></listitem> + + <listitem><para>Reset the signal mask + using + <function>sigprocmask()</function>.</para></listitem> + + <listitem><para>Sanitize the + environment block, removing or + resetting environment variables that + might negatively impact daemon + runtime.</para></listitem> + + <listitem><para>Call <function>fork()</function>, + to create a background + process.</para></listitem> + + <listitem><para>In the child, call + <function>setsid()</function> to + detach from any terminal and create an + independent session.</para></listitem> + + <listitem><para>In the child, call + <function>fork()</function> again, to + ensure the daemon can never re-acquire + a terminal again.</para></listitem> + + <listitem><para>Call <function>exit()</function> in the + first child, so that only the second + child (the actual daemon process) + stays around. This ensures that the + daemon process is reparented to + init/PID 1, as all daemons should + be.</para></listitem> + + <listitem><para>In the daemon process, + connect <filename>/dev/null</filename> + to STDIN, STDOUT, + STDERR.</para></listitem> + + <listitem><para>In the daemon process, + reset the umask to 0, so that the file + modes passed to <function>open()</function>, <function>mkdir()</function> and + suchlike directly control the access + mode of the created files and + directories.</para></listitem> + + <listitem><para>In the daemon process, + change the current directory to the + root directory (/), in order to avoid + that the daemon involuntarily + blocks mount points from being + unmounted.</para></listitem> + + <listitem><para>In the daemon process, + write the daemon PID (as returned by + <function>getpid()</function>) to a + PID file, for example + <filename>/var/run/foobar.pid</filename> + (for a hypothetical daemon "foobar"), + to ensure that the daemon cannot be + started more than once. This must be + implemented in race-free fashion so + that the PID file is only updated when + at the same time it is verified that + the PID previously stored in the PID + file no longer exists or belongs to a + foreign process. Commonly some kind of + file locking is employed to implement + this logic.</para></listitem> + + <listitem><para>In the daemon process, + drop privileges, if possible and + applicable.</para></listitem> + + <listitem><para>From the daemon + process notify the original process + started that initialization is + complete. This can be implemented via + an unnamed pipe or similar + communication channel that is created + before the first + <function>fork()</function> and hence + available in both the original and the + daemon process.</para></listitem> + + <listitem><para>Call + <function>exit()</function> in the + original process. The process that + invoked the daemon must be able to + rely that this + <function>exit()</function> happens + after initialization is complete and + all external communication channels + established and + accessible.</para></listitem> + </orderedlist> + + <para>The BSD <function>daemon()</function> function should not be + used, as it implements only a subset of these steps.</para> + + <para>A daemon that needs to provide + compatibility with SysV systems should + implement the scheme pointed out + above. However, it is recommended to make this + behaviour optional and configurable via a + command line argument, to ease debugging as + well as to simplify integration into systems + using systemd.</para> + </refsect2> + + <refsect2> + <title>New-Style Daemons</title> + + <para>Modern services for Linux should be + implemented as new-style daemons. This makes it + easier to supervise and control them at + runtime and simplifies their + implementation.</para> + + <para>For developing a new-style daemon none + of the initialization steps recommended for + SysV daemons need to be implemented. New-style + init systems such as systemd make all of them + redundant. Moreover, since some of these steps + interfere with process monitoring, file + descriptor passing and other functionality of + the init system it is recommended not to + execute them when run as new-style + service.</para> + + <para>Note that new-style init systems + guarantee execution of daemon processes in + clean process contexts: it is guaranteed that + the environment block is sanitized, that the + signal handlers and mask is reset and that no + left-over file descriptors are passed. Daemons + will be executed in their own session, and + STDIN/STDOUT/STDERR connected to + <filename>/dev/null</filename> unless + otherwise configured. The umask is reset.</para> + + <para>It is recommended for new-style daemons + to implement the following:</para> + + <orderedlist> + <listitem><para>If SIGTERM is + received, shut down the daemon and + exit cleanly.</para></listitem> + + <listitem><para>If SIGHUP is received, + reload the configuration files, if + this applies.</para></listitem> + + <listitem><para>Provide a correct exit + code from the main daemon process, as + this is used by the init system to + detect service errors and problems. It + is recommended to follow the exit code + scheme as defined in the <ulink + url="http://refspecs.freestandards.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB + recommendations for SysV init + scripts</ulink>.</para></listitem> + + <listitem><para>If possible and + applicable expose the daemon's control + interface via the D-Bus IPC system and + grab a bus name as last step of + initialization.</para></listitem> + + <listitem><para>For integration in + systemd, provide a + <filename>.service</filename> unit + file that carries information about + starting, stopping and otherwise + maintaining the daemon. See + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para></listitem> + + <listitem><para>As much as possible, + rely on the init systemd's + functionality to limit the access of + the daemon to files, services and + other resources. i.e. in the case of + systemd, rely on systemd's resource + limit control instead of implementing + your own, rely on systemd's privilege + dropping code instead of implementing + it in the daemon, and similar. See + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the available + controls.</para></listitem> + + <listitem><para>If D-Bus is used, make + your daemon bus-activatable, via + supplying a D-Bus service activation + configuration file. This has multiple + advantages: your daemon may be started + lazily on-demand; it may be started in + parallel to other daemons requiring it + -- which maximizes parallelization and + boot-up speed; your daemon can be + restarted on failure, without losing + any bus requests, as the bus queues + requests for activatable services. See + below for details.</para></listitem> + + <listitem><para>If your daemon + provides services to other local + processes or remote clients via a + socket, it should be made + socket-activatable following the + scheme pointed out below. Like D-Bus + activation this enables on-demand + starting of services as well as it + allows improved parallelization of + service start-up. Also, for state-less + protocols (such as syslog, DNS) a + daemon implementing socket-based + activation can be restarted without + losing a single request. See below for + details.</para></listitem> + + <listitem><para>If applicable a daemon + should notify the init system about + startup completion or status updates + via the + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> + interface.</para></listitem> + + <listitem><para>Instead of using the + <function>syslog()</function> call to log directly to the + system syslog service, a new-style daemon may + choose to simply log to STDERR via + <function>fprintf()</function>, which is then forwarded to + syslog by the init system. If log + priorities are necessary these can be + encoded by prefixing individual log + lines with strings like "<4>" + (for log priority 4 "WARNING" in the + syslog priority scheme), following a + similar style as the Linux kernel's + <function>printk()</function> priority system. In fact, + using this style of logging also + enables the init system to optionally + direct all application logging to the + kernel log buffer (kmsg), as + accessible via + <citerefentry><refentrytitle>dmesg</refentrytitle><manvolnum>1</manvolnum></citerefentry>. This + kind of logging may be enabled by + setting + <varname>StandardError=syslog</varname> + in the service unit file. For details + see + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + </orderedlist> + + <para>These recommendations are similar but + not identical to the <ulink + url="http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/Articles/LaunchOnDemandDaemons.html#//apple_ref/doc/uid/TP40001762-104738">Apple + MacOS X Daemon Requirements</ulink>.</para> + </refsect2> + + </refsect1> + <refsect1> + <title>Activation</title> + + <para>New-style init systems provide multiple + additional mechanisms to activate services, as + detailed below. It is common that services are + configured to be activated via more than one mechanism + at the same time. An example for systemd: + <filename>bluetoothd.service</filename> might get + activated either when Bluetooth hardware is plugged + in, or when an application accesses its programming + interfaces via D-Bus. Or, a print server daemon might + get activated when traffic arrives at an IPP port, or + when a printer is plugged in, or when a file is queued + in the printer spool directory. Even for services that + are intended to be started on system bootup + unconditionally it is a good idea to implement some of + the various activation schemes outlined below, in + order to maximize parallelization: if a daemon + implements a D-Bus service or listening socket, + implementing the full bus and socket activation scheme + allows starting of the daemon with its clients in + parallel (which speeds up boot-up), since all its + communication channels are established already, and no + request is lost because client requests will be queued + by the bus system (in case of D-Bus) or the kernel (in + case of sockets), until the activation is + completed.</para> + + <refsect2> + <title>Activation on Boot</title> + + <para>Old-style daemons are usually activated + exclusively on boot (and manually by the + administrator) via SysV init scripts, as + detailed in the <ulink + url="http://refspecs.freestandards.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB + Linux Standard Base Core + Specification</ulink>. This method of + activation is supported ubiquitously on Linux + init systems, both old-style and new-style + systems. Among other issues SysV init scripts + have the disadvantage of involving shell + scripts in the boot process. New-style init + systems generally employ updated versions of + activation, both during boot-up and during + runtime and using more minimal service + description files.</para> + + <para>In systemd, if the developer or + administrator wants to make sure a service or + other unit is activated automatically on boot + it is recommended to place a symlink to the + unit file in the <filename>.wants/</filename> + directory of either + <filename>multi-user.target</filename> or + <filename>graphical.target</filename>, which + are normally used as boot targets at system + startup. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details about the + <filename>.wants/</filename> directories, and + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details about the two boot targets.</para> + + </refsect2> + + <refsect2> + <title>Socket-Based Activation</title> + + <para>In order to maximize the possible + parallelization and robustness and simplify + configuration and development, it is + recommended for all new-style daemons that + communicate via listening sockets to employ + socket-based activation. In a socket-based + activation scheme the creation and binding of + the listening socket as primary communication + channel of daemons to local (and sometimes + remote) clients is moved out of the daemon + code and into the init system. Based on + per-daemon configuration the init system + installs the sockets and then hands them off + to the spawned process as soon as the + respective daemon is to be started. + Optionally activation of the service can be + delayed until the first inbound traffic + arrives at the socket, to implement on-demand + activation of daemons. However, the primary + advantage of this scheme is that all providers + and all consumers of the sockets can be + started in parallel as soon as all sockets + are established. In addition to that daemons + can be restarted with losing only a minimal + number of client transactions or even any + client request at all (the latter is + particularly true for state-less protocols, + such as DNS or syslog), because the socket + stays bound and accessible during the restart, + and all requests are queued while the daemon + cannot process them.</para> + + <para>New-style daemons which support socket + activation must be able to receive their + sockets from the init system, instead of of + creating and binding them themselves. For + details about the programming interfaces for + this scheme provided by systemd see + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>. For + details about porting existing daemons to + socket-based activation see below. With + minimal effort it is possible to implement + socket-based activation in addition to + traditional internal socket creation in the + same codebase in order to support both + new-style and old-style init systems from the + same daemon binary.</para> + + <para>systemd implements socket-based + activation via <filename>.socket</filename> + units, which are described in + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>. When + configuring socket units for socket-based + activation it is essential that all listening + sockets are pulled in by the special target + unit <filename>sockets.target</filename>. It + is recommended to place a + <varname>WantedBy=sockets.target</varname> + directive in the <literal>[Install]</literal> + section, to automatically add such a + dependency on installation of a socket + unit. Unless + <varname>DefaultDependencies=no</varname> is + set the necessary ordering dependencies are + implicitly created for all socket units. For + more information about + <filename>sockets.target</filename> see + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>. It + is not necessary or recommended to place any + additional dependencies on socket units (for + example from + <filename>multi-user.target</filename> or + suchlike) when one is installed in + <filename>sockets.target</filename>.</para> + </refsect2> + + <refsect2> + <title>Bus-Based Activation</title> + + <para>When the D-Bus IPC system is used for + communication with clients, new-style daemons + should employ bus activation so that they are + automatically activated when a client + application accesses their IPC + interfaces. This is configured in D-Bus + service files (not to be confused with systemd + service unit files!). To ensure that D-Bus + uses systemd to start-up and maintain the + daemon use the + <varname>SystemdService=</varname> directive + in these service files, to configure the + matching systemd service for a D-Bus + service. e.g.: for a D-Bus service whose D-Bus + activation file is named + <filename>org.freedesktop.RealtimeKit.service</filename>, + make sure to set + <varname>SystemdService=rtkit-daemon.service</varname> + in that file, to bind it to the systemd + service + <filename>rtkit-daemon.service</filename>. This + is needed to make sure that the daemon is + started in a race-free fashion when activated + via multiple mechanisms simultaneously.</para> + </refsect2> + + <refsect2> + <title>Device-Based Activation</title> + + <para>Often, daemons that manage a particular + type of hardware should be activated only when + the hardware of the respective kind is plugged + in or otherwise becomes available. In a + new-style init system it is possible to bind + activation to hardware plug/unplug events. In + systemd, kernel devices appearing in the + sysfs/udev device tree can be exposed as units + if they are tagged with the string + "<literal>systemd</literal>". Like any other + kind of unit they may then pull in other units + when activated (i.e. Plugged in) and thus + implement device-based activation. Systemd + dependencies may be encoded in the udev + database via the + <varname>SYSTEMD_WANTS=</varname> + property. See + <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. Often it is nicer to pull in + services from devices only indirectly via + dedicated targets. Example: instead of pulling + in <filename>bluetoothd.service</filename> + from all the various bluetooth dongles and + other hardware available, pull in + bluetooth.target from them and + <filename>bluetoothd.service</filename> from + that target. This provides for nicer + abstraction and gives administrators the + option to enable + <filename>bluetoothd.service</filename> via + controlling a + <filename>bluetooth.target.wants/</filename> + symlink uniformly with a command like + <command>enable</command> of + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + instead of manipulating the udev + ruleset.</para> + </refsect2> + + <refsect2> + <title>Path-Based Activation</title> + + <para>Often, runtime of daemons processing + spool files or directories (such as a printing + system) can be delayed until these file system + objects change state, or become + non-empty. New-style init systems provide a + way to bind service activation to file system + changes. systemd implements this scheme via + path-based activation configured in + <filename>.path</filename> units, as outlined + in + <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </refsect2> + + <refsect2> + <title>Timer-Based Activation</title> + + <para>Some daemons that implement clean-up + jobs that are intended to be executed in + regular intervals benefit from timer-based + activation. In systemd, this is implemented + via <filename>.timer</filename> units, as + described in + <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </refsect2> + + <refsect2> + <title>Other Forms of Activation</title> + + <para>Other forms of activation have been + suggested and implemented in some + systems. However, often there are simpler or + better alternatives, or they can be put + together of combinations of the schemes + above. Example: sometimes it appears useful to + start daemons or <filename>.socket</filename> + units when a specific IP address is configured + on a network interface, because network + sockets shall be bound to the + address. However, an alternative to implement + this is by utilizing the Linux IP_FREEBIND + socket option, as accessible via + <varname>FreeBind=yes</varname> in systemd + socket files (see + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details). This option, when enabled, + allows sockets to be bound to a non-local, not + configured IP address, and hence allows + bindings to a particular IP address before it + actually becomes available, making such an + explicit dependency to the configured address + redundant. Another often suggested trigger for + service activation is low system + load. However, here too, a more convincing + approach might be to make proper use of + features of the operating system: in + particular, the CPU or IO scheduler of + Linux. Instead of scheduling jobs from + userspace based on monitoring the OS + scheduler, it is advisable to leave the + scheduling of processes to the OS scheduler + itself. systemd provides fine-grained access + to the CPU and IO schedulers. If a process + executed by the init system shall not + negatively impact the amount of CPU or IO + bandwidth available to other processes, it + should be configured with + <varname>CPUSchedulingPolicy=idle</varname> + and/or + <varname>IOSchedulingClass=idle</varname>. Optionally, + this may be combined with timer-based + activation to schedule background jobs during + runtime and with minimal impact on the system, + and remove it from the boot phase + itself.</para> + </refsect2> + + </refsect1> + <refsect1> + <title>Integration with Systemd</title> + + <refsect2> + <title>Writing Systemd Unit Files</title> + + <para>When writing systemd unit files, it is + recommended to consider the following + suggestions:</para> + + <orderedlist> + <listitem><para>If possible do not use + the <varname>Type=forking</varname> + setting in service files. But if you + do, make sure to set the PID file path + using <varname>PIDFile=</varname>. See + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para></listitem> + + <listitem><para>If your daemon + registers a D-Bus name on the bus, + make sure to use + <varname>Type=dbus</varname> in the + service file if + possible.</para></listitem> + + <listitem><para>Make sure to set a + good human-readable description string + with + <varname>Description=</varname>.</para></listitem> + + <listitem><para>Do not disable + <varname>DefaultDependencies=</varname>, + unless you really know what you do and + your unit is involved in early boot or + late system shutdown.</para></listitem> + + <listitem><para>Normally, little if + any dependencies should need to + be defined explicitly. However, if you + do configure explicit dependencies, only refer to + unit names listed on + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> + or names introduced by your own + package to keep the unit file + operating + system-independent.</para></listitem> + + <listitem><para>Make sure to include + an <literal>[Install]</literal> + section including installation + information for the unit file. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. To activate your service + on boot make sure to add a + <varname>WantedBy=multi-user.target</varname> + or + <varname>WantedBy=graphical.target</varname> + directive. To activate your socket on + boot, make sure to add + <varname>WantedBy=sockets.target</varname>. Usually + you also want to make sure that when + your service is installed your socket + is installed too, hence add + <varname>Also=foo.socket</varname> in + your service file + <filename>foo.service</filename>, for + a hypothetical program + <filename>foo</filename>.</para></listitem> + + </orderedlist> + </refsect2> + + <refsect2> + <title>Installing Systemd Service Files</title> + + <para>At the build installation time + (e.g. <command>make install</command> during + package build) packages are recommended to + install their systemd unit files in the + directory returned by <command>pkg-config + systemd + --variable=systemdsystemunitdir</command> (for + system services), resp. <command>pkg-config + systemd + --variable=systemduserunitdir</command> + (for user services). This will make the + services available in the system on explicit + request but not activate them automatically + during boot. Optionally, during package + installation (e.g. <command>rpm -i</command> + by the administrator) symlinks should be + created in the systemd configuration + directories via the <command>enable</command> + command of the + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + tool, to activate them automatically on + boot.</para> + + <para>Packages using + <citerefentry><refentrytitle>autoconf</refentrytitle><manvolnum>1</manvolnum></citerefentry> + are recommended to use a configure script + excerpt like the following to determine the + unit installation path during source + configuration:</para> + + <programlisting>PKG_PROG_PKG_CONFIG +AC_ARG_WITH([systemdsystemunitdir], + AS_HELP_STRING([--with-systemdsystemunitdir=DIR], [Directory for systemd service files]), + [], [with_systemdsystemunitdir=$($PKG_CONFIG --variable=systemdsystemunitdir systemd)]) +if test "x$with_systemdsystemunitdir" != xno; then + AC_SUBST([systemdsystemunitdir], [$with_systemdsystemunitdir]) +fi +AM_CONDITIONAL(HAVE_SYSTEMD, [test -n "$with_systemdsystemunitdir" -a "x$with_systemdsystemunitdir" != xno ])</programlisting> + + <para>This snippet allows automatic + installation of the unit files on systemd + machines, and optionally allows their + installation even on machines lacking + systemd. (Modification of this snippet for the + user unit directory is left as an exercise for the + reader.)</para> + + <para>Additionally, to ensure that + <command>make distcheck</command> continues to + work, it is recommended to add the following + to the top-level <filename>Makefile.am</filename> + file in + <citerefentry><refentrytitle>automake</refentrytitle><manvolnum>1</manvolnum></citerefentry>-based + projects:</para> + + <programlisting>DISTCHECK_CONFIGURE_FLAGS = \ + --with-systemdsystemunitdir=$$dc_install_base/$(systemdsystemunitdir)</programlisting> + + <para>Finally, unit files should be installed in the system with an automake excerpt like the following:</para> + + <programlisting>if HAVE_SYSTEMD +systemdsystemunit_DATA = \ + foobar.socket \ + foobar.service +endif</programlisting> + + <para>In the + <citerefentry><refentrytitle>rpm</refentrytitle><manvolnum>8</manvolnum></citerefentry> + <filename>.spec</filename> file use a snippet like + the following to enable/disable the service + during installation/deinstallation. Consult + the packaging guidelines of your distribution + for details and the equivalent for other + package managers:</para> + + <programlisting>%post +if [ $1 -eq 1 ]; then + # On install (not upgrade), enable (but don't start) the + # units by default + /bin/systemctl enable foobar.service foobar.socket >/dev/null 2>&1 || : + + # Alternatively, just call + # /bin/systemctl daemon-reload >/dev/null 2>&1 || : + # here, if the daemon should not be enabled by default on + # installation +fi + +%preun +if [ $1 -eq 0 ]; then + # On uninstall (not upgrade), disable and stop the units + /bin/systemctl --no-reload disable foobar.service foobar.socket >/dev/null 2>&1 || : + /bin/systemctl stop foobar.service foobar.socket >/dev/null 2>&1 || : +fi + +%postun +# Reload init system configuration, to make systemd honour changed +# or deleted unit files +/bin/systemctl daemon-reload >/dev/null 2>&1 || : +if [ $1 -ge 1 ] ; then + # On upgrade (not uninstall), optionally, restart the daemon + /bin/systemctl try-restart foobar.service >/dev/null 2>&1 || : +fi</programlisting> + + <para>Depending on whether your service should + or should not be started/stopped/restarted + during package installation, deinstallation or + upgrade, a different set of commands may be + specified. See + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for details.</para> + + <para>To facilitate upgrades from a package + version that shipped only SysV init scripts to + a package version that ships both a SysV init + script and a native systemd service file, use + a fragment like the following:</para> + + <programlisting>%triggerun -- foobar < 0.47.11-1 +if /sbin/chkconfig --level 5 foobar ; then + /bin/systemctl --no-reload enable foobar.service foobar.socket >/dev/null 2>&1 || : +fi</programlisting> + + <para>Where 0.47.11-1 is the first package + version that includes the native unit + file. This fragment will ensure that the first + time the unit file is installed it will be + enabled if and only if the SysV init script is + enabled, thus making sure that the enable + status is not changed. Note that + <command>chkconfig</command> is a command + specific to Fedora which can be used to check + whether a SysV init script is enabled. Other + operating systems will have to use different + commands here.</para> + </refsect2> + </refsect1> + + <refsect1> + <title>Porting Existing Daemons</title> + + <para>Since new-style init systems such as systemd are + compatible with traditional SysV init systems it is + not strictly necessary to port existing daemons to the + new style. However doing so offers additional + functionality to the daemons as well as simplifying + integration into new-style init systems.</para> + + <para>To port an existing SysV compatible daemon the + following steps are recommended:</para> + + <orderedlist> + <listitem><para>If not already implemented, + add an optional command line switch to the + daemon to disable daemonization. This is + useful not only for using the daemon in + new-style init systems, but also to ease + debugging.</para></listitem> + + <listitem><para>If the daemon offers + interfaces to other software running on the + local system via local AF_UNIX sockets, + consider implementing socket-based activation + (see above). Usually a minimal patch is + sufficient to implement this: Extend the + socket creation in the daemon code so that + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry> + is checked for already passed sockets + first. If sockets are passed (i.e. when + <function>sd_listen_fds()</function> returns a + positive value), skip the socket creation step + and use the passed sockets. Secondly, ensure + that the file-system socket nodes for local + AF_UNIX sockets used in the socket-based + activation are not removed when the daemon + shuts down, if sockets have been + passed. Third, if the daemon normally closes + all remaining open file descriptors as part of + its initialization, the sockets passed from + the init system must be spared. Since + new-style init systems guarantee that no + left-over file descriptors are passed to + executed processes, it might be a good choice + to simply skip the closing of all remaining + open file descriptors if sockets are + passed.</para></listitem> + + <listitem><para>Write and install a systemd + unit file for the service (and the sockets if + socket-based activation is used, as well as a + path unit file, if the daemon processes a + spool directory), see above for + details.</para></listitem> + + <listitem><para>If the daemon exposes + interfaces via D-Bus, write and install a + D-Bus activation file for the service, see + above for details.</para></listitem> + </orderedlist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/halt.xml b/man/halt.xml new file mode 100644 index 000000000..97a53ba35 --- /dev/null +++ b/man/halt.xml @@ -0,0 +1,181 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="halt"> + + <refentryinfo> + <title>halt</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>halt</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>halt</refname> + <refname>poweroff</refname> + <refname>reboot</refname> + <refpurpose>Halt, power-off or reboot the machine</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>halt <arg choice="opt" rep="repeat">OPTIONS</arg></command> + </cmdsynopsis> + <cmdsynopsis> + <command>poweroff <arg choice="opt" rep="repeat">OPTIONS</arg></command> + </cmdsynopsis> + <cmdsynopsis> + <command>reboot <arg choice="opt" rep="repeat">OPTIONS</arg></command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>halt</command>, + <command>poweroff</command>, <command>reboot</command> + may be used to halt, power-off or reboot the + machine.</para> + + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--help</option></term> + + <listitem><para>Prints a short help + text and exits.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--halt</option></term> + + <listitem><para>Halt the machine, + regardless which one of the three + commands is invoked.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-p</option></term> + <term><option>--poweroff</option></term> + + <listitem><para>Power-off the machine, + regardless which one of the three + commands is invoked.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--reboot</option></term> + + <listitem><para>Reboot the machine, + regardless which one of the three + commands is invoked.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-f</option></term> + <term><option>--force</option></term> + + <listitem><para>Force immediate halt, + power-off, reboot. Don't contact the + init system.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-w</option></term> + <term><option>--wtmp-only</option></term> + + <listitem><para>Only write wtmp + shutdown entry, don't actually halt, + power-off, reboot.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-d</option></term> + <term><option>--no-wtmp</option></term> + + <listitem><para>Don't write wtmp + shutdown entry.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-n</option></term> + <term><option>--no-sync</option></term> + + <listitem><para>Don't sync hard disks/storage media before + halt, power-off, + reboot.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--no-wall</option></term> + + <listitem><para>Don't send wall + message before + halt, power-off, reboot.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success 0 is returned, a non-zero failure + code otherwise.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>These are legacy commands available for + compatibility only.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>shutdown</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/hostname.xml b/man/hostname.xml new file mode 100644 index 000000000..1acda1af5 --- /dev/null +++ b/man/hostname.xml @@ -0,0 +1,95 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="hostname"> + <refentryinfo> + <title>/etc/hostname</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>hostname</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>hostname</refname> + <refpurpose>Local host name configuration file</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/hostname</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <filename>/etc/hostname</filename> file + configures the name of the local system that is set + during boot, with the + <citerefentry><refentrytitle>sethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry> + system call. It should contain a single + newline-terminated host name string. The + host name may be a free-form string up to 64 characters + in length, however it is recommended that it consists + only of 7bit ASCII lower-case characters and no spaces or dots, + and limits itself to the format allowed for DNS domain + name labels, even though this is not a + strict requirement.</para> + + <para>Depending on the operating system other + configuration files might be checked for configuration + of the host name as well, however only as fallback.</para> + </refsect1> + + <refsect1> + <title>History</title> + + <para>The simple configuration file format of + <filename>/etc/hostname</filename> originates from + Debian GNU/Linux.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/journalctl.xml b/man/journalctl.xml new file mode 100644 index 000000000..f6e46cfbc --- /dev/null +++ b/man/journalctl.xml @@ -0,0 +1,260 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2012 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="journalctl"> + + <refentryinfo> + <title>journalctl</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>journalctl</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>journalctl</refname> + <refpurpose>Query the systemd journal</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>journalctl <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt">MATCH</arg></command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>journalctl</command> may be + used to query the contents of the + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + journal.</para> + + <para>If called without parameter will show the full + contents of the journal, starting with the oldest + entry collected.</para> + + <para>If a match argument is passed the output is + filtered accordingly. A match is in the format + <literal>FIELD=VALUE</literal>, + e.g. <literal>_SYSTEMD_UNIT=httpd.service</literal>.</para> + + <para>Output is interleaved from all accessible + journal files, whether they are rotated or currently + being written, and regardless whether they belong to the + system itself or are accessible user journals.</para> + + <para>All users are granted access to their private + per-user journals. However, by default only root and + users who are members of the <literal>adm</literal> + group get access to the system journal and the + journals of other users.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--help</option></term> + <term><option>-h</option></term> + + <listitem><para>Prints a short help + text and exits.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--version</option></term> + + <listitem><para>Prints a short version + string and exits.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--no-pager</option></term> + + <listitem><para>Do not pipe output into a + pager.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--all</option></term> + <term><option>-a</option></term> + + <listitem><para>Show all fields in + full, even if they include unprintable + characters or are very + long.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--follow</option></term> + <term><option>-f</option></term> + + <listitem><para>Show only most recent + journal entries, and continously print + new entries as they are appended to + the journal.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--lines=</option></term> + <term><option>-n</option></term> + + <listitem><para>Controls the number of + journal lines to show, counting from + the most recent ones. Takes a positive + integer argument. In follow mode + defaults to 10, otherwise is unset + thus not limiting how many lines are + shown.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--no-tail</option></term> + + <listitem><para>Show all stored output + lines, even in follow mode. Undoes the + effect of + <option>--lines=</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--output=</option></term> + <term><option>-o</option></term> + + <listitem><para>Controls the + formatting of the journal entries that are + shown. Takes one of + <literal>short</literal>, + <literal>short-monotonic</literal>, + <literal>verbose</literal>, + <literal>export</literal>, + <literal>json</literal>, + <literal>cat</literal>. <literal>short</literal> + is the default and generates an output + that is mostly identical to the + formatting of classic syslog log + files, showing one line per journal + entry. <literal>short-monotonic</literal> + is very similar but shows monotonic + timestamps instead of wallclock + timestamps. <literal>verbose</literal> + shows the full structered entry items + with all + fiels. <literal>export</literal> + serializes the journal into a binary + (but mostly text-based) stream + suitable for backups and network + transfer. <literal>json</literal> + formats entries as JSON data + structures. <literal>cat</literal> + generates a very terse output only + showing the actual message of each + journal entry with no meta data, not + even a timestamp.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--quiet</option></term> + <term><option>-q</option></term> + + <listitem><para>Suppresses any warning + message regarding inaccessable system + journals when run as normal + user.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--local</option></term> + <term><option>-l</option></term> + + <listitem><para>Show only locally + generated messages.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--new-id128</option></term> + + <listitem><para>Instead of showing + journal contents generate a new 128 + bit ID suitable for identifying + messages. This is intended for usage + by developers who need a new + identifier for a new message they + introduce and want to make + recognizable. Will print the new ID in + three different formats which can be + copied into source code or + similar.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success 0 is returned, a non-zero failure + code otherwise.</para> + </refsect1> + + <refsect1> + <title>Environment</title> + + <variablelist> + <varlistentry> + <term><varname>$SYSTEMD_PAGER</varname></term> + <listitem><para>Pager to use when + <option>--no-pager</option> is not given; + overrides <varname>$PAGER</varname>. Setting + this to an empty string or the value + <literal>cat</literal> is equivalent to passing + <option>--no-pager</option>.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/journald.conf.xml b/man/journald.conf.xml new file mode 100644 index 000000000..a9b0f66de --- /dev/null +++ b/man/journald.conf.xml @@ -0,0 +1,254 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="journald.conf"> + <refentryinfo> + <title>journald.conf</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>journald.conf</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>journald.conf</refname> + <refpurpose>Journal service configuration file</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>journald.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>This files configures various parameters of the systemd journal service.</para> + + </refsect1> + + <refsect1> + <title>Options</title> + + <para>All options are configured in the + <literal>[Journal]</literal> section:</para> + + <variablelist> + + <varlistentry> + <term><varname>Compress=</varname></term> + + <listitem><para>Takes a boolean + value. If enabled (the default) data + objects that shall be stored in the + journal and are larger than a certain + threshold are compressed with the XZ + compression algorithm before they are + written to the file + system.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RateLimitInterval=</varname></term> + <term><varname>RateLimitBurst=</varname></term> + + <listitem><para>Configures the rate + limiting that is applied to all + messages generated on the system. If + in the time interval defined by + <varname>RateLimitInterval=</varname> + more messages than specified in + <varname>RateLimitBurst=</varname> are + logged by a service all further + messages within the interval are + dropped, until the interval is over. A + message about the number of dropped + messages is generated. This rate + limiting is applied per-service, so + that two services which log do not + interfere with each other's + limit. Defaults to 100 messages in + 10s. The time specification for + <varname>RateLimitInterval=</varname> + may be specified in the following + units: <literal>s</literal>, + <literal>min</literal>, + <literal>h</literal>, + <literal>ms</literal>, + <literal>us</literal>. To turn off any + kind of rate limiting, set either + value to 0.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SystemMaxUse=</varname></term> + <term><varname>SystemKeepFree=</varname></term> + <term><varname>SystemMaxFileSize=</varname></term> + <term><varname>SystemMinFileSize=</varname></term> + <term><varname>RuntimeMaxUse=</varname></term> + <term><varname>RuntimeKeepFree=</varname></term> + <term><varname>RuntimeMaxFileSize=</varname></term> + <term><varname>RuntimeMinFileSize=</varname></term> + + <listitem><para>Enforce size limits on + the journal files stored. The options + prefixed with + <literal>System</literal> apply to the + journal files when stored on a + persistant file system, more + specifically + <filename>/var/log/journal</filename>. The + options prefixed with + <literal>Runtime</literal> apply to + the journal files when stored on a + volatile in-memory file system, more + specifically + <filename>/run/log/journal</filename>. The + former is used only when + <filename>/var</filename> is mounted, + writable and the directory + <filename>/var/log/journal</filename> + exists. Otherwise only the latter + applies. Note that this means that + during early boot and if the + administrator disabled persistant + logging only the latter options apply, + while the former apply if persistant + logging is enabled and the system is + fully booted + up. <varname>SystemMaxUse=</varname> + and <varname>RuntimeMaxUse=</varname> + control how much disk space the + journal may use up at + maximum. Defaults to 10% of the size + of the respective file + system. <varname>SystemKeepFree=</varname> + and + <varname>RuntimeKeepFree=</varname> + control how much disk space the + journal shall always leave free for + other uses if less than the disk space + configured in + <varname>SystemMaxUse=</varname> and + <varname>RuntimeMaxUse=</varname> is + available. Defaults to 5% of the size + of the respective file + system. <varname>SystemMaxFileSize=</varname> + and + <varname>RuntimeMaxFileSize=</varname> + control how large individual journal + files may grow at maximum. This + influences the granularity in which + disk space is made available through + rotation, i.e. deletion of historic + data. Defaults to one eigth of the + values configured with + <varname>SystemMaxUse=</varname> and + <varname>RuntimeMaxUse=</varname>, so + that usually seven rotated journal + files are kept as + history. <varname>SystemMinFileSize=</varname> + and + <varname>RuntimeMinFileSize=</varname> + control how large individual journal + files grow at minimum. Defaults to + 64K. Specify values in bytes or use + K, M, G, T, P, E as units for the + specified sizes. Note that size limits + are enforced synchronously to journal + files as they are extended, and need + no explicit rotation step triggered by + time.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ForwardToSyslog=</varname></term> + <term><varname>ForwardToKMsg=</varname></term> + <term><varname>ForwardToConsole=</varname></term> + + <listitem><para>Control whether log + messages received by the journal + daemon shall be forwarded to a + traditional syslog daemon, to the + kernel log buffer (kmsg), or to the + system console. These options take + boolean arguments. If forwarding to + syslog is enabled but no syslog daemon + is running the respective option has + no effect. By default only forwarding + to syslog is enabled. These settings + may be overriden at boot time with the + kernel command line options + <literal>systemd_journald.forward_to_syslog=</literal>, + <literal>systemd_journald.forward_to_kmsg=</literal> + and + <literal>systemd_journald.forward_to_console=</literal>. If + forwarding to the kernel log buffer and + <varname>ImportKernel=</varname> is + enabled at the same time care is taken + to avoid logging loops. It is safe to + use these options in combination. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ImportKernel=</varname></term> + + <listitem><para>Controls whether + kernel log messages shall be stored in + the journal. Takes a boolean argument + and defaults to enabled. Note that + currently only one userspace service + can read kernel messages at a time, + which means that kernel log message + reading might get corrupted if it + is enabled in more than one service, + for example in both the journal and a + traditional syslog service. + </para></listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/locale.conf.xml b/man/locale.conf.xml new file mode 100644 index 000000000..37239974b --- /dev/null +++ b/man/locale.conf.xml @@ -0,0 +1,146 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="locale.conf"> + <refentryinfo> + <title>locale.conf</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>locale.conf</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>locale.conf</refname> + <refpurpose>configuration file for locale settings</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/locale.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <filename>/etc/locale.conf</filename> file + configures system-wide locale settings.</para> + + <para>The basic file format of + <filename>locale.conf</filename> is a + newline-separated list of environment-like + shell-compatible variable assignments. It is possible + to source the configuration from shell scripts, + however, beyond mere variable assignments no shell + features are supported, allowing applications to read + the file without implementing a shell compatible + execution engine.</para> + + <para>Note that the kernel command line options + <varname>locale.LANG=</varname>, + <varname>locale.LANGUAGE=</varname>, + <varname>locale.LC_CTYPE=</varname>, + <varname>locale.LC_NUMERIC=</varname>, + <varname>locale.LC_TIME=</varname>, + <varname>locale.LC_COLLATE=</varname>, + <varname>locale.LC_MONETARY=</varname>, + <varname>locale.LC_MESSAGES=</varname>, + <varname>locale.LC_PAPER=</varname>, + <varname>locale.LC_NAME=</varname>, + <varname>locale.LC_ADDRESS=</varname>, + <varname>locale.LC_TELEPHONE=</varname>, + <varname>locale.LC_MEASUREMENT=</varname>, + <varname>locale.LC_IDENTIFICATION=</varname> may be + used to override the locale settings at boot.</para> + + <para>The locale settings configured in + <filename>/etc/locale.conf</filename> are system-wide + and are inherited by every service or user, unless + overridden or unset by individual programs or + individual users.</para> + + <para>Depending on the operating system other + configuration files might be checked for locale + configuration as well, however only as + fallback.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following locale settings may be set using + <filename>/etc/locale.conf</filename>: + <varname>LANG=</varname>, + <varname>LANGUAGE=</varname>, + <varname>LC_CTYPE=</varname>, + <varname>LC_NUMERIC=</varname>, + <varname>LC_TIME=</varname>, + <varname>LC_COLLATE=</varname>, + <varname>LC_MONETARY=</varname>, + <varname>LC_MESSAGES=</varname>, + <varname>LC_PAPER=</varname>, + <varname>LC_NAME=</varname>, + <varname>LC_ADDRESS=</varname>, + <varname>LC_TELEPHONE=</varname>, + <varname>LC_MEASUREMENT=</varname>, + <varname>LC_IDENTIFICATION=</varname>. Note that + <varname>LC_ALL</varname> may not be be configured in + this file. For details about the meaning and semantics + of these settings, refer to + <citerefentry><refentrytitle>locale</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>Example</title> + + <example> + <title>German locale with English messages</title> + + <para><filename>/etc/locale.conf:</filename></para> + + <programlisting>LANG=de_DE.UTF-8 +LC_MESSAGES=C</programlisting> + </example> + + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>locale</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/loginctl.xml b/man/loginctl.xml new file mode 100644 index 000000000..af1d631cf --- /dev/null +++ b/man/loginctl.xml @@ -0,0 +1,457 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="loginctl"> + + <refentryinfo> + <title>loginctl</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>loginctl</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>loginctl</refname> + <refpurpose>Control the systemd login manager</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>loginctl <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="req">COMMAND</arg> <arg choice="opt" rep="repeat">NAME</arg></command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>loginctl</command> may be used to + introspect and control the state of the + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + login manager.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--help</option></term> + <term><option>-h</option></term> + + <listitem><para>Prints a short help + text and exits.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--version</option></term> + + <listitem><para>Prints a short version + string and exits.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--property=</option></term> + <term><option>-p</option></term> + + <listitem><para>When showing + session/user/ properties, limit + display to certain properties as + specified as argument. If not + specified all set properties are + shown. The argument should be a + property name, such as + <literal>Sessions</literal>. If + specified more than once all + properties with the specified names + are shown.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--all</option></term> + <term><option>-a</option></term> + + <listitem><para>When showing + unit/job/manager properties, show all + properties regardless whether they are + set or not.</para></listitem> + </varlistentry> + + + <varlistentry> + <term><option>--no-pager</option></term> + + <listitem><para>Do not pipe output into a + pager.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--kill-who=</option></term> + + <listitem><para>When used with + <command>kill-session</command>, + choose which processes to kill. Must + be one of <option>leader</option>, or + <option>all</option> to select whether + to kill only the leader process of the + session or all processes of the + session. If omitted defaults to + <option>all</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--signal=</option></term> + <term><option>-s</option></term> + + <listitem><para>When used with + <command>kill-session</command> or + <command>kill-user</command>, choose + which signal to send to selected + processes. Must be one of the well + known signal specifiers such as + SIGTERM, SIGINT or SIGSTOP. If omitted + defaults to + <option>SIGTERM</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-H</option></term> + <term><option>--host</option></term> + + <listitem><para>Execute operation + remotely. Specify a hostname, or + username and hostname separated by @, + to connect to. This will use SSH to + talk to the remote login manager + instance.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-P</option></term> + <term><option>--privileged</option></term> + + <listitem><para>Acquire privileges via + PolicyKit before executing the + operation.</para></listitem> + </varlistentry> + </variablelist> + + <para>The following commands are understood:</para> + + <variablelist> + <varlistentry> + <term><command>list-sessions</command></term> + + <listitem><para>List current sessions.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>session-status [ID...]</command></term> + + <listitem><para>Show terse runtime + status information about one or more + sessions. This function is intended to + generate human-readable output. If you + are looking for computer-parsable + output, use + <command>show-session</command> + instead.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>show-session [ID...]</command></term> + + <listitem><para>Show properties of one + or more sessions or the manager + itself. If no argument is specified + properties of the manager will be + shown. If a session ID is specified + properties of the session is shown. By + default, empty properties are + suppressed. Use <option>--all</option> + to show those too. To select specific + properties to show use + <option>--property=</option>. This + command is intended to be used + whenever computer-parsable output is + required. Use + <command>session-status</command> if + you are looking for formatted + human-readable + output.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>activate [ID...]</command></term> + + <listitem><para>Activate one or more + sessions. This brings one or more + sessions into the foreground, if + another session is currently in the + foreground on the respective + seat.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>lock-session [ID...]</command></term> + <term><command>unlock-session [ID...]</command></term> + + <listitem><para>Activates/deactivates + the screen lock on one or more + sessions, if the session supports it.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>terminate-session [ID...]</command></term> + + <listitem><para>Terminates a + session. This kills all processes of + the session and deallocates all + resources attached to the + session.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>kill-session [ID...]</command></term> + + <listitem><para>Send a signal to one + or more processes of the session. Use + <option>--kill-who=</option> to select + which process to kill. Use + <option>--signal=</option> to select + the signal to send.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>list-users</command></term> + + <listitem><para>List currently logged + in users.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>user-status [USER...]</command></term> + + <listitem><para>Show terse runtime + status information about one or more + logged in users. This function is + intended to generate human-readable + output. If you are looking for + computer-parsable output, use + <command>show-user</command> + instead. Users may be specified by + their usernames or numeric user + IDs.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>show-user [USER...]</command></term> + + <listitem><para>Show properties of one + or more users or the manager + itself. If no argument is specified + properties of the manager will be + shown. If a user is specified + properties of the user is shown. By + default, empty properties are + suppressed. Use <option>--all</option> + to show those too. To select specific + properties to show use + <option>--property=</option>. This + command is intended to be used + whenever computer-parsable output is + required. Use + <command>user-status</command> if + you are looking for formatted + human-readable + output.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>enable-linger [USER...]</command></term> + <term><command>disable-linger [USER...]</command></term> + + <listitem><para>Enable/disable user + lingering for one or more users. If + enabled for a specific user a user + manager is spawned for him/her at + boot, and kept around after + logouts. This allows users who aren't + logged in to run long-running + services.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>terminate-user [USER...]</command></term> + + <listitem><para>Terminates all + sessions of a user. This kills all + processes of all sessions of the user + and deallocates all runtime resources + attached to the + user.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>kill-user [USER...]</command></term> + + <listitem><para>Send a signal to all + processes of a user. Use + <option>--signal=</option> to select + the signal to send.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>list-seats</command></term> + + <listitem><para>List currently + available seats on the local + system.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>seat-status [NAME...]</command></term> + + <listitem><para>Show terse runtime + status information about one or more + seats. This function is + intended to generate human-readable + output. If you are looking for + computer-parsable output, use + <command>show-seat</command> + instead.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>show-seat [NAME...]</command></term> + + <listitem><para>Show properties of one + or more seats or the manager + itself. If no argument is specified + properties of the manager will be + shown. If a seat is specified + properties of the seat are shown. By + default, empty properties are + suppressed. Use <option>--all</option> + to show those too. To select specific + properties to show use + <option>--property=</option>. This + command is intended to be used + whenever computer-parsable output is + required. Use + <command>seat-status</command> if you + are looking for formatted + human-readable + output.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>attach [NAME] [DEVICE...]</command></term> + + <listitem><para>Attach one or more + devices to a seat. The devices should + be specified via device paths in the + <filename>/sys</filename> file + system. To create a new seat attach at + least one graphics card to a + previously unused seat names. seat + names may consist only of a-z, A-Z, + 0-9, "-" and "_" and must be prefixed + with "seat". To drop assignment of a + device to a specific seat just + reassign it to a different seat, or + use + <command>flush-devices</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>flush-devices</command></term> + + <listitem><para>Removes all device + assignments previously created with + <command>attach</command>. After this + call only automatically generated + seats will remain and all seat + hardware is assigned to + them.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>terminate-seat [NAME...]</command></term> + + <listitem><para>Terminates all + sessions on a seat. This kills all + processes of all sessions on a seat and + deallocates all runtime resources + attached to them.</para></listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success 0 is returned, a non-zero failure + code otherwise.</para> + </refsect1> + + <refsect1> + <title>Environment</title> + + <variablelist> + <varlistentry> + <term><varname>$SYSTEMD_PAGER</varname></term> + <listitem><para>Pager to use when + <option>--no-pager</option> is not given; + overrides <varname>$PAGER</varname>. Setting + this to an empty string or the value + <literal>cat</literal> is equivalent to passing + <option>--no-pager</option>.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/logind.conf.xml b/man/logind.conf.xml new file mode 100644 index 000000000..950f81fa9 --- /dev/null +++ b/man/logind.conf.xml @@ -0,0 +1,175 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="logind.conf"> + <refentryinfo> + <title>logind.conf</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>logind.conf</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>logind.conf</refname> + <refpurpose>Login manager configuration file</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>logind.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>This files configures various parameters of the systemd login manager.</para> + + </refsect1> + + <refsect1> + <title>Options</title> + + <para>All options are configured in the + <literal>[Login]</literal> section:</para> + + <variablelist> + + <varlistentry> + <term><varname>NAutoVTs=</varname></term> + + <listitem><para>Takes a positive + integer. How many virtual terminals to + allocate by default and when switched + to autospawn <literal>autovt</literal> + services on (if they are otherwise + unused). These services are + instantiated from a template of + <filename>autovt@.service</filename> + with the virtual terminal TTY name, + e.g. <filename>autovt@tty4.service</filename>. By + default + <filename>autovt@.service</filename> + is linked to + <filename>getty@.service</filename>, + i.e. login prompts are started + dynamically as the user switches to + unused virtual terminals, and this + parameter hence controls how many + gettys are available on the virtual + terminals. Defaults to 6. When set to + 0, automatic spawning of + <literal>autovt</literal> services is + disabled.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>KillUserProcesses=</varname></term> + + <listitem><para>Takes a boolean + argument. Configures whether the + processes of a user should be killed + when she or he completely logs out (i.e. after + her/his last session ended). Defaults to + <literal>no</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>KillOnlyUsers=</varname></term> + <term><varname>KillExcludeUsers=</varname></term> + + <listitem><para>These settings take + space separated lists of user names + that influence the effect of + <varname>KillUserProcesses=</varname>. If + not empty only processes of users + listed in + <varname>KillOnlyUsers</varname> will + be killed when they log out + entirely. Processes of users listed in + <varname>KillExcludeUsers=</varname> + are excluded from being + killed. <varname>KillExcludeUsers=</varname> + defaults to <literal>root</literal> + and takes precedence over + <varname>KillOnlyUsers=</varname> + which defaults to the empty list.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Controllers=</varname></term> + <term><varname>ResetControllers=</varname></term> + + <listitem><para>These settings control + the default control group hierarchies + users logging are added to. When + logging in users will get private + control groups in all hierarchies + listed in + <varname>Controllers=</varname> and be + reset to the root control group in all + hierarchies listed in + <varname>ResetControllers=</varname>. <varname>Controllers=</varname> + defaults to the empty list, + <varname>ResetControllers=</varname> + defaults to + <literal>cpu</literal>.</para></listitem> + </varlistentry> + </variablelist> + + <para>Note that setting + <varname>KillUserProcesses=1</varname> will break tools + like + <citerefentry><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> + + <para>Note that <varname>KillUserProcesses=1</varname> + is a weaker version of + <varname>kill-session-processes=1</varname> which may + be configured per-service for + <citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>. The + latter kills processes of a session as soon as it + ends, the former kills processes as soon as the last + session of the user ends.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/machine-id.xml b/man/machine-id.xml new file mode 100644 index 000000000..97c622c6f --- /dev/null +++ b/man/machine-id.xml @@ -0,0 +1,143 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="machine-id"> + <refentryinfo> + <title>/etc/machine-id</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>machine-id</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>machine-id</refname> + <refpurpose>local machine ID configuration file</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/machine-id</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <filename>/etc/machine-id</filename> file + contains the unique machine id of the local system + that is set during installation. The machine ID is a + single newline-terminated, hexadecimal, lowercase 32 + character machine ID string. (When decoded from + hexadecimal this corresponds with a 16 byte/128 bit + string.)</para> + + <para>The machine ID is usually generated from a + random source during system installation and stays + constant for all subsequent boots. Optionally, for + stateless systems it is generated during runtime at + boot if it is found to be empty.</para> + + <para>The machine ID does not change based on user + configuration, or when hardware is replaced.</para> + + <para>This machine ID adheres to the same format and + logic as the D-Bus machine ID.</para> + + <para>Programs may use this ID to identify the host + with a globally unique ID in the network, that does + not change even if the local network configuration + changes. Due to this and its greater length it is + a more useful replacement for the + <citerefentry><refentrytitle>gethostid</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call POSIX specifies.</para> + + <para>The + <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry> + tool may be used by installer tools to initialize the + machine ID at install time.</para> + </refsect1> + + <refsect1> + <title>Relation to OSF UUIDs</title> + + <para>Note that the machine ID historically is not an + OSF UUID as defined by <ulink + url="http://tools.ietf.org/html/rfc4122">RFC + 4122</ulink>, nor a Microsoft GUID. Starting with + systemd v30 newly generated machine IDs however do + qualify as v4 UUIDs.</para> + + <para>In order to maintain compatibility with existing + installations, an application requiring a UUID should + decode the machine ID, and then apply the following + operations to turn it into a valid OSF v4 UUID. With + <literal>id</literal> being an unsigned character + array:</para> + + <programlisting>/* Set UUID version to 4 --- truly random generation */ +id[6] = (id[6] & 0x0F) | 0x40; +/* Set the UUID variant to DCE */ +id[8] = (id[8] & 0x3F) | 0x80;</programlisting> + + <para>(This code is inspired by + <literal>generate_random_uuid()</literal> of + <filename>drivers/char/random.c</filename> from the + kernel sources.)</para> + + </refsect1> + + <refsect1> + <title>History</title> + + <para>The simple configuration file format of + <filename>/etc/machine-id</filename> originates in the + <filename>/var/lib/dbus/machine-id</filename> file + introduced by D-Bus. In fact this latter file might be a + symlink to + <varname>/etc/machine-id</varname>.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>gethostid</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/machine-info.xml b/man/machine-info.xml new file mode 100644 index 000000000..240da25a6 --- /dev/null +++ b/man/machine-info.xml @@ -0,0 +1,147 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="machine-info"> + <refentryinfo> + <title>machine-info</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>machine-info</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>machine-info</refname> + <refpurpose>Local machine information file</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/machine-info</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <filename>/etc/machine-info</filename> file + contains machine meta data.</para> + + <para>The basic file format of + <filename>machine-info</filename> is a + newline-separated list of environment-like + shell-compatible variable assignments. It is possible + to source the configuration from shell scripts, + however, beyond mere variable assignments no shell + features are supported, allowing applications to read + the file without implementing a shell compatible + execution engine.</para> + + <para><filename>/etc/machine-info</filename> contains + meta data about the machine that is set by the user or + administrator.</para> + + <para>Depending on the operating system other + configuration files might be checked for machine + information as well, however only as fallback.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following machine meta data parameters may + be set using + <filename>/etc/machine-info</filename>:</para> + + <variablelist> + + <varlistentry> + <term><varname>PRETTY_HOSTNAME=</varname></term> + + <listitem><para>A pretty + human-readable UTF8 machine identifier + string. This should contain a name + like <literal>Lennart's + Laptop</literal> which is useful to + present to the user and does not + suffer by the syntax limitations of + internet domain names. If possible the + internet host name as configured in + <filename>/etc/hostname</filename> + should be kept similar to this + one. Example: if this value is + <literal>Lennart's Computer</literal> + an Internet host name of + <literal>lennarts-computer</literal> + might be a good choice. If this + parameter is not set an application + should fall back to the Internet host + name for presentation + purposes.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ICON_NAME=</varname></term> + + <listitem><para>An icon identifying + this machine according to the <ulink + url="http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">XDG + Icon Naming Specification</ulink>. If + this parameter is not set an + application should fall back to + <literal>computer</literal> or a + similar icon name.</para></listitem> + </varlistentry> + + </variablelist> + + </refsect1> + + <refsect1> + <title>Example</title> + + <programlisting>PRETTY_HOSTNAME="Lennart's Computer" +ICON_NAME=computer-laptop</programlisting> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/modules-load.d.xml b/man/modules-load.d.xml new file mode 100644 index 000000000..e2f7d5c68 --- /dev/null +++ b/man/modules-load.d.xml @@ -0,0 +1,112 @@ +<?xml version="1.0"?> +<!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- + This file is part of systemd. + + Copyright 2011 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> +<refentry id="modules-load.d"> + + <refentryinfo> + <title>modules-load.d</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>modules-load.d</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>modules-load.d</refname> + <refpurpose>Configure kernel modules to load at boot</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/modules-load.d/*.conf</filename></para> + <para><filename>/run/modules-load.d/*.conf</filename></para> + <para><filename>/usr/lib/modules-load.d/*.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd</command> uses + files from the above directories to configure + kernel modules to load during boot in a static list. + Each configuration file is named in the style of + <filename>/etc/modules-load.d/<program>.conf</filename>. Note + that it is usually a better idea to use the automatic + module loading by PCI ID, by DMI ID or similar + triggers configured in the kernel modules themselves + instead of relying on static configuration like + this.</para> + </refsect1> + + <refsect1> + <title>Configuration Format</title> + + <para>The configuration files should simply contain a + list of kernel module names to load, separated by + newlines. Empty lines and lines whose first + non-whitespace character is # or ; are ignored.</para> + + <para>Each configuration file is named in the style of + <filename><program>.conf</filename>. + Files in <filename>/etc/</filename> overwrite + files with the same name in <filename>/usr/lib/</filename>. + Files in <filename>/run</filename> overwrite files with + the same name in <filename>/etc/</filename> and + <filename>/usr/lib/</filename>. Packages should install their + configuration files in <filename>/usr/lib/</filename>, files + in <filename>/etc/</filename> are reserved for the local + administration, which possibly decides to overwrite the + configurations installed from packages. All files are sorted + by filename in alphabetical order, regardless in which of the + directories they reside, to ensure that a specific + configuration file takes precedence over another file with + an alphabetically later name.</para> + </refsect1> + + <refsect1> + <title>Example</title> + <example> + <title>/etc/modules-load.d/virtio-net.conf example:</title> + + <programlisting># Load virtio-net.ko at boot +virtio-net</programlisting> + </example> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>modprobe</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/os-release.xml b/man/os-release.xml new file mode 100644 index 000000000..ff8fdf16b --- /dev/null +++ b/man/os-release.xml @@ -0,0 +1,350 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="os-release"> + <refentryinfo> + <title>os-release</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>os-release</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>os-release</refname> + <refpurpose>Operating system identification</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/os-release</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <filename>/etc/os-release</filename> file + contains operating system identification data.</para> + + <para>The basic file format of + <filename>os-release</filename> is a newline-separated + list of environment-like shell-compatible variable + assignments. It is possible to source the + configuration from shell scripts, however, beyond mere + variable assignments no shell features are supported + (this means variable expansion is explicitly not + supported), allowing applications to read the file + without implementing a shell compatible execution + engine. Variable assignment values should be enclosed + in double or single quotes if they include spaces, + semicolons or other special characters outside of A-Z, + a-z, 0-9. All strings should be in UTF-8 format, and + non-printable characters should not be used. If double + or single quotes or backslashes are to be used within + variable assignments they should be escaped with + backslashes, following shell style. It is not + supported to concatenate multiple individually quoted + strings. Lines beginning with "#" shall be ignored as + comments.</para> + + <para><filename>/etc/os-release</filename> contains + data that is defined by the operating system vendor + and should not be changed by the administrator.</para> + + <para>As this file only encodes names and identifiers + it should not be localized.</para> + + <para>The file <filename>/etc/os-release</filename> might + be a symlink to another file, but it is important that + the file is available from earliest boot on, and hence + must be located on the root file system.</para> + + <para>For a longer rationale for + <filename>/etc/os-release</filename> please refer to + the <ulink + url="http://0pointer.de/blog/projects/os-release">Announcement of <filename>/etc/os-release</filename></ulink>.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following OS identifications parameters may be set using + <filename>/etc/os-release</filename>:</para> + + <variablelist> + + <varlistentry> + <term><varname>NAME=</varname></term> + + <listitem><para>A string identifying + the operating system, without a + version component, and suitable for + presentation to the user. If not set + defaults to + <literal>NAME=Linux</literal>. Example: + <literal>NAME=Fedora</literal> or + <literal>NAME="Debian + GNU/Linux"</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>VERSION=</varname></term> + + <listitem><para>A string identifying + the operating system version, + excluding any OS name information, + possibly including a release code + name, and suitable for presentation to + the user. This field is + optional. Example: + <literal>VERSION=17</literal> or + <literal>VERSION="17 (Beefy + Miracle)"</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ID=</varname></term> + + <listitem><para>A lower-case string + (no spaces or other characters outside + of 0-9, a-z, ".", "_" and "-") + identifying the operating system, + excluding any version information and + suitable for processing by scripts or + usage in generated file names. If not + set defaults to + <literal>ID=linux</literal>. Example: + <literal>ID=fedora</literal> or + <literal>ID=debian</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ID_LIKE=</varname></term> + + <listitem><para>A space-separated list + of operating system identifiers in the + same syntax as the + <varname>ID=</varname> setting. Should + list identifiers of operating systems + that are closely related to the local + operating system in regards to + packaging and programming interfaces, + for example listing one or more + OS identifiers the local + OS is a derivative from. An + OS should generally only list other OS + identifiers it itself is a derivative + from, and not any OSes that + are derived from it, but symmetric + relationships are possible. Build + scripts and similar should check this + variable if they need to identify the + local operating system and the value + of <varname>ID=</varname> is not + recognized. Operating systems should + be listed in order of how closely the + local operating system relates to the + listed ones, starting with the + closest. This field is + optional. Example: for an operating + system with + <literal>ID=centos</literal> an + assignment of <literal>ID_LIKE="rhel + fedora"</literal> would be + appropriate. For an operating system + with <literal>ID=ubuntu</literal> an + assignment of + <literal>ID_LIKE=debian</literal> is + appropriate.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>VERSION_ID=</varname></term> + + <listitem><para>A lower-case string + (mostly numeric, no spaces or other + characters outside of 0-9, a-z, ".", + "_" and "-") identifying the operating + system version, excluding any OS name + information or release code name, and + suitable for processing by scripts or + usage in generated file names. This + field is optional. Example: + <literal>VERSION_ID=17</literal> or + <literal>VERSION_ID=11.04</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PRETTY_NAME=</varname></term> + + <listitem><para>A pretty operating + system name in a format suitable for + presentation to the user. May or may + not contain a release code name or OS + version of some kind, as suitable. If + not set defaults to + <literal>PRETTY_NAME="Linux"</literal>. Example: + <literal>PRETTY_NAME="Fedora 17 (Beefy + Miracle)"</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ANSI_COLOR=</varname></term> + + <listitem><para>A suggested + presentation color when showing the + OS name on the console. This + should be specified as string suitable + for inclusion in the ESC [ m + ANSI/ECMA-48 escape code for setting + graphical rendition. This field is + optional. Example: + <literal>ANSI_COLOR="0;31"</literal> + for red, or + <literal>ANSI_COLOR="1;34"</literal> + for light blue.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>CPE_NAME=</varname></term> + + <listitem><para>A CPE name for the + operating system, following the <ulink + url="http://cpe.mitre.org/specification/">Common + Platform Enumeration + Specification</ulink> as proposed by + the MITRE Corporation. This field + is optional. Example: + <literal>CPE_NAME="cpe:/o:fedoraproject:fedora:17"</literal> + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>HOME_URL=</varname></term> + <term><varname>SUPPORT_URL=</varname></term> + <term><varname>BUG_REPORT_URL=</varname></term> + + <listitem><para>Links to resources on + the Internet related the operating + system. <varname>HOME_URL=</varname> + should refer to the homepage of the of + operating system, or alternatively + some homepage of the specific version + of the operating + system. <varname>SUPPORT_URL=</varname> + should refer to the main support page + for the operating system, if there is + any. This is primarily intended for + operating systems which vendors + provide support + for. <varname>BUG_REPORT_URL=</varname> + should refer to the main bug reporting + page for the operating system, if + there is any. This is primarily + intended for operating systems that + rely on community QA. These settings + are optional, and providing only some + of these settings is common. These + URLs are intended to be exposed in + "About this system" UIs behind links + with captions such as "About this + Operating System", "Obtain Support" + resp. "Report a Bug". The values should + be in <ulink + url="https://tools.ietf.org/html/rfc3986">RFC3986 + format</ulink>, and should be + <literal>http:</literal> or + <literal>https:</literal> URLs, and + possibly <literal>mailto:</literal> or + <literal>tel:</literal>. Only one URL + shall be listed in each setting. If + multiple resources need to be + referenced it is recommended to + provide an online landing page linking + all available resources. Examples: + <literal>HOME_URL="https://fedoraproject.org/"</literal> + and + <literal>BUG_REPORT_URL="https://bugzilla.redhat.com/"</literal></para></listitem> + </varlistentry> + + + </variablelist> + + <para>If you are reading this file from C code or a + shell script to determine the OS or a specific version + of it, use the ID and VERSION_ID fields, possibly with + ID_LIKE as fallback for ID. When looking for an OS + identification string for presentation to the user use + the PRETTY_NAME field.</para> + + <para>Note that operating system vendors may choose + not to provide version information, for example to + accommodate for rolling releases. In this case VERSION + and VERSION_ID may be unset. Applications should not + rely on these fields to be set.</para> + + <para>Operating system vendors may extend the file + format and introduce new fields. It is highly + recommended to prefix new fields with an OS specific + name in order to avoid name clashes. Applications + reading this file must ignore unknown fields. Example: + <literal>DEBIAN_BTS="debbugs://bugs.debian.org/"</literal></para> + </refsect1> + + <refsect1> + <title>Example</title> + + <programlisting>NAME=Fedora +VERSION="17 (Beefy Miracle)" +ID=fedora +VERSION_ID=17 +PRETTY_NAME="Fedora 17 (Beefy Miracle)" +ANSI_COLOR="0;34" +CPE_NAME="cpe:/o:fedoraproject:fedora:17" +HOME_URL="https://fedoraproject.org/" +BUG_REPORT_URL="https://bugzilla.redhat.com/"</programlisting> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>lsb_release</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/pam_systemd.xml b/man/pam_systemd.xml new file mode 100644 index 000000000..c07b46bab --- /dev/null +++ b/man/pam_systemd.xml @@ -0,0 +1,316 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="pam_systemd"> + + <refentryinfo> + <title>pam_systemd</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>pam_systemd</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>pam_systemd</refname> + <refpurpose>Register user sessions in the systemd control group hierarchy</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>pam_systemd.so</command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>pam_systemd</command> registers user + sessions in the systemd control group + hierarchy.</para> + + <para>On login, this module ensures the following:</para> + + <orderedlist> + <listitem><para>If it does not exist yet, the + user runtime directory + <filename>/run/user/$USER</filename> is + created and its ownership changed to the user + that is logging in.</para></listitem> + + <listitem><para>The + <varname>$XDG_SESSION_ID</varname> environment + variable is initialized. If auditing is + available and + <command>pam_loginuid.so</command> run before + this module (which is highly recommended), the + variable is initialized from the auditing + session id + (<filename>/proc/self/sessionid</filename>). Otherwise + an independent session counter is + used.</para></listitem> + + <listitem><para>A new control group + <filename>/user/$USER/$XDG_SESSION_ID</filename> + is created and the login process moved into + it.</para></listitem> + </orderedlist> + + <para>On logout, this module ensures the following:</para> + + <orderedlist> + <listitem><para>If + <varname>$XDG_SESSION_ID</varname> is set and + <option>kill-session-processes=1</option> specified, all + remaining processes in the + <filename>/user/$USER/$XDG_SESSION_ID</filename> + control group are killed and the control group + is removed.</para></listitem> + + <listitem><para>If last subgroup of the + <filename>/user/$USER</filename> control group + was removed the + <varname>$XDG_RUNTIME_DIR</varname> directory + and all its contents are + removed, too.</para></listitem> + </orderedlist> + + <para>If the system was not booted up with systemd as + init system, this module does nothing and immediately + returns PAM_SUCCESS.</para> + + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>kill-session-processes=</option></term> + + <listitem><para>Takes a boolean + argument. If true, all processes + created by the user during his session + and from his session will be + terminated when he logs out from his + session.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>kill-only-users=</option></term> + + <listitem><para>Takes a comma + separated list of user names or + numeric user ids as argument. If this + option is used the effect of the + <option>kill-session-processes=</option> options + will apply only to the listed + users. If this option is not used the + option applies to all local + users. Note that + <option>kill-exclude-users=</option> + takes precedence over this list and is + hence subtracted from the list + specified here.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>kill-exclude-users=</option></term> + + <listitem><para>Takes a comma + separated list of user names or + numeric user ids as argument. Users + listed in this argument will not be + subject to the effect of + <option>kill-session-processes=</option>. Note + that that this option takes precedence + over + <option>kill-only-users=</option>, and + hence whatever is listed for + <option>kill-exclude-users=</option> + is guaranteed to never be killed by + this PAM module, independent of any + other configuration + setting.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>controllers=</option></term> + + <listitem><para>Takes a comma + separated list of control group + controllers in which hierarchies a + user/session control group will be + created by default for each user + logging in, in addition to the control + group in the named 'name=systemd' + hierarchy. If omitted, defaults to an + empty list.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>reset-controllers=</option></term> + + <listitem><para>Takes a comma + separated list of control group + controllers in which hierarchies the + logged in processes will be reset to + the root control + group.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>debug=</option></term> + + <listitem><para>Takes a boolean + argument. If yes, the module will log + debugging information as it + operates.</para></listitem> + </varlistentry> + </variablelist> + + <para>Note that setting + <varname>kill-session-processes=1</varname> will break tools + like + <citerefentry><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> + + <para>Note that + <varname>kill-session-processes=1</varname> is a + stricter version of + <varname>KillUserProcesses=1</varname> which may be + configured system-wide in + <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The + former kills processes of a session as soon as it + ends, the latter kills processes as soon as the last + session of the user ends.</para> + + <para>If the options are omitted they default to + <option>kill-session-processes=0</option>, + <option>kill-only-users=</option>, + <option>kill-exclude-users=</option>, + <option>controllers=</option>, + <option>reset-controllers=</option>, + <option>debug=no</option>.</para> + </refsect1> + + <refsect1> + <title>Module Types Provided</title> + + <para>Only <option>session</option> is provided.</para> + </refsect1> + + <refsect1> + <title>Environment</title> + + <para>The following environment variables are set for the processes of the user's session:</para> + + <variablelist> + <varlistentry> + <term><varname>$XDG_SESSION_ID</varname></term> + + <listitem><para>A session identifier, + suitable to be used in file names. The + string itself should be considered + opaque, although often it is just the + audit session ID as reported by + <filename>/proc/self/sessionid</filename>. Each + ID will be assigned only once during + machine uptime. It may hence be used + to uniquely label files or other + resources of this + session.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$XDG_RUNTIME_DIR</varname></term> + + <listitem><para>Path to a user-private + user-writable directory that is bound + to the user login time on the + machine. It is automatically created + the first time a user logs in and + removed on his final logout. If a user + logs in twice at the same time, both + sessions will see the same + <varname>$XDG_RUNTIME_DIR</varname> + and the same contents. If a user logs + in once, then logs out again, and logs + in again, the directory contents will + have been lost in between, but + applications should not rely on this + behaviour and must be able to deal with + stale files. To store session-private + data in this directory the user should + include the value of <varname>$XDG_SESSION_ID</varname> + in the filename. This directory shall + be used for runtime file system + objects such as AF_UNIX sockets, + FIFOs, PID files and similar. It is + guaranteed that this directory is + local and offers the greatest possible + file system feature set the + operating system + provides.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Example</title> + + <programlisting>#%PAM-1.0 +auth required pam_unix.so +auth required pam_nologin.so +account required pam_unix.so +password required pam_unix.so +session required pam_unix.so +session required pam_loginuid.so +session required pam_systemd.so kill-session-processes=1</programlisting> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>pam_loginuid</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/runlevel.xml b/man/runlevel.xml new file mode 100644 index 000000000..160d1b14e --- /dev/null +++ b/man/runlevel.xml @@ -0,0 +1,154 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="runlevel"> + + <refentryinfo> + <title>runlevel</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>runlevel</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>runlevel</refname> + <refpurpose>Print previous and current SysV runlevel</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>runlevel <arg choice="opt" rep="repeat">options</arg></command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>runlevel</command> prints the previous + and current SysV runlevel if they are known.</para> + + <para>The two runlevel characters are separated by a + single space character. If a runlevel cannot be + determined, N is printed instead. If neither can be + determined, the word "unknown" is printed.</para> + + <para>Unless overridden in the environment, this will + check the utmp database for recent runlevel + changes.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following option is understood:</para> + + <variablelist> + <varlistentry> + <term><option>--help</option></term> + + <listitem><para>Prints a short help + text and exits.</para></listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>If one or both runlevels could be determined, 0 + is returned, a non-zero failure code otherwise.</para> + + </refsect1> + + <refsect1> + <title>Environment</title> + + <variablelist> + <varlistentry> + <term><varname>$RUNLEVEL</varname></term> + + <listitem><para>If + <varname>$RUNLEVEL</varname> is set, + <command>runlevel</command> will print + this value as current runlevel and + ignore utmp.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$PREVLEVEL</varname></term> + + <listitem><para>If + <varname>$PREVLEVEL</varname> is set + <command>runlevel</command> will print + this value as previous runlevel and + ignore utmp.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Files</title> + + <variablelist> + <varlistentry> + <term><varname>/var/run/utmp</varname></term> + + <listitem><para>The utmp database + <command>runlevel</command> reads the + previous and current runlevel + from.</para></listitem> + + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>This is a legacy command available for compatibility + only. It should not be used anymore, as the concept of + runlevels is obsolete.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd-daemon.xml b/man/sd-daemon.xml new file mode 100644 index 000000000..4ea88e43d --- /dev/null +++ b/man/sd-daemon.xml @@ -0,0 +1,172 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd-daemon"> + + <refentryinfo> + <title>sd-daemon</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd-daemon</refentrytitle> + <manvolnum>7</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd-daemon</refname> + <refpurpose>Reference implementation of APIs for + new-style daemons</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo> + </funcsynopsis> + + <cmdsynopsis> + <command>pkg-config --cflags --libs libsystemd-daemon</command> + </cmdsynopsis> + + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>sd-daemon.c</filename> and + <filename>sd-daemon.h</filename> provide a reference + implementation of various APIs for new-style daemons, + as implemented by the + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + init system.</para> + + <para>See + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_booted</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_is_fifo</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for more information about the functions + implemented. In addition to these functions a couple + of logging prefixes are defined as macros:</para> + + <programlisting>#define SD_EMERG "<0>" /* system is unusable */ +#define SD_ALERT "<1>" /* action must be taken immediately */ +#define SD_CRIT "<2>" /* critical conditions */ +#define SD_ERR "<3>" /* error conditions */ +#define SD_WARNING "<4>" /* warning conditions */ +#define SD_NOTICE "<5>" /* normal but significant condition */ +#define SD_INFO "<6>" /* informational */ +#define SD_DEBUG "<7>" /* debug-level messages */</programlisting> + + <para>These prefixes are intended to be used in + conjunction with STDERR-based logging as implemented + by systemd. If a systemd service definition file is + configured with <varname>StandardError=syslog</varname> + or <varname>StandardError=kmsg</varname> these + prefixes can be used to encode a log level in lines + printed. This is similar to the kernel + <function>printk()</function>-style logging. See + <citerefentry><refentrytitle>klogctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for more information.</para> + + <para>The log levels are identical to + <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>'s + log level system. To use these prefixes simply prefix + every line with one of these strings. A line that is + not prefixed will be logged at the default log level + SD_INFO.</para> + + <example> + <title>Hello World</title> + + <para>A daemon may log with the log level + NOTICE by issuing this call:</para> + + <programlisting>fprintf(stderr, SD_NOTICE "Hello World!\n");</programlisting> + </example> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>These interfaces are provided by the reference + implementation of APIs for new-style daemons and + distributed with the systemd package. The algorithms + they implement are simple, and can easily be + reimplemented in daemons if it is important to support + this interface without using the reference + implementation. See the respective function man pages + for details.</para> + + <para>In addition, for details about the algorithms + check the liberally licensed reference implementation + sources: + <ulink url="http://cgit.freedesktop.org/systemd/systemd/plain/src/sd-daemon.c"/> + resp. <ulink url="http://cgit.freedesktop.org/systemd/systemd/plain/src/systemd/sd-daemon.h"/></para> + + <para>These APIs are implemented in the reference + implementation's <filename>sd-daemon.c</filename> and + <filename>sd-daemon.h</filename> files. These + interfaces are available as shared library, which can + be compiled and linked to with the + <literal>libsystemd-daemon</literal> + <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file. Alternatively, applications consuming these APIs + may copy the implementation into their source tree, + either verbatim or in excerpts.</para> + + <para>The functions directly related to new-style + daemons become NOPs when -DDISABLE_SYSTEMD is set + during compilation and the reference implementation is + used as drop-in files. In addition, if + <filename>sd-daemon.c</filename> is compiled on + non-Linux systems they become NOPs.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_booted</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_is_fifo</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>fprintf</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-readahead</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd-login.xml b/man/sd-login.xml new file mode 100644 index 000000000..3fc0e16f6 --- /dev/null +++ b/man/sd-login.xml @@ -0,0 +1,146 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd-login"> + + <refentryinfo> + <title>sd-login</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd-login</refentrytitle> + <manvolnum>7</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd-login</refname> + <refpurpose>APIs for + tracking logins</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo> + </funcsynopsis> + + <cmdsynopsis> + <command>pkg-config --cflags --libs libsystemd-login</command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>sd-login.h</filename> provides APIs to + introspect and monitor seat, login session and user + status information on the local system. </para> + + <para>See <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/multiseat">Multi-Seat + on Linux</ulink> for an introduction into multi-seat + support on Linux, the background for this set of APIs.</para> + + <para>Note that these APIs only allow purely passive access + and monitoring of seats, sessions and users. To + actively make changes to the seat configuration, + terminate login sessions, or switch session on a seat + you need to utilize the D-Bus API of + systemd-logind, instead.</para> + + <para>These functions synchronously access data in + <filename>/proc</filename>, + <filename>/sys/fs/cgroup</filename> and + <filename>/run</filename>. All of these are virtual + file systems, hence the runtime cost of the accesses + is relatively cheap.</para> + + <para>It is possible (and often a very good choice) to + mix calls to the synchronous interface of + <filename>sd-login.h</filename> with the asynchronous + D-Bus interface of systemd-logind. However, if this is + done you need to think a bit about possible races + since the stream of events from D-Bus and from + <filename>sd-login.h</filename> interfaces such as the + login monitor are asynchronous and not ordered against + each other.</para> + + <para>If the functions return string arrays, these are + generally NULL terminated and need to be freed by the + caller with the libc + <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use, including the strings referenced + therein. Similar, individual strings returned need to + be freed, as well.</para> + + <para>As a special exception, instead of an empty + string array NULL may be returned, which should be + treated equivalent to an empty string array.</para> + + <para>See + <citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_uid_get_state</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_session_is_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_seat_get_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_login_monitor_new</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for more information about the functions + implemented.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>These APIs are implemented as shared library, + which can be compiled and linked to with the + <literal>libsystemd-login</literal> + <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_uid_get_state</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_session_is_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_seat_get_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_login_monitor_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-readahead</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd-readahead.xml b/man/sd-readahead.xml new file mode 100644 index 000000000..7fb863412 --- /dev/null +++ b/man/sd-readahead.xml @@ -0,0 +1,117 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd-daemon"> + + <refentryinfo> + <title>sd-readahead</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd-readahead</refentrytitle> + <manvolnum>7</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd-readahead</refname> + <refpurpose>Reference implementation of APIs for + controlling boot-time read-ahead</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include "sd-readahead.h"</funcsynopsisinfo> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>sd-readahead.c</filename> and + <filename>sd-readahead.h</filename> provide a + reference implementation for APIs for controlling boot-time + read-ahead, as implemented by the read-ahead subsystem + of the + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + init system.</para> + + <para>See + <citerefentry><refentrytitle>sd_readahead</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for more information about the function + implemented.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>This interface is provided by the reference + implementation of APIs for controlling boot-time + read-ahead and distributed with the systemd + package. The algorithms it implements are simple, and + can easily be reimplemented in daemons if it is + important to support this interface without using the + reference implementation. See the respective function + man pages for details.</para> + + <para>In addition, for details about the algorithms + check the liberally licensed reference implementation + sources: + <ulink url="http://cgit.freedesktop.org/systemd/systemd/plain/src/readahead/sd-readahead.c"/> + resp. <ulink url="http://cgit.freedesktop.org/systemd/systemd/plain/src/systemd/sd-readahead.h"/></para> + + <para>These APIs are implemented in the reference + implementation's drop-in + <filename>sd-readahead.c</filename> and + <filename>sd-readahead.h</filename> files. It is + recommended that applications consuming these APIs copy + the implementation into their source tree, either + verbatim or in excerpts. These interfaces are + currently not available in a dynamic library.</para> + + <para>The functions provided by this interface become + NOPs when -DDISABLE_SYSTEMD is set during + compilation. In addition, if + <filename>sd-readhead.c</filename> is compiled on + non-Linux systems it becomes NOPs.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_readahead</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_booted.xml b/man/sd_booted.xml new file mode 100644 index 000000000..141625d9a --- /dev/null +++ b/man/sd_booted.xml @@ -0,0 +1,128 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_booted"> + + <refentryinfo> + <title>sd_booted</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_booted</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_booted</refname> + <refpurpose>Test whether the system is running the systemd init system.</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_booted</function></funcdef> + <paramdef>void</paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para><function>sd_booted()</function> checks whether + the system was booted up using the systemd init system.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On failure, this call returns a negative + errno-style error code. If the system was booted up + with systemd as init system, this call returns a + positive return value, zero otherwise.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>This function is provided by the reference + implementation of APIs for new-style daemons and + distributed with the systemd package. The algorithm it + implements is simple, and can easily be reimplemented + in daemons if it is important to support this + interface without using the reference + implementation.</para> + + <para>Internally, this function checks whether the + <filename>/sys/fs/cgroup/systemd</filename> virtual file + system is mounted, by comparing the st_dev value of + the <function>stat()</function> data of + <filename>/sys/fs/cgroup</filename> and + <filename>/sys/fs/cgroup/systemd</filename>.</para> + + <para>For details about the algorithm check the + liberally licensed reference implementation sources: + <ulink url="http://cgit.freedesktop.org/systemd/systemd/plain/src/sd-daemon.c"/> + resp. <ulink + url="http://cgit.freedesktop.org/systemd/systemd/plain/src/systemd/sd-daemon.h"/></para> + + <para><function>sd_booted()</function> is implemented + in the reference implementation's + <filename>sd-daemon.c</filename> and + <filename>sd-daemon.h</filename> files. These + interfaces are available as shared library, which can + be compiled and linked to with the + <literal>libsystemd-daemon</literal> + <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file. Alternatively, applications consuming these APIs + may copy the implementation into their source + tree. For more details about the reference + implementation see + <citerefentry><refentrytitle>sd_daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + + <para>If the reference implementation is used as + drop-in files and -DDISABLE_SYSTEMD is set during + compilation this function will always return 0 and + otherwise become a NOP.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_get_seats.xml b/man/sd_get_seats.xml new file mode 100644 index 000000000..2ac76500e --- /dev/null +++ b/man/sd_get_seats.xml @@ -0,0 +1,127 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_get_seats"> + + <refentryinfo> + <title>sd_get_seats</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_get_seats</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_get_seats</refname> + <refname>sd_get_sessions</refname> + <refname>sd_get_uids</refname> + <refpurpose>Determine available seats, sessions and logged in users</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_get_seats</function></funcdef> + <paramdef>char*** <parameter>seats</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_get_sessions</function></funcdef> + <paramdef>char*** <parameter>sessions</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_get_uids</function></funcdef> + <paramdef>char*** <parameter>sessions</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_get_seats()</function> may be used + to determine all currently available local + seats. Returns a NULL terminated array of seat + identifiers. The returned array and all strings it + references need to be freed with the libc + <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use. Note that instead of an empty array + NULL may be returned and should be considered + equivalent to an empty array.</para> + + <para>Similar, <function>sd_get_sessions()</function> may + be used to determine all current login sessions.</para> + + <para>Similar, <function>sd_get_uids()</function> may + be used to determine all Unix users who currently have login sessions.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success <function>sd_get_seats()</function>, + <function>sd_get_sessions()</function> and + <function>sd_get_uids()</function> return the number + of entries in the arrays. On failure, these calls + return a negative errno-style error code.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_get_seats()</function>, + <function>sd_get_sessions()</function> and + <function>sd_get_uids()</function> interfaces + are available as shared library, which can be compiled + and linked to with the + <literal>libsystemd-login</literal> + <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_session_get_seat</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_is_fifo.xml b/man/sd_is_fifo.xml new file mode 100644 index 000000000..4db512012 --- /dev/null +++ b/man/sd_is_fifo.xml @@ -0,0 +1,217 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_is_fifo"> + + <refentryinfo> + <title>sd_is_fifo</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_is_fifo</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_is_fifo</refname> + <refname>sd_is_socket</refname> + <refname>sd_is_socket_inet</refname> + <refname>sd_is_socket_unix</refname> + <refname>sd_is_mq</refname> + <refpurpose>Check the type of a file descriptor</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_is_fifo</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>const char *<parameter>path</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_is_socket</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>family</parameter></paramdef> + <paramdef>int <parameter>type</parameter></paramdef> + <paramdef>int <parameter>listening</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_is_socket_inet</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>family</parameter></paramdef> + <paramdef>int <parameter>type</parameter></paramdef> + <paramdef>int <parameter>listening</parameter></paramdef> + <paramdef>uint16_t <parameter>port</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_is_socket_unix</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>type</parameter></paramdef> + <paramdef>int <parameter>listening</parameter></paramdef> + <paramdef>const char* <parameter>path</parameter></paramdef> + <paramdef>size_t <parameter>length</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_is_mq</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>const char *<parameter>path</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_is_fifo()</function> may be called + to check whether the specified file descriptor refers + to a FIFO or pipe. If the <parameter>path</parameter> + parameter is not NULL, it is checked whether the FIFO + is bound to the specified file system path.</para> + + <para><function>sd_is_socket()</function> may be + called to check whether the specified file descriptor + refers to a socket. It the + <parameter>family</parameter> parameter is not + AF_UNSPEC it is checked whether the socket is of the + specified family (AF_UNIX, AF_INET, ...). If the + <parameter>type</parameter> parameter is not 0 it is + checked whether the socket is of the specified type + (SOCK_STREAM, SOCK_DGRAM, ...). If the + <parameter>listening</parameter> parameter is positive + it is checked whether the socket is in accepting mode, + i.e. <function>listen()</function> has been called for + it. If <parameter>listening</parameter> is 0, it is + checked whether the socket is not in this mode. If the + parameter is negative, no such check is made. The + <parameter>listening</parameter> parameter should only + be used for stream sockets and should be set to a + negative value otherwise.</para> + + <para><function>sd_is_socket_inet()</function> is + similar to <function>sd_is_socket()</function>, but + optionally checks the IPv4 or IPv6 port number the + socket is bound to, unless <parameter>port</parameter> + is zero. For this call <parameter>family</parameter> + must be passed as either AF_UNSPEC, AF_INET or + AF_INET6.</para> + + <para><function>sd_is_socket_unix()</function> is + similar to <function>sd_is_socket()</function>, but + optionally checks the AF_UNIX path the socket is bound + to, unless the <parameter>path</parameter> parameter + is NULL. For normal file system AF_UNIX sockets set + the <parameter>length</parameter> parameter to 0. For + Linux abstract namespace sockets set the + <parameter>length</parameter> to the size of the + address, including the initial 0 byte and set + <parameter>path</parameter> to the initial 0 byte of + the socket address.</para> + + <para><function>sd_is_mq()</function> may be called to + check whether the specified file descriptor refers to + a POSIX message queue. If the + <parameter>path</parameter> parameter is not NULL, it + is checked whether the message queue is bound to the + specified name.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On failure, these calls return a negative + errno-style error code. If the file descriptor is of + the specified type and bound to the specified address + a positive return value is returned, otherwise + zero.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>These functions are provided by the reference + implementation of APIs for new-style daemons and + distributed with the systemd package. The algorithms + they implement are simple, and can easily be + reimplemented in daemons if it is important to support + this interface without using the reference + implementation.</para> + + <para>Internally, these function use a combination of + <filename>fstat()</filename> and + <filename>getsockname()</filename> to check the file + descriptor type and where it is bound to.</para> + + <para>For details about the algorithms check the + liberally licensed reference implementation sources: + <ulink url="http://cgit.freedesktop.org/systemd/systemd/plain/src/sd-daemon.c"/> + resp. <ulink + url="http://cgit.freedesktop.org/systemd/systemd/plain/src/systemd/sd-daemon.h"/></para> + + <para><function>sd_is_fifo()</function> and the + related functions are implemented in the reference + implementation's <filename>sd-daemon.c</filename> and + <filename>sd-daemon.h</filename> files. These + interfaces are available as shared library, which can + be compiled and linked to with the + <literal>libsystemd-daemon</literal> + <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file. Alternatively, applications consuming these APIs + may copy the implementation into their source + tree. For more details about the reference + implementation see + <citerefentry><refentrytitle>sd_daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + + <para>These functions continue to work as described, + even if -DDISABLE_SYSTEMD is set during + compilation.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_listen_fds.xml b/man/sd_listen_fds.xml new file mode 100644 index 000000000..c3c70a0df --- /dev/null +++ b/man/sd_listen_fds.xml @@ -0,0 +1,203 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_listen_fds"> + + <refentryinfo> + <title>sd_listen_fds</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_listen_fds</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_listen_fds</refname> + <refpurpose>Check for file descriptors passed by the init system.</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo> + + <funcsynopsisinfo>#define SD_LISTEN_FDS_START 3</funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_listen_fds</function></funcdef> + <paramdef>int <parameter>unset_environment</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_listen_fds()</function> shall be + called by a daemon to check for file descriptors + passed by the init system as part of the socket-based + activation logic.</para> + + <para>If the <parameter>unset_environment</parameter> + parameter is non-zero + <function>sd_listen_fds()</function> will unset the + <varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname> + environment variables before returning (regardless + whether the function call itself succeeded or + not). Further calls to + <function>sd_listen_fds()</function> will then fail, + but the variables are no longer inherited by child + processes.</para> + + <para>If a daemon receives more than one file + descriptor, they will be passed in the same order as + configured in the systemd socket definition + file. Nonetheless it is recommended to verify the + correct socket types before using them. To simplify + this checking the functions + <citerefentry><refentrytitle>sd_is_fifo</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_is_socket</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_is_socket_inet</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_is_socket_unix</refentrytitle><manvolnum>3</manvolnum></citerefentry> + are provided. In order to maximize flexibility it is + recommended to make these checks as loose as possible + without allowing incorrect setups. i.e. often the + actual port number a socket is bound to matters little + for the service to work, hence it should not be + verified. On the other hand, whether a socket is a + datagram or stream socket matters a lot for the most + common program logics and should be checked.</para> + + <para>This function call will set the FD_CLOEXEC flag + for all passed file descriptors to avoid further + inheritance to children of the calling process.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On failure, this call returns a negative + errno-style error code. If + <varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname> + was not set or was not correctly set for this daemon and + hence no file descriptors were received, 0 is + returned. Otherwise the number of file descriptors + passed is returned. The application may find them + starting with file descriptor SD_LISTEN_FDS_START, + i.e. file descriptor 3.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>This function is provided by the reference + implementation of APIs for new-style daemons and + distributed with the systemd package. The algorithm it + implements is simple, and can easily be reimplemented + in daemons if it is important to support this + interface without using the reference + implementation.</para> + + <para>Internally, this function checks whether the + <varname>$LISTEN_PID</varname> environment variable + equals the daemon PID. If not, it returns + immediately. Otherwise it parses the number passed in + the <varname>$LISTEN_FDS</varname> environment + variable, then sets the FD_CLOEXEC flag for the parsed + number of file descriptors starting from + SD_LISTEN_FDS_START. Finally it returns the parsed + number.</para> + + <para>For details about the algorithm check the + liberally licensed reference implementation sources: + <ulink url="http://cgit.freedesktop.org/systemd/systemd/plain/src/sd-daemon.c"/> + resp. <ulink + url="http://cgit.freedesktop.org/systemd/systemd/plain/src/systemd/sd-daemon.h"/></para> + + <para><function>sd_listen_fds()</function> is + implemented in the reference implementation's + <filename>sd-daemon.c</filename> and + <filename>sd-daemon.h</filename> files. These + interfaces are available as shared library, which can + be compiled and linked to with the + <literal>libsystemd-daemon</literal> + <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file. Alternatively, applications consuming these APIs + may copy the implementation into their source + tree. For more details about the reference + implementation see + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + + <para>If the reference implementation is used as + drop-in files and -DDISABLE_SYSTEMD is set during + compilation this function will always return 0 and + otherwise become a NOP.</para> + </refsect1> + + <refsect1> + <title>Environment</title> + + <variablelist> + <varlistentry> + <term><varname>$LISTEN_PID</varname></term> + <term><varname>$LISTEN_FDS</varname></term> + + <listitem><para>Set by the init system + for supervised processes that use + socket-based activation. This + environment variable specifies the + data + <function>sd_listen_fds()</function> + parses. See above for + details.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_is_fifo</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_is_socket</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_is_socket_inet</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_is_socket_unix</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_login_monitor_new.xml b/man/sd_login_monitor_new.xml new file mode 100644 index 000000000..de484329a --- /dev/null +++ b/man/sd_login_monitor_new.xml @@ -0,0 +1,172 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_login_monitor_new"> + + <refentryinfo> + <title>sd_login_monitor_new</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_login_monitor_new</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_login_monitor_new</refname> + <refname>sd_login_monitor_unref</refname> + <refname>sd_login_monitor_flush</refname> + <refname>sd_login_monitor_get_fd</refname> + <refpurpose>Monitor login sessions, seats and users</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_login_monitor_new</function></funcdef> + <paramdef>const char* <parameter>category</parameter></paramdef> + <paramdef>sd_login_monitor** <parameter>ret</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>sd_login_monitor* <function>sd_login_monitor_unref</function></funcdef> + <paramdef>sd_login_monitor* <parameter>m</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_login_monitor_flush</function></funcdef> + <paramdef>sd_login_monitor* <parameter>m</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_login_monitor_get_fd</function></funcdef> + <paramdef>sd_login_monitor* <parameter>m</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_login_monitor_new()</function> may + be used to monitor login session, users and seats. Via + a monitor object a file descriptor can be integrated + into an application defined event loop which is woken + up each time a user logs in, logs out or a seat is + added or removed, or a session, user, or seat changes + state otherwise. The first parameter takes a string + which can be either <literal>seat</literal> (to get + only notifications about seats being added, removed or + changed), <literal>session</literal> (to get only + notifications about sessions being created or removed + or changed) or <literal>uid</literal> (to get only + notifications when a user changes state in respect to + logins). If notifications shall be generated in all + these conditions, NULL may be passed. Note that in + future additional categories may be defined. The + second parameter returns a monitor object and needs to + be freed with the + <function>sd_login_monitor_unref()</function> call + after use.</para> + + <para><function>sd_login_monitor_unref()</function> + may be used to destroy a monitor object. Note that + this will invalidate any file descriptor returned by + <function>sd_login_monitor_get_fd()</function>.</para> + + <para><function>sd_login_monitor_flush()</function> + may be used to reset the wakeup state of the monitor + object. Whenever an event causes the monitor to wake + up the event loop via the file descriptor this + function needs to be called to reset the wake-up + state. If this call is not invoked the file descriptor + will immediately wake up the event loop again.</para> + + <para><function>sd_login_monitor_get_fd()</function> + may be used to retrieve the file descriptor of the + monitor object that may be integrated in an + application defined event loop, based around + <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry> + or a similar interface. The application should include + the returned file descriptor as wake up source for + POLLIN events. Whenever a wake-up is triggered the + file descriptor needs to be reset via + <function>sd_login_monitor_flush()</function>. An + application needs to reread the login state with a + function like + <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry> + or similar to determine what changed.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success + <function>sd_login_monitor_new()</function> and + <function>sd_login_monitor_flush()</function> return 0 + or a positive integer. On success + <function>sd_login_monitor_get_fd()</function> returns + a Unix file descriptor. On failure, these calls return + a negative errno-style error code.</para> + + <para><function>sd_login_monitor_unref()</function> + always returns NULL.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_login_monitor_new()</function>, + <function>sd_login_monitor_unref()</function>, <function>sd_login_monitor_flush()</function> and + <function>sd_login_monitor_get_fd()</function> interfaces + are available as shared library, which can be compiled + and linked to with the + <literal>libsystemd-login</literal> + <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_notify.xml b/man/sd_notify.xml new file mode 100644 index 000000000..9d9ea4132 --- /dev/null +++ b/man/sd_notify.xml @@ -0,0 +1,312 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_notify"> + + <refentryinfo> + <title>sd_notify</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_notify</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_notify</refname> + <refname>sd_notifyf</refname> + <refpurpose>Notify init system about start-up completion and other daemon status changes</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_notify</function></funcdef> + <paramdef>int <parameter>unset_environment</parameter></paramdef> + <paramdef>const char *<parameter>state</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_notifyf</function></funcdef> + <paramdef>int <parameter>unset_environment</parameter></paramdef> + <paramdef>const char *<parameter>format</parameter></paramdef> + <paramdef>...</paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para><function>sd_notify()</function> shall be called + by a daemon to notify the init system about status + changes. It can be used to send arbitrary information, + encoded in an environment-block-like string. Most + importantly it can be used for start-up completion + notification.</para> + + <para>If the <parameter>unset_environment</parameter> + parameter is non-zero <function>sd_notify()</function> + will unset the <varname>$NOTIFY_SOCKET</varname> + environment variable before returning (regardless + whether the function call itself succeeded or + not). Further calls to + <function>sd_notify()</function> will then fail, but + the variable is no longer inherited by child + processes.</para> + + <para>The <parameter>state</parameter> parameter + should contain an newline-separated list of variable + assignments, similar in style to an environment + block. A trailing newline is implied if none is + specified. The string may contain any kind of variable + assignments, but the following shall be considered + well-known:</para> + + <variablelist> + <varlistentry> + <term>READY=1</term> + + <listitem><para>Tells the init system + that daemon startup is finished. This + is only used by systemd if the service + definition file has Type=notify + set. The passed argument is a boolean + "1" or "0". Since there is little + value in signalling non-readiness, the + only value daemons should send is + "READY=1".</para></listitem> + </varlistentry> + + <varlistentry> + <term>STATUS=...</term> + + <listitem><para>Passes a single-line + status string back to the init system + that describes the daemon state. This + is free-form and can be used for + various purposes: general state + feedback, fsck-like programs could + pass completion percentages and + failing programs could pass a human + readable error message. Example: + "STATUS=Completed 66% of file system + check..."</para></listitem> + </varlistentry> + + <varlistentry> + <term>ERRNO=...</term> + + <listitem><para>If a daemon fails, the + errno-style error code, formatted as + string. Example: "ERRNO=2" for + ENOENT.</para></listitem> + </varlistentry> + + <varlistentry> + <term>BUSERROR=...</term> + + <listitem><para>If a daemon fails, the + D-Bus error-style error code. Example: + "BUSERROR=org.freedesktop.DBus.Error.TimedOut"</para></listitem> + </varlistentry> + + <varlistentry> + <term>MAINPID=...</term> + + <listitem><para>The main pid of the + daemon, in case the init system did + not fork off the process + itself. Example: + "MAINPID=4711"</para></listitem> + </varlistentry> + + <varlistentry> + <term>WATCHDOG=1</term> + + <listitem><para>Tells systemd to + update the watchdog timestamp. + Services using this feature should do + this in regular intervals. A watchdog + framework can use the timestamps to + detect failed + services.</para></listitem> + </varlistentry> + </variablelist> + + <para>It is recommended to prefix variable names that + are not shown in the list above with + <varname>X_</varname> to avoid namespace + clashes.</para> + + <para>Note that systemd will accept status data sent + from a daemon only if the + <varname>NotifyAccess=</varname> option is correctly + set in the service definition file. See + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para> + + <para><function>sd_notifyf()</function> is similar to + <function>sd_notify()</function> but takes a + <function>printf()</function>-like format string plus + arguments.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On failure, these calls return a negative + errno-style error code. If + <varname>$NOTIFY_SOCKET</varname> was not set and + hence no status data could be sent, 0 is returned. If + the status was sent these functions return with a + positive return value. In order to support both, init + systems that implement this scheme and those which + don't, it is generally recommended to ignore the return + value of this call.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>These functions are provided by the reference + implementation of APIs for new-style daemons and + distributed with the systemd package. The algorithms + they implement are simple, and can easily be + reimplemented in daemons if it is important to support + this interface without using the reference + implementation.</para> + + <para>Internally, these functions send a single + datagram with the state string as payload to the + AF_UNIX socket referenced in the + <varname>$NOTIFY_SOCKET</varname> environment + variable. If the first character of + <varname>$NOTIFY_SOCKET</varname> is @ the string is + understood as Linux abstract namespace socket. The + datagram is accompanied by the process credentials of + the sending daemon, using SCM_CREDENTIALS.</para> + + <para>For details about the algorithms check the + liberally licensed reference implementation sources: + <ulink url="http://cgit.freedesktop.org/systemd/systemd/plain/src/sd-daemon.c"/> + resp. <ulink + url="http://cgit.freedesktop.org/systemd/systemd/plain/src/systemd/sd-daemon.h"/></para> + + <para><function>sd_notify()</function> and + <function>sd_notifyf()</function> are implemented in + the reference implementation's + <filename>sd-daemon.c</filename> and + <filename>sd-daemon.h</filename> files. These + interfaces are available as shared library, which can + be compiled and linked to with the + <literal>libsystemd-daemon</literal> + <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file. Alternatively, applications consuming these APIs + may copy the implementation into their source tree. For + more details about the reference implementation see + <citerefentry><refentrytitle>sd_daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + + <para>If the reference implementation is used as + drop-in files and -DDISABLE_SYSTEMD is set during + compilation these functions will always return 0 and + otherwise become a NOP.</para> + </refsect1> + + <refsect1> + <title>Environment</title> + + <variablelist> + <varlistentry> + <term><varname>$NOTIFY_SOCKET</varname></term> + + <listitem><para>Set by the init system + for supervised processes for status + and start-up completion + notification. This environment variable + specifies the socket + <function>sd_notify()</function> talks + to. See above for details.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + + <example> + <title>Start-up Notification</title> + + <para>When a daemon finished starting up, it + might issue the following call to notify + the init system:</para> + + <programlisting>sd_notify(0, "READY=1");</programlisting> + </example> + + <example> + <title>Extended Start-up Notification</title> + + <para>A daemon could send the following after + completing initialization:</para> + + <programlisting>sd_notifyf(0, "READY=1\n" + "STATUS=Processing requests...\n" + "MAINPID=%lu", + (unsigned long) getpid());</programlisting> + </example> + + <example> + <title>Error Cause Notification</title> + + <para>A daemon could send the following shortly before exiting, on failure</para> + + <programlisting>sd_notifyf(0, "STATUS=Failed to start up: %s\n" + "ERRNO=%i", + strerror(errno), + errno);</programlisting> + </example> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_pid_get_session.xml b/man/sd_pid_get_session.xml new file mode 100644 index 000000000..94f533022 --- /dev/null +++ b/man/sd_pid_get_session.xml @@ -0,0 +1,160 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_pid_get_session"> + + <refentryinfo> + <title>sd_pid_get_session</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_pid_get_session</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_pid_get_session</refname> + <refname>sd_pid_get_unit</refname> + <refname>sd_pid_get_owner_uid</refname> + <refpurpose>Determine session, service or owner of a session of a specific PID</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_pid_get_session</function></funcdef> + <paramdef>pid_t <parameter>pid</parameter></paramdef> + <paramdef>char** <parameter>session</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_pid_get_unit</function></funcdef> + <paramdef>pid_t <parameter>pid</parameter></paramdef> + <paramdef>char** <parameter>unit</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_pid_get_owner_uid</function></funcdef> + <paramdef>pid_t <parameter>pid</parameter></paramdef> + <paramdef>uid_t* <parameter>uid</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_pid_get_session()</function> may be + used to determine the login session identifier of a + process identified by the specified process + identifier. The session identifier is a short string, + suitable for usage in file system paths. Note that not + all processes are part of a login session (e.g. system + service processes, user processes that are shared + between multiple sessions of the same user, or kernel + threads). For processes not being part of a login + session this function will fail. The returned string + needs to be freed with the libc + <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use.</para> + + <para><function>sd_pid_get_unit()</function> may be + used to determine the systemd unit (i.e. system + service) identifier of a process identified by the + specified process identifier. The unit name is a short + string, suitable for usage in file system paths. Note + that not all processes are part of a unit/service + (e.g. user processes, or kernel threads). For + processes not being part of a systemd unit/system + service this function will fail. The returned string + needs to be freed with the libc + <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use.</para> + + <para><function>sd_pid_get_owner_uid()</function> may + be used to determine the Unix user identifier of the + owner of the session of a process identified the + specified PID. Note that this function will succeed + for user processes which are shared between multiple + login sessions of the same user, where + <function>sd_pid_get_session()</function> will + fail. For processes not being part of a login session + and not being a shared process of a user this function + will fail.</para> + + <para>If the <literal>pid</literal> paramater of any + of these functions is passed as 0 the operation is + executed for the calling process.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success these calls return 0 or a positive + integer. On failure, these calls return a negative + errno-style error code.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_pid_get_session()</function>, + <function>sd_pid_get_pid()</function>, and + <function>sd_pid_get_owner_uid()</function> interfaces + are available as shared library, which can be compiled + and linked to with the + <literal>libsystemd-login</literal> + <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + + <para>Note that the login session identifier as + returned by <function>sd_pid_get_session()</function> + is completely unrelated to the process session + identifier as returned by + <citerefentry><refentrytitle>getsid</refentrytitle><manvolnum>2</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_session_is_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>getsid</refentrytitle><manvolnum>2</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_readahead.xml b/man/sd_readahead.xml new file mode 100644 index 000000000..2e7e09c5e --- /dev/null +++ b/man/sd_readahead.xml @@ -0,0 +1,178 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_notify"> + + <refentryinfo> + <title>sd_readahead</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_readahead</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_readahead</refname> + <refpurpose>Control ongoing disk boot-time read-ahead operations</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include "sd-readahead.h"</funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_readahead</function></funcdef> + <paramdef>const char *<parameter>action</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para><function>sd_readahead()</function> may be + called by programs involved with early boot-up to + control ongoing boot-time disk read-ahead operations. It may be + used to terminate read-ahead operations in case an + uncommon disk access pattern is to be expected and + hence read-ahead replay or collection is unlikely to + have the desired speed-up effect on the current or + future boot-ups.</para> + + <para>The <parameter>action</parameter> should be one + of the following strings:</para> + + <variablelist> + <varlistentry> + <term>cancel</term> + + <listitem><para>Terminates read-ahead + data collection, and drops all + read-ahead data collected during this + boot-up.</para></listitem> + </varlistentry> + + <varlistentry> + <term>done</term> + + <listitem><para>Terminates read-ahead + data collection, but keeps all + read-ahead data collected during this + boot-up around for use during + subsequent boot-ups.</para></listitem> + </varlistentry> + + <varlistentry> + <term>noreplay</term> + + <listitem><para>Terminates read-ahead + replay.</para></listitem> + </varlistentry> + + </variablelist> + + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On failure, these calls return a negative + errno-style error code. It is generally recommended to + ignore the return value of this call.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>This function is provided by the reference + implementation of APIs for controlling boot-time + read-ahead and distributed with the systemd + package. The algorithm it implements is simple, and + can easily be reimplemented in daemons if it is + important to support this interface without using the + reference implementation.</para> + + <para>Internally, this function creates a file in + <filename>/run/systemd/readahead/</filename> which is + then used as flag file to notify the read-ahead + subsystem.</para> + + <para>For details about the algorithm check the + liberally licensed reference implementation sources: + <ulink url="http://cgit.freedesktop.org/systemd/systemd/plain/src/readahead/sd-readahead.c"/> + resp. <ulink + url="http://cgit.freedesktop.org/systemd/systemd/plain/src/systemd/sd-readahead.h"/></para> + + <para><function>sd_readahead()</function> is + implemented in the reference implementation's drop-in + <filename>sd-readahead.c</filename> and + <filename>sd-readahead.h</filename> files. It is + recommended that applications consuming this API copy + the implementation into their source tree. For more + details about the reference implementation see + <citerefentry><refentrytitle>sd-readahead</refentrytitle><manvolnum>7</manvolnum></citerefentry></para> + + <para>If -DDISABLE_SYSTEMD is set during compilation + this function will always return 0 and otherwise + become a NOP.</para> + </refsect1> + + <refsect1> + <title>Examples</title> + + <example> + <title>Cancelling all read-ahead operations</title> + + <para>During boots where SELinux has to + relabel the file system hierarchy, it will + create a large amount of disk accesses that + are not necessary during normal boots. Hence + it is a good idea to disable both read-ahead replay and read-ahead collection. + </para> + + <programlisting>sd_readahead("cancel"); +sd_readahead("noreplay");</programlisting> + </example> + + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-readahead</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_seat_get_active.xml b/man/sd_seat_get_active.xml new file mode 100644 index 000000000..acc6ee4ea --- /dev/null +++ b/man/sd_seat_get_active.xml @@ -0,0 +1,157 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_seat_get_active"> + + <refentryinfo> + <title>sd_seat_get_active</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_seat_get_active</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_seat_get_active</refname> + <refname>sd_seat_get_sessions</refname> + <refname>sd_seat_can_multi_session</refname> + <refpurpose>Determine state of a specific seat</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_seat_get_active</function></funcdef> + <paramdef>const char* <parameter>seat</parameter></paramdef> + <paramdef>char** <parameter>session</parameter></paramdef> + <paramdef>uid_t* <parameter>uid</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_seat_get_sessions</function></funcdef> + <paramdef>const char* <parameter>seat</parameter></paramdef> + <paramdef>char*** <parameter>sessions</parameter></paramdef> + <paramdef>uid_t** <parameter>uid</parameter></paramdef> + <paramdef>unsigned* <parameter>n_uids</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_seat_can_multi_session</function></funcdef> + <paramdef>const char* <parameter>seat</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_seat_get_active()</function> may be + used to determine which session is currently active on + a seat, if there is any. Returns the session + identifier and the user identifier of the Unix user + the session is belonging to. Either the session or the + user identifier parameter can be be passed NULL, in + case only one of the parameters shall be queried. The + returned string needs to be freed with the libc + <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use.</para> + + <para><function>sd_seat_get_sessions()</function> may + be used to determine all sessions on the specified + seat. Returns two arrays, one (NULL terminated) with + the session identifiers of the sessions and one with + the user identifiers of the Unix users the sessions + belong to. An additional parameter may be used to + return the number of entries in the latter array. The + two arrays and the latter parameter may be passed as + NULL in case these values need not to be + determined. The arrays and the strings referenced by + them need to be freed with the libc + <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use. Note that instead of an empty array + NULL may be returned and should be considered + equivalent to an empty array.</para> + + <para><function>sd_seat_can_multi_session()</function> + may be used to determine whether a specific seat is + capable of multi-session, i.e. allows multiple login + sessions in parallel (whith only one being active at a + time).</para> + + <para>If the <literal>seat</literal> parameter of any + of these functions is passed as NULL the operation is + executed for the seat of the session of the calling + process, if there is any.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para> On success + <function>sd_seat_get_active()</function> return + return 0 or a positive integer. On success + <function>sd_seat_get_sessions()</function> returns + the number of entries in the session identifier + array. If the test succeeds + <function>sd_seat_can_multi_session</function> returns + a positive integer, if it fails 0. On failure, these + calls return a negative errno-style error code.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_seat_get_active()</function>, + <function>sd_seat_get_sessions()</function>, and + <function>sd_seat_can_multi_session()</function> interfaces + are available as shared library, which can be compiled + and linked to with the + <literal>libsystemd-login</literal> + <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_session_get_seat</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_session_is_active.xml b/man/sd_session_is_active.xml new file mode 100644 index 000000000..afdeed55d --- /dev/null +++ b/man/sd_session_is_active.xml @@ -0,0 +1,206 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_session_is_active"> + + <refentryinfo> + <title>sd_session_is_active</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_session_is_active</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_session_is_active</refname> + <refname>sd_session_get_uid</refname> + <refname>sd_session_get_seat</refname> + <refname>sd_session_get_service</refname> + <refname>sd_session_get_type</refname> + <refname>sd_session_get_class</refname> + <refname>sd_session_get_display</refname> + <refpurpose>Determine state of a specific session</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_session_is_active</function></funcdef> + <paramdef>const char* <parameter>session</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_session_get_uid</function></funcdef> + <paramdef>const char* <parameter>session</parameter></paramdef> + <paramdef>uid_t* <parameter>uid</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_session_get_seat</function></funcdef> + <paramdef>const char* <parameter>session</parameter></paramdef> + <paramdef>char** <parameter>seat</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_session_get_service</function></funcdef> + <paramdef>const char* <parameter>session</parameter></paramdef> + <paramdef>char** <parameter>service</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_session_get_type</function></funcdef> + <paramdef>const char* <parameter>session</parameter></paramdef> + <paramdef>char** <parameter>type</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_session_get_class</function></funcdef> + <paramdef>const char* <parameter>session</parameter></paramdef> + <paramdef>char** <parameter>class</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_session_get_display</function></funcdef> + <paramdef>const char* <parameter>session</parameter></paramdef> + <paramdef>char** <parameter>display</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_session_is_active()</function> may + be used to determine whether the session identified by + the specified session identifier is currently active + (i.e. currently in the foreground and available for + user input) or not.</para> + + <para><function>sd_session_get_uid()</function> may be + used to determine the user identifier of the Unix user the session + identified by the specified session identifier belongs + to.</para> + + <para><function>sd_session_get_seat()</function> may + be used to determine the seat identifier of the seat + the session identified by the specified session + identifier belongs to. Note that not all sessions are + attached to a seat, this call will fail for them. The + returned string needs to be freed with the libc + <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use.</para> + + <para><function>sd_session_get_service()</function> + may be used to determine the name of the service (as + passed during PAM session setup) that registered the + session identified by the specified session + identifier. The returned string needs to be freed with + the libc + <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use.</para> + + <para><function>sd_session_get_type()</function> may + be used to determine the type of the session + identified by the specified session identifier. The + returned string is one of <literal>x11</literal>, + <literal>tty</literal> or + <literal>unspecified</literal> and needs to be freed + with the libc + <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use.</para> + + <para><function>sd_session_get_class()</function> may + be used to determine the class of the session + identified by the specified session identifier. The + returned string is one of <literal>user</literal>, + <literal>greeter</literal> or + <literal>lock-screen</literal> and needs to be freed + with the libc + <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use.</para> + + <para><function>sd_session_get_display()</function> + may be used to determine the X11 display of the + session identified by the specified session + identifier. The returned string is one of needs to be + freed with the libc + <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use.</para> + + <para>If the <literal>session</literal> parameter of + any of these functions is passed as NULL the operation + is executed for the session the calling process is a + member of, if there is any.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>If the test succeeds + <function>sd_session_is_active()</function> returns a + positive integer, if it fails 0. On success + <function>sd_session_get_uid()</function>, + <function>sd_session_get_service()</function> and + <function>sd_session_get_seat()</function> return 0 or + a positive integer. On failure, these calls return a + negative errno-style error code.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_session_is_active()</function>, + <function>sd_session_get_uid()</function>, + <function>sd_session_get_service()</function> and + <function>sd_session_get_seat()</function> interfaces + are available as shared library, which can be compiled + and linked to with the + <literal>libsystemd-login</literal> + <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_uid_get_state.xml b/man/sd_uid_get_state.xml new file mode 100644 index 000000000..9249021aa --- /dev/null +++ b/man/sd_uid_get_state.xml @@ -0,0 +1,185 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_uid_get_state"> + + <refentryinfo> + <title>sd_uid_get_state</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_uid_get_state</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_uid_get_state</refname> + <refname>sd_uid_is_on_seat</refname> + <refname>sd_uid_get_sessions</refname> + <refname>sd_uid_get_seats</refname> + <refpurpose>Determine login state of a specific Unix user ID</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_uid_get_state</function></funcdef> + <paramdef>uid_t <parameter>uid</parameter></paramdef> + <paramdef>char** <parameter>state</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_uid_is_on_seat</function></funcdef> + <paramdef>uid_t <parameter>uid</parameter></paramdef> + <paramdef>int <parameter>require_active</parameter></paramdef> + <paramdef>const char* <parameter>seat</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_uid_get_sessions</function></funcdef> + <paramdef>uid_t <parameter>uid</parameter></paramdef> + <paramdef>int <parameter>require_active</parameter></paramdef> + <paramdef>char*** <parameter>sessions</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_uid_get_seats</function></funcdef> + <paramdef>uid_t <parameter>uid</parameter></paramdef> + <paramdef>int <parameter>require_active</parameter></paramdef> + <paramdef>char*** <parameter>seats</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_uid_get_state()</function> may be + used to determine the login state of a specific Unix + user identifier. The following states are currently + known: <literal>offline</literal> (user not logged in + at all), <literal>lingering</literal> (user not logged + in, but some user services running), + <literal>online</literal> (user logged in, but not + active), <literal>active</literal> (user logged in on + an active seat). In the future additional states might + be defined, client code should be written to be robust + in regards to additional state strings being + returned. The returned string needs to be freed with + the libc + <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use.</para> + + <para><function>sd_uid_is_on_seat()</function> may be + used to determine whether a specific user is logged in + or active on a specific seat. Accepts a Unix user + identifier and a seat identifier string as + parameters. The <parameter>require_active</parameter> + parameter is a boolean. If non-zero (true) this + function will test if the user is active (i.e. has a + session that is in the foreground and accepting user + input) on the specified seat, otherwise (false) only + if the user is logged in (and possibly inactive) on + the specified seat.</para> + + <para><function>sd_uid_get_sessions()</function> may + be used to determine the current sessions of the + specified user. Acceptes a Unix user identifier as + parameter. The <parameter>require_active</parameter> + boolean parameter controls whether the returned list + shall consist of only those sessions where the user is + currently active (true) or where the user is currently + logged in at all, possibly inactive (false). The call + returns a NULL terminated string array of session + identifiers in <parameter>sessions</parameter> which + needs to be freed by the caller with the libc + <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use, including all the strings + referenced. If the string array parameter is passed as + NULL the array will not be filled in, but the return + code still indicates the number of current + sessions. Note that instead of an empty array NULL may + be returned and should be considered equivalent to an + empty array.</para> + + <para>Similar, <function>sd_uid_get_seats()</function> + may be used to determine the list of seats on which + the user currently has sessions. Similar semantics + apply, however note that the user may have + multiple sessions on the same seat as well as sessions + with no attached seat and hence the number of entries + in the returned array may differ from the one returned + by <function>sd_uid_get_sessions()</function>.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success + <function>sd_uid_get_state()</function> returns 0 or a + positive integer. If the test succeeds + <function>sd_uid_is_on_seat()</function> returns a + positive integer, if it fails + 0. <function>sd_uid_get_sessions()</function> and + <function>sd_uid_get_seats()</function> return the + number of entries in the returned arrays. On failure, + these calls return a negative errno-style error + code.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_uid_get_state()</function>, + <function>sd_uid_is_on_seat()</function>, + <function>sd_uid_get_sessions()</function>, and + <function>sd_uid_get_seats()</function> interfaces are + available as shared library, which can be compiled and + linked to with the <literal>libsystemd-login</literal> + <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_pid_get_owner_uid</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/shutdown.xml b/man/shutdown.xml new file mode 100644 index 000000000..c8c4b5462 --- /dev/null +++ b/man/shutdown.xml @@ -0,0 +1,188 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="shutdown"> + + <refentryinfo> + <title>shutdown</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>shutdown</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>shutdown</refname> + <refpurpose>Halt, power-off or reboot the machine</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>shutdown <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt">TIME</arg> <arg choice="opt" rep="repeat">WALL</arg></command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>shutdown</command> may be used to halt, + power-off or reboot the machine.</para> + + <para>The first argument may be a time string (which + is usually <literal>now</literal>). Optionally, this + may be followed by a wall message to be sent to all + logged-in users before going down.</para> + + <para>The time string may either be in the format + <literal>hh:mm</literal> for hour/minutes specifying + the time to execute the shutdown at, specified in 24h + clock format. Alternatively it may be in the syntax + <literal>+m</literal> referring to the specified + number of minutes m from now. <literal>now</literal> + is an alias for <literal>+0</literal>, i.e. for + triggering an immediate shutdown. If no time argument + is specified, <literal>+1</literal> is + implied.</para> + + <para>Note that to specify a wall message you must + specify a time argument, too.</para> + + <para>If the time argument is used, 5 minutes + before the system goes down the + <filename>/etc/nologin</filename> file is created to + ensure that further logins shall not be + allowed.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--help</option></term> + + <listitem><para>Prints a short help + text and exits.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-H</option></term> + <term><option>--halt</option></term> + + <listitem><para>Halt the machine.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-P</option></term> + <term><option>--poweroff</option></term> + + <listitem><para>Power-off the + machine (the default).</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-r</option></term> + <term><option>--reboot</option></term> + + <listitem><para>Reboot the + machine.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-h</option></term> + + <listitem><para>Equivalent to + <option>--poweroff</option>, unless + <option>--halt</option> is + specified.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-k</option></term> + + <listitem><para>Don't halt, power-off, + reboot, just write wall + message.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--no-wall</option></term> + + <listitem><para>Don't send wall + message before + halt, power-off, reboot.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-c</option></term> + + <listitem><para>Cancel a pending + shutdown. This may be used cancel the + effect of an invocation of + <command>shutdown</command> with a + time argument that is not + <literal>+0</literal> or + <literal>now</literal>.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success 0 is returned, a non-zero failure + code otherwise.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>This is a legacy command available for + compatibility only.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>halt</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sysctl.d.xml b/man/sysctl.d.xml new file mode 100644 index 000000000..20f2e2482 --- /dev/null +++ b/man/sysctl.d.xml @@ -0,0 +1,123 @@ +<?xml version="1.0"?> +<!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- + This file is part of systemd. + + Copyright 2011 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> +<refentry id="sysctl.d"> + + <refentryinfo> + <title>sysctl.d</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sysctl.d</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>sysctl.d</refname> + <refpurpose>Configure kernel parameters at boot</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/sysctl.d/*.conf</filename></para> + <para><filename>/run/sysctl.d/*.conf</filename></para> + <para><filename>/usr/lib/sysctl.d/*.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd</command> uses configuration + files from the above directories to configure + <citerefentry><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry> + kernel parameters during boot.</para> + </refsect1> + + <refsect1> + <title>Configuration Format</title> + + <para>The configuration files contain a list of + variable assignments, separated by newlines. Empty + lines and lines whose first non-whitespace character + is # or ; are ignored.</para> + + <para>Note that both / and . are accepted as label + separators within sysctl variable + names. <literal>kernel.domainname=foo</literal> and + <literal>kernel/domainname=foo</literal> hence are + entirely equivalent.</para> + + <para>Each configuration file shall be named in the + style of <filename><program>.conf</filename>. + Files in <filename>/run/</filename> override files + with the same name in <filename>/usr/lib/</filename>. + Files in <filename>/etc</filename> override files with + the same name in <filename>/run/</filename> and + <filename>/usr/lib/</filename>. Packages should + install their configuration files in + <filename>/usr/lib/</filename>. Files in + <filename>/etc/</filename> are reserved for the local + administrator, who may use this logic to override the + configuration installed by vendor packages. All + configuration files are sorted by their name in + alphabetical order, regardless in which of the + directories they reside, to guarantee that a specific + configuration file takes precedence over another file + with an alphabetically earlier name, if both files + contain the same variable setting.</para> + + <para>If the administrator wants to disable a + configuration file supplied by the vendor the + recommended way is to place a symlink to + <filename>/dev/null</filename> in + <filename>/etc/sysctl.d</filename> carrying with the + same name.</para> + </refsect1> + + <refsect1> + <title>Example</title> + <example> + <title>/etc/sysctl.d/domain-name.conf example:</title> + + <programlisting># Set kernel YP domain name +kernel.domainname=example.com</programlisting> + </example> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sysctl.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemctl.xml b/man/systemctl.xml new file mode 100644 index 000000000..167a72b58 --- /dev/null +++ b/man/systemctl.xml @@ -0,0 +1,1190 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemctl"> + + <refentryinfo> + <title>systemctl</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemctl</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemctl</refname> + <refpurpose>Control the systemd system and service manager</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemctl <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="req">COMMAND</arg> <arg choice="opt" rep="repeat">NAME</arg></command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemctl</command> may be used to + introspect and control the state of the + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + system and service manager.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--help</option></term> + <term><option>-h</option></term> + + <listitem><para>Prints a short help + text and exits.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--version</option></term> + + <listitem><para>Prints a short version + string and exits.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--type=</option></term> + <term><option>-t</option></term> + + <listitem><para>When listing units, + limit display to certain unit + types. If not specified units of all + types will be shown. The argument + should be a unit type name such as + <option>service</option>, + <option>socket</option> and + similar.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--property=</option></term> + <term><option>-p</option></term> + + <listitem><para>When showing + unit/job/manager properties, limit + display to certain properties as + specified as argument. If not + specified all set properties are + shown. The argument should be a + property name, such as + <literal>MainPID</literal>. If + specified more than once all + properties with the specified names + are shown.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--all</option></term> + <term><option>-a</option></term> + + <listitem><para>When listing units, + show all units, regardless of their + state, including inactive units. When + showing unit/job/manager properties, + show all properties regardless whether + they are set or not.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--failed</option></term> + + <listitem><para>When listing units, + show only failed units. Do not confuse + with + <option>--fail</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--full</option></term> + + <listitem><para>Do not ellipsize unit + names and truncate unit descriptions + in the output of + <command>list-units</command> and + <command>list-jobs</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--fail</option></term> + + <listitem><para>If the requested + operation conflicts with a pending + unfinished job, fail the command. If + this is not specified the requested + operation will replace the pending job, + if necessary. Do not confuse + with + <option>--failed</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--ignore-dependencies</option></term> + + <listitem><para>When enqueuing a new + job ignore all its dependencies and + execute it immediately. If passed no + required units of the unit passed will + be pulled in, and no ordering + dependencies will be honoured. This is + mostly a debugging and rescue tool for + the administrator and should not be + used by + applications.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--quiet</option></term> + <term><option>-q</option></term> + + <listitem><para>Suppress output to + STDOUT in + <command>snapshot</command>, + <command>is-active</command>, + <command>enable</command> and + <command>disable</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--no-block</option></term> + + <listitem><para>Do not synchronously wait for + the requested operation to finish. If this is + not specified the job will be verified, + enqueued and <command>systemctl</command> will + wait until it is completed. By passing this + argument it is only verified and + enqueued.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--no-legend</option></term> + + <listitem><para>Do not print a legend, i.e. + the column headers and the footer with hints. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--no-pager</option></term> + + <listitem><para>Do not pipe output into a + pager.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--system</option></term> + + <listitem><para>Talk to the systemd + system manager. (Default)</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--user</option></term> + + <listitem><para>Talk to the systemd + manager of the calling user.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--order</option></term> + <term><option>--require</option></term> + + <listitem><para>When used in + conjunction with the + <command>dot</command> command (see + below), selects which dependencies are + shown in the dependency graph. If + <option>--order</option> is passed + only dependencies of type + <varname>After=</varname> or + <varname>Before=</varname> are + shown. If <option>--require</option> + is passed only dependencies of type + <varname>Requires=</varname>, + <varname>RequiresOverridable=</varname>, + <varname>Requisite=</varname>, + <varname>RequisiteOverridable=</varname>, + <varname>Wants=</varname> and + <varname>Conflicts=</varname> are + shown. If neither is passed, shows + dependencies of all these + types.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--no-wall</option></term> + + <listitem><para>Don't send wall + message before + halt, power-off, reboot.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--global</option></term> + + <listitem><para>When used with + <command>enable</command> and + <command>disable</command>, operate on the + global user configuration + directory, thus enabling or disabling + a unit file globally for all future + logins of all users.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--no-reload</option></term> + + <listitem><para>When used with + <command>enable</command> and + <command>disable</command>, do not + implicitly reload daemon configuration + after executing the + changes.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--no-ask-password</option></term> + + <listitem><para>When used with + <command>start</command> and related + commands, disables asking for + passwords. Background services may + require input of a password or + passphrase string, for example to + unlock system hard disks or + cryptographic certificates. Unless + this option is specified and the + command is invoked from a terminal + <command>systemctl</command> will + query the user on the terminal for the + necessary secrets. Use this option to + switch this behavior off. In this + case the password must be supplied by + some other means (for example + graphical password agents) or the + service might fail.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--kill-who=</option></term> + + <listitem><para>When used with + <command>kill</command>, choose which + processes to kill. Must be one of + <option>main</option>, + <option>control</option> or + <option>all</option> to select whether + to kill only the main process of the + unit, the control process or all + processes of the unit. If omitted + defaults to + <option>all</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--signal=</option></term> + <term><option>-s</option></term> + + <listitem><para>When used with + <command>kill</command>, choose which + signal to send to selected + processes. Must be one of the well + known signal specifiers such as + SIGTERM, SIGINT or SIGSTOP. If + omitted defaults to + <option>SIGTERM</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--force</option></term> + <term><option>-f</option></term> + + <listitem><para>When used with + <command>enable</command>, override any + existing conflicting + symlinks.</para></listitem> + + <listitem><para>When used with + <command>halt</command>, + <command>poweroff</command>, + <command>reboot</command> or + <command>kexec</command> execute the + selected operation without shutting + down all units. However, all processes + will be killed forcibly and all file + systems are unmounted or remounted + read-only. This is hence a drastic but + relatively safe option to request an + immediate reboot. If + <option>--force</option> is specified + twice for these operations, they will + be executed immediately without + terminating any processes or umounting + any file systems. Warning: specifying + <option>--force</option> twice with + any of these operations might result + in data loss.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--root=</option></term> + + <listitem><para>When used with + <command>enable</command>/<command>disable</command>/<command>is-enabled</command> (and + related commands), use alternative + root path when looking for unit + files.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--runtime</option></term> + + <listitem><para>When used with + <command>enable</command>/<command>disable</command>/<command>is-enabled</command> (and related commands), make + changes only temporarily, so that they + are dropped on the next reboot. This + will have the effect that changes are + not made in subdirectories of + <filename>/etc</filename> but in + <filename>/run</filename>, with + identical immediate effects, however, + since the latter is lost on reboot, + the changes are lost + too.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-H</option></term> + <term><option>--host</option></term> + + <listitem><para>Execute operation + remotely. Specify a hostname, or + username and hostname separated by @, + to connect to. This will use SSH to + talk to the remote systemd + instance.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-P</option></term> + <term><option>--privileged</option></term> + + <listitem><para>Acquire privileges via + PolicyKit before executing the + operation.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--lines=</option></term> + <term><option>-n</option></term> + + <listitem><para>When used with + <command>status</command> controls the + number of journal lines to show, + counting from the most recent + ones. Takes a positive integer + argument. Defaults to + 10.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--follow</option></term> + <term><option>-f</option></term> + + <listitem><para>When used with + <command>status</command> continously + prints new journal entries as they are + appended to the + journal.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--output=</option></term> + <term><option>-o</option></term> + + <listitem><para>When used with + <command>status</command> controls the + formatting of the journal entries that + are shown. For the available choices + see + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. Defaults + to + <literal>short</literal>.</para></listitem> + </varlistentry> + + </variablelist> + + <para>The following commands are understood:</para> + + <variablelist> + <varlistentry> + <term><command>list-units</command></term> + + <listitem><para>List known units.</para></listitem> + </varlistentry> + <varlistentry> + <term><command>start [NAME...]</command></term> + + <listitem><para>Start (activate) one + or more units specified on the command + line.</para></listitem> + </varlistentry> + <varlistentry> + <term><command>stop [NAME...]</command></term> + + <listitem><para>Stop (deactivate) one + or more units specified on the command + line.</para></listitem> + </varlistentry> + <varlistentry> + <term><command>reload [NAME...]</command></term> + + <listitem><para>Asks all units listed + on the command line to reload their + configuration. Note that this will + reload the service-specific + configuration, not the unit + configuration file of systemd. If you + want systemd to reload the + configuration file of a unit use the + <command>daemon-reload</command> + command. In other words: for the + example case of Apache, this will + reload Apache's + <filename>httpd.conf</filename> in the + web server, not the + <filename>apache.service</filename> + systemd unit file. </para> + + <para>This command should not be + confused with the + <command>daemon-reload</command> or + <command>load</command> + commands.</para></listitem> + + </varlistentry> + <varlistentry> + <term><command>restart [NAME...]</command></term> + + <listitem><para>Restart one or more + units specified on the command + line. If the units are not running yet + they will be + started.</para></listitem> + </varlistentry> + <varlistentry> + <term><command>try-restart [NAME...]</command></term> + + <listitem><para>Restart one or more + units specified on the command + line if the units are running. Do + nothing if units are not running. + Note that for compatibility + with Red Hat init scripts + <command>condrestart</command> is + equivalent to this command.</para></listitem> + </varlistentry> + <varlistentry> + <term><command>reload-or-restart [NAME...]</command></term> + + <listitem><para>Reload one or more + units if they support it. If not, + restart them instead. If the units + are not running yet they will be + started.</para></listitem> + </varlistentry> + <varlistentry> + <term><command>reload-or-try-restart [NAME...]</command></term> + + <listitem><para>Reload one or more + units if they support it. If not, + restart them instead. Do nothing if + the units are not running. Note that + for compatibility with SysV init + scripts + <command>force-reload</command> is + equivalent to this + command.</para></listitem> + </varlistentry> + <varlistentry> + <term><command>isolate [NAME]</command></term> + + <listitem><para>Start the unit + specified on the command line and its + dependencies and stop all others.</para> + + <para>This is similar to changing the + runlevel in a traditional init system. The + <command>isolate</command> command will + immediately stop processes that are not + enabled in the new unit, possibly including + the graphical environment or terminal you + are currently using.</para> + + <para>Note that this works only on units + where <option>AllowIsolate=</option> is + enabled. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + <varlistentry> + <term><command>kill [NAME...]</command></term> + + <listitem><para>Send a signal to one + or more processes of the unit. Use + <option>--kill-who=</option> to select + which process to kill. Use + <option>--kill-mode=</option> to + select the kill mode and + <option>--signal=</option> to select + the signal to send.</para></listitem> + </varlistentry> + <varlistentry> + <term><command>is-active [NAME...]</command></term> + + <listitem><para>Check whether any of + the specified units are active + (i.e. running). Returns an exit code + 0 if at least one is active, non-zero + otherwise. Unless + <option>--quiet</option> is specified + this will also print the current unit + state to STDOUT.</para></listitem> + </varlistentry> + <varlistentry> + <term><command>status [NAME...|PID...]</command></term> + + <listitem><para>Show terse runtime + status information about one or more + units, followed by its most recent log + data from the journal. This function + is intended to generate human-readable + output. If you are looking for + computer-parsable output, use + <command>show</command> instead. If a + PID is passed information about the + unit the process of the PID belongs to + is shown.</para></listitem> + </varlistentry> + <varlistentry> + <term><command>show [NAME...|JOB...]</command></term> + + <listitem><para>Show properties of one + or more units, jobs or the manager + itself. If no argument is specified + properties of the manager will be + shown. If a unit name is specified + properties of the unit is shown, and + if a job id is specified properties of + the job is shown. By default, empty + properties are suppressed. Use + <option>--all</option> to show those + too. To select specific properties to + show use + <option>--property=</option>. This + command is intended to be used + whenever computer-parsable output is + required. Use + <command>status</command> if you are + looking for formatted human-readable + output.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>reset-failed [NAME...]</command></term> + + <listitem><para>Reset the + '<literal>failed</literal>' state of the + specified units, or if no unit name is + passed of all units. When a unit fails + in some way (i.e. process exiting with + non-zero error code, terminating + abnormally or timing out) it will + automatically enter the + '<literal>failed</literal>' state and + its exit code and status is recorded + for introspection by the administrator + until the service is restarted or + reset with this + command.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>list-unit-files</command></term> + + <listitem><para>List installed unit files. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><command>enable [NAME...]</command></term> + + <listitem><para>Enable one or more + unit files, as specified on the + command line. This will create a + number of symlinks as encoded in the + <literal>[Install]</literal> sections + of the unit files. After the symlinks + have been created the systemd + configuration is reloaded (in a way + that is equivalent to + <command>daemon-reload</command>) to + ensure the changes are taken into + account immediately. Note that this + does not have the effect that any of + the units enabled are also started at + the same time. If this is desired a + separate <command>start</command> + command must be invoked for the + unit.</para> + + <para>This command will + print the actions executed. This + output may be suppressed by passing + <option>--quiet</option>.</para> + + <para>Note that this operation creates + only the suggested symlinks for the + units. While this command is the + recommended way to manipulate the unit + configuration directory, the + administrator is free to make + additional changes manually, by + placing or removing symlinks in the + directory. This is particularly useful + to create configurations that deviate + from the suggested default + installation. In this case the + administrator must make sure to invoke + <command>daemon-reload</command> + manually as necessary, to ensure his + changes are taken into account.</para> + + <para>Enabling units should not be + confused with starting (activating) + units, as done by the + <command>start</command> + command. Enabling and starting units + is orthogonal: units may be enabled + without being started and started + without being enabled. Enabling simply + hooks the unit into various suggested + places (for example, so that the unit + is automatically started on boot or + when a particular kind of hardware is + plugged in). Starting actually spawns + the daemon process (in case of service + units), or binds the socket (in case + of socket units), and so + on.</para> + + <para>Depending on whether + <option>--system</option>, + <option>--user</option> or + <option>--global</option> is specified + this enables the unit for the system, + for the calling user only + or for all future logins of all + users. Note that in the latter case no + systemd daemon configuration is + reloaded.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>disable [NAME...]</command></term> + + <listitem><para>Disables one or more + units. This removes all symlinks to + the specified unit files from the unit + configuration directory, and hence + undoes the changes made by + <command>enable</command>. Note + however that this removes + all symlinks to the unit files + (i.e. including manual additions), not + just those actually created by + <command>enable</command>. This call + implicitly reloads the systemd daemon + configuration after completing the + disabling of the units. Note that this + command does not implicitly stop the + units that is being disabled. If this + is desired an additional + <command>stop</command>command should + be executed afterwards.</para> + + <para>This command will print the + actions executed. This output may be + suppressed by passing + <option>--quiet</option>.</para> + </listitem> + + <para>This command honors + <option>--system</option>, + <option>--user</option>, + <option>--global</option> in a similar + way as + <command>enable</command>.</para> + </varlistentry> + + <varlistentry> + <term><command>is-enabled [NAME...]</command></term> + + <listitem><para>Checks whether any of + the specified unit files is enabled + (as with + <command>enable</command>). Returns an + exit code of 0 if at least one is + enabled, non-zero otherwise. Prints + the current enable status. To suppress + this output use + <option>--quiet</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>reenable [NAME...]</command></term> + + <listitem><para>Reenable one or more + unit files, as specified on the + command line. This is a combination of + <command>disable</command> and + <command>enable</command> and is + useful to reset the symlinks a unit is + enabled with to the defaults + configured in the + <literal>[Install]</literal> section + of the unit file.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>preset [NAME...]</command></term> + + <listitem><para>Reset one or more unit + files, as specified on the command + line, to the defaults configured in a + preset file. This has the same effect + as <command>disable</command> or + <command>enable</command>, depending + how the unit is listed in the preset + files.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>mask [NAME...]</command></term> + + <listitem><para>Mask one or more unit + files, as specified on the command + line. This will link these units to + <filename>/dev/null</filename>, making + it impossible to start them. This is a stronger version + of <command>disable</command>, since + it prohibits all kinds of activation + of the unit, including manual + activation. Use this option with + care.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>unmask [NAME...]</command></term> + + <listitem><para>Unmask one or more + unit files, as specified on the + command line. This will undo the + effect of + <command>mask</command>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>link [NAME...]</command></term> + + <listitem><para>Link a unit file that + is not in the unit file search paths + into the unit file search path. This + requires an absolute path to a unit + file. The effect of this can be undone + with <command>disable</command>. The + effect of this command is that a unit + file is available for + <command>start</command> and other + commands although it isn't installed + directly in the unit search + path.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>load [NAME...]</command></term> + + <listitem><para>Load one or more units + specified on the command line. This + will simply load their configuration + from disk, but not start them. To + start them you need to use the + <command>start</command> command which + will implicitly load a unit that has + not been loaded yet. Note that systemd + garbage collects loaded units that are + not active or referenced by an active + unit. This means that units loaded + this way will usually not stay loaded + for long. Also note that this command + cannot be used to reload unit + configuration. Use the + <command>daemon-reload</command> + command for that. All in all, this + command is of little use except for + debugging.</para> + <para>This command should not be + confused with the + <command>daemon-reload</command> or + <command>reload</command> + commands.</para></listitem> + </varlistentry> + <varlistentry> + <term><command>list-jobs</command></term> + + <listitem><para>List jobs that are in progress.</para></listitem> + </varlistentry> + <varlistentry> + <term><command>cancel [JOB...]</command></term> + + <listitem><para>Cancel one or more + jobs specified on the command line by + their numeric job + IDs. If no job id is specified, cancel all pending jobs.</para></listitem> + </varlistentry> + <varlistentry> + <term><command>dump</command></term> + + <listitem><para>Dump server + status. This will output a (usually + very long) human readable manager + status dump. Its format is subject to + change without notice and should not + be parsed by + applications.</para></listitem> + </varlistentry> + <varlistentry> + <term><command>dot</command></term> + + <listitem><para>Generate textual + dependency graph description in dot + format for further processing with the + GraphViz + <citerefentry><refentrytitle>dot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + tool. Use a command line like + <command>systemctl dot | dot -Tsvg > + systemd.svg</command> to generate a + graphical dependency tree. Unless + <option>--order</option> or + <option>--require</option> is passed + the generated graph will show both + ordering and requirement + dependencies.</para></listitem> + </varlistentry> + <varlistentry> + <term><command>snapshot [NAME]</command></term> + + <listitem><para>Create a snapshot. If + a snapshot name is specified, the new + snapshot will be named after it. If + none is specified an automatic + snapshot name is generated. In either + case, the snapshot name used is + printed to STDOUT, unless + <option>--quiet</option> is + specified.</para> + + <para>A snapshot refers to a saved + state of the systemd manager. It is + implemented itself as a unit that is + generated dynamically with this + command and has dependencies on all + units active at the time. At a later + time the user may return to this state + by using the + <command>isolate</command> command on + the snapshot unit.</para></listitem> + + <para>Snapshots are only useful for + saving and restoring which units are + running or are stopped, they do not + save/restore any other + state. Snapshots are dynamic and lost + on reboot.</para> + </varlistentry> + <varlistentry> + <term><command>delete [NAME...]</command></term> + + <listitem><para>Remove a snapshot + previously created with + <command>snapshot</command>.</para></listitem> + </varlistentry> + <varlistentry> + <term><command>daemon-reload</command></term> + + <listitem><para>Reload systemd manager + configuration. This will reload all + unit files and recreate the entire + dependency tree. While the daemon is + reloaded, all sockets systemd listens + on on behalf of user configuration will + stay accessible.</para> <para>This + command should not be confused with + the <command>load</command> or + <command>reload</command> + commands.</para></listitem> + </varlistentry> + <varlistentry> + <term><command>daemon-reexec</command></term> + + <listitem><para>Reexecute the systemd + manager. This will serialize the + manager state, reexecute the process + and deserialize the state again. This + command is of little use except for + debugging and package + upgrades. Sometimes it might be + helpful as a heavy-weight + <command>daemon-reload</command>. While + the daemon is reexecuted all sockets + systemd listens on on behalf of user + configuration will stay + accessible.</para></listitem> + </varlistentry> + <varlistentry> + <term><command>show-environment</command></term> + + <listitem><para>Dump the systemd + manager environment block. The + environment block will be dumped in + straight-forward form suitable for + sourcing into a shell script. This + environment block will be passed to + all processes the manager + spawns.</para></listitem> + </varlistentry> + <varlistentry> + <term><command>set-environment [NAME=VALUE...]</command></term> + + <listitem><para>Set one or more + systemd manager environment variables, + as specified on the command + line.</para></listitem> + </varlistentry> + <varlistentry> + <term><command>unset-environment [NAME...]</command></term> + + <listitem><para>Unset one or more + systemd manager environment + variables. If only a variable name is + specified it will be removed + regardless of its value. If a variable + and a value are specified the variable + is only removed if it has the + specified value.</para></listitem> + </varlistentry> + <varlistentry> + <term><command>default</command></term> + + <listitem><para>Enter default + mode. This is mostly equivalent to + <command>start + default.target</command>.</para></listitem> + </varlistentry> + <varlistentry> + <term><command>rescue</command></term> + + <listitem><para>Enter rescue + mode. This is mostly equivalent to + <command>isolate + rescue.target</command> but also + prints a wall message to all + users.</para></listitem> + </varlistentry> + <varlistentry> + <term><command>emergency</command></term> + + <listitem><para>Enter emergency + mode. This is mostly equivalent to + <command>isolate + emergency.target</command> but also + prints a wall message to all + users.</para></listitem> + </varlistentry> + <varlistentry> + <term><command>halt</command></term> + + <listitem><para>Shut down and halt the + system. This is mostly equivalent to + <command>start halt.target</command> + but also prints a wall message to all + users. If combined with + <option>--force</option> shutdown of + all running services is skipped, + however all processes are killed and + all file systems are unmounted or + mounted read-only, immediately + followed by the system halt. If + <option>--force</option> is specified + twice the the operation is immediately + executed without terminating any + processes or unmounting any file + systems. This may result in data + loss.</para></listitem> + </varlistentry> + <varlistentry> + <term><command>poweroff</command></term> + + <listitem><para>Shut down and + power-off the system. This is mostly + equivalent to <command>start + poweroff.target</command> but also + prints a wall message to all users. If + combined with <option>--force</option> + shutdown of all running services is + skipped, however all processes are + killed and all file systems are + unmounted or mounted read-only, + immediately followed by the powering + off. If <option>--force</option> is + specified twice the the operation is + immediately executed without + terminating any processes or + unmounting any file systems. This may + result in data loss.</para></listitem> + </varlistentry> + <varlistentry> + <term><command>reboot</command></term> + + <listitem><para>Shut down and reboot + the system. This is mostly equivalent + to <command>start + reboot.target</command> but also + prints a wall message to all users. If + combined with <option>--force</option> + shutdown of all running services is + skipped, however all processes are + killed and all file systems are + unmounted or mounted read-only, + immediately followed by the reboot. If + <option>--force</option> is specified + twice the the operation is immediately + executed without terminating any + processes or unmounting any file + systems. This may result in data + loss.</para></listitem> + </varlistentry> + <varlistentry> + <term><command>kexec</command></term> + + <listitem><para>Shut down and reboot + the system via kexec. This is mostly + equivalent to <command>start + kexec.target</command> but also prints + a wall message to all users. If + combined with <option>--force</option> + shutdown of all running services is + skipped, however all processes are killed + and all file systems are unmounted or + mounted read-only, immediately + followed by the + reboot.</para></listitem> + </varlistentry> + <varlistentry> + <term><command>exit</command></term> + + <listitem><para>Ask the systemd + manager to quit. This is only + supported for user service managers + (i.e. in conjunction with the + <option>--user</option> option) and + will fail otherwise.</para></listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success 0 is returned, a non-zero failure + code otherwise.</para> + </refsect1> + + <refsect1> + <title>Environment</title> + + <variablelist> + <varlistentry> + <term><varname>$SYSTEMD_PAGER</varname></term> + <listitem><para>Pager to use when + <option>--no-pager</option> is not given; + overrides <varname>$PAGER</varname>. Setting + this to an empty string or the value + <literal>cat</literal> is equivalent to passing + <option>--no-pager</option>.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemadm</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-ask-password.xml b/man/systemd-ask-password.xml new file mode 100644 index 000000000..c607b1a36 --- /dev/null +++ b/man/systemd-ask-password.xml @@ -0,0 +1,183 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2011 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd-ask-password"> + + <refentryinfo> + <title>systemd-ask-password</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-ask-password</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-ask-password</refname> + <refpurpose>Query the user for a system password</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-ask-password <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt">MESSAGE</arg></command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-ask-password</command> may be + used to query a system password or passphrase from the + user, using a question message specified on the + command line. When run from a TTY it will query a + password on the TTY and print it to STDOUT. When run + with no TTY or with <option>--no-tty</option> it will + query the password system-wide and allow active users + to respond via several agents. The latter is + only available to privileged processes.</para> + + <para>The purpose of this tool is to query system-wide + passwords -- that is passwords not attached to a + specific user account. Examples include: unlocking + encrypted hard disks when they are plugged in or at + boot, entering an SSL certificate passphrase for web + and VPN servers.</para> + + <para>Existing agents are: a boot-time password agent + asking the user for passwords using Plymouth; a + boot-time password agent querying the user directly on + the console; an agent requesting password input via a + <citerefentry><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry> + message; an agent suitable for running in a GNOME + session; a command line agent which can be started + temporarily to process queued password requests; a TTY + agent that is temporarily spawned during + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + invocations.</para> + + <para>Additional password agents may be implemented + according to the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/PasswordAgents">systemd + Password Agent Specification</ulink>.</para> + + <para>If a password is queried on a tty the user may + press TAB to hide the asterisks normally shown for + each character typed. Pressing Backspace as first key + achieves the same effect.</para> + + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--h</option></term> + <term><option>--help</option></term> + + <listitem><para>Prints a short help + text and exits.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--icon=</option></term> + + <listitem><para>Specify an icon name + alongside the password query, which may + be used in all agents supporting + graphical display. The icon name + should follow the <ulink + url="http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">XDG + Icon Naming + Specification</ulink>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--timeout=</option></term> + + <listitem><para>Specify the query + timeout in seconds. Defaults to + 90s.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--no-tty</option></term> + + <listitem><para>Never ask for password + on current TTY even if one is + available. Always use agent + system.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--accept-cached</option></term> + + <listitem><para>If passed accept + cached passwords, i.e. passwords + previously typed in.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--multiple</option></term> + + <listitem><para>When used in + conjunction with + <option>--accept-cached</option> + accept multiple passwords. This will + output one password per + line.</para></listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success 0 is returned, a non-zero failure + code otherwise.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-cat.xml b/man/systemd-cat.xml new file mode 100644 index 000000000..350a345d4 --- /dev/null +++ b/man/systemd-cat.xml @@ -0,0 +1,205 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2012 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd-cat"> + + <refentryinfo> + <title>systemd-cat</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-cat</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-cat</refname> + <refpurpose>Connect a pipeline or program's output with the journal</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-cat <arg choice="opt" rep="repeat">OPTIONS</arg> <arg>COMMAND</arg> <arg choice="opt" rep="repeat">ARGUMENTS</arg></command> + </cmdsynopsis> + <cmdsynopsis> + <command>systemd-cat <arg choice="opt" rep="repeat">OPTIONS</arg></command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-cat</command> may be used to + connect STDOUT and STDERR of a process with the + journal, or as a filter tool in a shell pipeline to + pass the output the previous pipeline element + generates to the journal.</para> + + <para>If no parameter is passed + <command>systemd-cat</command> will write + everything it reads from standard input (STDIN) to the journal.</para> + + <para>If parameters are passed they are executed as + command line with standard output (STDOUT) and standard + error output (STDERR) connected to the journal, so + that all it writes is stored in the journal.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--h</option></term> + <term><option>--help</option></term> + + <listitem><para>Prints a short help + text and exits.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--version</option></term> + + <listitem><para>Prints a short version + string and exits.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-t</option></term> + <term><option>--identifier=</option></term> + + <listitem><para>Specify a short string + that is used to identify the logging + tool. If not specified no identifying + string is written to the journal.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-p</option></term> + <term><option>--priority=</option></term> + + <listitem><para>Specify the default + priority level for the logged + messages. Pass one of + <literal>emerg</literal>, + <literal>alert</literal>, + <literal>crit</literal>, + <literal>err</literal>, + <literal>warning</literal>, + <literal>notice</literal>, + <literal>info</literal>, + <literal>debug</literal>, resp. a + value between 0 and 7 (corresponding + to the same named levels). These + priority values are the same as + defined by + <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Defaults + to <literal>info</literal>. Note that + this simply controls the default, + individual lines may be logged with + different levels if they are prefixed + accordingly. For details see + <option>--level-prefix=</option> + below.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--level-prefix=</option></term> + + <listitem><para>Controls whether lines + read are parsed for syslog priority + level prefixes. If enabled (the + default) a line prefixed with a + priority prefix such as + <literal><5></literal> is logged + at priority 5 + (<literal>notice</literal>), and + similar for the other priority + levels. Takes a boolean + argument.</para></listitem> + </varlistentry> + + </variablelist> + + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success 0 is returned, a non-zero failure + code otherwise.</para> + </refsect1> + + <refsect1> + <title>Examples</title> + + <example> + <title>Invoke a program</title> + + <para>This calls <filename>/bin/ls</filename> + with STDOUT/STDERR connected to the + journal:</para> + + <programlisting># systemd-cat ls</programlisting> + </example> + + <example> + <title>Usage in a shell pipeline</title> + + <para>This builds a shell pipeline also + invoking <filename>/bin/ls</filename> and + writes the output it generates to the + journal:</para> + + <programlisting># ls | systemd-cat</programlisting> + </example> + + <para>Even though the two examples have very similar + effects the first is preferable since only one process + is running at a time, and both STDOUT and STDERR are + captured while in the second example only STDOUT is + captured.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>logger</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-cgls.xml b/man/systemd-cgls.xml new file mode 100644 index 000000000..1e53147e1 --- /dev/null +++ b/man/systemd-cgls.xml @@ -0,0 +1,123 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd-cgls"> + + <refentryinfo> + <title>systemd-cgls</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-cgls</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-cgls</refname> + <refpurpose>Recursively show control group contents</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-cgls <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt" rep="repeat">CGROUP</arg></command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-cgls</command> recursively + shows the contents of the selected Linux control group + hierarchy in a tree. If arguments are specified shows + all member processes of the specified control groups + plus all their subgroups and their members. The + control groups may either be specified by their full + file paths or are assumed in the systemd control group + hierarchy. If no argument is specified and the current + working directory is beneath the control group mount + point <filename>/sys/fs/cgroup</filename> shows the contents + of the control group the working directory refers + to. Otherwise the full systemd control group hierarchy + is shown.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>-h</option></term> + <term><option>--help</option></term> + + <listitem><para>Prints a short help + text and exits.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--no-pager</option></term> + + <listitem><para>Do not pipe output into a + pager.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-k</option></term> + + <listitem><para>Include kernel + threads in output.</para></listitem> + </varlistentry> + + </variablelist> + + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success 0 is returned, a non-zero failure + code otherwise.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-cgtop</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-cgtop.xml b/man/systemd-cgtop.xml new file mode 100644 index 000000000..2d67ae5ef --- /dev/null +++ b/man/systemd-cgtop.xml @@ -0,0 +1,246 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2012 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd-cgtop"> + + <refentryinfo> + <title>systemd-cgtop</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-cgtop</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-cgtop</refname> + <refpurpose>Show top control groups by their resource usage</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-cgtop <arg choice="opt" rep="repeat">OPTIONS</arg></command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-cgtop</command> shows the top + control groups of the local Linux control group + hierarchy, ordered by their CPU, memory and disk I/O load. The + display is refreshed in regular intervals (by default + every 1s), similar in style to + <citerefentry><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> + + <para>Resource usage is only accounted for control + groups in the relevant hierarchy, i.e. CPU usage is + only accounted for control groups in the + <literal>cpuacct</literal> hierarchy, memory usage + only for those in <literal>memory</literal> and disk + I/O usage for those in + <literal>blkio</literal>. <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + by default places all services in their own control + group in the <literal>cpuacct</literal> hierarchy, but + not in <literal>memory</literal> nor + <literal>blkio</literal>. If resource monitoring for + these resources is required it is recommended to add + <literal>blkio</literal> and <literal>memory</literal> + to the <varname>DefaultControllers=</varname> setting + in <filename>/etc/systemd/system.conf</filename> (see + <citerefentry><refentrytitle>systemd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details). Alternatively, it is possible to enable + resource accounting individually for services, by + making use of the <varname>ControlGroup=</varname> + option in the unit files (See + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details).</para> + + <para>To emphasize this: unless + <literal>blkio</literal> and <literal>memory</literal> + are enabled for the services in question with either + of the options suggested above no resource accounting + will be available for system services and the data shown + by <command>systemd-cgtop</command> will be + incomplete.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>-h</option></term> + <term><option>--help</option></term> + + <listitem><para>Prints a short help + text and exits.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-p</option></term> + + <listitem><para>Order by control group + path name.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-t</option></term> + + <listitem><para>Order by number of + tasks in control + group (i.e. threads and processes).</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-c</option></term> + + <listitem><para>Order by CPU load.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-m</option></term> + + <listitem><para>Order by memory usage.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-i</option></term> + + <listitem><para>Order by disk I/O load.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-d</option></term> + <term><option>--delay=</option></term> + + <listitem><para>Specify refresh delay + in seconds (or if one of + <literal>ms</literal>, + <literal>us</literal>, + <literal>min</literal> is specified as + unit in this time + unit).</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--depth=</option></term> + + <listitem><para>Maximum control group + tree traversal depth. Specifies how + deep <command>systemd-cgtop</command> + shall traverse the control group + hierarchies. If 0 is specified only + the root group is monitored, for 1 + only the first level of control groups + is monitored, and so on. Defaults to + 2.</para></listitem> + </varlistentry> + + </variablelist> + + </refsect1> + + + <refsect1> + <title>Keys</title> + + <para><command>systemd-cgtop</command> is an + interactive tool and may be controlled via user input + using the following keys:</para> + + <variablelist> + <varlistentry> + <term>h</term> + + <listitem><para>Shows a short help text.</para></listitem> + </varlistentry> + + <varlistentry> + <term>SPACE</term> + + <listitem><para>Immediately refresh output.</para></listitem> + </varlistentry> + + <varlistentry> + <term>q</term> + + <listitem><para>Terminate the program.</para></listitem> + </varlistentry> + + + <varlistentry> + <term>p</term> + <term>t</term> + <term>c</term> + <term>m</term> + <term>i</term> + + <listitem><para>Change ordering of control groups + by path, number of tasks, CPU load, + memory usage resp. IO + load.</para></listitem> + </varlistentry> + + <varlistentry> + <term>+</term> + <term>-</term> + + <listitem><para>Increase, + resp. decrease refresh + delay.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success 0 is returned, a non-zero failure + code otherwise.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-cgls</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-machine-id-setup.xml b/man/systemd-machine-id-setup.xml new file mode 100644 index 000000000..49b92f689 --- /dev/null +++ b/man/systemd-machine-id-setup.xml @@ -0,0 +1,114 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2012 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd-machine-id-setup"> + + <refentryinfo> + <title>systemd-machine-id-setup</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-machine-id-setup</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-machine-id-setup</refname> + <refpurpose>Initialize the machine ID in <filename>/etc/machine-id</filename></refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-machine-id-setup</command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-machine-id-setup</command> may + be used by system installer tools to initialize the + machine ID stored in + <filename>/etc/machine-id</filename> at install time + with a randomly generated ID. See + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information about this file.</para> + + <para>This tool will execute no operation if + <filename>/etc/machine-id</filename> is already + initialized.</para> + + <para>If a valid D-Bus machine ID is already + configured for the system the D-Bus machine ID is + copied and used to initialize the machine ID in + <filename>/etc/machine-id</filename>.</para> + + <para>If run inside a KVM virtual machine and a UUID + is passed via the <option>-uuid</option> option this + UUID is used to initialize the machine ID instead of a + randomly generated one. The caller must ensure that the + UUID passed is sufficiently unique and is different + for every booted instanced of the VM.</para> + + <para>Similar, if run inside a Linux container + environment and a UUID is set for the container this + is used to initialize the machine ID. For details see + the documentation of the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container + Interface</ulink>.</para> + + </refsect1> + + <refsect1> + <title>Options</title> + + <para>This tool does not take any options or arguments.</para> + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success 0 is returned, a non-zero failure + code otherwise.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>dbus-uuidgen</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-notify.xml b/man/systemd-notify.xml new file mode 100644 index 000000000..c5ffafe89 --- /dev/null +++ b/man/systemd-notify.xml @@ -0,0 +1,218 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd-notify"> + + <refentryinfo> + <title>systemd-notify</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-notify</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-notify</refname> + <refpurpose>Notify init system about start-up completion and other daemon status changes</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-notify <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt" rep="repeat">VARIABLE=VALUE</arg></command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-notify</command> may be + called by daemon scripts to notify the init system + about status changes. It can be used to send arbitrary + information, encoded in an environment-block-like list + of strings. Most importantly it can be used for + start-up completion notification.</para> + + <para>This is mostly just a wrapper around + <function>sd_notify()</function> and makes this + functionality available to shell scripts. For details + see + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + + <para>The command line may carry a list of + environment variables to send as part of the status + update.</para> + + <para>Note that systemd will refuse reception of + status updates from this command unless + <varname>NotifyAccess=all</varname> is set for the + service unit this command is called from.</para> + + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--h</option></term> + <term><option>--help</option></term> + + <listitem><para>Prints a short help + text and exits.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--version</option></term> + + <listitem><para>Prints a short version + string and exits.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--ready</option></term> + + <listitem><para>Inform the init system + about service start-up + completion. This is equivalent to + <command>systemd-notify + READY=1</command>. For details about + the semantics of this option see + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--pid=</option></term> + + <listitem><para>Inform the init system + about the main PID of the + daemon. Takes a PID as argument. If + the argument is omitted the PID of the + process that invoked + <command>systemd-notify</command> is + used. This is equivalent to + <command>systemd-notify + MAINPID=$PID</command>. For details + about the semantics of this option see + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--status=</option></term> + + <listitem><para>Send a free-form + status string for the daemon to the + init systemd. This option takes the + status string as argument. This is + equivalent to <command>systemd-notify + STATUS=...</command>. For details + about the semantics of this option see + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--booted</option></term> + + <listitem><para>Returns 0 if the + system was booted up with systemd, + non-zero otherwise. If this option is + passed no message is sent. This option + is hence unrelated to the other + options. For details about the + semantics of this option see + <citerefentry><refentrytitle>sd_booted</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--readahead=</option></term> + + <listitem><para>Controls disk + read-ahead operations. The argument + must be a string, and either "cancel", + "done" or "noreplay". For details + about the semantics of this option see + <citerefentry><refentrytitle>sd_readahead</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success 0 is returned, a non-zero failure + code otherwise.</para> + </refsect1> + + <refsect1> + <title>Example</title> + + <example> + <title>Start-up Notification and Status Updates</title> + + <para>A simple shell daemon that sends + start-up notifications after having set up its + communication channel. During runtime it sends + further status updates to the init + system:</para> + + <programlisting>#!/bin/bash + +mkfifo /tmp/waldo +systemd-notify --ready --status="Waiting for data..." + +while : ; do + read a < /tmp/waldo + systemd-notify --status="Processing $a" + + # Do something with $a ... + + systemd-notify --status="Waiting for data..." +done</programlisting> + </example> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_booted</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml new file mode 100644 index 000000000..dbd2ff5a8 --- /dev/null +++ b/man/systemd-nspawn.xml @@ -0,0 +1,215 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd-nspawn"> + + <refentryinfo> + <title>systemd-nspawn</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-nspawn</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-nspawn</refname> + <refpurpose>Spawn a namespace container for debugging, testing and building</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-nspawn <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt">COMMAND</arg> <arg choice="opt" rep="repeat">ARGS</arg></command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-nspawn</command> may be used to + run a command or OS in a light-weight namespace + container. In many ways it is similar to + <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + but more powerful since it fully virtualizes the file + system hierarchy, as well as the process tree, the + various IPC subsystems and the host and domain + name.</para> + + <para><command>systemd-nspawn</command> limits access + to various kernel interfaces in the container to + read-only, such as <filename>/sys</filename>, + <filename>/proc/sys</filename> or + <filename>/sys/fs/selinux</filename>. Network + interfaces and the system clock may not be changed + from within the container. Device nodes may not be + created. The host system cannot be rebooted and kernel + modules may not be loaded from within the + container.</para> + + <para>Note that even though these security precautions + are taken <command>systemd-nspawn</command> is not + suitable for secure container setups. Many of the + security features may be circumvented and are hence + primarily useful to avoid accidental changes to the + host system from the container. The intended use of + this program is debugging and testing as well as + building of packages, distributions and software + involved with boot and systems management.</para> + + <para>In contrast to + <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + <command>systemd-nspawn</command> may be used to boot + full Linux-based operating systems in a + container.</para> + + <para>Use a tool like + <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry> or <citerefentry><refentrytitle>mock</refentrytitle><manvolnum>1</manvolnum></citerefentry> + to set up an OS directory tree suitable as file system + hierarchy for <command>systemd-nspawn</command> containers.</para> + + <para>Note that <command>systemd-nspawn</command> will + mount file systems private to the container to + <filename>/dev</filename>, + <filename>/run</filename> and similar. These will + not be visible outside of the container, and their + contents will be lost when the container exits.</para> + + <para>Note that running two + <command>systemd-nspawn</command> containers from the + same directory tree will not make processes in them + see each other. The PID namespace separation of the + two containers is complete and the containers will + share very few runtime objects except for the + underlying file system.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>If no arguments are passed the container is set + up and a shell started in it, otherwise the passed + command and arguments are executed in it. The + following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--help</option></term> + <term><option>-h</option></term> + + <listitem><para>Prints a short help + text and exits.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--directory=</option></term> + <term><option>-D</option></term> + + <listitem><para>Directory to use as + file system root for the namespace + container. If omitted the current + directory will be + used.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--user=</option></term> + <term><option>-u</option></term> + + <listitem><para>Run the command + under specified user, create home + directory and cd into it. As rest + of systemd-nspawn, this is not + the security feature and limits + against accidental changes only. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--private-network</option></term> + + <listitem><para>Turn off networking in + the container. This makes all network + interfaces unavailable in the + container, with the exception of the + loopback device.</para></listitem> + </varlistentry> + + </variablelist> + + </refsect1> + + <refsect1> + <title>Example 1</title> + + <programlisting># debootstrap --arch=amd64 unstable debian-tree/ +# systemd-nspawn -D debian-tree/</programlisting> + + <para>This installs a minimal Debian unstable + distribution into the directory + <filename>debian-tree/</filename> and then spawns a + shell in a namespace container in it.</para> + + </refsect1> + + <refsect1> + <title>Example 2</title> + + <programlisting># mock --init +# systemd-nspawn -D /var/lib/mock/fedora-rawhide-x86_64/root/ /sbin/init systemd.log_level=debug</programlisting> + + <para>This installs a minimal Fedora distribution into + a subdirectory of <filename>/var/lib/mock/</filename> + and then boots an OS in a namespace container in it, + with systemd as init system, configured for debug + logging.</para> + + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>The exit code of the program executed in the + container is returned.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>mock</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-tmpfiles.xml b/man/systemd-tmpfiles.xml new file mode 100644 index 000000000..bbb80b2f9 --- /dev/null +++ b/man/systemd-tmpfiles.xml @@ -0,0 +1,152 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd-tmpfiles"> + + <refentryinfo> + <title>systemd-tmpfiles</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-tmpfiles</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-tmpfiles</refname> + <refpurpose>Creates, deletes and cleans up volatile + and temporary files and directories.</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-tmpfiles <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt" rep="repeat">CONFIGURATION FILE</arg></command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-tmpfiles</command> creates, + deletes and cleans up volatile and temporary files and + directories, based on the configuration from + <filename>/etc/tmpfiles.d/</filename>. See + <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more details on these files.</para> + + <para>If invoked with no arguments applies all + directives from all configuration files in + <filename>/etc/tmpfiles.d/*.conf</filename>. If one or + more absolute file names are passed on the command + line only the directives in these files are + applied.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + + <varlistentry> + <term><option>--create</option></term> + <listitem><para>If this option is passed all + files and directories marked with f, + F, d, D in the configuration files are + created. Files and directories marked with z, + Z have their ownership, access mode and security + labels set.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--clean</option></term> + <listitem><para>If this option is + passed all files and directories with + an age parameter configured will be + cleaned up.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--remove</option></term> + <listitem><para>If this option is + passed all files and directories marked + with r, R in the configuration files + are removed.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--prefix=PATH</option></term> + <listitem><para>Only apply rules that + apply to paths with the specified + prefix.</para></listitem> + </varlistentry> + + + <varlistentry> + <term><option>--help</option></term> + + <listitem><para>Prints a short help + text and exits.</para></listitem> + </varlistentry> + + </variablelist> + + <para>It is possible to combine + <option>--create</option>, <option>--clean</option>, + and <option>--remove</option> in one invocation. For + example, during boot the following command line is + executed to ensure that all temporary and volatile + directories are removed and created according to the + configuration file:</para> + + <programlisting>systemd-tmpfiles --remove --create</programlisting> + + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success 0 is returned, a non-zero failure + code otherwise.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>tmpwatch</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd.automount.xml b/man/systemd.automount.xml new file mode 100644 index 000000000..754d1e37f --- /dev/null +++ b/man/systemd.automount.xml @@ -0,0 +1,167 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.automount"> + <refentryinfo> + <title>systemd.automount</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.automount</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.automount</refname> + <refpurpose>systemd automount configuration files</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd.automount</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>A unit configuration file whose name ends in + <filename>.automount</filename> encodes information + about a file system automount point controlled and + supervised by systemd.</para> + + <para>This man page lists the configuration options + specific to this unit type. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the common options of all unit configuration + files. The common configuration items are configured + in the generic [Unit] and [Install] sections. The + automount specific configuration options are configured + in the [Automount] section.</para> + + <para>Automount units must be named after the + automount directories they control. Example: the + automount point <filename>/home/lennart</filename> + must be configured in a unit file + <filename>home-lennart.automount</filename>. For + details about the escaping logic used to convert a + file system path to a unit name see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + + <para>For each automount unit file a matching mount + unit file (see + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details) must exist which is activated when the + automount path is accessed. Example: if an automount + unit <filename>home-lennart.automount</filename> is + active and the user accesses + <filename>/home/lennart</filename> the mount unit + <filename>home-lennart.mount</filename> will be + activated.</para> + + <para>Automount units may be used to implement + on-demand mounting as well as parallelized mounting of + file systems.</para> + + <para>If an automount point is beneath another mount + point in the file system hierarchy a dependency + between both units is created automatically.</para> + </refsect1> + + <refsect1> + <title><filename>fstab</filename></title> + + <para>Automount units may either be configured via unit + files, or via <filename>/etc/fstab</filename> (see + <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details).</para> + + <para>For details how systemd parses + <filename>/etc/fstab</filename> see + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + + <para>If an automount point is configured in both + <filename>/etc/fstab</filename> and a unit file the + configuration in the latter takes precedence.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>Automount files must include an [Automount] + section, which carries information about the file + system automount points it supervises. The options + specific to the [Automount] section of automount units + are the following:</para> + + <variablelist> + + <varlistentry> + <term><varname>Where=</varname></term> + <listitem><para>Takes an absolute path + of a directory of the automount + point. If the automount point is not + existing at time of the automount + point is installed it is created. This + string must be reflected in the unit + file name. (See above.) This option is + mandatory.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DirectoryMode=</varname></term> + <listitem><para>Directories of + automount points (and any parent + directories) are automatically created + if needed. This option specifies the + file system access mode used when + creating these directories. Takes an + access mode in octal + notation. Defaults to + 0755.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>automount</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd.conf.xml b/man/systemd.conf.xml new file mode 100644 index 000000000..ba144da8c --- /dev/null +++ b/man/systemd.conf.xml @@ -0,0 +1,162 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.conf"> + <refentryinfo> + <title>systemd.conf</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.conf</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.conf</refname> + <refpurpose>systemd manager configuration file</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>system.conf</filename></para> + <para><filename>user.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>When run as system instance systemd reads the + configuration file <filename>system.conf</filename>, + otherwise <filename>user.conf</filename>. These + configuration files contain a few settings controlling + basic manager operations.</para> + + </refsect1> + + <refsect1> + <title>Options</title> + + <para>All options are configured in the + <literal>[Manager]</literal> section:</para> + + <variablelist> + + <varlistentry> + <term><varname>LogLevel=</varname></term> + <term><varname>LogTarget=</varname></term> + <term><varname>LogColor=</varname></term> + <term><varname>LogLocation=</varname></term> + <term><varname>DumpCore=yes</varname></term> + <term><varname>CrashShell=no</varname></term> + <term><varname>ShowStatus=yes</varname></term> + <term><varname>SysVConsole=yes</varname></term> + <term><varname>CrashChVT=1</varname></term> + <term><varname>DefaultStandardOutput=journal</varname></term> + <term><varname>DefaultStandardError=inherit</varname></term> + + <listitem><para>Configures various + parameters of basic manager + operation. These options may be + overridden by the respective command + line arguments. See + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for details about these command line + arguments.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>CPUAffinity=</varname></term> + + <listitem><para>Configures the initial + CPU affinity for the init + process. Takes a space-separated list + of CPU indexes.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>MountAuto=yes</varname></term> + <term><varname>SwapAuto=yes</varname></term> + + <listitem><para>Configures whether + systemd should automatically activate + all swap or mounts listed in + <filename>/etc/fstab</filename>, or + whether this job is left to some other + system script.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DefaultControllers=cpu</varname></term> + + <listitem><para>Configures in which + cgroup controller hierarchies to + create per-service cgroups + automatically, in addition to the + name=systemd named hierarchy. Defaults + to 'cpu'. Takes a space separated list + of controller names. Pass an empty + string to ensure that systemd does not + touch any hierarchies but its + own.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>JoinControllers=cpu,cpuacct</varname></term> + + <listitem><para>Configures controllers + that shall be mounted in a single + hierarchy. By default systemd will + mount all controllers which are + enabled in the kernel in individual + hierachies, with the exception of + those listed in this setting. Takes a + space separated list of comma + separated controller names, in order + to allow multiple joined + hierarchies. Defaults to + 'cpu,cpuacct'. Pass an empty string to + ensure that systemd mounts all + controllers in separate + hierarchies.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd.device.xml b/man/systemd.device.xml new file mode 100644 index 000000000..63863bebd --- /dev/null +++ b/man/systemd.device.xml @@ -0,0 +1,168 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.device"> + <refentryinfo> + <title>systemd.device</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.device</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.device</refname> + <refpurpose>systemd device configuration files</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd.device</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>A unit configuration file whose name ends in + <filename>.device</filename> encodes information about + a device unit as exposed in the + sysfs/<citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry> + device tree.</para> + + <para>This unit type has no specific options. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the common options of all unit configuration + files. The common configuration items are configured + in the generic <literal>[Unit]</literal> and + <literal>[Install]</literal> sections. A separate + <literal>[Device]</literal> section does not exist, + since no device-specific options may be + configured.</para> + + <para>systemd will automatically create dynamic 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). This may be used to define + dependencies between devices and other + units.</para> + + <para>Device units are named after the + <filename>/sys</filename> and + <filename>/dev</filename> paths they control. Example: + the device <filename>/dev/sda5</filename> is exposed + in systemd as <filename>dev-sda5.device</filename>. For + details about the escaping logic used to convert a + file system path to a unit name see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + + </refsect1> + + <refsect1> + <title>The udev Database</title> + + <para>The settings of device units may either be + configured via unit files, or directly from the udev + database (which is recommended). The following udev + properties are understood by systemd:</para> + + <variablelist> + <varlistentry> + <term><varname>SYSTEMD_WANTS=</varname></term> + <listitem><para>Adds dependencies of + type <varname>Wants</varname> from + this unit to all listed units. This + may be used to activate arbitrary + units, when a specific device becomes + available. Note that this and the + other tags are not taken into account + unless the device is tagged with the + "<literal>systemd</literal>" string in + the udev database, because otherwise + the device is not exposed as systemd + unit.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SYSTEMD_ALIAS=</varname></term> + <listitem><para>Adds an additional + alias name to the device unit. This + must be an absolute path that is + automatically transformed into a unit + name. (See above.)</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SYSTEMD_READY=</varname></term> + <listitem><para>If set to 0 systemd + will consider this device unplugged + even if it shows up in the udev + tree. If this property is unset or set + to 1 the device will be considered + plugged the moment it shows up in the + udev tree. This property has no + influence on the behaviour when a + device disappears from the udev + tree. This option is useful to support + devices that initially show up in an + uninitialized state in the tree, and for + which a changed event is generated the + moment they are fully set + up.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ID_MODEL_FROM_DATABASE=</varname></term> + <term><varname>ID_MODEL=</varname></term> + + <listitem><para>If set, this property is + used as description string for the + device unit.</para></listitem> + </varlistentry> + + </variablelist> + + + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml new file mode 100644 index 000000000..e6f49c9fd --- /dev/null +++ b/man/systemd.exec.xml @@ -0,0 +1,1106 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.exec"> + <refentryinfo> + <title>systemd.exec</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.exec</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.exec</refname> + <refpurpose>systemd execution environment configuration</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd.service</filename>, + <filename>systemd.socket</filename>, + <filename>systemd.mount</filename>, + <filename>systemd.swap</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>Unit configuration files for services, sockets, + mount points and swap devices share a subset of + configuration options which define the execution + environment of spawned processes.</para> + + <para>This man page lists the configuration options + shared by these four unit types. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the common options of all unit configuration + files, and + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information on the specific unit + configuration files. The execution specific + configuration options are configured in the [Service], + [Socket], [Mount] resp. [Swap] section, depending on the unit + type.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <variablelist> + + <varlistentry> + <term><varname>WorkingDirectory=</varname></term> + + <listitem><para>Takes an absolute + directory path. Sets the working + directory for executed + processes.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RootDirectory=</varname></term> + + <listitem><para>Takes an absolute + directory path. Sets the root + directory for executed processes, with + the + <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>2</manvolnum></citerefentry> + system call. If this is used it must + be ensured that the process and all + its auxiliary files are available in + the <function>chroot()</function> + jail.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>User=</varname></term> + <term><varname>Group=</varname></term> + + <listitem><para>Sets the Unix user + resp. group the processes are executed + as. Takes a single user resp. group + name or ID as argument. If no group is + set the default group of the user is + chosen.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SupplementaryGroups=</varname></term> + + <listitem><para>Sets the supplementary + Unix groups the processes are executed + as. This takes a space separated list + of group names or IDs. This option may + be specified more than once in which + case all listed groups are set as + supplementary groups. This option does + not override but extends the list of + supplementary groups configured in the + system group database for the + user.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Nice=</varname></term> + + <listitem><para>Sets the default nice + level (scheduling priority) for + executed processes. Takes an integer + between -20 (highest priority) and 19 + (lowest priority). See + <citerefentry><refentrytitle>setpriority</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>OOMScoreAdjust=</varname></term> + + <listitem><para>Sets the adjustment + level for the Out-Of-Memory killer for + executed processes. Takes an integer + between -1000 (to disable OOM killing + for this process) and 1000 (to make + killing of this process under memory + pressure very likely). See <ulink + url="http://www.kernel.org/doc/Documentation/filesystems/proc.txt">proc.txt</ulink> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>IOSchedulingClass=</varname></term> + + <listitem><para>Sets the IO scheduling + class for executed processes. Takes an + integer between 0 and 3 or one of the + strings <option>none</option>, + <option>realtime</option>, + <option>best-effort</option> or + <option>idle</option>. See + <citerefentry><refentrytitle>ioprio_set</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>IOSchedulingPriority=</varname></term> + + <listitem><para>Sets the IO scheduling + priority for executed processes. Takes + an integer between 0 (highest + priority) and 7 (lowest priority). The + available priorities depend on the + selected IO scheduling class (see + above). See + <citerefentry><refentrytitle>ioprio_set</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>CPUSchedulingPolicy=</varname></term> + + <listitem><para>Sets the CPU + scheduling policy for executed + processes. Takes one of + <option>other</option>, + <option>batch</option>, + <option>idle</option>, + <option>fifo</option> or + <option>rr</option>. See + <citerefentry><refentrytitle>sched_setscheduler</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>CPUSchedulingPriority=</varname></term> + + <listitem><para>Sets the CPU + scheduling priority for executed + processes. Takes an integer between 1 + (lowest priority) and 99 (highest + priority). The available priority + range depends on the selected CPU + scheduling policy (see above). See + <citerefentry><refentrytitle>sched_setscheduler</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>CPUSchedulingResetOnFork=</varname></term> + + <listitem><para>Takes a boolean + argument. If true elevated CPU + scheduling priorities and policies + will be reset when the executed + processes fork, and can hence not leak + into child processes. See + <citerefentry><refentrytitle>sched_setscheduler</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details. Defaults to false.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>CPUAffinity=</varname></term> + + <listitem><para>Controls the CPU + affinity of the executed + processes. Takes a space-separated + list of CPU indexes. See + <citerefentry><refentrytitle>sched_setaffinity</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>UMask=</varname></term> + + <listitem><para>Controls the file mode + creation mask. Takes an access mode in + octal notation. See + <citerefentry><refentrytitle>umask</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details. Defaults to + 0022.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Environment=</varname></term> + + <listitem><para>Sets environment + variables for executed + processes. Takes a space-separated + list of variable assignments. This + option may be specified more than once + in which case all listed variables + will be set. If the same variable is + set twice the later setting will + override the earlier setting. See + <citerefentry><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>EnvironmentFile=</varname></term> + <listitem><para>Similar to + <varname>Environment=</varname> 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 + parser strips leading and + trailing whitespace from the values + of assignments, unless you use + double quotes ("). + The + argument passed should be an absolute + file name, 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. The files listed with this + directive will be read shortly before + the process is executed. Settings from + these files override settings made + with + <varname>Environment=</varname>. If + the same variable is set twice from + these files the files will be read in + the order they are specified and the + later setting will override the + earlier setting. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>StandardInput=</varname></term> + <listitem><para>Controls where file + descriptor 0 (STDIN) of the executed + processes is connected to. Takes one + of <option>null</option>, + <option>tty</option>, + <option>tty-force</option>, + <option>tty-fail</option> or + <option>socket</option>. If + <option>null</option> is selected + standard input will be connected to + <filename>/dev/null</filename>, + i.e. all read attempts by the process + will result in immediate EOF. If + <option>tty</option> is selected + standard input is connected to a TTY + (as configured by + <varname>TTYPath=</varname>, see + below) and the executed process + becomes the controlling process of the + terminal. If the terminal is already + being controlled by another process the + executed process waits until the current + controlling process releases the + terminal. + <option>tty-force</option> + is similar to <option>tty</option>, + but the executed process is forcefully + and immediately made the controlling + process of the terminal, potentially + removing previous controlling + processes from the + terminal. <option>tty-fail</option> is + similar to <option>tty</option> but if + the terminal already has a controlling + process start-up of the executed + process fails. The + <option>socket</option> option is only + valid in socket-activated services, + and only when the socket configuration + file (see + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details) specifies a single socket + only. If this option is set standard + input will be connected to the socket + the service was activated from, which + is primarily useful for compatibility + with daemons designed for use with the + traditional + <citerefentry><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry> + daemon. This setting defaults to + <option>null</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>StandardOutput=</varname></term> + <listitem><para>Controls where file + descriptor 1 (STDOUT) of the executed + processes is connected to. Takes one + of <option>inherit</option>, + <option>null</option>, + <option>tty</option>, + <option>syslog</option>, + <option>kmsg</option>, + <option>journal</option>, + <option>syslog+console</option>, + <option>kmsg+console</option>, + <option>journal+console</option> or + <option>socket</option>. If set to + <option>inherit</option> the file + descriptor of standard input is + duplicated for standard output. If set + to <option>null</option> standard + output will be connected to + <filename>/dev/null</filename>, + i.e. everything written to it will be + lost. If set to <option>tty</option> + standard output will be connected to a + tty (as configured via + <varname>TTYPath=</varname>, see + below). If the TTY is used for output + only the executed process will not + become the controlling process of the + terminal, and will not fail or wait + for other processes to release the + terminal. <option>syslog</option> + connects standard output to the + <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> + system syslog + service. <option>kmsg</option> + connects it with the kernel log buffer + which is accessible via + <citerefentry><refentrytitle>dmesg</refentrytitle><manvolnum>1</manvolnum></citerefentry>. <option>journal</option> + connects it with the journal which is + accessible via + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + (Note that everything that is written + to syslog or kmsg is implicitly stored + in the journal as well, those options + are hence supersets of this + one). <option>syslog+console</option>, + <option>journal+console</option> and + <option>kmsg+console</option> work + similarly but copy the output to the + system console as + well. <option>socket</option> connects + standard output to a socket from + socket activation, semantics are + similar to the respective option of + <varname>StandardInput=</varname>. + This setting defaults to the value set + with + <option>DefaultStandardOutput=</option> + in + <citerefentry><refentrytitle>systemd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which defaults to + <option>journal</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>StandardError=</varname></term> + <listitem><para>Controls where file + descriptor 2 (STDERR) of the executed + processes is connected to. The + available options are identical to + those of + <varname>StandardOutput=</varname>, + with one exception: if set to + <option>inherit</option> the file + descriptor used for standard output is + duplicated for standard error. This + setting defaults to the value set with + <option>DefaultStandardError=</option> + in + <citerefentry><refentrytitle>systemd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which defaults to + <option>inherit</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>TTYPath=</varname></term> + <listitem><para>Sets the terminal + device node to use if standard input, + output or stderr are connected to a + TTY (see above). Defaults to + <filename>/dev/console</filename>.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>TTYReset=</varname></term> + <listitem><para>Reset the terminal + device specified with + <varname>TTYPath=</varname> before and + after execution. Defaults to + <literal>no</literal>.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>TTYVHangup=</varname></term> + <listitem><para>Disconnect all clients + which have opened the terminal device + specified with + <varname>TTYPath=</varname> + before and after execution. Defaults + to + <literal>no</literal>.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>TTYVTDisallocate=</varname></term> + <listitem><para>If the the terminal + device specified with + <varname>TTYPath=</varname> is a + virtual console terminal try to + deallocate the TTY before and after + execution. This ensures that the + screen and scrollback buffer is + cleared. Defaults to + <literal>no</literal>.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>SyslogIdentifier=</varname></term> + <listitem><para>Sets the process name + to prefix log lines sent to syslog or + the kernel log buffer with. If not set + defaults to the process name of the + executed process. This option is only + useful when + <varname>StandardOutput=</varname> or + <varname>StandardError=</varname> are + set to <option>syslog</option> or + <option>kmsg</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>SyslogFacility=</varname></term> + <listitem><para>Sets the syslog + facility to use when logging to + syslog. One of <option>kern</option>, + <option>user</option>, + <option>mail</option>, + <option>daemon</option>, + <option>auth</option>, + <option>syslog</option>, + <option>lpr</option>, + <option>news</option>, + <option>uucp</option>, + <option>cron</option>, + <option>authpriv</option>, + <option>ftp</option>, + <option>local0</option>, + <option>local1</option>, + <option>local2</option>, + <option>local3</option>, + <option>local4</option>, + <option>local5</option>, + <option>local6</option> or + <option>local7</option>. See + <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for details. This option is only + useful when + <varname>StandardOutput=</varname> or + <varname>StandardError=</varname> are + set to <option>syslog</option>. + Defaults to + <option>daemon</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>SyslogLevel=</varname></term> + <listitem><para>Default syslog level + to use when logging to syslog or the + kernel log buffer. One of + <option>emerg</option>, + <option>alert</option>, + <option>crit</option>, + <option>err</option>, + <option>warning</option>, + <option>notice</option>, + <option>info</option>, + <option>debug</option>. See + <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for details. This option is only + useful when + <varname>StandardOutput=</varname> or + <varname>StandardError=</varname> are + set to <option>syslog</option> or + <option>kmsg</option>. Note that + individual lines output by the daemon + might be prefixed with a different log + level which can be used to override + the default log level specified + here. The interpretation of these + prefixes may be disabled with + <varname>SyslogLevelPrefix=</varname>, + see below. For details see + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + + Defaults to + <option>info</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SyslogLevelPrefix=</varname></term> + <listitem><para>Takes a boolean + argument. If true and + <varname>StandardOutput=</varname> or + <varname>StandardError=</varname> are + set to <option>syslog</option> or + <option>kmsg</option> log lines + written by the executed process that + are prefixed with a log level will be + passed on to syslog with this log + level set but the prefix removed. If + set to false, the interpretation of + these prefixes is disabled and the + logged lines are passed on as-is. For + details about this prefixing see + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + Defaults to true.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TimerSlackNSec=</varname></term> + <listitem><para>Sets the timer slack + in nanoseconds for the executed + processes. The timer slack controls the + accuracy of wake-ups triggered by + timers. See + <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for more information. Note that in + contrast to most other time span + definitions this parameter takes an + integer value in nano-seconds and does + not understand any other + units.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>LimitCPU=</varname></term> + <term><varname>LimitFSIZE=</varname></term> + <term><varname>LimitDATA=</varname></term> + <term><varname>LimitSTACK=</varname></term> + <term><varname>LimitCORE=</varname></term> + <term><varname>LimitRSS=</varname></term> + <term><varname>LimitNOFILE=</varname></term> + <term><varname>LimitAS=</varname></term> + <term><varname>LimitNPROC=</varname></term> + <term><varname>LimitMEMLOCK=</varname></term> + <term><varname>LimitLOCKS=</varname></term> + <term><varname>LimitSIGPENDING=</varname></term> + <term><varname>LimitMSGQUEUE=</varname></term> + <term><varname>LimitNICE=</varname></term> + <term><varname>LimitRTPRIO=</varname></term> + <term><varname>LimitRTTIME=</varname></term> + <listitem><para>These settings control + various resource limits for executed + processes. See + <citerefentry><refentrytitle>setrlimit</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details. Use the string + <varname>infinity</varname> to + configure no limit on a specific + resource.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PAMName=</varname></term> + <listitem><para>Sets the PAM service + name to set up a session as. If set + the executed process will be + registered as a PAM session under the + specified service name. This is only + useful in conjunction with the + <varname>User=</varname> setting. If + not set no PAM session will be opened + for the executed processes. See + <citerefentry><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TCPWrapName=</varname></term> + <listitem><para>If this is a + socket-activated service this sets the + tcpwrap service name to check the + permission for the current connection + with. This is only useful in + conjunction with socket-activated + services, and stream sockets (TCP) in + particular. It has no effect on other + socket types (e.g. datagram/UDP) and + on processes unrelated to socket-based + activation. If the tcpwrap + verification fails daemon start-up + will fail and the connection is + terminated. See + <citerefentry><refentrytitle>tcpd</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for details. Note that this option may + be used to do access control checks + only. Shell commands and commands + described in + <citerefentry><refentrytitle>hosts_options</refentrytitle><manvolnum>5</manvolnum></citerefentry> + are not supported.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>CapabilityBoundingSet=</varname></term> + + <listitem><para>Controls which + capabilities to include in the + capability bounding set for the + executed process. See + <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details. Takes a whitespace + separated list of capability names as + read by + <citerefentry><refentrytitle>cap_from_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + Capabilities listed will be included + in the bounding set, all others are + removed. If the list of capabilities + is prefixed with ~ all but the listed + capabilities will be included, the + effect of the assignment + inverted. Note that this option does + not actually set or unset any + capabilities in the effective, + permitted or inherited capability + sets. That's what + <varname>Capabilities=</varname> is + for. If this option is not used the + capability bounding set is not + modified on process execution, hence + no limits on the capabilities of the + process are enforced.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SecureBits=</varname></term> + <listitem><para>Controls the secure + bits set for the executed process. See + <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details. Takes a list of strings: + <option>keep-caps</option>, + <option>keep-caps-locked</option>, + <option>no-setuid-fixup</option>, + <option>no-setuid-fixup-locked</option>, + <option>noroot</option> and/or + <option>noroot-locked</option>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Capabilities=</varname></term> + <listitem><para>Controls the + <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> + set for the executed process. Take a + capability string describing the + effective, permitted and inherited + capability sets as documented in + <citerefentry><refentrytitle>cap_from_text</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + Note that these capability sets are + usually influenced by the capabilities + attached to the executed file. Due to + that + <varname>CapabilityBoundingSet=</varname> + is probably the much more useful + setting.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ControlGroup=</varname></term> + + <listitem><para>Controls the control + groups the executed processes shall be + made members of. Takes a + space-separated list of cgroup + identifiers. A cgroup identifier has a + format like + <filename>cpu:/foo/bar</filename>, + where "cpu" identifies the kernel + control group controller used, and + <filename>/foo/bar</filename> is the + control group path. The controller + name and ":" may be omitted in which + case the named systemd control group + hierarchy is implied. Alternatively, + the path and ":" may be omitted, in + which case the default control group + path for this unit is implied. This + option may be used to place executed + processes in arbitrary groups in + arbitrary hierarchies -- which can be + configured externally with additional + execution limits. By default systemd + will place all executed processes in + separate per-unit control groups + (named after the unit) in the systemd + named hierarchy. Since every process + can be in one group per hierarchy only + overriding the control group path in + the named systemd hierarchy will + disable automatic placement in the + default group. This option is + primarily intended to place executed + processes in specific paths in + specific kernel controller + hierarchies. It is however not + recommended to manipulate the service + control group path in the systemd + named hierarchy. For details about + control groups see <ulink + url="http://www.kernel.org/doc/Documentation/cgroups/cgroups.txt">cgroups.txt</ulink>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ControlGroupModify=</varname></term> + <listitem><para>Takes a boolean + argument. If true, the control groups + created for this unit will be owned by + the user specified with + <varname>User=</varname> (and the + appropriate group), and he/she can create + subgroups as well as add processes to + the group.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ControlGroupPersistent=</varname></term> + <listitem><para>Takes a boolean + argument. If true, the control groups + created for this unit will be marked + to be persistent, i.e. systemd will + not remove them when stopping the + unit. The default is false, meaning + that the control groups will be + removed when the unit is stopped. For + details about the semantics of this + logic see <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/PaxControlGroups">PaxControlGroups</ulink>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ControlGroupAttribute=</varname></term> + + <listitem><para>Set a specific control + group attribute for executed + processes, and (if needed) add the the + executed processes to a cgroup in the + hierarchy of the controller the + attribute belongs to. Takes two + space-separated arguments: the + attribute name (syntax is + <literal>cpu.shares</literal> where + <literal>cpu</literal> refers to a + specific controller and + <literal>shares</literal> to the + attribute name), and the attribute + value. Example: + <literal>ControlGroupAttribute=cpu.shares + 512</literal>. If this option is used + for an attribute that belongs to a + kernel controller hierarchy the unit + is not already configured to be added + to (for example via the + <literal>ControlGroup=</literal> + option) then the unit will be added to + the controller and the default unit + cgroup path is implied. Thus, using + <varname>ControlGroupAttribute=</varname> + is in most case sufficient to make use + of control group enforcements, + explicit + <varname>ControlGroup=</varname> are + only necessary in case the implied + default control group path for a + service is not desirable. For details + about control group attributes see + <ulink + url="http://www.kernel.org/doc/Documentation/cgroups/cgroups.txt">cgroups.txt</ulink>. This + option may appear more than once, in + order to set multiple control group + attributes.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>CPUShares=</varname></term> + + <listitem><para>Assign the specified + overall CPU time shares to the + processes executed. Takes an integer + value. This controls the + <literal>cpu.shares</literal> control + group attribute, which defaults to + 1024. For details about this control + group attribute see <ulink + url="http://www.kernel.org/doc/Documentation/scheduler/sched-design-CFS.txt">sched-design-CFS.txt</ulink>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>MemoryLimit=</varname></term> + <term><varname>MemorySoftLimit=</varname></term> + + <listitem><para>Limit the overall memory usage + of the executed processes to a certain + size. Takes a memory size in bytes. If + the value is suffixed with K, M, G or + T the specified memory size is parsed + as Kilobytes, Megabytes, Gigabytes, + resp. Terabytes (to the base + 1024). This controls the + <literal>memory.limit_in_bytes</literal> + and + <literal>memory.soft_limit_in_bytes</literal> + control group attributes. For details + about these control group attributes + see <ulink + url="http://www.kernel.org/doc/Documentation/cgroups/memory.txt">memory.txt</ulink>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DeviceAllow=</varname></term> + <term><varname>DeviceDeny=</varname></term> + + <listitem><para>Control access to + specific device nodes by the executed processes. Takes two + space separated strings: a device node + path (such as + <filename>/dev/null</filename>) + followed by a combination of r, w, m + to control reading, writing resp. + creating of the specific device node + by the unit. This controls the + <literal>devices.allow</literal> + and + <literal>devices.deny</literal> + control group attributes. For details + about these control group attributes + see <ulink + url="http://www.kernel.org/doc/Documentation/cgroups/devices.txt">devices.txt</ulink>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>BlockIOWeight=</varname></term> + + <listitem><para>Set the default or + per-device overall block IO weight + value for the executed + processes. Takes either a single + weight value (between 10 and 1000) to + set the default block IO weight, or a + space separated pair of a file path + and a weight value to specify the + device specific weight value (Example: + "/dev/sda 500"). The file path may be + specified as path to a block device + node or as any other file in which + case the backing block device of the + file system of the file is + determined. This controls the + <literal>blkio.weight</literal> and + <literal>blkio.weight_device</literal> + control group attributes, which + default to 1000. Use this option + multiple times to set weights for + multiple devices. For details about + these control group attributes see + <ulink + url="http://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>BlockIOReadBandwidth=</varname></term> + <term><varname>BlockIOWriteBandwidth=</varname></term> + + <listitem><para>Set the per-device + overall block IO bandwith limit for + the executed processes. Takes a space + separated pair of a file path and a + bandwith value (in bytes per second) + to specify the device specific + bandwidth. The file path may be + specified as path to a block device + node or as any other file in which + case the backing block device of the + file system of the file is determined. + If the bandwith is suffixed with K, M, + G, or T the specified bandwith is + parsed as Kilobytes, Megabytes, + Gigabytes, resp. Terabytes (Example: + "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 + 5M"). This controls the + <literal>blkio.read_bps_device</literal> + and + <literal>blkio.write_bps_device</literal> + control group attributes. Use this + option multiple times to set bandwith + limits for multiple devices. For + details about these control group + attributes see <ulink + url="http://www.kernel.org/doc/Documentation/cgroups/blkio-controller.txt">blkio-controller.txt</ulink>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ReadWriteDirectories=</varname></term> + <term><varname>ReadOnlyDirectories=</varname></term> + <term><varname>InaccessibleDirectories=</varname></term> + + <listitem><para>Sets up a new + file-system name space for executed + processes. These options may be used + to limit access a process might have + to the main file-system + hierarchy. Each setting takes a + space-separated list of absolute + directory paths. Directories listed in + <varname>ReadWriteDirectories=</varname> + are accessible from within the + namespace with the same access rights + as from outside. Directories listed in + <varname>ReadOnlyDirectories=</varname> + are accessible for reading only, + writing will be refused even if the + usual file access controls would + permit this. Directories listed in + <varname>InaccessibleDirectories=</varname> + will be made inaccessible for processes + inside the namespace. Note that + restricting access with these options + does not extend to submounts of a + directory. You must list submounts + separately in these settings to + ensure the same limited access. These + options may be specified more than + once in which case all directories + listed will have limited access from + within the + namespace.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PrivateTmp=</varname></term> + + <listitem><para>Takes a boolean + argument. If true sets up a new file + system namespace for the executed + processes and mounts a private + <filename>/tmp</filename> directory + inside it, that is not shared by + processes outside of the + namespace. This is useful to secure + access to temporary files of the + process, but makes sharing between + processes via + <filename>/tmp</filename> + impossible. Defaults to + false.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PrivateNetwork=</varname></term> + + <listitem><para>Takes a boolean + argument. If true sets up a new + network namespace for the executed + processes and configures only the + loopback network device + <literal>lo</literal> inside it. No + other network devices will be + available to the executed process. + This is useful to securely turn off + network access by the executed + process. Defaults to + false.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>MountFlags=</varname></term> + + <listitem><para>Takes a mount + propagation flag: + <option>shared</option>, + <option>slave</option> or + <option>private</option>, which + control whether namespaces set up with + <varname>ReadWriteDirectories=</varname>, + <varname>ReadOnlyDirectories=</varname> + and + <varname>InaccessibleDirectories=</varname> + receive or propagate new mounts + from/to the main namespace. See + <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for details. Defaults to + <option>shared</option>, i.e. the new + namespace will both receive new mount + points from the main namespace as well + as propagate new mounts to + it.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>UtmpIdentifier=</varname></term> + + <listitem><para>Takes a a four + character identifier string for an + utmp/wtmp entry for this service. This + should only be set for services such + as <command>getty</command> + implementations where utmp/wtmp + entries must be created and cleared + before and after execution. If the + configured string is longer than four + characters it is truncated and the + terminal four characters are + used. This setting interprets %I style + string replacements. This setting is + unset by default, i.e. no utmp/wtmp + entries are created or cleaned up for + this service.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>IgnoreSIGPIPE=</varname></term> + + <listitem><para>Takes a boolean + argument. If true causes SIGPIPE to be + ignored in the executed + process. Defaults to true, since + SIGPIPE generally is useful only in + shell pipelines.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd.mount.xml b/man/systemd.mount.xml new file mode 100644 index 000000000..8f1cc514c --- /dev/null +++ b/man/systemd.mount.xml @@ -0,0 +1,278 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.mount"> + <refentryinfo> + <title>systemd.mount</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.mount</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.mount</refname> + <refpurpose>systemd mount configuration files</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd.mount</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>A unit configuration file whose name ends in + <filename>.mount</filename> encodes information about + a file system mount point controlled and supervised by + systemd.</para> + + <para>This man page lists the configuration options + specific to this unit type. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the common options of all unit configuration + files. The common configuration items are configured + in the generic [Unit] and [Install] sections. The + mount specific configuration options are configured + in the [Mount] section.</para> + + <para>Additional options are listed in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which define the execution environment the + <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry> + binary is executed in.</para> + + <para>Mount units must be named after the mount point + directories they control. Example: the mount point + <filename>/home/lennart</filename> must be configured + in a unit file + <filename>home-lennart.mount</filename>. For details + about the escaping logic used to convert a file system + path to a unit name see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + + <para>Optionally, a mount unit may be accompanied by + an automount unit, to allow on-demand or parallelized + mounting. See + <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + + <para>If an mount point is beneath another mount point + in the file system hierarchy, a dependency between both + units is created automatically.</para> + + <para>Mount points created at runtime independent on + unit files or <filename>/etc/fstab</filename> will be + monitored by systemd and appear like any other mount + unit in systemd.</para> + </refsect1> + + <refsect1> + <title><filename>/etc/fstab</filename></title> + + <para>Mount units may either be configured via unit + files, or via <filename>/etc/fstab</filename> (see + <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details).</para> + + <para>When reading <filename>/etc/fstab</filename> a + few special mount options are understood by systemd + which influence how dependencies are created for mount + points from <filename>/etc/fstab</filename>. If + <option>MountAuto=yes</option> is set in + <filename>system.conf</filename> (which is the + default), or if <option>x-systemd.mount</option> is + specified as mount option, then systemd will create a + dependency of type <option>Wants</option> from either + <filename>local-fs.target</filename> or + <filename>remote-fs.target</filename>, depending + whether the file system is local or remote. If + <option>x-systemd.automount</option> is set, an + automount unit will be created for the file + system. See + <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. If + <option>x-systemd-device-timeout=</option> is + specified it may be used to configure how long systemd + should wait for a device to show up before giving up + on an entry from + <filename>/etc/fstab</filename>. Specify a time in + seconds or explicitly specifiy a unit as + <literal>s</literal>, <literal>min</literal>, + <literal>h</literal>, <literal>ms</literal>.</para> + + <para>If a mount point is configured in both + <filename>/etc/fstab</filename> and a unit file, the + configuration in the latter takes precedence.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>Mount files must include a [Mount] section, + which carries information about the file system mount points it + supervises. A number of options that may be used in + this section are shared with other unit types. These + options are documented in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The + options specific to the [Mount] section of mount + units are the following:</para> + + <variablelist> + + <varlistentry> + <term><varname>What=</varname></term> + <listitem><para>Takes an absolute path + of a device node, file or other + resource to mount. See + <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for details. If this refers to a + device node, a dependency on the + respective device unit is + automatically created. (See + <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information.) + This option is + mandatory.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Where=</varname></term> + <listitem><para>Takes an absolute path + of a directory of the mount point. If + the mount point is not existing at + time of mounting, it is created. This + string must be reflected in the unit + file name. (See above.) This option is + mandatory.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Type=</varname></term> + <listitem><para>Takes a string for the + filesystem type. See + <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for details. This setting is + optional.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Options=</varname></term> + + <listitem><para>Mount options to use + when mounting. This takes a comma + separated list of options. This + setting is optional.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DirectoryMode=</varname></term> + <listitem><para>Directories of mount + points (and any parent directories) + are automatically created if + needed. This option specifies the file + system access mode used when creating + these directories. Takes an access + mode in octal notation. Defaults to + 0755.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TimeoutSec=</varname></term> + <listitem><para>Configures the time to + wait for the mount command to + finish. If a command does not exit + within the configured time the mount + will be considered failed and be shut + down again. All commands still running + will be terminated forcibly via + SIGTERM, and after another delay of + this time with SIGKILL. (See + <option>KillMode=</option> below.) + Takes a unit-less value in seconds, or + a time span value such as "5min + 20s". Pass 0 to disable the timeout + logic. Defaults to + 90s.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>KillMode=</varname></term> + <listitem><para>Specifies how + processes of this mount shall be + killed. One of + <option>control-group</option>, + <option>process</option>, + <option>none</option>.</para> + + <para>This option is mostly equivalent + to the <option>KillMode=</option> + option of service files. See + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>KillSignal=</varname></term> + <listitem><para>Specifies which signal + to use when killing a process of this + mount. Defaults to SIGTERM. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SendSIGKILL=</varname></term> + <listitem><para>Specifies whether to + send SIGKILL to remaining processes + after a timeout, if the normal + shutdown procedure left processes of + the mount around. Takes a boolean + value. Defaults to "yes". + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd.path.xml b/man/systemd.path.xml new file mode 100644 index 000000000..5b1ff75f7 --- /dev/null +++ b/man/systemd.path.xml @@ -0,0 +1,220 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.path"> + <refentryinfo> + <title>systemd.path</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.path</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.path</refname> + <refpurpose>systemd path configuration files</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd.path</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>A unit configuration file whose name ends in + <filename>.path</filename> encodes information about + a path monitored by systemd, for + path-based activation.</para> + + <para>This man page lists the configuration options + specific to this unit type. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the common options of all unit configuration + files. The common configuration items are configured + in the generic [Unit] and [Install] sections. The + path specific configuration options are configured in + the [Path] section.</para> + + <para>For each path file, a matching unit file must + exist, describing the unit to activate when the path + changes. By default, a service by the same name as the + path (except for the suffix) is activated. Example: a + path file <filename>foo.path</filename> activates a + matching service <filename>foo.service</filename>. The + unit to activate may be controlled by + <varname>Unit=</varname> (see below).</para> + + <para>Internally, path units use the + <citerefentry><refentrytitle>inotify</refentrytitle><manvolnum>7</manvolnum></citerefentry> + API to monitor file systems. Due to that, it suffers by the + same limitations as inotify, and for example cannot be + used to monitor files or directories changed by other + machines on remote NFS file systems.</para> + + <para>If an path unit is beneath another mount + point in the file system hierarchy, a dependency + between both units is created automatically.</para> + + <para>Unless <varname>DefaultDependencies=</varname> + is set to <option>false</option>, path units will + implicitly have dependencies of type + <varname>Conflicts=</varname> and + <varname>Before=</varname> on + <filename>shutdown.target</filename>. These ensure + that path units are terminated cleanly prior to system + shutdown. Only path units involved with early boot or + late system shutdown should disable this + option.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>Path files must include a [Path] section, + which carries information about the path(s) it + monitors. The options specific to the [Path] section + of path units are the following:</para> + + <variablelist> + <varlistentry> + <term><varname>PathExists=</varname></term> + <term><varname>PathExistsGlob=</varname></term> + <term><varname>PathChanged=</varname></term> + <term><varname>PathModified=</varname></term> + <term><varname>DirectoryNotEmpty=</varname></term> + + <listitem><para>Defines paths to + monitor for certain changes: + <varname>PathExists=</varname> may be + used to watch the mere existence of a + file or directory. If the file + specified exists the configured unit + is + activated. <varname>PathExistsGlob=</varname> + works similar, but checks for the + existance of at least one file + matching the globbing pattern + specified. <varname>PathChanged=</varname> + may be used to watch a file or + directory and activate the configured + unit whenever it changes. It is not activated + on every write to the watched file but it is + activated if the file which was open for writing + gets closed. <varname>PathModified=</varname> + is similar, but additionally it is activated + also on simple writes to the watched file. + + <varname>DirectoryNotEmpty=</varname> + may be used to watch a directory and + activate the configured unit whenever + it contains at least one file.</para> + + <para>The arguments of these + directives must be absolute file + system paths.</para> + + <para>Multiple directives may be + combined, of the same and of different + types, to watch multiple paths.</para> + + <para>If a path is already existing + (in case of + <varname>PathExists=</varname> and + <varname>PathExistsGlob=</varname>) or + a directory already is not empty (in + case of + <varname>DirectoryNotEmpty=</varname>) + at the time the path unit is + activated, then the configured unit is + immediately activated as + well. Something similar does not apply + to <varname>PathChanged=</varname>. + </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>Unit=</varname></term> + + <listitem><para>The unit to activate + when any of the configured paths + changes. The argument is a unit name, + whose suffix is not + <filename>.path</filename>. If not + specified, this value defaults to a + service that has the same name as the + path unit, except for the suffix. (See + above.) It is recommended that the + unit name that is activated and the + unit name of the path unit are named + identical, except for the + suffix.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>MakeDirectory=</varname></term> + + <listitem><para>Takes a boolean + argument. If true the directories to + watch are created before + watching. This option is ignored for + <varname>PathExists=</varname> + settings. Defaults to + <option>false</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>DirectoryMode=</varname></term> + + <listitem><para>If + <varname>MakeDirectory=</varname> is + enabled use the mode specified here to + create the directories in + question. Takes an access mode in + octal notation. Defaults to + <option>0755</option>.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>inotify</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd.service.xml b/man/systemd.service.xml new file mode 100644 index 000000000..837a992ba --- /dev/null +++ b/man/systemd.service.xml @@ -0,0 +1,837 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.service"> + <refentryinfo> + <title>systemd.service</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.service</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.service</refname> + <refpurpose>systemd service configuration files</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd.service</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>A unit configuration file whose name ends in + <filename>.service</filename> encodes information + about a process controlled and supervised by + systemd.</para> + + <para>This man page lists the configuration options + specific to this unit type. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the common options of all unit configuration + files. The common configuration items are configured + in the generic <literal>[Unit]</literal> and + <literal>[Install]</literal> sections. The service + specific configuration options are configured in the + <literal>[Service]</literal> section.</para> + + <para>Additional options are listed in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which define the execution environment the commands + are executed in.</para> + + <para>Unless <varname>DefaultDependencies=</varname> + is set to <option>false</option>, service units will + implicitly have dependencies of type + <varname>Requires=</varname> and + <varname>After=</varname> on + <filename>basic.target</filename> as well as + dependencies of type <varname>Conflicts=</varname> and + <varname>Before=</varname> on + <filename>shutdown.target</filename>. These ensure + that normal service units pull in basic system + initialization, and are terminated cleanly prior to + system shutdown. Only services involved with early + boot or late system shutdown should disable this + option.</para> + + <para>If a service is requested under a certain name + but no unit configuration file is found, systemd looks + for a SysV init script by the same name (with the + <filename>.service</filename> suffix removed) and + dynamically creates a service unit from that + script. This is useful for compatibility with + SysV.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>Service files must include a + <literal>[Service]</literal> section, which carries + information about the service and the process it + supervises. A number of options that may be used in + this section are shared with other unit types. These + options are documented in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The + options specific to the <literal>[Service]</literal> + section of service units are the following:</para> + + <variablelist> + <varlistentry> + <term><varname>Type=</varname></term> + + <listitem><para>Configures the process + start-up type for this service + unit. One of <option>simple</option>, + <option>forking</option>, + <option>oneshot</option>, + <option>dbus</option>, + <option>notify</option>.</para> + + <para>If set to + <option>simple</option> (the default + value) it is expected that the process + configured with + <varname>ExecStart=</varname> is the + main process of the service. In this + mode, 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.</para> + + <para>If set to + <option>forking</option> it is + expected that the process configured + with <varname>ExecStart=</varname> + will call <function>fork()</function> + 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 behaviour of + traditional UNIX daemons. If this + setting is used, it is recommended to + also use the + <varname>PIDFile=</varname> 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.</para> + + <para>Behaviour of + <option>oneshot</option> is similar + to <option>simple</option>, however + it is expected that the process has to + exit before systemd starts follow-up + units. <varname>RemainAfterExit=</varname> + is particularly useful for this type + of service.</para> + + <para>Behaviour of + <option>dbus</option> is similar to + <option>simple</option>, however it is + expected that the daemon acquires a + name on the D-Bus bus, as configured + by + <varname>BusName=</varname>. systemd + will proceed starting follow-up units + after the D-Bus bus name has been + acquired. Service units with this + option configured implicitly gain + dependencies on the + <filename>dbus.socket</filename> + unit.</para> + + <para>Behaviour of + <option>notify</option> is similar to + <option>simple</option>, however it is + expected that the daemon sends a + notification message via + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> + or an equivalent call when it finished + starting up. systemd will proceed + starting follow-up units after this + notification message has been sent. If + this option is used + <varname>NotifyAccess=</varname> (see + below) should be set to open access to + the notification socket provided by + systemd. If + <varname>NotifyAccess=</varname> is + not set, it will be implicitly set to + <option>main</option>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>RemainAfterExit=</varname></term> + + <listitem><para>Takes a boolean value + that specifies whether the service + shall be considered active even when + all its processes exited. Defaults to + <option>no</option>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>GuessMainPID=</varname></term> + + <listitem><para>Takes a boolean value + that specifies whether systemd should + try to guess the main PID of a service + should if it cannot be determined + reliably. This option is ignored + unless <option>Type=forking</option> + is set and <option>PIDFile=</option> + is unset because for the other types + or with an explicitly configured PID + file the main PID is always known. The + guessing algorithm might come to + incorrect conclusions if a daemon + consists of more than one process. If + the main PID cannot be determined + failure detection and automatic + restarting of a service will not work + reliably. Defaults to + <option>yes</option>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>PIDFile=</varname></term> + + <listitem><para>Takes an absolute file + name pointing to the PID file of this + daemon. Use of this option is + recommended for services where + <varname>Type=</varname> is set to + <option>forking</option>. systemd will + read the PID of the main process of + the daemon after start-up of the + service. systemd will not write to the + file configured here.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>BusName=</varname></term> + + <listitem><para>Takes a D-Bus bus + name, where this service is reachable + as. This option is mandatory for + services where + <varname>Type=</varname> is set to + <option>dbus</option>, but its use + is otherwise recommended as well if + the process takes a name on the D-Bus + bus.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>ExecStart=</varname></term> + <listitem><para>Takes a command line + that is executed when this service + shall be started up. The first token + of the command line must be an + absolute file name, then followed by + arguments for the process. It is + mandatory to set this option for all + services. This option may not be + specified more than once, except when + <varname>Type=oneshot</varname> is + used in which case more than one + <varname>ExecStart=</varname> line is + accepted which are then invoked one by + one, sequentially in the order they + appear in the unit file.</para> + + <para>Optionally, if the absolute file + name is prefixed with + <literal>@</literal>, the second token + will be passed as + <literal>argv[0]</literal> to the + executed process, followed by the + further arguments specified. If the + first token is prefixed with + <literal>-</literal> an exit code of + the command normally considered a + failure (i.e. non-zero exit status or + abnormal exit due to signal) is ignored + and considered success. If both + <literal>-</literal> and + <literal>@</literal> are used for the + same command the former must precede + the latter. Unless + <varname>Type=forking</varname> is + set, the process started via this + command line will be considered the + main process of the daemon. The + command line accepts % specifiers as + described in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + + <para>On top of that basic environment + variable substitution is + supported. Use + <literal>${FOO}</literal> as part of a + word, or as 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. Use + <literal>$FOO</literal> as a separate + word on the command line, in which + case it will be replaced by the value + of the environment variable split up + at whitespace, resulting in no or more + arguments. Note that the first + argument (i.e. the program to execute) + may not be a variable, and must be a + literal and absolute path + name.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ExecStartPre=</varname></term> + <term><varname>ExecStartPost=</varname></term> + <listitem><para>Additional commands + that are executed before (resp. after) + the command in + <varname>ExecStart=</varname>. Multiple + command lines may be concatenated in a + single directive, by separating them + by semicolons (these semicolons must + be passed as separate words). In that + case, the commands are executed one + after the other, + serially. Alternatively, these + directives may be specified more than + once with the same effect. However, + the latter syntax is not recommended + for compatibility with parsers + suitable for XDG + <filename>.desktop</filename> files. + Use of these settings is + optional. Specifier and environment + variable substitution is + supported.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ExecReload=</varname></term> + <listitem><para>Commands to execute to + trigger a configuration reload in the + service. This argument takes multiple + command lines, following the same + scheme as pointed out for + <varname>ExecStartPre=</varname> + above. Use of this setting is + optional. Specifier and environment + variable substitution is supported + here following the same scheme as for + <varname>ExecStart=</varname>. One + special environment variable is set: + if known <literal>$MAINPID</literal> is + set to the main process of the + daemon, and may be used for command + lines like the following: + <command>/bin/kill -HUP + $MAINPID</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ExecStop=</varname></term> + <listitem><para>Commands to execute to + stop the service started via + <varname>ExecStart=</varname>. This + argument takes multiple command lines, + following the same scheme as pointed + out for + <varname>ExecStartPre=</varname> + above. Use of this setting is + optional. All processes remaining for + a service after the commands + configured in this option are run are + terminated according to the + <varname>KillMode=</varname> setting + (see below). If this option is not + specified the process is terminated + right-away when service stop is + requested. Specifier and environment + variable substitution is supported + (including + <literal>$MAINPID</literal>, see + above).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ExecStopPost=</varname></term> + <listitem><para>Additional commands + that are executed after the service + was stopped using the commands + configured in + <varname>ExecStop=</varname>. This + argument takes multiple command lines, + following the same scheme as pointed + out for + <varname>ExecStartPre</varname>. Use + of these settings is + optional. Specifier and environment + variable substitution is + supported.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RestartSec=</varname></term> + <listitem><para>Configures the time to + sleep before restarting a service (as + configured with + <varname>Restart=</varname>). Takes a + unit-less value in seconds, or a time + span value such as "5min + 20s". Defaults to + 100ms.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TimeoutSec=</varname></term> + <listitem><para>Configures the time to + wait for start-up and stop. If a + daemon service does not signal + start-up completion within the + configured time the service will be + considered failed and be shut down + again. If a service is asked to stop + but does not terminate in the + specified time it will be terminated + forcibly via SIGTERM, and after + another delay of this time with + SIGKILL. (See + <varname>KillMode=</varname> + below.) Takes a unit-less value in seconds, or a + time span value such as "5min + 20s". Pass 0 to disable the timeout + logic. Defaults to + 90s.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>WatchdogSec=</varname></term> + <listitem><para>Configures the + watchdog timeout for a service. This + is activated when the start-up is + completed. The service must call + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> + regularly with "WATCHDOG=1". If the + time between two such calls is larger + than the configured time then the + service is placed in a failure + state. By setting + <varname>Restart=</varname> + to <option>on-failure</option> or + <option>always</option> the service + will be automatically restarted. The + time configured here will be passed to + the executed service process in the + <varname>WATCHDOG_USEC=</varname> + environment variable. If + this option is used + <varname>NotifyAccess=</varname> (see + below) should be set to open access to + the notification socket provided by + systemd. If + <varname>NotifyAccess=</varname> is not + set, it will be implicitly set to + <option>main</option>. Defaults to 0, + which disables this + feature.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Restart=</varname></term> + <listitem><para>Configures whether the + main service process shall be + restarted when it exits. Takes one of + <option>no</option>, + <option>on-success</option>, + <option>on-failure</option>, + <option>on-abort</option> or + <option>always</option>. If set to + <option>no</option> (the default) the + service will not be restarted when it + exits. If set to + <option>on-success</option> it will be + restarted only when it exited cleanly, + i.e. terminated with an exit code of + 0. If set to + <option>on-failure</option> it will be + restarted only when it exited with an + exit code not equalling 0, when + terminated by a signal, when an + operation times out or when the + configured watchdog timeout is + triggered. If set to + <option>on-abort</option> it will be + restarted only if it exits due to + reception of an uncaught signal. If + set to <option>always</option> the + service will be restarted regardless + whether it exited cleanly or not, + got terminated abnormally by a + signal or hit a timeout.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PermissionsStartOnly=</varname></term> + <listitem><para>Takes a boolean + argument. If true, the permission + related execution options as + configured with + <varname>User=</varname> and similar + options (see + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information) are only applied + to the process started with + <varname>ExecStart=</varname>, and not + to the various other + <varname>ExecStartPre=</varname>, + <varname>ExecStartPost=</varname>, + <varname>ExecReload=</varname>, + <varname>ExecStop=</varname>, + <varname>ExecStopPost=</varname> + commands. If false, the setting is + applied to all configured commands the + same way. Defaults to + false.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RootDirectoryStartOnly=</varname></term> + <listitem><para>Takes a boolean + argument. If true, the root directory + as configured with the + <varname>RootDirectory=</varname> + option (see + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information) is only applied + to the process started with + <varname>ExecStart=</varname>, and not + to the various other + <varname>ExecStartPre=</varname>, + <varname>ExecStartPost=</varname>, + <varname>ExecReload=</varname>, + <varname>ExecStop=</varname>, + <varname>ExecStopPost=</varname> + commands. If false, the setting is + applied to all configured commands the + same way. Defaults to + false.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SysVStartPriority=</varname></term> + <listitem><para>Set the SysV start + priority to use to order this service + in relation to SysV services lacking + LSB headers. This option is only + necessary to fix ordering in relation + to legacy SysV services, that have no + ordering information encoded in the + script headers. As such it should only + be used as temporary compatibility + option, and not be used in new unit + files. Almost always it is a better + choice to add explicit ordering + directives via + <varname>After=</varname> or + <varname>Before=</varname>, + instead. For more details see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. If + used, pass an integer value in the + range 0-99.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>KillMode=</varname></term> + <listitem><para>Specifies how + processes of this service shall be + killed. One of + <option>control-group</option>, + <option>process</option>, + <option>none</option>.</para> + + <para>If set to + <option>control-group</option> all + remaining processes in the control + group of this service will be + terminated on service stop, after the + stop command (as configured with + <varname>ExecStop=</varname>) is + executed. If set to + <option>process</option> only the main + process itself is killed. If set to + <option>none</option> no process is + killed. In this case only the stop + command will be executed on service + stop, but no process be killed + otherwise. Processes remaining alive + after stop are left in their control + group and the control group continues + to exist after stop unless it is + empty. Defaults to + <option>control-group</option>.</para> + + <para>Processes will first be + terminated via SIGTERM (unless the + signal to send is changed via + <varname>KillSignal=</varname>). If + then after a delay (configured via the + <varname>TimeoutSec=</varname> option) + processes still remain, the + termination request is repeated with + the SIGKILL signal (unless this is + disabled via the + <varname>SendSIGKILL=</varname> + option). See + <citerefentry><refentrytitle>kill</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for more + information.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>KillSignal=</varname></term> + <listitem><para>Specifies which signal + to use when killing a + service. Defaults to SIGTERM. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SendSIGKILL=</varname></term> + <listitem><para>Specifies whether to + send SIGKILL to remaining processes + after a timeout, if the normal + shutdown procedure left processes of + the service around. Takes a boolean + value. Defaults to "yes". + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>NonBlocking=</varname></term> + <listitem><para>Set O_NONBLOCK flag + for all file descriptors passed via + socket-based activation. If true, all + file descriptors >= 3 (i.e. all except + STDIN/STDOUT/STDERR) will have + the O_NONBLOCK flag set and hence are in + non-blocking mode. This option is only + useful in conjunction with a socket + unit, as described in + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Defaults + to false.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>NotifyAccess=</varname></term> + <listitem><para>Controls access to the + service status notification socket, as + accessible via the + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call. Takes one of + <option>none</option> (the default), + <option>main</option> or + <option>all</option>. If + <option>none</option> no daemon status + updates are accepted from the service + processes, all status update messages + are ignored. If <option>main</option> + only service updates sent from the + main process of the service are + accepted. If <option>all</option> all + services updates from all members of + the service's control group are + accepted. This option should be set to + open access to the notification socket + when using + <varname>Type=notify</varname> or + <varname>WatchdogUsec=</varname> (see + above). If those options are used but + <varname>NotifyAccess=</varname> not + configured it will be implicitly set + to + <option>main</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Sockets=</varname></term> + <listitem><para>Specifies the name of + the socket units this service shall + inherit the sockets from when the + service is started. Normally it + should not be necessary to use this + setting as all sockets whose unit + shares the same name as the service + (ignoring the different suffix of course) + are passed to the spawned + process.</para> + + <para>Note that the same socket may be + passed to multiple processes at the + same time. Also note that a different + service may be activated on incoming + traffic than inherits the sockets. Or + in other words: The + <varname>Service=</varname> setting of + <filename>.socket</filename> units + doesn't have to match the inverse of the + <varname>Sockets=</varname> setting of + the <filename>.service</filename> it + refers to.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>FsckPassNo=</varname></term> + <listitem><para>Set the fsck passno + priority to use to order this service + in relation to other file system + checking services. This option is only + necessary to fix ordering in relation + to fsck jobs automatically created for + all <filename>/etc/fstab</filename> + entries with a value in the fs_passno + column > 0. As such it should only be + used as option for fsck + services. Almost always it is a better + choice to add explicit ordering + directives via + <varname>After=</varname> or + <varname>Before=</varname>, + instead. For more details see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. If + used, pass an integer value in the + same range as + <filename>/etc/fstab</filename>'s + fs_passno column. See + <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>StartLimitInterval=</varname></term> + <term><varname>StartLimitBurst=</varname></term> + + <listitem><para>Configure service + start rate limiting. By default + services which are started more often + than 5 times within 10s are not + permitted to start any more times + until the 10s interval ends. With + these two options this rate limiting + may be modified. Use + <varname>StartLimitInterval=</varname> + to configure the checking interval + (defaults to 10s, set to 0 to disable + any kind of rate limiting). Use + <varname>StartLimitBurst=</varname> to + configure how many starts per interval + are allowed (defaults to 5). These + configuration options are particularly + useful in conjunction with + <varname>Restart=</varname>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>StartLimitAction=</varname></term> + + <listitem><para>Configure the action + to take if the rate limit configured + with + <varname>StartLimitInterval=</varname> + and + <varname>StartLimitBurst=</varname> is + hit. Takes one of + <option>none</option>, + <option>reboot</option>, + <option>reboot-force</option> or + <option>reboot-immediate</option>. If + <option>none</option> is set, + hitting the rate limit will trigger no + action besides that the start will not + be + permitted. <option>reboot</option> + causes a reboot following the normal + shutdown procedure (i.e. equivalent to + <command>systemctl reboot</command>), + <option>reboot-force</option> causes + an forced reboot which will terminate + all processes forcibly but should + cause no dirty file systems on reboot + (i.e. equivalent to <command>systemctl + reboot -f</command>) and + <option>reboot-immediate</option> + causes immediate execution of the + <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> + system call, which might result in + data loss. Defaults to + <option>none</option>.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd.snapshot.xml b/man/systemd.snapshot.xml new file mode 100644 index 000000000..a3e23225c --- /dev/null +++ b/man/systemd.snapshot.xml @@ -0,0 +1,87 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.snapshot"> + <refentryinfo> + <title>systemd.snapshot</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.snapshot</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.snapshot</refname> + <refpurpose>systemd snapshot units</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd.snapshot</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>Snapshot units are not configured via unit + configuration files. Nonetheless they are named + similar to filenames. A unit name whose name ends in + <filename>.snapshot</filename> refers to a dynamic + snapshot of the systemd runtime state.</para> + + <para>Snapshots are not configured on disk but created + dynamically via <command>systemctl snapshot</command> + (see + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for details) or an equivalent command. When created, + they will automatically get dependencies on the + currently activated units. They act as saved + runtime state of the systemd manager. Later on, the + user may choose to return to the saved state via + <command>systemctl isolate</command>. They are + useful to roll back to a defined state after + temporarily starting/stopping services or + similar.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd.socket.xml b/man/systemd.socket.xml new file mode 100644 index 000000000..d9921e496 --- /dev/null +++ b/man/systemd.socket.xml @@ -0,0 +1,674 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.socket"> + <refentryinfo> + <title>systemd.socket</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.socket</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.socket</refname> + <refpurpose>systemd socket configuration files</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd.socket</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>A unit configuration file whose name ends in + <filename>.socket</filename> encodes information about + an IPC or network socket or a file system FIFO + controlled and supervised by systemd, for socket-based + activation.</para> + + <para>This man page lists the configuration options + specific to this unit type. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the common options of all unit configuration + files. The common configuration items are configured + in the generic [Unit] and [Install] sections. The + socket specific configuration options are configured + in the [Socket] section.</para> + + <para>Additional options are listed in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which define the execution environment the + <option>ExecStartPre=</option>, + <option>ExecStartPost=</option>, + <option>ExecStopPre=</option> and + <option>ExecStoptPost=</option> commands are executed + in.</para> + + <para>For each socket file a matching service file + (see + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details) must exist, describing the service to + start on incoming traffic on the socket. Depending on + the setting of <option>Accept=</option> (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 + <filename>foo.socket</filename> needs a matching + service <filename>foo.service</filename> if + <option>Accept=false</option> is set. If + <option>Accept=true</option> is set a service template + file <filename>foo@.service</filename> must exist from + which services are instantiated for each incoming + connection.</para> + + <para>Unless <varname>DefaultDependencies=</varname> + is set to <option>false</option>, socket units will + implicitly have dependencies of type + <varname>Requires=</varname> and + <varname>After=</varname> on + <filename>sysinit.target</filename> as well as + dependencies of type <varname>Conflicts=</varname> and + <varname>Before=</varname> on + <filename>shutdown.target</filename>. These ensure + that socket units pull in basic system + initialization, and are terminated cleanly prior to + system shutdown. Only sockets involved with early + boot or late system shutdown should disable this + option.</para> + + <para>Socket units may be used to implement on-demand + starting of services, as well as parallelized starting + of services.</para> + + <para>Note that the daemon software configured for + socket activation with socket units needs to be able + to accept sockets from systemd, either via systemd's + native socket passing interface (see + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for details) or via the traditional + <citerefentry><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry>-style + socket passing (i.e. sockets passed in via STDIN and + STDOUT, using <varname>StandardInput=socket</varname> + in the service file).</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>Socket files must include a [Socket] section, + which carries information about the socket or FIFO it + supervises. A number of options that may be used in + this section are shared with other unit types. These + options are documented in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The + options specific to the [Socket] section of socket + units are the following:</para> + + <variablelist> + <varlistentry> + <term><varname>ListenStream=</varname></term> + <term><varname>ListenDatagram=</varname></term> + <term><varname>ListenSequentialPacket=</varname></term> + <listitem><para>Specifies an address + to listen on for a stream + (SOCK_STREAM), datagram (SOCK_DGRAM) + resp. sequential packet + (SOCK_SEQPACKET) socket. The address + can be written in various formats:</para> + + <para>If the address starts with a + slash (/), it is read as file system + socket in the AF_UNIX socket + family.</para> + + <para>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. For details + see + <citerefentry><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + + <para>If the address string is a + single number it is read as port + number to listen on for both IPv4 and + IPv6.</para> + + <para>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.</para> + + <para>If the address string is a + string in the format [x]:y it is read + as IPv6 address x on a port y.</para> + + <para>Note that SOCK_SEQPACKET + (i.e. <varname>ListenSequentialPacket=</varname>) + is only available for AF_UNIX + sockets. SOCK_STREAM + (i.e. <varname>ListenStream=</varname>) + when used for IP sockets refers to TCP + sockets, SOCK_DGRAM + (i.e. <varname>ListenDatagram=</varname>) + to UDP.</para> + + <para>These options may be specified + more than once in which case incoming + traffic on any of the sockets will trigger + service activation, and all listed + sockets will be passed to the service, + regardless whether there is incoming + traffic on them or not.</para> + + <para>If an IP address is used here, it + is often desirable to listen on it + before the interface it is configured + on is up and running, and even + regardless whether it will be up and + running ever at all. To deal with this it is + recommended to set the + <varname>FreeBind=</varname> option + described below.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ListenFIFO=</varname></term> + <listitem><para>Specifies a file + system FIFO to listen on. This expects + an absolute file system path as + argument. Behaviour otherwise is very + similar to the + <varname>ListenDatagram=</varname> + directive above.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ListenSpecial=</varname></term> + <listitem><para>Specifies a special + file in the file system to listen + on. This expects an absolute file + system path as argument. Behaviour + otherwise is very similar to the + <varname>ListenFIFO=</varname> + directive above. Use this to open + character device nodes as well as + special files in + <filename>/proc</filename> and + <filename>/sys</filename>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ListenNetlink=</varname></term> + <listitem><para>Specifies a Netlink + family to create a socket for to + listen on. This expects a short string + referring to the AF_NETLINK family + name (such as <varname>audit</varname> + or <varname>kobject-uevent</varname>) + as argument, optionally suffixed by a + whitespace followed by a multicast + group integer. Behaviour otherwise is + very similar to the + <varname>ListenDatagram=</varname> + directive above.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ListenMessageQueue=</varname></term> + <listitem><para>Specifies a POSIX + message queue name to listen on. This + expects a valid message queue name + (i.e. beginning with /). Behaviour + otherwise is very similar to the + <varname>ListenFIFO=</varname> + directive above. On Linux message + queue descriptors are actually file + descriptors and can be inherited + between processes.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>BindIPv6Only=</varname></term> + <listitem><para>Takes a one of + <option>default</option>, + <option>both</option> or + <option>ipv6-only</option>. Controls + the IPV6_V6ONLY socket option (see + <citerefentry><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details). If + <option>both</option>, IPv6 sockets + bound will be accessible via both IPv4 + and IPv6. If + <option>ipv6-only</option>, they will + be accessible via IPv6 only. If + <option>default</option> (which is the + default, surprise!) the system wide + default setting is used, as controlled + by + <filename>/proc/sys/net/ipv6/bindv6only</filename>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>Backlog=</varname></term> + <listitem><para>Takes an unsigned + integer argument. Specifies the number + of connections to queue that have not + been accepted yet. This setting + matters only for stream and sequential + packet sockets. See + <citerefentry><refentrytitle>listen</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details. Defaults to SOMAXCONN + (128).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>BindToDevice=</varname></term> + <listitem><para>Specifies a network + interface name to bind this socket + to. If set traffic will only be + accepted from the specified network + interfaces. This controls the + SO_BINDTODEVICE socket option (see + <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details). If this option is used, + an automatic dependency from this + socket unit on the network interface + device unit + (<citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry> + is created.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DirectoryMode=</varname></term> + <listitem><para>If listening on a file + system socket of FIFO, the parent + directories are automatically created + if needed. This option specifies the + file system access mode used when + creating these directories. Takes an + access mode in octal + notation. Defaults to + 0755.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SocketMode=</varname></term> + <listitem><para>If listening on a file + system socket of FIFO, this option + specifies the file system access mode + used when creating the file + node. Takes an access mode in octal + notation. Defaults to + 0666.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Accept=</varname></term> + <listitem><para>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 (also see + above). This value is ignored for + datagram sockets and FIFOs where + a single service unit unconditionally + handles all incoming traffic. Defaults + to <option>false</option>. For + performance reasons, it is recommended + to write new daemons only in a way + that is suitable for + <option>Accept=false</option>. This + option is mostly useful to allow + daemons designed for usage with + <citerefentry><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + to work unmodified with systemd socket + activation.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>MaxConnections=</varname></term> + <listitem><para>The maximum number of + connections to simultaneously run + services instances for, when + <option>Accept=true</option> 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 + <option>Accept=no</option> or datagram + sockets. Defaults to + 64.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>KeepAlive=</varname></term> + <listitem><para>Takes a boolean + argument. If true, the TCP/IP stack + will send a keep alive message after + 2h (depending on the configuration of + <filename>/proc/sys/net/ipv4/tcp_keepalive_time</filename>) + for all TCP streams accepted on this + socket. This controls the SO_KEEPALIVE + socket option (see + <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> + and the <ulink + url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP + Keepalive HOWTO</ulink> for details.) + Defaults to + <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Priority=</varname></term> + <listitem><para>Takes an integer + argument controlling the priority for + all traffic sent from this + socket. This controls the SO_PRIORITY + socket option (see + <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details.).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ReceiveBuffer=</varname></term> + <term><varname>SendBuffer=</varname></term> + <listitem><para>Takes an integer + argument controlling the receive + resp. send buffer sizes of this + socket. This controls the SO_RCVBUF + resp. SO_SNDBUF socket options (see + <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details.).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>IPTOS=</varname></term> + <listitem><para>Takes an integer + argument controlling the IP + Type-Of-Service field for packets + generated from this socket. This + controls the IP_TOS socket option (see + <citerefentry><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details.). Either a numeric string + or one of <option>low-delay</option>, + <option>throughput</option>, + <option>reliability</option> or + <option>low-cost</option> may be + specified.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>IPTTL=</varname></term> + <listitem><para>Takes an integer + argument controlling the IPv4 + Time-To-Live/IPv6 Hop-Count field for + packets generated from this + socket. This sets the + IP_TTL/IPV6_UNICAST_HOPS socket + options (see + <citerefentry><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details.)</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Mark=</varname></term> + <listitem><para>Takes an integer + value. Controls the firewall mark of + packets generated by this socket. This + can be used in the firewall logic to + filter packets from this socket. This + sets the SO_MARK socket option. See + <citerefentry><refentrytitle>iptables</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PipeSize=</varname></term> + <listitem><para>Takes an integer + value. Controls the pipe buffer size + of FIFOs configured in this socket + unit. See + <citerefentry><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>MessageQueueMaxMessages=</varname>, + <varname>MessageQueueMessageSize=</varname></term> + <listitem><para>These two settings + take integer values and control the + mq_maxmsg resp. mq_msgsize field when + creating the message queue. Note that + either none or both of these variables + need to be set. See + <citerefentry><refentrytitle>mq_setattr</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>FreeBind=</varname></term> + <listitem><para>Takes a boolean + value. Controls whether the socket can + be bound to non-local IP + addresses. This is useful to configure + sockets listening on specific IP + addresses before those IP addresses + are successfully configured on a + network interface. This sets the + IP_FREEBIND socket option. For + robustness reasons it is recommended + to use this option whenever you bind a + socket to a specific IP + address. Defaults to <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Transparent=</varname></term> + <listitem><para>Takes a boolean + value. Controls the IP_TRANSPARENT + socket option. Defaults to + <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Broadcast=</varname></term> + <listitem><para>Takes a boolean + value. This controls the SO_BROADCAST + socket option, which allows broadcast + datagrams to be sent from this + socket. Defaults to + <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PassCredentials=</varname></term> + <listitem><para>Takes a boolean + value. This controls the SO_PASSCRED + socket option, which allows AF_UNIX sockets to + receive the credentials of the sending + process in an ancillary message. + Defaults to + <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PassSecurity=</varname></term> + <listitem><para>Takes a boolean + value. This controls the SO_PASSSEC + socket option, which allows AF_UNIX + sockets to receive the security + context of the sending process in an + ancillary message. Defaults to + <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TCPCongestion=</varname></term> + <listitem><para>Takes a string + value. Controls the TCP congestion + algorithm used by this socket. Should + be one of "westwood", "veno", "cubic", + "lp" or any other available algorithm + supported by the IP stack. This + setting applies only to stream + sockets.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ExecStartPre=</varname></term> + <term><varname>ExecStartPost=</varname></term> + <listitem><para>Takes one or more + command lines, which are executed + before (resp. after) the listening + sockets/FIFOs are created and + bound. The first token of the command + line must be an absolute file name, + then followed by arguments for the + process. Multiple command lines may be + specified following the same scheme as + used for + <varname>ExecStartPre=</varname> of + service unit files.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ExecStopPre=</varname></term> + <term><varname>ExecStopPost=</varname></term> + <listitem><para>Additional commands + that are executed before (resp. after) + the listening sockets/FIFOs are closed + and removed. Multiple command lines + may be specified following the same + scheme as used for + <varname>ExecStartPre=</varname> of + service unit files.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TimeoutSec=</varname></term> + <listitem><para>Configures the time to + wait for the commands specified in + <varname>ExecStartPre=</varname>, + <varname>ExecStartPost=</varname>, + <varname>ExecStopPre=</varname> and + <varname>ExecStopPost=</varname> to + finish. If a command does not exit + within the configured time, the socket + will be considered failed and be shut + down again. All commands still running, + will be terminated forcibly via + SIGTERM, and after another delay of + this time with SIGKILL. (See + <option>KillMode=</option> below.) + Takes a unit-less value in seconds, or + a time span value such as "5min + 20s". Pass 0 to disable the timeout + logic. Defaults to + 90s.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>KillMode=</varname></term> + <listitem><para>Specifies how + processes of this socket unit shall be + killed. One of + <option>control-group</option>, + <option>process</option>, + <option>none</option>.</para> + + <para>This option is mostly equivalent + to the <option>KillMode=</option> + option of service files. See + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>KillSignal=</varname></term> + <listitem><para>Specifies which signal + to use when killing a process of this + socket. Defaults to SIGTERM. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SendSIGKILL=</varname></term> + <listitem><para>Specifies whether to + send SIGKILL to remaining processes + after a timeout, if the normal + shutdown procedure left processes of + the socket around. Takes a boolean + value. Defaults to "yes". + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Service=</varname></term> + <listitem><para>Specifies the service + unit name to activate on incoming + traffic. This defaults to the service + that bears the same name as the socket + (ignoring the different suffixes). In + most cases it should not be necessary + to use this option.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd.special.xml b/man/systemd.special.xml new file mode 100644 index 000000000..116a43ccf --- /dev/null +++ b/man/systemd.special.xml @@ -0,0 +1,725 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.special"> + + <refentryinfo> + <title>systemd.special</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.special</refentrytitle> + <manvolnum>7</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.special</refname> + <refpurpose>special systemd units</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>basic.target</filename>, + <filename>ctrl-alt-del.target</filename>, + <filename>dbus.service</filename>, + <filename>default.target</filename>, + <filename>display-manager.service</filename>, + <filename>emergency.target</filename>, + <filename>exit.service</filename>, + <filename>graphical.target</filename>, + <filename>halt.target</filename>, + <filename>kbrequest.target</filename>, + <filename>local-fs.target</filename>, + <filename>local-fs-pre.target</filename>, + <filename>mail-transfer-agent.target</filename>, + <filename>multi-user.target</filename>, + <filename>network.target</filename>, + <filename>nss-lookup.target</filename>, + <filename>poweroff.target</filename>, + <filename>reboot.target</filename>, + <filename>remote-fs.target</filename>, + <filename>remote-fs-pre.target</filename>, + <filename>rescue.target</filename>, + <filename>rpcbind.target</filename>, + <filename>runlevel2.target</filename>, + <filename>runlevel3.target</filename>, + <filename>runlevel4.target</filename>, + <filename>runlevel5.target</filename>, + <filename>shutdown.target</filename>, + <filename>sigpwr.target</filename>, + <filename>sockets.target</filename>, + <filename>swap.target</filename>, + <filename>sysinit.target</filename>, + <filename>syslog.target</filename>, + <filename>systemd-initctl.service</filename>, + <filename>systemd-initctl.socket</filename>, + <filename>systemd-stdout-syslog-bridge.service</filename>, + <filename>systemd-stdout-syslog-bridge.socket</filename>, + <filename>time-sync.target</filename>, + <filename>umount.target</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>A few units are treated specially by + systemd. They have special internal semantics and + cannot be renamed.</para> + </refsect1> + + <refsect1> + <title>Special System Units</title> + + <variablelist> + <varlistentry> + <term><filename>basic.target</filename></term> + <listitem> + <para>A special target unit + covering early boot-up.</para> + <para>systemd automatically + adds dependencies of the types + Requires and After for this + target unit to all SysV + service units configured for + runlevel 1 to 5.</para> + <para>Usually this should pull-in + all sockets, mount points, + swap devices and other basic + initialization necessary for + the general purpose + daemons. Most normal daemons + should have dependencies of + type After and Requires on + this unit.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>ctrl-alt-del.target</filename></term> + <listitem> + <para>systemd starts this + target whenever + Control+Alt+Del is pressed on + the console. Usually this + should be aliased (symlinked) + to + <filename>reboot.target</filename>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>dbus.service</filename></term> + <listitem> + <para>A special unit for the + D-Bus system bus. As soon as + this service is fully started + up systemd will connect to it + and register its + service.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>default.target</filename></term> + <listitem> + <para>The default unit systemd + starts at bootup. Usually this + should be aliased (symlinked) + to + <filename>multi-user.target</filename> + or + <filename>graphical.target</filename>.</para> + <para>The default unit systemd + starts at bootup can be + overridden with the + <varname>systemd.unit=</varname> + kernel command line option.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>display-manager.service</filename></term> + <listitem> + <para>The display manager + service. Usually this should + be aliased (symlinked) to + <filename>xdm.service</filename> + or a similar display manager + service.</para> + <para>systemd automatically + adds dependencies of type + After for this target unit to + all SysV init script service + units with a LSB header + referring to the + <literal>$x-display-manager</literal> + facility, for compatibility + with Debian.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>emergency.target</filename></term> + <listitem> + <para>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 + <varname>systemd.unit=</varname> + and has otherwise little use. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>graphical.target</filename></term> + <listitem> + <para>A special target unit + for setting up a graphical + login screen. This pulls in + <filename>multi-user.target</filename>.</para> + + <para>Units that are needed + for graphical login shall add + Wants dependencies for their + unit to this unit (or + <filename>multi-user.target</filename>) + during installation.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>halt.target</filename></term> + <listitem> + <para>A special target unit + for shutting down and halting the system.</para> + + <para>Applications wanting to + halt the system should start + this unit.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>kbrequest.target</filename></term> + <listitem> + <para>systemd starts this + target whenever Alt+ArrowUp is + pressed on the console. This + is a good candidate to be + aliased (symlinked) to + <filename>rescue.target</filename>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>local-fs.target</filename></term> + <listitem> + <para>systemd automatically + adds dependencies of type + After to all mount units that + refer to local mount points + for this target unit. In + addition, systemd adds + dependencies of type Wants to + this target unit for those + mounts listed in + <filename>/etc/fstab</filename> + that have the + <option>auto</option> and + <option>comment=systemd.mount</option> + mount options set.</para> + + <para>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 + <literal>$local_fs</literal> + facility.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>local-fs-pre.target</filename></term> + <listitem> + <para>This target unit is + automatically ordered before + all local mount points marked + with <option>auto</option> + (see above). It can be used to + execute certain units before + all local mounts.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>mail-transfer-agent.target</filename></term> + <listitem> + <para>The mail transfer agent + (MTA) service. Usually this + should pull-in all units + necessary for + sending/receiving mails on the + local host.</para> + + <para>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 + <literal>$mail-transfer-agent</literal> + or + <literal>$mail-transport-agent</literal> + facilities, for compatibility + with Debian.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>multi-user.target</filename></term> + <listitem> + <para>A special target unit + for setting up a multi-user + system (non-graphical). This + is pulled in by + <filename>graphical.target</filename>.</para> + + <para>Units that are needed + for a multi-user system shall + add Wants dependencies to + this unit for their unit during + installation.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>network.target</filename></term> + <listitem> + <para>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 + <literal>$network</literal> + facility.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>nss-lookup.target</filename></term> + <listitem> + <para>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 + <literal>$named</literal> + facility.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>poweroff.target</filename></term> + <listitem> + <para>A special target unit + for shutting down and powering off the system.</para> + + <para>Applications wanting to + power off the system should start + this unit.</para> + + <para><filename>runlevel0.target</filename> + is an alias for this target + unit, for compatibility with SysV.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>reboot.target</filename></term> + <listitem> + <para>A special target unit + for shutting down and rebooting the system.</para> + + <para>Applications wanting to + reboot the system should start + this unit.</para> + + <para><filename>runlevel6.target</filename> + is an alias for this target + unit, for compatibility with SysV.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>remote-fs.target</filename></term> + <listitem> + <para>Similar to + <filename>local-fs.target</filename>, + but for remote mount + points.</para> + + <para>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 + <literal>$remote_fs</literal> + facility.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>remote-fs-pre.target</filename></term> + <listitem> + <para>This target unit is + automatically ordered before + all remote mount points marked + with <option>auto</option> + (see above). It can be used to + execute certain units before + all remote mounts.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>rescue.target</filename></term> + <listitem> + <para>A special target unit + for setting up the base system + and a rescue shell.</para> + + <para><filename>runlevel1.target</filename> + is an alias for this target + unit, for compatibility with SysV.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>rpcbind.target</filename></term> + <listitem> + <para>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 + <literal>$rpcbind</literal> + facility.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>runlevel2.target</filename></term> + <listitem> + <para>This is a target that is + called whenever the SysV + compatibility code asks for + runlevel 2. It is a good idea + to make this an alias for + (i.e. symlink to) + <filename>multi-user.target</filename>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>runlevel3.target</filename></term> + <listitem> + <para>This is a target that is + called whenever the SysV + compatibility code asks for + runlevel 3. It is a good idea + to make this an alias for + (i.e. symlink to) + <filename>multi-user.target</filename> + or + <filename>graphical.target</filename>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>runlevel4.target</filename></term> + <listitem> + <para>This is a target that is + called whenever the SysV + compatibility code asks for + runlevel 4. It is a good idea + to make this an alias for + (i.e. symlink to) + <filename>multi-user.target</filename> + or + <filename>graphical.target</filename>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>runlevel5.target</filename></term> + <listitem> + <para>This is a target that is + called whenever the SysV + compatibility code asks for + runlevel 5. It is a good idea + to make this an alias for + (i.e. symlink to) + <filename>multi-user.target</filename> + or + <filename>graphical.target</filename>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>shutdown.target</filename></term> + <listitem> + <para>A special target unit + that terminates the services + on system shutdown.</para> + + <para>Services that shall be + terminated on system shutdown + shall add Conflicts + dependencies to this unit for + their service unit, which is + implicitly done when + <varname>DefaultDependencies=yes</varname> + is set (the default).</para> + + <para>systemd automatically + adds dependencies of type + Conflicts to this target unit + for all SysV init script + service units that shall be + terminated in SysV runlevels 0 + or 6.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>sigpwr.target</filename></term> + <listitem> + <para>A special target that is + started when systemd receives + the SIGPWR process signal, + which is normally sent by the + kernel or UPS daemons when + power fails.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>sockets.target</filename></term> + <listitem> + <para>A special target unit + that sets up all service + sockets.</para> + + <para>Services that can be + socket-activated shall add + Wants dependencies to this + unit for their socket unit + during installation.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>swap.target</filename></term> + <listitem> + <para>Similar to + <filename>local-fs.target</filename>, but for swap + partitions and swap + files.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>sysinit.target</filename></term> + <listitem> + <para>A special target unit + covering early boot-up scripts.</para> + <para>systemd automatically + adds dependencies of the types + Wants and After for all + SysV service units configured + for runlevels that are not 0 + to 6 to this target unit. + This covers the special + boot-up runlevels some + distributions have, such as S + or b.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>syslog.target</filename></term> + <listitem> + <para>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 + <literal>$syslog</literal> + facility.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>systemd-initctl.service</filename></term> + <listitem> + <para>This provides + compatibility with the SysV + /dev/initctl file system FIFO + for communication with the + init system.</para> + <para>This is a + socket-activated service, see + <filename>system-initctl.socket</filename>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>systemd-initctl.socket</filename></term> + <listitem> + <para>Socket activation unit + for + <filename>system-initctl.service</filename>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>systemd-stdout-syslog-bridge.service</filename></term> + <listitem> + <para>This is internally used + by systemd to provide syslog + logging to the processes it + maintains.</para> + <para>This is a + socket-activated service, see + <filename>system-stdout-syslog-bridge.socket</filename>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>systemd-stdout-syslog-bridge.socket</filename></term> + <listitem> + <para>Socket activation unit + for + <filename>system-stdout-syslog-bridge.service</filename>. systemd + will automatically add + dependencies of types Requires + and After to all units that + have been configured for + stdout or stderr to be + connected to syslog or the + kernel log buffer.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>systemd-shutdownd.service</filename></term> + <listitem> + <para>This is internally used + by + <citerefentry><refentrytitle>shutdown</refentrytitle><manvolnum>8</manvolnum></citerefentry> + to implement delayed shutdowns.</para> + <para>This is a + socket-activated service, see + <filename>system-shutdownd.socket</filename>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>systemd-shutdownd.socket</filename></term> + <listitem> + <para>Socket activation unit + for + <filename>system-shutdownd.service</filename>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>time-sync.target</filename></term> + <listitem> + <para>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 + <literal>$time</literal> + facility.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>umount.target</filename></term> + <listitem> + <para>A special target unit + that umounts all mount and + automount points on system + shutdown.</para> + + <para>Mounts that shall be + unmounted on system shutdown + shall add Conflicts + dependencies to this unit for + their mount unit, which is + implicitly done when + <varname>DefaultDependencies=yes</varname> + is set (the default).</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Special User Units</title> + + <para>When systemd runs as a user instance, the + following special units are available, which have + similar definitions as their system counterparts: + <filename>default.target</filename>, + <filename>local-fs.target</filename>, + <filename>remote-fs.target</filename>, + <filename>shutdown.target</filename>, + <filename>sockets.target</filename>, + <filename>swap.target</filename>.</para> + + <para>In addition the following special unit is + understood only when systemd runs as service instance:</para> + + <variablelist> + <varlistentry> + <term><filename>exit.service</filename></term> + <listitem> + <para>A special service unit + for shutting down the + user service manager.</para> + + <para>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.</para> + + <para>Normally, this pulls in + <filename>shutdown.target</filename> + which in turn should be + conflicted by all units that + want to be shut down on + user service manager exit.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd.swap.xml b/man/systemd.swap.xml new file mode 100644 index 000000000..ab00f9f31 --- /dev/null +++ b/man/systemd.swap.xml @@ -0,0 +1,222 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.swap"> + <refentryinfo> + <title>systemd.swap</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.swap</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.swap</refname> + <refpurpose>systemd swap configuration files</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd.swap</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>A unit configuration file whose name ends in + <filename>.swap</filename> encodes information about a + swap device or file for memory paging controlled and + supervised by systemd.</para> + + <para>This man page lists the configuration options + specific to this unit type. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the common options of all unit configuration + files. The common configuration items are configured + in the generic [Unit] and [Install] sections. The swap + specific configuration options are configured in the + [Swap] section.</para> + + <para>Swap units must be named after the devices + (resp. files) they control. Example: the swap device + <filename>/dev/sda5</filename> must be configured in a + unit file <filename>dev-sda5.swap</filename>. For + details about the escaping logic used to convert a + file system path to a unit name see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + + <para>All swap units automatically get the appropriate + dependencies on the devices (resp. on the mount points + of the files) they are activated from.</para> + + <para>Swap units with + <varname>DefaultDependencies=</varname> enabled + implicitly acquire a conflicting dependency to + <filename>umount.target</filename> so that they are + deactivated at shutdown.</para> + </refsect1> + + <refsect1> + <title><filename>fstab</filename></title> + + <para>Swap units may either be configured via unit + files, or via <filename>/etc/fstab</filename> (see + <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details).</para> + + <para>If a swap device or file is configured in both + <filename>/etc/fstab</filename> and a unit file the + configuration in the latter takes precedence.</para> + + <para>Unless the <option>noauto</option> option is set + for them all swap units configured in + <filename>/etc/fstab</filename> are also added as + requirements to <filename>swap.target</filename>, so + that they are waited for and activated during + boot.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>Swap files must include a [Swap] section, which + carries information about the swap device it + supervises. A number of options that may be used in + this section are shared with other unit types. These + options are documented in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The + options specific to the [Swap] section of swap units + are the following:</para> + + <variablelist> + + <varlistentry> + <term><varname>What=</varname></term> + <listitem><para>Takes an absolute path + of a device node or file to use for + paging. See + <citerefentry><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for details. If this refers to a + device node, a dependency on the + respective device unit is + automatically created. (See + <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information.) If this refers + to a file, a dependency on the + respective mount unit is automatically + created. (See + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information.) This option is + mandatory.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Priority=</varname></term> + + <listitem><para>Swap priority to use + when activating the swap device or + file. This takes an integer. This + setting is optional.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TimeoutSec=</varname></term> + <listitem><para>Configures the time to + wait for the swapon command to + finish. If a command does not exit + within the configured time the swap + will be considered failed and be shut + down again. All commands still running + will be terminated forcibly via + SIGTERM, and after another delay of + this time with SIGKILL. (See + <option>KillMode=</option> below.) + Takes a unit-less value in seconds, or + a time span value such as "5min + 20s". Pass 0 to disable the timeout + logic. Defaults to + 90s.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>KillMode=</varname></term> + <listitem><para>Specifies how + processes of this swap shall be + killed. One of + <option>control-group</option>, + <option>process</option>, + <option>none</option>.</para> + + <para>This option is mostly equivalent + to the <option>KillMode=</option> + option of service files. See + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>KillSignal=</varname></term> + <listitem><para>Specifies which signal + to use when killing a process of this + swap. Defaults to SIGTERM. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SendSIGKILL=</varname></term> + <listitem><para>Specifies whether to + send SIGKILL to remaining processes + after a timeout, if the normal + shutdown procedure left processes of + the swap around. Takes a boolean + value. Defaults to "yes". + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd.target.xml b/man/systemd.target.xml new file mode 100644 index 000000000..6b1dbfbde --- /dev/null +++ b/man/systemd.target.xml @@ -0,0 +1,108 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.target"> + <refentryinfo> + <title>systemd.target</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.target</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.target</refname> + <refpurpose>systemd target configuration files</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd.target</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>A unit configuration file whose name ends in + <filename>.target</filename> encodes information about + a target unit of systemd, which is used for grouping + units and as well-known synchronization points during + start-up.</para> + + <para>This unit type has no specific options. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the common options of all unit configuration + files. The common configuration items are configured + in the generic [Unit] and [Install] sections. A + separate [Target] section does not exist, since no + target-specific options may be configured.</para> + + <para>Target units do not offer any additional + functionality on top of the generic functionality + provided by units. They exist merely to group units via dependencies + (useful as boot targets), and to establish + standardized names for synchronization points used in + dependencies between units. Among other things, target + units are a more flexible replacement for SysV + runlevels in the classic SysV init system. (And for + compatibility reasons special + target units such as + <filename>runlevel3.target</filename> exist which are used by + the SysV runlevel compatibility code in systemd. See + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details).</para> + + <para>Unless <varname>DefaultDependencies=</varname> + is set to <option>false</option>, target units will + implicitly complement all configured dependencies of + type <varname>Wants=</varname>, + <varname>Requires=</varname>, + <varname>RequiresOverridable=</varname> with + dependencies of type <varname>After=</varname> if the + units in question also have + <varname>DefaultDependencies=true</varname>. + </para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd.timer.xml b/man/systemd.timer.xml new file mode 100644 index 000000000..9b6b486bf --- /dev/null +++ b/man/systemd.timer.xml @@ -0,0 +1,192 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.timer"> + <refentryinfo> + <title>systemd.timer</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.timer</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.timer</refname> + <refpurpose>systemd timer configuration files</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd.timer</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>A unit configuration file whose name ends in + <filename>.timer</filename> encodes information about + a timer controlled and supervised by systemd, for + timer-based activation.</para> + + <para>This man page lists the configuration options + specific to this unit type. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the common options of all unit configuration + files. The common configuration items are configured + in the generic [Unit] and [Install] sections. The + timer specific configuration options are configured in + the [Timer] section.</para> + + <para>For each timer file, a matching unit file must + exist, describing the unit to activate when the timer + elapses. By default, a service by the same name as the + timer (except for the suffix) is activated. Example: a + timer file <filename>foo.timer</filename> activates a + matching service <filename>foo.service</filename>. The + unit to activate may be controlled by + <varname>Unit=</varname> (see below).</para> + + <para>Unless <varname>DefaultDependencies=</varname> + is set to <option>false</option>, timer units will + implicitly have dependencies of type + <varname>Conflicts=</varname> and + <varname>Before=</varname> on + <filename>shutdown.target</filename>. These ensure + that timer units are stopped cleanly prior to system + shutdown. Only timer units involved with early boot or + late system shutdown should disable this + option.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>Timer files must include a [Timer] section, + which carries information about the timer it + defines. The options specific to the [Timer] section + of timer units are the following:</para> + + <variablelist> + <varlistentry> + <term><varname>OnActiveSec=</varname></term> + <term><varname>OnBootSec=</varname></term> + <term><varname>OnStartupSec=</varname></term> + <term><varname>OnUnitActiveSec=</varname></term> + <term><varname>OnUnitInactiveSec=</varname></term> + + <listitem><para>Defines timers + relative to different starting points: + <varname>OnActiveSec=</varname> defines a + timer relative to the moment the timer + itself is + activated. <varname>OnBootSec=</varname> + defines a timer relative to when the + machine was booted + up. <varname>OnStartupSec=</varname> + defines a timer relative to when + systemd was + started. <varname>OnUnitActiveSec=</varname> + defines a timer relative to when the + unit the timer is activating was last + activated. <varname>OnUnitInactiveSec=</varname> + defines a timer relative to when the + unit the timer is activating was last + deactivated.</para> + + <para>Multiple directives may be + combined of the same and of different + types. For example, by combining + <varname>OnBootSec=</varname> and + <varname>OnUnitActiveSec=</varname> it is + possible to define a timer that + elapses in regular intervals and + activates a specific service each + time.</para> + + <para>The arguments to the directives + are time spans configured in + seconds. Example: "OnBootSec=50" means + 50s after boot-up. The argument may + also include time units. Example: + "OnBootSec=5h 30min" means 5 hours and 30 + minutes after boot-up. For details + about the syntax of time spans see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + + <para>If a timer configured with + <varname>OnBootSec=</varname> or + <varname>OnStartupSec=</varname> is + already in the past when the timer + unit is activated, it will immediately + elapse and the configured unit is + started. This is not the case for + timers defined in the other + directives.</para></listitem> + + <para>These are monotonic timers, + independent of wall-clock time and timezones. If the + computer is temporarily suspended, the + monotonic clock stops too.</para> + + </varlistentry> + <varlistentry> + <term><varname>Unit=</varname></term> + + <listitem><para>The unit to activate + when this timer elapses. The argument is a + unit name, whose suffix is not + <filename>.timer</filename>. If not + specified, this value defaults to a + service that has the same name as the + timer unit, except for the + suffix. (See above.) It is recommended + that the unit name that is activated + and the unit name of the timer unit + are named identically, except for the + suffix.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml new file mode 100644 index 000000000..3cc126b12 --- /dev/null +++ b/man/systemd.unit.xml @@ -0,0 +1,969 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.unit"> + + <refentryinfo> + <title>systemd.unit</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.unit</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.unit</refname> + <refpurpose>systemd unit configuration files</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd.service</filename>, + <filename>systemd.socket</filename>, + <filename>systemd.device</filename>, + <filename>systemd.mount</filename>, + <filename>systemd.automount</filename>, + <filename>systemd.swap</filename>, + <filename>systemd.target</filename>, + <filename>systemd.path</filename>, + <filename>systemd.timer</filename>, + <filename>systemd.snapshot</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>A unit configuration file 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 file system path or a timer controlled and + supervised by + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>. The + syntax is inspired by <ulink + url="http://standards.freedesktop.org/desktop-entry-spec/latest/">XDG + Desktop Entry Specification</ulink> <filename>.desktop</filename> files, which are in turn + inspired by Microsoft Windows + <filename>.ini</filename> files.</para> + + <para>This man pages lists the common configuration + options of all the unit types. These options need to + be configured in the [Unit] resp. [Install] + section of the unit files.</para> + + <para>In addition to the generic [Unit] and [Install] + sections described here, each unit should have a + type-specific section, e.g. [Service] for a service + unit. See the respective man pages for more + information.</para> + + <para>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 is prefixed + with <option>X-</option> it is ignored completely by + systemd. Applications may use this to include + additional information in the unit files.</para> + + <para>Boolean arguments used in unit files can be + written in various formats. For positive settings the + strings <option>1</option>, <option>yes</option>, + <option>true</option> and <option>on</option> are + equivalent. For negative settings the strings + <option>0</option>, <option>no</option>, + <option>false</option> and <option>off</option> are + equivalent.</para> + + <para>Time span values encoded in unit files can be + written in various formats. A stand-alone number + specifies a time in seconds. If suffixed with a time + unit, the unit is honored. A concatenation of + multiple values with units is supported, in which case + the values are added up. Example: "50" refers to 50 + seconds; "2min 200ms" refers to 2 minutes plus 200 + milliseconds, i.e. 120200ms. The following time units + are understood: s, min, h, d, w, ms, us.</para> + + <para>Empty lines and lines starting with # or ; are + ignored. This may be used for commenting. Lines ending + in a backslash are concatenated with the following + line while reading and the backslash is replaced by a + space character. This may be used to wrap long lines.</para> + + <para>If a line starts with <option>.include</option> + followed by a file name, the specified file will be + parsed at this point. Make sure that the file that is + included has the appropiate section headers before + any directives.</para> + + <para>Along with a unit file + <filename>foo.service</filename> a directory + <filename>foo.service.wants/</filename> may exist. All + units symlinked from such a directory are implicitly + added as dependencies of type + <varname>Wanted=</varname> to the unit. This is useful + to hook units into the start-up of other units, + without having to modify their unit configuration + files. For details about the semantics of + <varname>Wanted=</varname> see below. The preferred + way to create symlinks in the + <filename>.wants/</filename> directory of a service is + with the <command>enable</command> command of the + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + tool which reads information from the [Install] + section of unit files. (See below.) A similar + functionality exists for <varname>Requires=</varname> + type dependencies as well, the directory suffix is + <filename>.requires/</filename> in this case.</para> + + <para>Note that while systemd offers a flexible + dependency system between units it is recommended to + use this functionality only sparsely and instead rely + on techniques such as bus-based or socket-based + activation which makes dependencies implicit, which + both results in a simpler and more flexible + system.</para> + + <para>Some unit names reflect paths existing in the + file system name space. Example: a device unit + <filename>dev-sda.device</filename> refers to a device + with the device node <filename>/dev/sda</filename> in + the file system namespace. If this applies a special + way to escape the path name is used, so that the + result is usable as part of a file name. Basically, + given a path, "/" is replaced by "-", and all + unprintable characters and the "-" are replaced by + C-style "\x20" escapes. The root directory "/" is + encoded as single dash, while otherwise the initial + and ending "/" is removed from all paths during + transformation. This escaping is reversible.</para> + + <para>Optionally, units may be instantiated from a + template file at runtime. This allows creation of + multiple units from a single configuration file. If + systemd looks for a unit configuration file it will + first search for the literal unit name in the + filesystem. If that yields no success and the unit + name contains an @ character, systemd will look for a + unit template that shares the same name but with the + instance string (i.e. the part between the @ character + and the suffix) removed. Example: if a service + <filename>getty@tty3.service</filename> is requested + and no file by that name is found, systemd will look + for <filename>getty@.service</filename> and + instantiate a service from that configuration file if + it is found.</para> + + <para>To refer to the instance string from + within the configuration file you may use the special + <literal>%i</literal> specifier in many of the + configuration options. Other specifiers exist, the + full list is:</para> + + <table> + <title>Specifiers available in unit files</title> + <tgroup cols='3' align='left' colsep='1' rowsep='1'> + <colspec colname="spec" /> + <colspec colname="mean" /> + <colspec colname="detail" /> + <thead> + <row> + <entry>Specifier</entry> + <entry>Meaning</entry> + <entry>Details</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>%n</literal></entry> + <entry>Full unit name</entry> + <entry></entry> + </row> + <row> + <entry><literal>%N</literal></entry> + <entry>Unescaped full unit name</entry> + <entry></entry> + </row> + <row> + <entry><literal>%p</literal></entry> + <entry>Prefix name</entry> + <entry>This refers to the string before the @, i.e. "getty" in the example above, where "tty3" is the instance name.</entry> + </row> + <row> + <entry><literal>%P</literal></entry> + <entry>Unescaped prefix name</entry> + <entry></entry> + </row> + <row> + <entry><literal>%i</literal></entry> + <entry>Instance name</entry> + <entry>This is the string between the @ character and the suffix.</entry> + </row> + <row> + <entry><literal>%I</literal></entry> + <entry>Unescaped instance name</entry> + <entry></entry> + </row> + <row> + <entry><literal>%f</literal></entry> + <entry>Unescaped file name</entry> + <entry>This is either the unescaped instance name (if set) with / prepended (if necessary), or the prefix name similarly prepended with /.</entry> + </row> + <row> + <entry><literal>%c</literal></entry> + <entry>Control group path of the unit</entry> + <entry></entry> + </row> + <row> + <entry><literal>%r</literal></entry> + <entry>Root control group path of systemd</entry> + <entry></entry> + </row> + <row> + <entry><literal>%R</literal></entry> + <entry>Parent directory of the root control group path of systemd</entry> + <entry></entry> + </row> + <row> + <entry><literal>%t</literal></entry> + <entry>Runtime socket dir</entry> + <entry>This is either /run (for the system manager) or $XDG_RUNTIME_DIR (for user managers).</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>If a unit file is empty (i.e. has the file size + 0) or is symlinked to <filename>/dev/null</filename> + its configuration will not be loaded and it appears + with a load state of <literal>masked</literal>, and + cannot be activated. Use this as an effective way to + fully disable a unit, making it impossible to start it + even manually.</para> + + <para>The unit file format is covered by the + <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise">Interface + Stability Promise</ulink>.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>Unit file may include a [Unit] section, which + carries generic information about the unit that is not + dependent on the type of unit:</para> + + <variablelist> + + <varlistentry> + <term><varname>Description=</varname></term> + <listitem><para>A free-form string + describing the unit. This is intended + for use in UIs to show descriptive + information along with the unit + name.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Requires=</varname></term> + + <listitem><para>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. This option may be + specified more than once, in which + case requirement dependencies for all + listed names are created. Note that + requirement dependencies do not + influence the order in which services + are started or stopped. This has to be + configured independently with the + <varname>After=</varname> or + <varname>Before=</varname> options. If + a unit + <filename>foo.service</filename> + requires a unit + <filename>bar.service</filename> as + configured with + <varname>Requires=</varname> and no + ordering is configured with + <varname>After=</varname> or + <varname>Before=</varname>, then both + units will be started simultaneously + and without any delay between them if + <filename>foo.service</filename> is + activated. Often it is a better choice + to use <varname>Wants=</varname> + instead of + <varname>Requires=</varname> in order + to achieve a system that is more + robust when dealing with failing + services.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RequiresOverridable=</varname></term> + + <listitem><para>Similar to + <varname>Requires=</varname>. + Dependencies listed in + <varname>RequiresOverridable=</varname> + which cannot be fulfilled or fail to + start are ignored if the startup was + explicitly requested by the user. If + the start-up was pulled in indirectly + by some dependency or automatic + start-up of units that is not + requested by the user this dependency + must be fulfilled and otherwise the + transaction fails. Hence, this option + may be used to configure dependencies + that are normally honored unless the + user explicitly starts up the unit, in + which case whether they failed or not + is irrelevant.</para></listitem> + + </varlistentry> + <varlistentry> + <term><varname>Requisite=</varname></term> + <term><varname>RequisiteOverridable=</varname></term> + + <listitem><para>Similar to + <varname>Requires=</varname> + resp. <varname>RequiresOverridable=</varname>. However, + if a unit listed here is not started + already it will not be started and the + transaction fails + immediately.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Wants=</varname></term> + + <listitem><para>A weaker version of + <varname>Requires=</varname>. 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. This is + the recommended way to hook start-up + of one unit to the start-up of another + unit. Note that dependencies of this + type may also be configured outside of + the unit configuration file by + adding a symlink to a + <filename>.wants/</filename> directory + accompanying the unit file. For + details see above.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>BindTo=</varname></term> + + <listitem><para>Configures requirement + dependencies, very similar in style to + <varname>Requires=</varname>, however + in addition to this behaviour it also + declares that this unit is stopped + when any of the units listed suddenly + disappears. Units can suddenly, + unexpectedly disappear if a service + terminates on its own choice, a device + is unplugged or a mount point + unmounted without involvement of + systemd.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Conflicts=</varname></term> + + <listitem><para>Configures negative + requirement dependencies. If a unit + has a + <varname>Conflicts=</varname> setting + on another unit, starting the former + will stop the latter and vice + versa. Note that this setting is + independent of and orthogonal to the + <varname>After=</varname> and + <varname>Before=</varname> ordering + dependencies.</para> + + <para>If a unit A that conflicts with + a unit B is scheduled to be started at + the same time as B, the transaction + will either fail (in case both are + required part of the transaction) or + be modified to be fixed (in case one + or both jobs are not a required part + of the transaction). In the latter + case the job that is not the required + will be removed, or in case both are + not required the unit that conflicts + will be started and the unit that is + conflicted is + stopped.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Before=</varname></term> + <term><varname>After=</varname></term> + + <listitem><para>Configures ordering + dependencies between units. If a unit + <filename>foo.service</filename> + contains a setting + <option>Before=bar.service</option> + and both units are being started, + <filename>bar.service</filename>'s + start-up is delayed until + <filename>foo.service</filename> is + started up. Note that this setting is + independent of and orthogonal to the + requirement dependencies as configured + by <varname>Requires=</varname>. It is + a common pattern to include a unit + name in both the + <varname>After=</varname> and + <varname>Requires=</varname> option in + which case the unit listed will be + started before the unit that is + configured with these options. This + option may be specified more than + once, in which case ordering + dependencies for all listed names are + created. <varname>After=</varname> is + the inverse of + <varname>Before=</varname>, i.e. while + <varname>After=</varname> ensures that + the configured unit is started after + the listed unit finished starting up, + <varname>Before=</varname> ensures the + opposite, i.e. that the configured + unit is fully started up before the + listed unit is started. Note that when + two units with an ordering dependency + between them are shut down, the + inverse of the start-up order is + applied. i.e. if a unit is configured + with <varname>After=</varname> on + another unit, the former is stopped + before the latter if both are shut + down. If one unit with an ordering + dependency on another unit is shut + down while the latter is started up, + the shut down is ordered before the + start-up regardless whether the + ordering dependency is actually of + type <varname>After=</varname> or + <varname>Before=</varname>. If two + units have no ordering dependencies + between them they are shut down + resp. started up simultaneously, and + no ordering takes + place. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>OnFailure=</varname></term> + + <listitem><para>Lists one or more + units that are activated when this + unit enters the + '<literal>failed</literal>' + state.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PropagateReloadTo=</varname></term> + <term><varname>PropagateReloadFrom=</varname></term> + + <listitem><para>Lists one or more + units where reload requests on the + unit will be propagated to/on the + other unit will be propagated + from. Issuing a reload request on a + unit will automatically also enqueue a + reload request on all units that the + reload request shall be propagated to + via these two + settings.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>OnFailureIsolate=</varname></term> + + <listitem><para>Takes a boolean + argument. If <option>true</option> the + unit listed in + <varname>OnFailure=</varname> will be + enqueued in isolation mode, i.e. all + units that are not its dependency will + be stopped. If this is set only a + single unit may be listed in + <varname>OnFailure=</varname>. Defaults + to + <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>IgnoreOnIsolate=</varname></term> + + <listitem><para>Takes a boolean + argument. If <option>true</option> + this unit will not be stopped when + isolating another unit. Defaults to + <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>IgnoreOnSnapshot=</varname></term> + + <listitem><para>Takes a boolean + argument. If <option>true</option> + this unit will not be included in + snapshots. Defaults to + <option>true</option> for device and + snapshot units, <option>false</option> + for the others.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>StopWhenUnneeded=</varname></term> + + <listitem><para>Takes a boolean + argument. If <option>true</option> + this unit will be stopped when it is + no longer used. Note that in order to + minimize the work to be executed, + systemd will not stop units by default + unless they are conflicting with other + units, or the user explicitly + requested their shut down. If this + option is set, a unit will be + automatically cleaned up if no other + active unit requires it. Defaults to + <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RefuseManualStart=</varname></term> + <term><varname>RefuseManualStop=</varname></term> + + <listitem><para>Takes a boolean + argument. If <option>true</option> + this unit can only be activated + (resp. deactivated) indirectly. In + this case explicit start-up + (resp. termination) requested by the + user is denied, however if it is + started (resp. stopped) as a + dependency of another unit, start-up + (resp. termination) will succeed. This + is mostly a safety feature to ensure + that the user does not accidentally + activate units that are not intended + to be activated explicitly, and not + accidentally deactivate units that are + not intended to be deactivated. + These options default to + <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>AllowIsolate=</varname></term> + + <listitem><para>Takes a boolean + argument. If <option>true</option> + this unit may be used with the + <command>systemctl isolate</command> + command. Otherwise this will be + refused. It probably is a good idea to + leave this disabled except for target + units that shall be used similar to + runlevels in SysV init systems, just + as a precaution to avoid unusable + system states. This option defaults to + <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DefaultDependencies=</varname></term> + + <listitem><para>Takes a boolean + argument. If <option>true</option> + (the default), a few default + dependencies will implicitly be + created for the unit. The actual + dependencies created depend on the + unit type. For example, for service + units, these dependencies ensure that + the service is started only after + basic system initialization is + completed and is properly terminated on + system shutdown. See the respective + man pages for details. Generally, only + services involved with early boot or + late shutdown should set this option + to <option>false</option>. It is + highly recommended to leave this + option enabled for the majority of + common units. If set to + <option>false</option> this option + does not disable all implicit + dependencies, just non-essential + ones.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>JobTimeoutSec=</varname></term> + + <listitem><para>When clients are + waiting for a job of this unit to + complete, time out after the specified + time. If this time limit is reached + the job will be cancelled, the unit + however will not change state or even + enter the '<literal>failed</literal>' + mode. This value defaults to 0 (job + timeouts disabled), except for device + units. NB: this timeout is independent + from any unit-specific timeout (for + example, the timeout set with + <varname>Timeout=</varname> in service + units) as the job timeout has no + effect on the unit itself, only on the + job that might be pending for it. Or + in other words: unit-specific timeouts + are useful to abort unit state + changes, and revert them. The job + timeout set with this option however + is useful to abort only the job + waiting for the unit state to + change.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ConditionPathExists=</varname></term> + <term><varname>ConditionPathExistsGlob=</varname></term> + <term><varname>ConditionPathIsDirectory=</varname></term> + <term><varname>ConditionPathIsSymbolicLink=</varname></term> + <term><varname>ConditionPathIsMountPoint=</varname></term> + <term><varname>ConditionDirectoryNotEmpty=</varname></term> + <term><varname>ConditionFileIsExecutable=</varname></term> + <term><varname>ConditionKernelCommandLine=</varname></term> + <term><varname>ConditionVirtualization=</varname></term> + <term><varname>ConditionSecurity=</varname></term> + <term><varname>ConditionCapability=</varname></term> + <term><varname>ConditionNull=</varname></term> + + <listitem><para>Before starting a unit + verify that the specified condition is + true. With + <varname>ConditionPathExists=</varname> + a file existence condition can be + checked before a unit is started. If + the specified absolute path name does + not exist, startup of a unit will not + actually happen, however the unit is + still useful for ordering purposes in + this case. The condition is checked at + the time the queued start job is to be + executed. If the absolute path name + passed to + <varname>ConditionPathExists=</varname> + is prefixed with an exclamation mark + (!), the test is negated, and the unit + is only started if the path does not + exist. + <varname>ConditionPathExistsGlob=</varname> + works in a similar way, but checks for + the existence of at least one file or + directory matching the specified + globbing + pattern. <varname>ConditionPathIsDirectory=</varname> + is similar to + <varname>ConditionPathExists=</varname> + but verifies whether a certain path + exists and is a + directory. <varname>ConditionPathIsSymbolicLink=</varname> + is similar to + <varname>ConditionPathExists=</varname> + but verifies whether a certain path + exists and is a symbolic + link. <varname>ConditionPathIsMountPoint=</varname> + is similar to + <varname>ConditionPathExists=</varname> + but verifies whether a certain path + exists and is a mount + point. <varname>ConditionFileIsExecutable=</varname> + is similar to + <varname>ConditionPathExists=</varname> + but verifies whether a certain path + exists, is a regular file and marked + executable. + <varname>ConditionDirectoryNotEmpty=</varname> + is similar to + <varname>ConditionPathExists=</varname> + but verifies whether a certain path + exists and is a non-empty + directory. Similarly + <varname>ConditionKernelCommandLine=</varname> + may be used to check whether a + specific kernel command line option is + set (or if prefixed with the + exclamation mark unset). The argument + must either be a single word, or an + assignment (i.e. two words, separated + by the equality sign). In the former + case the kernel command line is + searched for the word appearing as is, + or as left hand side of an + assignment. In the latter case the + exact assignment is looked for with + right and left hand side + matching. <varname>ConditionVirtualization=</varname> + may be used to check whether the + system is executed in a virtualized + environment and optionally test + whether it is a specific + implementation. Takes either boolean + value to check if being executed in + any virtualized environment, or one of + <varname>vm</varname> and + <varname>container</varname> to test + against a specific type of + virtualization solution, or one of + <varname>qemu</varname>, + <varname>kvm</varname>, + <varname>vmware</varname>, + <varname>microsoft</varname>, + <varname>oracle</varname>, + <varname>xen</varname>, + <varname>bochs</varname>, + <varname>chroot</varname>, + <varname>openvz</varname>, + <varname>lxc</varname>, + <varname>lxc-libvirt</varname>, + <varname>systemd-nspawn</varname> to test + against a specific implementation. If + multiple virtualization technologies + are nested only the innermost is + considered. The test may be negated by + prepending an exclamation mark. + <varname>ConditionSecurity=</varname> + may be used to check whether the given + security module is enabled on the + system. Currently the only recognized + value is <varname>selinux</varname>. + The test may be negated by prepending + an exclamation + mark. <varname>ConditionCapability=</varname> + may be used to check whether the given + capability exists in the capability + bounding set of the service manager + (i.e. this does not check whether + capability is actually available in + the permitted or effective sets, see + <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details). Pass a capability name + such as <literal>CAP_MKNOD</literal>, + possibly prefixed with an exclamation + mark to negate the check. Finally, + <varname>ConditionNull=</varname> may + be used to add a constant condition + check value to the unit. It takes a + boolean argument. If set to + <varname>false</varname> the condition + will always fail, otherwise + succeed. If multiple conditions are + specified the unit will be executed if + all of them apply (i.e. a logical AND + is applied). Condition checks can be + prefixed with a pipe symbol (|) in + which case a condition becomes a + triggering condition. If at least one + triggering condition is defined for a + unit then the unit will be executed if + at least one of the triggering + conditions apply and all of the + non-triggering conditions. If you + prefix an argument with the pipe + symbol and an exclamation mark the + pipe symbol must be passed first, the + exclamation second. Except for + <varname>ConditionPathIsSymbolicLink=</varname>, + all path checks follow + symlinks.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Names=</varname></term> + + <listitem><para>Additional names for + this unit. The names listed here must + have the same suffix (i.e. type) as + the unit file name. This option may be + specified more than once, in which + case all listed names are used. Note + that this option is different from the + <varname>Alias=</varname> option from + the [Install] section mentioned + below. See below for details. Note + that in almost all cases this option + is not what you want. A symlink alias + in the file system is generally + preferable since it can be used as + lookup key. If a unit with a symlinked + alias name is not loaded and needs to + be it is easily found via the + symlink. However, if a unit with an + alias name configured with this + setting is not loaded it will not be + discovered. This settings' only use is + in conjunction with service + instances.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>Unit file may include a [Install] section, which + carries installation information for the unit. This + section is not interpreted by + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + during runtime. It is used exclusively by the + <command>enable</command> and + <command>disable</command> commands of the + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + tool during installation of a unit:</para> + + <variablelist> + <varlistentry> + <term><varname>Alias=</varname></term> + + <listitem><para>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. This option may be specified + more than once, in which case all + listed names are used. At installation + time, + <command>systemctl enable</command> + will create symlinks from these names + to the unit file name. Note that this + is different from the + <varname>Names=</varname> option from + the [Unit] section mentioned above: + The names from + <varname>Names=</varname> apply + unconditionally if the unit is + loaded. The names from + <varname>Alias=</varname> apply only + if the unit has actually been + installed with the + <command>systemctl enable</command> + command. Also, if systemd searches for a + unit, it will discover symlinked alias + names as configured with + <varname>Alias=</varname>, but not + names configured with + <varname>Names=</varname> only. It is + a common pattern to list a name in + both options. In this case, a unit + will be active under all names if + installed, but also if not installed + but requested explicitly under its + main name.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>WantedBy=</varname></term> + + <listitem><para>Installs a symlink in + the <filename>.wants/</filename> + subdirectory for a unit. This has the + effect that when the listed unit name + is activated the unit listing it is + activated + too. <command>WantedBy=foo.service</command> + in a service + <filename>bar.service</filename> is + mostly equivalent to + <command>Alias=foo.service.wants/bar.service</command> + in the same file.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Also=</varname></term> + + <listitem><para>Additional units to + install when this unit is + installed. If the user requests + installation of a unit with this + option configured, + <command>systemctl enable</command> + will automatically install units + listed in this option as + well.</para></listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd.xml b/man/systemd.xml new file mode 100644 index 000000000..aef65e30c --- /dev/null +++ b/man/systemd.xml @@ -0,0 +1,1167 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd"> + + <refentryinfo> + <title>systemd</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd</refname> + <refname>init</refname> + <refpurpose>systemd System and Service Manager</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd <arg choice="opt" rep="repeat">OPTIONS</arg></command> + </cmdsynopsis> + <cmdsynopsis> + <command>init <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="req">COMMAND</arg></command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>systemd is a system and service manager for + Linux operating systems. When run as first process on + boot (as PID 1), it acts as init system that brings + up and maintains userspace services.</para> + + <para>For compatibility with SysV, if systemd is called + as <command>init</command> and a PID that is not + 1, it will execute <command>telinit</command> and pass + all command line arguments unmodified. That means + <command>init</command> and <command>telinit</command> + are mostly equivalent when invoked from normal login sessions. See + <citerefentry><refentrytitle>telinit</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for more information.</para> + + <para>When run as system instance, systemd interprets + the configuration file + <filename>system.conf</filename>, otherwise + <filename>user.conf</filename>. See + <citerefentry><refentrytitle>systemd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>-h</option></term> + <term><option>--help</option></term> + + <listitem><para>Prints a short help + text and exits.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--test</option></term> + + <listitem><para>Determine startup + sequence, dump it and exit. This is an + option useful for debugging + only.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--dump-configuration-items</option></term> + + <listitem><para>Dump understood unit + configuration items. This outputs a + terse but complete list of + configuration items understood in unit + definition files.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--introspect=</option></term> + + <listitem><para>Extract D-Bus + interface introspection data. This is + mostly useful at install time + to generate data suitable for the + D-Bus interfaces + repository. Optionally the interface + name for the introspection data may be + specified. If omitted, the + introspection data for all interfaces + is dumped.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--unit=</option></term> + + <listitem><para>Set default unit to + activate on startup. If not specified + defaults to + <filename>default.target</filename>.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--system</option></term> + <term><option>--user</option></term> + + <listitem><para>Tell systemd to run a + system instance (resp. user + instance), even if the process ID is + not 1 (resp. is 1), i.e. systemd is + not (resp. is) run as init process. + Normally it should not be necessary to + pass these options, as systemd + automatically detects the mode it is + started in. These options are hence of + little use except for debugging. Note + that it is not supported booting and + maintaining a full system with systemd + running in <option>--system</option> + mode, but PID not 1. In practice, + passing <option>--system</option> explicitly is + only useful in conjunction with + <option>--test</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--dump-core</option></term> + + <listitem><para>Dump core on + crash. This switch has no effect when + run as user + instance.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--crash-shell</option></term> + + <listitem><para>Run shell on + crash. This switch has no effect when + run as user + instance.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--confirm-spawn</option></term> + + <listitem><para>Ask for confirmation + when spawning processes. This switch + has no effect when run as user + instance.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--show-status=</option></term> + + <listitem><para>Show terse service + status information while booting. This + switch has no effect when run as user + instance. Takes a boolean argument + which may be omitted which is + interpreted as + <option>true</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--sysv-console=</option></term> + + <listitem><para>Controls whether + output of SysV init scripts will be + directed to the console. This switch + has no effect when run as user + instance. Takes a boolean argument + which may be omitted which is + interpreted as + <option>true</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--log-target=</option></term> + + <listitem><para>Set log + target. Argument must be one of + <option>console</option>, + <option>journal</option>, + <option>syslog</option>, + <option>kmsg</option>, + <option>journal-or-kmsg</option>, + <option>syslog-or-kmsg</option>, + <option>null</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--log-level=</option></term> + + <listitem><para>Set log level. As + argument this accepts a numerical log + level or the well-known <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> + symbolic names (lowercase): + <option>emerg</option>, + <option>alert</option>, + <option>crit</option>, + <option>err</option>, + <option>warning</option>, + <option>notice</option>, + <option>info</option>, + <option>debug</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--log-color=</option></term> + + <listitem><para>Highlight important + log messages. Argument is a boolean + value. If the argument is omitted it + defaults to + <option>true</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--log-location=</option></term> + + <listitem><para>Include code location + in log messages. This is mostly + relevant for debugging + purposes. Argument is a boolean + value. If the argument is omitted + it defaults to + <option>true</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--default-standard-output=</option></term> + <term><option>--default-standard-error=</option></term> + + <listitem><para>Sets the default + output resp. error output for all + services and sockets, i.e. controls + the default for + <option>StandardOutput=</option> + resp. <option>StandardError=</option> + (see + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details). Takes one of + <option>inherit</option>, + <option>null</option>, + <option>tty</option>, + <option>journal</option>, + <option>journal+console</option>, + <option>syslog</option>, + <option>syslog+console</option>, + <option>kmsg</option>, + <option>kmsg+console</option>. If the + argument is omitted + <option>--default-standard-output=</option> + defaults to <option>journal</option> + and + <option>--default-standard-error=</option> + to + <option>inherit</option>.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Concepts</title> + + <para>systemd provides a dependency system between + various entities called "units". Units encapsulate + various objects that are relevant for system boot-up + and maintenance. The majority of units are configured + in unit configuration files, whose syntax and basic + set of options is described in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + however some are created automatically from other + configuration or dynamically from system state. Units + may be 'active' (meaning started, bound, plugged in, + ... depending on the unit type, see below), or + 'inactive' (meaning stopped, unbound, unplugged, ...), + as well as in the process of being activated or + deactivated, i.e. between the two states (these states + are called 'activating', 'deactivating'). A special + 'failed' state is available as well which is very + similar to 'inactive' and is entered when the service + failed in some way (process returned error code on + exit, or crashed, or an operation timed out). If this + state is entered the cause will be logged, for later + reference. Note that the various unit types may have a + number of additional substates, which are mapped to + the five generalized unit states described + here.</para> + + <para>The following unit types are available:</para> + + <orderedlist> + <listitem><para>Service units, which control + daemons and the processes they consist of. For + details see + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Socket units, which + encapsulate local IPC or network sockets in + the system, useful for socket-based + activation. For details about socket units see + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + for details on socket-based activation and + other forms of activation, see + <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Target units are useful to + group units, or provide well-known + synchronization points during boot-up, see + <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Device units expose kernel + devices in systemd and may be used to + implement device-based activation. For details + see + <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Mount units control mount + points in the file system, for details see + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Automount units provide + automount capabilities, for on-demand mounting + of file systems as well as parallelized + boot-up. See + <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Snapshot units can be used to + temporarily save the state of the set of + systemd units, which later may be restored by + activating the saved snapshot unit. For more + information see + <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Timer units are useful for + triggering activation of other units based on + timers. You may find details in + <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Swap units are very similar to + mount units and encapsulate memory swap + partitions or files of the operating + system. They are described in <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Path units may be used + to activate other services when file system + objects change or are modified. See + <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + </orderedlist> + + <para>Units are named as their configuration + files. Some units have special semantics. A detailed + list is available in + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + + <para>systemd knows various kinds of dependencies, + including positive and negative requirement + dependencies (i.e. <varname>Requires=</varname> and + <varname>Conflicts=</varname>) as well as ordering + dependencies (<varname>After=</varname> and + <varname>Before=</varname>). NB: ordering and + requirement dependencies are orthogonal. If only a + requirement dependency exists between two units + (e.g. <filename>foo.service</filename> requires + <filename>bar.service</filename>), but no ordering + dependency (e.g. <filename>foo.service</filename> + after <filename>bar.service</filename>) and both are + requested to start, they will be started in + parallel. It is a common pattern that both requirement + and ordering dependencies are placed between two + units. Also note that the majority of dependencies are + implicitly created and maintained by systemd. In most + cases it should be unnecessary to declare additional + dependencies manually, however it is possible to do + this.</para> + + <para>Application programs and units (via + dependencies) may request state changes of units. In + systemd, these requests are encapsulated as 'jobs' and + maintained in a job queue. Jobs may succeed or can + fail, their execution is ordered based on the ordering + dependencies of the units they have been scheduled + for.</para> + + <para>On boot systemd activates the target unit + <filename>default.target</filename> whose job is to + activate on-boot services and other on-boot units by + pulling them in via dependencies. Usually the unit + name is just an alias (symlink) for either + <filename>graphical.target</filename> (for + fully-featured boots into the UI) or + <filename>multi-user.target</filename> (for limited + console-only boots for use in embedded or server + environments, or similar; a subset of + graphical.target). However it is at the discretion of + the administrator to configure it as an alias to any + other target unit. See + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details about these target units.</para> + + <para>Processes systemd spawns are placed in + individual Linux control groups named after the unit + which they belong to in the private systemd + hierarchy. (see <ulink + url="http://www.kernel.org/doc/Documentation/cgroups/cgroups.txt">cgroups.txt</ulink> + for more information about control groups, or short + "cgroups"). systemd uses this to effectively keep + track of processes. Control group information is + maintained in the kernel, and is accessible via the + file system hierarchy (beneath + <filename>/sys/fs/cgroup/systemd/</filename>), or in tools + such as + <citerefentry><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry> + (<command>ps xawf -eo pid,user,cgroup,args</command> + is particularly useful to list all processes and the + systemd units they belong to.).</para> + + <para>systemd is compatible with the SysV init system + to a large degree: SysV init scripts are supported and + simply read as an alternative (though limited) + configuration file format. The SysV + <filename>/dev/initctl</filename> interface is + provided, and compatibility implementations of the + various SysV client tools are available. In addition to + that, various established Unix functionality such as + <filename>/etc/fstab</filename> or the + <filename>utmp</filename> database are + supported.</para> + + <para>systemd has a minimal transaction system: if a + unit is requested to start up or shut down it will add + it and all its dependencies to a temporary + transaction. Then, it will verify if the transaction + is consistent (i.e. whether the ordering of all units + is cycle-free). If it is not, systemd will try to fix + it up, and removes non-essential jobs from the + transaction that might remove the loop. Also, systemd + tries to suppress non-essential jobs in the + transaction that would stop a running service. Finally + it is checked whether the jobs of the transaction + contradict jobs that have already been queued, and + optionally the transaction is aborted then. If all + worked out and the transaction is consistent and + minimized in its impact it is merged with all already + outstanding jobs and added to the run + queue. Effectively this means that before executing a + requested operation, systemd will verify that it makes + sense, fixing it if possible, and only failing if it + really cannot work.</para> + + <para>Systemd contains native implementations of + various tasks that need to be executed as part of the + boot process. For example, it sets the host name or + configures the loopback network device. It also sets + up and mounts various API file systems, such as + <filename>/sys</filename> or + <filename>/proc</filename>.</para> + + <para>For more information about the concepts and + ideas behind systemd please refer to the <ulink + url="http://0pointer.de/blog/projects/systemd.html">Original + Design Document</ulink>.</para> + + <para>Note that some but not all interfaces provided + by systemd are covered by the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise">Interface + Stability Promise</ulink>.</para> + </refsect1> + + <refsect1> + <title>Directories</title> + + <variablelist> + <varlistentry> + <term>System unit directories</term> + + <listitem><para>The systemd system + manager reads unit configuration from + various directories. Packages that + want to install unit files shall place + them in the directory returned by + <command>pkg-config systemd + --variable=systemdsystemunitdir</command>. Other + directories checked are + <filename>/usr/local/lib/systemd/system</filename> + and + <filename>/usr/lib/systemd/system</filename>. User + configuration always takes + precedence. <command>pkg-config + systemd + --variable=systemdsystemconfdir</command> + returns the path of the system + configuration directory. Packages + should alter the content of these + directories only with the + <command>enable</command> and + <command>disable</command> commands of + the + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + tool.</para></listitem> + </varlistentry> + </variablelist> + + <variablelist> + <varlistentry> + <term>User unit directories</term> + + <listitem><para>Similar rules apply + for the user unit + directories. However, here the <ulink + url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG + Base Directory specification</ulink> + is followed to find + units. Applications should place their + unit files in the directory returned + by <command>pkg-config systemd + --variable=systemduserunitdir</command>. Global + configuration is done in the directory + reported by <command>pkg-config + systemd + --variable=systemduserconfdir</command>. The + <command>enable</command> and + <command>disable</command> commands of + the + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + tool can handle both global (i.e. for + all users) and private (for one user) + enabling/disabling of + units.</para></listitem> + </varlistentry> + </variablelist> + + <variablelist> + <varlistentry> + <term>SysV init scripts directory</term> + + <listitem><para>The location of the + SysV init script directory varies + between distributions. If systemd + cannot find a native unit file for a + requested service, it will look for a + SysV init script of the same name + (with the + <filename>.service</filename> suffix + removed).</para></listitem> + </varlistentry> + </variablelist> + + <variablelist> + <varlistentry> + <term>SysV runlevel link farm directory</term> + + <listitem><para>The location of the + SysV runlevel link farm directory + varies between distributions. systemd + will take the link farm into account + when figuring out whether a service + shall be enabled. Note that a service + unit with a native unit configuration + file cannot be started by activating it + in the SysV runlevel link + farm.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Signals</title> + + <variablelist> + <varlistentry> + <term>SIGTERM</term> + + <listitem><para>Upon receiving this + signal the systemd system manager + serializes its state, reexecutes + itself and deserializes the saved + state again. This is mostly equivalent + to <command>systemctl + daemon-reexec</command>.</para> + + <para>systemd user managers will + start the + <filename>exit.target</filename> unit + when this signal is received. This is + mostly equivalent to + <command>systemctl --user start + exit.target</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term>SIGINT</term> + + <listitem><para>Upon receiving this + signal the systemd system manager will + start the + <filename>ctrl-alt-del.target</filename> unit. This + is mostly equivalent to + <command>systemctl start + ctl-alt-del.target</command>.</para> + + <para>systemd user managers + treat this signal the same way as + SIGTERM.</para></listitem> + </varlistentry> + + <varlistentry> + <term>SIGWINCH</term> + + <listitem><para>When this signal is + received the systemd system manager + will start the + <filename>kbrequest.target</filename> + unit. This is mostly equivalent to + <command>systemctl start + kbrequest.target</command>.</para> + + <para>This signal is ignored by + systemd user + managers.</para></listitem> + </varlistentry> + + <varlistentry> + <term>SIGPWR</term> + + <listitem><para>When this signal is + received the systemd manager + will start the + <filename>sigpwr.target</filename> + unit. This is mostly equivalent to + <command>systemctl start + sigpwr.target</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term>SIGUSR1</term> + + <listitem><para>When this signal is + received the systemd manager will try + to reconnect to the D-Bus + bus.</para></listitem> + </varlistentry> + + <varlistentry> + <term>SIGUSR2</term> + + <listitem><para>When this signal is + received the systemd manager will log + its complete state in human readable + form. The data logged is the same as + printed by <command>systemctl + dump</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term>SIGHUP</term> + + <listitem><para>Reloads the complete + daemon configuration. This is mostly + equivalent to <command>systemctl + daemon-reload</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term>SIGRTMIN+0</term> + + <listitem><para>Enters default mode, starts the + <filename>default.target</filename> + unit. This is mostly equivalent to + <command>systemctl start + default.target</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term>SIGRTMIN+1</term> + + <listitem><para>Enters rescue mode, + starts the + <filename>rescue.target</filename> + unit. This is mostly equivalent to + <command>systemctl isolate + rescue.target</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term>SIGRTMIN+2</term> + + <listitem><para>Enters emergency mode, + starts the + <filename>emergency.service</filename> + unit. This is mostly equivalent to + <command>systemctl isolate + emergency.service</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term>SIGRTMIN+3</term> + + <listitem><para>Halts the machine, + starts the + <filename>halt.target</filename> + unit. This is mostly equivalent to + <command>systemctl start + halt.target</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term>SIGRTMIN+4</term> + + <listitem><para>Powers off the machine, + starts the + <filename>poweroff.target</filename> + unit. This is mostly equivalent to + <command>systemctl start + poweroff.target</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term>SIGRTMIN+5</term> + + <listitem><para>Reboots the machine, + starts the + <filename>reboot.target</filename> + unit. This is mostly equivalent to + <command>systemctl start + reboot.target</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term>SIGRTMIN+6</term> + + <listitem><para>Reboots the machine via kexec, + starts the + <filename>kexec.target</filename> + unit. This is mostly equivalent to + <command>systemctl start + kexec.target</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term>SIGRTMIN+13</term> + + <listitem><para>Immediately halts the machine.</para></listitem> + </varlistentry> + + <varlistentry> + <term>SIGRTMIN+14</term> + + <listitem><para>Immediately powers off the machine.</para></listitem> + </varlistentry> + + <varlistentry> + <term>SIGRTMIN+15</term> + + <listitem><para>Immediately reboots the machine.</para></listitem> + </varlistentry> + + <varlistentry> + <term>SIGRTMIN+16</term> + + <listitem><para>Immediately reboots the machine with kexec.</para></listitem> + </varlistentry> + + <varlistentry> + <term>SIGRTMIN+20</term> + + <listitem><para>Enables display of + status messages on the console, as + controlled via + <varname>systemd.show_status=1</varname> + on the kernel command + line.</para></listitem> + </varlistentry> + + <varlistentry> + <term>SIGRTMIN+21</term> + + <listitem><para>Disables display of + status messages on the console, as + controlled via + <varname>systemd.show_status=0</varname> + on the kernel command + line.</para></listitem> + </varlistentry> + + <varlistentry> + <term>SIGRTMIN+22</term> + <term>SIGRTMIN+23</term> + + <listitem><para>Sets the log level to + <literal>debug</literal> + (resp. <literal>info</literal> on + <literal>SIGRTMIN+23</literal>), as + controlled via + <varname>systemd.log_level=debug</varname> + (resp. <varname>systemd.log_level=info</varname> + on <literal>SIGRTMIN+23</literal>) on + the kernel command + line.</para></listitem> + </varlistentry> + + <varlistentry> + <term>SIGRTMIN+26</term> + <term>SIGRTMIN+27</term> + <term>SIGRTMIN+28</term> + <term>SIGRTMIN+29</term> + + <listitem><para>Sets the log level to + <literal>journal-or-kmsg</literal> + (resp. <literal>console</literal> on + <literal>SIGRTMIN+27</literal>; + resp. <literal>kmsg</literal> on + <literal>SIGRTMIN+28</literal>; + resp. <literal>syslog-or-kmsg</literal> + on <literal>SIGRTMIN+29</literal>), as + controlled via + <varname>systemd.log_target=journal-or-kmsg</varname> + (resp. <varname>systemd.log_target=console</varname> + on <literal>SIGRTMIN+27</literal>; + resp. <varname>systemd.log_target=kmsg</varname> + on <literal>SIGRTMIN+28</literal>; + resp + <varname>systemd.log_target=syslog-or-kmsg</varname> + on <literal>SIGRTMIN+29</literal>) on + the kernel command + line.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Environment</title> + + <variablelist> + <varlistentry> + <term><varname>$SYSTEMD_LOG_LEVEL</varname></term> + <listitem><para>systemd reads the + log level from this environment + variable. This can be overridden with + <option>--log-level=</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$SYSTEMD_LOG_TARGET</varname></term> + <listitem><para>systemd reads the + log target from this environment + variable. This can be overridden with + <option>--log-target=</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$SYSTEMD_LOG_COLOR</varname></term> + <listitem><para>Controls whether + systemd highlights important log + messages. This can be overridden with + <option>--log-color=</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$SYSTEMD_LOG_LOCATION</varname></term> + <listitem><para>Controls whether + systemd prints the code location along + with log messages. This can be + overridden with + <option>--log-location=</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$XDG_CONFIG_HOME</varname></term> + <term><varname>$XDG_CONFIG_DIRS</varname></term> + <term><varname>$XDG_DATA_HOME</varname></term> + <term><varname>$XDG_DATA_DIRS</varname></term> + + <listitem><para>The systemd user + manager uses these variables in + accordance to the <ulink + url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG + Base Directory specification</ulink> + to find its configuration.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$SYSTEMD_UNIT_PATH</varname></term> + + <listitem><para>Controls where systemd + looks for unit + files.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$SYSTEMD_SYSVINIT_PATH</varname></term> + + <listitem><para>Controls where systemd + looks for SysV init scripts.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$SYSTEMD_SYSVRCND_PATH</varname></term> + + <listitem><para>Controls where systemd + looks for SysV init script runlevel link + farms.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$LISTEN_PID</varname></term> + <term><varname>$LISTEN_FDS</varname></term> + + <listitem><para>Set by systemd for + supervised processes during + socket-based activation. See + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for more information. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$NOTIFY_SOCKET</varname></term> + + <listitem><para>Set by systemd for + supervised processes for status and + start-up completion notification. See + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for more information. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Kernel Command Line</title> + + <para>When run as system instance systemd parses a + number of kernel command line + arguments<footnote><para>If run inside a Linux + container these arguments may be passed as command + line arguments to systemd itself, next to any of the + command line options listed in the Options section + above. If run outside of Linux containers, these + arguments are parsed from + <filename>/proc/cmdline</filename> + instead.</para></footnote>:</para> + + <variablelist> + <varlistentry> + <term><varname>systemd.unit=</varname></term> + + <listitem><para>Overrides the unit to + activate on boot. Defaults to + <filename>default.target</filename>. This + may be used to temporarily boot into a + different boot unit, for example + <filename>rescue.target</filename> or + <filename>emergency.service</filename>. See + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details about these + units.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.dump_core=</varname></term> + + <listitem><para>Takes a boolean + argument. If <option>true</option> + systemd dumps core when it + crashes. Otherwise no core dump is + created. Defaults to + <option>true</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.crash_shell=</varname></term> + + <listitem><para>Takes a boolean + argument. If <option>true</option> + systemd spawns a shell when it + crashes. Otherwise no shell is + spawned. Defaults to + <option>false</option>, for security + reasons, as the shell is not protected + by any password + authentication.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.crash_chvt=</varname></term> + + <listitem><para>Takes an integer + argument. If positive systemd + activates the specified virtual + terminal when it crashes. Defaults to + <literal>-1</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.confirm_spawn=</varname></term> + + <listitem><para>Takes a boolean + argument. If <option>true</option> + asks for confirmation when spawning + processes. Defaults to + <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.show_status=</varname></term> + + <listitem><para>Takes a boolean + argument. If <option>true</option> + shows terse service status updates on + the console during bootup. Defaults to + <option>true</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.sysv_console=</varname></term> + + <listitem><para>Takes a boolean + argument. If <option>true</option> + output of SysV init scripts will be + directed to the console. Defaults to + <option>true</option>, unless + <option>quiet</option> is passed as + kernel command line option in which + case it defaults to + <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.log_target=</varname></term> + <term><varname>systemd.log_level=</varname></term> + <term><varname>systemd.log_color=</varname></term> + <term><varname>systemd.log_location=</varname></term> + + <listitem><para>Controls log output, + with the same effect as the + <varname>$SYSTEMD_LOG_TARGET</varname>, <varname>$SYSTEMD_LOG_LEVEL</varname>, <varname>$SYSTEMD_LOG_COLOR</varname>, <varname>$SYSTEMD_LOG_LOCATION</varname> + environment variables described above.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.default_standard_output=</varname></term> + <term><varname>systemd.default_standard_error=</varname></term> + <listitem><para>Controls default + standard output/error output for + services, with the same effect as the + <option>--default-standard-output=</option> + resp. <option>--default-standard-error=</option> + command line arguments described + above.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.setenv=</varname></term> + + <listitem><para>Takes a string + argument in the form + VARIABLE=VALUE. May be used to set + environment variables for the init + process and all its children at boot + time. May be used more than once to + set multiple variables. If the equal + sign and variable are missing unsets + an environment variable which might be + passed in from the initial ram + disk.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Sockets and FIFOs</title> + + <variablelist> + <varlistentry> + <term><filename>/run/systemd/notify</filename></term> + + <listitem><para>Daemon status + notification socket. This is an + AF_UNIX datagram socket and is used to + implement the daemon notification + logic as implemented by + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> + + </varlistentry> + + <varlistentry> + <term><filename>/run/systemd/shutdownd</filename></term> + + <listitem><para>Used internally by the + <citerefentry><refentrytitle>shutdown</refentrytitle><manvolnum>8</manvolnum></citerefentry> + tool to implement delayed + shutdowns. This is an AF_UNIX datagram + socket.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/run/systemd/private</filename></term> + + <listitem><para>Used internally as + communication channel between + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + and the systemd process. This is an + AF_UNIX stream socket. This interface + is private to systemd and should not + be used in external + projects.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/dev/initctl</filename></term> + + <listitem><para>Limited compatibility + support for the SysV client interface, + as implemented by the + <filename>systemd-initctl.service</filename> + unit. This is a named pipe in the file + system. This interface is obsolete and + should not be used in new + applications.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemadm</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-notify</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/telinit.xml b/man/telinit.xml new file mode 100644 index 000000000..fec059aa6 --- /dev/null +++ b/man/telinit.xml @@ -0,0 +1,195 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="telinit"> + + <refentryinfo> + <title>telinit</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>telinit</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>telinit</refname> + <refpurpose>Change SysV runlevel</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>telinit <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="req">COMMAND</arg></command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>telinit</command> may be used to change + the SysV system runlevel. Since the concept of SysV + runlevels is obsolete the runlevel requests + will be transparently translated into systemd unit + activation requests.</para> + + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--help</option></term> + + <listitem><para>Prints a short help + text and exits.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--no-wall</option></term> + + <listitem><para>Don't send wall + message before + reboot/halt/power-off.</para></listitem> + </varlistentry> + </variablelist> + + <para>The following commands are understood:</para> + + <variablelist> + <varlistentry> + <term><command>0</command></term> + + <listitem><para>Power-off the + machine. This is translated into an + activation request for + <filename>poweroff.target</filename> + and is equivalent to + <command>systemctl + poweroff</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>6</command></term> + + <listitem><para>Reboot the + machine. This is translated into an + activation request for + <filename>reboot.target</filename> and + is equivalent to <command>systemctl + reboot</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>2</command></term> + <term><command>3</command></term> + <term><command>4</command></term> + <term><command>5</command></term> + + <listitem><para>Change the SysV + runlevel. This is translated into an + activation request for + <filename>runlevel2.target</filename>, + <filename>runlevel3.target</filename>, + ... and is equivalent to + <command>systemctl isolate + runlevel2.target</command>, + <command>systemctl isolate + runlevel3.target</command>, + ...</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>1</command></term> + <term><command>s</command></term> + <term><command>S</command></term> + + <listitem><para>Change into system + rescue mode. This is translated into + an activation request for + <filename>rescue.target</filename> and + is equivalent to <command>systemctl + rescue</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>q</command></term> + <term><command>Q</command></term> + + <listitem><para>Reload daemon + configuration. This is equivalent to + <command>systemctl + daemon-reload</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>u</command></term> + <term><command>U</command></term> + + <listitem><para>Serialize state, + reexecute daemon and deserialize state + again. This is equivalent to + <command>systemctl + daemon-reexec</command>.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success 0 is returned, a non-zero failure + code otherwise.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>This is a legacy command available for compatibility + only. It should not be used anymore, as the concept of + runlevels is obsolete.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/timezone.xml b/man/timezone.xml new file mode 100644 index 000000000..4e3327915 --- /dev/null +++ b/man/timezone.xml @@ -0,0 +1,90 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="timezone"> + <refentryinfo> + <title>/etc/timezone</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>timezone</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>timezone</refname> + <refpurpose>Local time zone configuration file</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/timezone</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <filename>/etc/timezone</filename> file + configures the system-wide time zone of the local + system that is used by applications for presentation + to the user. It should contain a single + newline-terminated line consisting of a time zone + identifier such as + <literal>Europe/Berlin</literal>. The file + <filename>/etc/localtime</filename> corresponds with + <filename>/etc/timezone</filename> and contains the + binary time zone data for the time zone. These files + should always be changed simultaneously and kept in + sync.</para> + + <para>The time zone may be overridden for individual + programs by using the TZ environment variable. See + <citerefentry><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>History</title> + + <para>The simple configuration file format of + <filename>/etc/timezone</filename> originates from + Debian GNU/Linux.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/tmpfiles.d.xml b/man/tmpfiles.d.xml new file mode 100644 index 000000000..f70bf0ef9 --- /dev/null +++ b/man/tmpfiles.d.xml @@ -0,0 +1,300 @@ +<?xml version="1.0"?> +<!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- + This file is part of systemd. + + Copyright 2010 Brandon Philips + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> +<refentry id="tmpfiles.d"> + + <refentryinfo> + <title>tmpfiles.d</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Documentation</contrib> + <firstname>Brandon</firstname> + <surname>Philips</surname> + <email>brandon@ifup.org</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>tmpfiles.d</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>tmpfiles.d</refname> + <refpurpose>Configuration for creation, deletion and + cleaning of volatile and temporary files</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/tmpfiles.d/*.conf</filename></para> + <para><filename>/run/tmpfiles.d/*.conf</filename></para> + <para><filename>/usr/lib/tmpfiles.d/*.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-tmpfiles</command> uses the + configuration files from the above directories to describe the + creation, cleaning and removal of volatile and + temporary files and directories which usually reside + in directories such as <filename>/run</filename> + or <filename>/tmp</filename>.</para> + </refsect1> + + <refsect1> + <title>Configuration Format</title> + + <para>Each configuration file is named in the style of + <filename><program>.conf</filename>. Files in + <filename>/etc/</filename> override files with the + same name in <filename>/usr/lib/</filename>. Files in + <filename>/run</filename> override files with the same + name in <filename>/etc/</filename> and + <filename>/usr/lib/</filename>. Packages should + install their configuration files in + <filename>/usr/lib/</filename>, files in + <filename>/etc/</filename> are reserved for the local + administrator, who may choose to override the + configurations installed from packages. The list of + configuration files are sorted by their filename in + alphabetical order, regardless in which of the + directories they reside, to guarantee that a + configuration file takes precedence over another + configuration file with an alphabetically later + name.</para> + + <para>The configuration format is one line per path + containing action, path, mode, ownership, age and argument + fields:</para> + + <programlisting>Type Path Mode UID GID Age Argument +d /run/user 0755 root root 10d - +L /tmp/foobar - - - - /dev/null</programlisting> + + <refsect2> + <title>Type</title> + <variablelist> + <varlistentry> + <term><varname>f</varname></term> + <listitem><para>Create a file if it doesn't exist yet (optionally writing a short string into it, if the argument parameter is passed)</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>F</varname></term> + <listitem><para>Create or truncate a file (optionally writing a short string into it, if the argument parameter is passed)</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>w</varname></term> + <listitem><para>Write the argument parameter to a file, if it exists.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>d</varname></term> + <listitem><para>Create a directory if it doesn't exist yet</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>D</varname></term> + <listitem><para>Create or empty a directory</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>p</varname></term> + <listitem><para>Create a named pipe (FIFO) if it doesn't exist yet</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>L</varname></term> + <listitem><para>Create a symlink if it doesn't exist yet</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>c</varname></term> + <listitem><para>Create a character device node if it doesn't exist yet</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>b</varname></term> + <listitem><para>Create a block device node if it doesn't exist yet</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>x</varname></term> + <listitem><para>Ignore a path + during cleaning. Use this type + to exclude paths from clean-up + as controlled with the Age + parameter. Note that lines of + this type do not influence the + effect of r or R lines. Lines + of this type accept + shell-style globs in place of + of normal path + names.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>r</varname></term> + <listitem><para>Remove a file + or directory if it + exists. This may not be used + to remove non-empty + directories, use R for + that. Lines of this type + accept shell-style globs in + place of normal path + names.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>R</varname></term> + <listitem><para>Recursively + remove a path and all its + subdirectories (if it is a + directory). Lines of this type + accept shell-style globs in + place of normal path + names.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>z</varname></term> + <listitem><para>Restore + SELinux security context label + and set ownership and access + mode of a file or directory if + it exists. Lines of this type + accept shell-style globs in + place of normal path names. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Z</varname></term> + <listitem><para>Recursively + restore SELinux security + context label and set + ownership and access mode of a + path and all its + subdirectories (if it is a + directory). Lines of this type + accept shell-style globs in + place of normal path + names.</para></listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2> + <title>Mode</title> + + <para>The file access mode to use when + creating this file or directory. If omitted or + when set to - the default is used: 0755 for + directories, 0644 for all other file + objects. For z, Z lines if omitted or when set + to - the file access mode will not be + modified. This parameter is ignored for x, r, + R, L lines.</para> + </refsect2> + + <refsect2> + <title>UID, GID</title> + + <para>The user and group to use for this file + or directory. This may either be a numeric + user/group ID or a user or group name. If + omitted or when set to - the default 0 (root) + is used. For z, Z lines when omitted or when set to - + the file ownership will not be modified. + These parameters are ignored for x, r, R, L lines.</para> + </refsect2> + + <refsect2> + <title>Age</title> + <para>The date field, when set, is used to + decide what files to delete when cleaning. If + a file or directory is older than the current + time minus the age field it is deleted. The + field format is a series of integers each + followed by one of the following + postfixes for the respective time units:</para> + + <variablelist> + <varlistentry> + <term><varname>s</varname></term> + <term><varname>min</varname></term> + <term><varname>h</varname></term> + <term><varname>d</varname></term> + <term><varname>w</varname></term> + <term><varname>ms</varname></term> + <term><varname>m</varname></term> + <term><varname>us</varname></term></varlistentry> + </variablelist> + + <para>If multiple integers and units are specified the time + values are summed up.</para> + + <para>The age field only applies to lines starting with + d, D and x. If omitted or set to - no automatic clean-up + is done.</para> + </refsect2> + + <refsect2> + <title>Argument</title> + + <para>For L lines determines the destination + path of the symlink. For c, b determines the + major/minor of the device node, with major and + minor formatted as integers, separated by :, + e.g. "1:3". For f, F, w may be used to specify + a short string that is written to the file, + suffixed by a newline. Ignored for all other + lines.</para> + </refsect2> + + </refsect1> + + <refsect1> + <title>Example</title> + <example> + <title>/etc/tmpfiles.d/screen.conf example</title> + <para><command>screen</command> needs two directories created at boot with specific modes and ownership.</para> + + <programlisting>d /var/run/screens 1777 root root 10d +d /var/run/uscreens 0755 root root 10d12h</programlisting> + </example> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-tmpfiles</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/vconsole.conf.xml b/man/vconsole.conf.xml new file mode 100644 index 000000000..a73db00d1 --- /dev/null +++ b/man/vconsole.conf.xml @@ -0,0 +1,146 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + 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 + (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. + + You should have received a copy of the GNU General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="vconsole.conf"> + <refentryinfo> + <title>vconsole.conf</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>vconsole.conf</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>vconsole.conf</refname> + <refpurpose>configuration file for the virtual console</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/vconsole.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <filename>/etc/vconsole.conf</filename> file + configures the virtual console, i.e. keyboard mapping + and console font.</para> + + <para>The basic file format of the + <filename>vconsole.conf</filename> is a + newline-separated list environment-like + shell-compatible variable assignments. It is possible + to source the configuration from shell scripts, + however, beyond mere variable assignments no shell + features are supported, allowing applications to read + the file without implementing a shell compatible + execution engine.</para> + + <para>Note that the kernel command line options + <varname>vconsole.keymap=</varname>, + <varname>vconsole.keymap.toggle=</varname>, + <varname>vconsole.font=</varname>, + <varname>vconsole.font.map=</varname>, + <varname>vconsole.font.unimap=</varname> may be used + to override the console settings at boot.</para> + + <para>Depending on the operating system other + configuration files might be checked for configuration + of the virtual console as well, however only as + fallback.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + + <varlistentry> + <term><varname>KEYMAP=</varname></term> + <term><varname>KEYMAP_TOGGLE=</varname></term> + + <listitem><para>Configures the key + mapping table of for they + keyboard. <varname>KEYMAP=</varname> + defaults to <literal>us</literal> if + not set. The + <varname>KEYMAP_TOGGLE=</varname> can + be used to configured a second toggle + keymap and is by default + unset.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>FONT=</varname></term> + <term><varname>FONT_MAP=</varname></term> + <term><varname>FONT_UNIMAP=</varname></term> + + <listitem><para>Configures the console + font, the console map and the unicode + font map. <varname>FONT=</varname> + defaults to + <literal>latarcyrheb-sun16</literal>.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Example</title> + + <example> + <title>German keyboard and console</title> + + <para><filename>/etc/vconsole.conf:</filename></para> + + <programlisting>KEYMAP=de-latin1 +FONT=latarcyrheb-sun16</programlisting> + </example> + + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>loadkeys</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>setfont</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> |