diff options
Diffstat (limited to 'man')
124 files changed, 29300 insertions, 0 deletions
diff --git a/man/.gitignore b/man/.gitignore new file mode 100644 index 0000000000..cf8c17cb95 --- /dev/null +++ b/man/.gitignore @@ -0,0 +1 @@ +/systemd.directives.xml diff --git a/man/Makefile b/man/Makefile new file mode 120000 index 0000000000..bd1047548b --- /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 0000000000..07ae0ac231 --- /dev/null +++ b/man/binfmt.d.xml @@ -0,0 +1,124 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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 for + executables 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>At boot, + <citerefentry><refentrytitle>systemd-binfmt.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + reads configuration files from the above directories + to register in the kernel additional binary + formats for executables.</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 shall be 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> + and <filename>/run/</filename>. Files in + <filename>/run/</filename> override files with the + same name in <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 files installed from vendor + packages. All files are sorted by their filename 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 later name.</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/binfmt.d/</filename> bearing the + same file 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>systemd-binfmt.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-delta</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>wine</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/bootup.xml b/man/bootup.xml new file mode 100644 index 0000000000..4cc4bafab7 --- /dev/null +++ b/man/bootup.xml @@ -0,0 +1,226 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="bootup"> + + <refentryinfo> + <title>bootup</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>bootup</refentrytitle> + <manvolnum>7</manvolnum> + </refmeta> + + <refnamediv> + <refname>bootup</refname> + <refpurpose>System bootup process</refpurpose> + </refnamediv> + + <refsect1> + <title>Description</title> + + <para>A number of different components are involved in the + system boot. Immediately after power-up, the system + BIOS will do minimal hardware initialization, and hand + control over to a boot loader stored on a persistent + storage device. This boot loader will then invoke an + OS kernel from disk (or the network). In the Linux + case this kernel now (optionally) extracts and + executes an initial RAM disk image (initrd) such as + <citerefentry><refentrytitle>dracut</refentrytitle><manvolnum>8</manvolnum></citerefentry> + which looks for the root file system. After the root + file system is found and mounted the initrd hands over + control to the system manager (such as + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>) + stored on the OS image which is then responsible for + probing all remaining hardware, mounting all necessary + file systems and spawning all configured + services.</para> + + <para>On shutdown the system manager stops all + services, unmounts all file systems (detaching the + storage technologies backing them), and then + (optionally) jumps back into the initrd code which + unmounts/detaches the root file system and the storage + it resides on. As last step the system is powered down.</para> + + <para>Additional information about the system boot + process may be found in + <citerefentry><refentrytitle>boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>System Manager Bootup</title> + + <para>At boot, the system manager on the OS image is + responsible for initializing the required file + systems, services and drivers that are necessary for + operation of the system. On + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + systems this process is split up in various discrete + steps which are exposed as target units. (See + <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for detailed information about target units.) The + boot-up process is highly parallelized so that the + order in which specific target units are reached is not + deterministic, but still adheres to a limited amount + of ordering structure.</para> + + <para>When systemd starts up the system it will + activate all units that are dependencies of + <filename>default.target</filename> (as well as + recursively all dependencies of these + dependencies). Usually + <filename>default.target</filename> is simply an alias + of <filename>graphical.target</filename> or + <filename>multi-user.target</filename> depending on + whether the system is configured for a graphical UI or + only for a text console. To enforce minimal ordering + between the units pulled in a number of well-known + target units are available, as listed on + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + + <para>The following chart is a structural overview of + these well-known units and their position in the + boot-up logic. The arrows describe which units are + pulled in and ordered before which other units. Units + near the top are started before units nearer to the + bottom of the chart.</para> + +<programlisting>local-fs-pre.target + | + v +(various mounts and (various swap (various cryptsetup + fsck services...) devices...) devices...) (various low-level (various low-level + | | | services: udevd, API VFS mounts: + v v v tmpfiles, random mqueue, configfs, + local-fs.target swap.target cryptsetup.target seed, sysctl, ...) debugfs, ...) + | | | | | + \__________________|_________________ | ___________________|____________________/ + \|/ + v + sysinit.target + | + _________________/|\___________________ + / | \ + | | | + v | v + (various | rescue.service + sockets...) | | + | | v + v | <emphasis>rescue.target</emphasis> + sockets.target | + | | + \_________________ | + \| + v + basic.target + | + __________________________________/| emergency.service + / | | | + | | | v + v v v <emphasis>emergency.target</emphasis> + display- (various system (various system + manager.service services services) + | required for | + | graphical UIs) v + | | <emphasis>multi-user.target</emphasis> + | | | + \_______________ | _________________/ + \|/ + v + <emphasis>graphical.target</emphasis></programlisting> + + <para>Target units that are commonly used as boot + targets are <emphasis>emphasized</emphasis>. These + units are good choices as goal targets, for + example by passing them to the + <varname>systemd.unit=</varname> kernel command line + option (see + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>) + or by symlinking <filename>default.target</filename> + to them.</para> + </refsect1> + + <refsect1> + <title>System Manager Shutdown</title> + + <para>System shutdown also consists of various target + units with some minimal ordering structure + applied:</para> + + + + +<programlisting> (conflicts with (conflicts with + all system all file system + services) mounts, swaps, + | cryptsetup + | devices, ...) + | | + v v + shutdown.target umount.target + | | + \_______ ______/ + \ / + v + (various low-level + services) + | + v + final.target + | + _____________________________________/ \_________________________________ + / | | \ + | | | | + v v v v +systemd-reboot.service systemd-poweroff.service systemd-halt.service systemd-kexec.service + | | | | + v v v v + <emphasis>reboot.target</emphasis> <emphasis>poweroff.target</emphasis> <emphasis>halt.target</emphasis> <emphasis>kexec.target</emphasis></programlisting> + + <para>Commonly used system shutdown targets are <emphasis>emphasized</emphasis>.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/crypttab.xml b/man/crypttab.xml new file mode 100644 index 0000000000..2a839944dc --- /dev/null +++ b/man/crypttab.xml @@ -0,0 +1,313 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. + + This is based on crypttab(5) from Fedora's initscripts package, which in + turn is based on Debian's version. + + The Red Hat version has been written by Miloslav Trmac <mitr@redhat.com>. + +--> +<refentry id="crypttab"> + + <refentryinfo> + <title>crypttab</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Documentation</contrib> + <firstname>Miloslav</firstname> + <surname>Trmac</surname> + <email>mitr@redhat.com</email> + </author> + <author> + <contrib>Documentation</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>crypttab</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>crypttab</refname> + <refpurpose>Configuration for encrypted block devices</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/crypttab</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <filename>/etc/crypttab</filename> file + describes encrypted block devices that are set up + during system boot.</para> + + <para>Empty lines and lines starting with the # + character are ignored. Each of the remaining lines + describes one encrypted block device, fields on the + line are delimited by white space. The first two + fields are mandatory, the remaining two are + optional.</para> + + <para>The first field contains the name of the + resulting encrypted block device; the device is set up + within <filename>/dev/mapper/</filename>.</para> + + <para>The second field contains a path to the + underlying block device, or a specification of a block + device via <literal>UUID=</literal> followed by the + UUID. If the block device contains a LUKS signature, + it is opened as a LUKS encrypted partition; otherwise + it is assumed to be a raw dm-crypt partition.</para> + + <para>The third field specifies the encryption + password. If the field is not present or the password + is set to none, the password has to be manually + entered during system boot. Otherwise the field is + interpreted as a path to a file containing the + encryption password. For swap encryption + <filename>/dev/urandom</filename> or the hardware + device <filename>/dev/hw_random</filename> can be used + as the password file; using + <filename>/dev/random</filename> may prevent boot + completion if the system does not have enough entropy + to generate a truly random encryption key.</para> + + <para>The fourth field, if present, is a + comma-delimited list of options. The following + options are recognized:</para> + + <variablelist> + <varlistentry> + <term><varname>cipher=</varname></term> + + <listitem><para>Specifies the cipher + to use; see + <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for possible values and the default + value of this option. A cipher with + unpredictable IV values, such as + <literal>aes-cbc-essiv:sha256</literal>, + is recommended. </para></listitem> + </varlistentry> + + + <varlistentry> + <term><varname>size=</varname></term> + + <listitem><para>Specifies the key size + in bits; see + <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for possible values and the default + value of this + option. </para></listitem> + </varlistentry> + + + <varlistentry> + <term><varname>keyfile-size=</varname></term> + + <listitem><para>Specifies the maximum number + of bytes to read from the keyfile; see + <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for possible values and the default + value of this option. This option is ignored + in plain encryption mode, as the keyfile-size is then given by the key size.</para></listitem> + </varlistentry> + + + <varlistentry> + <term><varname>keyfile-offset=</varname></term> + + <listitem><para>Specifies the number + of bytes to skip at the start of + the keyfile; see + <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for possible values and the default + value of this option.</para></listitem> + </varlistentry> + + + <varlistentry> + <term><varname>hash=</varname></term> + + <listitem><para>Specifies the hash to + use for password hashing; see + <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> for possible values and + the default value of this + option. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>tries=</varname></term> + + <listitem><para>Specifies the maximum + number of times the user is queried + for a password.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>verify</varname></term> + + <listitem><para> If the encryption + password is read from console, it has + to be entered twice (to prevent + typos). </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>read-only</varname></term> + + <listitem><para>Set up the encrypted + block device in read-only + mode.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>allow-discards</varname></term> + + <listitem><para>Allow discard requests + to be passed through the encrypted + block device. This improves + performance on SSD storage but has + security + implications.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>luks</varname></term> + + <listitem><para>Force LUKS mode.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>plain</varname></term> + + <listitem><para>Force plain encryption + mode.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>timeout=</varname></term> + + <listitem><para>Specify the timeout + for querying for a password. If no + unit is specified seconds is used. + Supported units are s, ms, + us, min, h, d.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>noauto</varname></term> + + <listitem><para> This device will not + be automatically unlocked on + boot. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>nofail</varname></term> + + <listitem><para>The system will not + wait for the device to show up and be + unlocked at boot, and not fail the + boot if it doesn't show + up.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>swap</varname></term> + + <listitem><para> The encrypted block + device will be used as a swap + partition, and will be formatted as a + swap partition after setting up the + encrypted block device, with + <citerefentry><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + + <para>WARNING: Using the + <varname>swap</varname> option will + destroy the contents of the named + partition during every boot, so make + sure the underlying block device is + specified + correctly. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>tmp</varname></term> + + <listitem><para>The encrypted block + device will be prepared for using it + as <filename>/tmp</filename> + partition: it will be formatted using + <citerefentry><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + + <para>WARNING: Using the + <varname>tmp</varname> option will + destroy the contents of the named + partition during every boot, so make + sure the underlying block device is + specified + correctly. </para></listitem> + </varlistentry> + </variablelist> + + <para>At early boot and when the system manager + configuration is reloaded this file is translated into + native systemd units + by <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>Example</title> + <example> + <title>/etc/crypttab example</title> + <para>Set up two encrypted block devices with + LUKS: one normal one for storage, and another + one for usage as swap device.</para> + + <programlisting>luks-2505567a-9e27-4efe-a4d5-15ad146c258b UUID=2505567a-9e27-4efe-a4d5-15ad146c258b - timeout=0 +swap /dev/sda7 /dev/urandom swap</programlisting> + </example> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>mke2fs</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 0000000000..906ddc5572 --- /dev/null +++ b/man/custom-html.xsl @@ -0,0 +1,50 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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"/> + +<!-- translate man page references to links to html pages --> +<xsl:template match="citerefentry"> + <a> + <xsl:attribute name="href"> + <xsl:value-of select="refentrytitle"/><xsl:text>.html</xsl:text> + </xsl:attribute> + <xsl:call-template name="inline.charseq"/> + </a> +</xsl:template> + +<!-- add Index link at top of page --> +<xsl:template name="user.header.content"> + <a> + <xsl:attribute name="href"> + <xsl:text>index.html</xsl:text> + </xsl:attribute> + <xsl:text>Index </xsl:text> + </a> + <hr/> +</xsl:template> + +<!-- 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 0000000000..197138e51d --- /dev/null +++ b/man/daemon.xml @@ -0,0 +1,949 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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 on that this + <function>exit()</function> happens + after initialization is complete and + all external communication channels + are 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 + behavior 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 system'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>3</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 + 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>3</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) or <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 snippets + like the following to enable/disable the + service during + installation/deinstallation. This makes use of + the RPM macros shipped along systemd. Consult + the packaging guidelines of your distribution + for details and the equivalent for other + package managers.</para> + + <para>At the top of the file:</para> + + <programlisting>BuildRequires: systemd +%{?systemd_requires}</programlisting> + + <para>And as scriptlets, further down:</para> + + <programlisting>%post +%systemd_post foobar.service foobar.socket + +%preun +%systemd_preun foobar.service foobar.socket + +%postun +%systemd_postun</programlisting> + + <para>If the service shall be restarted during + upgrades replace the + <literal>%postun</literal> scriptlet above + with the following:</para> + + <programlisting>%postun +%systemd_postun_with_restart foobar.service</programlisting> + + <para>Note that + <literal>%systemd_post</literal> and + <literal>%systemd_preun</literal> expect the + names of all units that are installed/removed + as arguments, separated by + spaces. <literal>%systemd_postun</literal> + expects no + arguments. <literal>%systemd_postun_with_restart</literal> + expects the units to restart as + arguments.</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>3</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 0000000000..8473965194 --- /dev/null +++ b/man/halt.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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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 of 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 of which one of the three + commands is invoked.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--reboot</option></term> + + <listitem><para>Reboot the machine, + regardless of 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>--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 0000000000..84a2961664 --- /dev/null +++ b/man/hostname.xml @@ -0,0 +1,102 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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> + + <para>You may use + <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + to change the value of this file from the command + line.</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>, + <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/hostnamectl.xml b/man/hostnamectl.xml new file mode 100644 index 0000000000..c36f522c8e --- /dev/null +++ b/man/hostnamectl.xml @@ -0,0 +1,228 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="hostnamectl"> + + <refentryinfo> + <title>hostnamectl</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>hostnamectl</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>hostnamectl</refname> + <refpurpose>Control the system hostname</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>hostnamectl <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="req">COMMAND</arg></command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>hostnamectl</command> may be used to + query and change the system hostname and related + settings.</para> + + <para>This tool distinguishes three different host + names: the high-level "pretty" hostname which might + include all kinds of special characters + (e.g. "Lennart's Laptop"), the static hostname which + is used to initialize the kernel hostname at boot + (e.g. "lennarts-laptop"), and the transient hostname + which might be assigned temporarily due to network + configuration and might revert back to the static + hostname if network connectivity is lost and is only + temporarily written to the kernel hostname + (e.g. "dhcp-47-11").</para> + + <para>Note that the pretty hostname has little + restrictions on the characters used, while the static + and transient hostnames are limited to the usually + accepted characters of internet domain names.</para> + + <para>The static host name is stored in + <filename>/etc/hostname</filename>, see + <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information. The pretty host name and icon + name are stored in + <filename>/etc/machine-info</filename>, see + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</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-ask-password</option></term> + + <listitem><para>Don't query the user + for authentication for privileged + operations.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-H</option></term> + <term><option>--host</option></term> + + <listitem><para>Execute the operation + remotely. Specify a hostname, or + username and hostname separated by @, + to connect to. This will use SSH to + talk to a remote + system.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--static</option></term> + <term><option>--transient</option></term> + <term><option>--pretty</option></term> + + <listitem><para>If + <command>set-hostname</command> is + invoked and one or more of these + options are passed only the selected + hostnames is + updated.</para></listitem> + </varlistentry> + </variablelist> + + <para>The following commands are understood:</para> + + <variablelist> + <varlistentry> + <term><command>status</command></term> + + <listitem><para>Show current system + hostname and related + information.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>set-hostname [NAME]</command></term> + + <listitem><para>Set the system + hostname. By default this will alter + the pretty, the static, and the + transient hostname alike, however if + one or more of + <option>--static</option>, + <option>--transient</option>, + <option>--pretty</option> are used + only the selected hostnames are + changed. If the pretty hostname is + being set, and static or transient are + being set as well the specified host + name will be simplified in regards to + the character set used before the + latter are updated. This is done by + replacing spaces by "-" and removing + special characters. This ensures that + the pretty and the static hostname + are always closely related while still + following the validity rules of the + specific name. This simplification of + the hostname string is not done if + only the transient and/or static host + names are set, and the pretty host + name is left untouched. Pass the empty + string "" as hostname to reset the + selected hostnames to their default + (usually + "localhost").</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>set-icon-name [NAME]</command></term> + + <listitem><para>Set the system icon + name. The icon name is used by some + graphical applications to visualize + this host. The icon name should follow + the <ulink + url="http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">Icon + Naming Specification</ulink>. Pass an + empty string to this operation to + reset the icon name to the default + value which is determined from the + system form factor and possibly other + parameters.</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>hostname</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/journalctl.xml b/man/journalctl.xml new file mode 100644 index 0000000000..026bb22940 --- /dev/null +++ b/man/journalctl.xml @@ -0,0 +1,533 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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" rep="repeat">MATCHES</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 as written by + <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + + <para>If called without parameter it will show the full + contents of the journal, starting with the oldest + entry collected.</para> + + <para>If one or more match arguments are passed the + output is filtered accordingly. A match is in the + format <literal>FIELD=VALUE</literal>, + e.g. <literal>_SYSTEMD_UNIT=httpd.service</literal>, + referring to the components of a structured journal + entry. See + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for a list of well-known fields. If multiple matches + are specified matching different fields the log + entries are filtered by both, i.e. the resulting output + will show only entries matching all the specified + matches of this kind. If two matches apply to the same + field, then they are automatically matched as + alternatives, i.e. the resulting output will show + entries matching any of the specified matches for the + same field. Finally, if the character + "<literal>+</literal>" appears as separate word on the + command line all matches before and after are combined + in a disjunction (i.e. logical OR).</para> + + <para>As shortcuts for a few types of field/value + matches file paths may be specified. If a file path + refers to an executable file, this is equivalent to an + <literal>_EXE=</literal> match for the canonicalized + binary path. Similar, if a path refers to a device + node, this is equivalent to a + <literal>_KERNEL_DEVICE=</literal> match for the + device.</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 the most recent + journal entries, and continuously 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>Show the most recent + journal events and limit the number of + events shown. If + <option>--follow</option> is used, + this option is implied. The argument, + a positive integer, is optional, and + defaults to 10. </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>json-pretty</literal>, + <literal>json-sse</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 structured entry items + with all + fields. <literal>export</literal> + serializes the journal into a binary + (but mostly text-based) stream + suitable for backups and network + transfer (see <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/export">Journal + Export Format</ulink> for more + information). <literal>json</literal> + formats entries as JSON data + structures, one per + line (see <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/json">Journal + JSON Format</ulink> for more + information). <literal>json-pretty</literal> + also formats entries as JSON data + structures, but formats them in + multiple lines in order to make them + more readable for + humans. <literal>json-sse</literal> + also formats entries as JSON data + structures, but wraps them in a format + suitable for <ulink + url="https://developer.mozilla.org/en-US/docs/Server-sent_events/Using_server-sent_events">Server-Sent + Events</ulink>. <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 inaccessible system + journals when run as normal + user.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--merge</option></term> + <term><option>-m</option></term> + + <listitem><para>Show entries + interleaved from all available + journals, including remote + ones.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--this-boot</option></term> + <term><option>-b</option></term> + + <listitem><para>Show data only from + current boot. This will add a match + for <literal>_BOOT_ID=</literal> for + the current boot ID of the + kernel.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--unit=</option></term> + <term><option>-u</option></term> + + <listitem><para>Show data only of the + specified unit. This will add a match + for <literal>_SYSTEMD_UNIT=</literal> + for the specified + unit.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-p</option></term> + <term><option>--priority=</option></term> + + <listitem><para>Filter output by + message priorities or priority + ranges. Takes either a single numeric + or textual log level (i.e. between + 0/<literal>emerg</literal> and + 7/<literal>debug</literal>), or a + range of numeric/text log levels in + the form FROM..TO. The log levels are + the usual syslog log levels as + documented in + <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + i.e. <literal>emerg</literal> (0), + <literal>alert</literal> (1), + <literal>crit</literal> (2), + <literal>err</literal> (3), + <literal>warning</literal> (4), + <literal>notice</literal> (5), + <literal>info</literal> (6), + <literal>debug</literal> (7). If a + single log level is specified all + messages with this log level or a + lower (hence more important) log level + are shown. If a range is specified all + messages within the range are shown, + including both the start and the end + value of the range. This will add + <literal>PRIORITY=</literal> matches + for the specified + priorities.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--cursor=</option></term> + <term><option>-c</option></term> + + <listitem><para>Start showing entries + from the location in the journal + specified by the passed + cursor.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--since=</option></term> + <term><option>--until=</option></term> + + <listitem><para>Start showing entries + on or newer than the specified date, + or on or older than the specified + date, respectively. Date specifications should be of + the format "2012-10-30 18:17:16". If + the time part is omitted, 00:00:00 is + assumed. If only the seconds component + is omitted, :00 is assumed. If the + date component is ommitted, the + current day is assumed. Alternatively + the strings + <literal>yesterday</literal>, + <literal>today</literal>, + <literal>tomorrow</literal> are + understood, which refer to 00:00:00 of + the day before the current day, the + current day, or the day after the + current day, respectively. <literal>now</literal> + refers to the current time. Finally, + relative times may be specified, + prefixed with <literal>-</literal> or + <literal>+</literal>, referring to + times before or after the current + time, respectively.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--field=</option></term> + <term><option>-F</option></term> + + <listitem><para>Print all possible + data values the specified field can + take in all entries of the + journal.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--directory=</option></term> + <term><option>-D</option></term> + + <listitem><para>Takes an absolute + directory path as argument. If + specified journalctl will operate on the + specified journal directory instead of + the default runtime and system journal + paths.</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> + + <varlistentry> + <term><option>--header</option></term> + + <listitem><para>Instead of showing + journal contents show internal header + information of the journal fields + accessed.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--disk-usage</option></term> + + <listitem><para>Shows the current disk + usage of all + journal files.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--setup-keys</option></term> + + <listitem><para>Instead of showing + journal contents generate a new key + pair for Forward Secure Sealing + (FSS). This will generate a sealing + key and a verification key. The + sealing key is stored in the journal + data directory and shall remain on the + host. The verification key should be + stored externally.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--interval=</option></term> + + <listitem><para>Specifies the change + interval for the sealing key, when + generating an FSS key pair with + <option>--setup-keys</option>. Shorter + intervals increase CPU consumption but + shorten the time range of + undetectable journal + alterations. Defaults to + 15min.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--verify</option></term> + + <listitem><para>Check the journal file + for internal consistency. If the + file has been generated with FSS + enabled, and the FSS verification key + has been specified with + <option>--verify-key=</option> + authenticity of the journal file is + verified.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--verify-key=</option></term> + + <listitem><para>Specifies the FSS + verification key to use for the + <option>--verify</option> + operation.</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>Examples</title> + + <para>Without arguments all collected logs are shown + unfiltered:</para> + + <programlisting>journalctl</programlisting> + + <para>With one match specified all entries with a field matching the expression are shown:</para> + + <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service</programlisting> + + <para>If two different fields are matched only entries matching both expressions at the same time are shown:</para> + + <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097</programlisting> + + <para>If two matches refer to the same field all entries matching either expression are shown:</para> + + <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _SYSTEMD_UNIT=dbus.service</programlisting> + + <para>If the separator "<literal>+</literal>" is used + two expressions may be combined in a logical OR. The + following will show all messages from the Avahi + service process with the PID 28097 plus all messages + from the D-Bus service (from any of its + processes):</para> + + <programlisting>journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097 + _SYSTEMD_UNIT=dbus.service</programlisting> + + <para>Show all logs generated by the D-Bus executable:</para> + + <programlisting>journalctl /usr/bin/dbus-daemon</programlisting> + + <para>Show all logs of the kernel device node <filename>/dev/sda</filename>:</para> + + <programlisting>journalctl /dev/sda</programlisting> + + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</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 0000000000..86c9869e51 --- /dev/null +++ b/man/journald.conf.xml @@ -0,0 +1,411 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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>/etc/systemd/journald.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>This files configures various parameters of the + systemd journal service + <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + + </refsect1> + + <refsect1> + <title>Options</title> + + <para>All options are configured in the + <literal>[Journal]</literal> section:</para> + + <variablelist> + + <varlistentry> + <term><varname>Storage=</varname></term> + + <listitem><para>Controls where to + store journal data. One of + <literal>volatile</literal>, + <literal>persistent</literal>, + <literal>auto</literal> and + <literal>none</literal>. If + <literal>volatile</literal> journal + log data will be stored only in + memory, i.e. below the + <filename>/run/log/journal</filename> + hierarchy (which is created if + needed). If + <literal>persistent</literal> data will + be stored preferably on disk, + i.e. below the + <filename>/var/log/journal</filename> + hierarchy (which is created if + needed), with a fallback to + <filename>/run/log/journal</filename> + (which is created if needed), during + early boot and if the disk is not + writable. <literal>auto</literal> is + similar to + <literal>persistent</literal> but the + directory + <filename>/var/log/journal</filename> + is not created if needed, so that its + existence controls where log data + goes. <literal>none</literal> turns + off all storage, all log data received + will be dropped. Forwarding to other + targets, such as the console, the + kernel log buffer or a syslog daemon + will still work however. Defaults to + <literal>auto</literal>.</para></listitem> + </varlistentry> + + <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>Seal=</varname></term> + + <listitem><para>Takes a boolean + value. If enabled (the default) and a + sealing key is available (as created + by + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s + <option>--setup-keys</option> + command), forward secure sealing (FSS) for + all persistent journal files is + enabled.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SplitMode=</varname></term> + + <listitem><para>Controls whether to + split up journal files per user. One + of <literal>login</literal>, + <literal>uid</literal> and + <literal>none</literal>. If + <literal>login</literal> each logged + in user will get his own journal + files, but systemd user IDs will log + into the system journal. If + <literal>uid</literal> any user ID + will get his own journal files + regardless whether it belongs to a + system service or refers to a real + logged in user. If + <literal>none</literal> journal files + are not split up per-user and all + messages are stored in the single + system journal. Note that splitting + up journal files per-user is only + available of journals are stored + persistently. If journals are stored + on volatile storage (see above) only a + single journal file for all user IDs + is kept. Defaults to + <literal>login</literal>.</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 200 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>RuntimeMaxUse=</varname></term> + <term><varname>RuntimeKeepFree=</varname></term> + <term><varname>RuntimeMaxFileSize=</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 + persistent 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 persistent + logging only the latter options apply, + while the former apply if persistent + 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 eighth of the + values configured with + <varname>SystemMaxUse=</varname> and + <varname>RuntimeMaxUse=</varname>, so + that usually seven rotated journal + files are kept as history. 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>MaxFileSec=</varname></term> + + <listitem><para>The maximum time to + store entries in a single journal + file, before rotating to the next + one. Normally time-based rotation + should not be required as size-based + rotation with options such as + <varname>SystemMaxFileSize=</varname> + should be sufficient to ensure that + journal files don't grow without + bounds. However, to ensure that not + too much data is lost at once when old + journal files are deleted it might + make sense to change this value from + the default of one month. Set to 0 to + turn off this feature. This setting + takes time values which may be + suffixed with the units year, month, + week, day, h, m to override the + default time unit of + seconds.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>MaxRetentionSec=</varname></term> + + <listitem><para>The maximum time to + store journal entries. This + controls whether journal files + containing entries older then the + specified time span are + deleted. Normally time-based deletion + of old journal files should not be + required as size-based deletion with + options such as + <varname>SystemMaxUse=</varname> + should be sufficient to ensure that + journal files don't grow without + bounds. However, to enforce data + retention policies it might make sense + to change this value from the + default of 0 (which turns off this + feature). This setting also takes + time values which may be suffixed with + the units year, month, week, day, h, m + to override the default time unit of + seconds. </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 overridden 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>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>MaxLevelStore=</varname></term> + <term><varname>MaxLevelSyslog=</varname></term> + <term><varname>MaxLevelKMsg=</varname></term> + <term><varname>MaxLevelConsole=</varname></term> + + <listitem><para>Controls the maximum + log level of messages that are stored + on disk, forwarded to syslog, kmsg or + the console (if that is enabled, see + above). As argument, takes 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> or integer + values in the range of 0..7 (corresponding + to the same levels). Messages equal or below + the log level specified are + stored/forwarded, messages above are + dropped. Defaults to + <literal>debug</literal> for + <varname>MaxLevelStore=</varname> and + <varname>MaxLevelSyslog=</varname>, to + ensure that the all messages are + written to disk and forwarded to + syslog. Defaults to + <literal>notice</literal> for + <varname>MaxLevelKMsg=</varname> and + <literal>info</literal> for + <varname>MaxLevelConsole=</varname>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TTYPath=</varname></term> + + <listitem><para>Change the console TTY + to use if + <varname>ForwardToConsole=yes</varname> + is used. Defaults to + <filename>/dev/console</filename>.</para></listitem> + </varlistentry> + + </variablelist> + + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/kernel-command-line.xml b/man/kernel-command-line.xml new file mode 100644 index 0000000000..27f0d4036f --- /dev/null +++ b/man/kernel-command-line.xml @@ -0,0 +1,295 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="kernel-command-line"> + + <refentryinfo> + <title>kernel-command-line</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>kernel-command-line</refentrytitle> + <manvolnum>7</manvolnum> + </refmeta> + + <refnamediv> + <refname>kernel-command-line</refname> + <refpurpose>Kernel command line parameters</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/proc/cmdline</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The kernel, the initial RAM disk (initrd) and + basic userspace functionality may be configured at boot via + kernel command line arguments.</para> + + <para>For command line parameters understood by the + kernel please see <ulink + url="https://www.kernel.org/doc/Documentation/kernel-parameters.txt"><filename>kernel-parameters.txt</filename></ulink> + and + <citerefentry><refentrytitle>bootparam</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + + <para>For command line paramaters understood by the + initial RAM disk, please see + <citerefentry><refentrytitle>dracut.cmdline</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + or the documentation of the specific initrd + implementation of your installation.</para> + </refsect1> + + <refsect1> + <title>Core OS Command Line Arguments</title> + + <variablelist> + <varlistentry> + <term><varname>systemd.unit=</varname></term> + <term><varname>rd.systemd.unit=</varname></term> + <term><varname>systemd.dump_core=</varname></term> + <term><varname>systemd.crash_shell=</varname></term> + <term><varname>systemd.crash_chvt=</varname></term> + <term><varname>systemd.confirm_spawn=</varname></term> + <term><varname>systemd.show_status=</varname></term> + <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> + <term><varname>systemd.default_standard_output=</varname></term> + <term><varname>systemd.default_standard_error=</varname></term> + <term><varname>systemd.setenv=</varname></term> + <listitem> + <para>Parameters understood by + the system and service manager + to control system behavior. For details see + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>quiet</varname></term> + <listitem> + <para>Parameter understood by + both the kernel and the system + and service manager to control + console log verbosity. For + details see + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>emergency</varname></term> + <term><varname>single</varname></term> + <term><varname>s</varname></term> + <term><varname>S</varname></term> + <term><varname>1</varname></term> + <term><varname>2</varname></term> + <term><varname>3</varname></term> + <term><varname>4</varname></term> + <term><varname>5</varname></term> + <listitem> + <para>Parameters understood by + the system and service + manager, as compatibility + options. For details see + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>locale.LANG=</varname></term> + <term><varname>locale.LANGUAGE=</varname></term> + <term><varname>locale.LC_CTYPE=</varname></term> + <term><varname>locale.LC_NUMERIC=</varname></term> + <term><varname>locale.LC_TIME=</varname></term> + <term><varname>locale.LC_COLLATE=</varname></term> + <term><varname>locale.LC_MONETARY=</varname></term> + <term><varname>locale.LC_MESSAGES=</varname></term> + <term><varname>locale.LC_PAPER=</varname></term> + <term><varname>locale.LC_NAME=</varname></term> + <term><varname>locale.LC_ADDRESS=</varname></term> + <term><varname>locale.LC_TELEPHONE=</varname></term> + <term><varname>locale.LC_MEASUREMENT=</varname></term> + <term><varname>locale.LC_IDENTIFICATION=</varname></term> + <listitem> + <para>Parameters understood by + the system and service manager + to control locale and language + settings. For details see + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>fsck.mode=</varname></term> + + <listitem> + <para>Parameter understood by + the file system checker + services. For details see + <citerefentry><refentrytitle>systemd-fsck@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>quotacheck.mode=</varname></term> + + <listitem> + <para>Parameter understood by + the file quota checker + service. For details see + <citerefentry><refentrytitle>systemd-quotacheck.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.journald.forward_to_syslog=</varname></term> + <term><varname>systemd.journald.forward_to_kmsg=</varname></term> + <term><varname>systemd.journald.forward_to_console=</varname></term> + + <listitem> + <para>Parameters understood by + the journal service. For + details see + <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>vconsole.keymap=</varname></term> + <term><varname>vconsole.keymap.toggle=</varname></term> + <term><varname>vconsole.font=</varname></term> + <term><varname>vconsole.font.map=</varname></term> + <term><varname>vconsole.font.unimap=</varname></term> + + <listitem> + <para>Parameters understood by + the virtual console setup logic. For + details see + <citerefentry><refentrytitle>systemd-vconsole-setup.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>udev.log-priority=</varname></term> + <term><varname>rd.udev.log-priority=</varname></term> + <term><varname>udev.children-max=</varname></term> + <term><varname>rd.udev.children-max=</varname></term> + <term><varname>udev.exec-delay=</varname></term> + <term><varname>rd.udev.exec-delay=</varname></term> + + <listitem> + <para>Parameters understood by + the device event managing daemon. For + details see + <citerefentry><refentrytitle>systemd-udevd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>plymouth.enable=</varname></term> + + <listitem> + <para>May be used to disable + the Plymouth boot splash. For + details see + <citerefentry><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>luks=</varname></term> + <term><varname>rd.luks=</varname></term> + <term><varname>luks.crypttab=</varname></term> + <term><varname>rd.luks.crypttab=</varname></term> + <term><varname>luks.uuid=</varname></term> + <term><varname>rd.luks.uuid=</varname></term> + + <listitem> + <para>Configures the LUKS + full-disk encryption logic at + boot. For details see + <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>fstab=</varname></term> + <term><varname>rd.fstab=</varname></term> + + <listitem> + <para>Configures the + <filename>/etc/fstab</filename> + logic at boot. For details see + <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>modules-load=</varname></term> + <term><varname>rd.modules-load=</varname></term> + + <listitem> + <para>Load a specific kernel + module early at boot. For + details see + <citerefentry><refentrytitle>systemd-modules-load.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + </variablelist> + + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>bootparam</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>dracut.cmdline</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-fsck@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-quotacheck.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-vconsole-setup.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-udevd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-modules-load.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/locale.conf.xml b/man/locale.conf.xml new file mode 100644 index 0000000000..06c0af0bf7 --- /dev/null +++ b/man/locale.conf.xml @@ -0,0 +1,149 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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. It is read at + early-boot by + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</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 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>, + <citerefentry><refentrytitle>systemd-localed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/localectl.xml b/man/localectl.xml new file mode 100644 index 0000000000..33508cffe5 --- /dev/null +++ b/man/localectl.xml @@ -0,0 +1,259 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="localectl"> + + <refentryinfo> + <title>localectl</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>localectl</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>localectl</refname> + <refpurpose>Control the system locale and keyboard layout settings</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>localectl <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="req">COMMAND</arg></command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>localectl</command> may be used to + query and change the system locale and keyboard layout + settings.</para> + + <para>The system locale controls the language settings + of system services and of the UI before the user logs + in, such as the display manager, as well as the + default for users after login.</para> + + <para>The keyboard settings control the keyboard + layout used on the text console and of the graphical + UI before the user logs in, such as the display + manager, as well as the default for users after + login.</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>--no-ask-password</option></term> + + <listitem><para>Don't query the user + for authentication for privileged + operations.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-H</option></term> + <term><option>--host</option></term> + + <listitem><para>Execute the operation + remotely. Specify a hostname, or + username and hostname separated by @, + to connect to. This will use SSH to + talk to a remote + system.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--no-convert</option></term> + + <listitem><para>If + <command>set-keymap</command> or + <command>set-x11-keymap</command> is + invoked and this option is passed then + the keymap will not be converted from + the console to X11, or X11 to console, + respectively.</para></listitem> + </varlistentry> + </variablelist> + + <para>The following commands are understood:</para> + + <variablelist> + <varlistentry> + <term><command>status</command></term> + + <listitem><para>Show current settings + of the system locale and keyboard + mapping.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>set-locale LOCALE...</command></term> + + <listitem><para>Set the system + locale. This takes one or more + assignments such as "LANG=de_DE.utf8", + "LC_MESSAGES=en_GB.utf8", and so + on. See + <citerefentry><refentrytitle>locale</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details on the available settings + and their meanings. Use + <command>list-locales</command> for a + list of available locales (see below). + </para></listitem> + </varlistentry> + + <varlistentry> + <term><command>list-locales</command></term> + + <listitem><para>List available locales + useful for configuration with + <command>set-locale</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>set-keymap MAP [TOGGLEMAP]</command></term> + + <listitem><para>Set the system + keyboard mapping for the console. This + takes a keyboard mapping name (such as + "de" or "us"), and possibly a second + one to define a toggle keyboard + mapping. Unless + <option>--no-convert</option> is + passed the selected setting is also + applied to the default keyboard + mapping of X11, after converting it to + the closest matching X11 keyboard + mapping. Use + <command>list-locales</command> for a + list of available keyboard mappings + (see below).</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>list-keymaps</command></term> + + <listitem><para>List available + keyboard mappings for the console, + useful for configuration with + <command>set-keyboard</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>set-x11-keymap LAYOUT [MODEL] [VARIANT] [OPTIONS]</command></term> + + <listitem><para>Set the system default + keyboard mapping for X11. This takes a + keyboard mapping name (such as "de" or + "us"), and possibly a model, variant + and options, see + <citerefentry><refentrytitle>kbd</refentrytitle><manvolnum>4</manvolnum></citerefentry> + for details. Unless + <option>--no-convert</option> is + passed the selected setting is also + applied to the system console keyboard + mapping, after converting it to the + closest matching console keyboard + mapping.</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>locale</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>loadkeys</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>kbd</refentrytitle><manvolnum>4</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-localed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/localtime.xml b/man/localtime.xml new file mode 100644 index 0000000000..88c84a3682 --- /dev/null +++ b/man/localtime.xml @@ -0,0 +1,103 @@ +<?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 + Copyright 2012 Shawn Landden + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="localtime"> + <refentryinfo> + <title>/etc/localtime</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + <author> + <contrib>Developer</contrib> + <firstname>Shawn</firstname> + <surname>Landden</surname> + <email>shawnlandden@gmail.com</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>localtime</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>localtime</refname> + <refpurpose>Local time zone configuration file</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/localtime</filename> -> <filename>../usr/share/zoneinfo/…</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <filename>/etc/localtime</filename> file + configures the system-wide time zone of the local + system that is used by applications for presentation + to the user. It should be an absolute or relative + symbolic link pointing to + <filename>/usr/share/zoneinfo/</filename>, followed by + a time zone identifier such as + <literal>Europe/Berlin</literal> or + <literal>Etc/UTC</literal>. The resulting link should + lead to the corresponding binary + <citerefentry><refentrytitle>tzfile</refentrytitle><manvolnum>5</manvolnum></citerefentry> + time zone data for the configured time zone.</para> + + <para>As the time zone identifier is extracted from + the symlink target name of + <filename>/etc/localtime</filename> this file may not + be a normal file or hardlink.</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> + + <para>You may use + <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + to change the settings of this file from the command + line.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>tzset</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-timedated.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/loginctl.xml b/man/loginctl.xml new file mode 100644 index 0000000000..5dbc1f6967 --- /dev/null +++ b/man/loginctl.xml @@ -0,0 +1,474 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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 <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</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>--no-ask-password</option></term> + + <listitem><para>Don't query the user + for authentication for privileged + operations.</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>lock-sessions</command></term> + + <listitem><para>Activate the screen + lock on all current sessions + supporting 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>Persistently 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 name. 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>systemd-logind.service</refentrytitle><manvolnum>8</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 0000000000..df15d51b5f --- /dev/null +++ b/man/logind.conf.xml @@ -0,0 +1,298 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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>/etc/systemd/logind.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>This file configures various parameters of the systemd login manager <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</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. Configures how many virtual + terminals (VTs) to allocate by default + that -- when switched to and + previously unused -- + <literal>autovt</literal> services are + automatically spawned on. These + services are instantiated from the + template unit + <filename>autovt@.service</filename> + for the respective VT 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. Hence, this + parameter controls how many login + <literal>gettys</literal> are + available on the VTs. If a VT is + already used by some other subsystem + (for example a graphical login) this + kind of activation will not be + attempted. Note that the VT configured + in <varname>ReserveVT=</varname> is + always subject to this kind of + activation, even if it is not one of + VTs configured with the + <varname>NAutoVTs=</varname> + directive. Defaults to 6. When set to + 0, automatic spawning of + <literal>autovt</literal> services is + disabled. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ReserveVT=</varname></term> + + <listitem><para>Takes a positive + integer. Configures the number of one + virtual terminal that shall + unconditionally be reserved for + <filename>autovt@.service</filename> + activation (see above). The VT + selected with this option will be + marked busy unconditionally so that no + other subsystem will allocate it. This + functionality is useful to ensure that + regardless how many VTs are allocated + by other subsystems one login + <literal>getty</literal> is always + available. Defaults to 6 (with other + words: there'll always be a + <literal>getty</literal> available on + Alt-F6.). When set to 0, VT + reservation 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 in 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> + + <varlistentry> + <term><varname>InhibitDelayMaxSec=</varname></term> + + <listitem><para>Specifies the maximum + time a system shutdown or sleep + request is delayed due to an inhibitor + lock of type <literal>delay</literal> + being active -- before it is ignored + and the operation executed + anyway. Defaults to + 5s.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>HandlePowerKey=</varname></term> + <term><varname>HandleSuspendKey=</varname></term> + <term><varname>HandleHibernateKey=</varname></term> + <term><varname>HandleLidSwitch=</varname></term> + + <listitem><para>Controls whether + logind shall handle the system power + and sleep keys and the lid switch to + trigger actions such as system + power-off or suspend. Can be one of + <literal>ignore</literal>, + <literal>poweroff</literal>, + <literal>reboot</literal>, + <literal>halt</literal>, + <literal>kexec</literal>, + <literal>suspend</literal>, + <literal>hibernate</literal>, + <literal>hybrid-sleep</literal> and + <literal>lock</literal>. If + <literal>ignore</literal> logind will + never handle these keys. If + <literal>lock</literal> all running + sessions will be screen + locked. Otherwise the specified action + will be taken in the respective + event. Only input devices with the + <literal>power-switch</literal> udev + tag will be watched for key/lid switch + events. <varname>HandlePowerKey=</varname> + defaults to + <literal>poweroff</literal>. + <varname>HandleSuspendKey=</varname> + and + <varname>HandleLidSwitch=</varname> + default to <literal>suspend</literal>. + <varname>HandleHibernateKey=</varname> + defaults to + <literal>hibernate</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PowerKeyIgnoreInhibited=</varname></term> + <term><varname>SuspendKeyIgnoreInhibited=</varname></term> + <term><varname>HibernateKeyIgnoreInhibited=</varname></term> + <term><varname>LidSwitchIgnoreInhibited=</varname></term> + + <listitem><para>Controls whether + actions triggered by the power and + sleep keys and the lid switch are + subject to inhibitor locks. These + settings take boolean arguments. If + <literal>off</literal> the inhibitor + locks taken by applications in order + to block the requested operation are + respected, if <literal>on</literal> + the requested operation is executed in + any + case. <varname>PowerKeyIgnoreInhibited=</varname>, + <varname>SuspendKeyIgnoreInhibited=</varname> + and + <varname>HibernateKeyIgnoreInhibited=</varname> + defaults to <literal>off</literal>, + <varname>LidSwitchIgnoreInhibited=</varname> + defaults to + <literal>yes</literal>. This means + that the lid switch does not respect + suspend blockers by default, but the + power and sleep keys do. + </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>systemd-logind.service</refentrytitle><manvolnum>8</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 0000000000..7d424b705b --- /dev/null +++ b/man/machine-id.xml @@ -0,0 +1,145 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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>, + <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_id128_get_machine</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/machine-info.xml b/man/machine-info.xml new file mode 100644 index 0000000000..b310d71334 --- /dev/null +++ b/man/machine-info.xml @@ -0,0 +1,154 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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> + + <para>You may use + <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + to change the settings of this file from the command + line.</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>, + <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/modules-load.d.xml b/man/modules-load.d.xml new file mode 100644 index 0000000000..bcc4d12561 --- /dev/null +++ b/man/modules-load.d.xml @@ -0,0 +1,120 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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><citerefentry><refentrytitle>systemd-modules-load.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + reads files from the above directories which contain + 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 rely on the + automatic module loading by PCI IDs, USB IDs, DMI IDs + or similar triggers encoded in the kernel modules + themselves instead of static configuration like + this. In fact, most modern kernel modules are prepared + for automatic loading already.</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 shall be 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> + and <filename>/run/</filename>. Files in + <filename>/run/</filename> override files with the + same name in <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 files installed from vendor + packages.</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/modules-load.d/</filename> bearing the + same file 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>systemd-modules-load.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-delta</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 0000000000..98320efe31 --- /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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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 + 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", + and "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 0000000000..2d2f191487 --- /dev/null +++ b/man/pam_systemd.xml @@ -0,0 +1,319 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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 login manager</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 login manager + <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + and hence 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 the 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 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 + behavior 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>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <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> + </para> + </refsect1> + +</refentry> diff --git a/man/runlevel.xml b/man/runlevel.xml new file mode 100644 index 0000000000..02d5371c5d --- /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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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 0000000000..a3bf662fe9 --- /dev/null +++ b/man/sd-daemon.xml @@ -0,0 +1,180 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd-daemon</refname> + <refname>SD_EMERG</refname> + <refname>SD_ALERT</refname> + <refname>SD_CRIT</refname> + <refname>SD_ERR</refname> + <refname>SD_WARNING</refname> + <refname>SD_NOTICE</refname> + <refname>SD_INFO</refname> + <refname>SD_DEBUG</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/libsystemd-daemon/sd-daemon.c"/> + and <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>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd-id128.xml b/man/sd-id128.xml new file mode 100644 index 0000000000..ac2000e275 --- /dev/null +++ b/man/sd-id128.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 2012 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd-id128"> + + <refentryinfo> + <title>sd-id128</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-id128</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd-id128</refname> + <refname>sd_id128_t</refname> + <refname>SD_ID128_MAKE</refname> + <refname>SD_ID128_CONST_STR</refname> + <refname>SD_ID128_FORMAT_STR</refname> + <refname>SD_ID128_FORMAT_VAL</refname> + <refname>sd_id128_equal</refname> + <refpurpose>APIs for processing 128 bit IDs</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-id128.h></funcsynopsisinfo> + </funcsynopsis> + + <cmdsynopsis> + <command>pkg-config --cflags --libs libsystemd-id128</command> + </cmdsynopsis> + + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>sd-id128.h</filename> provides APIs to + process and generate 128 bit ID values. The 128 bit ID + values processed and generated by these APIs are a + generalization of OSF UUIDs as defined by <ulink + url="http://tools.ietf.org/html/rfc4122">RFC + 4122</ulink>, though use a simpler string + formatting. These functions impose no structure on the + used IDs, much unlike OSF UUIDs or Microsoft GUIDs, + but are fully compatible with those types of IDs. + </para> + + <para>See + <citerefentry><refentrytitle>sd_id128_to_string</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_id128_randomize</refentrytitle><manvolnum>3</manvolnum></citerefentry> and + <citerefentry><refentrytitle>sd_id128_get_machine</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for more information about the implemented + functions.</para> + + <para>A 128 bit ID is implemented as the following + union type:</para> + + <programlisting>typedef union sd_id128 { + uint8_t bytes[16]; + uint64_t qwords[2]; +} sd_id128_t;</programlisting> + + <para>This union type allows accessing the 128 bit ID + as 16 separate bytes or two 64 bit words. It is generally + safer to access the ID components by their 8 bit array + to avoid endianness issues. This union is intended to + be passed call-by-value (as opposed to + call-by-reference) and may be directly manipulated by + clients.</para> + + <para>A couple of macros are defined to denote and + decode 128 bit IDs:</para> + + <para><function>SD_ID128_MAKE()</function> may be used + to denote a constant 128 bit ID in source code. A + commonly used idiom is to assign a name to a 128 bit + ID using this macro:</para> + + <programlisting>#define SD_MESSAGE_COREDUMP SD_ID128_MAKE(fc,2e,22,bc,6e,e6,47,b6,b9,07,29,ab,34,a2,50,b1)</programlisting> + + <para><function>SD_ID128_CONST_STR()</function> may be + used to convert constant 128bit IDs into constant + strings for output. The following example code will + output the string + "fc2e22bc6ee647b6b90729ab34a250b1":</para> + <programlisting>int main(int argc, char *argv[]) { + puts(SD_ID128_CONST_STR(SD_MESSAGE_COREDUMP)); +}</programlisting> + + <para><function>SD_ID128_FORMAT_STR</function> and + <function>SD_ID128_FORMAT_VAL()</function> may be used + to format a 128 bit ID in a + <citerefentry><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry> + format string, as shown in the following + example:</para> + + <programlisting>int main(int argc, char *argv[]) { + sd_id128_t id; + id = SD_ID128_MAKE(ee,89,be,71,bd,6e,43,d6,91,e6,c5,5d,eb,03,02,07); + printf("The ID encoded in this C file is " SD_ID128_FORMAT_STR ".\n", SD_ID128_FORMAT_VAL(id)); + return 0; +}</programlisting> + + <para>Use <function>sd_id128_equal()</function> to compare two 128 bit IDs:</para> + + <programlisting>int main(int argc, char *argv[]) { + sd_id128_t a, b, c; + a = SD_ID128_MAKE(ee,89,be,71,bd,6e,43,d6,91,e6,c5,5d,eb,03,02,07); + b = SD_ID128_MAKE(f2,28,88,9c,5f,09,44,15,9d,d7,04,77,58,cb,e7,3e); + c = a; + assert(sd_id128_equal(a, c)); + assert(!sd_id128_equal(a, b)); + return 0; +}</programlisting> + + <para>Note that new, randomized IDs may be generated + with + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s + <literal>--new-id</literal> option.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>These APIs are implemented as a shared library, + which can be compiled and linked to with the + <literal>libsystemd-id128</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_id128_to_string</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_id128_randomize</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_id128_get_machine</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd-journal.xml b/man/sd-journal.xml new file mode 100644 index 0000000000..1beb9a5c7d --- /dev/null +++ b/man/sd-journal.xml @@ -0,0 +1,130 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd-journal"> + + <refentryinfo> + <title>sd-journal</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-journal</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd-journal</refname> + <refpurpose>APIs for submitting and querying log entries to and from the journal</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> + </funcsynopsis> + + <cmdsynopsis> + <command>pkg-config --cflags --libs libsystemd-journal</command> + </cmdsynopsis> + + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>sd-journal.h</filename> provides APIs + to submit and query log entries. The APIs exposed act + both as client for the + <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + journal service and as parser for the journal files + on disk. + </para> + + <para>See + <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_stream_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_seek_head</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_cutoff_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_usage</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>sd_journal_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for more information about the functions + implemented.</para> + + <para>Command line access for submitting entries to + the journal is available with the + <citerefentry><refentrytitle>systemd-cat</refentrytitle><manvolnum>1</manvolnum></citerefentry> + tool. Command line access for querying entries from + the journal is available with the + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + tool.</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-journal</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_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_stream_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_seek_head</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_cutoff_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_usage</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_query_unique</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</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 0000000000..c02ad0c146 --- /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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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>3</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>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-readahead</refentrytitle><manvolnum>3</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 0000000000..cebaa5da2b --- /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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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>3</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"/> + and <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>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_booted.xml b/man/sd_booted.xml new file mode 100644 index 0000000000..34f2cbfbc8 --- /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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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/libsystemd-daemon/sd-daemon.c"/> + and <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>3</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>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_get_seats.xml b/man/sd_get_seats.xml new file mode 100644 index 0000000000..17adcef745 --- /dev/null +++ b/man/sd_get_seats.xml @@ -0,0 +1,129 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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> + + <para>Note that the returned lists are not sorted and in an undefined order.</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>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_session_get_seat</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_id128_get_machine.xml b/man/sd_id128_get_machine.xml new file mode 100644 index 0000000000..039c1dd64c --- /dev/null +++ b/man/sd_id128_get_machine.xml @@ -0,0 +1,138 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_id128_get_machine"> + + <refentryinfo> + <title>sd_id128_get_machine</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_id128_get_machine</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_id128_get_machine</refname> + <refname>sd_id128_get_boot</refname> + <refpurpose>Retrieve 128 bit IDs</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-id128.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_id128_get_machine</function></funcdef> + <paramdef>sd_id128_t* <parameter>ret</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_id128_get_boot</function></funcdef> + <paramdef>sd_id128_t* <parameter>ret</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_id128_get_machine()</function> + returns the machine ID of the executing host. This + reads and parses the + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> + file. This function caches the machine ID internally + to make retrieving the machine ID a cheap + operation.</para> + + <para><function>sd_id128_get_boot()</function> returns + the boot ID of the executing kernel. This reads and + parses the + <filename>/proc/sys/kernel/random/boot_id</filename> + file exposed by the kernel. It is randomly generated + early at boot and is unique for every running kernel + instance. See + <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> + for more information. This function also internally + caches the returned ID to make this call a cheap + operation.</para> + + <para>Note that + <function>sd_id128_get_boot()</function> always returns + a UUID v4 compatible + ID. <function>sd_id128_get_machine()</function> will + also return a UUID v4 compatible ID on new + installations, but might not on older. It is possible + to convert the machine ID into an UUID v4 compatible + one. For more information see + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + + <para>For more information about the + <literal>sd_id128_t</literal> type see + <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>The two calls return 0 on success (in which + case <parameter>ret</parameter> is filled in), or a + negative errno-style error code.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_id128_get_machine()</function> + and <function>sd_id128_get_boot()</function> + interfaces are available as shared library, which can + be compiled and linked to with the + <literal>libsystemd-id128</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-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_id128_randomize</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_id128_randomize.xml b/man/sd_id128_randomize.xml new file mode 100644 index 0000000000..be74937dd0 --- /dev/null +++ b/man/sd_id128_randomize.xml @@ -0,0 +1,118 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_id128_randomize"> + + <refentryinfo> + <title>sd_id128_randomize</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_id128_randomize</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_id128_randomize</refname> + <refpurpose>Generate 128 bit IDs</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-id128.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_id128_randomize</function></funcdef> + <paramdef>sd_id128_t* <parameter>ret</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_id128_randomize()</function> + generates a new randomized 128 bit ID and returns it + in <parameter>ret</parameter>. Every invocation + returns a new randomly generated ID. This uses the + <filename>/dev/urandom</filename> kernel random number + generator.</para> + + <para>Note that + <function>sd_id128_randomize()</function> always returns + a UUID v4 compatible + ID.</para> + + <para>For more information about the + <literal>sd_id128_t</literal> type see + <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + + <para><citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s + <literal>--new-id</literal> command may be used as + command line front-end for + <function>sd_id128_randomize()</function>.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>The call returns 0 on success (in which + case <parameter>ret</parameter> is filled in), or a + negative errno-style error code.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_id128_randomize()</function> interface + is available as shared library, which can be compiled + and linked to with the + <literal>libsystemd-id128</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-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_id128_get_machine</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_id128_to_string.xml b/man/sd_id128_to_string.xml new file mode 100644 index 0000000000..ec8b263e0d --- /dev/null +++ b/man/sd_id128_to_string.xml @@ -0,0 +1,131 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_id128_to_string"> + + <refentryinfo> + <title>sd_id128_to_string</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_id128_to_string</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_id128_to_string</refname> + <refname>sd_id128_from_string</refname> + <refpurpose>Format or parse 128 bit IDs as strings</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-id128.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>char* <function>sd_id128_to_string</function></funcdef> + <paramdef>sd_id128_t <parameter>id</parameter>, char <parameter>s</parameter>[33]</paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_id128_from_string</function></funcdef> + <paramdef>const char <parameter>s</parameter>[33], sd_id128_t* <parameter>ret</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_id128_to_string()</function> + formats a 128 bit ID as character string. It expects + the ID and a string array capable of storing 33 + characters. The ID will be formatted as 32 lowercase + hexadecimal digits and be terminated by a NUL + byte.</para> + + <para><function>sd_id128_from_string()</function> + implements the reverse operation: it takes a 33 + character array with 32 hexadecimal digits + (terminated by NUL) and parses them back into an + 128 bit ID returned in + <parameter>ret</parameter>.</para> + + <para>For more information about the + <literal>sd_id128_t</literal> type see + <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + + <para>When formatting a 128 bit ID into a string it is + often easier to use a format string for + <citerefentry><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This + is easily done using the + <function>SD_ID128_FORMAT_STR</function> and + <function>SD_ID128_FORMAT_VAL()</function> macros. For + more information see + <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para><function>sd_id128_to_string()</function> always + succeeds and returns a pointer to the string array + passed in. <function>sd_id128_from_string</function> + returns 0 on success (in which case + <parameter>ret</parameter> is filled in), or a negative + errno-style error code.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_id128_to_string()</function> + and <function>sd_id128_from_string()</function> interfaces are + available as shared library, which can be compiled and + linked to with the <literal>libsystemd-id128</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-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>printf</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 0000000000..595c8f112d --- /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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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. If 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/libsystemd-daemon/sd-daemon.c"/> + and <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>3</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>3</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_journal_add_match.xml b/man/sd_journal_add_match.xml new file mode 100644 index 0000000000..ad2486d749 --- /dev/null +++ b/man/sd_journal_add_match.xml @@ -0,0 +1,189 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_journal_add_match"> + + <refentryinfo> + <title>sd_journal_add_match</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_journal_add_match</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_journal_add_match</refname> + <refname>sd_journal_add_disjunction</refname> + <refname>sd_journal_flush_matches</refname> + <refpurpose>Add or remove entry matches</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_journal_add_match</function></funcdef> + <paramdef>sd_journal* <parameter>j</parameter></paramdef> + <paramdef>const void* <parameter>data</parameter></paramdef> + <paramdef>size_t <parameter>size</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_add_disjunction</function></funcdef> + <paramdef>sd_journal* <parameter>j</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_flush_matches</function></funcdef> + <paramdef>sd_journal* <parameter>j</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_journal_add_match()</function> adds + a match by which to filter the entries of the journal + file. Matches applied with this call will filter what + can be iterated through and read from the journal file + via calls like + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Matches + are of the form <literal>FIELD=value</literal>, where + the field part is a short uppercase string consisting + only of 0-9, A-Z and the underscore. It may not begin + with two underscores or be the empty string. The value + part may be any value, including binary. If a match is + applied only entries with this field set will be + iterated. Multiple matches may be active at the same + time: if they apply to different fields only entries + with both fields set like this will be iterated, if + they apply to the same fields only entries where the + field takes one of the specified values will be + iterated. Well known fields are documented in + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>. Whenever + a new match is added the current entry position is + reset, and + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> (or a similar call) + needs to be called before entries can be read + again.</para> + + <para><function>sd_journal_add_disjunction()</function> + may be used to insert a disjunction (i.e. logical OR) + in the match list. If this call is invoked all + previously added matches are combined in an OR with + all matches added afterwards, until + <function>sd_journal_add_disjunction()</function> is + invoked again to begin the next OR term. The + combination of + <function>sd_journal_add_match()</function> and + <function>sd_journal_add_disjunction()</function> may + be used to build complex search terms, even though + full logical expressions are not available.</para> + + <para><function>sd_journal_flush_matches()</function> + may be used to flush all matches and disjunction terms + again. After this call all filtering is removed and + all entries in the journal will be iterated + again.</para> + + <para>Note that filtering via matches only applies to + the way the journal is read, it has no effect on storage + on disk.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para><function>sd_journal_add_match()</function> and + <function>sd_journal_add_disjunction()</function> + return 0 on success or a negative errno-style error + code. <function>sd_journal_flush_matches()</function> + returns nothing.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_journal_add_match()</function>, + <function>sd_journal_add_disjunction()</function> and + <function>sd_journal_flush_matches()</function> interfaces are + available as shared library, which can be compiled and + linked to with the + <literal>libsystemd-journal</literal> + <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>Examples</title> + + <para>The following example adds matches to a journal + context object to iterate only through messages + generated by the Avahi service at the four error log + levels, plus all messages of the message ID + 03bb1dab98ab4ecfbf6fff2738bdd964 coming from any + service (this example lacks the necessary error + checking):</para> + + <programlisting>... +int add_matches(sd_journal *j) { + sd_journal_add_match(j, "_SYSTEMD_UNIT=avahi-daemon.service", 0); + sd_journal_add_match(j, "PRIORITY=0", 0); + sd_journal_add_match(j, "PRIORITY=1", 0); + sd_journal_add_match(j, "PRIORITY=2", 0); + sd_journal_add_match(j, "PRIORITY=3", 0); + sd_journal_add_disjunction(j); + sd_journal_add_match(j, "MESSAGE_ID=03bb1dab98ab4ecfbf6fff2738bdd964", 0); +}</programlisting> + + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_journal_get_cursor.xml b/man/sd_journal_get_cursor.xml new file mode 100644 index 0000000000..354168bee2 --- /dev/null +++ b/man/sd_journal_get_cursor.xml @@ -0,0 +1,151 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_journal_get_cursor"> + + <refentryinfo> + <title>sd_journal_get_cursor</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_journal_get_cursor</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_journal_get_cursor</refname> + <refname>sd_journal_test_cursor</refname> + <refpurpose>Get cursor string for or test cursor string against the current journal entry</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_journal_get_cursor</function></funcdef> + <paramdef>sd_journal* <parameter>j</parameter></paramdef> + <paramdef>char ** <parameter>cursor</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_test_cursor</function></funcdef> + <paramdef>sd_journal* <parameter>j</parameter></paramdef> + <paramdef>const char * <parameter>cursor</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_journal_get_cursor()</function> + returns a cursor string for the current journal + entry. A cursor is a serialization of the current + journal position formatted as text. The string only + contains printable characters and can be passed around + in text form. The cursor identifies a journal entry + globally and in a stable way and may be used to later + seek to it via + <citerefentry><refentrytitle>sd_journal_seek_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>. The + cursor string should be considered opaque and not be + parsed by clients. Seeking to a cursor position + without the specific entry being available locally + will seek to the next closest (in terms of time) + available entry. The call takes two arguments: a + journal context object and a pointer to a string + pointer where the cursor string will be placed. The + string is allocated via libc + <citerefentry><refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and should be freed after use with + <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + + <para>Note that + <function>sd_journal_get_cursor()</function> will not + work before + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> + (or related call) has been called at least once, in + order to position the read pointer at a valid + entry.</para> + + <para><function>sd_journal_test_cursor()</function> + may be used to check whether the current position in + the journal matches the specified cursor. This is + useful since cursor strings do not uniquely identify + an entry: the same entry might be referred to by + multiple different cursor strings, and hence string + comparing cursors is not possible. Use this call to + verify after an invocation of + <citerefentry><refentrytitle>sd_journal_seek_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry> + whether the entry being seeked to was actually found + in the journal or the next closest entry was used + instead.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para><function>sd_journal_get_cursor()</function> + returns 0 on success or a negative errno-style error + code. <function>sd_journal_test_cursor()</function> + returns positive if the current entry matches the + specified cursor, 0 if it doesn't match the specified + cursor or a negative errno-style error code on + failure.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_journal_get_cursor()</function> + and <function>sd_journal_test_cursor()</function> + interfaces are available as shared library, which can + be compiled and linked to with the + <literal>libsystemd-journal</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-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_seek_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_journal_get_cutoff_realtime_usec.xml b/man/sd_journal_get_cutoff_realtime_usec.xml new file mode 100644 index 0000000000..ed014cb509 --- /dev/null +++ b/man/sd_journal_get_cutoff_realtime_usec.xml @@ -0,0 +1,142 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_journal_get_cutoff_realtime_usec"> + + <refentryinfo> + <title>sd_journal_get_cutoff_realtime_usec</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_journal_get_cutoff_realtime_usec</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_journal_get_cutoff_realtime_usec</refname> + <refname>sd_journal_get_cutoff_monotonic_usec</refname> + <refpurpose>Read cut-off timestamps from the current journal entry</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_journal_get_cutoff_realtime_usec</function></funcdef> + <paramdef>sd_journal* <parameter>j</parameter></paramdef> + <paramdef>uint64_t* <parameter>from</parameter></paramdef> + <paramdef>uint64_t* <parameter>to</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_get_cutoff_monotonic_usec</function></funcdef> + <paramdef>sd_journal* <parameter>j</parameter></paramdef> + <paramdef>sd_id128_t <parameter>boot_id</parameter></paramdef> + <paramdef>uint64_t* <parameter>from</parameter></paramdef> + <paramdef>uint64_t* <parameter>to</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_journal_get_cutoff_realtime_usec()</function> + gets the realtime (wallclock) timestamps of the first + and last entries accessible in the journal. It takes + three arguments: the journal context object and two + pointers to 64 Bit unsigned integers to store the + timestamps in. The timestamps are in microseconds + since the epoch, i.e. CLOCK_REALTIME. Either one of + the two timestamp arguments may be passed as NULL in + case the timestamp is not needed, but not both.</para> + + <para><function>sd_journal_get_cutoff_monotonic_usec()</function> + gets the monotonic timestamps of the first and last + entries accessible in the journal. It takes three + arguments: the journal context object, a 128 Bit + identifier for the boot, and two pointers to 64 Bit + unsigned integers to store the timestamps. The + timestamps are in microseconds since boot-up of the + specific boot, i.e. CLOCK_MONOTONIC. Since the + monotonic clock begins new with every reboot it only + defines a well-defined point in time when used + together with an identifier identifying the boot, see + <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for more information. The function will return the + timestamps for the boot identified by the passed boot + ID. Either one of the two timestamp arguments may be + passed as NULL in case the timestamp is not needed, + but not both.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para><function>sd_journal_get_cutoff_realtime_usec()</function> + and + <function>sd_journal_get_cutoff_monotonic_usec()</function> + return 1 on success, 0 if not suitable entries are in + the journal or a negative errno-style error code.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The + <function>sd_journal_get_cutoff_realtime_usec()</function> + and + <function>sd_journal_get_cutoff_monotonic_usec()</function> + interfaces are available as shared library, which can + be compiled and linked to with the + <literal>libsystemd-journal</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-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_journal_get_data.xml b/man/sd_journal_get_data.xml new file mode 100644 index 0000000000..6470f19cc6 --- /dev/null +++ b/man/sd_journal_get_data.xml @@ -0,0 +1,201 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_journal_get_data"> + + <refentryinfo> + <title>sd_journal_get_data</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_journal_get_data</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_journal_get_data</refname> + <refname>sd_journal_enumerate_data</refname> + <refname>sd_journal_restart_data</refname> + <refname>SD_JOURNAL_FOREACH_DATA</refname> + <refpurpose>Read data fields from the current journal entry</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_journal_get_data</function></funcdef> + <paramdef>sd_journal* <parameter>j</parameter></paramdef> + <paramdef>const char* <parameter>field</parameter></paramdef> + <paramdef>const void** <parameter>data</parameter></paramdef> + <paramdef>size_t* <parameter>length</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_enumerate_data</function></funcdef> + <paramdef>sd_journal* <parameter>j</parameter></paramdef> + <paramdef>const void** <parameter>data</parameter></paramdef> + <paramdef>size_t* <parameter>length</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>void <function>sd_journal_restart_data</function></funcdef> + <paramdef>sd_journal* <parameter>j</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef><function>SD_JOURNAL_FOREACH_DATA</function></funcdef> + <paramdef>sd_journal* <parameter>j</parameter></paramdef> + <paramdef>const void* <parameter>data</parameter></paramdef> + <paramdef>size_t <parameter>length</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_journal_get_data()</function> gets + the data object associated with a specific field from + the current journal entry. It takes four arguments: + the journal context object, a string with the field + name to request, plus a pair of pointers to + pointer/size variables where the data object and its + size shall be stored in. The field name should be an + entry field name. Well-known field names are listed in + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The + returned data is in a read-only memory map and is only + valid until the next invocation of + <function>sd_journal_get_data()</function> or + <function>sd_journal_enumerate_data()</function>, or + the read pointer is altered. Note that the data + returned will be prefixed with the field name and + '='.</para> + + <para><function>sd_journal_enumerate_data()</function> + may be used to iterate through all fields of the + current entry. On each invocation the data for the + next field is returned. The order of these fields is + not defined. The data returned is in the same format + as with <function>sd_journal_get_data()</function> and + also follows the same life-time semantics.</para> + + <para><function>sd_journal_restart_data()</function> + resets the data enumeration index to the beginning of + the entry. The next invocation of + <function>sd_journal_enumerate_data()</function> will return the first + field of the entry again.</para> + + <para>Note that the + <function>SD_JOURNAL_FOREACH_DATA()</function> macro + may be used as a handy wrapper around + <function>sd_journal_restart_data()</function> and + <function>sd_journal_enumerate_data()</function>.</para> + + <para>Note that these functions will not work before + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> + (or related call) has been called at least + once, in order to position the read pointer at a valid entry.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para><function>sd_journal_get_data()</function> + returns 0 on success or a negative errno-style error + code. If the current entry does not include the + specified field -ENOENT is returned. If + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> + has not been called at least once -EADDRNOTAVAIL is + returned. <function>sd_journal_enumerate_data()</function> + returns a positive integer if the next field has been + read, 0 when no more fields are known, or a negative + errno-style error + code. <function>sd_journal_restart_data()</function> + returns nothing.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_journal_get_data()</function>, + <function>sd_journal_enumerate_data()</function> and + <function>sd_journal_restart_data()</function> + interfaces are available as shared library, which can + be compiled and linked to with the + <literal>libsystemd-journal</literal> + <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>Examples</title> + + <para>See + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for a complete example how to use + <function>sd_journal_get_data()</function>.</para> + + <para>Use the + <function>SD_JOURNAL_FOREACH_DATA</function> macro to + iterate through all fields of the current journal + entry:</para> + + <programlisting>... +int print_fields(sd_journal *j) { + const void *data; + size_t l; + SD_JOURNAL_FOREACH_DATA(j, data, length) + printf("%.*s\n", (int) length, data); +} +...</programlisting> + + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_query_unique</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_journal_get_fd.xml b/man/sd_journal_get_fd.xml new file mode 100644 index 0000000000..189d21352b --- /dev/null +++ b/man/sd_journal_get_fd.xml @@ -0,0 +1,272 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_journal_get_fd"> + + <refentryinfo> + <title>sd_journal_get_fd</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_journal_get_fd</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_journal_get_fd</refname> + <refname>sd_journal_reliable_fd</refname> + <refname>sd_journal_process</refname> + <refname>sd_journal_wait</refname> + <refname>SD_JOURNAL_NOP</refname> + <refname>SD_JOURNAL_APPEND</refname> + <refname>SD_JOURNAL_INVALIDATE</refname> + <refpurpose>Journal change notification + interface</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_journal_get_fd</function></funcdef> + <paramdef>sd_journal* <parameter>j</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_reliable_fd</function></funcdef> + <paramdef>sd_journal* <parameter>j</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_process</function></funcdef> + <paramdef>sd_journal* <parameter>j</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_wait</function></funcdef> + <paramdef>sd_journal* <parameter>j</parameter></paramdef> + <paramdef>uint64_t <parameter>timeout_usec</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_journal_get_fd()</function> returns + a file descriptor that may be asynchronously polled in + an external event loop and is signaled readable as + soon as the journal changes, because new entries or + files were added, rotation took place, or files have + been deleted, and similar. The file descriptor is + suitable for usage in + <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry> + where it will yield POLLIN on changes. The call takes + one argument: the journal context object. Note that + not all file systems are capable of generating the + necessary events for wakeups from this file descriptor + to be enirely reliable. In particular network files + systems do not generate suitable file change events in + all cases. In such a case an application should not + rely alone on wake-ups from this file descriptor but + wake up and recheck the journal in regular time + intervals, for example every 2s. To detect + cases where this is necessary, use + <function>sd_journal_reliable_fd()</function>, + below.</para> + + <para><function>sd_journal_reliable_fd()</function> + may be used to check whether the wakeup events from + the file descriptor returned by + <function>sd_journal_get_fd</function> are sufficient + to track changes to the journal. If this call returns + 0, it is necessary to regularly recheck for journal + changes (suggestion: every 2s). If this call returns a + positive integer this is not necessary, and wakeups + from the file descriptor returned by + <function>sd_journal_get_fd()</function> are + sufficient as only source for wake-ups.</para> + + <para>After each POLLIN wake-up + <function>sd_journal_process()</function> needs to be + called to process events and reset the readable state + of the file descriptor. This call will also indicate + what kind of change has been detected (see below; note + that spurious wake-ups are possible).</para> + + <para>A synchronous alternative for using + <function>sd_journal_get_fd()</function>, + <function>sd_journal_reliable_fd()</function> and + <function>sd_journal_process()</function> is + <function>sd_journal_wait()</function>. It will + synchronously wait until the journal gets changed, + possibly using a 2s time-out if this is necessary (see + above). In either way the maximum time this call + sleeps may be controlled with the + <parameter>timeout_usec</parameter> parameter. Pass + <literal>(uint64_t) -1</literal> to wait + indefinitely. Internally this call simply combines + <function>sd_journal_get_fd()</function>, + <function>sd_journal_reliable_fd()</function>, + <function>poll()</function> and + <function>sd_journal_process()</function> into + one.</para> + + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para><function>sd_journal_get_fd()</function> returns a valid file descriptor on success or a negative errno-style error + code.</para> + + <para><function>sd_journal_reliable_fd()</function> + returns a positive integer if the file descriptor + returned by <function>sd_journal_get_fd()</function> + is sufficient as sole wake-up source for journal + change events. Returns 0 if it is not sufficient and + the journal needs to be checked manually in regular + time intervals for changes. Returns a negative + errno-style error code on failure.</para> + + <para><function>sd_journal_process()</function> and + <function>sd_journal_wait()</function> return one of + <literal>SD_JOURNAL_NOP</literal>, + <literal>SD_JOURNAL_APPEND</literal> or + <literal>SD_JOURNAL_INVALIDATE</literal> on success or + a negative errno-style error code. If + <literal>SD_JOURNAL_NOP</literal> is returned the + journal didn't change since the last invocation. If + <literal>SD_JOURNAL_APPEND</literal> is returned new + entries have been appended to the end of the + journal. If <literal>SD_JOURNAL_INVALIDATE</literal> + journal files were added or removed (possibly due to + rotation). In the latter event live-view UIs should + probably refresh their entire display while in the + case of <literal>SD_JOURNAL_APPEND</literal> it is + sufficient to simply continue reading at the previous + end of the journal.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_journal_get_fd()</function>, + <function>sd_journal_reliable_fd()</function>, + <function>sd_journal_process()</function> and + <function>sd_journal_wait()</function> interfaces are + available as shared library, which can be compiled and + linked to with the + <literal>libsystemd-journal</literal> + <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>Examples</title> + + <para>Iterating through the journal, in a live view tracking all changes:</para> + + <programlisting>#include <stdio.h> +#include <string.h> +#include <systemd/sd-journal.h> + +int main(int argc, char *argv[]) { + int r; + sd_journal *j; + r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY); + if (r < 0) { + fprintf(stderr, "Failed to open journal: %s\n", strerror(-r)); + return 1; + } + for (;;) { + const char *d; + size_t l; + r = sd_journal_next(j); + if (r < 0) { + fprintf(stderr, "Failed to iterate to next entry: %s\n", strerror(-r)); + break; + } + if (r == 0) { + /* Reached the end, let's wait for changes, and try again */ + r = sd_journal_wait(j, (uint64_t) -1); + if (r < 0) { + fprintf(stderr, "Failed to wait for changes: %s\n", strerror(-r)); + break; + } + continue; + } + r = sd_journal_get_data(j, "MESSAGE", &d, &l); + if (r < 0) { + fprintf(stderr, "Failed to read message field: %s\n", strerror(-r)); + continue; + } + printf("%.*s\n", (int) l, d); + } + sd_journal_close(j); + return 0; +}</programlisting> + + <para>Waiting with <function>poll()</function> (this + example lacks all error checking for the sake of + simplicity):</para> + + <programlisting>#include <sys/poll.h> +#include <systemd/sd-journal.h> + +int wait_for_changes(sd_journal *j) { + struct pollfd pollfd; + pollfd.fd = sd_journal_get_fd(); + pollfd.events = POLLIN; + poll(&pollfd, 1, sd_journal_reliable_fd() > 0 ? -1 : 2000); + return sd_journal_process(j); +} + </programlisting> + </refsect1> + + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_journal_get_realtime_usec.xml b/man/sd_journal_get_realtime_usec.xml new file mode 100644 index 0000000000..515932c6d8 --- /dev/null +++ b/man/sd_journal_get_realtime_usec.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 2012 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_journal_get_realtime_usec"> + + <refentryinfo> + <title>sd_journal_get_realtime_usec</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_journal_get_realtime_usec</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_journal_get_realtime_usec</refname> + <refname>sd_journal_get_monotonic_usec</refname> + <refpurpose>Read timestamps from the current journal entry</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_journal_get_realtime_usec</function></funcdef> + <paramdef>sd_journal* <parameter>j</parameter></paramdef> + <paramdef>uint64_t* <parameter>usec</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_get_monotonic_usec</function></funcdef> + <paramdef>sd_journal* <parameter>j</parameter></paramdef> + <paramdef>uint64_t* <parameter>usec</parameter></paramdef> + <paramdef>sd_id128_t* <parameter>boot_id</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_journal_get_realtime_usec()</function> + gets the realtime (wallclock) timestamp of the + current journal entry. It takes two arguments: the + journal context object and a pointer to a 64 Bit + unsigned integer to store the timestamp in. The + timestamp is in microseconds since the epoch, + i.e. CLOCK_REALTIME.</para> + + <para><function>sd_journal_get_monotonic_usec()</function> + gets the monotonic timestamp of the current + journal entry. It takes three arguments: the journal + context object, a pointer to a 64 Bit unsigned integer + to store the timestamp in as well as a 128 Bit ID + buffer to store the boot ID of the monotonic timestamp + in. The timestamp is in microseconds since boot-up of + the specific boot, i.e. CLOCK_MONOTONIC. Since the + monotonic clock begins new with every reboot it only + defines a well-defined point in time when used + together with an identifier identifying the boot, see + <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for more information. If the boot ID parameter is + passed NULL the function will fail if the monotonic + timestamp of the current entry is not of the current + system boot.</para> + + <para>Note that these functions will not work before + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> + (or related call) has been called at least + once, in order to position the read pointer at a valid entry.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para><function>sd_journal_get_realtime_usec()</function> + and + <function>sd_journal_get_monotonic_usec()</function> + returns 0 on success or a negative errno-style error + code. If the boot ID parameter was passed NULL and the + monotonic timestamp of the current journal entry is + not of the current system boot, -ESTALE is returned by <function>sd_journal_get_monotonic_usec()</function>.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The + <function>sd_journal_get_realtime_usec()</function> + and + <function>sd_journal_get_monotonic_usec()</function> + interfaces are available as shared library, which can + be compiled and linked to with the + <literal>libsystemd-journal</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-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_cutoff_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_journal_get_usage.xml b/man/sd_journal_get_usage.xml new file mode 100644 index 0000000000..14eb1e2b79 --- /dev/null +++ b/man/sd_journal_get_usage.xml @@ -0,0 +1,104 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_journal_get_usage"> + + <refentryinfo> + <title>sd_journal_get_usage</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_journal_get_usage</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_journal_get_usage</refname> + <refpurpose>Journal disk usage</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_journal_get_usage</function></funcdef> + <paramdef>sd_journal* <parameter>j</parameter></paramdef> + <paramdef>uint64_t* <parameter>bytes</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_journal_get_usage()</function> + determines the total disk space currently used up by + journal files. If + <literal>SD_JOURNAL_LOCAL_ONLY</literal> has been + passed when opening the journal files this value will + only reflect the size of journal files of the local + host, otherwise of all hosts.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para><function>sd_journal_get_usage()</function> + returns 0 on success or a negative errno-style error + code.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_journal_get_usage()</function> + interface is available as shared library, which can be + compiled and linked to with the + <literal>libsystemd-journal</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-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + </para> + </refsect1> + +</refentry> diff --git a/man/sd_journal_next.xml b/man/sd_journal_next.xml new file mode 100644 index 0000000000..9b1cb1fc46 --- /dev/null +++ b/man/sd_journal_next.xml @@ -0,0 +1,214 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_journal_next"> + + <refentryinfo> + <title>sd_journal_next</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_journal_next</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_journal_next</refname> + <refname>sd_journal_previous</refname> + <refname>sd_journal_next_skip</refname> + <refname>sd_journal_previous_skip</refname> + <refname>SD_JOURNAL_FOREACH</refname> + <refname>SD_JOURNAL_FOREACH_BACKWARDS</refname> + <refpurpose>Advance or set back the read pointer in the journal</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_journal_next</function></funcdef> + <paramdef>sd_journal* <parameter>j</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_previous</function></funcdef> + <paramdef>sd_journal* <parameter>j</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_next_skip</function></funcdef> + <paramdef>sd_journal* <parameter>j</parameter></paramdef> + <paramdef>uint64_t <parameter>skip</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_previous_skip</function></funcdef> + <paramdef>sd_journal* <parameter>j</parameter></paramdef> + <paramdef>uint64_t <parameter>skip</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef><function>SD_JOURNAL_FOREACH</function></funcdef> + <paramdef>sd_journal* <parameter>j</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef><function>SD_JOURNAL_FOREACH_BACKWARDS</function></funcdef> + <paramdef>sd_journal* <parameter>j</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_journal_next()</function> advances + the read pointer into the journal by one entry. The + only argument taken is a journal context object as + allocated via + <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>. After + successful invocation the entry may be read with + functions such as + <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + + <para>Similar, <function>sd_journal_previous()</function> sets + the read pointer back one entry.</para> + + <para><function>sd_journal_next_skip()</function> and + <function>sd_journal_previous_skip()</function> + advance/set back the read pointer by multiple entries + at once, as specified in the <varname>skip</varname> + parameter.</para> + + <para>The journal is strictly ordered by reception + time, and hence advancing to the next entry guarantees + that the entry then pointing to is later in time than + then previous one, or has the same timestamp.</para> + + <para>Note that + <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and related calls will fail unless + <function>sd_journal_next()</function> has been + invoked at least once in order to position the read + pointer on a journal entry.</para> + + <para>Note that the + <function>SD_JOURNAL_FOREACH()</function> macro may be used + as a wrapper around + <citerefentry><refentrytitle>sd_journal_seek_head</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and <function>sd_journal_next()</function> in order to + make iterating through the journal easier. See below + for an example. Similar, + <function>SD_JOURNAL_FOREACH_BACKWARDS()</function> + may be used for iterating the journal in reverse + order.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>The four calls return the number of entries + advanced/set back on success or a negative errno-style + error code. When the end or beginning of the journal + is reached, a number smaller than requested is + returned. More specifically, if + <function>sd_journal_next()</function> or + <function>sd_journal_previous()</function> reach the + end/beginning of the journal they will return 0, + instead of 1 when they are successful. This should be + considered an EOF marker.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_journal_next()</function>, <function>sd_journal_previous()</function>, + <function>sd_journal_next_skip()</function> and + <function>sd_journal_previous_skip()</function> interfaces are + available as shared library, which can be compiled and + linked to with the + <literal>libsystemd-journal</literal> + <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>Examples</title> + + <para>Iterating through the journal:</para> + + <programlisting>#include <stdio.h> +#include <string.h> +#include <systemd/sd-journal.h> + +int main(int argc, char *argv[]) { + int r; + sd_journal *j; + r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY); + if (r < 0) { + fprintf(stderr, "Failed to open journal: %s\n", strerror(-r)); + return 1; + } + SD_JOURNAL_FOREACH(j) { + const char *d; + size_t l; + + r = sd_journal_get_data(j, "MESSAGE", &d, &l); + if (r < 0) { + fprintf(stderr, "Failed to read message field: %s\n", strerror(-r)); + continue; + } + + printf("%.*s\n", (int) l, d); + } + sd_journal_close(j); + return 0; +}</programlisting> + + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_journal_open.xml b/man/sd_journal_open.xml new file mode 100644 index 0000000000..06d0ccfd12 --- /dev/null +++ b/man/sd_journal_open.xml @@ -0,0 +1,184 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_journal_open"> + + <refentryinfo> + <title>sd_journal_open</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_journal_open</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_journal_open</refname> + <refname>sd_journal_open_directory</refname> + <refname>sd_journal_close</refname> + <refname>sd_journal</refname> + <refname>SD_JOURNAL_LOCAL_ONLY</refname> + <refname>SD_JOURNAL_RUNTIME_ONLY</refname> + <refname>SD_JOURNAL_SYSTEM_ONLY</refname> + <refpurpose>Open the system journal for reading</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_journal_open</function></funcdef> + <paramdef>sd_journal** <parameter>ret</parameter></paramdef> + <paramdef>int <parameter>flags</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_open_directory</function></funcdef> + <paramdef>sd_journal** <parameter>ret</parameter></paramdef> + <paramdef>const char* <parameter>path</parameter></paramdef> + <paramdef>int <parameter>flags</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_close</function></funcdef> + <paramdef>sd_journal* <parameter>j</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_journal_open()</function> opens + the log journal for reading. It will find all journal + files automatically and interleave them automatically + when reading. As first argument it takes a pointer to + a <literal>sd_journal</literal> pointer, which on + success will contain journal context object afterwards. The + second argument is a flags field, which may consist of + the following flags ORed together: + <literal>SD_JOURNAL_LOCAL_ONLY</literal> makes sure + only journal files generated on the local machine will + be opened. <literal>SD_JOURNAL_RUNTIME_ONLY</literal> + makes sure only volatile journal files will be opened, + excluding those which are stored on persistent + storage. <literal>SD_JOURNAL_SYSTEM_ONLY</literal> + will ensure that only journal files of system services + and the kernel (in opposition to user session processes) will + be opened.</para> + + <para><function>sd_journal_open_directory()</function> + is similar to <function>sd_journal_open()</function> + but takes an absolute directory path as argument. All + journal files in this directory will be opened and + interleaved automatically. This call also takes a + flags argument, but it must be passed as 0 as no flags + are currently understood for this call.</para> + + <para><function>sd_journal_close()</function> will + close the journal context allocated with + <function>sd_journal_open()</function> or + <function>sd_journal_open_directory()</function> and + free its resources.</para> + + <para>When opening the journal only journal files + accessible to the calling user will be opened. If + journal files are not accessible to the caller this + will be silently ignored.</para> + + <para>See + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for an example how to iterate through the journal + after opening it with + <function>sd_journal_open()</function>.</para> + + <para>A journal context object returned by + <function>sd_journal_open()</function> references a + specific journal entry as <emphasis>current</emphasis> entry, + similar to a file seek index in a classic file system + file, but without absolute positions. It may be + altered with + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>sd_journal_seek_head</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and related calls. The current entry position may be + exported in <emphasis>cursor</emphasis> strings, as accessible + via + <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Cursor + strings may be used to globally identify a specific + journal entry in a stable way and then later to seek + to it (or if the specific entry is not available + locally, to its closest entry in time) + <citerefentry><refentrytitle>sd_journal_seek_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + + <para>Notification of journal changes is available via + <function>sd_journal_get_fd()</function> and related + calls.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>The <function>sd_journal_open()</function> and + <function>sd_journal_open_directory()</function> calls + return 0 on success or a negative errno-style error + code. <function>sd_journal_close()</function> returns + nothing.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_journal_open()</function>, + <function>sd_journal_open_directory()</function> and + <function>sd_journal_close()</function> interfaces are + available as shared library, which can be compiled and + linked to with the + <literal>libsystemd-journal</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-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_journal_print.xml b/man/sd_journal_print.xml new file mode 100644 index 0000000000..7742268f5d --- /dev/null +++ b/man/sd_journal_print.xml @@ -0,0 +1,251 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_journal_print"> + + <refentryinfo> + <title>sd_journal_print</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_journal_print</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_journal_print</refname> + <refname>sd_journal_printv</refname> + <refname>sd_journal_send</refname> + <refname>sd_journal_sendv</refname> + <refname>sd_journal_perror</refname> + <refname>SD_JOURNAL_SUPPRESS_LOCATION</refname> + <refpurpose>Submit log entries to the journal</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_journal_print</function></funcdef> + <paramdef>int <parameter>priority</parameter></paramdef> + <paramdef>const char* <parameter>format</parameter></paramdef> + <paramdef>...</paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_printv</function></funcdef> + <paramdef>int <parameter>priority</parameter></paramdef> + <paramdef>const char* <parameter>format</parameter></paramdef> + <paramdef>va_list <parameter>ap</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_send</function></funcdef> + <paramdef>const char* <parameter>format</parameter></paramdef> + <paramdef>...</paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_sendv</function></funcdef> + <paramdef>const struct iovec *<parameter>iov</parameter></paramdef> + <paramdef>int <parameter>n</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_perror</function></funcdef> + <paramdef>const char* <parameter>message</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_journal_print()</function> may be + used to submit simple, plain text log entries to the + system journal. The first argument is a priority + value. This is followed by a format string and its + parameters, similar to + <citerefentry><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry> + or + <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>. The + priority value is one of + <literal>LOG_EMERG</literal>, + <literal>LOG_ALERT</literal>, + <literal>LOG_CRIT</literal>, + <literal>LOG_ERR</literal>, + <literal>LOG_WARNING</literal>, + <literal>LOG_NOTICE</literal>, + <literal>LOG_INFO</literal>, + <literal>LOG_DEBUG</literal>, as defined in + <filename>syslog.h</filename>, see + <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for details. It is recommended to use this call to + submit log messages in the application locale or system + locale and in UTF-8 format, but no such restrictions + are enforced.</para> + + <para><function>sd_journal_printv()</function> is + similar to <function>sd_journal_print()</function> but + takes a variable argument list encapsulated in an + object of type <literal>va_list</literal> (see + <citerefentry><refentrytitle>stdarg</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for more information) instead of the format string. It + is otherwise equivalent in behavior.</para> + + <para><function>sd_journal_send()</function> may be + used to submit structured log entries to the system + journal. It takes a series of format strings, each + immediately followed by their associated parameters, + terminated by NULL. The strings passed should be of + the format <literal>VARIABLE=value</literal>. The + variable name must be in uppercase and consist only of + characters, numbers and underscores, and may not begin + with an underscore. (All assignments that do not + follow this syntax will be ignored.) The value can be + of any size and format. It is highly recommended to + submit text strings formatted in the UTF-8 character + encoding only, and submit binary fields only when + formatting in UTf-8 strings is not sensible. A number + of well known fields are defined, see + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details, but additional application defined fields + may be used. A variable may be assigned more than one + value per entry.</para> + + <para><function>sd_journal_sendv()</function> is + similar to <function>sd_journal_send()</function> but + takes an array of <literal>struct iovec</literal> (as + defined in <filename>uio.h</filename>, see + <citerefentry><refentrytitle>readv</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for details) instead of the format string. Each + structure should reference one field of the entry to + submit. The second argument specifies the number of + structures in the + array. <function>sd_journal_sendv()</function> is + particularly useful to submit binary objects to the + journal where that is necessary.</para> + + <para><function>sd_journal_perror()</function> is a + similar to + <citerefentry><refentrytitle>perror</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and writes a message to the journal that consists of + the passed string, suffixed with ": " and a human + readable representation of the current error code + stored in + <citerefentry><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If + the message string is passed as NULL or empty string + only the error string representation will be written, + prefixed with nothing. An additional journal field + ERRNO= is included in the entry containing the numeric + error code formatted as decimal string. The log + priority used is <literal>LOG_ERR</literal> (3).</para> + + <para>Note that <function>sd_journal_send()</function> + is a wrapper around + <function>sd_journal_sendv()</function> to make it + easier to use when only text strings shall be + submitted. Also, the following two calls are + mostly equivalent:</para> + + <programlisting>sd_journal_print(LOG_INFO, "Hello World, this is PID %lu!", (unsigned long) getpid()); + +sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid(), + "PRIORITY=%i", LOG_INFO, + NULL);</programlisting> + + <para>Note that these calls implicitly add fields for + the source file, function name and code line where + invoked. This is implemented with macros. If this is + not desired it can be turned off by defining + SD_JOURNAL_SUPPRESS_LOCATION before including + <filename>sd-journal.h</filename>.</para> + + <para><citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and <function>sd_journal_print()</function> may + largely be used interchangeably + functionality-wise. However, note that log messages + logged via the former take a different path to the + journal server than the later, and hence global + chronological ordering between the two streams cannot + be guaranteed. Using + <function>sd_journal_print()</function> has the + benefit of logging source code line, file names, and + functions as meta data along all entries, and + guaranteeing chronological ordering with structured + log entries that are generated via + <function>sd_journal_send()</function>. Using + <function>syslog()</function> has the benefit of being + more portable.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>The four calls return 0 on success or a negative + errno-style error code. The + <citerefentry><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry> + variable itself is not altered.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_journal_print()</function>, + <function>sd_journal_printv()</function>, + <function>sd_journal_send()</function> and + <function>sd_journal_sendv()</function> interfaces + are available as shared library, which can be compiled + and linked to with the + <literal>libsystemd-journal</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-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_stream_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>perror</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_journal_query_unique.xml b/man/sd_journal_query_unique.xml new file mode 100644 index 0000000000..f2f8af0eb5 --- /dev/null +++ b/man/sd_journal_query_unique.xml @@ -0,0 +1,214 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_journal_query_unique"> + + <refentryinfo> + <title>sd_journal_query_unique</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_journal_query_unique</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_journal_query_unique</refname> + <refname>sd_journal_enumerate_unique</refname> + <refname>sd_journal_restart_unique</refname> + <refname>SD_JOURNAL_FOREACH_UNIQUE</refname> + <refpurpose>Read unique data fields from the journal</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_journal_query_unique</function></funcdef> + <paramdef>sd_journal* <parameter>j</parameter></paramdef> + <paramdef>const char* <parameter>field</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_enumerate_unique</function></funcdef> + <paramdef>sd_journal* <parameter>j</parameter></paramdef> + <paramdef>const void** <parameter>data</parameter></paramdef> + <paramdef>size_t* <parameter>length</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>void <function>sd_journal_restart_unique</function></funcdef> + <paramdef>sd_journal* <parameter>j</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef><function>SD_JOURNAL_FOREACH_UNIQUE</function></funcdef> + <paramdef>sd_journal* <parameter>j</parameter></paramdef> + <paramdef>const void* <parameter>data</parameter></paramdef> + <paramdef>size_t <parameter>length</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_journal_query_unique()</function> + queries the journal for all unique values the + specified field can take. It takes two arguments: the + journal to query and the field name to look + for. Well-known field names are listed on + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>. Field + names must be specified without a trailing '='. After + this function has been executed successfully the field + values may be queried using + <function>sd_journal_enumerate_unique()</function>. Invoking + this call a second time will change the field name + being queried and reset the enumeration index to the + first field value that matches.</para> + + <para><function>sd_journal_enumerate_unique()</function> + may be used to iterate through all data fields which + match the previously selected field name as set with + <function>sd_journal_query_unique()</function>. On + each invocation the next field data matching the field + name is returned. The order of the returned data + fields is not defined. It takes three arguments: the + journal context object, plus a pair of pointers to + pointer/size variables where the data object and its + size shall be stored in. The returned data is in a + read-only memory map and is only valid until the next + invocation of + <function>sd_journal_enumerate_unique()</function>. Note + that the data returned will be prefixed with the field + name and '='.</para> + + <para><function>sd_journal_restart_unique()</function> + resets the data enumeration index to the beginning of + the list. The next invocation of + <function>sd_journal_enumerate_unique()</function> + will return the first field data matching the field + name again.</para> + + <para>Note that the + <function>SD_JOURNAL_FOREACH_UNIQUE()</function> macro + may be used as a handy wrapper around + <function>sd_journal_restart_unique()</function> and + <function>sd_journal_enumerate_unique()</function>.</para> + + <para>Note that these functions currently are not + influenced by matches set with + <function>sd_journal_add_match()</function> but this + might change in a later version of this + software.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para><function>sd_journal_query_unique()</function> + returns 0 on success or a negative errno-style error + code. <function>sd_journal_enumerate_unique()</function> + returns a positive integer if the next field data has + been read, 0 when no more fields are known, or a + negative errno-style error + code. <function>sd_journal_restart_unique()</function> + returns nothing.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_journal_query_unique()</function>, + <function>sd_journal_enumerate_unique()</function> and + <function>sd_journal_restart_unique()</function> + interfaces are available as shared library, which can + be compiled and linked to with the + <literal>libsystemd-journal</literal> + <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>Examples</title> + + <para>Use the + <function>SD_JOURNAL_FOREACH_UNIQUE</function> macro + to iterate through all values a field of the journal + can take. The following example lists all unit names + referenced in the journal:</para> + + <programlisting>#include <stdio.h> +#include <string.h> +#include <systemd/sd-journal.h> + +int main(int argc, char *argv[]) { + sd_journal *j; + const void *d; + size_t l; + int r; + + r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY); + if (r < 0) { + fprintf(stderr, "Failed to open journal: %s\n", strerror(-r)); + return 1; + } + r = sd_journal_query_unique(j, "_SYSTEMD_UNIT"); + if (r < 0) { + fprintf(stderr, "Failed to query journal: %s\n", strerror(-r)); + return 1; + } + SD_JOURNAL_FOREACH_UNIQUE(j, d, l) + printf("%.*s\n", (int) l, (const char*) d); + sd_journal_close(j); + return 0; +}</programlisting> + + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_journal_seek_head.xml b/man/sd_journal_seek_head.xml new file mode 100644 index 0000000000..3716c5d367 --- /dev/null +++ b/man/sd_journal_seek_head.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 2012 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_journal_seek_head"> + + <refentryinfo> + <title>sd_journal_seek_head</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_journal_seek_head</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_journal_seek_head</refname> + <refname>sd_journal_seek_tail</refname> + <refname>sd_journal_seek_monotonic_usec</refname> + <refname>sd_journal_seek_realtime_usec</refname> + <refname>sd_journal_seek_cursor</refname> + <refpurpose>Seek to a position in the + journal</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_journal_seek_head</function></funcdef> + <paramdef>sd_journal* <parameter>j</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_seek_tail</function></funcdef> + <paramdef>sd_journal* <parameter>j</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_seek_monotonic_usec</function></funcdef> + <paramdef>sd_journal* <parameter>j</parameter></paramdef> + <paramdef>sd_id128_t <parameter>boot_id</parameter></paramdef> + <paramdef>uint64_t <parameter>usec</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_seek_realtime_usec</function></funcdef> + <paramdef>sd_journal* <parameter>j</parameter></paramdef> + <paramdef>uint64_t <parameter>usec</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_seek_cursor</function></funcdef> + <paramdef>sd_journal* <parameter>j</parameter></paramdef> + <paramdef>const char * <parameter>cursor</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_journal_seek_head()</function> + seeks to the beginning of the journal, i.e. the oldest + available entry.</para> + + <para>Similar, + <function>sd_journal_seek_tail()</function> may be + used to seek to the end of the journal, i.e. the most + recent available entry.</para> + + <para><function>sd_journal_seek_monotonic_usec()</function> + seeks to the entry with the specified monotonic + timestamp, i.e. CLOCK_MONOOTONIC. Since monotonic time + restarts on every reboot a boot ID needs to be + specified as well.</para> + + <para><function>sd_journal_seek_realtime_usec()</function> + seeks to the entry with the specified realtime + (wallclock) timestamp, i.e. CLOCK_REALTIME. Note that + the realtime clock is not necessarily monotonic. If a + realtime timestamp is ambiguous it is not defined + which position is sought to.</para> + + <para><function>sd_journal_seek_cursor()</function> + seeks to the entry located at the specified cursor + string. For details on cursors see + <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If + no entry matching the specified cursor is found the + call will seek to the next closest entry (in terms of + time) instead. To verify whether the newly selected + entry actually matches the cursor use + <citerefentry><refentrytitle>sd_journal_test_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + + <para>Note that these calls do not actually make any + entry the new current entry, this needs to be done in + a separate step with a subsequent + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> + invocation (or a similar call). Only then entry data + may be retrieved via + <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If + no entry exists that matches exactly the specified + seek address the next closest is sought to. If + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> + is used the closest following entry will be sought to, + if + <citerefentry><refentrytitle>sd_journal_previous</refentrytitle><manvolnum>3</manvolnum></citerefentry> + is used the closest preceding entry is sought + to.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>The functions return 0 on success or a negative + errno-style error code.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_journal_seek_head()</function>, + <function>sd_journal_seek_tail()</function>, + <function>sd_journal_seek_monotonic_usec()</function>, + <function>sd_journal_seek_realtime_usec()</function>, + and <function>sd_journal_seek_cursor()</function> + interfaces are available as shared library, which can + be compiled and linked to with the + <literal>libsystemd-journal</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-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_journal_stream_fd.xml b/man/sd_journal_stream_fd.xml new file mode 100644 index 0000000000..4407296b40 --- /dev/null +++ b/man/sd_journal_stream_fd.xml @@ -0,0 +1,171 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_journal_stream_fd"> + + <refentryinfo> + <title>sd_journal_stream_fd</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_journal_stream_fd</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_journal_stream_fd</refname> + <refpurpose>Create log stream file descriptor to the journal</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_journal_stream_fd</function></funcdef> + <paramdef>const char* <parameter>identifier</parameter></paramdef> + <paramdef>int <parameter>priority</parameter></paramdef> + <paramdef>int <parameter>level_prefix</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_journal_stream_fd()</function> may + be used to create a log stream file descriptor. Log + messages written to this file descriptor as simple + newline separated text strings are written to the + journal. This file descriptor can be used internally + by applications or be made STDOUT/STDERR of other + processes executed.</para> + + <para><function>sd_journal_stream_fd()</function> + takes a short program identifier string as first + argument, which will be written to the journal as + _SYSLOG_IDENTIFIER= field for each log entry (see + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for more information). The second argument shall be + the default priority level for all messages. The + priority level is one of <literal>LOG_EMERG</literal>, + <literal>LOG_ALERT</literal>, + <literal>LOG_CRIT</literal>, + <literal>LOG_ERR</literal>, + <literal>LOG_WARNING</literal>, + <literal>LOG_NOTICE</literal>, + <literal>LOG_INFO</literal>, + <literal>LOG_DEBUG</literal>, as defined in + <filename>syslog.h</filename>, see + <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for details. The third argument is a boolean: if true + kernel-style log priority level prefixes (such as + <literal>SD_WARNING</literal>) are interpreted, see + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for more information.</para> + + <para>It is recommended that applications log UTF-8 + messages only with this API, but this is not + enforced.</para> + + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>The call returns a valid write-only file descriptor on success or a + negative errno-style error code.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_journal_stream_fd()</function> + interface is available as shared library, which can + be compiled and linked to with the + <literal>libsystemd-journal</literal> + <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>Examples</title> + + <para>Creating a log stream suitable for + <citerefentry><refentrytitle>fprintf</refentrytitle><manvolnum>3</manvolnum></citerefentry>:</para> + + <programlisting>#include <syslog.h> +#include <stdio.h> +#include <string.h> +#include <unistd.h> +#include <systemd/sd-journal.h> +#include <systemd/sd-daemon.h> + +int main(int argc, char *argv[]) { + int fd; + FILE *log; + fd = sd_journal_stream_fd("test", LOG_INFO, 1); + if (fd < 0) { + fprintf(stderr, "Failed to create stream fd: %s\n", strerror(-fd)); + return 1; + } + log = fdopen(fd, "w"); + if (!log) { + fprintf(stderr, "Failed to create file object: %m\n"); + close(fd); + return 1; + } + fprintf(log, "Hello World!\n"); + fprintf(log, SD_WARNING "This is a warning!\n"); + fclose(log); + return 0; +}</programlisting> + + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>fprintf</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_listen_fds.xml b/man/sd_listen_fds.xml new file mode 100644 index 0000000000..b891b6b039 --- /dev/null +++ b/man/sd_listen_fds.xml @@ -0,0 +1,204 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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> + <refname>SD_LISTEN_FDS_START</refname> + <refpurpose>Check for file descriptors passed by the system manager</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/libsystemd-daemon/sd-daemon.c"/> + and <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>3</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>3</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 0000000000..35cb6b368b --- /dev/null +++ b/man/sd_login_monitor_new.xml @@ -0,0 +1,173 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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> + <refname>sd_login_monitor</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 sessions, 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 <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 the + 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>3</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 0000000000..75edeeadf3 --- /dev/null +++ b/man/sd_notify.xml @@ -0,0 +1,319 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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 service manager 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 a 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 signaling 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. This is + the keep-alive ping that services need + to issue in regular intervals if + <varname>WatchdogSec=</varname> is + enabled for it. See + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. It is recommended to send + this message if the + <varname>WATCHDOG_USEC=</varname> + environment variable has been set for + the service process, in every half the + time interval that is specified in the + variable.</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/libsystemd-daemon/sd-daemon.c"/> + and <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>3</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>3</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 0000000000..9517795f78 --- /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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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> parameter 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>3</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 0000000000..a1fc6f178f --- /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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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"/> + and <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>3</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>3</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 0000000000..b1d6d20edf --- /dev/null +++ b/man/sd_seat_get_active.xml @@ -0,0 +1,180 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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> + + <funcprototype> + <funcdef>int <function>sd_seat_can_tty</function></funcdef> + <paramdef>const char* <parameter>seat</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_seat_can_graphical</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 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 (with only one being active at a + time).</para> + + <para><function>sd_seat_can_tty()</function> may be + used to determine whether a specific seat provides TTY + functionality, i.e. is useful as a text console.</para> + + <para><function>sd_seat_can_graphical()</function> may + be used to determine whether a specific seat provides + graphics functionality, i.e. is useful as a graphics + display.</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> + returns 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>, + <function>sd_seat_can_tty</function> and + <function>sd_seat_can_graphical</function> return 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>, + <function>sd_seat_can_multi_session()</function>, + <function>sd_seat_can_tty()</function> and + <function>sd_seat_can_grapical()</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>3</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 0000000000..a9107cb95f --- /dev/null +++ b/man/sd_session_is_active.xml @@ -0,0 +1,240 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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_state</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_state</function></funcdef> + <paramdef>const char* <parameter>session</parameter></paramdef> + <paramdef>char** <parameter>state</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_state()</function> may + be used to determine the state of the session + identified by the specified session identifier. The + following states are currently known: + <literal>online</literal> (session logged in, but + session not active, i.e. not in the foreground), + <literal>active</literal> (session logged in and + active, i.e. in the foreground), + <literal>closing</literal> (session nominally logged + out, but some processes belonging to it are still + around). In the future additional states might be + defined, client code should be written to be robust in + regards to additional state strings being + returned. This function is a more generic version of + <function>sd_session_is_active()</function>. 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_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_state()</function>, + <function>sd_session_get_uid()</function>, + <function>sd_session_get_seat()</function>, + <function>sd_session_get_service()</function>, + <function>sd_session_get_type()</function>, + <function>sd_session_get_class()</function> and + <function>sd_session_get_display()</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_state()</function>, + <function>sd_session_get_uid()</function>, + <function>sd_session_get_seat()</function>, + <function>sd_session_get_service()</function>, + <function>sd_session_get_type()</function>, + <function>sd_session_get_class()</function> and + <function>sd_session_get_display()</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>3</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 0000000000..b7bc944b14 --- /dev/null +++ b/man/sd_uid_get_state.xml @@ -0,0 +1,190 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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, i.e. has no session in the foreground), + <literal>active</literal> (user logged in, and has at + least one active session, i.e. one session in the + foreground), <literal>closing</literal> (user not + logged in, and not lingering, but some processes are + still around). 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 value. 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. Accepts a Unix user identifier as + parameter. The <parameter>require_active</parameter> + parameter controls whether the returned list shall + consist of only those sessions where the user is + currently active (> 0), where the user is currently + online but possibly inactive (= 0), or + logged in at all but possibly closing the session (< 0). 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>3</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 0000000000..d54fcb25ab --- /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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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 0000000000..69aac8cab7 --- /dev/null +++ b/man/sysctl.d.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 2011 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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>At boot, + <citerefentry><refentrytitle>systemd-sysctl.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + reads configuration files from the above directories + to configure + <citerefentry><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry> + kernel parameters.</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>/etc/</filename> override files + with the same name in <filename>/usr/lib/</filename> + and <filename>/run/</filename>. Files in + <filename>/run/</filename> override files with the same + name in <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 files installed by vendor packages. All + configuration files are sorted by their filename 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> bearing the + same file 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>systemd-sysctl.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-delta</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 0000000000..31f3b1a909 --- /dev/null +++ b/man/systemctl.xml @@ -0,0 +1,1268 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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>The argument should + be a unit type name such as + <option>service</option> and + <option>socket</option>, + or a unit load state such as + <option>loaded</option> and + <option>masked</option>. + </para> + + <para>If the argument is a unit type, + when listing units, limit display to + certain unit types. If not specified + units of all types will be shown.</para> + + <para>If the argument is a unit load state, + when listing units, limit display to + certain unit types. If not specified + units of in all load states will be + shown.</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 honored. 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. This also disables querying the + user for authentication for privileged + operations.</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>, overwrite 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>--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>help [NAME...|PID...]</command></term> + + <listitem><para>Show manual pages for + one or more units, if available. If a + PID is passed the manual pages for the + unit the process of the PID belongs to + is shown.</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 or unit file + instances, 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. + Also note that in case of instance + enablement, symlinks named same as + instances are created in install + location, however they all point to + the same template unit file.</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 are 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 are 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 + the preset policy files. This has the + same effect as + <command>disable</command> or + <command>enable</command>, depending + how the unit is listed in the preset + files. For more information on preset + policy format see + <citerefentry><refentrytitle>systemd.preset</refentrytitle><manvolnum>5</manvolnum></citerefentry>. For + more information on the concept of + presets please consult the <ulink + url="http://freedesktop.org/wiki/Software/systemd/Preset">Preset</ulink> + document.</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 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 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 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> + <varlistentry> + <term><command>suspend</command></term> + + <listitem><para>Suspend the + system. This will trigger activation + of the special + <filename>suspend.target</filename> + target.</para></listitem> + </varlistentry> + <varlistentry> + <term><command>hibernate</command></term> + + <listitem><para>Hibernate the + system. This will trigger activation + of the special + <filename>hibernate.target</filename> + target.</para></listitem> + </varlistentry> + <varlistentry> + <term><command>hybrid-sleep</command></term> + + <listitem><para>Hibernate and suspend + the system. This will trigger + activation of the special + <filename>hybrid-sleep.target</filename> + target.</para></listitem> + </varlistentry> + <varlistentry> + <term><command>switch-root [ROOT] [INIT]</command></term> + + <listitem><para>Switches to a + different root directory and executes + a new system manager process below + it. This is intended for usage in + initial RAM disks ("initrd"), and will + transition from the initrd's system + manager process (a.k.a "init" process) + to the main system manager + process. Takes two arguments: the + directory to make the new root + directory, and the path to the new + system manager binary below it to + execute as PID 1. If the latter is + omitted or the empty string, a + systemd binary will automatically be + searched for and used as init. If the + system manager path is omitted or + equal the empty string the state of + the initrd's system manager process is + passed to the main system manager, + which allows later introspection of the + state of the services involved in the + initrd boot.</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>, + <citerefentry><refentrytitle>systemd.preset</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-analyze.xml b/man/systemd-analyze.xml new file mode 100644 index 0000000000..c2ff9cc5bd --- /dev/null +++ b/man/systemd-analyze.xml @@ -0,0 +1,138 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd-analyze"> + + <refentryinfo> + <title>systemd-analyze</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-analyze</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-analyze</refname> + <refpurpose>Analyze system boot-up performance</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-analyze <arg choice="opt" rep="repeat">OPTIONS</arg> time</command> + </cmdsynopsis> + <cmdsynopsis> + <command>systemd-analyze <arg choice="opt" rep="repeat">OPTIONS</arg> blame </command> + </cmdsynopsis> + <cmdsynopsis> + <command>systemd-analyze <arg choice="opt" rep="repeat">OPTIONS</arg> plot <arg choice="opt">> file.svg</arg></command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-analyze</command> may be used + to determine system boot-up performance of the current + boot.</para> + + <para><command>systemd-analyze time</command> + prints the time spent in the kernel before + userspace has been reached, the time spent in the + initial RAM disk (initrd) before normal system + userspace has been reached and the time normal system + userspace took to initialize. Note that these + measurements simply measure the time passed up to the + point where all system services have been spawned, but + not necessarily until they fully finished + initialization or the disk is idle.</para> + + <para><command>systemd-analyze blame</command> prints + a list of all running units, ordered by the time they + took to initialize. This information may be used to + optimize boot-up times. Note that the output might be + misleading as the initialization of one service might + be slow simply because it waits for the initialization + of another service to complete.</para> + + <para><command>systemd-analyze plot</command> prints + an SVG graphic detailing which system services have + been started at what time, highlighting the time they + spent on initialization.</para> + + <para>If no command is passed <command>systemd-analyze + time</command> is implied.</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>--user</option></term> + + <listitem><para>Shows performance data + of user sessions instead of the system + manager.</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> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-ask-password-console.service.xml b/man/systemd-ask-password-console.service.xml new file mode 100644 index 0000000000..6c87feb179 --- /dev/null +++ b/man/systemd-ask-password-console.service.xml @@ -0,0 +1,96 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> +<refentry id="systemd-ask-password-console.service"> + + <refentryinfo> + <title>systemd-ask-password-console.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-ask-password-console.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-ask-password-console.service</refname> + <refname>systemd-ask-password-console.path</refname> + <refname>systemd-ask-password-wall.service</refname> + <refname>systemd-ask-password-wall.path</refname> + <refpurpose>Query the user for system passwords on the + console and via wall</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-ask-password-console.service</filename></para> + <para><filename>systemd-ask-password-console.path</filename></para> + <para><filename>systemd-ask-password-wall.service</filename></para> + <para><filename>systemd-ask-password-wall.path</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-ask-password-console.service</filename> + is a system service that queries the user for system + passwords (such as hard disk encryption keys and SSL + certificate passphrases) on the console. It is + intended to be used during boot to ensure proper + handling of passwords necessary for + boot. <filename>systemd-ask-password-wall.service</filename> + is a system service that informs all logged in users + for system passwords via + <citerefentry><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>. It + is intended to be used after boot to ensure that users + are properly notified.</para> + + <para>See the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/PasswordAgents"> + developer documentation</ulink> for more information + about the system password logic.</para> + + <para>Note that these services invoke + <citerefentry><refentrytitle>systemd-tty-ask-password-agent</refentrytitle><manvolnum>1</manvolnum></citerefentry> + with either the <command>--watch --console</command> + or <command>--watch --wall</command> command line + parameters.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-tty-ask-password-agent</refentrytitle><manvolnum>1</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 0000000000..7b0b9ab809 --- /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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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-binfmt.service.xml b/man/systemd-binfmt.service.xml new file mode 100644 index 0000000000..1db735a826 --- /dev/null +++ b/man/systemd-binfmt.service.xml @@ -0,0 +1,76 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> +<refentry id="systemd-binfmt.service"> + + <refentryinfo> + <title>systemd-binfmt.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-binfmt.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-binfmt.service</refname> + <refname>systemd-binfmt</refname> + <refpurpose>Configure additional binary formats for executables at boot</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-binfmt.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-binfmt</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-binfmt.service</filename> is + an early-boot service that registers additional binary + formats for executables in the kernel.</para> + + <para>See + <citerefentry><refentrytitle>binfmt.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for information about the configuration of this + service.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>binfmt.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>wine</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-cat.xml b/man/systemd-cat.xml new file mode 100644 index 0000000000..cac275b453 --- /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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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>, or 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 0000000000..4b6ee93b4e --- /dev/null +++ b/man/systemd-cgls.xml @@ -0,0 +1,141 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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> + + <para>By default empty control groups are not + 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>--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> + + <listitem><para>Don't hide empty + control groups in the + output.</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 0000000000..7a34512b21 --- /dev/null +++ b/man/systemd-cgtop.xml @@ -0,0 +1,276 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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>--version</option></term> + + <listitem><para>Prints a version string 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>-b</option></term> + <term><option>--batch</option></term> + + <listitem><para>Run in "batch" mode: + do not accept input and run until the + iteration limit set with + <option>--iterations</option> is + exhausted or until killed. This mode + could be useful for sending output + from <command>systemd-cgtop</command> + to other programs or to a + file.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-n</option></term> + <term><option>--iterations=</option></term> + + <listitem><para>Perform only this many + iterations.</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 + 3.</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>Sort the control groups + by path, number of tasks, CPU load, + memory usage, or IO + load, respectively.</para></listitem> + </varlistentry> + + <varlistentry> + <term>+</term> + <term>-</term> + + <listitem><para>Increase + or decrease refresh + delay, respectively.</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-coredumpctl.xml b/man/systemd-coredumpctl.xml new file mode 100644 index 0000000000..8b54b90999 --- /dev/null +++ b/man/systemd-coredumpctl.xml @@ -0,0 +1,214 @@ +<?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 Zbigniew Jędrzejewski-Szmek + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd-coredumpctl"> + + <refentryinfo> + <title>systemd-coredumpctl</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Zbigniew</firstname> + <surname>Jędrzejewski-Szmek</surname> + <email>zbyszek@in.waw.pl</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-coredumpctl</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-coredumpctl</refname> + <refpurpose>Retrieve coredumps from the journal</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-coredumpctl <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="req">COMMAND</arg> <arg choice="opt" rep="repeat">PID|COMM|EXE|MATCH</arg></command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-coredumpctl</command> may be used to + retrieve coredumps from + <citerefentry><refentrytitle>systemd-journald</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</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>Print a short help + text and exit.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--version</option></term> + + <listitem><para>Print a short version + string and exit.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--field=</option></term> + <term><option>-F</option></term> + + <listitem><para>Print all possible + data values the specified field + takes in matching coredump entries of the + journal.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--output=FILE</option></term> + <term><option>-o FILE</option></term> + + <listitem><para>Write the core to + <option>FILE</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--no-pager</option></term> + + <listitem><para>Do not pipe output of + <command>list</command> into a + pager.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--no-legend</option></term> + + <listitem><para>Do not print the column headers. + </para></listitem> + </varlistentry> + + </variablelist> + + <para>The following commands are understood:</para> + + <variablelist> + <varlistentry> + <term><command>list</command></term> + + <listitem><para>List coredumps captured in the journal + matching specified characteristics.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>dump</command></term> + + <listitem><para>Extract the last coredump + matching specified characteristics. + Coredump will be written on stdout, unless + an output file is specified with + <option>-o/--output</option>. + </para></listitem> + </varlistentry> + + + <varlistentry> + <term><command>gdb</command></term> + + <listitem><para>Invoke the GNU + debugger on the last coredump matching + specified characteristics. + </para></listitem> + </varlistentry> + + </variablelist> + + </refsect1> + + <refsect1> + <title>Matching</title> + + <para>Match can be:</para> + + <variablelist> + <varlistentry> + <term><option>PID</option></term> + + <listitem><para>Process ID of the + process that dumped + core. An integer.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>COMM</option></term> + + <listitem><para>Name of the executable + (matches <option>COREDUMP_COMM=</option>). + Must not contain slashes. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>EXE</option></term> + + <listitem><para>Path to the executable + (matches <option>COREDUMP_EXE=</option>). + Must contain at least one slash. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>MATCH</option></term> + + <listitem><para>General journalctl predicates + (see <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>). + Must contain an equals sign. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Exit status</title> + <para>On success 0 is returned, a non-zero failure + code otherwise. Not finding any matching coredumps is treated + as failure. + </para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-cryptsetup-generator.xml b/man/systemd-cryptsetup-generator.xml new file mode 100644 index 0000000000..49d4d5545b --- /dev/null +++ b/man/systemd-cryptsetup-generator.xml @@ -0,0 +1,147 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> +<refentry id="systemd-cryptsetup-generator"> + + <refentryinfo> + <title>systemd-cryptsetup-generator</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-cryptsetup-generator</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-cryptsetup-generator</refname> + <refpurpose>Unit generator for <filename>/etc/crypttab</filename></refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/usr/lib/systemd/system-generators/systemd-cryptsetup-generator</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-cryptsetup-generator</filename> + is a generator that translates + <filename>/etc/crypttab</filename> into native systemd + units early at boot and when configuration of the + system manager is reloaded. This will create + <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + units as necessary.</para> + + <para><filename>systemd-cryptsetup-generator</filename> + implements the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/Generators">generator + specification</ulink>.</para> + </refsect1> + + <refsect1> + <title>Kernel Command Line</title> + + <para><filename>systemd-cryptsetup-generator</filename> understands + the following kernel command line parameters:</para> + + <variablelist> + <varlistentry> + <term><varname>luks=</varname></term> + <term><varname>rd.luks=</varname></term> + + <listitem><para>Takes a boolean + argument. Defaults to + <literal>yes</literal>. If + <literal>no</literal> disables the + generator + entirely. <varname>rd.luks=</varname> + is honored only by initial RAM disk + (initrd) while + <varname>luks=</varname> is honored + by both the main system and the + initrd. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>luks.crypttab=</varname></term> + <term><varname>rd.luks.crypttab=</varname></term> + + <listitem><para>Takes a boolean + argument. Defaults to + <literal>yes</literal>. If + <literal>no</literal> causes the + generator to ignore any devices + configured in + <filename>/etc/crypttab</filename> + (<varname>luks.uuid=</varname> will + still work + however). <varname>rd.luks.crypttab=</varname> + is honored only by initial RAM disk + (initrd) while + <varname>luks.crypttab=</varname> is + honored by both the main system and + the initrd. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>luks.uuid=</varname></term> + <term><varname>rd.luks.uuid=</varname></term> + + <listitem><para>Takes a LUKS super + block UUID as argument. This will + activate the specified device as part + of the boot process as if it was + listed in + <filename>/etc/fstab</filename>. This + option may be specified more than once + in order to set up multiple + devices. <varname>rd.luks.uuid=</varname> + is honored only by initial RAM disk + (initrd) while + <varname>luks.uuid=</varname> is + honored by both the main system and + the initrd.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-cryptsetup@.service.xml b/man/systemd-cryptsetup@.service.xml new file mode 100644 index 0000000000..abbb9d78f2 --- /dev/null +++ b/man/systemd-cryptsetup@.service.xml @@ -0,0 +1,87 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> +<refentry id="systemd-cryptsetup@.service"> + + <refentryinfo> + <title>systemd-cryptsetup@.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-cryptsetup@.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-cryptsetup@.service</refname> + <refname>systemd-cryptsetup</refname> + <refpurpose>Full disk decryption logic</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-cryptsetup@.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-cryptsetup</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-cryptsetup@.service</filename> + is a service responsible for setting up encrypted + block devices. It is instantiated for each device that + requires decryption for access.</para> + + <para><filename>systemd-cryptsetup@.service</filename> + will ask for hard disk passwords via the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/PasswordAgents"> + password agent logic</ulink>, in order to query the + user for the password using the right mechanism at + boot and during runtime.</para> + + <para>At early boot and when the system manager + configuration is reloaded this + <filename>/etc/crypttab</filename> is translated into + <filename>systemd-cryptsetup@.service</filename> units + by + <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-delta.xml b/man/systemd-delta.xml new file mode 100644 index 0000000000..072f55f1a1 --- /dev/null +++ b/man/systemd-delta.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 2012 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd-delta"> + + <refentryinfo> + <title>systemd-delta</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-delta</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-delta</refname> + <refpurpose>Find overridden configuration files</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-delta <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt" rep="repeat">SUFFIX</arg></command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-delta</command> may be used to + identify and compare configuration files in + <filename>/etc</filename> that override default + counterparts in <filename>/usr</filename>. The command + line argument can be one or more name of a subdirectories of + <filename>/etc</filename> or + <filename>/usr/lib</filename> to compare, such as + <filename>tmpfiles.d</filename>, <filename>sysctl.d</filename> or + <filename>systemd/system</filename>.</para> + + <para>When no argument is specified a number of + well-known subdirectories are searched for overridden + files.</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>--no-pager</option></term> + + <listitem><para>Do not pipe output into a + pager.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--type=</option></term> + <term><option>-t</option></term> + + <listitem><para>When listing the + differences, only list those that are + asked for. The list itself is a + comma-separated list of desired + difference types.</para> + + <para>Recognized types are: + + <variablelist> + <varlistentry> + <term><varname>masked</varname></term> + + <listitem><para>Show masked files</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>equivalent</varname></term> + + <listitem><para>Show overridden + files that while overridden, do + not differ in content.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>redirected</varname></term> + + <listitem><para>Show files that + are redirected to another.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>overridden</varname></term> + + <listitem><para>Show overridden, + and changed files.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>unchanged</varname></term> + + <listitem><para>Show unmodified + files too.</para></listitem> + </varlistentry> + </variablelist> + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--diff=</option></term> + + <listitem><para>When showing modified + files, when a file is overridden show a + diff as well. This option takes a + boolean argument. If omitted it defaults + to <option>true</option>.</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> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-detect-virt.xml b/man/systemd-detect-virt.xml new file mode 100644 index 0000000000..762b6ab992 --- /dev/null +++ b/man/systemd-detect-virt.xml @@ -0,0 +1,151 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd-detect-virt"> + + <refentryinfo> + <title>systemd-detect-virt</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-detect-virt</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-detect-virt</refname> + <refpurpose>Detect execution in a virtualized environment</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-detect-virt <arg choice="opt" rep="repeat">OPTIONS</arg></command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-detect-virt</command> detects + execution in a virtualized environment. It identifies + the virtualization technology and can distinguish full + VM virtualization from container + virtualization.</para> + + <para>When executed without <option>--quiet</option> + will print a short identifier for the detected + virtualization technology. The following technologies + are currently identified: <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>.</para> + + <para>If multiple virtualization solutions are used + only the "innermost" is detected and identified. That + means if both VM virtualization and container + virtualization are used in conjunction only the latter + will be identified (unless <option>--vm</option> is + passed).</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>-c</option></term> + <term><option>--container</option></term> + + <listitem><para>Only detects container + virtualization (i.e. shared kernel + virtualization).</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-v</option></term> + <term><option>--vm</option></term> + + <listitem><para>Only detects VM + virtualization (i.e. full hardware + virtualization).</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-q</option></term> + <term><option>--quiet</option></term> + + <listitem><para>Suppress output of the + virtualization technology + identifier.</para></listitem> + </varlistentry> + + </variablelist> + + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>If a virtualization technology is detected 0 is + returned, a non-zero code otherwise.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-fsck@.service.xml b/man/systemd-fsck@.service.xml new file mode 100644 index 0000000000..62f63110e1 --- /dev/null +++ b/man/systemd-fsck@.service.xml @@ -0,0 +1,110 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> +<refentry id="systemd-fsck@.service"> + + <refentryinfo> + <title>systemd-fsck@.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-fsck@.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-fsck@.service</refname> + <refname>systemd-fsck-root.service</refname> + <refname>systemd-fsck</refname> + <refpurpose>File system checker logic</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-fsck@.service</filename></para> + <para><filename>systemd-fsck-root.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-fsck</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-fsck@.service</filename> is a + service responsible for file system checks. It is + instantiated for each device that requires a file + system + check. <filename>systemd-fsck-root.service</filename> is + responsible for file system checks on the root + file system.</para> + + <para><filename>systemd-fsck</filename> will + forward file system checking progress to the + console. If a file system check fails emergency mode + is activated, by isolating to + <filename>emergency.target</filename>.</para> + </refsect1> + + <refsect1> + <title>Kernel Command Line</title> + + <para><filename>systemd-fsck</filename> understands + one kernel command line parameter:</para> + + <variablelist> + <varlistentry> + <term><varname>fsck.mode=</varname></term> + + <listitem><para>One of + <literal>auto</literal>, + <literal>force</literal>, + <literal>skip</literal>. Controls the + mode of operation. The default is + <literal>auto</literal>, and ensures + that file system checks are done when + the file system checker deems them + necessary. <literal>force</literal> + unconditionally results in full file + system checks. <literal>skip</literal> + skips any file system + checks.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>fsck</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-quotacheck.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-fstab-generator.xml b/man/systemd-fstab-generator.xml new file mode 100644 index 0000000000..2decec6c40 --- /dev/null +++ b/man/systemd-fstab-generator.xml @@ -0,0 +1,118 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> +<refentry id="systemd-fstab-generator"> + + <refentryinfo> + <title>systemd-fstab-generator</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-fstab-generator</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-fstab-generator</refname> + <refpurpose>Unit generator for /etc/fstab</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/usr/lib/systemd/system-generators/systemd-fstab-generator</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-fstab-generator</filename> is + a generator that translates + <filename>/etc/fstab</filename> (see + <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details) into native systemd units early at boot + and when configuration of the system manager is + reloaded. This will instantiate mount and swap units + as necessary.</para> + + <para>See + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information about special + <filename>/etc/fstab</filename> mount options this + generator understands.</para> + + <para><filename>systemd-fstab-generator</filename> + implements the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/Generators">generator + specification</ulink>.</para> + </refsect1> + + <refsect1> + <title>Kernel Command Line</title> + + <para><filename>systemd-fstab-generator</filename> understands + the following kernel command line parameters:</para> + + <variablelist> + + <varlistentry> + <term><varname>fstab=</varname></term> + <term><varname>rd.fstab=</varname></term> + + <listitem><para>Takes a boolean + argument. Defaults to + <literal>yes</literal>. If + <literal>no</literal> causes the + generator to ignore any mounts or swaps + configured in + <filename>/etc/fstab</filename>. <varname>rd.fstab=</varname> + is honored only by initial RAM disk + (initrd) while + <varname>luks.fstab=</varname> is + honored by both the main system and + the initrd. </para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-getty-generator.xml b/man/systemd-getty-generator.xml new file mode 100644 index 0000000000..1c9c9345f9 --- /dev/null +++ b/man/systemd-getty-generator.xml @@ -0,0 +1,90 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> +<refentry id="systemd-getty-generator"> + + <refentryinfo> + <title>systemd-getty-generator</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-getty-generator</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-getty-generator</refname> + <refpurpose>Generator for enabling getty instances on + the console</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/usr/lib/systemd/system-generators/systemd-getty-generator</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-getty-generator</filename> is + a generator that automatically instantiates + <filename>serial-getty@.service</filename> on the + kernel console <filename>/dev/console</filename> if + that is not directed to the virtual console + subsystem. It will also instantiate + <filename>serial-getty@.service</filename> instances + for virtualizer consoles, if execution in a + virtualized environment is detected. This should + ensure that the user is shown a login prompt at the + right place, regardless in which environment the + system is started. For example, it is sufficient to + redirect the kernel console with a kernel command line + argument such as <varname>console=</varname> to get + both kernel messages and a getty prompt on a serial + TTY. See <ulink + url="https://www.kernel.org/doc/Documentation/kernel-parameters.txt"><filename>kernel-parameters.txt</filename></ulink> + for more information on the + <varname>console=</varname> kernel parameter.</para> + + <para><filename>systemd-getty-generator</filename> + implements the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/Generators">generator + specification</ulink>.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>agetty</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-halt.service.xml b/man/systemd-halt.service.xml new file mode 100644 index 0000000000..6a6bfdc7d7 --- /dev/null +++ b/man/systemd-halt.service.xml @@ -0,0 +1,119 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd-halt.service"> + + <refentryinfo> + <title>systemd-halt.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-halt.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-halt.service</refname> + <refname>systemd-poweroff.service</refname> + <refname>systemd-reboot.service</refname> + <refname>systemd-kexec.service</refname> + <refname>systemd-shutdown</refname> + <refpurpose>System shutdown logic</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-halt.service</filename></para> + <para><filename>systemd-poweroff.service</filename></para> + <para><filename>systemd-reboot.service</filename></para> + <para><filename>systemd-kexec.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-shutdown</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-halt.service</filename> is a + system service that is pulled in by + <filename>halt.target</filename> and is responsible + for the actual system halt. Similar, + <filename>systemd-poweroff.service</filename> is + pulled in by <filename>poweroff.target</filename>, + <filename>systemd-reboot.service</filename> by + <filename>reboot.target</filename> and + <filename>systemd-kexec.service</filename> by + <filename>kexec.target</filename> to execute the + respective actions.</para> + + <para>When these services are run they ensure that PID + 1 is replaced by the + <filename>/usr/lib/systemd/systemd-shutdown</filename> + tool which is then responsible for the actual + shutdown. Before shutting down this binary will try to + unmount all remaining file systems, disable all + remaining swap devices, detach all remaining storage + devices and kill all remaining processes.</para> + + <para>Immediately before executing the actual system + halt/poweroff/reboot/kexec + <filename>systemd-shutdown</filename> will run all + executables in + <filename>/usr/lib/systemd/system-shutdown/</filename> + and pass one arguments to them: either + "<literal>halt</literal>", + "<literal>poweroff</literal>", + "<literal>reboot</literal>" or + "<literal>kexec</literal>", depending on the chosen + action. All executables in this directory are executed + in parallel, and execution of the action is not + continued before all executables finished.</para> + + <para>Note that + <filename>systemd-halt.service</filename> (and the + related units) should never be executed + directly. Instead, trigger system shutdown with a + command such as "<literal>systemctl halt</literal>" or + suchlike.</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.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-suspend.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-hostnamed.service.xml b/man/systemd-hostnamed.service.xml new file mode 100644 index 0000000000..d9c1911018 --- /dev/null +++ b/man/systemd-hostnamed.service.xml @@ -0,0 +1,87 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd-hostnamed.service"> + + <refentryinfo> + <title>systemd-hostnamed.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-hostnamed.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-hostnamed.service</refname> + <refname>systemd-hostnamed</refname> + <refpurpose>Hostname bus mechanism</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-hostnamed.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-hostnamed</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-hostnamed</filename> is a system + service that may be used as mechanism to change the + system hostname. <filename>systemd-hostnamed</filename> is + automatically activated on request and terminates + itself when it is unused.</para> + + <para>The tool + <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + is a command line client to this service.</para> + + <para>See the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/hostnamed"> + developer documentation</ulink> for information about + the APIs <filename>systemd-hostnamed</filename> + provides.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-inhibit.xml b/man/systemd-inhibit.xml new file mode 100644 index 0000000000..6f63c8c73e --- /dev/null +++ b/man/systemd-inhibit.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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd-inhibit"> + + <refentryinfo> + <title>systemd-inhibit</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-inhibit</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-inhibit</refname> + <refpurpose>Execute a program with an inhibition lock taken</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-inhibit <arg choice="opt" rep="repeat">OPTIONS</arg> <arg>COMMAND</arg> <arg choice="opt" rep="repeat">ARGUMENTS</arg></command> + </cmdsynopsis> + <cmdsynopsis> + <command>systemd-inhibit <arg choice="opt" rep="repeat">OPTIONS</arg> --list</command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-inhibit</command> may be used + to execute a program with a shutdown, sleep or idle + inhibitor lock taken. The lock will be acquired before + the specified command line is executed and released + afterwards.</para> + + <para>Inhibitor locks may be used to block or delay + system sleep and shutdown requests from the user, as well + as automatic idle handling of the OS. This is useful + to avoid system suspends while an optical disc is + being recorded, or similar operations that should not + be interrupted.</para> + + <para>For more information see the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/inhibit">Inhibitor + Lock Developer Documentation</ulink>.</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>--what=</option></term> + + <listitem><para>Takes a colon + separated list of one or more + operations to inhibit: + <literal>shutdown</literal>, + <literal>sleep</literal>, + <literal>idle</literal>, + <literal>handle-power-key</literal>, + <literal>handle-suspend-key</literal>, + <literal>handle-hibernate-key</literal>, + <literal>handle-lid-switch</literal>, + for inhibiting + reboot/power-off/halt/kexec, + suspending/hibernating, the automatic + idle detection, or the low-level + handling of the power/sleep key and + the lid switch, respectively. If omitted, + defaults to + <literal>idle:sleep:shutdown</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--who=</option></term> + + <listitem><para>Takes a short human + readable descriptive string for the + program taking the lock. If not passed + defaults to the command line + string.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--why=</option></term> + + <listitem><para>Takes a short human + readable descriptive string for the + reason for taking the lock. Defaults + to "Unknown reason".</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--mode=</option></term> + + <listitem><para>Takes either + <literal>block</literal> or + <literal>delay</literal> and describes + how the lock is applied. If + <literal>block</literal> is used (the + default), the lock prohibits any of + the requested operations without time + limit, and only privileged users may + override it. If + <literal>delay</literal> is used, the + lock can only delay the requested + operations for a limited time. If the + time elapses the lock is ignored and + the operation executed. The time limit + may be specified in + <citerefentry><refentrytitle>systemd-logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Note + that <literal>delay</literal> is only + available for <literal>sleep</literal> + and + <literal>shutdown</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--list</option></term> + + <listitem><para>Lists all active + inhibition locks instead of acquiring + one.</para></listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>Returns the exit status of the executed program.</para> + </refsect1> + + <refsect1> + <title>Example</title> + + <programlisting># systemd-inhibit wodim foobar.iso</programlisting> + + <para>This burns the ISO image + <filename>foobar.iso</filename> on a CD using + <citerefentry><refentrytitle>wodim</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + and inhibits system sleeping, shutdown and idle while + doing so.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-initctl.service.xml b/man/systemd-initctl.service.xml new file mode 100644 index 0000000000..eda6459b50 --- /dev/null +++ b/man/systemd-initctl.service.xml @@ -0,0 +1,76 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd-initctl.service"> + + <refentryinfo> + <title>systemd-initctl.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-initctl.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-initctl.service</refname> + <refname>systemd-initctl.socket</refname> + <refname>systemd-initctl</refname> + <refpurpose>/dev/initctl compatibility</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-initctl.service</filename></para> + <para><filename>systemd-initctl.socket</filename></para> + <para><filename>/usr/lib/systemd/systemd-initctl</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-initctl</filename> is a system + service that implements compatibility with the + <filename>/dev/initctl</filename> FIFO file system + object, as implemented by the SysV init system. <filename>systemd-initctl</filename> is + automatically activated on request and terminates + itself when it is unused.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-journald.service.xml b/man/systemd-journald.service.xml new file mode 100644 index 0000000000..abc03df5db --- /dev/null +++ b/man/systemd-journald.service.xml @@ -0,0 +1,173 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd-journald.service"> + + <refentryinfo> + <title>systemd-journald.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-journald.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-journald.service</refname> + <refname>systemd-journald.socket</refname> + <refname>systemd-journald</refname> + <refpurpose>Journal service</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-journald.service</filename></para> + <para><filename>systemd-journald.socket</filename></para> + <para><filename>/usr/lib/systemd/systemd-journald</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-journald</filename> is a + system service that collects and stores logging + data. It creates and maintains structured, indexed + journals based on logging information that is received + from the kernel, from user processes via the libc + <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call, from STDOUT/STDERR of system services or via its + native API. It will implicitly collect numerous meta + data fields for each log messages in a secure and + unfakeable way. See + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for more information about the collected meta data. + </para> + + <para>Log data collected by the journal is primarily + text based but can also include binary data where + necessary. All objects stored in the journal can be up + to 2^64-1 bytes in size.</para> + + <para>By default the journal stores log data in + <filename>/run/log/journal/</filename>. Since + <filename>/run/</filename> is volatile log data is + lost at reboot. To make the data persistent it + is sufficient to create + <filename>/var/log/journal/</filename> where + <filename>systemd-journald</filename> will then store + the data.</para> + + <para><filename>systemd-journald</filename> will + forward all received log messages to the AF_UNIX + SOCK_DGRAM socket + <filename>/run/systemd/journal/syslog</filename> (if it exists) which + may be used by UNIX syslog daemons to process the data + further.</para> + + <para>See + <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for information about the configuration of this + service.</para> + </refsect1> + + <refsect1> + <title>Signals</title> + + <variablelist> + <varlistentry> + <term>SIGUSR1</term> + + <listitem><para>Request that journal + data from <filename>/run/</filename> + is flushed to + <filename>/var/</filename> in order to + make it persistent (if this is + enabled). This may be used after + <filename>/var/</filename> is mounted, + but is generally not required since + the first journal write when + <filename>/var/</filename> becomes + writable triggers the flushing + anyway.</para></listitem> + </varlistentry> + + <varlistentry> + <term>SIGUSR2</term> + + <listitem><para>Request immediate + rotation of the journal + files.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Kernel Command Line</title> + + <para>A few configuration parameters from + <filename>journald.conf</filename> may be overridden on + the kernel command line:</para> + + <variablelist> + <varlistentry> + <term><varname>systemd.journald.forward_to_syslog=</varname></term> + <term><varname>systemd.journald.forward_to_kmsg=</varname></term> + <term><varname>systemd.journald.forward_to_console=</varname></term> + + <listitem><para>Enables/disables + forwarding of collected log messages + to syslog, the kernel log buffer or + the system console. + </para> + + <para>See + <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for information about these settings.</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>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-localed.service.xml b/man/systemd-localed.service.xml new file mode 100644 index 0000000000..6cefc4265f --- /dev/null +++ b/man/systemd-localed.service.xml @@ -0,0 +1,89 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd-localed.service"> + + <refentryinfo> + <title>systemd-localed.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-localed.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-localed.service</refname> + <refname>systemd-localed</refname> + <refpurpose>Locale bus mechanism</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-localed.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-localed</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-localed</filename> is a system + service that may be used as mechanism to change the + system locale settings, as well as the console key + mapping and default X11 key + mapping. <filename>systemd-localed</filename> is + automatically activated on request and terminates + itself when it is unused.</para> + + <para>The tool + <citerefentry><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + is a command line client to this service.</para> + + <para>See the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/localed"> + developer documentation</ulink> for information about + the APIs <filename>systemd-localed</filename> + provides.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>loadkeys</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-logind.service.xml b/man/systemd-logind.service.xml new file mode 100644 index 0000000000..00f34051a3 --- /dev/null +++ b/man/systemd-logind.service.xml @@ -0,0 +1,133 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd-logind.service"> + + <refentryinfo> + <title>systemd-logind.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-logind.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-logind.service</refname> + <refname>systemd-logind</refname> + <refpurpose>Login manager</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-logind.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-logind</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-logind</filename> is a system + service that manages user logins. It is responsible + for:</para> + + <itemizedlist> + <listitem><para>Keeping track of users and sessions, their + processes and their idle state</para></listitem> + + <listitem><para>Creating control groups for + user processes</para></listitem> + + <listitem><para>Providing PolicyKit-based access + for users to operations such as system + shutdown or sleep</para></listitem> + + <listitem><para>Implementing a shutdown/sleep + inhibition logic for + applications</para></listitem> + + <listitem><para>Handling of power/sleep + hardware keys</para></listitem> + + <listitem><para>Multi-seat + management</para></listitem> + + <listitem><para>Session + switch management</para></listitem> + + <listitem><para>Device access management for + users</para></listitem> + + <listitem><para>Automatic spawning of text + logins (gettys) on virtual console activation + and user runtime directory + management</para></listitem> + </itemizedlist> + + <para>User sessions are registered in logind via the + <citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry> + PAM module.</para> + + <para>See + <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for information about the configuration of this + service.</para> + + <para>See <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/multiseat">Multi-Seat + on Linux</ulink> for an introduction into basic + concepts of logind such as users, sessions and seats.</para> + + <para>See the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/logind"> + logind D-Bus API Documentation</ulink> for information about + the APIs <filename>systemd-logind</filename> + provides.</para> + + <para>For more information on the inhibition logic see + the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/inhibit">Inhibitor + Lock Developer Documentation</ulink>.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-user-sessions.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</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 0000000000..25fb63af2d --- /dev/null +++ b/man/systemd-machine-id-setup.xml @@ -0,0 +1,132 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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 /etc/machine-id</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>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> + </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>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>dbus-uuidgen</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-modules-load.service.xml b/man/systemd-modules-load.service.xml new file mode 100644 index 0000000000..e5f10a7beb --- /dev/null +++ b/man/systemd-modules-load.service.xml @@ -0,0 +1,101 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> +<refentry id="systemd-modules-load.service"> + + <refentryinfo> + <title>systemd-modules-load.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-modules-load.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-modules-load.service</refname> + <refname>systemd-modules-load</refname> + <refpurpose>Configure kernel modules to load at boot</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-modules-load.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-modules-load</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-modules-load.service</filename> + is an early-boot service that loads kernel modules + from static configuration.</para> + + <para>See + <citerefentry><refentrytitle>modules-load.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for information about the configuration of this + service.</para> + + </refsect1> + + <refsect1> + <title>Kernel Command Line</title> + + <para><filename>systemd-modules-load.service</filename> understands + the following kernel command line parameters:</para> + + <variablelist> + + <varlistentry> + <term><varname>modules-load=</varname></term> + <term><varname>rd.modules-load=</varname></term> + + <listitem><para>Takes a comma + separated list of kernel modules to + statically load during early boot. The + option prefixed with + <literal>rd.</literal> is read by the + initial RAM disk + only.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>modules-load.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>wine</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-notify.xml b/man/systemd-notify.xml new file mode 100644 index 0000000000..b03492c5c1 --- /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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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 service manager 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 0000000000..fef5c2c83a --- /dev/null +++ b/man/systemd-nspawn.xml @@ -0,0 +1,331 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry> + or + <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</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> + + <para><command>systemd-nspawn</command> implements the + <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container + Interface</ulink> specification.</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>--boot</option></term> + <term><option>-b</option></term> + + <listitem><para>Automatically search + for an init binary and invoke it + instead of a shell or a user supplied + program.</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>--uuid=</option></term> + + <listitem><para>Set the specified uuid + for the container. The init system + will initialize + <filename>/etc/machine-id</filename> + from this if this file is not set yet. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--controllers=</option></term> + <term><option>-C</option></term> + + <listitem><para>Makes the container appear in + other hierarchies than the name=systemd:/ one. + Takes a comma-separated list of controllers. + </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> + + <varlistentry> + <term><option>--read-only</option></term> + + <listitem><para>Mount the root file + system read only for the + container.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--capability=</option></term> + + <listitem><para>List one or more + additional capabilities to grant the + container. Takes a comma separated + list of capability names, see + <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for more information. Note that the + following capabilities will be + granted in any way: CAP_CHOWN, + CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH, + CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER, + CAP_KILL, CAP_LEASE, + CAP_LINUX_IMMUTABLE, + CAP_NET_BIND_SERVICE, + CAP_NET_BROADCAST, CAP_NET_RAW, + CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP, + CAP_SETUID, CAP_SYS_ADMIN, + CAP_SYS_CHROOT, CAP_SYS_NICE, + CAP_SYS_PTRACE, CAP_SYS_TTY_CONFIG, + CAP_SYS_RESOURCE, CAP_SYS_BOOT.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--link-journal=</option></term> + + <listitem><para>Control whether the + container's journal shall be made + visible to the host system. If enabled + allows viewing the container's journal + files from the host (but not vice + versa). Takes one of + <literal>no</literal>, + <literal>host</literal>, + <literal>guest</literal>, + <literal>auto</literal>. If + <literal>no</literal>, the journal is + not linked. If <literal>host</literal>, + the journal files are stored on the + host file system (beneath + <filename>/var/log/journal/<machine-id></filename>) + and the subdirectory is bind-mounted + into the container at the same + location. If <literal>guest</literal>, + the journal files are stored on the + guest file system (beneath + <filename>/var/log/journal/<machine-id></filename>) + and the subdirectory is symlinked into the host + at the same location. If + <literal>auto</literal> (the default), + and the right subdirectory of + <filename>/var/log/journal</filename> + exists, it will be bind mounted + into the container. If the + subdirectory doesn't exist, no + linking is performed. Effectively, + booting a container once with + <literal>guest</literal> or + <literal>host</literal> will link the + journal persistently if further on + the default of <literal>auto</literal> + is used.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-j</option></term> + + <listitem><para>Equivalent to + <option>--link-journal=guest</option>.</para></listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>Example 1</title> + + <programlisting># yum --releasever=17 --nogpgcheck --installroot ~/fedora-tree/ install yum passwd vim-minimal rootfiles systemd +# systemd-nspawn -D ~/fedora-tree /usr/lib/systemd/systemd</programlisting> + + <para>This installs a minimal Fedora distribution into + the directory <filename>~/fedora-tree/</filename> + and then boots an OS in a namespace container in it, + with systemd as init system.</para> + </refsect1> + + <refsect1> + <title>Example 2</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>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>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-quotacheck.service.xml b/man/systemd-quotacheck.service.xml new file mode 100644 index 0000000000..4d0218b659 --- /dev/null +++ b/man/systemd-quotacheck.service.xml @@ -0,0 +1,102 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> +<refentry id="systemd-quotacheck.service"> + + <refentryinfo> + <title>systemd-quotacheck.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-quotacheck.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-quotacheck.service</refname> + <refname>systemd-quotacheck</refname> + <refpurpose>File system quota checker logic</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-quotacheck.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-quotacheck</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-quotacheck.service</filename> + is a service responsible for file system quota + checks. It is run once at boot after all necessary + file systems are mounted. It is pulled in only if at + least one file system has quotas enabled.</para> + </refsect1> + + <refsect1> + <title>Kernel Command Line</title> + + <para><filename>systemd-quotacheck</filename> understands + one kernel command line parameter:</para> + + <variablelist> + <varlistentry> + <term><varname>quotacheck.mode=</varname></term> + + <listitem><para>One of + <literal>auto</literal>, + <literal>force</literal>, + <literal>skip</literal>. Controls the + mode of operation. The default is + <literal>auto</literal>, and ensures + that file system quota checks are done + when the file system quota checker + deems them + necessary. <literal>force</literal> + unconditionally results in full file + system quota + checks. <literal>skip</literal> skips + any file system quota + checks.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>quotacheck</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-fsck@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-random-seed-load.service.xml b/man/systemd-random-seed-load.service.xml new file mode 100644 index 0000000000..87f563e293 --- /dev/null +++ b/man/systemd-random-seed-load.service.xml @@ -0,0 +1,80 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> +<refentry id="systemd-random-seed-load.service"> + + <refentryinfo> + <title>systemd-random-seed-load.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-random-seed-load.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-random-seed-load.service</refname> + <refname>systemd-random-seed-save.service</refname> + <refname>systemd-random-seed</refname> + <refpurpose>Load and save the system random seed at boot and shutdown</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-random-seed-load.service</filename></para> + <para><filename>systemd-random-seed-save.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-random-seed</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-random-seed-load.service</filename> + is an early-boot service that restores the random seed + of the + system. <filename>systemd-random-seed-save.service</filename> + is a late-shutdown service that saves the random seed + of the system. See + <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> + for details. Saving/restoring the random seed across + boots increases the amount of available entropy early + at boot. On disk the random seed is stored in + <filename>/var/lib/random-seed</filename>.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-readahead-replay.service.xml b/man/systemd-readahead-replay.service.xml new file mode 100644 index 0000000000..66d253454b --- /dev/null +++ b/man/systemd-readahead-replay.service.xml @@ -0,0 +1,113 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd-readahead-replay.service"> + + <refentryinfo> + <title>systemd-readahead-replay.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-readahead-replay.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-readahead-replay.service</refname> + <refname>systemd-readahead-collect.service</refname> + <refname>systemd-readahead-done.service</refname> + <refname>systemd-readahead-done.timer</refname> + <refname>systemd-readahead</refname> + <refpurpose>Disk read ahead logic</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-readahead-replay.service</filename></para> + <para><filename>systemd-readahead-collect.service</filename></para> + <para><filename>systemd-readahead-done.service</filename></para> + <para><filename>systemd-readahead-done.timer</filename></para> + <para><filename>/usr/lib/systemd/systemd-readahead</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-readahead-collect.service</filename> + is a service that collects disk usage patterns at boot + time. <filename>systemd-readahead-replay.service</filename> + is a service that replays this access data collected + at the subsequent boot. Since disks tend to be + magnitudes slower than RAM this is intended to improve + boot speeds by pre-loading early at boot all data on + disk that is known to be read for the complete boot + process.</para> + + <para><filename>systemd-readahead-done.service</filename> + is executed a short while after boot completed and signals + <filename>systemd-readahead-collect.service</filename> + to end data collection. On this signal this service + will then sort the collected disk accesses and store + information about them disk in + <filename>/.readahead</filename>.</para> + + <para>Normally, both + <filename>systemd-readahead-collect.service</filename> + and + <filename>systemd-readahead-replay.service</filename> + are activated at boot so that access patterns from the + preceding boot are replayed and new data collected + for the subsequent boot. However, on read-only media + where the collected data cannot be stored it might + be a good idea to disable + <filename>systemd-readahead-collect.service</filename>.</para> + + <para>On rotating media, when replaying disk accesses + at early boot + <filename>systemd-readahead-replay.service</filename> + will order read requests by their location on disk. On + non-rotating media, they will be ordered by their + original access timestamp. If the file system supports + it + <filename>systemd-readahead-collect.service</filename> + will also defragment and rearrange files on disk to + optimize subsequent boot times.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-remount-fs.service.xml b/man/systemd-remount-fs.service.xml new file mode 100644 index 0000000000..d920c0c400 --- /dev/null +++ b/man/systemd-remount-fs.service.xml @@ -0,0 +1,87 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> +<refentry id="systemd-remount-fs.service"> + + <refentryinfo> + <title>systemd-remount-fs.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-remount-fs.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-remount-fs.service</refname> + <refname>systemd-remount-fs</refname> + <refpurpose>Remount root and kernel file systems</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-remount-fs.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-remount-fs</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-remount-fs.service</filename> + is an early-boot service that applies mount options + listed in + <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry> + to the root file system, the <filename>/usr</filename> + file system and the kernel API virtual file + systems. This is required so that the mount options of + these file systems -- which are pre-mounted by the + kernel, the initial RAM disk, container environments + or system manager code -- are updated to those listed + in <filename>/etc/fstab</filename>. This service + ignores normal file systems and only changes the root + file system (i.e. <filename>/</filename>), + <filename>/usr</filename> and the virtual kernel API + file systems such as <filename>/proc</filename>, + <filename>/sys</filename> or + <filename>/dev/</filename>. This service executes no + operation if <filename>/etc/fstab</filename> does not + exist or lists no entries for the mentioned file systems.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-shutdownd.service.xml b/man/systemd-shutdownd.service.xml new file mode 100644 index 0000000000..c1b8ef7a49 --- /dev/null +++ b/man/systemd-shutdownd.service.xml @@ -0,0 +1,77 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd-shutdownd.service"> + + <refentryinfo> + <title>systemd-shutdownd.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-shutdownd.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-shutdownd.service</refname> + <refname>systemd-shutdownd.socket</refname> + <refname>systemd-shutdownd</refname> + <refpurpose>Scheduled shutdown service</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-shutdownd.service</filename></para> + <para><filename>systemd-shutdownd.socket</filename></para> + <para><filename>/usr/lib/systemd/systemd-shutdownd</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-shutdownd.service</filename> is a + system service that implements scheduled shutdowns, as + exposed by + <citerefentry><refentrytitle>shutdown</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + <filename>systemd-shutdownd.service</filename> is automatically activated on request and terminates + itself when it is unused.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>shutdown</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-suspend.service.xml b/man/systemd-suspend.service.xml new file mode 100644 index 0000000000..9b8bad4791 --- /dev/null +++ b/man/systemd-suspend.service.xml @@ -0,0 +1,126 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd-suspend.service"> + + <refentryinfo> + <title>systemd-suspend.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-suspend.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-suspend.service</refname> + <refname>systemd-hibernate.service</refname> + <refname>systemd-hybrid-sleep.service</refname> + <refname>systemd-sleep</refname> + <refpurpose>System sleep state logic</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-suspend.service</filename></para> + <para><filename>systemd-hibernate.service</filename></para> + <para><filename>systemd-hybrid-sleep.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-sleep</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-suspend.service</filename> is + a system service that is pulled in by + <filename>suspend.target</filename> and is responsible + for the actual system suspend. Similar, + <filename>systemd-hibernate.service</filename> is + pulled in by <filename>hibernate.target</filename> to + execute the actual hibernation. Finally, + <filename>systemd-hybrid-sleep.service</filename> is + pulled in by <filename>hybrid-sleep.target</filename> + to execute hybrid hibernation with system + suspend.</para> + + <para>Immediately before entering system suspend + and/or hibernation + <filename>systemd-suspend.service</filename> (and the + other mentioned units, respectively) will run all + executables in + <filename>/usr/lib/systemd/system-sleep/</filename> + and pass two arguments to them. The first argument + will be "<literal>pre</literal>", the second either + "<literal>suspend</literal>", + "<literal>hibernate</literal>", or + "<literal>hybrid-sleep</literal>" depending on the + chosen action. Immediately after leaving system + suspend and/or hibernation the same executables are run, + but the first argument is now + "<literal>post</literal>". All executables in this + directory are executed in parallel, and execution of + the action is not continued before all executables + finished.</para> + + <para>Note that scripts or binaries dropped in + <filename>/usr/lib/systemd/system-sleep/</filename> + are intended for local use only and should be + considered hacks. If applications want to be notified + of system suspend/hibernation and resume there are + much nicer interfaces available.</para> + + <para>Note that + <filename>systemd-suspend.service</filename>, + <filename>systemd-hibernate.service</filename> and + <filename>systemd-hybrid-sleep.service</filename> + should never be executed directly. Instead, trigger + system sleep states with a command such as + "<literal>systemctl suspend</literal>" or + similar.</para> + + <para>Internally, this service will echo a string like + <literal>mem</literal> into + <filename>/sys/power/state</filename>, to trigger the + actual system suspend.</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.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-halt.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-sysctl.service.xml b/man/systemd-sysctl.service.xml new file mode 100644 index 0000000000..72a102c128 --- /dev/null +++ b/man/systemd-sysctl.service.xml @@ -0,0 +1,78 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> +<refentry id="systemd-sysctl.service"> + + <refentryinfo> + <title>systemd-sysctl.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-sysctl.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-sysctl.service</refname> + <refname>systemd-sysctl</refname> + <refpurpose>Configure kernel parameters at boot</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-sysctl.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-sysctl</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-sysctl.service</filename> is + an early-boot service that configures + <citerefentry><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry> + kernel parameters.</para> + + <para>See + <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for information about the configuration of this + service.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>wine</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-system-update-generator.xml b/man/systemd-system-update-generator.xml new file mode 100644 index 0000000000..18a23ed7fc --- /dev/null +++ b/man/systemd-system-update-generator.xml @@ -0,0 +1,79 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> +<refentry id="systemd-system-update-generator"> + + <refentryinfo> + <title>systemd-system-update-generator</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-system-update-generator</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-system-update-generator</refname> + <refpurpose>Generator for redirecting boot to offline update mode</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/usr/lib/systemd/system-generators/systemd-system-update-generator</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-system-update-generator</filename> + is a generator that automatically redirects the boot + process to <filename>system-update.target</filename> + if <filename>/system-update</filename> exists. This is + required to implement the logic explained in the + <ulink + url="http://freedesktop.org/wiki/Software/systemd/SystemUpdates">System + Updates Specification</ulink>. + </para> + + <para><filename>systemd-system-update-generator</filename> + implements the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/Generators">generator + specification</ulink>.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-timedated.service.xml b/man/systemd-timedated.service.xml new file mode 100644 index 0000000000..ea2abc5765 --- /dev/null +++ b/man/systemd-timedated.service.xml @@ -0,0 +1,88 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd-timedated.service"> + + <refentryinfo> + <title>systemd-timedated.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-timedated.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-timedated.service</refname> + <refname>systemd-timedated</refname> + <refpurpose>Time and date bus mechanism</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-timedated.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-timedated</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-timedated</filename> is a + system service that may be used as mechanism to change + the system clock and timezone, as well as to + enable/disable NTP time + synchronization. <filename>systemd-timedated</filename> + is automatically activated on request and terminates + itself when it is unused.</para> + + <para>The tool + <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + is a command line client to this service.</para> + + <para>See the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/timedated"> + developer documentation</ulink> for information about + the APIs <filename>systemd-timedated</filename> + provides.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-tmpfiles.xml b/man/systemd-tmpfiles.xml new file mode 100644 index 0000000000..22744c7c41 --- /dev/null +++ b/man/systemd-tmpfiles.xml @@ -0,0 +1,162 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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> + <refname>systemd-tmpfiles-setup.service</refname> + <refname>systemd-tmpfiles-clean.service</refname> + <refname>systemd-tmpfiles-clean.timer</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> + + <para><filename>systemd-tmpfiles-setup.service</filename></para> + <para><filename>systemd-tmpfiles-clean.service</filename></para> + <para><filename>systemd-tmpfiles-clean.timer</filename></para> + </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 file format and + location specified in <citerefentry> + <refentrytitle>tmpfiles.d</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry>.</para> + + <para>If invoked with no arguments, it applies all + directives from all configuration files. If one or + more file names are passed on the command line, only + the directives in these files are applied. If only + the basename of a configuration file is specified, + all configuration directories as specified in <citerefentry> + <refentrytitle>tmpfiles.d</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry> are searched for a matching file.</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>, + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-tty-ask-password-agent.xml b/man/systemd-tty-ask-password-agent.xml new file mode 100644 index 0000000000..31a18ba4b0 --- /dev/null +++ b/man/systemd-tty-ask-password-agent.xml @@ -0,0 +1,166 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd-tty-ask-password-agent"> + + <refentryinfo> + <title>systemd-tty-ask-password-agent</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-tty-ask-password-agent</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-tty-ask-password-agent</refname> + <refpurpose>List or process pending systemd password requests</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-tty-ask-password-agent <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-tty-ask-password-agent</command> + is a password agent that handles password + requests of the system, for example for hard disk + encryption passwords or SSL certificate passwords that + need to be queried at boot-time or during + runtime.</para> + + <para><command>systemd-tty-ask-password-agent</command> + implements the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/PasswordAgents">Password + Agents Specification</ulink>.</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>--list</option></term> + + <listitem><para>Lists all currently pending system password requests.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--query</option></term> + + <listitem><para>Process all currently + pending system password requests by + querying the user on the calling + TTY.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--watch</option></term> + + <listitem><para>Continuously process + password requests.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--wall</option></term> + + <listitem><para>Forward password + requests to + <citerefentry><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry> + instead of querying the user on the + calling TTY.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--plymouth</option></term> + + <listitem><para>Ask question with + <citerefentry><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry> + instead of querying the user on the + calling TTY.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--console</option></term> + + <listitem><para>Ask question on + <filename>/dev/console</filename> + instead of querying the user on the + calling TTY. </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-ask-password-console.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-udevd.service.xml b/man/systemd-udevd.service.xml new file mode 100644 index 0000000000..92fb38f067 --- /dev/null +++ b/man/systemd-udevd.service.xml @@ -0,0 +1,168 @@ +<?xml version='1.0'?> +<?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"> + +<refentry id="systemd-udevd.service"> + <refentryinfo> + <title>systemd-udevd.service</title> + <productname>systemd</productname> + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Kay</firstname> + <surname>Sievers</surname> + <email>kay@vrfy.org</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-udevd.service</refentrytitle> + <manvolnum>8</manvolnum> + <refmiscinfo class="version"></refmiscinfo> + </refmeta> + + <refnamediv> + <refname>systemd-udevd.service</refname> + <refname>systemd-udevd-control.socket</refname> + <refname>systemd-udevd-kernel.socket</refname> + <refname>systemd-udevd</refname> + <refpurpose>Device event managing daemon</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-udevd.service</filename></para> + <para><filename>systemd-udevd-control.socket</filename></para> + <para><filename>systemd-udevd-kernel.socket</filename></para> + + <cmdsynopsis> + <command>/usr/lib/systemd/systemd-udevd</command> + <arg><option>--daemon</option></arg> + <arg><option>--debug</option></arg> + <arg><option>--children-max=</option></arg> + <arg><option>--exec-delay=</option></arg> + <arg><option>--resolve-names=early|late|never</option></arg> + <arg><option>--version</option></arg> + <arg><option>--help</option></arg> + </cmdsynopsis> + + </refsynopsisdiv> + + <refsect1><title>Description</title> + <para><command>systemd-udevd</command> listens to kernel uevents. + For every event, systemd-udevd executes matching instructions + specified in udev rules. See <citerefentry> + <refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum> + </citerefentry>.</para> + <para>The behavior of the running daemon can be changed with + <command>udevadm control</command>.</para> + </refsect1> + + <refsect1><title>Options</title> + <variablelist> + <varlistentry> + <term><option>--daemon</option></term> + <listitem> + <para>Detach and run in the background.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--debug</option></term> + <listitem> + <para>Print debug messages to stderr.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--children-max=</option></term> + <listitem> + <para>Limit the number of events executed in parallel.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--exec-delay=</option></term> + <listitem> + + <para>Delay the execution of RUN instruction by the given + number of seconds. This option might be useful when + debugging system crashes during coldplug caused by loading + non-working kernel modules.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--resolve-names=</option></term> + <listitem> + <para>Specify when systemd-udevd should resolve names of users and groups. + When set to <option>early</option> (the default) names will be + resolved when the rules are parsed. When set to + <option>late</option> names will be resolved for every event. + When set to <option>never</option> names will never be resolved + and all devices will be owned by root.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--version</option></term> + <listitem> + <para>Print version number.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--help</option></term> + <listitem> + <para>Print help text.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1><title>Environment</title> + <variablelist> + <varlistentry> + <term><varname>UDEV_LOG=</varname></term> + <listitem> + <para>Set the logging priority.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1><title>Kernel command line</title> + <variablelist> + <para>Parameters starting with "rd." will be read when + <command>systemd-udevd</command> is used in an initrd.</para> + <varlistentry> + <term><varname>udev.log-priority=</varname></term> + <term><varname>rd.udev.log-priority=</varname></term> + <listitem> + <para>Set the logging priority.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>udev.children-max=</varname></term> + <term><varname>rd.udev.children-max=</varname></term> + <listitem> + <para>Limit the number of events executed in parallel.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>udev.exec-delay=</varname></term> + <term><varname>rd.udev.exec-delay=</varname></term> + <listitem> + <para>Delay the execution of RUN instruction by the given + number of seconds. This option might be useful when + debugging system crashes during coldplug caused by loading + non-working kernel modules.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para><citerefentry> + <refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum> + </citerefentry>, <citerefentry> + <refentrytitle>udevadm</refentrytitle><manvolnum>8</manvolnum> + </citerefentry></para> + </refsect1> +</refentry> diff --git a/man/systemd-update-utmp-runlevel.service.xml b/man/systemd-update-utmp-runlevel.service.xml new file mode 100644 index 0000000000..0e19581f98 --- /dev/null +++ b/man/systemd-update-utmp-runlevel.service.xml @@ -0,0 +1,76 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> +<refentry id="systemd-user-sessions.service"> + + <refentryinfo> + <title>systemd-update-utmp-runlevel.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-update-utmp-runlevel.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-update-utmp-runlevel.service</refname> + <refname>systemd-update-utmp-shutdown.service</refname> + <refname>systemd-update-utmp</refname> + <refpurpose>Write audit and utmp updates at runlevel + changes and shutdown</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-update-utmp-runlevel.service</filename></para> + <para><filename>systemd-update-utmp-shutdown.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-update-utmp</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-update-utmp-runlevel.service</filename> + is a service that writes SysV runlevel changes to utmp + and wtmp, as well as the audit logs, as they + occur. <filename>systemd-update-utmp-shutdown.service</filename> + does the same for shut-down requests.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>utmp</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>auditd</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-user-sessions.service.xml b/man/systemd-user-sessions.service.xml new file mode 100644 index 0000000000..9214ec9c35 --- /dev/null +++ b/man/systemd-user-sessions.service.xml @@ -0,0 +1,77 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> +<refentry id="systemd-user-sessions.service"> + + <refentryinfo> + <title>systemd-user-sessions.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-user-sessions.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-user-sessions.service</refname> + <refname>systemd-user-sessions</refname> + <refpurpose>Permit user logins after boot, prohibit user logins at shutdown</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-user-sessions.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-user-sessions</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-user-sessions.service</filename> + is a service that controls user logins. After basic + system initialization is complete it removes + <filename>/run/nologin</filename>, thus permitting + logins. Before system shutdown it creates + <filename>/run/nologin</filename>, thus prohibiting + further logins. At the same time it also kills all + user processes, so that system shutdown may proceed + without any remaining user processes around.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>pam_nologin</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-vconsole-setup.service.xml b/man/systemd-vconsole-setup.service.xml new file mode 100644 index 0000000000..c1ef80dae4 --- /dev/null +++ b/man/systemd-vconsole-setup.service.xml @@ -0,0 +1,118 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> +<refentry id="systemd-vconsole-setup.service"> + + <refentryinfo> + <title>systemd-vconsole-setup.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-vconsole-setup.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-vconsole-setup.service</refname> + <refname>systemd-vconsole-setup</refname> + <refpurpose>Configure the virtual console at boot</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-vconsole-setup.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-vconsole-setup</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-vconsole-setup.service</filename> + is an early-boot service that configures the virtual + console font and console keymap. Internally it calls + <citerefentry><refentrytitle>loadkeys</refentrytitle><manvolnum>1</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>setfont</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + + <para>See + <citerefentry><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for information about the configuration files understood by this + service.</para> + + + </refsect1> + + <refsect1> + <title>Kernel Command Line</title> + + <para>A few configuration parameters from + <filename>vconsole.conf</filename> may be overridden on + the kernel command line:</para> + + <variablelist> + <varlistentry> + <term><varname>vconsole.keymap=</varname></term> + <term><varname>vconsole.keymap.toggle=</varname></term> + + <listitem><para>Overrides the key + mapping table for the keyboard and the + second toggle keymap.</para></listitem> + </varlistentry> + <varlistentry> + + <term><varname>vconsole.font=</varname></term> + <term><varname>vconsole.font.map=</varname></term> + <term><varname>vconsole.font.unimap=</varname></term> + + <listitem><para>Configures the console + font, the console map, and the unicode + font map.</para></listitem> + + + </varlistentry> + </variablelist> + + <para>See + <citerefentry><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for information about these settings.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>loadkeys</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>setfont</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-localed.service</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 0000000000..fe559e1dcb --- /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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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>Automount unit configuration</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 that 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 0000000000..a6be932c73 --- /dev/null +++ b/man/systemd.conf.xml @@ -0,0 +1,284 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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>System and service manager configuration file</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/systemd/system.conf</filename></para> + <para><filename>/etc/systemd/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 class='systemd-directives'> + + <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>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>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,cpuset net_cls,netprio</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 + hierarchies, 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> + + <varlistentry> + <term><varname>RuntimeWatchdogSec=</varname></term> + <term><varname>ShutdownWatchdogSec=</varname></term> + + <listitem><para>Configure the hardware + watchdog at runtime and at + reboot. Takes a timeout value in + seconds (or in other time units if + suffixed with <literal>ms</literal>, + <literal>min</literal>, + <literal>h</literal>, + <literal>d</literal>, + <literal>w</literal>). If + <varname>RuntimeWatchdogSec=</varname> + is set to a non-zero value the + watchdog hardware + (<filename>/dev/watchdog</filename>) + will be programmed to automatically + reboot the system if it is not + contacted within the specified timeout + interval. The system manager will + ensure to contact it at least once in + half the specified timeout + interval. This feature requires a + hardware watchdog device to be + present, as it is commonly the case in + embedded and server systems. Not all + hardware watchdogs allow configuration + of the reboot timeout, in which case + the closest available timeout is + picked. <varname>ShutdownWatchdogSec=</varname> + may be used to configure the hardware + watchdog when the system is asked to + reboot. It works as a safety net to + ensure that the reboot takes place + even if a clean reboot attempt times + out. By default + <varname>RuntimeWatchdogSec=</varname> + defaults to 0 (off), and + <varname>ShutdownWatchdogSec=</varname> + to 10min. These settings have no + effect if a hardware watchdog is not + available.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>CapabilityBoundingSet=</varname></term> + + <listitem><para>Controls which + capabilities to include in the + capability bounding set for PID 1 and + its children. 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 also + affects the respective capabilities in + the effective, permitted and + inheritable capability sets. The + capability bounding set may also be + individually configured for units + using the + <varname>CapabilityBoundingSet=</varname> + directive for units, but note that + capabilities dropped for PID 1 cannot + be regained in individual units, they + are lost for good.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TimerSlackNSec=</varname></term> + + <listitem><para>Sets the timer slack + in nanoseconds for PID 1 which is then + inherited to all executed processes, + unless overridden individually, for + example with the + <varname>TimerSlackNSec=</varname> + setting in service units (for details + see + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>). 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 if no + unit is specified. The usual time + units are understood + too.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DefaultLimitCPU=</varname></term> + <term><varname>DefaultLimitFSIZE=</varname></term> + <term><varname>DefaultLimitDATA=</varname></term> + <term><varname>DefaultLimitSTACK=</varname></term> + <term><varname>DefaultLimitCORE=</varname></term> + <term><varname>DefaultLimitRSS=</varname></term> + <term><varname>DefaultLimitNOFILE=</varname></term> + <term><varname>DefaultLimitAS=</varname></term> + <term><varname>DefaultLimitNPROC=</varname></term> + <term><varname>DefaultLimitMEMLOCK=</varname></term> + <term><varname>DefaultLimitLOCKS=</varname></term> + <term><varname>DefaultLimitSIGPENDING=</varname></term> + <term><varname>DefaultLimitMSGQUEUE=</varname></term> + <term><varname>DefaultLimitNICE=</varname></term> + <term><varname>DefaultLimitRTPRIO=</varname></term> + <term><varname>DefaultLimitRTTIME=</varname></term> + + <listitem><para>These settings control + various default resource limits for + units. 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. These settings may be + overridden in individual units + using the corresponding LimitXXX= + directives. Note that these resource + limits are only defaults for units, + they are not applied to PID 1 + itself.</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 0000000000..141d72e3dc --- /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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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>Device unit configuration</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 class='udev-directives'> + <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 behavior 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 0000000000..7b6514375d --- /dev/null +++ b/man/systemd.exec.xml @@ -0,0 +1,1154 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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>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], or [Swap] sections, 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. If + not set defaults to the root directory + when systemd is running as a system + instance and the respective user's + home directory if run as + user.</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 + or group that the processes are executed + as, respectively. Takes a single user or 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 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>3</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>, + <option>kmsg</option> or + <option>journal</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>3</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 if no + unit is specified. The usual time + units are understood + too.</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 also + effects the respective capabilities in + the effective, permitted and + inheritable capability sets, on top of + what <varname>Capabilities=</varname> + does. 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 + 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, + or Terabytes (to the base + 1024), respectively. 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, or + creating of the specific device node + by the unit, respectively. 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 bandwidth limit for + the executed processes. Takes a space + separated pair of a file path and a + bandwidth 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 bandwidth is suffixed with K, M, + G, or T the specified bandwidth is + parsed as Kilobytes, Megabytes, + Gigabytes, or Terabytes, respectively (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 bandwidth + 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 the file system + namespace set up for this unit's + processes will receive or propagate + new mounts. See + <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for details. Default to + <option>shared</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>UtmpIdentifier=</varname></term> + + <listitem><para>Takes 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> + + <varlistentry> + <term><varname>NoNewPrivileges=</varname></term> + + <listitem><para>Takes a boolean + argument. If true ensures that the + service process and all its children + can never gain new privileges. This + option is more powerful than the respective + secure bits flags (see above), as it + also prohibits UID changes of any + kind. This is the simplest, most + effective way to ensure that a process + and its children can never elevate + privileges again.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SystemCallFilter=</varname></term> + + <listitem><para>Takes a space + separated list of system call + names. If this setting is used all + system calls executed by the unit + process except for the listed ones + will result in immediate process + termination with the SIGSYS signal + (whitelisting). If the first character + of the list is <literal>~</literal> + the effect is inverted: only the + listed system calls will result in + immediate process termination + (blacklisting). If this option is used + <varname>NoNewPrivileges=yes</varname> + is implied. This feature makes use of + the Secure Computing Mode 2 interfaces + of the kernel ('seccomp filtering') + and is useful for enforcing a minimal + sandboxing environment. Note that the + <function>execve</function>, + <function>rt_sigreturn</function>, + <function>sigreturn</function>, + <function>exit_group</function>, + <function>exit</function> system calls + are implicitly whitelisted and don't + need to be listed + explicitly.</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>, + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd.journal-fields.xml b/man/systemd.journal-fields.xml new file mode 100644 index 0000000000..76a436d650 --- /dev/null +++ b/man/systemd.journal-fields.xml @@ -0,0 +1,450 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.journal-fields"> + + <refentryinfo> + <title>systemd.journal-fields</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.journal-fields</refentrytitle> + <manvolnum>7</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.journal-fields</refname> + <refpurpose>Special journal fields</refpurpose> + </refnamediv> + + <refsect1> + <title>Description</title> + + <para>Entries in the journal resemble an environment + block in their syntax, however with fields that can + include binary data. Primarily, fields are formatted + UTF-8 text strings, and binary formatting is used only + where formatting as UTF-8 text strings makes little + sense. New fields may freely be defined by + applications, but a few fields have special + meaning. All fields with special meanings are + optional. In some cases fields may appear more than + once per entry.</para> + </refsect1> + + <refsect1> + <title>User Journal Fields</title> + + <para>User fields are fields that are directly passed + from clients and stored in the journal.</para> + + <variablelist class='journal-directives'> + <varlistentry> + <term><varname>MESSAGE=</varname></term> + <listitem> + <para>The human readable + message string for this + entry. This is supposed to be + the primary text shown to the + user. It is usually not + translated (but might be in + some cases), and is not + supposed to be parsed for meta + data.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>MESSAGE_ID=</varname></term> + <listitem> + <para>A 128bit message + identifier ID for recognizing + certain message types, if this + is desirable. This should + contain a 128bit id formatted + as lower-case hexadecimal + string, without any separating + dashes or suchlike. This is + recommended to be a UUID + compatible ID, but this is not + enforced, and formatted + differently. Developers can + generate a new ID for this + purpose with + <command>journalctl + --new-id</command>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>PRIORITY=</varname></term> + <listitem> + <para>A priority value between + 0 (<literal>emerg</literal>) + and 7 + (<literal>debug</literal>) + formatted as decimal + string. This field is + compatible with syslog's + priority concept.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>CODE_FILE=</varname></term> + <term><varname>CODE_LINE=</varname></term> + <term><varname>CODE_FUNC=</varname></term> + <listitem> + <para>The code location + generating this message, if + known. Contains the source + file name, the line number and + the function name.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>ERRNO=</varname></term> + <listitem> + <para>The low-level Unix error + number causing this entry, if + any. Contains the numeric + value of + <citerefentry><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry> + formatted as decimal + string.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>SYSLOG_FACILITY=</varname></term> + <term><varname>SYSLOG_IDENTIFIER=</varname></term> + <term><varname>SYSLOG_PID=</varname></term> + <listitem> + <para>Syslog compatibility + fields containing the facility + (formatted as decimal string), + the identifier string + (i.e. "tag"), and the client + PID.</para> + </listitem> + + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Trusted Journal Fields</title> + + <para>Fields prefixed with an underscore are trusted + fields, i.e. fields that are implicitly added by the + journal and cannot be altered by client code.</para> + + <variablelist class='journal-directives'> + <varlistentry> + <term><varname>_PID=</varname></term> + <term><varname>_UID=</varname></term> + <term><varname>_GID=</varname></term> + <listitem> + <para>The process, user and + group ID of the process the + journal entry originates from + formatted as decimal + string.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>_COMM=</varname></term> + <term><varname>_EXE=</varname></term> + <term><varname>_CMDLINE=</varname></term> + <listitem> + <para>The name, the executable + path and the command line of + the process the journal entry + originates from.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>_AUDIT_SESSION=</varname></term> + <term><varname>_AUDIT_LOGINUID=</varname></term> + <listitem> + <para>The session and login + UID of the process the journal + entry originates from, as + maintained by the kernel audit + subsystem.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>_SYSTEMD_CGROUP=</varname></term> + <term><varname>_SYSTEMD_SESSION=</varname></term> + <term><varname>_SYSTEMD_UNIT=</varname></term> + <term><varname>_SYSTEMD_OWNER_UID=</varname></term> + + <listitem> + <para>The control group path in + the systemd hierarchy, the + systemd session ID (if any), + the systemd unit name (if any) + and the owner UID of the + systemd session (if any) of + the process the journal entry + originates from.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>_SELINUX_CONTEXT=</varname></term> + <listitem> + <para>The SELinux security + context of the process the + journal entry originates + from.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>_SOURCE_REALTIME_TIMESTAMP=</varname></term> + <listitem> + <para>The earliest trusted + timestamp of the message, if + any is known that is different + from the reception time of the + journal. This is the time in + usec since the epoch UTC + formatted as decimal + string.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>_BOOT_ID=</varname></term> + <listitem> + <para>The kernel boot ID for + the boot the message was + generated in, formatted as + 128bit hexadecimal + string.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>_MACHINE_ID=</varname></term> + <listitem> + <para>The machine ID of the + originating host, as available + in + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>_HOSTNAME=</varname></term> + <listitem> + <para>The name of the + originating host.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>_TRANSPORT=</varname></term> + <listitem> + <para>How the entry was + received by the journal + service. One of + <literal>driver</literal>, + <literal>syslog</literal>, + <literal>journal</literal>, + <literal>stdout</literal>, + <literal>kernel</literal> for + internally generated messages, + for those received via the + local syslog socket with the + syslog protocol, for those + received via the native + journal protocol, for the + those read from a services' + standard output or error + output, or for those read + from the kernel, respectively. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Kernel Journal Fields</title> + + <para>Kernel fields are fields that are used by + messages originating in the kernel and stored in the + journal.</para> + + <variablelist> + <varlistentry> + <term>_KERNEL_DEVICE=</term> + <listitem> + <para>The kernel device + name. If the entry is + associated to a block device, + the major and minor of the + device node, separated by ':' + and prefixed by 'b'. Similar + for character devices, but + prefixed by 'c'. For network + devices the interface index, + prefixed by 'n'. For all other + devices '+' followed by the + subsystem name, followed by + ':', followed by the kernel + device name.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>_KERNEL_SUBSYSTEM=</term> + <listitem> + <para>The kernel subsystem name.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>_UDEV_SYSNAME=</term> + <listitem> + <para>The kernel device name + as it shows up in the device + tree below + <filename>/sys</filename>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>_UDEV_DEVNODE=</term> + <listitem> + <para>The device node path of + this device in + <filename>/dev</filename>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>_UDEV_DEVLINK=</term> + <listitem> + <para>Additional symlink names + pointing to the device node in + <filename>/dev</filename>. This + field is frequently set more + than once per entry.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Address Fields</title> + + <para>During serialization into external formats, such + as the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/export">Journal + Export Format</ulink> or the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/json">Journal + JSON Format</ulink>, the addresses of journal entries + are serialized into fields prefixed with double + underscores. Note that these aren't proper fields when + stored in the journal, but addressing meta data of + entries. They cannot be written as part of structured + log entries via calls such as + <citerefentry><refentrytitle>sd_journal_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>. They + may also not be used as matches for + <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry></para> + + <variablelist class='journal-directives'> + <varlistentry> + <term><varname>__CURSOR=</varname></term> + <listitem> + <para>The cursor for the + entry. A cursor is an opaque + text string that uniquely + describes the position of an + entry in the journal and is + portable across machines, + platforms and journal + files.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>__REALTIME_TIMESTAMP=</varname></term> + <listitem> + <para>The wallclock time + (CLOCK_REALTIME) at the point + in time the entry was received + by the journal, in usec since + the epoch UTC formatted as + decimal string. This has + different properties from + <literal>_SOURCE_REALTIME_TIMESTAMP=</literal> + as it is usually a bit later + but more likely to be + monotonic.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>__MONOTONIC_TIMESTAMP=</varname></term> + <listitem> + <para>The monotonic time + (CLOCK_MONOTONIC) at the point + in time the entry was received + by the journal in usec + formatted as decimal + string. To be useful as an + address for the entry this + should be combined with with + boot ID in + <literal>_BOOT_ID=</literal>.</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>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd.kill.xml b/man/systemd.kill.xml new file mode 100644 index 0000000000..3fff2f57e6 --- /dev/null +++ b/man/systemd.kill.xml @@ -0,0 +1,170 @@ +<?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 2012 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.kill"> + <refentryinfo> + <title>systemd.kill</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.kill</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.kill</refname> + <refpurpose>Kill 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 process killing + parameters 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], or [Swap] section, depending on the unit + type.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <variablelist> + + <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 unit will be terminated + on unit stop (for services: after the + stop command is executed, as + configured with + <varname>ExecStop=</varname>). 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 unit + 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> + </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>, + <citerefentry><refentrytitle>systemd.exec</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 0000000000..219ef6531e --- /dev/null +++ b/man/systemd.mount.xml @@ -0,0 +1,282 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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>Mount unit configuration</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, and in + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> + which define the way the processes are + terminated.</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 a 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). Mounts listed in + <filename>/etc/fstab</filename> will be converted into + native units dynamically at boot and when the + configuration of the system manager is reloaded. See + <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for details about the conversion.</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>. 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 specify 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> + and + <citerefentry><refentrytitle>systemd.kill</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 does not exist at the + 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> in + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.) + 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> + </variablelist> + + <para>Check + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more settings.</para> + </refsect1> + + <refsect1> + <title>Compatibility Options</title> + + <para>The following option is also available in the + <literal>[Mount]</literal> section, but exists purely + for compatibility reasons and should not be used in + newly written mount files.</para> + + <variablelist> + <varlistentry> + <term><varname>FsckPassNo=</varname></term> + + <listitem><para>The pass number for + the file system checking service for + this mount. See + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information on this setting. + </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.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-fstab-generator</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 0000000000..a27a97be77 --- /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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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>Path unit configuration</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 a 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 + existence 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.preset.xml b/man/systemd.preset.xml new file mode 100644 index 0000000000..a692053876 --- /dev/null +++ b/man/systemd.preset.xml @@ -0,0 +1,204 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> +<refentry id="systemd.preset"> + + <refentryinfo> + <title>systemd.preset</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.preset</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.preset</refname> + <refpurpose>Service enablement presets</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/systemd/system-preset/*.preset</filename></para> + <para><filename>/run/systemd/system-preset/*.preset</filename></para> + <para><filename>/usr/lib/systemd/system-preset/*.preset</filename></para> + <para><filename>/etc/systemd/user-preset/*.preset</filename></para> + <para><filename>/run/systemd/user-preset/*.preset</filename></para> + <para><filename>/usr/lib/systemd/user-preset/*.preset</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>Preset files may be used to encode policy which + units shall be enabled by default and which ones + shall be disabled. They are read by <command>systemctl + preset</command> (for more information see + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>) + which uses this information to enable or disable a + unit according to preset policy. <command>systemctl + preset</command> is used by the post install + scriptlets of RPM packages (or other OS package formats), + to enable/disable specific units by default on package + installation, enforcing distribution, spin or + administrator preset policy. This allows choosing a certain + set of units to be enabled/disabled even before + installing the actual package.</para> + + <para>For more information on the preset logic please + have a look at the <ulink + url="http://freedesktop.org/wiki/Software/systemd/Preset">Presets</ulink> + document.</para> + + <para>It is not recommended to ship preset files + within the respective software packages implementing + the units, but rather centralize them in a + distribution or spin default policy, which can be + amended by administrator policy.</para> + + <para>If no preset files exist, <command>systemctl + preset</command> will enable all units that are + installed by default. If this is not desired and all + units shall rather be disabled it is necessary to ship + a preset file with a single, catchall + "<filename>disable *</filename>" line. (See example 1, + below.)</para> + </refsect1> + + <refsect1> + <title>Preset File Format</title> + + <para>The preset files contain a list of + directives consisting of either the word + <literal>enable</literal> or + <literal>disable</literal> followed by a space and a + unit name (possibly with shell style wildcards), + separated by newlines. Empty lines and lines whose + first non-whitespace character is # or ; are + ignored.</para> + + <para>Two different directives are understood: + <literal>enable</literal> may be used to enable units + by default, <literal>disable</literal> to disable + units by default.</para> + + <para>If multiple lines apply to a unit name the + first matching one takes precedence over all + others.</para> + + <para>Each preset file shall be named in the style of + <filename><priority>-<program>.conf</filename>. + Files in <filename>/etc/</filename> override files + with the same name in <filename>/usr/lib/</filename> + and <filename>/run/</filename>. Files in + <filename>/run/</filename> override files with the + same name in <filename>/usr/lib/</filename>. Packages + should install their preset 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 + preset files installed by vendor packages. All preset + files are sorted by their filename in alphabetical + order, regardless in which of the directories they + reside, to guarantee that a specific preset file takes + precedence over another file with an alphabetically + earlier name, if both files contain lines that apply + to the same unit names. It is recommended to prefix + all file names with two-digit number, to simplify + ordering.</para> + + <para>If the administrator wants to disable a preset + file supplied by the vendor the recommended way is to + place a symlink to <filename>/dev/null</filename> in + <filename>/etc/systemd/system-preset/</filename> + bearing the same file name.</para> + </refsect1> + + <refsect1> + <title>Example</title> + + <example> + <title>Default off example <filename>/usr/lib/systemd/system-preset/99-default.preset</filename>:</title> + + <programlisting>disable *</programlisting> + </example> + + <para>This disables all units. Due to the file name + prefix <literal>99-</literal> it will be read last and + hence can easily be overridden by spin or + administrator preset policy or suchlike.</para> + + <example> + <title>A GNOME spin example <filename>/usr/lib/systemd/system-preset/50-gnome.preset</filename>:</title> + + <programlisting>enable gdm.service +enable colord.service +enable accounts-daemon.service +enable avahi-daemon.*</programlisting> + + </example> + + <para>This enables the three mentioned units, plus all + <filename>avahi-daemon</filename> regardless of which + unit type. A file like this could be useful for + inclusion in a GNOME spin of a distribution. It will + ensure that the units necessary for GNOME are properly + enabled as they are installed. It leaves all other + units untouched, and subject to other (later) preset + files, for example like the one from the first example + above.</para> + + <example> + <title>Administrator policy <filename>/etc/systemd/system-preset/00-lennart.preset</filename>:</title> + + <programlisting>enable httpd.service +enable sshd.service +enable postfix.service +disable *</programlisting> + </example> + + <para>This enables three specific services and + disables all others. This is useful for administrators + to specifically select the units to enable, and + disable all others. Due to the file name prefix + <literal>00-</literal> it will be read early and hence + overrides all other preset policy files.</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-delta</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd.service.xml b/man/systemd.service.xml new file mode 100644 index 0000000000..00a6398a1e --- /dev/null +++ b/man/systemd.service.xml @@ -0,0 +1,924 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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>Service unit configuration</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, and in + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> + which define the way the processes of the service are + terminated.</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. Note that this compatibility is quite + comprehensive but not 100%. For details about the + incompatibilities see the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/Incompatibilities">Incompatibilities + with SysV</ulink> document. + </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> + and + <citerefentry><refentrytitle>systemd.kill</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> or + <option>idle</option>.</para> + + <para>If set to + <option>simple</option> (the default + value if <varname>BusName=</varname> + is not specified) 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 behavior 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>Behavior 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>Behavior 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. This type is the default if + <varname>BusName=</varname> is + specified.</para> + + <para>Behavior 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> + + <para>Behavior of + <option>idle</option> is very similar + to <option>simple</option>, however + actual execution of the service + binary is delayed until all jobs are + dispatched. This may be used to avoid + interleaving of output of shell + services with the status output on the + console.</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 + 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, that 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 a word of its own on the + command line, in which case it will be + replaced by the value of the + environment variable including all + whitespace it contains, resulting in a + single argument. 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> + + <para>Note that this setting does not + directly support shell command + lines. If shell command lines are to + be used they need to be passed + explicitly to a shell implementation + of some kind. Example: + <literal>ExecStart=/bin/sh -c 'dmesg | tac'</literal></para> + + <para>For services run by a user + instance of systemd the special + environment variable + <literal>MANAGERPID</literal> is set + to the PID of the systemd + instance.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>ExecStartPre=</varname></term> + <term><varname>ExecStartPost=</varname></term> + <listitem><para>Additional commands + that are executed before or after + the command in + <varname>ExecStart=</varname>, respectively. 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 + additional special environment + variables 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 + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>). 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>TimeoutStartSec=</varname></term> + <listitem><para>Configures the time to + wait for start-up. 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. + 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, except when + <varname>Type=oneshot</varname> is + used in which case the timeout + is disabled by default. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TimeoutStopSec=</varname></term> + <listitem><para>Configures the time to + wait for stop. 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> + in <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>). + 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>TimeoutSec=</varname></term> + <listitem><para>A shorthand for configuring + both <varname>TimeoutStartSec=</varname> + and <varname>TimeoutStopSec=</varname> + to the specified value. + </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" (i.e. the + "keep-alive ping"). 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. This allows + daemons to automatically enable the + keep-alive pinging logic if watchdog + support is enabled for the service. 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 equaling 0, when + terminated by a signal (including on + core dump), when an operation (such as + service reload) 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 + (including on core dump). 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>SuccessExitStatus=</varname></term> + <listitem><para>Takes a list of exit + status definitions that when returned + by the main service process will be + considered successful termination, in + addition to the normal successful exit + code 0 and the signals SIGHUP, SIGINT, + SIGTERM and SIGPIPE. Exit status + definitions can either be numeric exit + codes or termination signal names, and + are separated by spaces. Example: + "<literal>SuccessExitStatus=1 2 8 + SIGKILL</literal>", ensures that exit + codes 1, 2, 8 and the termination + signal SIGKILL are considered clean + service + terminations.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RestartPreventExitStatus=</varname></term> + <listitem><para>Takes a list of exit + status definitions that when returned + by the main service process will + prevent automatic service restarts + regardless of the restart setting + configured with + <varname>Restart=</varname>. Exit + status definitions can either be + numeric exit codes or termination + signal names, and are separated by + spaces. Defaults to the empty list, so + that by default no exit status is + excluded from the configured restart + logic. Example: + "<literal>RestartPreventExitStatus=1 6 + SIGABRT</literal>", ensures that exit + codes 1 and 6 and the termination signal + SIGABRT will not result in automatic + service restarting.</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>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>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>, however + apply to all kinds of starts + (including manual), not just those + triggered by the + <varname>Restart=</varname> logic. + Note that units which are configured + for <varname>Restart=</varname> and + which reach the start limit are not + attempted to be restarted anymore, + however they may still be restarted + manually at a later point from which + point on the restart logic is again + activated. Note that + <command>systemctl + reset-failed</command> will cause the + restart rate counter for a service to + be flushed, which is useful if the + administrator wants to manually start + a service and the start limit + interferes with + that.</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> + + <para>Check + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more settings.</para> + + </refsect1> + + <refsect1> + <title>Compatibility Options</title> + + <para>The following options are also available in the + <literal>[Service]</literal> section, but exist purely + for compatibility reasons and should not be used in + newly written service files.</para> + + <variablelist> + <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>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> + + </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.kill</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 0000000000..b432682a48 --- /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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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>Snapshot unit configuration</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 0000000000..4b1fcc8b0c --- /dev/null +++ b/man/systemd.socket.xml @@ -0,0 +1,685 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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>Socket unit configuration</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, and in + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> + which define the way the processes are + terminated.</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> + and + <citerefentry><refentrytitle>systemd.kill</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), + or sequential packet + (SOCK_SEQPACKET) socket, respectively. 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 via + IPv6. Depending on the value of + <varname>BindIPv6Only=</varname> (see below) this + might result in the service being + available via both IPv6 and IPv4 (default) or + just via 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. Note + that this might make the service + available via IPv4, too, depending on + the <varname>BindIPv6Only=</varname> + setting (see below). + </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. Behavior 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. Behavior + 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. Behavior 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 /). Behavior + 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>, + which in turn defaults to the + equivalent of + <option>both</option>.</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 or 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 or 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=false</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 + or send buffer sizes of this + socket, respectively. This controls the SO_RCVBUF + and 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>SmackLabel=</varname></term> + <term><varname>SmackLabelIPIn=</varname></term> + <term><varname>SmackLabelIPOut=</varname></term> + <listitem><para>Takes a string + value. Controls the extended + attributes + <literal>security.SMACK64</literal>, + <literal>security.SMACK64IPIN</literal> + and + <literal>security.SMACK64IPOUT</literal>, + respectively, i.e. the security label + of the FIFO, or the security label for + the incoming or outgoing connections + of the socket, respectively. See + <ulink + url="https://www.kernel.org/doc/Documentation/security/Smack.txt">Smack.txt</ulink> + 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 field or the mq_msgsize field, respectively, 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 or after the listening + sockets/FIFOs are created and + bound, respectively. 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 or after + the listening sockets/FIFOs are closed + and removed, respectively. 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> in <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.) + 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>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> + + <para>Check + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more settings.</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.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.kill</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 0000000000..9ea288e337 --- /dev/null +++ b/man/systemd.special.xml @@ -0,0 +1,817 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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>bluetooth.target</filename>, + <filename>ctrl-alt-del.target</filename>, + <filename>cryptsetup.target</filename>, + <filename>dbus.service</filename>, + <filename>dbus.socket</filename>, + <filename>default.target</filename>, + <filename>display-manager.service</filename>, + <filename>emergency.target</filename>, + <filename>exit.target</filename>, + <filename>final.target</filename>, + <filename>getty.target</filename>, + <filename>graphical.target</filename>, + <filename>halt.target</filename>, + <filename>hibernate.target</filename>, + <filename>hybrid-sleep.target</filename>, + <filename>kbrequest.target</filename>, + <filename>kexec.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>nss-user-lookup.target</filename>, + <filename>poweroff.target</filename>, + <filename>printer.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>sleep.target</filename>, + <filename>smartcard.target</filename>, + <filename>sockets.target</filename>, + <filename>sound.target</filename>, + <filename>suspend.target</filename>, + <filename>swap.target</filename>, + <filename>sysinit.target</filename>, + <filename>syslog.socket</filename>, + <filename>syslog.target</filename>, + <filename>system-update.target</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>bluetooth.target</filename></term> + <listitem> + <para>This target is started + automatically as soon as a + bluetooth controller is + plugged in or becomes + available at boot.</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>cryptsetup.target</filename></term> + <listitem> + <para>A target that pulls in + setup services for all + encrypted block + devices.</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>dbus.socket</filename></term> + <listitem> + <para>A special unit for the + D-Bus system bus socket. All + units with + <literal>Type=dbus</literal> + automatically gain a + dependency on this + unit.</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>gdm.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.</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>final.target</filename></term> + <listitem> + <para>A special target unit + that is used during the + shutdown logic and may be used + to pull in late services after + all normal services are + already terminated and all + mounts unmounted. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>getty.target</filename></term> + <listitem> + <para>A special target unit + that pulls in all local TTY + <filename>getty</filename> instances. + </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>hibernate.target</filename></term> + <listitem> + <para>A special target unit + for hibernating the + system. This pulls in + <filename>sleep.target</filename>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>hybrid-sleep.target</filename></term> + <listitem> + <para>A special target unit + for hibernating and suspending the + system at the same time. This pulls in + <filename>sleep.target</filename>.</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>kexec.target</filename></term> + <listitem> + <para>A special target unit + for shutting down and rebooting the system via kexec.</para> + + <para>Applications wanting to + reboot the system with kexec should start + this unit.</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>.</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>A target that should be + used as synchronization point + for all host/network name + service lookups. Note that + this is independent of + user/group name lookups for + which + <filename>nss-user-lookup.target</filename> + should be used. systemd + automatically adds + dependencies of type After for + this target unit to all SysV + init script service units with + an LSB header referring to the + <literal>$named</literal> + facility.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>nss-user-lookup.target</filename></term> + <listitem> + <para>A target that should be + used as synchronization point + for all user/group name + service lookups. Note that + this is independent of + host/network name lookups for + which + <filename>nss-lookup.target</filename> + should be used. </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>printer.target</filename></term> + <listitem> + <para>This target is started + automatically as soon as a + printer is plugged in or + becomes available at + boot.</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>$portmap</literal> + facility.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>runlevel2.target</filename></term> + <term><filename>runlevel3.target</filename></term> + <term><filename>runlevel4.target</filename></term> + <term><filename>runlevel5.target</filename></term> + <listitem> + <para>These are targets that + are called whenever the SysV + compatibility code asks for + runlevel 2, 3, 4, 5, + respectively. It is a good + idea to make this an alias for + (i.e. symlink to) + <filename>multi-user.target</filename> + (for runlevel 2) or + <filename>graphical.target</filename> + (the others).</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>sleep.target</filename></term> + <listitem> + <para>A special target unit + that is pulled in by + <filename>suspend.target</filename>, + <filename>hibernate.target</filename> and <filename>hybrid-sleep.target</filename> + and may be used to hook units + into the sleep state + logic.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>smartcard.target</filename></term> + <listitem> + <para>This target is started + automatically as soon as a + smartcard controller is + plugged in or becomes + available at boot.</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>sound.target</filename></term> + <listitem> + <para>This target is started + automatically as soon as a + sound card is plugged in or + becomes available at + boot.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>suspend.target</filename></term> + <listitem> + <para>A special target unit + for suspending the + system. This pulls in + <filename>sleep.target</filename>.</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.socket</filename></term> + <listitem> + <para>The socket unit + syslog implementations should + listen on. All userspace log + messages will be made + available on this socket. For + more information about syslog + integration, please consult + the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/syslog">Syslog + Interface</ulink> + document.</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>system-update.target</filename></term> + <listitem> + <para>A special target unit + that is used for off-line + system updates. + <citerefentry><refentrytitle>systemd-system-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> + will redirect the boot process + to this target if + <filename>/system-update</filename> + exists. For more information + see the <ulink + url="http://freedesktop.org/wiki/Software/systemd/SystemUpdates">System + Updates + Specification</ulink>.</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>shutdown.target</filename>, + <filename>sockets.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.target</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</refentrytitle><manvolnum>1</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.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd.swap.xml b/man/systemd.swap.xml new file mode 100644 index 0000000000..a932143d43 --- /dev/null +++ b/man/systemd.swap.xml @@ -0,0 +1,213 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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>Swap unit configuration</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>Additional options are listed in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which define the execution environment the + <citerefentry><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry> + binary is executed in, and in + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> + which define the way the processes are + terminated.</para> + + <para>Swap units must be named after the devices + or 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 or 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). Swaps listed in + <filename>/etc/fstab</filename> will be converted into + native units dynamically at boot and when the + configuration of the system manager is + reloaded. See + <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for details about the conversion.</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> + and + <citerefentry><refentrytitle>systemd.kill</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> in + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.) + 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> + </variablelist> + + <para>Check + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more settings.</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.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.kill</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>, + <citerefentry><refentrytitle>systemd-fstab-generator</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 0000000000..d1f4d22674 --- /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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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>Target unit configuration</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 0000000000..6fc26a5536 --- /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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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>Timer unit configuration</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 0000000000..c20efe5527 --- /dev/null +++ b/man/systemd.unit.xml @@ -0,0 +1,1084 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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>Unit configuration</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 page lists the common configuration + options of all the unit types. These options need to + be configured in the [Unit] or [Install] + sections of the unit files.</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 appropriate 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> + <row> + <entry><literal>%u</literal></entry> + <entry>User name</entry> + <entry>This is the name of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry> + </row> + <row> + <entry><literal>%h</literal></entry> + <entry>User home directory</entry> + <entry>This is the home directory of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry> + </row> + <row> + <entry><literal>%s</literal></entry> + <entry>User shell</entry> + <entry>This is the shell of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry> + </row> + <row> + <entry><literal>%m</literal></entry> + <entry>Machine ID</entry> + <entry>The machine ID of the running system, formatted as string. See <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information.</entry> + </row> + <row> + <entry><literal>%b</literal></entry> + <entry>Boot ID</entry> + <entry>The boot ID of the running system, formatted as string. See <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information.</entry> + </row> + <row> + <entry><literal>%H</literal></entry> + <entry>Host name</entry> + <entry>The host name of the running system.</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>Documentation=</varname></term> + <listitem><para>A space separated list + of URIs referencing documentation for + this unit or its + configuration. Accepted are only URIs + of the types + <literal>http://</literal>, + <literal>https://</literal>, + <literal>file:</literal>, + <literal>info:</literal>, + <literal>man:</literal>. For more + information about the syntax of these + URIs see + <citerefentry><refentrytitle>uri</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The + URIs should be listed in order of + relevance, starting with the most + relevant. It is a good idea to first + reference documentation that explains + what the unit's purpose is, followed + by how it is configured, followed by + any other related + documentation.</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> + + <para>Note that dependencies of this + type may also be configured outside of + the unit configuration file by + adding a symlink to a + <filename>.requires/</filename> directory + accompanying the unit file. For + details see above.</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> + and <varname>RequiresOverridable=</varname>, respectively. 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.</para> + + <para>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>BindsTo=</varname></term> + + <listitem><para>Configures requirement + dependencies, very similar in style to + <varname>Requires=</varname>, however + in addition to this behavior 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>PartOf=</varname></term> + + <listitem><para>Configures dependencies + similar to <varname>Requires=</varname>, + but limited to stopping and restarting + of units. When systemd stops or restarts + the units listed here, the action is + propagated to this unit. + Note that this is a one way dependency - + changes to this unit do not affect the + listed units. + </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 + or 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>PropagatesReloadTo=</varname></term> + <term><varname>ReloadPropagatedFrom=</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>RequiresMountsFor=</varname></term> + + <listitem><para>Takes a space + separated list of absolute paths. Automatically + adds dependencies of type + <varname>Requires=</varname> and + <varname>After=</varname> for all + mount units required to access the + specified path.</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 + or deactivated indirectly. In + this case explicit start-up + or termination requested by the + user is denied, however if it is + started or stopped as a + dependency of another unit, start-up + or 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>ConditionPathIsReadWrite=</varname></term> + <term><varname>ConditionDirectoryNotEmpty=</varname></term> + <term><varname>ConditionFileNotEmpty=</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>ConditionHost=</varname></term> + <term><varname>ConditionNull=</varname></term> + + <listitem><para>Before starting a unit + verify that the specified condition is + true. If it is not true the starting + of the unit will be skipped, however + all ordering dependencies of it are + still respected. A failing condition + will not result in the unit being + moved into a failure state. The + condition is checked at the time the + queued start job is to be + executed.</para> + + <para>With + <varname>ConditionPathExists=</varname> + a file existence condition is + checked before a unit is started. If + the specified absolute path name does + not exist the condition will + fail. 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.</para> + + <para><varname>ConditionPathExistsGlob=</varname> + is similar to + <varname>ConditionPathExists=</varname>, + but checks for the existence of at + least one file or directory matching + the specified globbing pattern.</para> + + <para><varname>ConditionPathIsDirectory=</varname> + is similar to + <varname>ConditionPathExists=</varname> + but verifies whether a certain path + exists and is a + directory.</para> + + <para><varname>ConditionPathIsSymbolicLink=</varname> + is similar to + <varname>ConditionPathExists=</varname> + but verifies whether a certain path + exists and is a symbolic + link.</para> + + <para><varname>ConditionPathIsMountPoint=</varname> + is similar to + <varname>ConditionPathExists=</varname> + but verifies whether a certain path + exists and is a mount + point.</para> + + <para><varname>ConditionPathIsReadWrite=</varname> + is similar to + <varname>ConditionPathExists=</varname> + but verifies whether the underlying + file system is readable and writable + (i.e. not mounted + read-only).</para> + + <para><varname>ConditionDirectoryNotEmpty=</varname> + is similar to + <varname>ConditionPathExists=</varname> + but verifies whether a certain path + exists and is a non-empty + directory.</para> + + <para><varname>ConditionFileNotEmpty=</varname> + is similar to + <varname>ConditionPathExists=</varname> + but verifies whether a certain path + exists and refers to a regular file + with a non-zero size.</para> + + <para><varname>ConditionFileIsExecutable=</varname> + is similar to + <varname>ConditionPathExists=</varname> + but verifies whether a certain path + exists, is a regular file and marked + executable.</para> + + <para>Similar, + <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 + '='). 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.</para> + + <para><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 generic 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.</para> + + <para><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.</para> + + <para><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.</para> + + <para><varname>ConditionHost=</varname> + may be used to match against the + host name or machine ID of the + host. This either takes a host name + string (optionally with shell style + globs) which is tested against the + locally set host name as returned by + <citerefentry><refentrytitle>gethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + or a machine ID formatted as string + (see + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>). + The test may be negated by prepending + an exclamation mark.</para> + + <para>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.</para> + + <para>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>SourcePath=</varname></term> + <listitem><para>A path to a + configuration file this unit has been + generated from. This is primarily + useful for implementation of generator + tools that convert configuration from + an external configuration file format + into native unit files. Thus + functionality should not be used in + normal units.</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.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>WantedBy=</varname></term> + <term><varname>RequiredBy=</varname></term> + + <listitem><para>Installs a symlink in + the <filename>.wants/</filename> + or <filename>.requires/</filename> + subdirectory for a unit, respectively. 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 0000000000..7b3d265b8d --- /dev/null +++ b/man/systemd.xml @@ -0,0 +1,1272 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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>--version</option></term> + + <listitem><para>Prints a systemd version + identifier 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>For <option>--system</option>, + tell systemd to run a + system instance, even if the process ID is + not 1, i.e. systemd is not run as init process. + <option>--user</option> does the opposite, + running a user instance even if the process + ID is 1. + 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>--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 or error output for all + services and sockets, respectively. That is, controls + the default for + <option>StandardOutput=</option> + and <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> + + <para>Units may be generated dynamically at boot and + system manager reload time, for example based on other + configuration files or parameters passed on the kernel + command line. For details see the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/Generators">Generators + Specification</ulink>.</para> + + <para>Systems which invoke systemd in a container + or initrd environment should implement the + <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container + Interface</ulink> or <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/InitrdInterface">initrd + Interface</ulink> specifications, respectively.</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> + (or <literal>info</literal> on + <literal>SIGRTMIN+23</literal>), as + controlled via + <varname>systemd.log_level=debug</varname> + (or <varname>systemd.log_level=info</varname> + on <literal>SIGRTMIN+23</literal>) on + the kernel command + line.</para></listitem> + </varlistentry> + + <varlistentry> + <term>SIGRTMIN+24</term> + + <listitem><para>Immediately exits the + manager (only available for --user + instances).</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> + (or <literal>console</literal> on + <literal>SIGRTMIN+27</literal>, + <literal>kmsg</literal> on + <literal>SIGRTMIN+28</literal>, + or <literal>syslog-or-kmsg</literal> + on <literal>SIGRTMIN+29</literal>), as + controlled via + <varname>systemd.log_target=journal-or-kmsg</varname> + (or <varname>systemd.log_target=console</varname> + on <literal>SIGRTMIN+27</literal>, + <varname>systemd.log_target=kmsg</varname> + on <literal>SIGRTMIN+28</literal>, + or + <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> + <term><varname>rd.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. The + option prefixed with + <literal>rd.</literal> is honored + only in the initial RAM disk (initrd), + while the one that isn't prefixed only + in the main system.</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>, 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 and error output for + services, with the same effect as the + <option>--default-standard-output=</option> + and <option>--default-standard-error=</option> + command line arguments described + above, respectively.</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 it unsets + an environment variable which might be + passed in from the initial ram + disk.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>quiet</varname></term> + + <listitem><para>If passed turns off + status output at boot, much like + <varname>systemd.show_status=false</varname> + would. Note that this option is also + read by the kernel itself and disables + kernel log output to the + kernel. Passing this option hence + turns off the usual output from both + the system manager and the + kernel.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>emergency</varname></term> + + <listitem><para>Boot into emergency + mode. This is equivalent to + <varname>systemd.unit=emergency.target</varname> + and provided for compatibility + reasons and to be easier to type.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>single</varname></term> + <term><varname>s</varname></term> + <term><varname>S</varname></term> + <term><varname>1</varname></term> + + <listitem><para>Boot into rescue + mode. This is equivalent to + <varname>systemd.unit=rescue.target</varname> + and provided for compatibility reasons + and to be easier to + type.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>2</varname></term> + <term><varname>3</varname></term> + <term><varname>4</varname></term> + <term><varname>5</varname></term> + + <listitem><para>Boot into the + specified legacy SysV runlevel. These + are equivalent to + <varname>systemd.unit=runlevel2.target</varname>, + <varname>systemd.unit=runlevel3.target</varname>, + <varname>systemd.unit=runlevel4.target</varname>, + and <varname>systemd.unit=runlevel5.target</varname>, respectively, + and provided for compatibility reasons + and to be easier to + type.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>locale.LANG=</varname></term> + <term><varname>locale.LANGUAGE=</varname></term> + <term><varname>locale.LC_CTYPE=</varname></term> + <term><varname>locale.LC_NUMERIC=</varname></term> + <term><varname>locale.LC_TIME=</varname></term> + <term><varname>locale.LC_COLLATE=</varname></term> + <term><varname>locale.LC_MONETARY=</varname></term> + <term><varname>locale.LC_MESSAGES=</varname></term> + <term><varname>locale.LC_PAPER=</varname></term> + <term><varname>locale.LC_NAME=</varname></term> + <term><varname>locale.LC_ADDRESS=</varname></term> + <term><varname>locale.LC_TELEPHONE=</varname></term> + <term><varname>locale.LC_MEASUREMENT=</varname></term> + <term><varname>locale.LC_IDENTIFICATION=</varname></term> + + <listitem><para>Set the system locale + to use. This overrides the settings in + <filename>/etc/locale.conf</filename>. For + more information see + <citerefentry><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>locale</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + </para></listitem> + </varlistentry> + </variablelist> + + <para>For other kernel command line parameters + understood by components of the core OS, please refer + to + <citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + </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>systemd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>journalctl</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>3</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>, + <citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/telinit.xml b/man/telinit.xml new file mode 100644 index 0000000000..4c6064f54a --- /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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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/timedatectl.xml b/man/timedatectl.xml new file mode 100644 index 0000000000..01ca0a73d5 --- /dev/null +++ b/man/timedatectl.xml @@ -0,0 +1,293 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="timedatectl"> + + <refentryinfo> + <title>timedatectl</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>timedatectl</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>timedatectl</refname> + <refpurpose>Control the system time and date</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>timedatectl <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="req">COMMAND</arg></command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>timedatectl</command> may be used to + query and change the system clock and its + settings.</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>--no-ask-password</option></term> + + <listitem><para>Don't query the user + for authentication for privileged + operations.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-H</option></term> + <term><option>--host</option></term> + + <listitem><para>Execute the operation + remotely. Specify a hostname, or + username and hostname separated by @, + to connect to. This will use SSH to + talk to a remote + system.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--adjust-system-clock</option></term> + + <listitem><para>If + <command>set-local-rtc</command> is + invoked and this option is passed the + system clock is synchronized from the + RTC again, taking the new setting into + account. Otherwise the RTC is + synchronized from the system + clock.</para></listitem> + </varlistentry> + </variablelist> + + <para>The following commands are understood:</para> + + <variablelist> + <varlistentry> + <term><command>status</command></term> + + <listitem><para>Show current settings + of the system clock and + RTC.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>set-time [TIME]</command></term> + + <listitem><para>Set the system clock + to the specified time. This will also + update the RTC time accordingly. The time + may be specified in the format + "2012-10-30 + 18:17:16".</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>set-timezone [TIMEZONE]</command></term> + + <listitem><para>Set the system time + zone to the specified value. Available + time zones can be listed with + <command>list-timezones</command>. If + the RTC is configured to be in the + local time this will also update the + RTC time. This call will alter the + <filename>/etc/localtime</filename> + symlink. See + <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more + information.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>list-timezones</command></term> + + <listitem><para>List available time + zones, one per line. Entries from the + list can be set as the system + time zone with + <command>set-timezone</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>set-local-rtc [BOOL]</command></term> + + <listitem><para>Takes a boolean + argument. If <literal>0</literal> the + system is configured to maintain the + RTC in universal time, if + <literal>1</literal> it will maintain + the RTC in local time instead. Note + that maintaining the RTC in the local + time zone is not fully supported and + will create various problems with time + zone changes and daylight saving + adjustments. If at all possible use + RTC in UTC. Note that invoking this + will also synchronize the RTC from the + system clock, unless + <option>--adjust-system-clock</option> is + passed (see above). This command will + change the 3rd line of + <filename>/etc/adjtime</filename>, as + documented in + <citerefentry><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>set-ntp [BOOL]</command></term> + + <listitem><para>Takes a boolean + argument. Controls whether NTP based + network time synchronization is + enabled (if + available).</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>Examples</title> + <para>Show current settings: + <programlisting> +$ timedatectl + Local time: Fri, 2012-11-02 09:26:46 CET + Universal time: Fri, 2012-11-02 08:26:46 UTC + RTC time: Fri, 2012-11-02 08:26:45 + Timezone: Europe/Warsaw + UTC offset: +0100 + NTP enabled: no +NTP synchronized: no + RTC in local TZ: no + DST active: no + Last DST change: CEST → CET, DST became inactive + Sun, 2012-10-28 02:59:59 CEST + Sun, 2012-10-28 02:00:00 CET + Next DST change: CET → CEST, DST will become active + the clock will jump one hour forward + Sun, 2013-03-31 01:59:59 CET + Sun, 2013-03-31 03:00:00 CEST + </programlisting> + </para> + + <para>Enable an NTP daemon (chronyd): + <programlisting> +$ timedatectl set-ntp true +==== AUTHENTICATING FOR org.freedesktop.timedate1.set-ntp === +Authentication is required to control whether network time synchronization shall be enabled. +Authenticating as: user +Password: ******** +==== AUTHENTICATION COMPLETE === + </programlisting> + + <programlisting> +$ systemctl status chronyd.service +chronyd.service - NTP client/server + Loaded: loaded (/usr/lib/systemd/system/chronyd.service; enabled) + Active: active (running) since Fri, 2012-11-02 09:36:25 CET; 5s ago +... + </programlisting> + </para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>date</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-timedated.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/tmpfiles.d.xml b/man/tmpfiles.d.xml new file mode 100644 index 0000000000..785264e3cf --- /dev/null +++ b/man/tmpfiles.d.xml @@ -0,0 +1,321 @@ +<?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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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 shall be 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> + and <filename>/run/</filename>. Files in + <filename>/run/</filename> override files with the same + name in <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 files installed by vendor packages. All + configuration files are sorted by their filename 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 later name.</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/tmpfiles.d/</filename> bearing the + same file 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 the file exists. + Lines of this type accept shell-style globs in place of normal path + names. The argument parameter will be written without a trailing + newline. C-style backslash escapes are interpreted.</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 + 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. If an integer is given without a unit, + s is assumed. + </para> + + <para>When the age is set to zero, the files are cleaned + unconditionally.</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> + + <para>If the age field starts with a tilde + character (~) the clean-up is only applied to + files and directories one level inside the + directory specified, but not the files and + directories immediately inside it.</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>, + <citerefentry><refentrytitle>systemd-delta</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/udev.xml b/man/udev.xml new file mode 100644 index 0000000000..7ec7a3fed0 --- /dev/null +++ b/man/udev.xml @@ -0,0 +1,705 @@ +<?xml version='1.0'?> +<?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"> + +<refentry id="udev"> + <refentryinfo> + <title>udev</title> + <productname>systemd</productname> + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Greg</firstname> + <surname>Kroah-Hartmann</surname> + <email>greg@kroah.com</email> + </author> + <author> + <contrib>Developer</contrib> + <firstname>Kay</firstname> + <surname>Sievers</surname> + <email>kay@vrfy.org</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>udev</refentrytitle> + <manvolnum>7</manvolnum> + </refmeta> + + <refnamediv> + <refname>udev</refname> + <refpurpose>Linux dynamic device management</refpurpose> + </refnamediv> + + <refsect1><title>Description</title> + <para>udev supplies the system software with device events, manages permissions + of device nodes and may create additional symlinks in the <filename>/dev</filename> + directory, or renames network interfaces. The kernel usually just assigns unpredictable + device names based on the order of discovery. Meaningful symlinks or network device + names provide a way to reliably identify devices based on their properties or + current configuration.</para> + + <para>The udev daemon, <citerefentry><refentrytitle>systemd-udevd.service</refentrytitle> + <manvolnum>8</manvolnum></citerefentry>, receives device uevents directly from + the kernel whenever a device is added or removed from the system, or it changes its + state. When udev receives a device event, it matches its configured set of rules + against various device attributes to identify the device. Rules that match may + provide additional device information to be stored in the udev database or + to be used to create meaningful symlink names.</para> + + <para>All device information udev processes is stored in the udev database and + sent out to possible event subscribers. Access to all stored data and the event + sources is provided by the library libudev.</para> + </refsect1> + + <refsect1><title>Configuration</title> + <para>udev configuration files are placed in <filename>/etc/udev</filename> + and <filename>/usr/lib/udev</filename>. All empty lines or lines beginning with + '#' are ignored.</para> + + <refsect2><title>Configuration file</title> + <para>udev expects its main configuration file at <filename>/etc/udev/udev.conf</filename>. + It consists of a set of variables allowing the user to override default udev values. + The following variables can be set:</para> + <variablelist> + <varlistentry> + <term><option>udev_log</option></term> + <listitem> + <para>The logging priority. Valid values are the numerical syslog priorities + or their textual representations: <option>err</option>, <option>info</option> + and <option>debug</option>.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2><title>Rules files</title> + <para>The udev rules are read from the files located in the + system rules directory <filename>/usr/lib/udev/rules.d</filename>, + the volatile runtime directory <filename>/run/udev/rules.d</filename> + and the local administration directory <filename>/etc/udev/rules.d</filename>. + All rules files are collectively sorted and processed in lexical order, + regardless of the directories in which they live. However, files with + identical file names replace each other. Files in <filename>/etc</filename> + have the highest priority, files in <filename>/run</filename> take precedence + over files with the same name in <filename>/lib</filename>. This can be + used to override a system-supplied rules file with a local file if needed; + a symlink in <filename>/etc</filename> with the same name as a rules file in + <filename>/lib</filename>, pointing to <filename>/dev/null</filename>, + disables the rules file entirely.</para> + + <para>Rule files must have the extension <filename>.rules</filename>; other + extensions are ignored.</para> + + <para>Every line in the rules file contains at least one key-value pair. + There are two kinds of keys: match and assignment. + If all match keys are matching against its value, the rule gets applied and the + assignment keys get the specified value assigned.</para> + + <para>A matching rule may rename a network interface, add symlinks + pointing to the device node, or run a specified program as part of + the event handling.</para> + + <para>A rule consists of a comma-separated list of one or more key-value pairs. + Each key has a distinct operation, depending on the used operator. Valid + operators are:</para> + <variablelist> + <varlistentry> + <term><option>==</option></term> + <listitem> + <para>Compare for equality.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>!=</option></term> + <listitem> + <para>Compare for inequality.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>=</option></term> + <listitem> + <para>Assign a value to a key. Keys that represent a list are reset + and only this single value is assigned.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>+=</option></term> + <listitem> + <para>Add the value to a key that holds a list of entries.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>:=</option></term> + <listitem> + <para>Assign a value to a key finally; disallow any later changes.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>The following key names can be used to match against device properties. + Some of the keys also match against properties of the parent devices in sysfs, + not only the device that has generated the event. If multiple keys that match + a parent device are specified in a single rule, all these keys must match at + one and the same parent device.</para> + <variablelist> + <varlistentry> + <term><option>ACTION</option></term> + <listitem> + <para>Match the name of the event action.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>DEVPATH</option></term> + <listitem> + <para>Match the devpath of the event device.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>KERNEL</option></term> + <listitem> + <para>Match the name of the event device.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>NAME</option></term> + <listitem> + <para>Match the name of a network interface. It can be used once the + NAME key has been set in one of the preceding rules.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>SYMLINK</option></term> + <listitem> + <para>Match the name of a symlink targeting the node. It can + be used once a SYMLINK key has been set in one of the preceding + rules. There may be multiple symlinks; only one needs to match. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>SUBSYSTEM</option></term> + <listitem> + <para>Match the subsystem of the event device.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>DRIVER</option></term> + <listitem> + <para>Match the driver name of the event device. Only set this key for devices + which are bound to a driver at the time the event is generated.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>ATTR{<replaceable>filename</replaceable>}</option></term> + <listitem> + <para>Match sysfs attribute values of the event device. Trailing + whitespace in the attribute values is ignored unless the specified match + value itself contains trailing whitespace. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>KERNELS</option></term> + <listitem> + <para>Search the devpath upwards for a matching device name.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>SUBSYSTEMS</option></term> + <listitem> + <para>Search the devpath upwards for a matching device subsystem name.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>DRIVERS</option></term> + <listitem> + <para>Search the devpath upwards for a matching device driver name.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>ATTRS{<replaceable>filename</replaceable>}</option></term> + <listitem> + <para>Search the devpath upwards for a device with matching sysfs attribute values. + If multiple <option>ATTRS</option> matches are specified, all of them + must match on the same device. Trailing whitespace in the attribute values is ignored + unless the specified match value itself contains trailing whitespace.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>TAGS</option></term> + <listitem> + <para>Search the devpath upwards for a device with matching tag.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>ENV{<replaceable>key</replaceable>}</option></term> + <listitem> + <para>Match against a device property value.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>TAG</option></term> + <listitem> + <para>Match against a device tag.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>TEST{<replaceable>octal mode mask</replaceable>}</option></term> + <listitem> + <para>Test the existence of a file. An octal mode mask can be specified + if needed.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>PROGRAM</option></term> + <listitem> + <para>Execute a program to determine whether there + is a match; the key is true if the program returns + successfully. The device properties are made available to the + executed program in the environment. The program's stdout + is available in the RESULT key.</para> + <para>This can only be used for very short-running foreground tasks. For details + see <option>RUN</option>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>RESULT</option></term> + <listitem> + <para>Match the returned string of the last PROGRAM call. This key can + be used in the same or in any later rule after a PROGRAM call.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>Most of the fields support shell-style pattern matching. The following + pattern characters are supported:</para> + <variablelist> + <varlistentry> + <term><option>*</option></term> + <listitem> + <para>Matches zero or more characters.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>?</option></term> + <listitem> + <para>Matches any single character.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>[]</option></term> + <listitem> + <para>Matches any single character specified within the brackets. For + example, the pattern string 'tty[SR]' would match either 'ttyS' or 'ttyR'. + Ranges are also supported via the '-' character. + For example, to match on the range of all digits, the pattern [0-9] could + be used. If the first character following the '[' is a '!', any characters + not enclosed are matched.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>The following keys can get values assigned:</para> + <variablelist> + <varlistentry> + <term><option>NAME</option></term> + <listitem> + <para>The name to use for a network interface. The name of a device node + cannot be changed by udev, only additional symlinks can be created.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>SYMLINK</option></term> + <listitem> + <para>The name of a symlink targeting the node. Every matching rule adds + this value to the list of symlinks to be created.</para> + <para>The set of characters to name a symlink is limited. Allowed + characters are [0-9A-Za-z#+-.:=@_/], valid utf8 character sequences, + and "\x00" hex encoding. All other characters are replaced by + a '_' character.</para> + <para>Multiple symlinks may be specified by separating the names by the + space character. In case multiple devices claim the same name, the link + always points to the device with the highest link_priority. If the current + device goes away, the links are re-evaluated and the device with the + next highest link_priority becomes the owner of the link. If no + link_priority is specified, the order of the devices (and which one of + them owns the link) is undefined.</para> + <para>Symlink names must never conflict with the kernel's default device + node names, as that would result in unpredictable behavior. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>OWNER, GROUP, MODE</option></term> + <listitem> + <para>The permissions for the device node. Every specified value overrides + the compiled-in default value.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>ATTR{<replaceable>key</replaceable>}</option></term> + <listitem> + <para>The value that should be written to a sysfs attribute of the + event device.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>ENV{<replaceable>key</replaceable>}</option></term> + <listitem> + <para>Set a device property value. Property names with a leading '.' + are neither stored in the database nor exported to events or + external tools (run by, say, the PROGRAM match key).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>TAG</option></term> + <listitem> + <para>Attach a tag to a device. This is used to filter events for users + of libudev's monitor functionality, or to enumerate a group of tagged + devices. The implementation can only work efficiently if only a few + tags are attached to a device. It is only meant to be used in + contexts with specific device filter requirements, and not as a + general-purpose flag. Excessive use might result in inefficient event + handling.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>RUN</option></term> + <listitem> + <para>Add a program to the list of programs to be executed for a specific + device.</para> + <para>If no absolute path is given, the program is expected to live in + /usr/lib/udev, otherwise the absolute path must be specified. The program + name and following arguments are separated by spaces. Single quotes can + be used to specify arguments with spaces.</para> + <para>This can only be used for very short-running foreground tasks. Running an + event process for a long period of time may block all further events for + this or a dependent device.</para> + <para>Starting daemons or other long running processes is not appropriate + for udev; the forked processes, detached or not, will be unconditionally + killed after the event handling has finished.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>LABEL</option></term> + <listitem> + <para>A named label to which a GOTO may jump.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>GOTO</option></term> + <listitem> + <para>Jumps to the next LABEL with a matching name.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>IMPORT{<replaceable>type</replaceable>}</option></term> + <listitem> + <para>Import a set of variables as device properties, + depending on <replaceable>type</replaceable>:</para> + <variablelist> + <varlistentry> + <term><option>program</option></term> + <listitem> + <para>Execute an external program specified as the assigned value and + import its output, which must be in environment key + format. Path specification, command/argument separation, + and quoting work like in <option>RUN</option>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>file</option></term> + <listitem> + <para>Import a text file specified as the assigned value, the content + of which must be in environment key format.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>db</option></term> + <listitem> + <para>Import a single property specified as the assigned value from the + current device database. This works only if the database is already populated + by an earlier event.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>cmdline</option></term> + <listitem> + <para>Import a single property from the kernel command line. For simple flags + the value of the property is set to '1'.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>parent</option></term> + <listitem> + <para>Import the stored keys from the parent device by reading + the database entry of the parent device. The value assigned to + <option>IMPORT{parent}</option> is used as a filter of key names + to import (with the same shell-style pattern matching used for + comparisons).</para> + </listitem> + </varlistentry> + </variablelist> + <para>This can only be used for very short-running foreground tasks. For details + see <option>RUN</option>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>WAIT_FOR</option></term> + <listitem> + <para>Wait for a file to become available or until a timeout of + 10 seconds expires. The path is relative to the sysfs device; + if no path is specified, this waits for an attribute to appear.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>OPTIONS</option></term> + <listitem> + <para>Rule and device options:</para> + <variablelist> + <varlistentry> + <term><option>link_priority=<replaceable>value</replaceable></option></term> + <listitem> + <para>Specify the priority of the created symlinks. Devices with higher + priorities overwrite existing symlinks of other devices. The default is 0.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>event_timeout=</option></term> + <listitem> + <para>Number of seconds an event waits for operations to finish before + giving up and terminating itself.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>string_escape=<replaceable>none|replace</replaceable></option></term> + <listitem> + <para>Usually control and other possibly unsafe characters are replaced + in strings used for device naming. The mode of replacement can be specified + with this option.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>static_node=</option></term> + <listitem> + <para>Apply the permissions specified in this rule to the static device node with + the specified name. Static device node creation can be requested by kernel modules. + These nodes might not have a corresponding kernel device at the time systemd-udevd is + started; they can trigger automatic kernel module loading.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>watch</option></term> + <listitem> + <para>Watch the device node with inotify; when the node is closed after being opened for + writing, a change uevent is synthesized.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>nowatch</option></term> + <listitem> + <para>Disable the watching of a device node with inotify.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + </variablelist> + + <para>The <option>NAME</option>, <option>SYMLINK</option>, <option>PROGRAM</option>, + <option>OWNER</option>, <option>GROUP</option>, <option>MODE</option> and <option>RUN</option> + fields support simple string substitutions. The <option>RUN</option> + substitutions are performed after all rules have been processed, right before the program + is executed, allowing for the use of device properties set by earlier matching + rules. For all other fields, substitutions are performed while the individual rule is + being processed. The available substitutions are:</para> + <variablelist> + <varlistentry> + <term><option>$kernel</option>, <option>%k</option></term> + <listitem> + <para>The kernel name for this device.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>$number</option>, <option>%n</option></term> + <listitem> + <para>The kernel number for this device. For example, 'sda3' has + kernel number of '3'</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>$devpath</option>, <option>%p</option></term> + <listitem> + <para>The devpath of the device.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>$id</option>, <option>%b</option></term> + <listitem> + <para>The name of the device matched while searching the devpath upwards for + <option>SUBSYSTEMS</option>, <option>KERNELS</option>, <option>DRIVERS</option> and <option>ATTRS</option>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>$driver</option></term> + <listitem> + <para>The driver name of the device matched while searching the devpath upwards for + <option>SUBSYSTEMS</option>, <option>KERNELS</option>, <option>DRIVERS</option> and <option>ATTRS</option>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>$attr{<replaceable>file</replaceable>}</option>, <option>%s{<replaceable>file</replaceable>}</option></term> + <listitem> + <para>The value of a sysfs attribute found at the device where + all keys of the rule have matched. If the matching device does not have + such an attribute, and a previous KERNELS, SUBSYSTEMS, DRIVERS, or + ATTRS test selected a parent device, then the attribute from that + parent device is used.</para> + <para>If the attribute is a symlink, the last element of the symlink target is + returned as the value.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>$env{<replaceable>key</replaceable>}</option>, <option>%E{<replaceable>key</replaceable>}</option></term> + <listitem> + <para>A device property value.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>$major</option>, <option>%M</option></term> + <listitem> + <para>The kernel major number for the device.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>$minor</option>, <option>%m</option></term> + <listitem> + <para>The kernel minor number for the device.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>$result</option>, <option>%c</option></term> + <listitem> + <para>The string returned by the external program requested with PROGRAM. + A single part of the string, separated by a space character, may be selected + by specifying the part number as an attribute: <option>%c{N}</option>. + If the number is followed by the '+' character, this part plus all remaining parts + of the result string are substituted: <option>%c{N+}</option></para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>$parent</option>, <option>%P</option></term> + <listitem> + <para>The node name of the parent device.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>$name</option></term> + <listitem> + <para>The current name of the device. If not changed by a rule, it is the + name of the kernel device.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>$links</option></term> + <listitem> + <para>A space-separated list of the current symlinks. The value is + only set during a remove event or if an earlier rule assigned a value.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>$root</option>, <option>%r</option></term> + <listitem> + <para>The udev_root value.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>$sys</option>, <option>%S</option></term> + <listitem> + <para>The sysfs mount point.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>$devnode</option>, <option>%N</option></term> + <listitem> + <para>The name of the device node.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>%%</option></term> + <listitem> + <para>The '%' character itself.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>$$</option></term> + <listitem> + <para>The '$' character itself.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>See Also</title> + <para><citerefentry> + <refentrytitle>systemd-udevd.service</refentrytitle><manvolnum>8</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>udevadm</refentrytitle><manvolnum>8</manvolnum> + </citerefentry></para> + </refsect1> +</refentry> diff --git a/man/udevadm.xml b/man/udevadm.xml new file mode 100644 index 0000000000..015980a63b --- /dev/null +++ b/man/udevadm.xml @@ -0,0 +1,495 @@ +<?xml version='1.0'?> +<?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"> + +<refentry id="udevadm"> + <refentryinfo> + <title>udevadm</title> + <productname>systemd</productname> + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Kay</firstname> + <surname>Sievers</surname> + <email>kay@vrfy.org</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>udevadm</refentrytitle> + <manvolnum>8</manvolnum> + <refmiscinfo class="version"></refmiscinfo> + </refmeta> + + <refnamediv> + <refname>udevadm</refname><refpurpose>udev management tool</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>udevadm</command> + <arg><option>--debug</option></arg> + <arg><option>--version</option></arg> + <arg><option>--help</option></arg> + </cmdsynopsis> + <cmdsynopsis> + <command>udevadm info <replaceable>options</replaceable></command> + </cmdsynopsis> + <cmdsynopsis> + <command>udevadm trigger <optional>options</optional></command> + </cmdsynopsis> + <cmdsynopsis> + <command>udevadm settle <optional>options</optional></command> + </cmdsynopsis> + <cmdsynopsis> + <command>udevadm control <replaceable>command</replaceable></command> + </cmdsynopsis> + <cmdsynopsis> + <command>udevadm monitor <optional>options</optional></command> + </cmdsynopsis> + <cmdsynopsis> + <command>udevadm hwdb <optional>options</optional></command> + </cmdsynopsis> + <cmdsynopsis> + <command>udevadm test <optional>options</optional> <replaceable>devpath</replaceable></command> + </cmdsynopsis> + <cmdsynopsis> + <command>udevadm test-builtin <optional>options</optional> <replaceable>command</replaceable> <replaceable>devpath</replaceable></command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1><title>Description</title> + <para>udevadm expects a command and command specific options. It + controls the runtime behavior of udev, requests kernel events, + manages the event queue, and provides simple debugging mechanisms.</para> + </refsect1> + + <refsect1><title>OPTIONS</title> + <variablelist> + <varlistentry> + <term><option>--debug</option></term> + <listitem> + <para>Print debug messages to stderr.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--version</option></term> + <listitem> + <para>Print version number.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--help</option></term> + <listitem> + <para>Print help text.</para> + </listitem> + </varlistentry> + </variablelist> + + <refsect2><title>udevadm info <replaceable>options</replaceable></title> + <para>Queries the udev database for device information + stored in the udev database. It can also query the properties + of a device from its sysfs representation to help creating udev + rules that match this device.</para> + <variablelist> + <varlistentry> + <term><option>--query=<replaceable>type</replaceable></option></term> + <listitem> + <para>Query the database for specified type of device data. It needs the + <option>--path</option> or <option>--name</option> to identify the specified + device. Valid queries are: + <command>name</command>, <command>symlink</command>, <command>path</command>, + <command>property</command>, <command>all</command>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--path=<replaceable>devpath</replaceable></option></term> + <listitem> + <para>The devpath of the device to query.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--name=<replaceable>file</replaceable></option></term> + <listitem> + <para>The name of the device node or a symlink to query</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--root</option></term> + <listitem> + <para>Print absolute paths in <command>name</command> or <command>symlink</command> + query.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--attribute-walk</option></term> + <listitem> + <para>Print all sysfs properties of the specified device that can be used + in udev rules to match the specified device. It prints all devices + along the chain, up to the root of sysfs that can be used in udev rules.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--export</option></term> + <listitem> + <para>Print output as key/value pairs. Values are enclosed in single quotes.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--export-prefix=<replaceable>name</replaceable></option></term> + <listitem> + <para>Add a prefix to the key name of exported values.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--device-id-of-file=<replaceable>file</replaceable></option></term> + <listitem> + <para>Print major/minor numbers of the underlying device, where the file + lives on.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--export-db</option></term> + <listitem> + <para>Export the content of the udev database.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--cleanup-db</option></term> + <listitem> + <para>Cleanup the udev database.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--version</option></term> + <listitem> + <para>Print version.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--help</option></term> + <listitem> + <para>Print help text.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2><title>udevadm trigger <optional>options</optional></title> + <para>Request device events from the kernel. Primarily used to replay events at system coldplug time.</para> + <variablelist> + <varlistentry> + <term><option>--verbose</option></term> + <listitem> + <para>Print the list of devices which will be triggered.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--dry-run</option></term> + <listitem> + <para>Do not actually trigger the event.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--type=<replaceable>type</replaceable></option></term> + <listitem> + <para>Trigger a specific type of devices. Valid types are: + <command>devices</command>, <command>subsystems</command>. + The default value is <command>devices</command>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--action=<replaceable>action</replaceable></option></term> + <listitem> + <para>Type of event to be triggered. The default value is <command>change</command>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--subsystem-match=<replaceable>subsystem</replaceable></option></term> + <listitem> + <para>Trigger events for devices which belong to a matching subsystem. This option + can be specified multiple times and supports shell style pattern matching.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--subsystem-nomatch=<replaceable>subsystem</replaceable></option></term> + <listitem> + <para>Do not trigger events for devices which belong to a matching subsystem. This option + can be specified multiple times and supports shell style pattern matching.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--attr-match=<replaceable>attribute</replaceable>=<replaceable>value</replaceable></option></term> + <listitem> + <para>Trigger events for devices with a matching sysfs attribute. If a value is specified + along with the attribute name, the content of the attribute is matched against the given + value using shell style pattern matching. If no value is specified, the existence of the + sysfs attribute is checked. This option can be specified multiple times.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--attr-nomatch=<replaceable>attribute</replaceable>=<replaceable>value</replaceable></option></term> + <listitem> + <para>Do not trigger events for devices with a matching sysfs attribute. If a value is + specified along with the attribute name, the content of the attribute is matched against + the given value using shell style pattern matching. If no value is specified, the existence + of the sysfs attribute is checked. This option can be specified multiple times.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--property-match=<replaceable>property</replaceable>=<replaceable>value</replaceable></option></term> + <listitem> + <para>Trigger events for devices with a matching property value. This option can be + specified multiple times and supports shell style pattern matching.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--tag-match=<replaceable>property</replaceable></option></term> + <listitem> + <para>Trigger events for devices with a matching tag. This option can be + specified multiple times.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--sysname-match=<replaceable>name</replaceable></option></term> + <listitem> + <para>Trigger events for devices with a matching sys device name. This option can be + specified multiple times and supports shell style pattern matching.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--parent-match=<replaceable>syspath</replaceable></option></term> + <listitem> + <para>Trigger events for all children of a given device.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2><title>udevadm settle <optional>options</optional></title> + <para>Watches the udev event queue, and exits if all current events are handled.</para> + <variablelist> + <varlistentry> + <term><option>--timeout=<replaceable>seconds</replaceable></option></term> + <listitem> + <para>Maximum number of seconds to wait for the event queue to become empty. + The default value is 120 seconds. A value of 0 will check if the queue is empty + and always return immediately.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--seq-start=<replaceable>seqnum</replaceable></option></term> + <listitem> + <para>Wait only for events after the given sequence number.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--seq-end=<replaceable>seqnum</replaceable></option></term> + <listitem> + <para>Wait only for events before the given sequence number.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--exit-if-exists=<replaceable>file</replaceable></option></term> + <listitem> + <para>Stop waiting if file exists.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--quiet</option></term> + <listitem> + <para>Do not print any output, like the remaining queue entries when reaching the timeout.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--help</option></term> + <listitem> + <para>Print help text.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2><title>udevadm control <replaceable>command</replaceable></title> + <para>Modify the internal state of the running udev daemon.</para> + <variablelist> + <varlistentry> + <term><option>--exit</option></term> + <listitem> + <para>Signal and wait for systemd-udevd to exit.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--log-priority=<replaceable>value</replaceable></option></term> + <listitem> + <para>Set the internal log level of systemd-udevd. Valid values are the numerical + syslog priorities or their textual representations: <option>err</option>, + <option>info</option> and <option>debug</option>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--stop-exec-queue</option></term> + <listitem> + <para>Signal systemd-udevd to stop executing new events. Incoming events + will be queued.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--start-exec-queue</option></term> + <listitem> + <para>Signal systemd-udevd to enable the execution of events.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--reload</option></term> + <listitem> + <para>Signal systemd-udevd to reload the rules files and other databases like the kernel + module index. Reloading rules and databases does not apply any changes to already + existing devices; the new configuration will only be applied to new events.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--property=<replaceable>KEY</replaceable>=<replaceable>value</replaceable></option></term> + <listitem> + <para>Set a global property for all events.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--children-max=</option><replaceable>value</replaceable></term> + <listitem> + <para>Set the maximum number of events, systemd-udevd will handle at the + same time.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--timeout=</option><replaceable>seconds</replaceable></term> + <listitem> + <para>The maximum number of seconds to wait for a reply from systemd-udevd.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--help</option></term> + <listitem> + <para>Print help text.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2><title>udevadm monitor <optional>options</optional></title> + <para>Listens to the kernel uevents and events sent out by a udev rule + and prints the devpath of the event to the console. It can be used to analyze the + event timing, by comparing the timestamps of the kernel uevent and the udev event. + </para> + <variablelist> + <varlistentry> + <term><option>--kernel</option></term> + <listitem> + <para>Print the kernel uevents.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--udev</option></term> + <listitem> + <para>Print the udev event after the rule processing.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--property</option></term> + <listitem> + <para>Also print the properties of the event.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--subsystem-match=<replaceable>string[/string]</replaceable></option></term> + <listitem> + <para>Filter events by subsystem[/devtype]. Only udev events with a matching subsystem value will pass.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--tag-match=<replaceable>string</replaceable></option></term> + <listitem> + <para>Filter events by property. Only udev events with a given tag attached will pass.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--help</option></term> + <listitem> + <para>Print help text.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2><title>udevadm hwdb <optional>options</optional></title> + <para>Maintain the hardware database index in /etc/udev/hwdb.bin.</para> + <variablelist> + <varlistentry> + <term><option>--update</option></term> + <listitem> + <para>Compile the hardware dabase information located in /usr/lib/udev/hwdb.d/, + /etc/udev/hwdb.d/ and store it in /etc/udev/hwdb.bin. This should be done with + any update to the source files, it will not be called automatically. The running + udev daemon will detect a new database on its own and does not need to be + notified about it.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--test=<replaceable>string</replaceable></option></term> + <listitem> + <para>Query the database with a modalias string, and print the + retrieved properties.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2><title>udevadm test <optional>options</optional> <replaceable>devpath</replaceable></title> + <para>Simulate a udev event run for the given device, and print debug output.</para> + <variablelist> + <varlistentry> + <term><option>--action=<replaceable>string</replaceable></option></term> + <listitem> + <para>The action string.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--subsystem=<replaceable>string</replaceable></option></term> + <listitem> + <para>The subsystem string.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--help</option></term> + <listitem> + <para>Print help text.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2><title>udevadm test-builtin <optional>options</optional> <replaceable>command</replaceable> <replaceable>devpath</replaceable></title> + <para>Run a built-in command for the given device, and print debug output.</para> + <variablelist> + <varlistentry> + <term><option>--help</option></term> + <listitem> + <para>Print help text.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + + <refsect1> + <title>See Also</title> + <para><citerefentry> + <refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum> + </citerefentry> + <citerefentry> + <refentrytitle>systemd-udevd.service</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 0000000000..45156b7447 --- /dev/null +++ b/man/vconsole.conf.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 Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser 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. It is applied at boot by + <citerefentry><refentrytitle>systemd-vconsole-setup.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + + <para>The basic file format of the + <filename>vconsole.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>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 for the + keyboard. <varname>KEYMAP=</varname> + defaults to <literal>us</literal> if + not set. The + <varname>KEYMAP_TOGGLE=</varname> can + be used to configure 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.</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>systemd-vconsole-setup.service</refentrytitle><manvolnum>8</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>, + <citerefentry><refentrytitle>systemd-localed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> |