diff options
| author | Luke Shumaker <lukeshu@sbcglobal.net> | 2016-09-06 02:27:18 -0400 |
|---|---|---|
| committer | Luke Shumaker <lukeshu@sbcglobal.net> | 2016-09-06 02:27:18 -0400 |
| commit | 4160043a0fac8b812905b7502ce34adf3af538f1 (patch) | |
| tree | 4b95910ee00e86eda8a256910eeef2b224c770ce /man | |
| parent | cd27bb69b17df0fd0da7c06aba41c4da25c12666 (diff) | |
move man pages to appropriate directories
Diffstat (limited to 'man')
236 files changed, 0 insertions, 56967 deletions
diff --git a/man/binfmt.d.xml b/man/binfmt.d.xml deleted file mode 100644 index 5b63cfb4c3..0000000000 --- a/man/binfmt.d.xml +++ /dev/null @@ -1,101 +0,0 @@ -<?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" conditional='ENABLE_BINFMT' - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <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="https://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> - </refsect1> - - <xi:include href="standard-conf.xml" xpointer="confd" /> - - <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 project='die-net'><refentrytitle>wine</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/bootctl.xml b/man/bootctl.xml deleted file mode 100644 index ebd58750d3..0000000000 --- a/man/bootctl.xml +++ /dev/null @@ -1,128 +0,0 @@ -<?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. - - 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="bootctl" conditional='ENABLE_EFI' - xmlns:xi="http://www.w3.org/2001/XInclude"> - <refentryinfo> - <title>bootctl</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>bootctl</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>bootctl</refname> - <refpurpose>Control the firmware and boot manager settings</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>bootctl <arg choice="opt" rep="repeat">OPTIONS</arg>status</command> - </cmdsynopsis> - <cmdsynopsis> - <command>bootctl <arg choice="opt" rep="repeat">OPTIONS</arg>update</command> - </cmdsynopsis> - <cmdsynopsis> - <command>bootctl <arg choice="opt" rep="repeat">OPTIONS</arg>install</command> - </cmdsynopsis> - <cmdsynopsis> - <command>bootctl <arg choice="opt" rep="repeat">OPTIONS</arg>remove</command> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>bootctl</command> checks, updates, - installs or removes the boot loader from the current - system.</para> - - <para><command>bootctl status</command> checks and prints the - currently installed versions of the boot loader binaries and - all current EFI boot variables.</para> - - <para><command>bootctl update</command> updates all installed - versions of systemd-boot, if the current version is newer than the - version installed in the EFI system partition. This also includes - the EFI default/fallback loader at /EFI/Boot/boot*.efi. A - systemd-boot entry in the EFI boot variables is created if there - is no current entry. The created entry will be added to the end of - the boot order list.</para> - - <para><command>bootctl install</command> installs systemd-boot into - the EFI system partition. A copy of systemd-boot will be stored as - the EFI default/fallback loader at /EFI/Boot/boot*.efi. A systemd-boot - entry in the EFI boot variables is created and added to the top - of the boot order list.</para> - - <para><command>bootctl remove</command> removes all installed - versions of systemd-boot from the EFI system partition, and removes - systemd-boot from the EFI boot variables.</para> - - <para>If no command is passed, <command>status</command> is - implied.</para> - </refsect1> - - <refsect1> - <title>Options</title> - <para>The following options are understood:</para> - - <variablelist> - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - <varlistentry> - <term><option>--path</option></term> - <listitem><para>Path to the EFI system partition. The default is /boot.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--no-variables</option></term> - <listitem><para>Do not touch the EFI boot variables.</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> - <ulink url="http://www.freedesktop.org/wiki/Specifications/BootLoaderSpec">Boot loader specification</ulink> - <ulink url="http://www.freedesktop.org/wiki/Software/systemd/BootLoaderInterface">Systemd boot loader interface</ulink> - </para> - </refsect1> -</refentry> diff --git a/man/bootup.xml b/man/bootup.xml deleted file mode 100644 index 986996398c..0000000000 --- a/man/bootup.xml +++ /dev/null @@ -1,305 +0,0 @@ -<?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 (optionally) extracts and executes an initial RAM disk - image (initrd), such as generated by - <citerefentry project='die-net'><refentrytitle>dracut</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - which looks for the root file system (possibly using - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> - for this). After the root file system is found and mounted, the - initrd hands over control to the host's 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 a last step, the system is powered down.</para> - - <para>Additional information about the system boot process may be - found in - <citerefentry project='man-pages'><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 | v v - (various (various | (various rescue.service - timers...) paths...) | sockets...) | - | | | | v - v v | v <emphasis>rescue.target</emphasis> - timers.target paths.target | sockets.target - | | | | - v \_________________ | ___________________/ - \|/ - 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> - - <para><filename>timers.target</filename> is pulled-in by - <filename>basic.target</filename> asynchronously. This allows - timers units to depend on services which become only available - later in boot.</para> - </refsect1> - - <refsect1> - <title>Bootup in the Initial RAM Disk (initrd)</title> - <para>The initial RAM disk implementation (initrd) can be set up - using systemd as well. In this case, boot up inside the initrd - follows the following structure.</para> - - <para>The default target in the initrd is - <filename>initrd.target</filename>. The bootup process begins - identical to the system manager bootup (see above) until it - reaches <filename>basic.target</filename>. From there, systemd - approaches the special target <filename>initrd.target</filename>. - When the root device becomes available, - <filename>initd-root-device.target</filename> is reached. - If the root device can be mounted at - <filename>/sysroot</filename>, the - <filename>sysroot.mount</filename> unit becomes active and - <filename>initrd-root-fs.target</filename> is reached. The service - <filename>initrd-parse-etc.service</filename> scans - <filename>/sysroot/etc/fstab</filename> for a possible - <filename>/usr</filename> mount point and additional entries - marked with the <emphasis>x-initrd.mount</emphasis> option. All - entries found are mounted below <filename>/sysroot</filename>, and - <filename>initrd-fs.target</filename> is reached. The service - <filename>initrd-cleanup.service</filename> isolates to the - <filename>initrd-switch-root.target</filename>, where cleanup - services can run. As the very last step, the - <filename>initrd-switch-root.service</filename> is activated, - which will cause the system to switch its root to - <filename>/sysroot</filename>. - </para> - -<programlisting> : (beginning identical to above) - : - v - basic.target - | emergency.service - ______________________/| | - / | v - | initrd-root-device.target <emphasis>emergency.target</emphasis> - | | - | v - | sysroot.mount - | | - | v - | initrd-root-fs.target - | | - | v - v initrd-parse-etc.service - (custom initrd | - services...) v - | (sysroot-usr.mount and - | various mounts marked - | with fstab option - | x-initrd.mount...) - | | - | v - | initrd-fs.target - \______________________ | - \| - v - initrd.target - | - v - initrd-cleanup.service - isolates to - initrd-switch-root.target - | - v - ______________________/| - / v - | initrd-udevadm-cleanup-db.service - v | - (custom initrd | - services...) | - \______________________ | - \| - v - initrd-switch-root.target - | - v - initrd-switch-root.service - | - v - Transition to Host OS</programlisting> - </refsect1> - - <refsect1> - <title>System Manager Shutdown</title> - - <para>System shutdown with systemd 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 project='man-pages'><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>, - <citerefentry project='die-net'><refentrytitle>dracut</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/busctl.xml b/man/busctl.xml deleted file mode 100644 index b71a174634..0000000000 --- a/man/busctl.xml +++ /dev/null @@ -1,480 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2014 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="busctl" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>busctl</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>A monkey with a typewriter</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>busctl</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>busctl</refname> - <refpurpose>Introspect the bus</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>busctl</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="opt">COMMAND</arg> - <arg choice="opt" rep="repeat"><replaceable>NAME</replaceable></arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>busctl</command> may be used to - introspect and monitor the D-Bus bus.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--address=<replaceable>ADDRESS</replaceable></option></term> - - <listitem><para>Connect to the bus specified by - <replaceable>ADDRESS</replaceable> instead of using suitable - defaults for either the system or user bus (see - <option>--system</option> and <option>--user</option> - options).</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--show-machine</option></term> - - <listitem><para>When showing the list of peers, show a - column containing the names of containers they belong to. - See - <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--unique</option></term> - - <listitem><para>When showing the list of peers, show only - "unique" names (of the form - <literal>:<replaceable>number</replaceable>.<replaceable>number</replaceable></literal>). - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--acquired</option></term> - - <listitem><para>The opposite of <option>--unique</option> — - only "well-known" names will be shown.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--activatable</option></term> - - <listitem><para>When showing the list of peers, show only - peers which have actually not been activated yet, but may be - started automatically if accessed.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--match=<replaceable>MATCH</replaceable></option></term> - - <listitem><para>When showing messages being exchanged, show only the - subset matching <replaceable>MATCH</replaceable>.</para></listitem> - <!-- TODO: link to sd_bus_add_match when it is written? --> - </varlistentry> - - <varlistentry> - <term><option>--size=</option></term> - - <listitem> - <para>When used with the <command>capture</command> command, - specifies the maximum bus message size to capture - ("snaplen"). Defaults to 4096 bytes.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--list</option></term> - - <listitem> - <para>When used with the <command>tree</command> command, shows a - flat list of object paths instead of a tree.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--quiet</option></term> - - <listitem> - <para>When used with the <command>call</command> command, - suppresses display of the response message payload. Note that even - if this option is specified, errors returned will still be - printed and the tool will indicate success or failure with - the process exit code.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--verbose</option></term> - - <listitem> - <para>When used with the <command>call</command> or - <command>get-property</command> command, shows output in a - more verbose format.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--expect-reply=</option><replaceable>BOOL</replaceable></term> - - <listitem> - <para>When used with the <command>call</command> command, - specifies whether <command>busctl</command> shall wait for - completion of the method call, output the returned method - response data, and return success or failure via the process - exit code. If this is set to <literal>no</literal>, the - method call will be issued but no response is expected, the - tool terminates immediately, and thus no response can be - shown, and no success or failure is returned via the exit - code. To only suppress output of the reply message payload, - use <option>--quiet</option> above. Defaults to - <literal>yes</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--auto-start=</option><replaceable>BOOL</replaceable></term> - - <listitem> - <para>When used with the <command>call</command> command, specifies - whether the method call should implicitly activate the - called service, should it not be running yet but is - configured to be auto-started. Defaults to - <literal>yes</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--allow-interactive-authorization=</option><replaceable>BOOL</replaceable></term> - - <listitem> - <para>When used with the <command>call</command> command, - specifies whether the services may enforce interactive - authorization while executing the operation, if the security - policy is configured for this. Defaults to - <literal>yes</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--timeout=</option><replaceable>SECS</replaceable></term> - - <listitem> - <para>When used with the <command>call</command> command, - specifies the maximum time to wait for method call - completion. If no time unit is specified, assumes - seconds. The usual other units are understood, too (ms, us, - s, min, h, d, w, month, y). Note that this timeout does not - apply if <option>--expect-reply=no</option> is used, as the - tool does not wait for any reply message then. When not - specified or when set to 0, the default of - <literal>25s</literal> is assumed.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--augment-creds=</option><replaceable>BOOL</replaceable></term> - - <listitem> - <para>Controls whether credential data reported by - <command>list</command> or <command>status</command> shall - be augmented with data from - <filename>/proc</filename>. When this is turned on, the data - shown is possibly inconsistent, as the data read from - <filename>/proc</filename> might be more recent than the rest of - the credential information. Defaults to <literal>yes</literal>.</para> - </listitem> - </varlistentry> - - <xi:include href="user-system-options.xml" xpointer="user" /> - <xi:include href="user-system-options.xml" xpointer="system" /> - <xi:include href="user-system-options.xml" xpointer="host" /> - <xi:include href="user-system-options.xml" xpointer="machine" /> - - <xi:include href="standard-options.xml" xpointer="no-pager" /> - <xi:include href="standard-options.xml" xpointer="no-legend" /> - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </variablelist> - </refsect1> - - <refsect1> - <title>Commands</title> - - <para>The following commands are understood:</para> - - <variablelist> - <varlistentry> - <term><command>list</command></term> - - <listitem><para>Show all peers on the bus, by their service - names. By default, shows both unique and well-known names, but - this may be changed with the <option>--unique</option> and - <option>--acquired</option> switches. This is the default - operation if no command is specified.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>status</command> <arg choice="opt"><replaceable>SERVICE</replaceable></arg></term> - - <listitem><para>Show process information and credentials of a - bus service (if one is specified by its unique or well-known - name), a process (if one is specified by its numeric PID), or - the owner of the bus (if no parameter is - specified).</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>monitor</command> <arg choice="opt" rep="repeat"><replaceable>SERVICE</replaceable></arg></term> - - <listitem><para>Dump messages being exchanged. If - <replaceable>SERVICE</replaceable> is specified, show messages - to or from this peer, identified by its well-known or unique - name. Otherwise, show all messages on the bus. Use Ctrl-C to - terminate the dump.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>capture</command> <arg choice="opt" rep="repeat"><replaceable>SERVICE</replaceable></arg></term> - - <listitem><para>Similar to <command>monitor</command> but - writes the output in pcap format (for details, see the <ulink - url="http://wiki.wireshark.org/Development/LibpcapFileFormat">Libpcap - File Format</ulink> description. Make sure to redirect the - output to STDOUT to a file. Tools like - <citerefentry project='die-net'><refentrytitle>wireshark</refentrytitle><manvolnum>1</manvolnum></citerefentry> - may be used to dissect and view the generated - files.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>tree</command> <arg choice="opt" rep="repeat"><replaceable>SERVICE</replaceable></arg></term> - - <listitem><para>Shows an object tree of one or more - services. If <replaceable>SERVICE</replaceable> is specified, - show object tree of the specified services only. Otherwise, - show all object trees of all services on the bus that acquired - at least one well-known name.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>introspect</command> <arg choice="plain"><replaceable>SERVICE</replaceable></arg> <arg choice="plain"><replaceable>OBJECT</replaceable></arg> <arg choice="opt"><replaceable>INTERFACE</replaceable></arg></term> - - <listitem><para>Show interfaces, methods, properties and - signals of the specified object (identified by its path) on - the specified service. If the interface argument is passed, the - output is limited to members of the specified - interface.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>call</command> <arg choice="plain"><replaceable>SERVICE</replaceable></arg> <arg choice="plain"><replaceable>OBJECT</replaceable></arg> <arg choice="plain"><replaceable>INTERFACE</replaceable></arg> <arg choice="plain"><replaceable>METHOD</replaceable></arg> <arg choice="opt"><replaceable>SIGNATURE</replaceable> <arg choice="opt" rep="repeat"><replaceable>ARGUMENT</replaceable></arg></arg></term> - - <listitem><para>Invoke a method and show the response. Takes a - service name, object path, interface name and method name. If - parameters shall be passed to the method call, a signature - string is required, followed by the arguments, individually - formatted as strings. For details on the formatting used, see - below. To suppress output of the returned data, use the - <option>--quiet</option> option.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>get-property</command> <arg choice="plain"><replaceable>SERVICE</replaceable></arg> <arg choice="plain"><replaceable>OBJECT</replaceable></arg> <arg choice="plain"><replaceable>INTERFACE</replaceable></arg> <arg choice="plain" rep="repeat"><replaceable>PROPERTY</replaceable></arg></term> - - <listitem><para>Retrieve the current value of one or more - object properties. Takes a service name, object path, - interface name and property name. Multiple properties may be - specified at once, in which case their values will be shown one - after the other, separated by newlines. The output is, by - default, in terse format. Use <option>--verbose</option> for a - more elaborate output format.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>set-property</command> <arg choice="plain"><replaceable>SERVICE</replaceable></arg> <arg choice="plain"><replaceable>OBJECT</replaceable></arg> <arg choice="plain"><replaceable>INTERFACE</replaceable></arg> <arg choice="plain"><replaceable>PROPERTY</replaceable></arg> <arg choice="plain"><replaceable>SIGNATURE</replaceable></arg> <arg choice="plain" rep="repeat"><replaceable>ARGUMENT</replaceable></arg></term> - - <listitem><para>Set the current value of an object - property. Takes a service name, object path, interface name, - property name, property signature, followed by a list of - parameters formatted as strings.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>help</command></term> - - <listitem><para>Show command syntax help.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Parameter Formatting</title> - - <para>The <command>call</command> and - <command>set-property</command> commands take a signature string - followed by a list of parameters formatted as string (for details - on D-Bus signature strings, see the <ulink - url="http://dbus.freedesktop.org/doc/dbus-specification.html#type-system">Type - system chapter of the D-Bus specification</ulink>). For simple - types, each parameter following the signature should simply be the - parameter's value formatted as string. Positive boolean values may - be formatted as <literal>true</literal>, <literal>yes</literal>, - <literal>on</literal>, or <literal>1</literal>; negative boolean - values may be specified as <literal>false</literal>, - <literal>no</literal>, <literal>off</literal>, or - <literal>0</literal>. For arrays, a numeric argument for the - number of entries followed by the entries shall be specified. For - variants, the signature of the contents shall be specified, - followed by the contents. For dictionaries and structs, the - contents of them shall be directly specified.</para> - - <para>For example, - <programlisting>s jawoll</programlisting> is the formatting - of a single string <literal>jawoll</literal>.</para> - - <para> - <programlisting>as 3 hello world foobar</programlisting> - is the formatting of a string array with three entries, - <literal>hello</literal>, <literal>world</literal> and - <literal>foobar</literal>.</para> - - <para> - <programlisting>a{sv} 3 One s Eins Two u 2 Yes b true</programlisting> - is the formatting of a dictionary - array that maps strings to variants, consisting of three - entries. The string <literal>One</literal> is assigned the - string <literal>Eins</literal>. The string - <literal>Two</literal> is assigned the 32-bit unsigned - integer 2. The string <literal>Yes</literal> is assigned a - positive boolean.</para> - - <para>Note that the <command>call</command>, - <command>get-property</command>, <command>introspect</command> - commands will also generate output in this format for the returned - data. Since this format is sometimes too terse to be easily - understood, the <command>call</command> and - <command>get-property</command> commands may generate a more - verbose, multi-line output when passed the - <option>--verbose</option> option.</para> - </refsect1> - - <refsect1> - <title>Examples</title> - - <example> - <title>Write and Read a Property</title> - - <para>The following two commands first write a property and then - read it back. The property is found on the - <literal>/org/freedesktop/systemd1</literal> object of the - <literal>org.freedesktop.systemd1</literal> service. The name of - the property is <literal>LogLevel</literal> on the - <literal>org.freedesktop.systemd1.Manager</literal> - interface. The property contains a single string:</para> - - <programlisting># busctl set-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel s debug -# busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel -s "debug"</programlisting> - - </example> - - <example> - <title>Terse and Verbose Output</title> - - <para>The following two commands read a property that contains - an array of strings, and first show it in terse format, followed - by verbose format:</para> - - <programlisting>$ busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment -as 2 "LANG=en_US.UTF-8" "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin" -$ busctl get-property --verbose org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment -ARRAY "s" { - STRING "LANG=en_US.UTF-8"; - STRING "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"; -};</programlisting> - </example> - - <example> - <title>Invoking a Method</title> - - <para>The following command invokes the - <literal>StartUnit</literal> method on the - <literal>org.freedesktop.systemd1.Manager</literal> - interface of the - <literal>/org/freedesktop/systemd1</literal> object - of the <literal>org.freedesktop.systemd1</literal> - service, and passes it two strings - <literal>cups.service</literal> and - <literal>replace</literal>. As a result of the method - call, a single object path parameter is received and - shown:</para> - - <programlisting># busctl call org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager StartUnit ss "cups.service" "replace" -o "/org/freedesktop/systemd1/job/42684"</programlisting> - </example> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry project='dbus'><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <ulink url="http://freedesktop.org/wiki/Software/dbus">D-Bus</ulink>, - <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>wireshark</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> -</refentry> diff --git a/man/coredump.conf.xml b/man/coredump.conf.xml deleted file mode 100644 index 4f95680a3a..0000000000 --- a/man/coredump.conf.xml +++ /dev/null @@ -1,161 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2014 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="coredump.conf" conditional="ENABLE_COREDUMP" - xmlns:xi="http://www.w3.org/2001/XInclude"> - <refentryinfo> - <title>coredump.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>coredump.conf</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>coredump.conf</refname> - <refname>coredump.conf.d</refname> - <refpurpose>Core dump storage configuration files</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/etc/systemd/coredump.conf</filename></para> - <para><filename>/etc/systemd/coredump.conf.d/*.conf</filename></para> - <para><filename>/run/systemd/coredump.conf.d/*.conf</filename></para> - <para><filename>/usr/lib/systemd/coredump.conf.d/*.conf</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>These files configure the behavior of - <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - a handler for core dumps invoked by the kernel. Whether <command>systemd-coredump</command> is used - is determined by the kernel's - <varname>kernel.core_pattern</varname> <citerefentry project='man-pages'><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry> - setting. See - <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry> - and - <citerefentry project='man-pages'><refentrytitle>core</refentrytitle><manvolnum>5</manvolnum></citerefentry> - pages for the details.</para> - </refsect1> - - <xi:include href="standard-conf.xml" xpointer="main-conf" /> - - <refsect1> - <title>Options</title> - - <para>All options are configured in the - <literal>[Coredump]</literal> section:</para> - - <variablelist> - - <varlistentry> - <term><varname>Storage=</varname></term> - - <listitem><para>Controls where to store cores. One of - <literal>none</literal>, <literal>external</literal>, - <literal>journal</literal>, and <literal>both</literal>. When - <literal>none</literal>, the core dumps will be logged but not - stored permanently. When <literal>external</literal> (the - default), cores will be stored in <filename>/var/lib/systemd/coredump</filename>. - When <literal>journal</literal>, cores will be stored in - the journal and rotated following normal journal - rotation patterns. When <literal>both</literal>, cores - will be stored in both locations.</para> - - <para>When cores are stored in the journal, they might be - compressed following journal compression settings, see - <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - When cores are stored externally, they will be compressed - by default, see below.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Compress=</varname></term> - - <listitem><para>Controls compression for external - storage. Takes a boolean argument, which defaults to - <literal>yes</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>ProcessSizeMax=</varname></term> - - <listitem><para>The maximum size in bytes of a core - which will be processed. Core dumps exceeding this size - will be logged, but the backtrace will not be generated - and the core will not be stored.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>ExternalSizeMax=</varname></term> - <term><varname>JournalSizeMax=</varname></term> - - <listitem><para>The maximum (uncompressed) size in bytes of a - core to be saved.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>MaxUse=</varname></term> - <term><varname>KeepFree=</varname></term> - - <listitem><para>Enforce limits on the disk space taken up by - externally stored core dumps. <option>MaxUse=</option> makes - sure that old core dumps are removed as soon as the total disk - space taken up by core dumps grows beyond this limit (defaults - to 10% of the total disk size). <option>KeepFree=</option> - controls how much disk space to keep free at least (defaults - to 15% of the total disk size). Note that the disk space used - by core dumps might temporarily exceed these limits while - core dumps are processed. Note that old core dumps are also - removed based on time via - <citerefentry><refentrytitle>systemd-tmpfiles</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Set - either value to 0 to turn off size-based - clean-up.</para></listitem> - </varlistentry> - </variablelist> - - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-tmpfiles</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/coredumpctl.xml b/man/coredumpctl.xml deleted file mode 100644 index abc245be5e..0000000000 --- a/man/coredumpctl.xml +++ /dev/null @@ -1,259 +0,0 @@ -<?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="coredumpctl" conditional='ENABLE_COREDUMP' - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>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>coredumpctl</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>coredumpctl</refname> - <refpurpose>Retrieve and process saved core dumps and metadata</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>coredumpctl</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="req">COMMAND</arg> - <arg choice="opt" rep="repeat">PID|COMM|EXE|MATCH</arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>coredumpctl</command> is a tool that can be used to retrieve and process core - dumps and metadata which were saved by - <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>. - </para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - - <varlistentry> - <term><option>--no-legend</option></term> - - <listitem><para>Do not print column headers.</para></listitem> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="no-pager" /> - - <varlistentry> - <term><option>-1</option></term> - - <listitem><para>Show information of a single core dump only, instead of listing - all known core dumps.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-F</option> <replaceable>FIELD</replaceable></term> - <term><option>--field=</option><replaceable>FIELD</replaceable></term> - - <listitem><para>Print all possible data values the specified - field takes in matching core dump entries of the - journal.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-o</option> <replaceable>FILE</replaceable></term> - <term><option>--output=</option><replaceable>FILE</replaceable></term> - - <listitem><para>Write the core to <option>FILE</option>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-D</option> <replaceable>DIR</replaceable></term> - <term><option>--directory=</option><replaceable>DIR</replaceable></term> - - <listitem><para>Use the journal files in the specified <option>DIR</option>. - </para></listitem> - </varlistentry> - - </variablelist> - </refsect1> - - <refsect1> - <title>Commands</title> - - <para>The following commands are understood:</para> - - <variablelist> - <varlistentry> - <term><command>list</command></term> - - <listitem><para>List core dumps captured in the journal - matching specified characteristics. If no command is - specified, this is the implied default.</para> - - <para>It's worth noting that different restrictions apply to - data saved in the journal and core dump files saved in - <filename>/var/lib/systemd/coredump</filename>, see overview in - <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>. - Thus it may very well happen that a particular core dump is still listed - in the journal while its corresponding core dump file has already been - removed.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>info</command></term> - - <listitem><para>Show detailed information about core dumps - captured in the journal.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>dump</command></term> - - <listitem><para>Extract the last core dump matching specified - characteristics. The core dump will be written on standard - output, unless an output file is specified with - <option>--output=</option>. </para></listitem> - </varlistentry> - - <varlistentry> - <term><command>gdb</command></term> - - <listitem><para>Invoke the GNU debugger on the last core dump - matching specified characteristics. </para></listitem> - </varlistentry> - - </variablelist> - - </refsect1> - - <refsect1> - <title>Matching</title> - - <para>A match can be:</para> - - <variablelist> - <varlistentry> - <term><replaceable>PID</replaceable></term> - - <listitem><para>Process ID of the - process that dumped - core. An integer.</para></listitem> - </varlistentry> - - <varlistentry> - <term><replaceable>COMM</replaceable></term> - - <listitem><para>Name of the executable (matches - <option>COREDUMP_COMM=</option>). Must not contain slashes. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><replaceable>EXE</replaceable></term> - - <listitem><para>Path to the executable (matches - <option>COREDUMP_EXE=</option>). Must contain at least one - slash. </para></listitem> - </varlistentry> - - <varlistentry> - <term><replaceable>MATCH</replaceable></term> - - <listitem><para>General journalctl predicates (see - <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>). - Must contain an equal sign. </para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Exit status</title> - <para>On success, 0 is returned; otherwise, a non-zero failure - code is returned. Not finding any matching core dumps is treated as - failure. - </para> - </refsect1> - - <refsect1> - <title>Examples</title> - - <example> - <title>List all the core dumps of a program named foo</title> - - <programlisting># coredumpctl list foo</programlisting> - </example> - - <example> - <title>Invoke gdb on the last core dump</title> - - <programlisting># coredumpctl gdb</programlisting> - </example> - - <example> - <title>Show information about a process that dumped core, - matching by its PID 6654</title> - - <programlisting># coredumpctl info 6654</programlisting> - </example> - - <example> - <title>Extract the last core dump of /usr/bin/bar to a file named - <filename noindex="true">bar.coredump</filename></title> - - <programlisting># coredumpctl -o bar.coredump dump /usr/bin/bar</programlisting> - </example> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>coredump.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/crypttab.xml b/man/crypttab.xml deleted file mode 100644 index 1de834a045..0000000000 --- a/man/crypttab.xml +++ /dev/null @@ -1,416 +0,0 @@ -<?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" conditional='HAVE_LIBCRYPTSETUP'> - - <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 <literal>#</literal> - 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>Setting up encrypted block devices using this file supports - three encryption modes: LUKS, TrueCrypt and plain. See - <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for more information about each mode. When no mode is specified in - the options field and the block device contains a LUKS signature, - it is opened as a LUKS device; otherwise, it is assumed to be in - raw dm-crypt (plain mode) format.</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 file, or a specification of a block device via - <literal>UUID=</literal> followed by the UUID.</para> - - <para>The third field specifies the encryption password. If the - field is not present or the password is set to - <literal>none</literal> or <literal>-</literal>, the password has - to be manually entered during system boot. Otherwise, the field is - interpreted as a absolute 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 class='fstab-options'> - - <varlistentry> - <term><option>discard</option></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><option>cipher=</option></term> - - <listitem><para>Specifies the cipher to use. See - <citerefentry project='die-net'><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><option>hash=</option></term> - - <listitem><para>Specifies the hash to use for password - hashing. See - <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for possible values and the default value of this - option.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>header=</option></term> - - <listitem><para>Use a detached (separated) metadata device or - file where the LUKS header is stored. This option is only - relevant for LUKS devices. See - <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for possible values and the default value of this - option.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>offset=</option></term> - - <listitem><para>Start offset in the backend device, in 512-byte sectors. - This option is only relevant for plain devices. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>skip=</option></term> - - <listitem><para>How many 512-byte sectors of the encrypted data to skip - at the beginning. This is different from the <option>--offset</option> - option with respect to the sector numbers used in initialization vector - (IV) calculation. Using <option>--offset</option> will shift the IV - calculation by the same negative amount. Hence, if <option>--offset n</option> is given, - sector n will get a sector number of 0 for the IV calculation. - Using <option>--skip</option> causes sector n to also be the first - sector of the mapped device, but with its number for IV generation being n.</para> - - <para>This option is only relevant for plain devices.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>keyfile-offset=</option></term> - - <listitem><para>Specifies the number of bytes to skip at the - start of the key file. See - <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for possible values and the default value of this - option.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>keyfile-size=</option></term> - - <listitem><para>Specifies the maximum number of bytes to read - from the key file. See - <citerefentry project='die-net'><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 key file - size is then given by the key size.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>key-slot=</option></term> - - <listitem><para>Specifies the key slot to compare the - passphrase or key against. If the key slot does not match the - given passphrase or key, but another would, the setup of the - device will fail regardless. This option implies - <option>luks</option>. See - <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for possible values. The default is to try all key slots in - sequential order.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>luks</option></term> - - <listitem><para>Force LUKS mode. When this mode is used, the - following options are ignored since they are provided by the - LUKS header on the device: <option>cipher=</option>, - <option>hash=</option>, - <option>size=</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>noauto</option></term> - - <listitem><para>This device will not be automatically unlocked - on boot.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>nofail</option></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 - does not show up.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>plain</option></term> - - <listitem><para>Force plain encryption mode.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>read-only</option></term><term><option>readonly</option></term> - - <listitem><para>Set up the encrypted block device in read-only - mode.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>size=</option></term> - - <listitem><para>Specifies the key size in bits. See - <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for possible values and the default value of this - option.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>swap</option></term> - - <listitem><para>The encrypted block device will be used as a - swap device, and will be formatted accordingly after setting - up the encrypted block device, with - <citerefentry project='man-pages'><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>. - This option implies <option>plain</option>.</para> - - <para>WARNING: Using the <option>swap</option> 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><option>tcrypt</option></term> - - <listitem><para>Use TrueCrypt encryption mode. When this mode - is used, the following options are ignored since they are - provided by the TrueCrypt header on the device or do not - apply: - <option>cipher=</option>, - <option>hash=</option>, - <option>keyfile-offset=</option>, - <option>keyfile-size=</option>, - <option>size=</option>.</para> - - <para>When this mode is used, the passphrase is read from the - key file given in the third field. Only the first line of this - file is read, excluding the new line character.</para> - - <para>Note that the TrueCrypt format uses both passphrase and - key files to derive a password for the volume. Therefore, the - passphrase and all key files need to be provided. Use - <option>tcrypt-keyfile=</option> to provide the absolute path - to all key files. When using an empty passphrase in - combination with one or more key files, use - <literal>/dev/null</literal> as the password file in the third - field.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>tcrypt-hidden</option></term> - - <listitem><para>Use the hidden TrueCrypt volume. This option - implies <option>tcrypt</option>.</para> - - <para>This will map the hidden volume that is inside of the - volume provided in the second field. Please note that there is - no protection for the hidden volume if the outer volume is - mounted instead. See - <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for more information on this limitation.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>tcrypt-keyfile=</option></term> - - <listitem><para>Specifies the absolute path to a key file to - use for a TrueCrypt volume. This implies - <option>tcrypt</option> and can be used more than once to - provide several key files.</para> - - <para>See the entry for <option>tcrypt</option> on the - behavior of the passphrase and key files when using TrueCrypt - encryption mode.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>tcrypt-system</option></term> - - <listitem><para>Use TrueCrypt in system encryption mode. This - option implies <option>tcrypt</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>timeout=</option></term> - - <listitem><para>Specifies the timeout for querying for a - password. If no unit is specified, seconds is used. Supported - units are s, ms, us, min, h, d. A timeout of 0 waits - indefinitely (which is the default).</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>x-systemd.device-timeout=</option></term> - - <listitem><para>Specifies how long systemd should wait for a - device to show up before giving up on the entry. The argument - is a time in seconds or explicitly specified units of - <literal>s</literal>, - <literal>min</literal>, - <literal>h</literal>, - <literal>ms</literal>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>tmp</option></term> - - <listitem><para>The encrypted block device will be prepared - for using it as <filename>/tmp</filename>; it will be - formatted using - <citerefentry project='man-pages'><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry>. - This option implies <option>plain</option>.</para> - - <para>WARNING: Using the <option>tmp</option> 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><option>tries=</option></term> - - <listitem><para>Specifies the maximum number of times the user - is queried for a password. The default is 3. If set to 0, the - user is queried for a password indefinitely.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>verify</option></term> - - <listitem><para> If the encryption password is read from - console, it has to be entered twice to prevent - typos.</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 four encrypted block devices. One using LUKS for - normal storage, another one for usage as a swap device and two - TrueCrypt volumes.</para> - - <programlisting>luks UUID=2505567a-9e27-4efe-a4d5-15ad146c258b -swap /dev/sda7 /dev/urandom swap -truecrypt /dev/sda2 /etc/container_password tcrypt -hidden /mnt/tc_hidden /dev/null tcrypt-hidden,tcrypt-keyfile=/etc/keyfile</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 project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/dnssec-trust-anchors.d.xml b/man/dnssec-trust-anchors.d.xml deleted file mode 100644 index 4bdc167f79..0000000000 --- a/man/dnssec-trust-anchors.d.xml +++ /dev/null @@ -1,200 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2016 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="dnssec-trust-anchors.d" conditional='ENABLE_RESOLVED' - xmlns:xi="http://www.w3.org/2001/XInclude"> - <refentryinfo> - <title>dnssec-trust-anchors.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>dnssec-trust-anchors.d</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>dnssec-trust-anchors.d</refname> - <refname>systemd.positive</refname> - <refname>systemd.negative</refname> - <refpurpose>DNSSEC trust anchor configuration files</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/etc/dnssec-trust-anchors.d/*.positive</filename></para> - <para><filename>/run/dnssec-trust-anchors.d/*.positive</filename></para> - <para><filename>/usr/lib/dnssec-trust-anchors.d/*.positive</filename></para> - <para><filename>/etc/dnssec-trust-anchors.d/*.negative</filename></para> - <para><filename>/run/dnssec-trust-anchors.d/*.negative</filename></para> - <para><filename>/usr/lib/dnssec-trust-anchors.d/*.negative</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>The DNSSEC trust anchor configuration files define positive - and negative trust anchors - <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - bases DNSSEC integrity proofs on.</para> - </refsect1> - - <refsect1> - <title>Positive Trust Anchors</title> - - <para>Positive trust anchor configuration files contain DNSKEY and - DS resource record definitions to use as base for DNSSEC integrity - proofs. See <ulink - url="https://tools.ietf.org/html/rfc4035#section-4.4">RFC 4035, - Section 4.4</ulink> for more information about DNSSEC trust - anchors.</para> - - <para>Positive trust anchors are read from files with the suffix - <filename>.positive</filename> located in - <filename>/etc/dnssec-trust-anchors.d/</filename>, - <filename>/run/dnssec-trust-anchors.d/</filename> and - <filename>/usr/lib/dnssec-trust-anchors.d/</filename>. These - directories are searched in the specified order, and a trust - anchor file of the same name in an earlier path overrides a trust - anchor files in a later path. To disable a trust anchor file - shipped in <filename>/usr/lib/dnssec-trust-anchors.d/</filename> - it is sufficient to provide an identically-named file in - <filename>/etc/dnssec-trust-anchors.d/</filename> or - <filename>/run/dnssec-trust-anchors.d/</filename> that is either - empty or a symlink to <filename>/dev/null</filename> ("masked").</para> - - <para>Positive trust anchor files are simple text files resembling - DNS zone files, as documented in <ulink - url="https://tools.ietf.org/html/rfc1035#section-5">RFC 1035, Section - 5</ulink>. One DS or DNSKEY resource record may be listed per - line. Empty lines and lines starting with a semicolon - (<literal>;</literal>) are ignored and considered comments. A DS - resource record is specified like in the following example:</para> - - <programlisting>. IN DS 19036 8 2 49aac11d7b6f6446702e54a1607371607a1a41855200fd2ce1cdde32f24e8fb5</programlisting> - - <para>The first word specifies the domain, use - <literal>.</literal> for the root domain. The domain may be - specified with or without trailing dot, which is considered - equivalent. The second word must be <literal>IN</literal> the - third word <literal>DS</literal>. The following words specify the - key tag, signature algorithm, digest algorithm, followed by the - hex-encoded key fingerprint. See <ulink - url="https://tools.ietf.org/html/rfc4034#section-5">RFC 4034, - Section 5</ulink> for details about the precise syntax and meaning - of these fields.</para> - - <para>Alternatively, DNSKEY resource records may be used to define - trust anchors, like in the following example:</para> - - <programlisting>. IN DNSKEY 257 3 8 AwEAAagAIKlVZrpC6Ia7gEzahOR+9W29euxhJhVVLOyQbSEW0O8gcCjFFVQUTf6v58fLjwBd0YI0EzrAcQqBGCzh/RStIoO8g0NfnfL2MTJRkxoXbfDaUeVPQuYEhg37NZWAJQ9VnMVDxP/VHL496M/QZxkjf5/Efucp2gaDX6RS6CXpoY68LsvPVjR0ZSwzz1apAzvN9dlzEheX7ICJBBtuA6G3LQpzW5hOA2hzCTMjJPJ8LbqF6dsV6DoBQzgul0sGIcGOYl7OyQdXfZ57relSQageu+ipAdTTJ25AsRTAoub8ONGcLmqrAmRLKBP1dfwhYB4N7knNnulqQxA+Uk1ihz0=</programlisting> - - <para>The first word specifies the domain again, the second word - must be <literal>IN</literal>, followed by - <literal>DNSKEY</literal>. The subsequent words encode the DNSKEY - flags, protocol and algorithm fields, followed by the key data - encoded in Base64. See <ulink - url="https://tools.ietf.org/html/rfc4034#section-2">RFC 4034, - Section 2</ulink> for details about the precise syntax and meaning - of these fields.</para> - - <para>If multiple DS or DNSKEY records are defined for the same - domain (possibly even in different trust anchor files), all keys - are used and are considered equivalent as base for DNSSEC - proofs.</para> - - <para>Note that <filename>systemd-resolved</filename> will - automatically use a built-in trust anchor key for the Internet - root domain if no positive trust anchors are defined for the root - domain. In most cases it is hence unnecessary to define an - explicit key with trust anchor files. The built-in key is disabled - as soon as at least one trust anchor key for the root domain is - defined in trust anchor files.</para> - - <para>It is generally recommended to encode trust anchors in DS - resource records, rather than DNSKEY resource records.</para> - - <para>If a trust anchor specified via a DS record is found revoked - it is automatically removed from the trust anchor database for the - runtime. See <ulink url="https://tools.ietf.org/html/rfc5011">RFC - 5011</ulink> for details about revoked trust anchors. Note that - <filename>systemd-resolved</filename> will not update its trust - anchor database from DNS servers automatically. Instead, it is - recommended to update the resolver software or update the new - trust anchor via adding in new trust anchor files.</para> - - <para>The current DNSSEC trust anchor for the Internet's root - domain is available at the <ulink - url="https://data.iana.org/root-anchors/root-anchors.xml">IANA - Trust Anchor and Keys</ulink> page.</para> - </refsect1> - - <refsect1> - <title>Negative Trust Anchors</title> - - <para>Negative trust anchors define domains where DNSSEC - validation shall be turned off. Negative trust anchor files are - found at the same location as positive trust anchor files, and - follow the same overriding rules. They are text files with the - <filename>.negative</filename> suffix. Empty lines and lines whose - first character is <literal>;</literal> are ignored. Each line - specifies one domain name where DNSSEC validation shall be - disabled on.</para> - - <para>Negative trust anchors are useful to support private DNS - subtrees that are not referenced from the Internet DNS hierarchy, - and not signed.</para> - - <para><ulink url="https://tools.ietf.org/html/rfc7646">RFC - 7646</ulink> for details on negative trust anchors.</para> - - <para>If no negative trust anchor files are configured a built-in - set of well-known private DNS zone domains is used as negative - trust anchors.</para> - - <para>It is also possibly to define per-interface negative trust - anchors using the <varname>DNSSECNegativeTrustAnchors=</varname> - setting in - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> - files.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/glib-event-glue.c b/man/glib-event-glue.c deleted file mode 100644 index 8f3168d0ea..0000000000 --- a/man/glib-event-glue.c +++ /dev/null @@ -1,68 +0,0 @@ -/*** - Copyright 2014 Tom Gundersen - - Permission is hereby granted, free of charge, to any person - obtaining a copy of this software and associated documentation files - (the "Software"), to deal in the Software without restriction, - including without limitation the rights to use, copy, modify, merge, - publish, distribute, sublicense, and/or sell copies of the Software, - and to permit persons to whom the Software is furnished to do so, - subject to the following conditions: - - The above copyright notice and this permission notice shall be - included in all copies or substantial portions of the Software. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, - EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF - MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND - NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS - BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN - ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN - CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - SOFTWARE. -***/ - -#include <stdlib.h> - -typedef struct SDEventSource { - GSource source; - GPollFD pollfd; - sd_event *event; -} SDEventSource; - -static gboolean event_prepare(GSource *source, gint *timeout_) { - return sd_event_prepare(((SDEventSource *)source)->event) > 0; -} - -static gboolean event_check(GSource *source) { - return sd_event_wait(((SDEventSource *)source)->event, 0) > 0; -} - -static gboolean event_dispatch(GSource *source, GSourceFunc callback, gpointer user_data) { - return sd_event_dispatch(((SDEventSource *)source)->event) > 0; -} - -static void event_finalize(GSource *source) { - sd_event_unref(((SDEventSource *)source)->event); -} - -static GSourceFuncs event_funcs = { - .prepare = event_prepare, - .check = event_check, - .dispatch = event_dispatch, - .finalize = event_finalize, -}; - -GSource *g_sd_event_create_source(sd_event *event) { - SDEventSource *source; - - source = (SDEventSource *)g_source_new(&event_funcs, sizeof(SDEventSource)); - - source->event = sd_event_ref(event); - source->pollfd.fd = sd_event_get_fd(event); - source->pollfd.events = G_IO_IN | G_IO_HUP | G_IO_ERR; - - g_source_add_poll((GSource *)source, &source->pollfd); - - return (GSource *)source; -} diff --git a/man/halt.xml b/man/halt.xml deleted file mode 100644 index e3fa60a915..0000000000 --- a/man/halt.xml +++ /dev/null @@ -1,176 +0,0 @@ -<?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" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <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</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - </cmdsynopsis> - <cmdsynopsis> - <command>poweroff</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - </cmdsynopsis> - <cmdsynopsis> - <command>reboot</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - </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> - - <xi:include href="standard-options.xml" xpointer="help-text" /> - </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. Do - not 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, do not - actually halt, power-off, reboot.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-d</option></term> - <term><option>--no-wtmp</option></term> - - <listitem><para>Do not write wtmp shutdown - entry.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-n</option></term> - <term><option>--no-sync</option></term> - - <listitem><para>Don't sync hard disks/storage media before - halt, power-off, reboot.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--no-wall</option></term> - - <listitem><para>Do not 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 project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/hostnamectl.xml b/man/hostnamectl.xml deleted file mode 100644 index 60004e9d04..0000000000 --- a/man/hostnamectl.xml +++ /dev/null @@ -1,260 +0,0 @@ -<?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" conditional='ENABLE_HOSTNAMED' - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <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</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="req">COMMAND</arg> - </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 hostnames: 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 is a fallback - value received from network configuration. If a static hostname is - set, and is valid (something other than localhost), then the - transient hostname is not used.</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 hostname is stored in - <filename>/etc/hostname</filename>, see - <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more information. The pretty hostname, chassis type, and icon - name are stored in <filename>/etc/machine-info</filename>, see - <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> - - <para>Use - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - to initialize the system host name for mounted (but not booted) - system images.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--no-ask-password</option></term> - - <listitem><para>Do not query the user for authentication for - privileged operations.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--static</option></term> - <term><option>--transient</option></term> - <term><option>--pretty</option></term> - - <listitem><para>If <command>status</command> is used (or no - explicit command is given) and one of those fields is given, - <command>hostnamectl</command> will print out just this - selected hostname.</para> - - <para>If used with <command>set-hostname</command>, only the - selected hostname(s) will be updated. When more than one of - those options is used, all the specified hostnames will be - updated. </para></listitem> - </varlistentry> - - <xi:include href="user-system-options.xml" xpointer="host" /> - <xi:include href="user-system-options.xml" xpointer="machine" /> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </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 <replaceable>NAME</replaceable></command></term> - - <listitem><para>Set the system hostname to - <replaceable>NAME</replaceable>. 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 hostname will be simplified in regards - to the character set used before the latter are updated. This - is done by replacing spaces with <literal>-</literal> 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.</para> - - <para>Pass the empty string <literal></literal> as the - hostname to reset the selected hostnames to their default - (usually <literal>localhost</literal>).</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>set-icon-name <replaceable>NAME</replaceable></command></term> - - <listitem><para>Set the system icon name to - <replaceable>NAME</replaceable>. 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>.</para> - - <para>Pass an empty string to reset the icon name to the - default value, which is determined from chassis type (see - below) and possibly other parameters.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>set-chassis <replaceable>TYPE</replaceable></command></term> - - <listitem><para>Set the chassis type to - <replaceable>TYPE</replaceable>. The chassis type is used by - some graphical applications to visualize the host or alter - user interaction. Currently, the following chassis types are - defined: - <literal>desktop</literal>, - <literal>laptop</literal>, - <literal>server</literal>, - <literal>tablet</literal>, - <literal>handset</literal>, - <literal>watch</literal>, - <literal>embedded</literal>, - as well as the special chassis types - <literal>vm</literal> and - <literal>container</literal> for virtualized systems that lack - an immediate physical chassis.</para> - - <para>Pass an empty string to reset the chassis type to the - default value which is determined from the firmware and - possibly other parameters.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>set-deployment <replaceable>ENVIRONMENT</replaceable></command></term> - - <listitem><para>Set the deployment environment description. - <replaceable>ENVIRONMENT</replaceable> must be a single word - without any control characters. One of the following is - suggested: - <literal>development</literal>, - <literal>integration</literal>, - <literal>staging</literal>, - <literal>production</literal>. - </para> - - <para>Pass an empty string to reset to the default empty - value.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>set-location <replaceable>LOCATION</replaceable></command></term> - - <listitem><para>Set the location string for the system, if it - is known. <replaceable>LOCATION</replaceable> should be a - human-friendly, free-form string describing the physical - location of the system, if it is known and applicable. This - may be as generic as <literal>Berlin, Germany</literal> or as - specific as <literal>Left Rack, 2nd Shelf</literal>.</para> - - <para>Pass an empty string to reset to the default empty - value.</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>, - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/hwdb.xml b/man/hwdb.xml deleted file mode 100644 index 2b1e60fb22..0000000000 --- a/man/hwdb.xml +++ /dev/null @@ -1,85 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - -<refentry id="hwdb" conditional="ENABLE_HWDB"> - <refentryinfo> - <title>hwdb</title> - <productname>systemd</productname> - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Kay</firstname> - <surname>Sievers</surname> - <email>kay@vrfy.org</email> - </author> - <author> - <contrib>Developer</contrib> - <firstname>Tom</firstname> - <surname>Gundersen</surname> - <email>teg@jklm.no</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>hwdb</refentrytitle> - <manvolnum>7</manvolnum> - </refmeta> - - <refnamediv> - <refname>hwdb</refname> - <refpurpose>Hardware Database</refpurpose> - </refnamediv> - - <refsect1><title>Description</title> - <para>The hardware database is a key-value store for associating modalias-like keys to - udev-property-like values. It is used primarily by udev to add the relevant properties - to matching devices, but it can also be queried directly.</para> - </refsect1> - - <refsect1><title>Hardware Database Files</title> - <para>The hwdb files are read from the files located in the - system hwdb directory <filename>/usr/lib/udev/hwdb.d</filename> and - the local administration directory <filename>/etc/udev/hwdb.d</filename>. - All hwdb files are collectively sorted and processed in lexical order, - regardless of the directories in which they live. However, files with - identical filenames replace each other. Files in <filename>/etc</filename> - have the highest priority and take precedence over files with the same - name in <filename>/usr/lib</filename>. This can be used to override a - system-supplied hwdb file with a local file if needed; - a symlink in <filename>/etc</filename> with the same name as a hwdb file in - <filename>/usr/lib</filename>, pointing to <filename>/dev/null</filename>, - disables the hwdb file entirely. hwdb files must have the extension - <filename>.hwdb</filename>; other extensions are ignored.</para> - - <para>The hwdb file contains data records consisting of matches and - associated key-value pairs. Every record in the hwdb starts with one or - more match strings, specifying a shell glob to compare the database - lookup string against. Multiple match lines are specified in additional - consecutive lines. Every match line is compared individually, and they are - combined by OR. Every match line must start at the first character of - the line.</para> - - <para>The match lines are followed by one or more key-value pair lines, which - are recognized by a leading space character. The key name and value are separated - by <literal>=</literal>. An empty line signifies the end - of a record. Lines beginning with <literal>#</literal> are ignored.</para> - - <para>The content of all hwdb files is read by - <citerefentry><refentrytitle>systemd-hwdb</refentrytitle><manvolnum>8</manvolnum></citerefentry> - and compiled to a binary database located at <filename>/etc/udev/hwdb.bin</filename>, - or alternatively <filename>/usr/lib/udev/hwdb.bin</filename> if you want ship the compiled - database in an immutable image. - During runtime, only the binary database is used.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry> - <refentrytitle>systemd-hwdb</refentrytitle><manvolnum>8</manvolnum> - </citerefentry> - </para> - </refsect1> -</refentry> diff --git a/man/journal-remote.conf.xml b/man/journal-remote.conf.xml deleted file mode 100644 index 2d345963d9..0000000000 --- a/man/journal-remote.conf.xml +++ /dev/null @@ -1,121 +0,0 @@ -<?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 2015 Chris Morgan - - 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="journal-remote.conf" conditional='HAVE_MICROHTTPD' - xmlns:xi="http://www.w3.org/2001/XInclude"> - <refentryinfo> - <title>journal-remote.conf</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Chris</firstname> - <surname>Morgan</surname> - <email>chmorgan@gmail.com</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>journal-remote.conf</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>journal-remote.conf</refname> - <refname>journal-remote.conf.d</refname> - <refpurpose>Journal remote service configuration files</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/etc/systemd/journal-remote.conf</filename></para> - <para><filename>/etc/systemd/journald.conf.d/*.conf</filename></para> - <para><filename>/run/systemd/journald.conf.d/*.conf</filename></para> - <para><filename>/usr/lib/systemd/journald.conf.d/*.conf</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>These files configure various parameters of the systemd-remote-journal - application, - <citerefentry><refentrytitle>systemd-journal-remote</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> - </refsect1> - - <xi:include href="standard-conf.xml" xpointer="main-conf" /> - - <refsect1> - <title>Options</title> - - <para>All options are configured in the - <literal>[Remote]</literal> section:</para> - - <variablelist> - <varlistentry> - <term><varname>Seal=</varname></term> - - <listitem><para>Periodically sign the data in the journal using Forward Secure Sealing. - </para></listitem> - </varlistentry> - - - <varlistentry> - <term><varname>SplitMode=</varname></term> - - <listitem><para>One of <literal>host</literal> or <literal>none</literal>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>ServerKeyFile=</varname></term> - - <listitem><para>SSL key in PEM format.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>ServerCertificateFile=</varname></term> - - <listitem><para>SSL CA certificate in PEM format.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>TrustedCertificateFile=</varname></term> - - <listitem><para>SSL CA certificate.</para></listitem> - </varlistentry> - - </variablelist> - - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd-journal-remote</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/journalctl.xml b/man/journalctl.xml deleted file mode 100644 index 3efe6ef62a..0000000000 --- a/man/journalctl.xml +++ /dev/null @@ -1,914 +0,0 @@ -<?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" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <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</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="opt" rep="repeat">MATCHES</arg> - </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 parameters, 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, the character <literal>+</literal> may appear - as a separate word between other terms on the command line. This - causes all matches before and after to be 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. Similarly, if a path refers - to a device node then match is added for the kernel name of the - device (<literal>_KERNEL_DEVICE=</literal>). Also, matches for the - kernel names of all the parent devices are added automatically. - Device node paths are not stable across reboots, therefore match - for the current boot id (<literal>_BOOT_ID=</literal>) is - always added as well. Note that only the log entries for - the existing device nodes maybe queried by providing path to - the device node.</para> - - <para>Additional constraints may be added using options - <option>--boot</option>, <option>--unit=</option>, etc., to - further limit what entries will be shown (logical AND).</para> - - <para>Output is interleaved from all accessible journal files, - whether they are rotated or currently being written, and - regardless of whether they belong to the system itself or are - accessible user journals.</para> - - <para>The set of journal files which will be used can be - modified using the <option>--user</option>, - <option>--system</option>, <option>--directory</option>, and - <option>--file</option> options, see below.</para> - - <para>All users are granted access to their private per-user - journals. However, by default, only root and users who are - members of a few special groups are granted access to the system - journal and the journals of other users. Members of the groups - <literal>systemd-journal</literal>, <literal>adm</literal>, and - <literal>wheel</literal> can read all journal files. Note - that the two latter groups traditionally have additional - privileges specified by the distribution. Members of the - <literal>wheel</literal> group can often perform administrative - tasks.</para> - - <para>The output is paged through <command>less</command> by - default, and long lines are "truncated" to screen width. The - hidden part can be viewed by using the left-arrow and - right-arrow keys. Paging can be disabled; see the - <option>--no-pager</option> option and the "Environment" section - below.</para> - - <para>When outputting to a tty, lines are colored according to - priority: lines of level ERROR and higher are colored red; lines - of level NOTICE and higher are highlighted; other lines are - displayed normally.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--no-full</option></term> - <term><option>--full</option></term> - <term><option>-l</option></term> - - <listitem><para>Ellipsize fields when they do not fit in - available columns. The default is to show full fields, - allowing them to wrap or be truncated by the pager, if one - is used.</para> - - <para>The old options - <option>-l</option>/<option>--full</option> are not useful - anymore, except to undo <option>--no-full</option>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-a</option></term> - <term><option>--all</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>-f</option></term> - <term><option>--follow</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>-e</option></term> - <term><option>--pager-end</option></term> - - <listitem><para>Immediately jump to the end of the journal - inside the implied pager tool. This implies - <option>-n1000</option> to guarantee that the pager will not - buffer logs of unbounded size. This may be overridden with - an explicit <option>-n</option> with some other numeric - value, while <option>-nall</option> will disable this cap. - Note that this option is only supported for the - <citerefentry project='man-pages'><refentrytitle>less</refentrytitle><manvolnum>1</manvolnum></citerefentry> - pager.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-n</option></term> - <term><option>--lines=</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 is a positive integer or - <literal>all</literal> to disable line limiting. The default - value is 10 if no argument is given.</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>-r</option></term> - <term><option>--reverse</option></term> - - <listitem><para>Reverse output so that the newest entries - are displayed first.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-o</option></term> - <term><option>--output=</option></term> - - <listitem><para>Controls the formatting of the journal - entries that are shown. Takes one of the following - options:</para> - <variablelist> - <varlistentry> - <term> - <option>short</option> - </term> - <listitem> - <para>is the default and generates an output that is - mostly identical to the formatting of classic syslog - files, showing one line per journal entry.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>short-iso</option> - </term> - <listitem> - <para>is very similar, but shows ISO 8601 wallclock - timestamps.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>short-precise</option> - </term> - <listitem> - <para>is very similar, but shows timestamps with full - microsecond precision.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>short-monotonic</option> - </term> - <listitem> - <para>is very similar, but shows monotonic timestamps - instead of wallclock timestamps.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>short-unix</option> - </term> - <listitem> - <para>is very similar, but shows seconds passed since January 1st 1970 UTC instead of wallclock - timestamps ("UNIX time"). The time is shown with microsecond accuracy.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>verbose</option> - </term> - <listitem> - <para>shows the full-structured entry items with all - fields.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>export</option> - </term> - <listitem> - <para>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).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>json</option> - </term> - <listitem> - <para>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).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>json-pretty</option> - </term> - <listitem> - <para>formats entries as JSON data structures, but - formats them in multiple lines in order to make them - more readable by humans.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>json-sse</option> - </term> - <listitem> - <para>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>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>cat</option> - </term> - <listitem> - <para>generates a very terse output, only showing the - actual message of each journal entry with no metadata, - not even a timestamp.</para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--utc</option></term> - - <listitem><para>Express time in Coordinated Universal Time - (UTC).</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--no-hostname</option></term> - - <listitem><para>Don't show the hostname field of log messages originating from the local host. This switch only - has an effect on the <option>short</option> family of output modes (see above).</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-x</option></term> - <term><option>--catalog</option></term> - - <listitem><para>Augment log lines with explanation texts from - the message catalog. This will add explanatory help texts to - log messages in the output where this is available. These - short help texts will explain the context of an error or log - event, possible solutions, as well as pointers to support - forums, developer documentation, and any other relevant - manuals. Note that help texts are not available for all - messages, but only for selected ones. For more information on - the message catalog, please refer to the - <ulink url="http://www.freedesktop.org/wiki/Software/systemd/catalog">Message Catalog Developer Documentation</ulink>.</para> - - <para>Note: when attaching <command>journalctl</command> - output to bug reports, please do <emphasis>not</emphasis> use - <option>-x</option>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-q</option></term> - <term><option>--quiet</option></term> - - <listitem><para>Suppresses all info messages - (i.e. "-- Logs begin at ...", "-- Reboot --"), - any warning messages regarding - inaccessible system journals when run as a normal - user.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-m</option></term> - <term><option>--merge</option></term> - - <listitem><para>Show entries interleaved from all available - journals, including remote ones.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-b <optional><replaceable>ID</replaceable></optional><optional><replaceable>±offset</replaceable></optional></option></term> - <term><option>--boot=<optional><replaceable>ID</replaceable></optional><optional><replaceable>±offset</replaceable></optional></option></term> - - <listitem><para>Show messages from a specific boot. This will - add a match for <literal>_BOOT_ID=</literal>.</para> - - <para>The argument may be empty, in which case logs for the - current boot will be shown.</para> - - <para>If the boot ID is omitted, a positive - <replaceable>offset</replaceable> will look up the boots - starting from the beginning of the journal, and an - equal-or-less-than zero <replaceable>offset</replaceable> will - look up boots starting from the end of the journal. Thus, - <constant>1</constant> means the first boot found in the - journal in chronological order, <constant>2</constant> the - second and so on; while <constant>-0</constant> is the last - boot, <constant>-1</constant> the boot before last, and so - on. An empty <replaceable>offset</replaceable> is equivalent - to specifying <constant>-0</constant>, except when the current - boot is not the last boot (e.g. because - <option>--directory</option> was specified to look at logs - from a different machine).</para> - - <para>If the 32-character <replaceable>ID</replaceable> is - specified, it may optionally be followed by - <replaceable>offset</replaceable> which identifies the boot - relative to the one given by boot - <replaceable>ID</replaceable>. Negative values mean earlier - boots and positive values mean later boots. If - <replaceable>offset</replaceable> is not specified, a value of - zero is assumed, and the logs for the boot given by - <replaceable>ID</replaceable> are shown.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--list-boots</option></term> - - <listitem><para>Show a tabular list of boot numbers (relative to - the current boot), their IDs, and the timestamps of the first - and last message pertaining to the boot.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-k</option></term> - <term><option>--dmesg</option></term> - - <listitem><para>Show only kernel messages. This implies - <option>-b</option> and adds the match - <literal>_TRANSPORT=kernel</literal>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-t</option></term> - <term><option>--identifier=<replaceable>SYSLOG_IDENTIFIER</replaceable></option></term> - - <listitem><para>Show messages for the specified syslog - identifier - <replaceable>SYSLOG_IDENTIFIER</replaceable>.</para> - - <para>This parameter can be specified multiple - times.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-u</option></term> - <term><option>--unit=<replaceable>UNIT</replaceable>|<replaceable>PATTERN</replaceable></option></term> - - <listitem><para>Show messages for the specified systemd unit - <replaceable>UNIT</replaceable> (such as a service unit), or - for any of the units matched by - <replaceable>PATTERN</replaceable>. If a pattern is - specified, a list of unit names found in the journal is - compared with the specified pattern and all that match are - used. For each unit name, a match is added for messages from - the unit - (<literal>_SYSTEMD_UNIT=<replaceable>UNIT</replaceable></literal>), - along with additional matches for messages from systemd and - messages about coredumps for the specified unit.</para> - - <para>This parameter can be specified multiple times.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--user-unit=</option></term> - - <listitem><para>Show messages for the specified user session - unit. This will add a match for messages from the unit - (<literal>_SYSTEMD_USER_UNIT=</literal> and - <literal>_UID=</literal>) and additional matches for messages - from session systemd and messages about coredumps for the - specified unit.</para> - - <para>This parameter can be specified multiple times.</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 project='man-pages'><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>-c</option></term> - <term><option>--cursor=</option></term> - - <listitem><para>Start showing entries from the location in the - journal specified by the passed cursor.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--after-cursor=</option></term> - - <listitem><para>Start showing entries from the location in the - journal <emphasis>after</emphasis> the location specified by - the passed cursor. The cursor is shown when the - <option>--show-cursor</option> option is used.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--show-cursor</option></term> - - <listitem><para>The cursor is shown after the last entry after - two dashes:</para> - <programlisting>-- cursor: s=0639...</programlisting> - <para>The format of the cursor is private - and subject to change.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-S</option></term> - <term><option>--since=</option></term> - <term><option>-U</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 - <literal>2012-10-30 18:17:16</literal>. If the time part is - omitted, <literal>00:00:00</literal> is assumed. If only the - seconds component is omitted, <literal>:00</literal> is - assumed. If the date component is omitted, 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. For complete - time and date specification, see - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-F</option></term> - <term><option>--field=</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>-N</option></term> - <term><option>--fields</option></term> - - <listitem><para>Print all field names currently used in all entries of the journal.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--system</option></term> - <term><option>--user</option></term> - - <listitem><para>Show messages from system services and the - kernel (with <option>--system</option>). Show messages from - service of current user (with <option>--user</option>). If - neither is specified, show all messages that the user can see. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-M</option></term> - <term><option>--machine=</option></term> - - <listitem><para>Show messages from a running, local - container. Specify a container name to connect to.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-D <replaceable>DIR</replaceable></option></term> - <term><option>--directory=<replaceable>DIR</replaceable></option></term> - - <listitem><para>Takes a directory path as argument. If - specified, journalctl will operate on the specified journal - directory <replaceable>DIR</replaceable> instead of the - default runtime and system journal paths.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--file=<replaceable>GLOB</replaceable></option></term> - - <listitem><para>Takes a file glob as an argument. If - specified, journalctl will operate on the specified journal - files matching <replaceable>GLOB</replaceable> instead of the - default runtime and system journal paths. May be specified - multiple times, in which case files will be suitably - interleaved.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--root=<replaceable>ROOT</replaceable></option></term> - - <listitem><para>Takes a directory path as an argument. If - specified, journalctl will operate on catalog file hierarchy - underneath the specified directory instead of the root - directory (e.g. <option>--update-catalog</option> will create - <filename><replaceable>ROOT</replaceable>/var/lib/systemd/catalog/database</filename>). - </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. This 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. This shows the sum of the disk usage of all archived - and active journal files.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--vacuum-size=</option></term> - <term><option>--vacuum-time=</option></term> - <term><option>--vacuum-files=</option></term> - - <listitem><para>Removes archived journal files until the disk - space they use falls below the specified size (specified with - the usual <literal>K</literal>, <literal>M</literal>, - <literal>G</literal> and <literal>T</literal> suffixes), or all - archived journal files contain no data older than the specified - timespan (specified with the usual <literal>s</literal>, - <literal>m</literal>, <literal>h</literal>, - <literal>days</literal>, <literal>months</literal>, - <literal>weeks</literal> and <literal>years</literal> suffixes), - or no more than the specified number of separate journal files - remain. Note that running <option>--vacuum-size=</option> has - only an indirect effect on the output shown by - <option>--disk-usage</option>, as the latter includes active - journal files, while the vacuuming operation only operates - on archived journal files. Similarly, - <option>--vacuum-files=</option> might not actually reduce the - number of journal files to below the specified number, as it - will not remove active journal - files. <option>--vacuum-size=</option>, - <option>--vacuum-time=</option> and - <option>--vacuum-files=</option> may be combined in a single - invocation to enforce any combination of a size, a time and a - number of files limit on the archived journal - files. Specifying any of these three parameters as zero is - equivalent to not enforcing the specific limit, and is thus - redundant.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--list-catalog - <optional><replaceable>128-bit-ID...</replaceable></optional> - </option></term> - - <listitem><para>List the contents of the message catalog as a - table of message IDs, plus their short description strings. - </para> - - <para>If any <replaceable>128-bit-ID</replaceable>s are - specified, only those entries are shown.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--dump-catalog - <optional><replaceable>128-bit-ID...</replaceable></optional> - </option></term> - - <listitem><para>Show the contents of the message catalog, with - entries separated by a line consisting of two dashes and the - ID (the format is the same as <filename>.catalog</filename> - files).</para> - - <para>If any <replaceable>128-bit-ID</replaceable>s are - specified, only those entries are shown.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--update-catalog</option></term> - - <listitem><para>Update the message catalog index. This command - needs to be executed each time new catalog files are - installed, removed, or updated to rebuild the binary catalog - index.</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. Refer to the <option>Seal=</option> option in - <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for information on Forward Secure Sealing and for a link to a - refereed scholarly paper detailing the cryptographic theory it - is based on.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--force</option></term> - - <listitem><para>When <option>--setup-keys</option> is passed - and Forward Secure Sealing (FSS) has already been configured, - recreate FSS keys.</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> - - <varlistentry> - <term><option>--sync</option></term> - - <listitem><para>Asks the journal daemon to write all yet - unwritten journal data to the backing file system and - synchronize all journals. This call does not return until the - synchronization operation is complete. This command guarantees - that any log messages written before its invocation are safely - stored on disk at the time it returns.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--flush</option></term> - - <listitem><para>Asks the journal daemon to flush any log data - stored in <filename>/run/log/journal</filename> into - <filename>/var/log/journal</filename>, if persistent storage - is enabled. This call does not return until the operation is - complete. Note that this call is idempotent: the data is only - flushed from <filename>/run/log/journal</filename> into - <filename>/var/log/journal</filename> once during system - runtime, and this command exits cleanly without executing any - operation if this has already has happened. This command - effectively guarantees that all data is flushed to - <filename>/var/log/journal</filename> at the time it - returns.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--rotate</option></term> - - <listitem><para>Asks the journal daemon to rotate journal - files. This call does not return until the rotation operation - is complete.</para></listitem> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - <xi:include href="standard-options.xml" xpointer="no-pager" /> - </variablelist> - </refsect1> - - <refsect1> - <title>Exit status</title> - - <para>On success, 0 is returned; otherwise, a non-zero failure - code is returned.</para> - </refsect1> - - <xi:include href="less-variables.xml" /> - - <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 kernel logs from previous boot:</para> - - <programlisting>journalctl -k -b -1</programlisting> - - <para>Show a live log display from a system service - <filename>apache.service</filename>:</para> - - <programlisting>journalctl -f -u apache</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>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> -</refentry> diff --git a/man/journald.conf.xml b/man/journald.conf.xml deleted file mode 100644 index 3964cd6bc5..0000000000 --- a/man/journald.conf.xml +++ /dev/null @@ -1,410 +0,0 @@ -<?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="journald.conf" - xmlns:xi="http://www.w3.org/2001/XInclude"> - <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> - <refname>journald.conf.d</refname> - <refpurpose>Journal service configuration files</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/etc/systemd/journald.conf</filename></para> - <para><filename>/etc/systemd/journald.conf.d/*.conf</filename></para> - <para><filename>/run/systemd/journald.conf.d/*.conf</filename></para> - <para><filename>/usr/lib/systemd/journald.conf.d/*.conf</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>These files configure various parameters of the systemd - journal service, - <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> - - </refsect1> - - <xi:include href="standard-conf.xml" xpointer="main-conf" /> - - <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 socket 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 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. FSS is - based on <ulink - url="https://eprint.iacr.org/2013/397">Seekable Sequential Key - Generators</ulink> by G. A. Marson and B. Poettering - (doi:10.1007/978-3-642-40203-6_7) and may be used to protect - journal files from unnoticed alteration.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>SplitMode=</varname></term> - - <listitem><para>Controls whether to split up journal files per - user. One of <literal>uid</literal>, <literal>login</literal> - and <literal>none</literal>. If <literal>uid</literal>, all - users will get each their own journal files regardless of - whether they possess a login session or not, however system - users will log into the system journal. If - <literal>login</literal>, actually logged-in users will get - each their own journal files, but users without login session - and system users will log into the system journal. If - <literal>none</literal>, journal files are not split up by - user and all messages are instead stored in the single system - journal. Note that splitting up journal files by user is only - available for journals 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>uid</literal>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>RateLimitIntervalSec=</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>RateLimitIntervalSec=</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 limits. Defaults to 1000 messages in 30s. - The time specification for - <varname>RateLimitIntervalSec=</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>SystemMaxFiles=</varname></term> - <term><varname>RuntimeMaxUse=</varname></term> - <term><varname>RuntimeKeepFree=</varname></term> - <term><varname>RuntimeMaxFileSize=</varname></term> - <term><varname>RuntimeMaxFiles=</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. <command>journalctl</command> and - <command>systemd-journald</command> ignore all files with - names not ending with <literal>.journal</literal> or - <literal>.journal~</literal>, so only such files, located in - the appropriate directories, are taken into account when - calculating current disk usage.</para> - - <para><varname>SystemMaxUse=</varname> and - <varname>RuntimeMaxUse=</varname> control how much disk space - the journal may use up at most. - <varname>SystemKeepFree=</varname> and - <varname>RuntimeKeepFree=</varname> control how much disk - space systemd-journald shall leave free for other uses. - <command>systemd-journald</command> will respect both limits - and use the smaller of the two values.</para> - - <para>The first pair defaults to 10% and the second to 15% of - the size of the respective file system, but each value is - capped to 4G. If the file system is nearly full and either - <varname>SystemKeepFree=</varname> or - <varname>RuntimeKeepFree=</varname> are violated when - systemd-journald is started, the limit will be raised to the - percentage that is actually free. This means that if there was - enough free space before and journal files were created, and - subsequently something else causes the file system to fill up, - journald will stop using more space, but it will not be - removing existing files to reduce the footprint again, - either.</para> - - <para><varname>SystemMaxFileSize=</varname> and - <varname>RuntimeMaxFileSize=</varname> control how large - individual journal files may grow at most. 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.</para> - - <para>Specify values in bytes or use K, M, G, T, P, E as - units for the specified sizes (equal to 1024, 1024², ... bytes). - Note that size limits are enforced synchronously when journal - files are extended, and no explicit rotation step triggered by - time is needed.</para> - - <para><varname>SystemMaxFiles=</varname> and - <varname>RuntimeMaxFiles=</varname> control how many - individual journal files to keep at most. Note that only - archived files are deleted to reduce the number of files until - this limit is reached; active files will stay around. This - means that, in effect, there might still be more journal files - around in total than this limit after a vacuuming operation is - complete. This setting defaults to 100.</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 do not 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 <literal>year</literal>, - <literal>month</literal>, <literal>week</literal>, - <literal>day</literal>, <literal>h</literal> or - <literal>m</literal> 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 do not 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 <literal>year</literal>, - <literal>month</literal>, <literal>week</literal>, - <literal>day</literal>, <literal>h</literal> or <literal> - m</literal> to override the default time unit of - seconds.</para></listitem> - </varlistentry> - - - <varlistentry> - <term><varname>SyncIntervalSec=</varname></term> - - <listitem><para>The timeout before synchronizing journal files - to disk. After syncing, journal files are placed in the - OFFLINE state. Note that syncing is unconditionally done - immediately after a log message of priority CRIT, ALERT or - EMERG has been logged. This setting hence applies only to - messages of the levels ERR, WARNING, NOTICE, INFO, DEBUG. The - default timeout is 5 minutes. </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>ForwardToSyslog=</varname></term> - <term><varname>ForwardToKMsg=</varname></term> - <term><varname>ForwardToConsole=</varname></term> - <term><varname>ForwardToWall=</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), to the system - console, or sent as wall messages to all logged-in users. - These options take boolean arguments. If forwarding to syslog - is enabled but nothing reads messages from the socket, - forwarding to syslog has no effect. By default, only - forwarding to wall 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>, - <literal>systemd.journald.forward_to_console=</literal>, and - <literal>systemd.journald.forward_to_wall=</literal>. When - forwarding to the console, the TTY to log to can be changed - with <varname>TTYPath=</varname>, described - below.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>MaxLevelStore=</varname></term> - <term><varname>MaxLevelSyslog=</varname></term> - <term><varname>MaxLevelKMsg=</varname></term> - <term><varname>MaxLevelConsole=</varname></term> - <term><varname>MaxLevelWall=</varname></term> - - <listitem><para>Controls the maximum log level of messages - that are stored on disk, forwarded to syslog, kmsg, the - console or wall (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>, - <literal>info</literal> for <varname>MaxLevelConsole=</varname>, - and <literal>emerg</literal> for - <varname>MaxLevelWall=</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>Forwarding to traditional syslog daemons</title> - - <para> - Journal events can be transferred to a different logging daemon - in two different ways. With the first method, messages are - immediately forwarded to a socket - (<filename>/run/systemd/journal/syslog</filename>), where the - traditional syslog daemon can read them. This method is - controlled by the <varname>ForwardToSyslog=</varname> option. With a - second method, a syslog daemon behaves like a normal journal - client, and reads messages from the journal files, similarly to - <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. - With this, messages do not have to be read immediately, - which allows a logging daemon which is only started late in boot - to access all messages since the start of the system. In - addition, full structured meta-data is available to it. This - method of course is available only if the messages are stored in - a journal file at all. So it will not work if - <varname>Storage=none</varname> is set. It should be noted that - usually the <emphasis>second</emphasis> method is used by syslog - daemons, so the <varname>Storage=</varname> option, and not the - <varname>ForwardToSyslog=</varname> option, is relevant for them. - </para> - </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-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/kernel-command-line.xml b/man/kernel-command-line.xml deleted file mode 100644 index 9c04849f66..0000000000 --- a/man/kernel-command-line.xml +++ /dev/null @@ -1,382 +0,0 @@ -<?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 project='man-pages'><refentrytitle>bootparam</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> - - <para>For command line parameters understood by the initial RAM - disk, please see - <citerefentry project='man-pages'><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 class='kernel-commandline-options'> - <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_chvt=</varname></term> - <term><varname>systemd.crash_shell=</varname></term> - <term><varname>systemd.crash_reboot=</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> - <term><varname>systemd.machine_id=</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>systemd.mask=</varname></term> - <term><varname>systemd.wants=</varname></term> - <term><varname>systemd.debug-shell</varname></term> - <listitem> - <para>Additional parameters understood by - <citerefentry><refentrytitle>systemd-debug-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - to mask or start specific units at boot, or invoke a debug - shell on tty9.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>systemd.restore_state=</varname></term> - <listitem> - <para>This parameter is understood by several system tools - to control whether or not they should restore system state - from the previous boot. For details, see - <citerefentry><refentrytitle>systemd-backlight@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>systemd-rfkill.service</refentrytitle><manvolnum>8</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>debug</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>-b</varname></term> - <term><varname>emergency</varname></term> - <term><varname>rescue</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> - <term><varname>fsck.repair=</varname></term> - - <listitem> - <para>Parameters 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> - <term><varname>systemd.journald.forward_to_wall=</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> - <term><varname>udev.event-timeout=</varname></term> - <term><varname>rd.udev.event-timeout=</varname></term> - <term><varname>net.ifnames=</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 project='die-net'><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.name=</varname></term> - <term><varname>rd.luks.name=</varname></term> - <term><varname>luks.uuid=</varname></term> - <term><varname>rd.luks.uuid=</varname></term> - <term><varname>luks.options=</varname></term> - <term><varname>rd.luks.options=</varname></term> - <term><varname>luks.key=</varname></term> - <term><varname>rd.luks.key=</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>root=</varname></term> - <term><varname>rootfstype=</varname></term> - <term><varname>rootflags=</varname></term> - <term><varname>ro</varname></term> - <term><varname>rw</varname></term> - - <listitem> - <para>Configures the root file system and its file system - type and mount options, as well as whether it shall be - mounted read-only or read-writable initially. For details, - see - <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>systemd.gpt_auto=</varname></term> - <term><varname>rd.systemd.gpt_auto=</varname></term> - - <listitem> - <para>Configures whether GPT based partition auto-discovery - shall be attempted. For details, see - <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>systemd.default_timeout_start_sec=</varname></term> - - <listitem> - <para>Overwrites the default start job timeout <varname>DefaultTimeoutStartSec=</varname> at boot. For details, - see <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</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> - - <varlistentry> - <term><varname>resume=</varname></term> - - <listitem> - <para>Enables resume from hibernation using the specified - device. All - <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>-like - paths are supported. For details, see - <citerefentry><refentrytitle>systemd-hibernate-resume-generator</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 project='man-pages'><refentrytitle>bootparam</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>dracut.cmdline</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-debug-generator</refentrytitle><manvolnum>8</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 project='die-net'><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-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-modules-load.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-backlight@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-rfkill.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-hibernate-resume-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/custom-html.xsl b/man/lib/custom-html.xsl index e89d73e7f1..e89d73e7f1 100644 --- a/man/custom-html.xsl +++ b/man/lib/custom-html.xsl diff --git a/man/custom-man.xsl b/man/lib/custom-man.xsl index e1b8d3618a..e1b8d3618a 100644 --- a/man/custom-man.xsl +++ b/man/lib/custom-man.xsl diff --git a/man/less-variables.xml b/man/lib/less-variables.xml index 0fb4d7fbcf..0fb4d7fbcf 100644 --- a/man/less-variables.xml +++ b/man/lib/less-variables.xml diff --git a/man/libsystemd-pkgconfig.xml b/man/lib/libsystemd-pkgconfig.xml index 272da64cd7..272da64cd7 100644 --- a/man/libsystemd-pkgconfig.xml +++ b/man/lib/libsystemd-pkgconfig.xml diff --git a/man/standard-conf.xml b/man/lib/standard-conf.xml index 6edbb7ff83..6edbb7ff83 100644 --- a/man/standard-conf.xml +++ b/man/lib/standard-conf.xml diff --git a/man/standard-options.xml b/man/lib/standard-options.xml index f214463392..f214463392 100644 --- a/man/standard-options.xml +++ b/man/lib/standard-options.xml diff --git a/man/user-system-options.xml b/man/lib/user-system-options.xml index 8616c54249..8616c54249 100644 --- a/man/user-system-options.xml +++ b/man/lib/user-system-options.xml diff --git a/man/libudev.xml b/man/libudev.xml deleted file mode 100644 index 7ef978463c..0000000000 --- a/man/libudev.xml +++ /dev/null @@ -1,125 +0,0 @@ -<?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" [ -<!ENTITY % entities SYSTEM "custom-entities.ent" > -%entities; -]> - -<!-- - This file is part of systemd. - - Copyright 2015 David Herrmann <dh.herrmann@gmail.com> - - 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="libudev" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>libudev</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>David</firstname> - <surname>Herrmann</surname> - <email>dh.herrmann@gmail.com</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>libudev</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>libudev</refname> - <refpurpose>API for enumerating and introspecting local devices</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <libudev.h></funcsynopsisinfo> - </funcsynopsis> - - <cmdsynopsis> - <command>pkg-config --cflags --libs libudev</command> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>libudev.h</filename> provides APIs to introspect - and enumerate devices on the local system.</para> - - <para>All functions require a libudev context to operate. This - context can be create via - <citerefentry><refentrytitle>udev_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - It is used to track library state and link objects together. No - global state is used by libudev, everything is always linked to - a udev context. Furthermore, multiple different udev contexts can - be used in parallel by multiple threads. However, a single context - must not be accessed by multiple threads in parallel. The caller - is responsible for providing suitable locking if they intend to use - it from multiple threads.</para> - - <para>To introspect a local device on a system, a udev device - object can be created via - <citerefentry><refentrytitle>udev_device_new_from_syspath</refentrytitle><manvolnum>3</manvolnum></citerefentry> - and friends. The device object allows to query current state, - read and write attributes and lookup properties of the device in - question.</para> - - <para>To enumerate local devices on the system, an enumeration - object can be created via - <citerefentry><refentrytitle>udev_enumerate_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> - - <para>To monitor the local system for hotplugged or unplugged - devices, a monitor can be created via - <citerefentry><refentrytitle>udev_monitor_new_from_netlink</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> - - <para>Whenever libudev returns a list of objects, the - <citerefentry><refentrytitle>udev_list_entry</refentrytitle><manvolnum>3</manvolnum></citerefentry> - API should be used to iterate, access and modify those lists.</para> - - <para>Furthermore, libudev also exports legacy APIs that should - not be used by new software (and as such are not documented as - part of this manual). This includes the hardware database known - as <constant>udev_hwdb</constant> (please use the new - <citerefentry><refentrytitle>sd-hwdb</refentrytitle><manvolnum>3</manvolnum></citerefentry> - API instead) and the <constant>udev_queue</constant> object to - query the udev daemon (which should not be used by new software - at all).</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>udev_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_device_new_from_syspath</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_enumerate_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_monitor_new_from_netlink</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_list_entry</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-device</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-hwdb</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/locale.conf.xml b/man/locale.conf.xml deleted file mode 100644 index 2fe731113a..0000000000 --- a/man/locale.conf.xml +++ /dev/null @@ -1,152 +0,0 @@ -<?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="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> - - <para><citerefentry project='man-pages'><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - may be used to alter the settings in this file during runtime from - the command line. Use - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - to initialize them on mounted (but not booted) system - images.</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 project='man-pages'><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=en_US.UTF-8</programlisting> - </example> - - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>locale</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-localed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/localectl.xml b/man/localectl.xml deleted file mode 100644 index 7def047f62..0000000000 --- a/man/localectl.xml +++ /dev/null @@ -1,221 +0,0 @@ -<?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" conditional='ENABLE_LOCALED' - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <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</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="req">COMMAND</arg> - </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> - - <para>Use - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - to initialize the system locale for mounted (but not booted) - system images.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--no-ask-password</option></term> - - <listitem><para>Do not query the user for authentication for - privileged operations.</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> - - <xi:include href="user-system-options.xml" xpointer="host" /> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - <xi:include href="standard-options.xml" xpointer="no-pager" /> - </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 project='man-pages'><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 and X11. This takes a 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 as the default system - keyboard mapping of X11, after converting it to the closest - matching X11 keyboard mapping. Use - <command>list-keymaps</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-keymap</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 and the virtual console. This takes a keyboard mapping - name (such as <literal>de</literal> or <literal>us</literal>), - 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 as the system console - keyboard mapping, after converting it to the closest matching - console keyboard mapping.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>list-x11-keymap-models</command></term> - <term><command>list-x11-keymap-layouts</command></term> - <term><command>list-x11-keymap-variants [LAYOUT]</command></term> - <term><command>list-x11-keymap-options</command></term> - - <listitem><para>List available X11 keymap models, layouts, - variants and options, useful for configuration with - <command>set-keymap</command>. The command - <command>list-x11-keymap-variants</command> optionally takes a - layout parameter to limit the output to the variants suitable - for the specific layout.</para></listitem> - </varlistentry> - </variablelist> - - </refsect1> - - <refsect1> - <title>Exit status</title> - - <para>On success, 0 is returned, a non-zero failure code - otherwise.</para> - </refsect1> - - <xi:include href="less-variables.xml" /> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>locale</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='mankier'><refentrytitle>loadkeys</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>kbd</refentrytitle><manvolnum>4</manvolnum></citerefentry>, - <ulink url="http://www.x.org/releases/current/doc/xorg-docs/input/XKB-Config.html"> - The XKB Configuration Guide - </ulink>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-localed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/loginctl.xml b/man/loginctl.xml deleted file mode 100644 index fb51740503..0000000000 --- a/man/loginctl.xml +++ /dev/null @@ -1,459 +0,0 @@ -<?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" conditional='ENABLE_LOGIND' - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <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</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="req">COMMAND</arg> - <arg choice="opt" rep="repeat">NAME</arg> - </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>--no-ask-password</option></term> - - <listitem><para>Do not query the user for authentication for - privileged operations.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-p</option></term> - <term><option>--property=</option></term> - - <listitem><para>When showing session/user/seat 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>--value</option></term> - - <listitem> - <para>When printing properties with <command>show</command>, - only print the value, and skip the property name and - <literal>=</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-a</option></term> - <term><option>--all</option></term> - - <listitem><para>When showing session/user/seat properties, - show all properties regardless of whether they are set or - not.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-l</option></term> - <term><option>--full</option></term> - - <listitem><para>Do not ellipsize process tree entries.</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>-s</option></term> - <term><option>--signal=</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 <constant>SIGTERM</constant>, - <constant>SIGINT</constant> or <constant>SIGSTOP</constant>. - If omitted, defaults to - <constant>SIGTERM</constant>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-n</option></term> - <term><option>--lines=</option></term> - - <listitem><para>When used with <command>user-status</command> - and <command>session-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>-o</option></term> - <term><option>--output=</option></term> - - <listitem><para>When used with <command>user-status</command> - and <command>session-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> - - <xi:include href="user-system-options.xml" xpointer="host" /> - <xi:include href="user-system-options.xml" xpointer="machine" /> - - <xi:include href="standard-options.xml" xpointer="no-pager" /> - <xi:include href="standard-options.xml" xpointer="no-legend" /> - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </variablelist> - </refsect1> - - <refsect1> - <title>Commands</title> - - <para>The following commands are understood:</para> - - <refsect2><title>Session Commands</title><variablelist> - - <varlistentry> - <term><command>list-sessions</command></term> - - <listitem><para>List current sessions.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>session-status</command> <optional><replaceable>ID</replaceable>...</optional></term> - - <listitem><para>Show terse runtime status information about - one or more sessions, followed by the most recent log data - from the journal. Takes one or more session identifiers as - parameters. If no session identifiers are passed, the status of - the caller's session is shown. 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</command> <optional><replaceable>ID</replaceable>...</optional></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 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>session-status</command> if you are looking for - formatted human-readable output.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>activate</command> <optional><replaceable>ID</replaceable></optional></term> - - <listitem><para>Activate a session. This brings a session into - the foreground if another session is currently in the - foreground on the respective seat. Takes a session identifier - as argument. If no argument is specified, the session of the - caller is put into foreground.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>lock-session</command> <optional><replaceable>ID</replaceable>...</optional></term> - <term><command>unlock-session</command> <optional><replaceable>ID</replaceable>...</optional></term> - - <listitem><para>Activates/deactivates the screen lock on one - or more sessions, if the session supports it. Takes one or - more session identifiers as arguments. If no argument is - specified, the session of the caller is locked/unlocked. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><command>lock-sessions</command></term> - <term><command>unlock-sessions</command></term> - - <listitem><para>Activates/deactivates the screen lock on all - current sessions supporting it. </para></listitem> - </varlistentry> - - <varlistentry> - <term><command>terminate-session</command> <replaceable>ID</replaceable>...</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</command> <replaceable>ID</replaceable>...</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> - </variablelist></refsect2> - - <refsect2><title>User Commands</title><variablelist> - <varlistentry> - <term><command>list-users</command></term> - - <listitem><para>List currently logged in users. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><command>user-status</command> <optional><replaceable>USER</replaceable>...</optional></term> - - <listitem><para>Show terse runtime status information about - one or more logged in users, followed by the most recent log - data from the journal. Takes one or more user names or numeric - user IDs as parameters. If no parameters are passed, the status - of the caller's user is shown. 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</command> <optional><replaceable>USER</replaceable>...</optional></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 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>user-status</command> if you are looking for - formatted human-readable output.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>enable-linger</command> <optional><replaceable>USER</replaceable>...</optional></term> - <term><command>disable-linger</command> <optional><replaceable>USER</replaceable>...</optional></term> - - <listitem><para>Enable/disable user lingering for one or more - users. If enabled for a specific user, a user manager is - spawned for the user at boot and kept around after logouts. - This allows users who are not logged in to run long-running - services. Takes one or more user names or numeric UIDs as - argument. If no argument is specified, enables/disables - lingering for the user of the session of the caller.</para> - - <para>See also <varname>KillUserProcesses=</varname> setting in - <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><command>terminate-user</command> <replaceable>USER</replaceable>...</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</command> <replaceable>USER</replaceable>...</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> - </variablelist></refsect2> - - <refsect2><title>Seat Commands</title><variablelist> - <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</command> <optional><replaceable>NAME</replaceable>...</optional></term> - - <listitem><para>Show terse runtime status information about - one or more seats. Takes one or more seat names as parameters. - If no seat names are passed the status of the caller's - session's seat is shown. 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</command> <optional><replaceable>NAME</replaceable>...</optional></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</command> <replaceable>NAME</replaceable> <replaceable>DEVICE</replaceable>...</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, - <literal>-</literal> and <literal>_</literal> and must be - prefixed with <literal>seat</literal>. 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</command> <replaceable>NAME</replaceable>...</term> - - <listitem><para>Terminates all sessions on a seat. This kills - all processes of all sessions on the seat and deallocates all - runtime resources attached to them.</para></listitem> - </varlistentry> - </variablelist></refsect2> - - </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>Querying user status</title> - - <programlisting>$ loginctl user-status -fatima (1005) - Since: Sat 2016-04-09 14:23:31 EDT; 54min ago - State: active - Sessions: 5 *3 - Unit: user-1005.slice - ├─user@1005.service - ... - ├─session-3.scope - ... - └─session-5.scope - ├─3473 login -- fatima - └─3515 -zsh - -Apr 09 14:40:30 laptop login[2325]: pam_unix(login:session): - session opened for user fatima by LOGIN(uid=0) -Apr 09 14:40:30 laptop login[2325]: LOGIN ON tty3 BY fatima -</programlisting> - - <para>There are two sessions, 3 and 5. Session 3 is a graphical session, - marked with a star. The tree of processing including the two corresponding - scope units and the user manager unit are shown.</para> - </example> - </refsect1> - - <xi:include href="less-variables.xml" /> - - <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 deleted file mode 100644 index fe92277a1f..0000000000 --- a/man/logind.conf.xml +++ /dev/null @@ -1,349 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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" conditional='ENABLE_LOGIND' - xmlns:xi="http://www.w3.org/2001/XInclude"> - <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> - <refname>logind.conf.d</refname> - <refpurpose>Login manager configuration files</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/etc/systemd/logind.conf</filename></para> - <para><filename>/etc/systemd/logind.conf.d/*.conf</filename></para> - <para><filename>/run/systemd/logind.conf.d/*.conf</filename></para> - <para><filename>/usr/lib/systemd/logind.conf.d/*.conf</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>These files configure various parameters of the systemd - login manager, - <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. - </para> - </refsect1> - - <xi:include href="standard-conf.xml" xpointer="main-conf" /> - - <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 are 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, for example, <filename>autovt@tty4.service</filename>. - By default, <filename>autovt@.service</filename> is linked to - <filename>getty@.service</filename>. In other words, 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 the 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. Identifies 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 of how - many VTs are allocated by other subsystems, one login - <literal>getty</literal> is always available. Defaults to 6 - (in other words, there will 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 the user logs out. If true, the scope unit - corresponding to the session and all processes inside that scope will be - terminated. If false, the scope is "abandoned", see - <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - and processes are not killed. Defaults to <literal>yes</literal>, - but see the options <varname>KillOnlyUsers=</varname> and - <varname>KillExcludeUsers=</varname> below.</para> - - <para>In addition to session processes, user process may run under the user - manager unit <filename>user@.service</filename>. Depending on the linger - settings, this may allow users to run processes independent of their login - sessions. See the description of <command>enable-linger</command> in - <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. - </para> - - <para>Note that setting <varname>KillUserProcesses=yes</varname> - will break tools like - <citerefentry project='die-net'><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry> - and - <citerefentry project='die-net'><refentrytitle>tmux</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - unless they are moved out of the session scope. See example in - <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>KillOnlyUsers=</varname></term> - <term><varname>KillExcludeUsers=</varname></term> - - <listitem><para>These settings take space-separated lists of usernames that override - the <varname>KillUserProcesses=</varname> setting. A user name may be added to - <varname>KillExcludeUsers=</varname> to exclude the processes in the session scopes of - that user from being killed even if <varname>KillUserProcesses=yes</varname> is set. If - <varname>KillExcludeUsers=</varname> is not set, the <literal>root</literal> user is - excluded by default. <varname>KillExcludeUsers=</varname> may be set to an empty value - to override this default. If a user is not excluded, <varname>KillOnlyUsers=</varname> - is checked next. If this setting is specified, only the session scopes of those users - will be killed. Otherwise, users are subject to the - <varname>KillUserProcesses=yes</varname> setting.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>IdleAction=</varname></term> - - <listitem><para>Configures the action to take when the system - is idle. Takes 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>. - Defaults to <literal>ignore</literal>.</para> - - <para>Note that this requires that user sessions correctly - report the idle status to the system. The system will execute - the action after all sessions report that they are idle, no - idle inhibitor lock is active, and subsequently, the time - configured with <varname>IdleActionSec=</varname> (see below) - has expired.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>IdleActionSec=</varname></term> - - <listitem><para>Configures the delay after which the action - configured in <varname>IdleAction=</varname> (see above) is - taken after the system is idle.</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 the inhibitor is - ignored and the operation executes anyway. Defaults to - 5.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>HandlePowerKey=</varname></term> - <term><varname>HandleSuspendKey=</varname></term> - <term><varname>HandleHibernateKey=</varname></term> - <term><varname>HandleLidSwitch=</varname></term> - <term><varname>HandleLidSwitchDocked=</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>HandleLidSwitchDocked=</varname> defaults to - <literal>ignore</literal>. - <varname>HandleHibernateKey=</varname> defaults to - <literal>hibernate</literal>. If the system is inserted in a - docking station, or if more than one display is connected, the - action specified by <varname>HandleLidSwitchDocked=</varname> - occurs; otherwise the <varname>HandleLidSwitch=</varname> - action occurs.</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>no</literal>, the inhibitor locks taken by - applications in order to block the requested operation are - respected. If <literal>yes</literal>, the requested operation - is executed in any case. - <varname>PowerKeyIgnoreInhibited=</varname>, - <varname>SuspendKeyIgnoreInhibited=</varname> and - <varname>HibernateKeyIgnoreInhibited=</varname> default to - <literal>no</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> - - <varlistentry> - <term><varname>HoldoffTimeoutSec=</varname></term> - - <listitem><para>Specifies the timeout after system startup or - system resume in which systemd will hold off on reacting to - lid events. This is required for the system to properly - detect any hotplugged devices so systemd can ignore lid events - if external monitors, or docks, are connected. If set to 0, - systemd will always react immediately, possibly before the - kernel fully probed all hotplugged devices. This is safe, as - long as you do not care for systemd to account for devices - that have been plugged or unplugged while the system was off. - Defaults to 30s.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>RuntimeDirectorySize=</varname></term> - - <listitem><para>Sets the size limit on the - <varname>$XDG_RUNTIME_DIR</varname> runtime directory for each - user who logs in. Takes a size in bytes, optionally suffixed - with the usual K, G, M, and T suffixes, to the base 1024 - (IEC). Alternatively, a numerical percentage suffixed by - <literal>%</literal> may be specified, which sets the size - limit relative to the amount of physical RAM. Defaults to 10%. - Note that this size is a safety limit only. As each runtime - directory is a tmpfs file system, it will only consume as much - memory as is needed.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>InhibitorsMax=</varname></term> - - <listitem><para>Controls the maximum number of concurrent inhibitors to permit. Defaults to 8192 - (8K).</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>SessionsMax=</varname></term> - - <listitem><para>Controls the maximum number of concurrent user sessions to manage. Defaults to 8192 - (8K). Depending on how the <filename>pam_systemd.so</filename> module is included in the PAM stack - configuration, further login sessions will either be refused, or permitted but not tracked by - <filename>systemd-logind</filename>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>UserTasksMax=</varname></term> - - <listitem><para>Sets the maximum number of OS tasks each user - may run concurrently. This controls the - <varname>TasksMax=</varname> setting of the per-user slice - unit, see - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. Defaults to 12288 (12K).</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>RemoveIPC=</varname></term> - - <listitem><para>Controls whether System V and POSIX IPC objects belonging to the user shall be removed when the - user fully logs out. Takes a boolean argument. If enabled, the user may not consume IPC resources after the - last of the user's sessions terminated. This covers System V semaphores, shared memory and message queues, as - well as POSIX shared memory and message queues. Note that IPC objects of the root user and other system users - are excluded from the effect of this setting. Defaults to <literal>yes</literal>.</para></listitem> - </varlistentry> - - </variablelist> - </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-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/machinectl.xml b/man/machinectl.xml deleted file mode 100644 index 4b7f9a0391..0000000000 --- a/man/machinectl.xml +++ /dev/null @@ -1,1022 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2013 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="machinectl" conditional='ENABLE_MACHINED' - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>machinectl</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>machinectl</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>machinectl</refname> - <refpurpose>Control the systemd machine manager</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>machinectl</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="req">COMMAND</arg> - <arg choice="opt" rep="repeat">NAME</arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>machinectl</command> may be used to introspect and - control the state of the - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> - virtual machine and container registration manager - <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> - - <para><command>machinectl</command> may be used to execute - operations on machines and images. Machines in this sense are - considered running instances of:</para> - - <itemizedlist> - <listitem><para>Virtual Machines (VMs) that virtualize hardware - to run full operating system (OS) instances (including their kernels) - in a virtualized environment on top of the host OS.</para></listitem> - - <listitem><para>Containers that share the hardware and - OS kernel with the host OS, in order to run - OS userspace instances on top the host OS.</para></listitem> - - <listitem><para>The host system itself</para></listitem> - </itemizedlist> - - <para>Machines are identified by names that follow the same rules - as UNIX and DNS host names, for details, see below. Machines are - instantiated from disk or file system images that frequently — but not - necessarily — carry the same name as machines running from - them. Images in this sense are considered:</para> - - <itemizedlist> - <listitem><para>Directory trees containing an OS, including its - top-level directories <filename>/usr</filename>, - <filename>/etc</filename>, and so on.</para></listitem> - - <listitem><para>btrfs subvolumes containing OS trees, similar to - normal directory trees.</para></listitem> - - <listitem><para>Binary "raw" disk images containing MBR or GPT - partition tables and Linux file system partitions.</para></listitem> - - <listitem><para>The file system tree of the host OS itself.</para></listitem> - </itemizedlist> - - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>-p</option></term> - <term><option>--property=</option></term> - - <listitem><para>When showing machine or image properties, - limit the output to certain properties as specified by the - argument. If not specified, all set properties are shown. The - argument should be a property name, such as - <literal>Name</literal>. If specified more than once, all - properties with the specified names are - shown.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-a</option></term> - <term><option>--all</option></term> - - <listitem><para>When showing machine or image properties, show - all properties regardless of whether they are set or - not.</para> - - <para>When listing VM or container images, do not suppress - images beginning in a dot character - (<literal>.</literal>).</para> - - <para>When cleaning VM or container images, remove all images, not just hidden ones.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--value</option></term> - - <listitem><para>When printing properties with <command>show</command>, only print the value, - and skip the property name and <literal>=</literal>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-l</option></term> - <term><option>--full</option></term> - - <listitem><para>Do not ellipsize process tree entries.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--no-ask-password</option></term> - - <listitem><para>Do not 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</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 machine or all - processes of the machine. If omitted, defaults to - <option>all</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-s</option></term> - <term><option>--signal=</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 - <constant>SIGTERM</constant>, <constant>SIGINT</constant> or - <constant>SIGSTOP</constant>. If omitted, defaults to - <constant>SIGTERM</constant>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--uid=</option></term> - - <listitem><para>When used with the <command>shell</command> - command, chooses the user ID to open the interactive shell - session as. If this switch is not specified, defaults to - <literal>root</literal>. Note that this switch is not - supported for the <command>login</command> command (see - below).</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-E <replaceable>NAME</replaceable>=<replaceable>VALUE</replaceable></option></term> - <term><option>--setenv=<replaceable>NAME</replaceable>=<replaceable>VALUE</replaceable></option></term> - - <listitem><para>When used with the <command>shell</command> command, sets an environment - variable to pass to the executed shell. Takes an environment variable name and value, - separated by <literal>=</literal>. This switch may be used multiple times to set multiple - environment variables. Note that this switch is not supported for the - <command>login</command> command (see below).</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--mkdir</option></term> - - <listitem><para>When used with <command>bind</command>, creates - the destination directory before applying the bind - mount.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--read-only</option></term> - - <listitem><para>When used with <command>bind</command>, applies - a read-only bind mount.</para> - - <para>When used with <command>clone</command>, <command>import-raw</command> or <command>import-tar</command> a - read-only container or VM image is created.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-n</option></term> - <term><option>--lines=</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>-o</option></term> - <term><option>--output=</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> - - <varlistentry> - <term><option>--verify=</option></term> - - <listitem><para>When downloading a container or VM image, - specify whether the image shall be verified before it is made - available. Takes one of <literal>no</literal>, - <literal>checksum</literal> and <literal>signature</literal>. - If <literal>no</literal>, no verification is done. If - <literal>checksum</literal> is specified, the download is - checked for integrity after the transfer is complete, but no - signatures are verified. If <literal>signature</literal> is - specified, the checksum is verified and the image's signature - is checked against a local keyring of trustable vendors. It is - strongly recommended to set this option to - <literal>signature</literal> if the server and protocol - support this. Defaults to - <literal>signature</literal>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--force</option></term> - - <listitem><para>When downloading a container or VM image, and - a local copy by the specified local machine name already - exists, delete it first and replace it by the newly downloaded - image.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--format=</option></term> - - <listitem><para>When used with the <option>export-tar</option> - or <option>export-raw</option> commands, specifies the - compression format to use for the resulting file. Takes one of - <literal>uncompressed</literal>, <literal>xz</literal>, - <literal>gzip</literal>, <literal>bzip2</literal>. By default, - the format is determined automatically from the image file - name passed.</para></listitem> - </varlistentry> - - <xi:include href="user-system-options.xml" xpointer="host" /> - <xi:include href="user-system-options.xml" xpointer="machine" /> - - <xi:include href="standard-options.xml" xpointer="no-pager" /> - <xi:include href="standard-options.xml" xpointer="no-legend" /> - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </variablelist> - </refsect1> - - <refsect1> - <title>Commands</title> - - <para>The following commands are understood:</para> - - <refsect2><title>Machine Commands</title><variablelist> - - <varlistentry> - <term><command>list</command></term> - - <listitem><para>List currently running (online) virtual - machines and containers. To enumerate machine images that can - be started, use <command>list-images</command> (see - below). Note that this command hides the special - <literal>.host</literal> machine by default. Use the - <option>--all</option> switch to show it.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>status</command> <replaceable>NAME</replaceable>...</term> - - <listitem><para>Show runtime status information about - one or more virtual machines and containers, followed by the - 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. Note that the log data shown is reported by the - virtual machine or container manager, and frequently contains - console output of the machine, but not necessarily journal - contents of the machine itself.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>show</command> [<replaceable>NAME</replaceable>...]</term> - - <listitem><para>Show properties of one or more registered - virtual machines or containers or the manager itself. If no - argument is specified, properties of the manager will be - shown. If an NAME is specified, properties of this virtual - machine or container 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, and does - not print the cgroup tree or journal entries. Use - <command>status</command> if you are looking for formatted - human-readable output.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>start</command> <replaceable>NAME</replaceable>...</term> - - <listitem><para>Start a container as a system service, using - <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>. - This starts <filename>systemd-nspawn@.service</filename>, - instantiated for the specified machine name, similar to the - effect of <command>systemctl start</command> on the service - name. <command>systemd-nspawn</command> looks for a container - image by the specified name in - <filename>/var/lib/machines/</filename> (and other search - paths, see below) and runs it. Use - <command>list-images</command> (see below) for listing - available container images to start.</para> - - <para>Note that - <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - also interfaces with a variety of other container and VM - managers, <command>systemd-nspawn</command> is just one - implementation of it. Most of the commands available in - <command>machinectl</command> may be used on containers or VMs - controlled by other managers, not just - <command>systemd-nspawn</command>. Starting VMs and container - images on those managers requires manager-specific - tools.</para> - - <para>To interactively start a container on the command line - with full access to the container's console, please invoke - <command>systemd-nspawn</command> directly. To stop a running - container use <command>machinectl poweroff</command>, see - below.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>login</command> [<replaceable>NAME</replaceable>]</term> - - <listitem><para>Open an interactive terminal login session in - a container or on the local host. If an argument is supplied, - it refers to the container machine to connect to. If none is - specified, or the container name is specified as the empty - string, or the special machine name <literal>.host</literal> - (see below) is specified, the connection is made to the local - host instead. This will create a TTY connection to a specific - container or the local host and asks for the execution of a - getty on it. Note that this is only supported for containers - running - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> - as init system.</para> - - <para>This command will open a full login prompt on the - container or the local host, which then asks for username and - password. Use <command>shell</command> (see below) or - <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry> - with the <option>--machine=</option> switch to directly invoke - a single command, either interactively or in the - background.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>shell</command> [[<replaceable>NAME</replaceable>@]<replaceable>NAME</replaceable> [<replaceable>PATH</replaceable> [<replaceable>ARGUMENTS</replaceable>...]]] </term> - - <listitem><para>Open an interactive shell session in a - container or on the local host. The first argument refers to - the container machine to connect to. If none is specified, or - the machine name is specified as the empty string, or the - special machine name <literal>.host</literal> (see below) is - specified, the connection is made to the local host - instead. This works similar to <command>login</command> but - immediately invokes a user process. This command runs the - specified executable with the specified arguments, or - <filename>/bin/sh</filename> if none is specified. By default, - opens a <literal>root</literal> shell, but by using - <option>--uid=</option>, or by prefixing the machine name with - a username and an <literal>@</literal> character, a different - user may be selected. Use <option>--setenv=</option> to set - environment variables for the executed process.</para> - - <para>When using the <command>shell</command> command without - arguments, (thus invoking the executed shell or command on the - local host), it is in many ways similar to a <citerefentry - project='die-net'><refentrytitle>su</refentrytitle><manvolnum>1</manvolnum></citerefentry> - session, but, unlike <command>su</command>, completely isolates - the new session from the originating session, so that it - shares no process or session properties, and is in a clean and - well-defined state. It will be tracked in a new utmp, login, - audit, security and keyring session, and will not inherit any - environment variables or resource limits, among other - properties.</para> - - <para>Note that - <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry> - may be used in place of the <command>shell</command> command, - and allows more detailed, low-level configuration of the - invoked unit. However, it is frequently more privileged than - the <command>shell</command> command.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>enable</command> <replaceable>NAME</replaceable>...</term> - <term><command>disable</command> <replaceable>NAME</replaceable>...</term> - - <listitem><para>Enable or disable a container as a system - service to start at system boot, using - <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>. - This enables or disables - <filename>systemd-nspawn@.service</filename>, instantiated for - the specified machine name, similar to the effect of - <command>systemctl enable</command> or <command>systemctl - disable</command> on the service name.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>poweroff</command> <replaceable>NAME</replaceable>...</term> - - <listitem><para>Power off one or more containers. This will - trigger a reboot by sending SIGRTMIN+4 to the container's init - process, which causes systemd-compatible init systems to shut - down cleanly. This operation does not work on containers that - do not run a - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible - init system, such as sysvinit. Use - <command>terminate</command> (see below) to immediately - terminate a container or VM, without cleanly shutting it - down.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>reboot</command> <replaceable>NAME</replaceable>...</term> - - <listitem><para>Reboot one or more containers. This will - trigger a reboot by sending SIGINT to the container's init - process, which is roughly equivalent to pressing Ctrl+Alt+Del - on a non-containerized system, and is compatible with - containers running any system manager.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>terminate</command> <replaceable>NAME</replaceable>...</term> - - <listitem><para>Immediately terminates a virtual machine or - container, without cleanly shutting it down. This kills all - processes of the virtual machine or container and deallocates - all resources attached to that instance. Use - <command>poweroff</command> to issue a clean shutdown - request.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>kill</command> <replaceable>NAME</replaceable>...</term> - - <listitem><para>Send a signal to one or more processes of the - virtual machine or container. This means processes as seen by - the host, not the processes inside the virtual machine or - container. 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>bind</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term> - - <listitem><para>Bind mounts a directory from the host into the - specified container. The first directory argument is the - source directory on the host, the second directory argument - is the destination directory in the container. When the - latter is omitted, the destination path in the container is - the same as the source path on the host. When combined with - the <option>--read-only</option> switch, a ready-only bind - mount is created. When combined with the - <option>--mkdir</option> switch, the destination path is first - created before the mount is applied. Note that this option is - currently only supported for - <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> - containers.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>copy-to</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term> - - <listitem><para>Copies files or directories from the host - system into a running container. Takes a container name, - followed by the source path on the host and the destination - path in the container. If the destination path is omitted, the - same as the source path is used.</para></listitem> - </varlistentry> - - - <varlistentry> - <term><command>copy-from</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term> - - <listitem><para>Copies files or directories from a container - into the host system. Takes a container name, followed by the - source path in the container the destination path on the host. - If the destination path is omitted, the same as the source path - is used.</para></listitem> - </varlistentry> - </variablelist></refsect2> - - <refsect2><title>Image Commands</title><variablelist> - - <varlistentry> - <term><command>list-images</command></term> - - <listitem><para>Show a list of locally installed container and - VM images. This enumerates all raw disk images and container - directories and subvolumes in - <filename>/var/lib/machines/</filename> (and other search - paths, see below). Use <command>start</command> (see above) to - run a container off one of the listed images. Note that, by - default, containers whose name begins with a dot - (<literal>.</literal>) are not shown. To show these too, - specify <option>--all</option>. Note that a special image - <literal>.host</literal> always implicitly exists and refers - to the image the host itself is booted from.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>image-status</command> [<replaceable>NAME</replaceable>...]</term> - - <listitem><para>Show terse status information about one or - more container or VM images. This function is intended to - generate human-readable output. Use - <command>show-image</command> (see below) to generate - computer-parsable output instead.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>show-image</command> [<replaceable>NAME</replaceable>...]</term> - - <listitem><para>Show properties of one or more registered - virtual machine or container images, or the manager itself. If - no argument is specified, properties of the manager will be - shown. If an NAME is specified, properties of this virtual - machine or container image 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>image-status</command> if you are looking for - formatted human-readable output.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>clone</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term> - - <listitem><para>Clones a container or VM image. The arguments specify the name of the image to clone and the - name of the newly cloned image. Note that plain directory container images are cloned into btrfs subvolume - images with this command, if the underlying file system supports this. Note that cloning a container or VM - image is optimized for btrfs file systems, and might not be efficient on others, due to file system - limitations.</para> - - <para>Note that this command leaves host name, machine ID and - all other settings that could identify the instance - unmodified. The original image and the cloned copy will hence - share these credentials, and it might be necessary to manually - change them in the copy.</para> - - <para>If combined with the <option>--read-only</option> switch a read-only cloned image is - created.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>rename</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term> - - <listitem><para>Renames a container or VM image. The - arguments specify the name of the image to rename and the new - name of the image.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>read-only</command> <replaceable>NAME</replaceable> [<replaceable>BOOL</replaceable>]</term> - - <listitem><para>Marks or (unmarks) a container or VM image - read-only. Takes a VM or container image name, followed by a - boolean as arguments. If the boolean is omitted, positive is - implied, i.e. the image is marked read-only.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>remove</command> <replaceable>NAME</replaceable>...</term> - - <listitem><para>Removes one or more container or VM images. - The special image <literal>.host</literal>, which refers to - the host's own directory tree, may not be - removed.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>set-limit</command> [<replaceable>NAME</replaceable>] <replaceable>BYTES</replaceable></term> - - <listitem><para>Sets the maximum size in bytes that a specific - container or VM image, or all images, may grow up to on disk - (disk quota). Takes either one or two parameters. The first, - optional parameter refers to a container or VM image name. If - specified, the size limit of the specified image is changed. If - omitted, the overall size limit of the sum of all images stored - locally is changed. The final argument specifies the size - limit in bytes, possibly suffixed by the usual K, M, G, T - units. If the size limit shall be disabled, specify - <literal>-</literal> as size.</para> - - <para>Note that per-container size limits are only supported - on btrfs file systems. Also note that, if - <command>set-limit</command> is invoked without an image - parameter, and <filename>/var/lib/machines</filename> is - empty, and the directory is not located on btrfs, a btrfs - loopback file is implicitly created as - <filename>/var/lib/machines.raw</filename> with the given - size, and mounted to - <filename>/var/lib/machines</filename>. The size of the - loopback may later be readjusted with - <command>set-limit</command>, as well. If such a - loopback-mounted <filename>/var/lib/machines</filename> - directory is used, <command>set-limit</command> without an image - name alters both the quota setting within the file system as - well as the loopback file and file system size - itself.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>clean</command></term> - - <listitem><para>Remove hidden VM or container images (or all). This command removes all hidden machine images - from <filename>/var/lib/machines</filename>, i.e. those whose name begins with a dot. Use <command>machinectl - list-images --all</command> to see a list of all machine images, including the hidden ones.</para> - - <para>When combined with the <option>--all</option> switch removes all images, not just hidden ones. This - command effectively empties <filename>/var/lib/machines</filename>.</para> - - <para>Note that commands such as <command>machinectl pull-tar</command> or <command>machinectl - pull-raw</command> usually create hidden, read-only, unmodified machine images from the downloaded image first, - before cloning a writable working copy of it, in order to avoid duplicate downloads in case of images that are - reused multiple times. Use <command>machinectl clean</command> to remove old, hidden images created this - way.</para></listitem> - </varlistentry> - - </variablelist></refsect2> - - <refsect2><title>Image Transfer Commands</title><variablelist> - - <varlistentry> - <term><command>pull-tar</command> <replaceable>URL</replaceable> [<replaceable>NAME</replaceable>]</term> - - <listitem><para>Downloads a <filename>.tar</filename> - container image from the specified URL, and makes it available - under the specified local machine name. The URL must be of - type <literal>http://</literal> or - <literal>https://</literal>, and must refer to a - <filename>.tar</filename>, <filename>.tar.gz</filename>, - <filename>.tar.xz</filename> or <filename>.tar.bz2</filename> - archive file. If the local machine name is omitted, it - is automatically derived from the last component of the URL, - with its suffix removed.</para> - - <para>The image is verified before it is made available, - unless <option>--verify=no</option> is specified. Verification - is done via SHA256SUMS and SHA256SUMS.gpg files that need to - be made available on the same web server, under the same URL - as the <filename>.tar</filename> file, but with the last - component (the filename) of the URL replaced. With - <option>--verify=checksum</option>, only the SHA256 checksum - for the file is verified, based on the - <filename>SHA256SUMS</filename> file. With - <option>--verify=signature</option>, the SHA256SUMS file is - first verified with detached GPG signature file - <filename>SHA256SUMS.gpg</filename>. The public key for this - verification step needs to be available in - <filename>/usr/lib/systemd/import-pubring.gpg</filename> or - <filename>/etc/systemd/import-pubring.gpg</filename>.</para> - - <para>The container image will be downloaded and stored in a - read-only subvolume in - <filename>/var/lib/machines/</filename> that is named after - the specified URL and its HTTP etag. A writable snapshot is - then taken from this subvolume, and named after the specified - local name. This behavior ensures that creating multiple - container instances of the same URL is efficient, as multiple - downloads are not necessary. In order to create only the - read-only image, and avoid creating its writable snapshot, - specify <literal>-</literal> as local machine name.</para> - - <para>Note that the read-only subvolume is prefixed with - <filename>.tar-</filename>, and is thus not shown by - <command>list-images</command>, unless <option>--all</option> - is passed.</para> - - <para>Note that pressing C-c during execution of this command - will not abort the download. Use - <command>cancel-transfer</command>, described - below.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>pull-raw</command> <replaceable>URL</replaceable> [<replaceable>NAME</replaceable>]</term> - - <listitem><para>Downloads a <filename>.raw</filename> - container or VM disk image from the specified URL, and makes - it available under the specified local machine name. The URL - must be of type <literal>http://</literal> or - <literal>https://</literal>. The container image must either - be a <filename>.qcow2</filename> or raw disk image, optionally - compressed as <filename>.gz</filename>, - <filename>.xz</filename>, or <filename>.bz2</filename>. If the - local machine name is omitted, it is automatically - derived from the last component of the URL, with its suffix - removed.</para> - - <para>Image verification is identical for raw and tar images - (see above).</para> - - <para>If the downloaded image is in - <filename>.qcow2</filename> format it is converted into a raw - image file before it is made available.</para> - - <para>Downloaded images of this type will be placed as - read-only <filename>.raw</filename> file in - <filename>/var/lib/machines/</filename>. A local, writable - (reflinked) copy is then made under the specified local - machine name. To omit creation of the local, writable copy - pass <literal>-</literal> as local machine name.</para> - - <para>Similar to the behavior of <command>pull-tar</command>, - the read-only image is prefixed with - <filename>.raw-</filename>, and thus not shown by - <command>list-images</command>, unless <option>--all</option> - is passed.</para> - - <para>Note that pressing C-c during execution of this command - will not abort the download. Use - <command>cancel-transfer</command>, described - below.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>import-tar</command> <replaceable>FILE</replaceable> [<replaceable>NAME</replaceable>]</term> - <term><command>import-raw</command> <replaceable>FILE</replaceable> [<replaceable>NAME</replaceable>]</term> - <listitem><para>Imports a TAR or RAW container or VM image, - and places it under the specified name in - <filename>/var/lib/machines/</filename>. When - <command>import-tar</command> is used, the file specified as - the first argument should be a tar archive, possibly compressed - with xz, gzip or bzip2. It will then be unpacked into its own - subvolume in <filename>/var/lib/machines</filename>. When - <command>import-raw</command> is used, the file should be a - qcow2 or raw disk image, possibly compressed with xz, gzip or - bzip2. If the second argument (the resulting image name) is - not specified, it is automatically derived from the file - name. If the file name is passed as <literal>-</literal>, the - image is read from standard input, in which case the second - argument is mandatory.</para> - - <para>Both <command>pull-tar</command> and <command>pull-raw</command> - will resize <filename>/var/lib/machines.raw</filename> and the - filesystem therein as necessary. Optionally, the - <option>--read-only</option> switch may be used to create a - read-only container or VM image. No cryptographic validation - is done when importing the images.</para> - - <para>Much like image downloads, ongoing imports may be listed - with <command>list-transfers</command> and aborted with - <command>cancel-transfer</command>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>export-tar</command> <replaceable>NAME</replaceable> [<replaceable>FILE</replaceable>]</term> - <term><command>export-raw</command> <replaceable>NAME</replaceable> [<replaceable>FILE</replaceable>]</term> - <listitem><para>Exports a TAR or RAW container or VM image and - stores it in the specified file. The first parameter should be - a VM or container image name. The second parameter should be a - file path the TAR or RAW image is written to. If the path ends - in <literal>.gz</literal>, the file is compressed with gzip, if - it ends in <literal>.xz</literal>, with xz, and if it ends in - <literal>.bz2</literal>, with bzip2. If the path ends in - neither, the file is left uncompressed. If the second argument - is missing, the image is written to standard output. The - compression may also be explicitly selected with the - <option>--format=</option> switch. This is in particular - useful if the second parameter is left unspecified.</para> - - <para>Much like image downloads and imports, ongoing exports - may be listed with <command>list-transfers</command> and - aborted with - <command>cancel-transfer</command>.</para> - - <para>Note that, currently, only directory and subvolume images - may be exported as TAR images, and only raw disk images as RAW - images.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>list-transfers</command></term> - - <listitem><para>Shows a list of container or VM image - downloads, imports and exports that are currently in - progress.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>cancel-transfers</command> <replaceable>ID</replaceable>...</term> - - <listitem><para>Aborts a download, import or export of the - container or VM image with the specified ID. To list ongoing - transfers and their IDs, use - <command>list-transfers</command>. </para></listitem> - </varlistentry> - - </variablelist></refsect2> - - </refsect1> - - <refsect1> - <title>Machine and Image Names</title> - - <para>The <command>machinectl</command> tool operates on machines - and images whose names must be chosen following strict - rules. Machine names must be suitable for use as host names - following a conservative subset of DNS and UNIX/Linux - semantics. Specifically, they must consist of one or more - non-empty label strings, separated by dots. No leading or trailing - dots are allowed. No sequences of multiple dots are allowed. The - label strings may only consist of alphanumeric characters as well - as the dash and underscore. The maximum length of a machine name - is 64 characters.</para> - - <para>A special machine with the name <literal>.host</literal> - refers to the running host system itself. This is useful for execution - operations or inspecting the host system as well. Note that - <command>machinectl list</command> will not show this special - machine unless the <option>--all</option> switch is specified.</para> - - <para>Requirements on image names are less strict, however, they must be - valid UTF-8, must be suitable as file names (hence not be the - single or double dot, and not include a slash), and may not - contain control characters. Since many operations search for an - image by the name of a requested machine, it is recommended to name - images in the same strict fashion as machines.</para> - - <para>A special image with the name <literal>.host</literal> - refers to the image of the running host system. It hence - conceptually maps to the special <literal>.host</literal> machine - name described above. Note that <command>machinectl - list-images</command> will not show this special image either, unless - <option>--all</option> is specified.</para> - </refsect1> - - <refsect1> - <title>Files and Directories</title> - - <para>Machine images are preferably stored in - <filename>/var/lib/machines/</filename>, but are also searched for - in <filename>/usr/local/lib/machines/</filename> and - <filename>/usr/lib/machines/</filename>. For compatibility reasons, - the directory <filename>/var/lib/container/</filename> is - searched, too. Note that images stored below - <filename>/usr</filename> are always considered read-only. It is - possible to symlink machines images from other directories into - <filename>/var/lib/machines/</filename> to make them available for - control with <command>machinectl</command>.</para> - - <para>Note that many image operations are only supported, - efficient or atomic on btrfs file systems. Due to this, if the - <command>pull-tar</command>, <command>pull-raw</command>, - <command>import-tar</command>, <command>import-raw</command> and - <command>set-limit</command> commands notice that - <filename>/var/lib/machines</filename> is empty and not located on - btrfs, they will implicitly set up a loopback file - <filename>/var/lib/machines.raw</filename> containing a btrfs file - system that is mounted to - <filename>/var/lib/machines</filename>. The size of this loopback - file may be controlled dynamically with - <command>set-limit</command>.</para> - - <para>Disk images are understood by - <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> - and <command>machinectl</command> in three formats:</para> - - <itemizedlist> - <listitem><para>A simple directory tree, containing the files - and directories of the container to boot.</para></listitem> - - <listitem><para>Subvolumes (on btrfs file systems), which are - similar to the simple directories, described above. However, - they have additional benefits, such as efficient cloning and - quota reporting.</para></listitem> - - <listitem><para>"Raw" disk images, i.e. binary images of disks - with a GPT or MBR partition table. Images of this type are - regular files with the suffix - <literal>.raw</literal>.</para></listitem> - </itemizedlist> - - <para>See - <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> - for more information on image formats, in particular its - <option>--directory=</option> and <option>--image=</option> - options.</para> - </refsect1> - - <refsect1> - <title>Examples</title> - <example> - <title>Download an Ubuntu image and open a shell in it</title> - - <programlisting># machinectl pull-tar https://cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-root.tar.gz -# systemd-nspawn -M trusty-server-cloudimg-amd64-root</programlisting> - - <para>This downloads and verifies the specified - <filename>.tar</filename> image, and then uses - <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> - to open a shell in it.</para> - </example> - - <example> - <title>Download a Fedora image, set a root password in it, start - it as service</title> - - <programlisting># machinectl pull-raw --verify=no https://dl.fedoraproject.org/pub/fedora/linux/releases/23/Cloud/x86_64/Images/Fedora-Cloud-Base-23-20151030.x86_64.raw.xz -# systemd-nspawn -M Fedora-Cloud-Base-23-20151030 -# passwd -# exit -# machinectl start Fedora-Cloud-Base-23-20151030 -# machinectl login Fedora-Cloud-Base-23-20151030</programlisting> - - <para>This downloads the specified <filename>.raw</filename> - image with verification disabled. Then, a shell is opened in it - and a root password is set. Afterwards the shell is left, and - the machine started as system service. With the last command a - login prompt into the container is requested.</para> - </example> - - <example> - <title>Exports a container image as tar file</title> - - <programlisting># machinectl export-tar fedora myfedora.tar.xz</programlisting> - - <para>Exports the container <literal>fedora</literal> as an - xz-compressed tar file <filename>myfedora.tar.xz</filename> into the - current directory.</para> - </example> - - <example> - <title>Create a new shell session</title> - - <programlisting># machinectl shell --uid=lennart</programlisting> - - <para>This creates a new shell session on the local host for - the user ID <literal>lennart</literal>, in a <citerefentry - project='die-net'><refentrytitle>su</refentrytitle><manvolnum>1</manvolnum></citerefentry>-like - fashion.</para> - </example> - - </refsect1> - - <refsect1> - <title>Exit status</title> - - <para>On success, 0 is returned, a non-zero failure code - otherwise.</para> - </refsect1> - - <xi:include href="less-variables.xml" /> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>tar</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>xz</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>gzip</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>bzip2</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/modules-load.d.xml b/man/modules-load.d.xml deleted file mode 100644 index 4b722aa128..0000000000 --- a/man/modules-load.d.xml +++ /dev/null @@ -1,101 +0,0 @@ -<?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" conditional='HAVE_KMOD' - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <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/<replaceable>program</replaceable>.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> - </refsect1> - - <xi:include href="standard-conf.xml" xpointer="confd" /> - - <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 project='man-pages'><refentrytitle>modprobe</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/networkctl.xml b/man/networkctl.xml deleted file mode 100644 index 24e1de6986..0000000000 --- a/man/networkctl.xml +++ /dev/null @@ -1,193 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2015 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="networkctl" conditional='ENABLE_NETWORKD' - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>networkctl</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Documentation</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>networkctl</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>networkctl</refname> - <refpurpose>Query the status of network links</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>networkctl</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="plain">COMMAND</arg> - <arg choice="opt" rep="repeat">LINK</arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>networkctl</command> may be used to introspect the - state of the network links as seen by - <command>systemd-networkd</command>. Please refer to - <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for an introduction to the basic concepts, functionality, and - configuration syntax.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term> - <option>-a</option> - <option>--all</option> - </term> - - <listitem> - <para>Show all links with <command>status</command>.</para> - </listitem> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - <xi:include href="standard-options.xml" xpointer="no-legend" /> - <xi:include href="standard-options.xml" xpointer="no-pager" /> - - </variablelist> - </refsect1> - - <refsect1> - <title>Commands</title> - - <para>The following commands are understood:</para> - - <variablelist> - <varlistentry> - <term> - <command>list</command> - <optional><replaceable>LINK...</replaceable></optional> - </term> - - <listitem> - <para>Show a list of existing links and their status. If no further arguments are specified shows all links, - otherwise just the specified links. Produces output similar to: - - <programlisting>IDX LINK TYPE OPERATIONAL SETUP - 1 lo loopback carrier unmanaged - 2 eth0 ether routable configured - 3 virbr0 ether no-carrier unmanaged - 4 virbr0-nic ether off unmanaged - -4 links listed.</programlisting></para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <command>status</command> - <optional><replaceable>LINK...</replaceable></optional> - </term> - - <listitem> - <para>Show information about the specified links: type, - state, kernel module driver, hardware and IP address, - configured DNS servers, etc.</para> - - <para>When no links are specified, an overall network status is shown. Also see the option - <option>--all</option>.</para> - - <para>Produces output similar to: - <programlisting> -● State: routable - Address: 10.193.76.5 on eth0 - 192.168.122.1 on virbr0 - 169.254.190.105 on eth0 - fe80::5054:aa:bbbb:cccc on eth0 - Gateway: 10.193.11.1 (CISCO SYSTEMS, INC.) on eth0 - DNS: 8.8.8.8 - 8.8.4.4</programlisting></para> - </listitem> - - </varlistentry> - - <varlistentry> - <term> - <command>lldp</command> - <optional><replaceable>LINK...</replaceable></optional> - </term> - - <listitem> - <para>Show discovered LLDP (Link Layer Discovery Protocol) neighbors. If one or more link names are specified - only neighbors on those interfaces are shown. Otherwise shows discovered neighbors on all interfaces. Note - that for this feature to work, <varname>LLDP=</varname> must be turned on on the specific interface, see - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for - details.</para> - - <para>Produces output similar to: - <programlisting>LINK CHASSIS ID SYSTEM NAME CAPS PORT ID PORT DESCRIPTION -enp0s25 00:e0:4c:00:00:00 GS1900 ..b........ 2 Port #2 - -Capability Flags: -o - Other; p - Repeater; b - Bridge; w - WLAN Access Point; r - Router; -t - Telephone; d - DOCSIS cable device; a - Station; c - Customer VLAN; -s - Service VLAN, m - Two-port MAC Relay (TPMR) - -1 neighbors listed.</programlisting></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-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry> - </para> - </refsect1> -</refentry> diff --git a/man/networkd.conf.xml b/man/networkd.conf.xml deleted file mode 100644 index 4bfc4f773a..0000000000 --- a/man/networkd.conf.xml +++ /dev/null @@ -1,154 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2014 Vinay Kulkarni - - 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="networkd.conf" conditional='ENABLE_NETWORKD' - xmlns:xi="http://www.w3.org/2001/XInclude"> - <refentryinfo> - <title>networkd.conf</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Vinay</firstname> - <surname>Kulkarni</surname> - <email>kulkarniv@vmware.com</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>networkd.conf</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>networkd.conf</refname> - <refname>networkd.conf.d</refname> - <refpurpose>Global Network configuration files</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/etc/systemd/networkd.conf</filename></para> - <para><filename>/etc/systemd/networkd.conf.d/*.conf</filename></para> - <para><filename>/usr/lib/systemd/networkd.conf.d/*.conf</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>These configuration files control global network parameters. - Currently the DHCP Unique Identifier (DUID).</para> - - </refsect1> - - <xi:include href="standard-conf.xml" xpointer="main-conf" /> - - <refsect1> - <title>[DHCP] Section Options</title> - - <para>This section configures the DHCP Unique Identifier (DUID) value used by DHCP - protocol. DHCPv6 client protocol sends the DHCP Unique Identifier and the interface - Identity Association Identifier (IAID) to a DHCP server when acquiring a dynamic IPv6 - address. DHCPv4 client protocol sends IAID and DUID to the DHCP server when acquiring - a dynamic IPv4 address if <option>ClientIdentifier=duid</option>. IAID and DUID allows - a DHCP server to uniquely identify the machine and the interface requesting a DHCP IP. - To configure IAID and ClientIdentifier, see - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - </para> - - <para>The following options are understood:</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>DUIDType=</varname></term> - <listitem><para>Specifies how the DUID should be generated. See - <ulink url="https://tools.ietf.org/html/rfc3315#section-9">RFC 3315</ulink> - for a description of all the options.</para> - - <para>The following values are understood: - <variablelist> - <varlistentry> - <term><option>vendor</option> </term> - <listitem><para>If <literal>DUIDType=vendor</literal>, then the DUID value will be generated using - <literal>43793</literal> as the vendor identifier (systemd) and hashed contents of - <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - This is the default if <varname>DUIDType=</varname> is not specified. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>link-layer-time</option> </term> - <term><option>link-layer</option> </term> - <term><option>uuid</option> </term> - <listitem><para>Those values are parsed and can be used to set the DUID type - field, but DUID contents must be provided using <varname>DUIDRawData=</varname>. - </para></listitem> - </varlistentry> - </variablelist> - </para> - - <para>In all cases, <varname>DUIDRawData=</varname> can be used to override the - actual DUID value that is used.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>DUIDRawData=</varname></term> - <listitem><para>Specifies the DHCP DUID value as a single newline-terminated, hexadecimal string, with each - byte separated by <literal>:</literal>. The DUID that is sent is composed of the DUID type specified by - <varname>DUIDType=</varname> and the value configured here.</para> - - <para>The DUID value specified here overrides the DUID that systemd-networkd generates using the machine-id - from the <filename>/etc/machine-id</filename> file. To configure DUID per-network, see - <citerefentry><refentrytitle>systemd.network </refentrytitle><manvolnum>5</manvolnum></citerefentry>. - The configured DHCP DUID should conform to the specification in - <ulink url="http://tools.ietf.org/html/rfc3315#section-9">RFC 3315</ulink>, - <ulink url="http://tools.ietf.org/html/rfc6355">RFC 6355</ulink>. To configure IAID, see - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum> - </citerefentry>.</para> - - <example> - <title>A <option>DUIDType=vendor</option> with a custom value</title> - - <programlisting>DUIDType=vendor -DUIDRawData=00:00:ab:11:f9:2a:c2:77:29:f9:5c:00</programlisting> - - <para>This specifies a 14 byte DUID, with the type DUID-EN (<literal>00:02</literal>), enterprise number - 43793 (<literal>00:00:ab:11</literal>), and identifier value <literal>f9:2a:c2:77:29:f9:5c:00</literal>. - </para> - </example> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/nss-myhostname.xml b/man/nss-myhostname.xml deleted file mode 100644 index a920ec334f..0000000000 --- a/man/nss-myhostname.xml +++ /dev/null @@ -1,148 +0,0 @@ -<?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 - Copyright 2013 Tom Gundersen - - 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="nss-myhostname" conditional='HAVE_MYHOSTNAME'> - - <refentryinfo> - <title>nss-myhostname</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>nss-myhostname</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>nss-myhostname</refname> - <refname>libnss_myhostname.so.2</refname> - <refpurpose>Provide hostname resolution for the locally - configured system hostname.</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>libnss_myhostname.so.2</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>nss-myhostname</command> is a plug-in module for the GNU Name Service Switch (NSS) functionality of - the GNU C Library (<command>glibc</command>), primarily providing hostname resolution for the locally configured - system hostname as returned by - <citerefentry><refentrytitle>gethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>. The precise - hostnames resolved by this module are:</para> - - <itemizedlist> - <listitem><para>The local, configured hostname is resolved to - all locally configured IP addresses ordered by their scope, or - — if none are configured — the IPv4 address 127.0.0.2 (which - is on the local loopback) and the IPv6 address ::1 (which is the - local host).</para></listitem> - - <listitem><para>The hostnames <literal>localhost</literal> and - <literal>localhost.localdomain</literal> (as well as any hostname - ending in <literal>.localhost</literal> or <literal>.localhost.localdomain</literal>) - are resolved to the IP addresses 127.0.0.1 and ::1.</para></listitem> - - <listitem><para>The hostname <literal>gateway</literal> is - resolved to all current default routing gateway addresses, - ordered by their metric. This assigns a stable hostname to the - current gateway, useful for referencing it independently of the - current network configuration state.</para></listitem> - </itemizedlist> - - <para>Various software relies on an always-resolvable local - hostname. When using dynamic hostnames, this is traditionally - achieved by patching <filename>/etc/hosts</filename> at the same - time as changing the hostname. This is problematic since it - requires a writable <filename>/etc</filename> file system and is - fragile because the file might be edited by the administrator at - the same time. With <command>nss-myhostname</command> enabled, - changing <filename>/etc/hosts</filename> is unnecessary, and on - many systems, the file becomes entirely optional.</para> - - <para>To activate the NSS modules, add <literal>myhostname</literal> to the line starting with - <literal>hosts:</literal> in <filename>/etc/nsswitch.conf</filename>.</para> - - <para>It is recommended to place <literal>myhostname</literal> last in the <filename>nsswitch.conf</filename>' - <literal>hosts:</literal> line to make sure that this mapping is only used as fallback, and that any DNS or - <filename>/etc/hosts</filename> based mapping takes precedence.</para> - </refsect1> - - <refsect1> - <title>Example</title> - - <para>Here is an example <filename>/etc/nsswitch.conf</filename> file that enables - <command>nss-myhostname</command> correctly:</para> - -<programlisting>passwd: compat mymachines -group: compat mymachines -shadow: compat - -hosts: files mymachines resolve <command>myhostname</command> -networks: files - -protocols: db files -services: db files -ethers: db files -rpc: db files - -netgroup: nis</programlisting> - - <para>To test, use <command>glibc</command>'s <command>getent</command> tool:</para> - - <programlisting>$ getent ahosts `hostname` -::1 STREAM omega -::1 DGRAM -::1 RAW -127.0.0.2 STREAM -127.0.0.2 DGRAM -127.0.0.2 RAW</programlisting> - - <para>In this case, the local hostname is <varname>omega</varname>.</para> - - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>nss-resolve</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>nsswitch.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>getent</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/nss-mymachines.xml b/man/nss-mymachines.xml deleted file mode 100644 index ec047449bf..0000000000 --- a/man/nss-mymachines.xml +++ /dev/null @@ -1,113 +0,0 @@ -<?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 2014 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="nss-mymachines" conditional='ENABLE_MACHINED'> - - <refentryinfo> - <title>nss-mymachines</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>nss-mymachines</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>nss-mymachines</refname> - <refname>libnss_mymachines.so.2</refname> - <refpurpose>Provide hostname resolution for local - container instances.</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>libnss_mymachines.so.2</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>nss-mymachines</command> is a plug-in module for the GNU Name Service Switch (NSS) functionality of - the GNU C Library (<command>glibc</command>), providing hostname resolution for the names of containers running - locally that are registered with - <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. The - container names are resolved to the IP addresses of the specific container, ordered by their scope. This - functionality only applies to containers using network namespacing.</para> - - <para>The module also resolves user and group IDs used by containers to user and group names indicating the - container name, and back. This functionality only applies to containers using user namespacing.</para> - - <para>To activate the NSS module, add <literal>mymachines</literal> to the lines starting with - <literal>hosts:</literal>, <literal>passwd:</literal> and <literal>group:</literal> in - <filename>/etc/nsswitch.conf</filename>.</para> - - <para>It is recommended to place <literal>mymachines</literal> after the <literal>files</literal> or - <literal>compat</literal> entry of the <filename>/etc/nsswitch.conf</filename> lines to make sure that its mappings - are preferred over other resolvers such as DNS, but so that <filename>/etc/hosts</filename>, - <filename>/etc/passwd</filename> and <filename>/etc/group</filename> based mappings take precedence.</para> - </refsect1> - - <refsect1> - <title>Example</title> - - <para>Here is an example <filename>/etc/nsswitch.conf</filename> file that enables - <command>nss-mymachines</command> correctly:</para> - - <programlisting>passwd: compat <command>mymachines</command> -group: compat <command>mymachines</command> -shadow: compat - -hosts: files <command>mymachines</command> resolve myhostname -networks: files - -protocols: db files -services: db files -ethers: db files -rpc: db files - -netgroup: nis</programlisting> - - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>nss-resolve</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>nsswitch.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>getent</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/nss-resolve.xml b/man/nss-resolve.xml deleted file mode 100644 index d9e56453e8..0000000000 --- a/man/nss-resolve.xml +++ /dev/null @@ -1,111 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 - Copyright 2013 Tom Gundersen - - 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="nss-resolve" conditional='ENABLE_RESOLVED'> - - <refentryinfo> - <title>nss-resolve</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>nss-resolve</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>nss-resolve</refname> - <refname>libnss_resolve.so.2</refname> - <refpurpose>Provide hostname resolution via <filename>systemd-resolved.service</filename></refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>libnss_resolve.so.2</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>nss-resolve</command> is a plug-in module for the GNU Name Service Switch (NSS) functionality of the - GNU C Library (<command>glibc</command>) enabling it to resolve host names via the - <citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry> local network - name resolution service. It replaces the <command>nss-dns</command> plug-in module that traditionally resolves - hostnames via DNS.</para> - - <para>To activate the NSS module, add <literal>resolve</literal> to the line starting with - <literal>hosts:</literal> in <filename>/etc/nsswitch.conf</filename>.</para> - - <para>It is recommended to place <literal>resolve</literal> early in <filename>/etc/nsswitch.conf</filename>' - <literal>hosts:</literal> line (but after the <literal>files</literal> or <literal>mymachines</literal> entries), - replacing the <literal>dns</literal> entry if it exists, to ensure DNS queries are always routed via - <citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> - - <para>Note that <command>nss-resolve</command> will chain-load <command>nss-dns</command> if - <filename>systemd-resolved.service</filename> is not running, ensuring that basic DNS resolution continues to work - if the service is down.</para> - </refsect1> - - <refsect1> - <title>Example</title> - - <para>Here is an example <filename>/etc/nsswitch.conf</filename> file that enables <command>nss-resolve</command> - correctly:</para> - -<programlisting>passwd: compat mymachines -group: compat mymachines -shadow: compat - -hosts: files mymachines <command>resolve</command> myhostname -networks: files - -protocols: db files -services: db files -ethers: db files -rpc: db files - -netgroup: nis</programlisting> - - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>nsswitch.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/pam_systemd.xml b/man/pam_systemd.xml deleted file mode 100644 index ddda81bc90..0000000000 --- a/man/pam_systemd.xml +++ /dev/null @@ -1,296 +0,0 @@ -<?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" conditional='HAVE_PAM'> - - <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> - <para><filename>pam_systemd.so</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>pam_systemd</command> registers user sessions with - 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> was 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 systemd scope unit is created for the - session. If this is the first concurrent session of the user, an - implicit slice below <filename>user.slice</filename> is - automatically created and the scope placed into it. An instance - of the system service <filename>user@.service</filename>, which - runs the systemd user manager instance, is started. - </para></listitem> - </orderedlist> - - <para>On logout, this module ensures the following:</para> - - <orderedlist> - <listitem><para>If enabled in - <citerefentry><refentrytitle>logind.conf</refentrytitle> - <manvolnum>5</manvolnum></citerefentry>, all processes of the - session are terminated. If the last concurrent session of a user - ends, the user's systemd instance will be terminated too, and so - will the user's slice unit.</para></listitem> - - <listitem><para>If the last concurrent session of a user ends, - 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 - <constant>PAM_SUCCESS</constant>.</para> - - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist class='pam-directives'> - - <varlistentry> - <term><option>class=</option></term> - - <listitem><para>Takes a string argument which sets the session - class. The XDG_SESSION_CLASS environmental variable takes - precedence. One of - <literal>user</literal>, - <literal>greeter</literal>, - <literal>lock-screen</literal> or - <literal>background</literal>. See - <citerefentry><refentrytitle>sd_session_get_class</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for details about the session class.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>type=</option></term> - - <listitem><para>Takes a string argument which sets the session - type. The XDG_SESSION_TYPE environmental variable takes - precedence. One of - <literal>unspecified</literal>, - <literal>tty</literal>, - <literal>x11</literal>, - <literal>wayland</literal> or - <literal>mir</literal>. See - <citerefentry><refentrytitle>sd_session_get_type</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for details about the session type.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>debug<optional>=</optional></option></term> - - <listitem><para>Takes an optional - boolean argument. If yes or without - the argument, the module will log - debugging information as it - operates.</para></listitem> - </varlistentry> - </variablelist> - </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 class='environment-variables'> - <varlistentry> - <term><varname>$XDG_SESSION_ID</varname></term> - - <listitem><para>A session identifier, suitable to be used in - filenames. 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 the user's 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 <constant>AF_UNIX</constant> 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. For further details, see the <ulink - url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG - Base Directory Specification</ulink>.</para></listitem> - </varlistentry> - - </variablelist> - - <para>The following environment variables are read by the module - and may be used by the PAM service to pass metadata to the - module:</para> - - <variablelist class='environment-variables'> - <varlistentry> - <term><varname>$XDG_SESSION_TYPE</varname></term> - - <listitem><para>The session type. This may be used instead of - <option>session=</option> on the module parameter line, and is - usually preferred.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$XDG_SESSION_CLASS</varname></term> - - <listitem><para>The session class. This may be used instead of - <option>class=</option> on the module parameter line, and is - usually preferred.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$XDG_SESSION_DESKTOP</varname></term> - - <listitem><para>A single, short identifier string for the - desktop environment. This may be used to indicate the session - desktop used, where this applies and if this information is - available. For example: <literal>GNOME</literal>, or - <literal>KDE</literal>. It is recommended to use the same - identifiers and capitalization as for - <varname>$XDG_CURRENT_DESKTOP</varname>, as defined by the - <ulink - url="http://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop - Entry Specification</ulink>. (However, note that - <varname>$XDG_SESSION_DESKTOP</varname> only takes a single - item, and not a colon-separated list like - <varname>$XDG_CURRENT_DESKTOP</varname>.) See - <citerefentry><refentrytitle>sd_session_get_desktop</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for more details.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$XDG_SEAT</varname></term> - - <listitem><para>The seat name the session shall be registered - for, if any.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$XDG_VTNR</varname></term> - - <listitem><para>The VT number the session shall be registered - for, if any. (Only applies to seats with a VT available, such - as <literal>seat0</literal>)</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</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 project='man-pages'><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>pam_loginuid</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/resolved.conf.xml b/man/resolved.conf.xml deleted file mode 100644 index 920ce9e89b..0000000000 --- a/man/resolved.conf.xml +++ /dev/null @@ -1,219 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2014 Tom Gundersen - - 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="resolved.conf" conditional='ENABLE_RESOLVED' - xmlns:xi="http://www.w3.org/2001/XInclude"> - <refentryinfo> - <title>resolved.conf</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Tom</firstname> - <surname>Gundersen</surname> - <email>teg@jklm.no</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>resolved.conf</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>resolved.conf</refname> - <refname>resolved.conf.d</refname> - <refpurpose>Network Name Resolution configuration files</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/etc/systemd/resolved.conf</filename></para> - <para><filename>/etc/systemd/resolved.conf.d/*.conf</filename></para> - <para><filename>/run/systemd/resolved.conf.d/*.conf</filename></para> - <para><filename>/usr/lib/systemd/resolved.conf.d/*.conf</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>These configuration files control local DNS and LLMNR - name resolution.</para> - - </refsect1> - - <xi:include href="standard-conf.xml" xpointer="main-conf" /> - - <refsect1> - <title>Options</title> - - <para>The following options are available in the <literal>[Resolve]</literal> section:</para> - - <variablelist class='network-directives'> - - <varlistentry> - <term><varname>DNS=</varname></term> - <listitem><para>A space-separated list of IPv4 and IPv6 addresses to use as system DNS servers. DNS requests - are sent to one of the listed DNS servers in parallel to suitable per-link DNS servers acquired from - <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> or - set at runtime by external applications. For compatibility reasons, if this setting is not specified, the DNS - servers listed in <filename>/etc/resolv.conf</filename> are used instead, if that file exists and any servers - are configured in it. This setting defaults to the empty list.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>FallbackDNS=</varname></term> - <listitem><para>A space-separated list of IPv4 and IPv6 addresses to use as the fallback DNS servers. Any - per-link DNS servers obtained from - <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - take precedence over this setting, as do any servers set via <varname>DNS=</varname> above or - <filename>/etc/resolv.conf</filename>. This setting is hence only used if no other DNS server information is - known. If this option is not given, a compiled-in list of DNS servers is used instead.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Domains=</varname></term> - <listitem><para>A space-separated list of domains. These domains are used as search suffixes when resolving - single-label host names (domain names which contain no dot), in order to qualify them into fully-qualified - domain names (FQDNs). Search domains are strictly processed in the order they are specified, until the name - with the suffix appended is found. For compatibility reasons, if this setting is not specified, the search - domains listed in <filename>/etc/resolv.conf</filename> are used instead, if that file exists and any domains - are configured in it. This setting defaults to the empty list.</para> - - <para>Specified domain names may optionally be prefixed with <literal>~</literal>. In this case they do not - define a search path, but preferably direct DNS queries for the indicated domains to the DNS servers configured - with the system <varname>DNS=</varname> setting (see above), in case additional, suitable per-link DNS servers - are known. If no per-link DNS servers are known using the <literal>~</literal> syntax has no effect. Use the - construct <literal>~.</literal> (which is composed of <literal>~</literal> to indicate a routing domain and - <literal>.</literal> to indicate the DNS root domain that is the implied suffix of all DNS domains) to use the - system DNS server defined with <varname>DNS=</varname> preferably for all domains.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>LLMNR=</varname></term> - <listitem><para>Takes a boolean argument or - <literal>resolve</literal>. Controls Link-Local Multicast Name - Resolution support (<ulink - url="https://tools.ietf.org/html/rfc4795">RFC 4794</ulink>) on - the local host. If true, enables full LLMNR responder and - resolver support. If false, disables both. If set to - <literal>resolve</literal>, only resolution support is enabled, - but responding is disabled. Note that - <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - also maintains per-link LLMNR settings. LLMNR will be - enabled on a link only if the per-link and the - global setting is on.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>DNSSEC=</varname></term> - <listitem><para>Takes a boolean argument or - <literal>allow-downgrade</literal>. If true all DNS lookups are - DNSSEC-validated locally (excluding LLMNR and Multicast - DNS). If the response to a lookup request is detected to be invalid - a lookup failure is returned to applications. Note that - this mode requires a DNS server that supports DNSSEC. If the - DNS server does not properly support DNSSEC all validations - will fail. If set to <literal>allow-downgrade</literal> DNSSEC - validation is attempted, but if the server does not support - DNSSEC properly, DNSSEC mode is automatically disabled. Note - that this mode makes DNSSEC validation vulnerable to - "downgrade" attacks, where an attacker might be able to - trigger a downgrade to non-DNSSEC mode by synthesizing a DNS - response that suggests DNSSEC was not supported. If set to - false, DNS lookups are not DNSSEC validated.</para> - - <para>Note that DNSSEC validation requires retrieval of - additional DNS data, and thus results in a small DNS look-up - time penalty.</para> - - <para>DNSSEC requires knowledge of "trust anchors" to prove - data integrity. The trust anchor for the Internet root domain - is built into the resolver, additional trust anchors may be - defined with - <citerefentry><refentrytitle>dnssec-trust-anchors.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - Trust anchors may change at regular intervals, and old trust - anchors may be revoked. In such a case DNSSEC validation is - not possible until new trust anchors are configured locally or - the resolver software package is updated with the new root - trust anchor. In effect, when the built-in trust anchor is - revoked and <varname>DNSSEC=</varname> is true, all further - lookups will fail, as it cannot be proved anymore whether - lookups are correctly signed, or validly unsigned. If - <varname>DNSSEC=</varname> is set to - <literal>allow-downgrade</literal> the resolver will - automatically turn off DNSSEC validation in such a case.</para> - - <para>Client programs looking up DNS data will be informed - whether lookups could be verified using DNSSEC, or whether the - returned data could not be verified (either because the data - was found unsigned in the DNS, or the DNS server did not - support DNSSEC or no appropriate trust anchors were known). In - the latter case it is assumed that client programs employ a - secondary scheme to validate the returned DNS data, should - this be required.</para> - - <para>It is recommended to set <varname>DNSSEC=</varname> to - true on systems where it is known that the DNS server supports - DNSSEC correctly, and where software or trust anchor updates - happen regularly. On other systems it is recommended to set - <varname>DNSSEC=</varname> to - <literal>allow-downgrade</literal>.</para> - - <para>In addition to this global DNSSEC setting - <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - also maintains per-link DNSSEC settings. For system DNS - servers (see above), only the global DNSSEC setting is in - effect. For per-link DNS servers the per-link - setting is in effect, unless it is unset in which case the - global setting is used instead.</para> - - <para>Site-private DNS zones generally conflict with DNSSEC - operation, unless a negative (if the private zone is not - signed) or positive (if the private zone is signed) trust - anchor is configured for them. If - <literal>allow-downgrade</literal> mode is selected, it is - attempted to detect site-private DNS zones using top-level - domains (TLDs) that are not known by the DNS root server. This - logic does not work in all private zone setups.</para> - - <para>Defaults to off.</para> - </listitem> - </varlistentry> - - </variablelist> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>dnssec-trust-anchors.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>4</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/runlevel.xml b/man/runlevel.xml deleted file mode 100644 index ca29c7c22c..0000000000 --- a/man/runlevel.xml +++ /dev/null @@ -1,192 +0,0 @@ -<?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" - xmlns:xi="http://www.w3.org/2001/XInclude" - conditional="HAVE_UTMP"> - - <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</command> - <arg choice="opt" rep="repeat">options</arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Overview</title> - - <para>"Runlevels" are an obsolete way to start and stop groups of - services used in SysV init. systemd provides a compatibility layer - that maps runlevels to targets, and associated binaries like - <command>runlevel</command>. Nevertheless, only one runlevel can - be "active" at a given time, while systemd can activate multiple - targets concurrently, so the mapping to runlevels is confusing - and only approximate. Runlevels should not be used in new code, - and are mostly useful as a shorthand way to refer the matching - systemd targets in kernel boot parameters.</para> - - <table> - <title>Mapping between runlevels and systemd targets</title> - <tgroup cols='2' align='left' colsep='1' rowsep='1'> - <colspec colname="runlevel" /> - <colspec colname="target" /> - <thead> - <row> - <entry>Runlevel</entry> - <entry>Target</entry> - </row> - </thead> - <tbody> - <row> - <entry>0</entry> - <entry><filename>poweroff.target</filename></entry> - </row> - <row> - <entry>1</entry> - <entry><filename>rescue.target</filename></entry> - </row> - <row> - <entry>2, 3, 4</entry> - <entry><filename>multi-user.target</filename></entry> - </row> - <row> - <entry>5</entry> - <entry><filename>graphical.target</filename></entry> - </row> - <row> - <entry>6</entry> - <entry><filename>reboot.target</filename></entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <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> - - <xi:include href="standard-options.xml" xpointer="help-text" /> - </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 class='environment-variables'> - <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><filename>/var/run/utmp</filename></term> - - <listitem><para>The utmp database <command>runlevel</command> - reads the previous and current runlevel - from.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd-bus-errors.xml b/man/sd-bus-errors.xml deleted file mode 100644 index d2b81f4e4a..0000000000 --- a/man/sd-bus-errors.xml +++ /dev/null @@ -1,309 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2015 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-bus-errors"> - - <refentryinfo> - <title>sd-bus-errors</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-bus-errors</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd-bus-errors</refname> - <refname>SD_BUS_ERROR_FAILED</refname> - <refname>SD_BUS_ERROR_NO_MEMORY</refname> - <refname>SD_BUS_ERROR_SERVICE_UNKNOWN</refname> - <refname>SD_BUS_ERROR_NAME_HAS_NO_OWNER</refname> - <refname>SD_BUS_ERROR_NO_REPLY</refname> - <refname>SD_BUS_ERROR_IO_ERROR</refname> - <refname>SD_BUS_ERROR_BAD_ADDRESS</refname> - <refname>SD_BUS_ERROR_NOT_SUPPORTED</refname> - <refname>SD_BUS_ERROR_LIMITS_EXCEEDED</refname> - <refname>SD_BUS_ERROR_ACCESS_DENIED</refname> - <refname>SD_BUS_ERROR_AUTH_FAILED</refname> - <refname>SD_BUS_ERROR_NO_SERVER</refname> - <refname>SD_BUS_ERROR_TIMEOUT</refname> - <refname>SD_BUS_ERROR_NO_NETWORK</refname> - <refname>SD_BUS_ERROR_ADDRESS_IN_USE</refname> - <refname>SD_BUS_ERROR_DISCONNECTED</refname> - <refname>SD_BUS_ERROR_INVALID_ARGS</refname> - <refname>SD_BUS_ERROR_FILE_NOT_FOUND</refname> - <refname>SD_BUS_ERROR_FILE_EXISTS</refname> - <refname>SD_BUS_ERROR_UNKNOWN_METHOD</refname> - <refname>SD_BUS_ERROR_UNKNOWN_OBJECT</refname> - <refname>SD_BUS_ERROR_UNKNOWN_INTERFACE</refname> - <refname>SD_BUS_ERROR_UNKNOWN_PROPERTY</refname> - <refname>SD_BUS_ERROR_PROPERTY_READ_ONLY</refname> - <refname>SD_BUS_ERROR_UNIX_PROCESS_ID_UNKNOWN</refname> - <refname>SD_BUS_ERROR_INVALID_SIGNATURE</refname> - <refname>SD_BUS_ERROR_INCONSISTENT_MESSAGE</refname> - <refname>SD_BUS_ERROR_MATCH_RULE_NOT_FOUND</refname> - <refname>SD_BUS_ERROR_MATCH_RULE_INVALID</refname> - <refname>SD_BUS_ERROR_INTERACTIVE_AUTHORIZATION_REQUIRED</refname> - - <refpurpose>Standard D-Bus error names</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> - -<funcsynopsisinfo>#define SD_BUS_ERROR_FAILED "org.freedesktop.DBus.Error.Failed" -#define SD_BUS_ERROR_NO_MEMORY "org.freedesktop.DBus.Error.NoMemory" -#define SD_BUS_ERROR_SERVICE_UNKNOWN "org.freedesktop.DBus.Error.ServiceUnknown" -#define SD_BUS_ERROR_NAME_HAS_NO_OWNER "org.freedesktop.DBus.Error.NameHasNoOwner" -#define SD_BUS_ERROR_NO_REPLY "org.freedesktop.DBus.Error.NoReply" -#define SD_BUS_ERROR_IO_ERROR "org.freedesktop.DBus.Error.IOError" -#define SD_BUS_ERROR_BAD_ADDRESS "org.freedesktop.DBus.Error.BadAddress" -#define SD_BUS_ERROR_NOT_SUPPORTED "org.freedesktop.DBus.Error.NotSupported" -#define SD_BUS_ERROR_LIMITS_EXCEEDED "org.freedesktop.DBus.Error.LimitsExceeded" -#define SD_BUS_ERROR_ACCESS_DENIED "org.freedesktop.DBus.Error.AccessDenied" -#define SD_BUS_ERROR_AUTH_FAILED "org.freedesktop.DBus.Error.AuthFailed" -#define SD_BUS_ERROR_NO_SERVER "org.freedesktop.DBus.Error.NoServer" -#define SD_BUS_ERROR_TIMEOUT "org.freedesktop.DBus.Error.Timeout" -#define SD_BUS_ERROR_NO_NETWORK "org.freedesktop.DBus.Error.NoNetwork" -#define SD_BUS_ERROR_ADDRESS_IN_USE "org.freedesktop.DBus.Error.AddressInUse" -#define SD_BUS_ERROR_DISCONNECTED "org.freedesktop.DBus.Error.Disconnected" -#define SD_BUS_ERROR_INVALID_ARGS "org.freedesktop.DBus.Error.InvalidArgs" -#define SD_BUS_ERROR_FILE_NOT_FOUND "org.freedesktop.DBus.Error.FileNotFound" -#define SD_BUS_ERROR_FILE_EXISTS "org.freedesktop.DBus.Error.FileExists" -#define SD_BUS_ERROR_UNKNOWN_METHOD "org.freedesktop.DBus.Error.UnknownMethod" -#define SD_BUS_ERROR_UNKNOWN_OBJECT "org.freedesktop.DBus.Error.UnknownObject" -#define SD_BUS_ERROR_UNKNOWN_INTERFACE "org.freedesktop.DBus.Error.UnknownInterface" -#define SD_BUS_ERROR_UNKNOWN_PROPERTY "org.freedesktop.DBus.Error.UnknownProperty" -#define SD_BUS_ERROR_PROPERTY_READ_ONLY "org.freedesktop.DBus.Error.PropertyReadOnly" -#define SD_BUS_ERROR_UNIX_PROCESS_ID_UNKNOWN "org.freedesktop.DBus.Error.UnixProcessIdUnknown" -#define SD_BUS_ERROR_INVALID_SIGNATURE "org.freedesktop.DBus.Error.InvalidSignature" -#define SD_BUS_ERROR_INCONSISTENT_MESSAGE "org.freedesktop.DBus.Error.InconsistentMessage" -#define SD_BUS_ERROR_MATCH_RULE_NOT_FOUND "org.freedesktop.DBus.Error.MatchRuleNotFound" -#define SD_BUS_ERROR_MATCH_RULE_INVALID "org.freedesktop.DBus.Error.MatchRuleInvalid" -#define SD_BUS_ERROR_INTERACTIVE_AUTHORIZATION_REQUIRED \ - "org.freedesktop.DBus.Error.InteractiveAuthorizationRequired"</funcsynopsisinfo> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>In addition to the error names user programs define, D-Bus - knows a number of generic, standardized error names that are - listed below.</para> - - <para>In addition to this list, in sd-bus, the special error - namespace <literal>System.Error.</literal> is used to map - arbitrary GNU/Linux system errors (as defined by <citerefentry - project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>) - to D-Bus errors and back. For example, the error - <constant>EUCLEAN</constant> is mapped to - <literal>System.Error.EUCLEAN</literal> and back.</para> - - <variablelist> - - <varlistentry> - <term><varname>SD_BUS_ERROR_FAILED</varname></term> - <listitem><para>A generic error indication. See the error - message for further details. This error name should be - avoided, in favor of a more expressive error - name.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>SD_BUS_ERROR_NO_MEMORY</varname></term> - <listitem><para>A memory allocation failed, and the requested - operation could not be completed.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>SD_BUS_ERROR_SERVICE_UNKNOWN</varname></term> - <listitem><para>The contacted bus service is unknown and - cannot be activated.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>SD_BUS_ERROR_NAME_HAS_NO_OWNER</varname></term> - <listitem><para>The specified bus service name currently has - no owner.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>SD_BUS_ERROR_NO_REPLY</varname></term> - <listitem><para>A message did not receive a reply. This error - is usually generated after a timeout.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>SD_BUS_ERROR_IO_ERROR</varname></term> - <listitem><para>Generic input/output error, for example when - accessing a socket or other I/O context.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>SD_BUS_ERROR_BAD_ADDRESS</varname></term> - <listitem><para>The specified D-Bus bus address string is - malformed.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>SD_BUS_ERROR_NOT_SUPPORTED</varname></term> - <listitem><para>The requested operation is not supported on - the local system.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>SD_BUS_ERROR_LIMITS_EXCEEDED</varname></term> - <listitem><para>Some limited resource has been - exhausted.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>SD_BUS_ERROR_ACCESS_DENIED</varname></term> - <listitem><para>Access to a resource has been denied due to security restrictions.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>SD_BUS_ERROR_AUTH_FAILED</varname></term> - <listitem><para>Authentication did not complete successfully.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>SD_BUS_ERROR_NO_SERVER</varname></term> - <listitem><para>Unable to connect to the specified server.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>SD_BUS_ERROR_TIMEOUT</varname></term> - <listitem><para>An operation timed out. Note that method calls - which timeout generate a - <varname>SD_BUS_ERROR_NO_REPLY</varname>.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>SD_BUS_ERROR_NO_NETWORK</varname></term> - <listitem><para>No network available to execute requested network operation on.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>SD_BUS_ERROR_ADDRESS_IN_USE</varname></term> - <listitem><para>The specified network address is already being listened on.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>SD_BUS_ERROR_DISCONNECTED</varname></term> - <listitem><para>The connection has been terminated.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>SD_BUS_ERROR_INVALID_ARGS</varname></term> - <listitem><para>One or more invalid arguments have been passed.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>SD_BUS_ERROR_FILE_NOT_FOUND</varname></term> - <listitem><para>The requested file could not be found.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>SD_BUS_ERROR_FILE_EXISTS</varname></term> - <listitem><para>The requested file already exists.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>SD_BUS_ERROR_UNKNOWN_METHOD</varname></term> - <listitem><para>The requested method does not exist in the selected interface.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>SD_BUS_ERROR_UNKNOWN_OBJECT</varname></term> - <listitem><para>The requested object does not exist in the selected service.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>SD_BUS_ERROR_UNKNOWN_INTERFACE</varname></term> - <listitem><para>The requested interface does not exist on the selected object.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>SD_BUS_ERROR_UNKNOWN_PROPERTY</varname></term> - <listitem><para>The requested property does not exist in the selected interface.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>SD_BUS_ERROR_PROPERTY_READ_ONLY</varname></term> - <listitem><para>A write operation was requested on a read-only property.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>SD_BUS_ERROR_UNIX_PROCESS_ID_UNKNOWN</varname></term> - <listitem><para>The requested PID is not known.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>SD_BUS_ERROR_INVALID_SIGNATURE</varname></term> - <listitem><para>The specified message signature is not - valid.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>SD_BUS_ERROR_INCONSISTENT_MESSAGE</varname></term> - <listitem><para>The passed message does not validate - correctly.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>SD_BUS_ERROR_MATCH_RULE_NOT_FOUND</varname></term> - <listitem><para>The specified match rule does not exist.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>SD_BUS_ERROR_MATCH_RULE_INVALID</varname></term> - <listitem><para>The specified match rule is invalid.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>SD_BUS_ERROR_INTERACTIVE_AUTHORIZATION_REQUIRED</varname></term> - <listitem><para>Access to the requested operation is not - permitted. However, it might be available after interactive - authentication. This is usually returned by method calls - supporting a framework for additional interactive - authorization, when interactive authorization was not enabled - with the - <citerefentry><refentrytitle>sd_bus_message_set_allow_interactive_authorization</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for the method call message.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>The various error definitions described here are available - as a shared library, which can be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry - project='die-net'><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-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_message_set_allow_interactive_authorization</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>strerror</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd-bus.xml b/man/sd-bus.xml deleted file mode 100644 index 336dd33ea0..0000000000 --- a/man/sd-bus.xml +++ /dev/null @@ -1,123 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2016 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="sd-bus" xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd-bus</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Documentation</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd-bus</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd-bus</refname> - <refpurpose>A lightweight D-Bus and kdbus client library</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> - </funcsynopsis> - - <cmdsynopsis> - <command>pkg-config --cflags --libs libsystemd</command> - </cmdsynopsis> - - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>sd-bus.h</filename> provides an implementation - of a D-Bus client. It can interoperate both with the traditional - <citerefentry project='man-pages'><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - and with kdbus. See - <ulink url="http://www.freedesktop.org/software/dbus/" /> - for more information about the big picture. - </para> - - <important> - <para>Interfaces described here have not been declared stable yet, - and are not accessible from <filename>libsystemd.so</filename>. - This documentation is provided in hope it might be useful for - developers, without any guarantees of availability or stability. - </para> - </important> - - <para>See - <citerefentry><refentrytitle>sd_bus_default</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_request_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_message_append_array</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_message_append_string_memfd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_message_append_strv</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_message_can_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_message_get_cookie</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_set_address</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_creds_new_from_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_negotiate_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_path_encode</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_set_allow_interactive_authorization</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for more information about the functions available.</para> - </refsect1> - - <xi:include href="libsystemd-pkgconfig.xml" /> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>dbus-send</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <ulink url="https://developer.gnome.org/gio/stable/gdbus.html">gdbus</ulink> - </para> - </refsect1> - -</refentry> diff --git a/man/sd-daemon.xml b/man/sd-daemon.xml deleted file mode 100644 index b06d99f346..0000000000 --- a/man/sd-daemon.xml +++ /dev/null @@ -1,144 +0,0 @@ -<?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" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <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>APIs for - new-style daemons</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo> - </funcsynopsis> - - <cmdsynopsis> - <command>pkg-config --cflags --libs libsystemd</command> - </cmdsynopsis> - - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>sd-daemon.h</filename> provides APIs for new-style - daemons, as implemented by the - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> - service manager.</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>, - <citerefentry><refentrytitle>sd_watchdog_enabled</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=journal</varname>, - <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 project='man-pages'><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> - - <xi:include href="libsystemd-pkgconfig.xml" /> - - <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>sd_watchdog_enabled</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 project='man-pages'><refentrytitle>fprintf</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd-event.xml b/man/sd-event.xml deleted file mode 100644 index fc615f0906..0000000000 --- a/man/sd-event.xml +++ /dev/null @@ -1,187 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2015 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-event" xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd-event</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-event</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd-event</refname> - <refpurpose>A generic event loop implementation</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> - </funcsynopsis> - - <cmdsynopsis> - <command>pkg-config --cflags --libs libsystemd</command> - </cmdsynopsis> - - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>sd-event.h</filename> provides a generic event - loop implementation, based on Linux <citerefentry - project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>. - </para> - - <para>See - <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_get_event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_get_pending</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for more information about the functions available.</para> - - <para>The event loop design is targeted on running a separate - instance of the event loop in each thread; it has no concept of - distributing events from a single event loop instance onto - multiple worker threads. Dispatching events is strictly ordered - and subject to configurable priorities. In each event loop - iteration a single event source is dispatched. Each time an event - source is dispatched the kernel is polled for new events, before - the next event source is dispatched. The event loop is designed to - honour priorities and provide fairness within each priority. It is - not designed to provide optimal throughput, as this contradicts - these goals due the limitations of the underlying <citerefentry - project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry> - primitives.</para> - - <para>The event loop implementation provides the following features:</para> - - <orderedlist> - <listitem><para>I/O event sources, based on <citerefentry - project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>'s - file descriptor watching, including edge triggered events (<constant>EPOLLET</constant>). See <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> - - <listitem><para>Timer event sources, based on <citerefentry - project='man-pages'><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>, - supporting the <constant>CLOCK_MONOTONIC</constant>, - <constant>CLOCK_REALTIME</constant>, - <constant>CLOCK_BOOTIME</constant> clocks, as well as the - <constant>CLOCK_REALTIME_ALARM</constant> and - <constant>CLOCK_BOOTTIME_ALARM</constant> clocks that can resume - the system from suspend. When creating timer events a required - accuracy parameter may be specified which allows coalescing of - timer events to minimize power consumption. See <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> - - <listitem><para>UNIX process signal events, based on - <citerefentry - project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry>, - including full support for real-time signals, and queued parameters. See <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> - - <listitem><para>Child process state change events, based on - <citerefentry project='man-pages'><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry>. See <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> - - <listitem><para>Static event sources, of three types: defer, - post and exit, for invoking calls in each event loop, after - other event sources or at event loop termination. See - <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> - - <listitem><para>Event sources may be assigned a 64bit priority - value, that controls the order in which event sources are - dispatched if multiple are pending simultaneously. See - <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> - - <listitem><para>The event loop may automatically send watchdog - notification messages to the service manager. See - <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> - - <listitem><para>The event loop may be integrated into foreign - event loops, such as the GLib one. See - <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for an example.</para></listitem> - </orderedlist> - - </refsect1> - - <xi:include href="libsystemd-pkgconfig.xml" /> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_get_event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_get_pending</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd-id128.xml b/man/sd-id128.xml deleted file mode 100644 index ea7972055d..0000000000 --- a/man/sd-id128.xml +++ /dev/null @@ -1,166 +0,0 @@ -<?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" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <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</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="https://tools.ietf.org/html/rfc4122">RFC - 4122</ulink> but use a simpler string format. 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 128-bit 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 project='man-pages'><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 - <option>--new-id</option> option.</para> - </refsect1> - - <xi:include href="libsystemd-pkgconfig.xml" /> - - <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 project='man-pages'><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 project='die-net'><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 deleted file mode 100644 index 09747a480c..0000000000 --- a/man/sd-journal.xml +++ /dev/null @@ -1,133 +0,0 @@ -<?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" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <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</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_query_enumerate</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_enumerate_fields</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_cutoff_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_cutoff_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_usage</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_catalog</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_has_runtime_files</refentrytitle><manvolnum>3</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>sd_journal_has_persistent_files</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> - - <xi:include href="libsystemd-pkgconfig.xml" /> - - <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_query_enumerate</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_enumerate_fields</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_cutoff_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_cutoff_monotonic_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>sd_journal_get_catalog</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_has_runtime_files</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_has_persistent_files</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd-login.xml b/man/sd-login.xml deleted file mode 100644 index 328f71164d..0000000000 --- a/man/sd-login.xml +++ /dev/null @@ -1,135 +0,0 @@ -<?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" conditional='HAVE_PAM' - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <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</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 - <constant>NULL</constant> terminated and need to be freed by the - caller with the libc - <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use, including the strings referenced therein. - Similarly, individual strings returned need to be freed, as - well.</para> - - <para>As a special exception, instead of an empty string array - <constant>NULL</constant> 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> - - <xi:include href="libsystemd-pkgconfig.xml" /> - - <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 project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_booted.xml b/man/sd_booted.xml deleted file mode 100644 index 4dd674b8ea..0000000000 --- a/man/sd_booted.xml +++ /dev/null @@ -1,95 +0,0 @@ -<?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" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <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> - - <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> - - <para>Internally, this function checks whether the directory - <filename>/run/systemd/system/</filename> exists. A simple check - like this can also be implemented trivially in shell or any other - language.</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_bus_creds_get_pid.xml b/man/sd_bus_creds_get_pid.xml deleted file mode 100644 index 4c05835568..0000000000 --- a/man/sd_bus_creds_get_pid.xml +++ /dev/null @@ -1,566 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2014 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="sd_bus_creds_get_pid"> - - <refentryinfo> - <title>sd_bus_creds_get_pid</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>A monkey with a typewriter</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_bus_creds_get_pid</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_bus_creds_get_pid</refname> - <refname>sd_bus_creds_get_ppid</refname> - <refname>sd_bus_creds_get_tid</refname> - <refname>sd_bus_creds_get_uid</refname> - <refname>sd_bus_creds_get_euid</refname> - <refname>sd_bus_creds_get_suid</refname> - <refname>sd_bus_creds_get_fsuid</refname> - <refname>sd_bus_creds_get_gid</refname> - <refname>sd_bus_creds_get_egid</refname> - <refname>sd_bus_creds_get_sgid</refname> - <refname>sd_bus_creds_get_fsgid</refname> - <refname>sd_bus_creds_get_supplementary_gids</refname> - <refname>sd_bus_creds_get_comm</refname> - <refname>sd_bus_creds_get_tid_comm</refname> - <refname>sd_bus_creds_get_exe</refname> - <refname>sd_bus_creds_get_cmdline</refname> - <refname>sd_bus_creds_get_cgroup</refname> - <refname>sd_bus_creds_get_unit</refname> - <refname>sd_bus_creds_get_slice</refname> - <refname>sd_bus_creds_get_user_unit</refname> - <refname>sd_bus_creds_get_user_slice</refname> - <refname>sd_bus_creds_get_session</refname> - <refname>sd_bus_creds_get_owner_uid</refname> - <refname>sd_bus_creds_has_effective_cap</refname> - <refname>sd_bus_creds_has_permitted_cap</refname> - <refname>sd_bus_creds_has_inheritable_cap</refname> - <refname>sd_bus_creds_has_bounding_cap</refname> - <refname>sd_bus_creds_get_selinux_context</refname> - <refname>sd_bus_creds_get_audit_session_id</refname> - <refname>sd_bus_creds_get_audit_login_uid</refname> - <refname>sd_bus_creds_get_tty</refname> - <refname>sd_bus_creds_get_unique_name</refname> - <refname>sd_bus_creds_get_well_known_names</refname> - <refname>sd_bus_creds_get_description</refname> - - <refpurpose>Retrieve fields from a credentials object</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_bus_creds_get_pid</function></funcdef> - <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> - <paramdef>pid_t *<parameter>pid</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_creds_get_ppid</function></funcdef> - <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> - <paramdef>pid_t *<parameter>ppid</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_creds_get_tid</function></funcdef> - <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> - <paramdef>pid_t *<parameter>tid</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_creds_get_uid</function></funcdef> - <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> - <paramdef>uid_t *<parameter>uid</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_creds_get_euid</function></funcdef> - <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> - <paramdef>uid_t *<parameter>uid</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_creds_get_suid</function></funcdef> - <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> - <paramdef>uid_t *<parameter>uid</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_creds_get_fsuid</function></funcdef> - <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> - <paramdef>uid_t *<parameter>uid</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_creds_get_gid</function></funcdef> - <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> - <paramdef>gid_t *<parameter>gid</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_creds_get_egid</function></funcdef> - <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> - <paramdef>gid_t *<parameter>gid</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_creds_get_sgid</function></funcdef> - <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> - <paramdef>gid_t *<parameter>gid</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_creds_get_fsgid</function></funcdef> - <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> - <paramdef>gid_t *<parameter>gid</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_creds_get_supplementary_gids</function></funcdef> - <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> - <paramdef>const gid_t **<parameter>gids</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_creds_get_comm</function></funcdef> - <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> - <paramdef>const char **<parameter>comm</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_creds_get_tid_comm</function></funcdef> - <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> - <paramdef>const char **<parameter>comm</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_creds_get_exe</function></funcdef> - <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> - <paramdef>const char **<parameter>exe</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_creds_get_cmdline</function></funcdef> - <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> - <paramdef>char ***<parameter>cmdline</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_creds_get_cgroup</function></funcdef> - <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> - <paramdef>const char **<parameter>cgroup</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_creds_get_unit</function></funcdef> - <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> - <paramdef>const char **<parameter>unit</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_creds_get_slice</function></funcdef> - <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> - <paramdef>const char **<parameter>slice</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_creds_get_user_unit</function></funcdef> - <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> - <paramdef>const char **<parameter>unit</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_creds_get_user_slice</function></funcdef> - <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> - <paramdef>const char **<parameter>slice</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_creds_get_session</function></funcdef> - <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> - <paramdef>const char **<parameter>slice</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_creds_get_owner_uid</function></funcdef> - <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> - <paramdef>uid_t *<parameter>uid</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_creds_has_effective_cap</function></funcdef> - <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> - <paramdef>int <parameter>capability</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_creds_has_permitted_cap</function></funcdef> - <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> - <paramdef>int <parameter>capability</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_creds_has_inheritable_cap</function></funcdef> - <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> - <paramdef>int <parameter>capability</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_creds_has_bounding_cap</function></funcdef> - <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> - <paramdef>int <parameter>capability</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_creds_get_selinux_context</function></funcdef> - <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> - <paramdef>const char **<parameter>context</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_creds_get_audit_session_id</function></funcdef> - <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> - <paramdef>uint32_t *<parameter>sessionid</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_creds_get_audit_login_uid</function></funcdef> - <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> - <paramdef>uid_t *<parameter>loginuid</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_creds_get_tty</function></funcdef> - <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> - <paramdef>const char **<parameter>tty</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_creds_get_unique_name</function></funcdef> - <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> - <paramdef>const char **<parameter>name</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_creds_get_well_known_names</function></funcdef> - <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> - <paramdef>char ***<parameter>name</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_creds_get_description</function></funcdef> - <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> - <paramdef>const char **<parameter>name</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>These functions return credential information from an - <parameter>sd_bus_creds</parameter> object. Credential objects may - be created with - <citerefentry><refentrytitle>sd_bus_creds_new_from_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - in which case they describe the credentials of the process - identified by the specified PID, with - <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - in which case they describe the credentials of a bus peer - identified by the specified bus name, with - <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - in which case they describe the credentials of the creator of a - bus, or with - <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - in which case they describe the credentials of the sender of the - message.</para> - - <para>Not all credential fields are part of every - <literal>sd_bus_creds</literal> object. Use - <citerefentry><refentrytitle>sd_bus_creds_get_mask</refentrytitle><manvolnum>3</manvolnum></citerefentry> - to determine the mask of fields available.</para> - - <para><function>sd_bus_creds_get_pid()</function> will retrieve - the PID (process identifier). Similarly, - <function>sd_bus_creds_get_ppid()</function> will retrieve the - parent PID. Note that PID 1 has no parent process, in which case - -ENXIO is returned.</para> - - <para><function>sd_bus_creds_get_tid()</function> will retrieve the - TID (thread identifier).</para> - - <para><function>sd_bus_creds_get_uid()</function> will retrieve - the numeric UID (user identifier). Similarly, - <function>sd_bus_creds_get_euid()</function> returns the effective - UID, <function>sd_bus_creds_get_suid()</function> the saved UID - and <function>sd_bus_creds_get_fsuid()</function> the file system - UID.</para> - - <para><function>sd_bus_creds_get_gid()</function> will retrieve the - numeric GID (group identifier). Similarly, - <function>sd_bus_creds_get_egid()</function> returns the effective - GID, <function>sd_bus_creds_get_sgid()</function> the saved GID - and <function>sd_bus_creds_get_fsgid()</function> the file system - GID.</para> - - <para><function>sd_bus_creds_get_supplementary_gids()</function> - will retrieve the supplementary GIDs list.</para> - - <para><function>sd_bus_creds_get_comm()</function> will retrieve the - comm field (truncated name of the executable, as stored in - <filename>/proc/<replaceable>pid</replaceable>/comm</filename>). - </para> - - <para><function>sd_bus_creds_get_tid_comm()</function> will retrieve - the comm field of the thread (as stored in - <filename>/proc/<replaceable>pid</replaceable>/task/<replaceable>tid</replaceable>/comm</filename>). - </para> - - <para><function>sd_bus_creds_get_exe()</function> will retrieve - the path to the program executable (as stored in the - <filename>/proc/<replaceable>pid</replaceable>/exe</filename> - link, but with the <literal> (deleted)</literal> suffix removed). Note - that kernel threads do not have an executable path, in which case - -ENXIO is returned.</para> - - <para><function>sd_bus_creds_get_cmdline()</function> will - retrieve an array of command line arguments (as stored in - <filename>/proc/<replaceable>pid</replaceable>/cmdline</filename>). Note - that kernel threads do not have a command line, in which case - -ENXIO is returned.</para> - - <para><function>sd_bus_creds_get_cgroup()</function> will retrieve - the cgroup path. See <ulink - url="https://www.kernel.org/doc/Documentation/cgroups/cgroups.txt">cgroups.txt</ulink>. - </para> - - <para><function>sd_bus_creds_get_unit()</function> will retrieve - the systemd unit name (in the system instance of systemd) that the - process is a part of. See - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. For - processes that are not part of a unit, returns -ENXIO. - </para> - - <para><function>sd_bus_creds_get_user_unit()</function> will - retrieve the systemd unit name (in the user instance of systemd) - that the process is a part of. See - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. For - processes that are not part of a user unit, returns -ENXIO. - </para> - - <para><function>sd_bus_creds_get_slice()</function> will retrieve - the systemd slice (a unit in the system instance of systemd) that - the process is a part of. See - <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Similarly, - <function>sd_bus_creds_get_user_slice()</function> retrieves the - systemd slice of the process, in the user instance of systemd. - </para> - - <para><function>sd_bus_creds_get_session()</function> will - retrieve the identifier of the login session that the process is - a part of. See - <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. For - processes that are not part of a session, returns -ENXIO. - </para> - - <para><function>sd_bus_creds_get_owner_uid()</function> will - retrieve the numeric UID (user identifier) of the user who owns - the login session that the process is a part of. See - <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. - For processes that are not part of a session, returns -ENXIO. - </para> - - <para><function>sd_bus_creds_has_effective_cap()</function> will check whether the capability specified by - <parameter>capability</parameter> was set in the effective capabilities mask. A positive return value means that it - was set, zero means that it was not set, and a negative return value indicates an error. See <citerefentry - project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> and the - <varname>AmbientCapabilities=</varname> and <varname>CapabilityBoundingSet=</varname> settings in - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - </para> - - <para><function>sd_bus_creds_has_permitted_cap()</function> is - similar to <function>sd_bus_creds_has_effective_cap()</function>, - but will check the permitted capabilities mask.</para> - - <para><function>sd_bus_creds_has_inheritable_cap()</function> is - similar to <function>sd_bus_creds_has_effective_cap()</function>, - but will check the inheritable capabilities mask.</para> - - <para><function>sd_bus_creds_has_bounding_cap()</function> is - similar to <function>sd_bus_creds_has_effective_cap()</function>, - but will check the bounding capabilities mask.</para> - - <para><function>sd_bus_creds_get_selinux_context()</function> will - retrieve the SELinux security context (label) of the process.</para> - - <para><function>sd_bus_creds_get_audit_session_id()</function> - will retrieve the audit session identifier of the process. Returns - -ENXIO for processes that are not part of an audit session.</para> - - <para><function>sd_bus_creds_get_audit_login_uid()</function> will - retrieve the audit user login identifier (the identifier of the - user who is "responsible" for the session). Returns -ENXIO for - processes that are not part of an audit session.</para> - - <para><function>sd_bus_creds_get_tty()</function> will retrieve - the controlling TTY, without the prefixing "/dev/". Returns -ENXIO - for processes that have no controlling TTY.</para> - - <para><function>sd_bus_creds_get_unique_name()</function> will - retrieve the D-Bus unique name. See <ulink - url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus">The - D-Bus specification</ulink>.</para> - - <para><function>sd_bus_creds_get_well_known_names()</function> will - retrieve the set of D-Bus well-known names. See <ulink - url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus">The - D-Bus specification</ulink>.</para> - - <para><function>sd_bus_creds_get_description()</function> will - retrieve a descriptive name of the bus connection of the - peer. This name is useful to discern multiple bus connections by - the same peer, and may be altered by the peer with the - <citerefentry><refentrytitle>sd_bus_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call.</para> - - <para>All functions that take a <parameter>const - char**</parameter> parameter will store the answer there as an - address of a NUL-terminated string. It will be valid as long as - <parameter>c</parameter> remains valid, and should not be freed or - modified by the caller.</para> - - <para>All functions that take a <parameter>char***</parameter> - parameter will store the answer there as an address of an array - of strings. Each individual string is NUL-terminated, and the - array is NULL-terminated as a whole. It will be valid as long as - <parameter>c</parameter> remains valid, and should not be freed or - modified by the caller.</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>Errors</title> - - <para>Returned errors may indicate the following problems:</para> - - <variablelist> - <varlistentry> - <term><constant>-ENODATA</constant></term> - - <listitem><para>The given field is not available in the - credentials object <parameter>c</parameter>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ENXIO</constant></term> - - <listitem><para>The given field is not specified for the described - process or peer. This will be returned by - <function>sd_bus_get_unit()</function>, - <function>sd_bus_get_slice()</function>, - <function>sd_bus_get_user_unit()</function>, - <function>sd_bus_get_user_slice()</function>, - <function>sd_bus_get_session()</function>, and - <function>sd_bus_get_owner_uid()</function> if the process is - not part of a systemd system unit, systemd user unit, systemd - slice, or logind session. It will also be returned by - <function>sd_bus_creds_get_exe()</function> and - <function>sd_bus_creds_get_cmdline()</function> for kernel - threads (since these are not started from an executable binary, - nor have a command line), and by - <function>sd_bus_creds_get_audit_session_id()</function> and - <function>sd_bus_creds_get_audit_login_uid()</function> when - the process is not part of an audit session, and - <function>sd_bus_creds_get_tty()</function> if the process has - no controlling TTY. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><constant>-EINVAL</constant></term> - - <listitem><para>Specified pointer parameter is <constant>NULL</constant>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ENOMEM</constant></term> - - <listitem><para>Memory allocation failed.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para><function>sd_bus_creds_get_pid()</function> and the other - functions described here are available as a shared library, which - can be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry - project='die-net'><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-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_creds_new_from_pid</refentrytitle><manvolnum>2</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>fork</refentrytitle><manvolnum>2</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>credentials</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_bus_creds_new_from_pid.xml b/man/sd_bus_creds_new_from_pid.xml deleted file mode 100644 index 082f7b67db..0000000000 --- a/man/sd_bus_creds_new_from_pid.xml +++ /dev/null @@ -1,353 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2014 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="sd_bus_creds_new_from_pid"> - - <refentryinfo> - <title>sd_bus_creds_new_from_pid</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>A monkey with a typewriter</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_bus_creds_new_from_pid</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_bus_creds_new_from_pid</refname> - <refname>sd_bus_creds_get_mask</refname> - <refname>sd_bus_creds_get_augmented_mask</refname> - <refname>sd_bus_creds_ref</refname> - <refname>sd_bus_creds_unref</refname> - <refname>sd_bus_creds_unrefp</refname> - - <refpurpose>Retrieve credentials object for the specified PID</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_bus_creds_new_from_pid</function></funcdef> - <paramdef>pid_t <parameter>pid</parameter></paramdef> - <paramdef>uint64_t <parameter>creds_mask</parameter></paramdef> - <paramdef>sd_bus_creds **<parameter>ret</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>uint64_t <function>sd_bus_creds_get_mask</function></funcdef> - <paramdef>const sd_bus_creds *<parameter>c</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>uint64_t <function>sd_bus_creds_get_augmented_mask</function></funcdef> - <paramdef>const sd_bus_creds *<parameter>c</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>sd_bus_creds *<function>sd_bus_creds_ref</function></funcdef> - <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>sd_bus_creds *<function>sd_bus_creds_unref</function></funcdef> - <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>void <function>sd_bus_creds_unrefp</function></funcdef> - <paramdef>sd_bus_creds **<parameter>c</parameter></paramdef> - </funcprototype> - </funcsynopsis> - - <para> - <constant>SD_BUS_CREDS_PID</constant>, - <constant>SD_BUS_CREDS_PPID</constant>, - <constant>SD_BUS_CREDS_TID</constant>, - <constant>SD_BUS_CREDS_UID</constant>, - <constant>SD_BUS_CREDS_EUID</constant>, - <constant>SD_BUS_CREDS_SUID</constant>, - <constant>SD_BUS_CREDS_FSUID</constant>, - <constant>SD_BUS_CREDS_GID</constant>, - <constant>SD_BUS_CREDS_EGID</constant>, - <constant>SD_BUS_CREDS_SGID</constant>, - <constant>SD_BUS_CREDS_FSGID</constant>, - <constant>SD_BUS_CREDS_SUPPLEMENTARY_GIDS</constant>, - <constant>SD_BUS_CREDS_COMM</constant>, - <constant>SD_BUS_CREDS_TID_COMM</constant>, - <constant>SD_BUS_CREDS_EXE</constant>, - <constant>SD_BUS_CREDS_CMDLINE</constant>, - <constant>SD_BUS_CREDS_CGROUP</constant>, - <constant>SD_BUS_CREDS_UNIT</constant>, - <constant>SD_BUS_CREDS_SLICE</constant>, - <constant>SD_BUS_CREDS_USER_UNIT</constant>, - <constant>SD_BUS_CREDS_USER_SLICE</constant>, - <constant>SD_BUS_CREDS_SESSION</constant>, - <constant>SD_BUS_CREDS_OWNER_UID</constant>, - <constant>SD_BUS_CREDS_EFFECTIVE_CAPS</constant>, - <constant>SD_BUS_CREDS_PERMITTED_CAPS</constant>, - <constant>SD_BUS_CREDS_INHERITABLE_CAPS</constant>, - <constant>SD_BUS_CREDS_BOUNDING_CAPS</constant>, - <constant>SD_BUS_CREDS_SELINUX_CONTEXT</constant>, - <constant>SD_BUS_CREDS_AUDIT_SESSION_ID</constant>, - <constant>SD_BUS_CREDS_AUDIT_LOGIN_UID</constant>, - <constant>SD_BUS_CREDS_TTY</constant>, - <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>, - <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant>, - <constant>SD_BUS_CREDS_DESCRIPTION</constant>, - <constant>SD_BUS_CREDS_AUGMENT</constant>, - <constant>_SD_BUS_CREDS_ALL</constant> - </para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_bus_creds_new_from_pid()</function> creates a - new credentials object and fills it with information about the - process <parameter>pid</parameter>. The pointer to this object - will be stored in the <parameter>ret</parameter> pointer. Note that - credential objects may also be created and retrieved via - <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> - - <para>The information that will be stored is determined by - <parameter>creds_mask</parameter>. It may contain a subset of ORed - constants <constant>SD_BUS_CREDS_PID</constant>, - <constant>SD_BUS_CREDS_PPID</constant>, - <constant>SD_BUS_CREDS_TID</constant>, - <constant>SD_BUS_CREDS_UID</constant>, - <constant>SD_BUS_CREDS_EUID</constant>, - <constant>SD_BUS_CREDS_SUID</constant>, - <constant>SD_BUS_CREDS_FSUID</constant>, - <constant>SD_BUS_CREDS_GID</constant>, - <constant>SD_BUS_CREDS_EGID</constant>, - <constant>SD_BUS_CREDS_SGID</constant>, - <constant>SD_BUS_CREDS_FSGID</constant>, - <constant>SD_BUS_CREDS_SUPPLEMENTARY_GIDS</constant>, - <constant>SD_BUS_CREDS_COMM</constant>, - <constant>SD_BUS_CREDS_TID_COMM</constant>, - <constant>SD_BUS_CREDS_EXE</constant>, - <constant>SD_BUS_CREDS_CMDLINE</constant>, - <constant>SD_BUS_CREDS_CGROUP</constant>, - <constant>SD_BUS_CREDS_UNIT</constant>, - <constant>SD_BUS_CREDS_SLICE</constant>, - <constant>SD_BUS_CREDS_USER_UNIT</constant>, - <constant>SD_BUS_CREDS_USER_SLICE</constant>, - <constant>SD_BUS_CREDS_SESSION</constant>, - <constant>SD_BUS_CREDS_OWNER_UID</constant>, - <constant>SD_BUS_CREDS_EFFECTIVE_CAPS</constant>, - <constant>SD_BUS_CREDS_PERMITTED_CAPS</constant>, - <constant>SD_BUS_CREDS_INHERITABLE_CAPS</constant>, - <constant>SD_BUS_CREDS_BOUNDING_CAPS</constant>, - <constant>SD_BUS_CREDS_SELINUX_CONTEXT</constant>, - <constant>SD_BUS_CREDS_AUDIT_SESSION_ID</constant>, - <constant>SD_BUS_CREDS_AUDIT_LOGIN_UID</constant>, - <constant>SD_BUS_CREDS_TTY</constant>, - <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>, - <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant>, and - <constant>SD_BUS_CREDS_DESCRIPTION</constant>. Use the special - value <constant>_SD_BUS_CREDS_ALL</constant> to request all - supported fields. The <constant>SD_BUS_CREDS_AUGMENT</constant> - constant may not be ORed into the mask for invocations of - <function>sd_bus_creds_new_from_pid()</function>.</para> - - <para>Fields can be retrieved from the credentials object using - <citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry> - and other functions which correspond directly to the constants - listed above.</para> - - <para>A mask of fields which were actually successfully retrieved - can be retrieved with - <function>sd_bus_creds_get_mask()</function>. If the credentials - object was created with - <function>sd_bus_creds_new_from_pid()</function>, this will be a - subset of fields requested in <parameter>creds_mask</parameter>. - </para> - - <para>Similar to <function>sd_bus_creds_get_mask()</function>, the - function <function>sd_bus_creds_get_augmented_mask()</function> - returns a bitmask of field constants. The mask indicates which - credential fields have been retrieved in a non-atomic fashion. For - credential objects created via - <function>sd_bus_creds_new_from_pid()</function>, this mask will be - identical to the mask returned by - <function>sd_bus_creds_get_mask()</function>. However, for - credential objects retrieved via - <function>sd_bus_get_name_creds()</function>, this mask will be set - for the credential fields that could not be determined atomically - at peer connection time, and which were later added by reading - augmenting credential data from - <filename>/proc</filename>. Similarly, for credential objects - retrieved via <function>sd_bus_get_owner_creds()</function>, the - mask is set for the fields that could not be determined atomically - at bus creation time, but have been augmented. Similarly, for - credential objects retrieved via - <function>sd_bus_message_get_creds()</function>, the mask is set - for the fields that could not be determined atomically at message - sending time, but have been augmented. The mask returned by - <function>sd_bus_creds_get_augmented_mask()</function> is always a - subset of (or identical to) the mask returned by - <function>sd_bus_creds_get_mask()</function> for the same - object. The latter call hence returns all credential fields - available in the credential object, the former then marks the - subset of those that have been augmented. Note that augmented - fields are unsuitable for authorization decisions, as they may be - retrieved at different times, thus being subject to races. Hence, - augmented fields should be used exclusively for informational - purposes. - </para> - - <para><function>sd_bus_creds_ref()</function> creates a new - reference to the credentials object <parameter>c</parameter>. This - object will not be destroyed until - <function>sd_bus_creds_unref()</function> has been called as many - times plus once more. Once the reference count has dropped to zero, - <parameter>c</parameter> cannot be used anymore, so further - calls to <function>sd_bus_creds_ref(c)</function> or - <function>sd_bus_creds_unref(c)</function> are illegal.</para> - - <para><function>sd_bus_creds_unref()</function> destroys a reference - to <parameter>c</parameter>.</para> - - <para><function>sd_bus_creds_unrefp()</function> is similar to - <function>sd_bus_creds_unref()</function> but takes a pointer to a - pointer to an <type>sd_bus_creds</type> object. This call is useful in - conjunction with GCC's and LLVM's <ulink - url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up - Variable Attribute</ulink>. Note that this function is defined as - inline function.</para> - - <para><function>sd_bus_creds_ref()</function>, - <function>sd_bus_creds_unref()</function> and - <function>sd_bus_creds_unrefp()</function> execute no operation if - the passed in bus credentials object is - <constant>NULL</constant>.</para> - - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, <function>sd_bus_creds_new_from_pid()</function> - returns 0 or a positive integer. On failure, it returns a negative - errno-style error code.</para> - - <para><function>sd_bus_creds_get_mask()</function> returns the - mask of successfully acquired fields.</para> - - <para><function>sd_bus_creds_get_augmented_mask()</function> - returns the mask of fields that have been augmented from data in - <filename>/proc</filename>, and are thus not suitable for - authorization decisions.</para> - - <para><function>sd_bus_creds_ref()</function> always returns the - argument.</para> - - <para><function>sd_bus_creds_unref()</function> always returns - <constant>NULL</constant>.</para> - </refsect1> - - <refsect1> - <title>Reference ownership</title> - - <para>Function <function>sd_bus_creds_new_from_pid()</function> - creates a new object and the caller owns the sole reference. When - not needed anymore, this reference should be destroyed with - <citerefentry><refentrytitle>sd_bus_creds_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - </para> - </refsect1> - - <refsect1> - <title>Errors</title> - - <para>Returned errors may indicate the following problems:</para> - - <variablelist> - - <varlistentry> - <term><constant>-ESRCH</constant></term> - - <listitem><para>Specified <parameter>pid</parameter> could not - be found.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-EINVAL</constant></term> - - <listitem><para>Specified parameter is invalid - (<constant>NULL</constant> in case of output - parameters).</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ENOMEM</constant></term> - - <listitem><para>Memory allocation failed.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-EOPNOTSUPP</constant></term> - - <listitem><para>One of the requested fields is unknown to the local system.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para><function>sd_bus_creds_new_from_pid()</function> and the - other calls described here are available as a shared library, - which can be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry - project='die-net'><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-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_bus_default.xml b/man/sd_bus_default.xml deleted file mode 100644 index 6d5a90de72..0000000000 --- a/man/sd_bus_default.xml +++ /dev/null @@ -1,312 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2014 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="sd_bus_default"> - - <refentryinfo> - <title>sd_bus_default</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>A monkey with a typewriter</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_bus_default</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_bus_default</refname> - <refname>sd_bus_default_user</refname> - <refname>sd_bus_default_system</refname> - - <refname>sd_bus_open</refname> - <refname>sd_bus_open_user</refname> - <refname>sd_bus_open_system</refname> - <refname>sd_bus_open_system_remote</refname> - <refname>sd_bus_open_system_machine</refname> - - <refpurpose>Acquire a connection to a system or user bus</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_bus_default</function></funcdef> - <paramdef>sd_bus **<parameter>bus</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_default_user</function></funcdef> - <paramdef>sd_bus **<parameter>bus</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_default_system</function></funcdef> - <paramdef>sd_bus **<parameter>bus</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_open</function></funcdef> - <paramdef>sd_bus **<parameter>bus</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_open_user</function></funcdef> - <paramdef>sd_bus **<parameter>bus</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_open_system</function></funcdef> - <paramdef>sd_bus **<parameter>bus</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_open_system_remote</function></funcdef> - <paramdef>sd_bus **<parameter>bus</parameter></paramdef> - <paramdef>const char *<parameter>host</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_open_system_machine</function></funcdef> - <paramdef>sd_bus **<parameter>bus</parameter></paramdef> - <paramdef>const char *<parameter>machine</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_bus_default()</function> acquires a bus - connection object to the user bus when invoked in user context, or - to the system bus otherwise. The connection object is associated - with the calling thread. Each time the function is invoked from - the same thread, the same object is returned, but its reference - count is increased by one, as long as at least one reference is - kept. When the last reference to the connection is dropped (using - the - <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call), the connection is terminated. Note that the connection is - not automatically terminated when the associated thread ends. It - is important to drop the last reference to the bus connection - explicitly before the thread ends, as otherwise, the connection will - leak. Also, queued but unread or unwritten messages keep the - bus referenced, see below.</para> - - <para><function>sd_bus_default_user()</function> returns a user - bus connection object associated with the calling thread. - <function>sd_bus_default_system()</function> is similar, but - connects to the system bus. Note that - <function>sd_bus_default()</function> is identical to these two - calls, depending on the execution context.</para> - - <para><function>sd_bus_open()</function> creates a new, - independent bus connection to the user bus when invoked in user - context, or the system bus - otherwise. <function>sd_bus_open_user()</function> is similar, but - connects only to the user bus. - <function>sd_bus_open_system()</function> does the same, but - connects to the system bus. In contrast to - <function>sd_bus_default()</function>, - <function>sd_bus_default_user()</function>, and - <function>sd_bus_default_system()</function>, these calls return - new, independent connection objects that are not associated with - the invoking thread and are not shared between multiple - invocations. It is recommended to share connections per thread to - efficiently make use the available resources. Thus, it is - recommended to use <function>sd_bus_default()</function>, - <function>sd_bus_default_user()</function> and - <function>sd_bus_default_system()</function> to connect to the - user or system buses.</para> - - <para>If the <varname>$DBUS_SESSION_BUS_ADDRESS</varname> environment - variable is set - (cf. <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>), - it will be used as the address of the user bus. This variable can - contain multiple addresses separated by <literal>;</literal>. If - this variable is not set, a suitable default for the default user - D-Bus instance will be used.</para> - - <para>If the <varname>$DBUS_SYSTEM_BUS_ADDRESS</varname> - environment variable is set, it will be used as the address of the - system bus. This variable uses the same syntax as - <varname>$DBUS_SESSION_BUS_ADDRESS</varname>. If this variable is - not set, a suitable default for the default system D-Bus instance - will be used.</para> - - <para><function>sd_bus_open_system_remote()</function> connects to - the system bus on the specified <parameter>host</parameter> using - <citerefentry - project='die-net'><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry>. <parameter>host</parameter> - consists of an optional user name followed by the - <literal>@</literal> symbol, and the hostname. - </para> - - <para><function>sd_bus_open_system_machine()</function> connects - to the system bus in the specified <parameter>machine</parameter>, - where <parameter>machine</parameter> is the name of a local - container. See - <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - for more information about the "machine" concept. Note that - connections into local containers are only available to privileged - processes at this time.</para> - - <para>These calls allocate a bus connection object and initiate - the connection to a well-known bus of some form. An alternative to - using these high-level calls is to create an unconnected bus - object with - <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry> - and to connect it with - <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - </para> - - </refsect1> - - <refsect1> - <title>Reference ownership</title> - <para>The functions <function>sd_bus_open()</function>, - <function>sd_bus_open_user()</function>, - <function>sd_bus_open_system()</function>, - <function>sd_bus_open_system_remote()</function>, and - <function>sd_bus_open_system_machine()</function> return a new - connection object and the caller owns the sole reference. When not - needed anymore, this reference should be destroyed with - <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - </para> - - <para>The functions <function>sd_bus_default()</function>, - <function>sd_bus_default_user()</function> and - <function>sd_bus_default_system()</function> do not necessarily - create a new object, but increase the connection reference of an - existing connection object by one. Use - <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> - to drop the reference.</para> - - <para>Queued but unwritten/unread messages also keep a reference - to their bus connection object. For this reason, even if an - application dropped all references to a bus connection, it might - not get destroyed right away. Until all incoming queued - messages are read, and until all outgoing unwritten messages are - written, the bus object will stay - alive. <function>sd_bus_flush()</function> may be used to write - all outgoing queued messages so they drop their references. To - flush the unread incoming messages, use - <function>sd_bus_close()</function>, which will also close the bus - connection. When using the default bus logic, it is a good idea to - first invoke <function>sd_bus_flush()</function> followed by - <function>sd_bus_close()</function> when a thread or process - terminates, and thus its bus connection object should be - freed.</para> - - <para>The life cycle of the default bus connection should be the - responsibility of the code that creates/owns the thread the - default bus connection object is associated with. Library code - should neither call <function>sd_bus_flush()</function> nor - <function>sd_bus_close()</function> on default bus objects unless - it does so in its own private, self-allocated thread. Library code - should not use the default bus object in other threads unless it - is clear that the program using it will life cycle the bus - connection object and flush and close it before exiting from the - thread. In libraries where it is not clear that the calling - program will life cycle the bus connection object, it is hence - recommended to use <function>sd_bus_open_system()</function> - instead of <function>sd_bus_default_system()</function> and - related calls.</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>Errors</title> - - <para>Returned errors may indicate the following problems:</para> - - <variablelist> - - <varlistentry> - <term><constant>-EINVAL</constant></term> - - <listitem><para>The specified parameters are invalid.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ENOMEM</constant></term> - - <listitem><para>Memory allocation failed.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ESOCKTNOSUPPORT</constant></term> - - <listitem><para>The protocol version required to connect to the selected bus is not supported.</para></listitem> - </varlistentry> - </variablelist> - - <para>In addition, any further connection-related errors may be - by returned. See <citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para><function>sd_bus_open_user()</function> and the other - functions described here are available as a shared library, which - can be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry - project='die-net'><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-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_bus_error.xml b/man/sd_bus_error.xml deleted file mode 100644 index c2d7ee389b..0000000000 --- a/man/sd_bus_error.xml +++ /dev/null @@ -1,389 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2014 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="sd_bus_error"> - - <refentryinfo> - <title>sd_bus_error</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>A monkey with a typewriter</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_bus_error</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_bus_error</refname> - <refname>SD_BUS_ERROR_MAKE_CONST</refname> - <refname>SD_BUS_ERROR_NULL</refname> - <refname>sd_bus_error_free</refname> - <refname>sd_bus_error_set</refname> - <refname>sd_bus_error_setf</refname> - <refname>sd_bus_error_set_const</refname> - <refname>sd_bus_error_set_errno</refname> - <refname>sd_bus_error_set_errnof</refname> - <refname>sd_bus_error_set_errnofv</refname> - <refname>sd_bus_error_get_errno</refname> - <refname>sd_bus_error_copy</refname> - <refname>sd_bus_error_is_set</refname> - <refname>sd_bus_error_has_name</refname> - - <refpurpose>sd-bus error handling</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> - - <funcsynopsisinfo>typedef struct { - const char *name; - const char *message; - ... -} sd_bus_error;</funcsynopsisinfo> - - <para> - <constant>SD_BUS_ERROR_MAKE_CONST(<replaceable>name</replaceable>, <replaceable>message</replaceable>)</constant> - </para> - <para> - <constant>SD_BUS_ERROR_NULL</constant> - </para> - - <funcprototype> - <funcdef>void <function>sd_bus_error_free</function></funcdef> - <paramdef>sd_bus_error *<parameter>e</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_error_set</function></funcdef> - <paramdef>sd_bus_error *<parameter>e</parameter></paramdef> - <paramdef>const char *<parameter>name</parameter></paramdef> - <paramdef>const char *<parameter>message</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_error_setf</function></funcdef> - <paramdef>sd_bus_error *<parameter>e</parameter></paramdef> - <paramdef>const char *<parameter>name</parameter></paramdef> - <paramdef>const char *<parameter>format</parameter></paramdef> - <paramdef>...</paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_error_set_const</function></funcdef> - <paramdef>sd_bus_error *<parameter>e</parameter></paramdef> - <paramdef>const char *<parameter>name</parameter></paramdef> - <paramdef>const char *<parameter>message</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_error_set_errno</function></funcdef> - <paramdef>sd_bus_error *<parameter>e</parameter></paramdef> - <paramdef>int <parameter>error</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_error_set_errnof</function></funcdef> - <paramdef>sd_bus_error *<parameter>e</parameter></paramdef> - <paramdef>int <parameter>error</parameter></paramdef> - <paramdef>const char *<parameter>format</parameter></paramdef> - <paramdef>...</paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_error_set_errnofv</function></funcdef> - <paramdef>sd_bus_error *<parameter>e</parameter></paramdef> - <paramdef>int <parameter>error</parameter></paramdef> - <paramdef>const char *<parameter>format</parameter></paramdef> - <paramdef>va_list ap</paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_error_get_errno</function></funcdef> - <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_error_copy</function></funcdef> - <paramdef>sd_bus_error *<parameter>dst</parameter></paramdef> - <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_error_is_set</function></funcdef> - <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_error_has_name</function></funcdef> - <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef> - <paramdef>const char *<parameter>name</parameter></paramdef> - </funcprototype> - </funcsynopsis> - - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>The <structname>sd_bus_error</structname> structure carries - information about a D-Bus error condition. The functions described - below may be used to set and query fields in this structure. The - <structfield>name</structfield> field contains a short identifier - of an error. It should follow the rules for error names described - in the D-Bus specification, subsection <ulink - url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names">Valid - Names</ulink>. A number of common, standardized error names are - described in - <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - but additional domain-specific errors may be defined by - applications. The <structfield>message</structfield> field usually - contains a human-readable string describing the details, but might - be NULL. An unset <structname>sd_bus_error</structname> structure - should have both fields initialized to NULL. Set an error - structure to <constant>SD_BUS_ERROR_NULL</constant> in order to - reset both fields to NULL. When no longer necessary, resources - held by the <structname>sd_bus_error</structname>structure should - be destroyed with <function>sd_bus_error_free()</function>.</para> - - <para><function>sd_bus_error_set()</function> sets an error - structure to the specified name and message strings. The strings - will be copied into internal, newly allocated memory. It is - essential to free the error structure again when it is not - required anymore (see above). The function will return an - <varname>errno</varname>-like negative value (see <citerefentry - project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>) - determined from the specified error name. Various well-known - D-Bus errors are converted to well-known <varname>errno</varname> - counterparts, and the other ones to <constant>-EIO</constant>. See - <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for a list of well-known error names. Additional error mappings - may be defined with - <citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If - <parameter>e</parameter> is NULL, no error structure is initialized, - but the error is still converted into an - <varname>errno</varname>-style error. If - <parameter>name</parameter> is <constant>NULL</constant>, it is - assumed that no error occurred, and 0 is returned. This means that - this function may be conveniently used in a - <function>return</function> statement. If - <parameter>message</parameter> is NULL, no message is set. This - call can fail if no memory may be allocated for the name and - message strings, in which case an - <constant>SD_BUS_ERROR_NO_MEMORY</constant> error might be set - instead and -ENOMEM be returned. Do not use this call on error - structures that are already initialized. If you intend to reuse an - error structure, free the old data stored in it with - <function>sd_bus_error_free()</function> first.</para> - - <para><function>sd_bus_error_setf()</function> is similar to - <function>sd_bus_error_set()</function>, but takes a <citerefentry - project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry> - format string and corresponding arguments to generate the - <structfield>message</structfield> field.</para> - - <para><function>sd_bus_error_set_const()</function> is similar to - <function>sd_bus_error_set()</function>, but the string parameters - are not copied internally, and must hence remain constant and - valid for the lifetime of <parameter>e</parameter>. Use this call - to avoid memory allocations when setting error structures. Since - this call does not allocate memory, it will not fail with an - out-of-memory condition as - <function>sd_bus_error_set()</function> can, as described - above. Alternatively, the - <constant>SD_BUS_ERROR_MAKE_CONST()</constant> macro may be used - to generate a literal, constant bus error structure - on-the-fly.</para> - - <para><function>sd_bus_error_set_errno()</function> will set - <structfield>name</structfield> from an - <varname>errno</varname>-like value that is converted to a D-Bus - error. <citerefentry - project='die-net'><refentrytitle>strerror_r</refentrytitle><manvolnum>3</manvolnum></citerefentry> - will be used to set <structfield>message</structfield>. Well-known - D-Bus error names will be used for <structfield>name</structfield> - if applicable, otherwise a name in the - <literal>System.Error.</literal> namespace will be generated. The - sign of the specified error number is ignored. The absolute value - is used implicitly. The call always returns a negative value, for - convenient usage in <function>return</function> statements. This - call might fail due to lack of memory, in which case an - <constant>SD_BUS_ERROR_NO_MEMORY</constant> error is set instead, - and -ENOMEM is returned.</para> - - <para><function>sd_bus_error_set_errnof()</function> is similar to - <function>sd_bus_error_set_errno()</function>, but in addition to - <parameter>error</parameter>, takes a <citerefentry - project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry> - format string and corresponding arguments. The - <structfield>message</structfield> field will be generated from - <parameter>format</parameter> and the arguments.</para> - - <para><function>sd_bus_error_set_errnofv()</function> is similar to - <function>sd_bus_error_set_errnof()</function>, but takes the - format string parameters as <citerefentry - project='man-pages'><refentrytitle>va_arg</refentrytitle><manvolnum>3</manvolnum></citerefentry> - parameter list.</para> - - <para><function>sd_bus_error_get_errno()</function> converts the - <structfield>name</structfield> field of an error structure to an - <varname>errno</varname>-like (positive) value using the same - rules as <function>sd_bus_error_set()</function>. If - <parameter>e</parameter> is <constant>NULL</constant>, 0 will be - returned.</para> - - <para><function>sd_bus_error_copy()</function> will initialize - <parameter>dst</parameter> using the values in - <parameter>e</parameter>. If the strings in - <parameter>e</parameter> were set using - <function>sd_bus_set_error_const()</function>, they will be shared. - Otherwise, they will be copied. Returns a converted - <varname>errno</varname>-like, negative error code.</para> - - <para><function>sd_bus_error_is_set()</function> will return a - non-zero value if <parameter>e</parameter> is - non-<constant>NULL</constant> and an error has been set, - <constant>false</constant> otherwise.</para> - - <para><function>sd_bus_error_has_name()</function> will return a - non-zero value if <parameter>e</parameter> is - non-<constant>NULL</constant> and an error with the same - <parameter>name</parameter> has been set, - <constant>false</constant> otherwise.</para> - - <para><function>sd_bus_error_free()</function> will destroy - resources held by <parameter>e</parameter>. The parameter itself - will not be deallocated, and must be <citerefentry - project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>d - by the caller if necessary. The function may also be called safely - on unset errors (error structures with both fields set to NULL), - in which case it performs no operation. This call will reset the - error structure after freeing the data, so that all fields are set - to NULL. The structure may be reused afterwards.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>The functions <function>sd_bus_error_set()</function>, - <function>sd_bus_error_setf()</function>, and - <function>sd_bus_error_set_const()</function>, when successful, - return the negative errno value corresponding to the - <parameter>name</parameter> parameter. The functions - <function>sd_bus_error_set_errno()</function>, - <function>sd_bus_error_set_errnof()</function> and - <function>sd_bus_error_set_errnofv()</function>, when successful, - return the negative value of the <parameter>error</parameter> - parameter. If an error occurs, one of the negative error values - listed below will be returned.</para> - - <para><function>sd_bus_error_get_errno()</function> returns - <constant>false</constant> when <parameter>e</parameter> is - <constant>NULL</constant>, and a positive errno value mapped from - <parameter>e->name</parameter> otherwise.</para> - - <para><function>sd_bus_error_copy()</function> returns 0 or a - positive integer on success, and a negative error value converted - from the error name otherwise.</para> - - <para><function>sd_bus_error_is_set()</function> returns a - non-zero value when <parameter>e</parameter> and the - <structfield>name</structfield> field are - non-<constant>NULL</constant>, zero otherwise.</para> - - <para><function>sd_bus_error_has_name()</function> returns a - non-zero value when <parameter>e</parameter> is - non-<constant>NULL</constant> and the - <structfield>name</structfield> field is equal to - <parameter>name</parameter>, zero otherwise.</para> - </refsect1> - - <refsect1> - <title>Reference ownership</title> - <para><structname>sd_bus_error</structname> is not reference - counted. Users should destroy resources held by it by calling - <function>sd_bus_error_free()</function>. Usually, error structures - are allocated on the stack or passed in as function parameters, - but they may also be allocated dynamically, in which case it is - the duty of the caller to <citerefentry - project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - the memory held by the structure itself after freeing its contents - with <function>sd_bus_error_free()</function>.</para> - </refsect1> - - <refsect1> - <title>Errors</title> - - <para>Returned errors may indicate the following problems:</para> - - <variablelist> - - <varlistentry> - <term><constant>-EINVAL</constant></term> - - <listitem><para>Error was already set in - <structname>sd_bus_error</structname> structure when one the - error-setting functions was called.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ENOMEM</constant></term> - - <listitem><para>Memory allocation failed.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para><function>sd_bus_set_error()</function> and other functions - described here are available as a shared library, which can be - compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><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-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>strerror_r</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_bus_error_add_map.xml b/man/sd_bus_error_add_map.xml deleted file mode 100644 index 7dc1ef6c90..0000000000 --- a/man/sd_bus_error_add_map.xml +++ /dev/null @@ -1,173 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2015 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_bus_error_add_map"> - - <refentryinfo> - <title>sd_bus_error_add_map</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_bus_error_add_map</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_bus_error_add_map</refname> - <refname>sd_bus_error_map</refname> - <refname>SD_BUS_ERROR_MAP</refname> - <refname>SD_BUS_ERROR_END</refname> - - <refpurpose>Additional sd-dbus error mappings</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> - - <funcsynopsisinfo>typedef struct { - const char *name; - int code; - ... -} sd_bus_error_map;</funcsynopsisinfo> - - </funcsynopsis> - - <para> - <constant>SD_BUS_ERROR_MAP(<replaceable>name</replaceable>, <replaceable>code</replaceable>)</constant> - </para> - <para> - <constant>SD_BUS_ERROR_MAP_END</constant> - </para> - - <funcprototype> - <funcdef>int <function>sd_bus_error_add_map</function></funcdef> - <paramdef>const sd_bus_map *<parameter>map</parameter></paramdef> - </funcprototype> - - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>The <function>sd_bus_error_add_map()</function> call may be - used to register additional mappings for converting D-Bus errors - to GNU/Linux <varname>errno</varname>-style errors. The mappings - defined with this call are consulted by calls such as - <citerefentry><refentrytitle>sd_bus_error_set</refentrytitle><manvolnum>3</manvolnum></citerefentry> - or - <citerefentry><refentrytitle>sd_bus_error_get_errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>. By - default, a number of generic, standardized mappings are known, as - documented in - <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Use - this call to add further, application-specific mappings.</para> - - <para>The function takes a pointer to an array of - <structname>sd_bus_error_map</structname> structures. A reference - to the specified array is added to the lookup tables for error - mappings. Note that the structure is not copied, and that it is hence - essential that the array stays available and constant during the - entire remaining runtime of the process.</para> - - <para>The mapping array should be put together with a series of - <constant>SD_BUS_ERROR_MAP()</constant> macro invocations that - take a literal name string and a (positive) - <varname>errno</varname>-style error number. The last entry of the - array should be an invocation of the - <constant>SD_BUS_ERROR_MAP_END</constant> macro. The array should not be - put together without use of these two macros.</para> - - <para>Note that the call is idempotent: it is safe to invoke it - multiple times with the parameter, which will only add the passed - mapping array once.</para> - - <para>Note that the memory allocated by this call is not intended - to be freed during the lifetime of the process. It should not be - freed explicitly.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para><function>sd_bus_error_add_map()</function> returns a - positive value when the new array was added to the lookup - tables. It returns zero when the same array was already added - before. On error, a negative <varname>errno</varname>-style error - code is returned. See below for known error codes.</para> - </refsect1> - - <refsect1> - <title>Errors</title> - - <para>Returned errors may indicate the following problems:</para> - - <variablelist> - - <varlistentry> - <term><constant>-EINVAL</constant></term> - - <listitem><para>The specified mapping array is invalid.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ENOMEM</constant></term> - - <listitem><para>Memory allocation failed.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>The various error definitions described here are available - as a shared library, which can be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry - project='die-net'><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-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>strerror_r</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_bus_message_append.xml b/man/sd_bus_message_append.xml deleted file mode 100644 index 77fce02eae..0000000000 --- a/man/sd_bus_message_append.xml +++ /dev/null @@ -1,264 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2014 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="sd_bus_message_append" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd_bus_message_append</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>A monkey with a typewriter</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_bus_message_append</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_bus_message_append</refname> - - <refpurpose>Attach fields to a D-Bus message based on a type - string</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int sd_bus_message_append</funcdef> - <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> - <paramdef>const char *<parameter>types</parameter></paramdef> - <paramdef>...</paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>The <function>sd_bus_message_append()</function> function - appends a sequence of fields to the D-Bus message object - <parameter>m</parameter>. The type string - <parameter>types</parameter> describes the types of the field - arguments that follow. For each type specified in the type string, - one or more arguments need to be specified, in the same order as - declared in the type string.</para> - - <para>The type string is composed of the elements shown in the - table below. It contains zero or more single "complete types". - Each complete type may be one of the basic types or a fully - described container type. A container type may be a structure with - the contained types, a variant, an array with its element type, or - a dictionary entry with the contained types. The type string is - <constant>NUL</constant>-terminated.</para> - - <para>In case of a basic type, one argument of the corresponding - type is expected.</para> - - <para>A structure is denoted by a sequence of complete types - between <literal>(</literal> and <literal>)</literal>. This - sequence cannot be empty — it must contain at least one type. - Arguments corresponding to this nested sequence follow the same - rules as if they were not nested.</para> - - <para>A variant is denoted by <literal>v</literal>. Corresponding - arguments must begin with a type string denoting a complete type, - and following that, arguments corresponding to the specified type. - </para> - - <para>An array is denoted by <literal>a</literal> followed by a - complete type. Corresponding arguments must begin with the number of - entries in the array, followed by the entries themselves, - matching the element type of the array.</para> - - <para>A dictionary is an array of dictionary entries, denoted by - <literal>a</literal> followed by a pair of complete types between - <literal>{</literal> and <literal>}</literal>. The first of those - types must be a basic type. Corresponding arguments must begin - with the number of dictionary entries, followed by a pair of - values for each entry matching the element type of - the dictionary entries.</para> - - <para>For further details on the D-Bus type system, please consult - the <ulink - url="http://dbus.freedesktop.org/doc/dbus-specification.html#type-system">D-Bus - Specification</ulink>.</para> - - <table> - <title>Item type specifiers</title> - - <tgroup cols='5'> - <xi:include href="sd_bus_message_append_basic.xml" xpointer="xpointer(//table[@id='format-specifiers'])//colspec" /> - <xi:include href="sd_bus_message_append_basic.xml" xpointer="xpointer(//table[@id='format-specifiers']//thead)" /> - - <tbody> - <xi:include href="sd_bus_message_append_basic.xml" xpointer="xpointer(//table[@id='format-specifiers']//tbody/*)" /> - - <row> - <entry><literal>a</literal></entry> - <entry><constant>SD_BUS_TYPE_ARRAY</constant></entry> - <entry>array</entry> - <entry>determined by array type and size</entry> - <entry>int, followed by array contents</entry> - </row> - - <row> - <entry><literal>v</literal></entry> - <entry><constant>SD_BUS_TYPE_VARIANT</constant></entry> - <entry>variant</entry> - <entry>determined by the type argument</entry> - <entry>signature string, followed by variant contents</entry> - </row> - - <row> - <entry><literal>(</literal></entry> - <entry><constant>SD_BUS_TYPE_STRUCT_BEGIN</constant></entry> - <entry>array start</entry> - <entry morerows="1">determined by the nested types</entry> - <entry morerows="1">structure contents</entry> - </row> - <row> - <entry><literal>)</literal></entry> - <entry><constant>SD_BUS_TYPE_STRUCT_END</constant></entry> - <entry>array end</entry> - </row> - - <row> - <entry><literal>{</literal></entry> - <entry><constant>SD_BUS_TYPE_DICT_ENTRY_BEGIN</constant></entry> - <entry>dictionary entry start</entry> - <entry morerows="1">determined by the nested types</entry> - <entry morerows="1">dictionary contents</entry> - </row> - <row> - <entry><literal>}</literal></entry> - <entry><constant>SD_BUS_TYPE_DICT_ENTRY_END</constant></entry> - <entry>dictionary entry end</entry> - </row> - </tbody> - </tgroup> - </table> - - </refsect1> - - <refsect1> - <title>Types String Grammar</title> - - <programlisting>types ::= complete_type* -complete_type ::= basic_type | variant | structure | array | dictionary -basic_type ::= "y" | "n" | "q" | "u" | "i" | "x" | "t" | "d" | - "b" | "h" | - "s" | "o" | "g" -variant ::= "v" -structure ::= "(" complete_type+ ")" -array ::= "a" complete_type -dictionary ::= "a" "{" basic_type complete_type "}" -</programlisting> - </refsect1> - - <refsect1> - <title>Examples</title> - - <para>Append a single basic type (the string <literal>a string</literal>): - </para> - - <programlisting>sd_bus_message *m; -... -sd_bus_message_append(m, "s", "a string");</programlisting> - - <para>Append all types of integers:</para> - - <programlisting>uint8_t y = 1; -int16_t n = 2; -uint16_t q = 3; -int32_t i = 4; -uint32_t u = 5; -int32_t x = 6; -uint32_t t = 7; -double d = 8.0; -sd_bus_message_append(m, "ynqiuxtd", y, n, q, i, u, x, t, d);</programlisting> - - <para>Append a structure composed of a string and a D-Bus path:</para> - - <programlisting>sd_bus_message_append(m, "(so)", "a string", "/a/path"); -</programlisting> - - <para>Append an array of UNIX file descriptors:</para> - - <programlisting>sd_bus_message_append(m, "ah", 3, STDIN_FILENO, STDOUT_FILENO, STDERR_FILENO); -</programlisting> - - <para>Append a variant, with the real type "g" (signature), - and value "sdbusisgood":</para> - - <programlisting>sd_bus_message_append(m, "v", "g", "sdbusisgood");</programlisting> - - <para>Append a dictionary containing the mapping {1=>"a", 2=>"b", 3=>""}: - </para> - - <programlisting>sd_bus_message_append(m, "a{is}", 3, 1, "a", 2, "b", 3, NULL); - </programlisting> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, this call returns 0 or a positive - integer. On failure, this call returns a negative - errno-style error code.</para> - </refsect1> - - <xi:include href="sd_bus_message_append_basic.xml" xpointer="errors" /> - - <refsect1> - <title>Notes</title> - - <para><function>sd_bus_open_user()</function> and other functions - described here are available as a shared library, which can be - compiled and linked to with the - <constant>libsystemd-bus</constant> <citerefentry project='die-net'><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-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_message_append_array</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_bus_message_append_array.xml b/man/sd_bus_message_append_array.xml deleted file mode 100644 index 27db2a96c3..0000000000 --- a/man/sd_bus_message_append_array.xml +++ /dev/null @@ -1,213 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2014 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="sd_bus_message_append_array" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd_bus_message_append_array</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>A monkey with a typewriter</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_bus_message_append_array</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_bus_message_append_array</refname> - <refname>sd_bus_message_append_array_memfd</refname> - <refname>sd_bus_message_append_array_iovec</refname> - <refname>sd_bus_message_append_array_space</refname> - - <refpurpose>Append an array of fields to a D-Bus - message</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int sd_bus_message_append_array</funcdef> - <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> - <paramdef>char <parameter>type</parameter></paramdef> - <paramdef>char void *<parameter>ptr</parameter></paramdef> - <paramdef>size_t <parameter>size</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int sd_bus_message_append_array_memfd</funcdef> - <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> - <paramdef>char <parameter>type</parameter></paramdef> - <paramdef>int <parameter>memfd</parameter></paramdef> - <paramdef>uint64_t <parameter>offset</parameter></paramdef> - <paramdef>uint64_t <parameter>size</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int sd_bus_message_append_array_iovec</funcdef> - <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> - <paramdef>char <parameter>type</parameter></paramdef> - <paramdef>const struct iovec *<parameter>iov</parameter></paramdef> - <paramdef>unsigned <parameter>n</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int sd_bus_message_append_array_space</funcdef> - <paramdef>char <parameter>type</parameter></paramdef> - <paramdef>size_t <parameter>size</parameter></paramdef> - <paramdef>void **<parameter>ptr</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>The <function>sd_bus_message_append_array()</function> - function appends an array to a D-Bus message - <parameter>m</parameter>. A container will be opened, the array - contents appended, and the container closed. The parameter - <parameter>type</parameter> determines how the pointer - <parameter>p</parameter> is interpreted. - <parameter>type</parameter> must be one of the "trivial" types - <literal>y</literal>, <literal>n</literal>, <literal>q</literal>, - <literal>i</literal>, <literal>u</literal>, <literal>x</literal>, - <literal>t</literal>, <literal>d</literal> (but not - <literal>b</literal>), as defined by the <ulink - url="http://dbus.freedesktop.org/doc/dbus-specification.html#basic-types">Basic - Types</ulink> section of the D-Bus specification, and listed in - <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - Pointer <parameter>p</parameter> must point to an array of size - <parameter>size</parameter> bytes containing items of the - respective type. Size <parameter>size</parameter> must be a - multiple of the size of the type <parameter>type</parameter>. As a - special case, <parameter>p</parameter> may be - <constant>NULL</constant>, if <parameter>size</parameter> is 0. - The memory pointed to by <parameter>p</parameter> is copied into - the memory area containing the message and stays in possession of - the caller. The caller may hence freely change the data after this - call without affecting the message the array was appended - to.</para> - - <para>The <function>sd_bus_message_append_array_memfd()</function> - function appends an array of a trivial type to message - <parameter>m</parameter>, similar to - <function>sd_bus_message_append_array()</function>. The contents - of the memory file descriptor <parameter>memfd</parameter> - starting at the specified offset and of the specified size is - used as the contents of the array. The offset and size must be a - multiple of the size of the type - <parameter>type</parameter>. However, as a special exception, if - the offset is specified as zero and the size specified as - UINT64_MAX the full memory file descriptor contents is used. The - memory file descriptor is sealed by this call if it has not been - sealed yet, and cannot be modified after this call. See - <citerefentry - project='man-pages'><refentrytitle>memfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for details about memory file descriptors. Appending arrays with - memory file descriptors enables efficient zero-copy data transfer, - as the memory file descriptor may be passed as-is to the - destination, without copying the memory in it to the destination - process. Not all protocol transports support passing memory file - descriptors between participants, in which case this call will - automatically fall back to copying. Also, as memory file - descriptor passing is inefficient for smaller amounts of data, - copying might still be enforced even where memory file descriptor - passing is supported.</para> - - <para>The <function>sd_bus_message_append_array_iovec()</function> - function appends an array of a trivial type to the message - <parameter>m</parameter>, similar to - <function>sd_bus_message_append_array()</function>. Contents of - the I/O vector array <parameter>iov</parameter> are used as the - contents of the array. The total size of - <parameter>iov</parameter> payload (the sum of - <structfield>iov_len</structfield> fields) must be a multiple of - the size of the type <parameter>type</parameter>. The - <parameter>iov</parameter> argument must point to - <parameter>n</parameter> I/O vector structures. Each structure may - have the <structname>iov_base</structname> field set, in which - case the memory pointed to will be copied into the message, or - unset (set to zero), in which case a block of zeros of length - <structname>iov_len</structname> bytes will be inserted. The - memory pointed at by <parameter>iov</parameter> may be changed - after this call.</para> - - <para>The <function>sd_bus_message_append_array_space()</function> - function appends space for an array of a trivial type to message - <parameter>m</parameter>. It behaves the same as - <function>sd_bus_message_append_array()</function>, but instead of - copying items to the message, it returns a pointer to the - destination area to the caller in pointer - <parameter>p</parameter>. The caller should subsequently write the - array contents to this memory. Modifications to the memory - pointed to should only occur until the next operation on the bus - message is invoked. Most importantly, the memory should not be - altered anymore when another field has been added to the message - or the message has been sealed.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, these calls return 0 or a positive integer. On - failure, they return a negative errno-style error code.</para> - </refsect1> - - <xi:include href="sd_bus_message_append_basic.xml" xpointer="errors" /> - - <refsect1> - <title>Notes</title> - - <para><function>sd_bus_append_array()</function> and other - functions described here are available as a shared library, which - can be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><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-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>memfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>, - <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html">The D-Bus specification</ulink> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_bus_message_append_basic.xml b/man/sd_bus_message_append_basic.xml deleted file mode 100644 index 276953af69..0000000000 --- a/man/sd_bus_message_append_basic.xml +++ /dev/null @@ -1,295 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2014 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="sd_bus_message_append_basic"> - - <refentryinfo> - <title>sd_bus_message_append_basic</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>A monkey with a typewriter</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_bus_message_append_basic</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_bus_message_append_basic</refname> - - <refpurpose>Attach a single field to a message</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int sd_bus_message_append_basic</funcdef> - <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> - <paramdef>char <parameter>type</parameter></paramdef> - <paramdef>const void *<parameter>p</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_bus_message_append_basic()</function> appends a - single field to the message <parameter>m</parameter>. The - parameter <parameter>type</parameter> determines how the pointer - <parameter>p</parameter> is interpreted. - <parameter>type</parameter> must be one of the basic types as - defined by the <ulink - url="http://dbus.freedesktop.org/doc/dbus-specification.html#basic-types">Basic - Types</ulink> section of the D-Bus specification, and listed in - the table below. - </para> - - <table id='format-specifiers'> - <title>Item type specifiers</title> - - <tgroup cols='5'> - <colspec colname='specifier' /> - <colspec colname='constant' /> - <colspec colname='description' /> - <colspec colname='size' /> - <colspec colname='ctype' /> - <thead> - <row> - <entry>Specifier</entry> - <entry>Constant</entry> - <entry>Description</entry> - <entry>Size</entry> - <entry>Expected C Type</entry> - </row> - </thead> - <tbody> - <row> - <entry><literal>y</literal></entry> - <entry><constant>SD_BUS_TYPE_BYTE</constant></entry> - <entry>unsigned integer</entry> - <entry>1 byte</entry> - <entry>uint8_t</entry> - </row> - - <row> - <entry><literal>b</literal></entry> - <entry><constant>SD_BUS_TYPE_BOOLEAN</constant></entry> - <entry>boolean</entry> - <entry>4 bytes</entry> - <entry>int</entry> - </row> - - <row> - <entry><literal>n</literal></entry> - <entry><constant>SD_BUS_TYPE_INT16</constant></entry> - <entry>signed integer</entry> - <entry>2 bytes</entry> - <entry>int16_t</entry> - </row> - - <row> - <entry><literal>q</literal></entry> - <entry><constant>SD_BUS_TYPE_UINT16</constant></entry> - <entry>unsigned integer</entry> - <entry>2 bytes</entry> - <entry>uint16_t</entry> - </row> - - <row> - <entry><literal>i</literal></entry> - <entry><constant>SD_BUS_TYPE_INT32</constant></entry> - <entry>signed integer</entry> - <entry>4 bytes</entry> - <entry>int32_t</entry> - </row> - - <row> - <entry><literal>u</literal></entry> - <entry><constant>SD_BUS_TYPE_UINT32</constant></entry> - <entry>unsigned integer</entry> - <entry>4 bytes</entry> - <entry>uint32_t</entry> - </row> - - <row> - <entry><literal>x</literal></entry> - <entry><constant>SD_BUS_TYPE_INT64</constant></entry> - <entry>signed integer</entry> - <entry>8 bytes</entry> - <entry>int64_t</entry> - </row> - - <row> - <entry><literal>t</literal></entry> - <entry><constant>SD_BUS_TYPE_UINT64</constant></entry> - <entry>unsigned integer</entry> - <entry>8 bytes</entry> - <entry>uint64_t</entry> - </row> - - <row> - <entry><literal>d</literal></entry> - <entry><constant>SD_BUS_TYPE_DOUBLE</constant></entry> - <entry>floating-point</entry> - <entry>8 bytes</entry> - <entry>double</entry> - </row> - - <row> - <entry><literal>s</literal></entry> - <entry><constant>SD_BUS_TYPE_STRING</constant></entry> - <entry>Unicode string</entry> - <entry>variable</entry> - <entry>char[]</entry> - </row> - - <row> - <entry><literal>o</literal></entry> - <entry><constant>SD_BUS_TYPE_OBJECT_PATH</constant></entry> - <entry>object path</entry> - <entry>variable</entry> - <entry>char[]</entry> - </row> - - <row> - <entry><literal>g</literal></entry> - <entry><constant>SD_BUS_TYPE_SIGNATURE</constant></entry> - <entry>signature</entry> - <entry>variable</entry> - <entry>char[]</entry> - </row> - - <row> - <entry><literal>h</literal></entry> - <entry><constant>SD_BUS_TYPE_UNIX_FD</constant></entry> - <entry>UNIX file descriptor</entry> - <entry>4 bytes</entry> - <entry>int</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>The value of the parameter is copied into a memory area held - by the message object, stays in the possession of the caller and - may hence be freely changed after this call without affecting the - bus message it has been added to. If <parameter>type</parameter> - is <literal>h</literal> (UNIX file descriptor), the descriptor is - duplicated by this call and the passed descriptor stays in - possession of the caller.</para> - - <para>For types <literal>s</literal>, <literal>o</literal>, and - <literal>g</literal>, the parameter <parameter>p</parameter> is - interpreted as a pointer to a <constant>NUL</constant>-terminated - character sequence. As a special case, a <constant>NULL</constant> - pointer is interpreted as an empty string. The string should be - valid Unicode string encoded as UTF-8. In case of the two latter - types, the additional requirements for a D-Bus object path or - type signature should be satisfied. Those requirements should be - verified by the recipient of the message. - </para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, this call returns 0 or a positive integer. On - failure, it returns a negative errno-style error code.</para> - </refsect1> - - <refsect1 id='errors'> - <title>Errors</title> - - <para>Returned errors may indicate the following problems:</para> - - <variablelist> - - <varlistentry> - <term><constant>-EINVAL</constant></term> - - <listitem><para>Specified parameter is invalid. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-EPERM</constant></term> - - <listitem><para>Message has been sealed. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ESTALE</constant></term> - - <listitem><para>Message is in invalid state. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ENXIO</constant></term> - - <listitem><para>Message cannot be appended to. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ENOMEM</constant></term> - - <listitem><para>Memory allocation failed.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>The <function>sd_bus_append_basic()</function> function - described here is available as a shared library, which can be - compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><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-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html">The D-Bus specification</ulink> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_bus_message_append_string_memfd.xml b/man/sd_bus_message_append_string_memfd.xml deleted file mode 100644 index 9e99999bf3..0000000000 --- a/man/sd_bus_message_append_string_memfd.xml +++ /dev/null @@ -1,153 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2014 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="sd_bus_message_append_string_memfd" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd_bus_message_append_string_memfd</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>A monkey with a typewriter</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_bus_message_append_string_memfd</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_bus_message_append_string_memfd</refname> - <refname>sd_bus_message_append_string_iovec</refname> - <refname>sd_bus_message_append_string_space</refname> - - <refpurpose>Attach a string to a message</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int sd_bus_message_append_string_memfd</funcdef> - <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> - <paramdef>int <parameter>memfd</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int sd_bus_message_append_string_iovec</funcdef> - <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> - <paramdef>const struct iovec *<parameter>iov</parameter></paramdef> - <paramdef>unsigned <parameter>n</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int sd_bus_message_append_string_space</funcdef> - <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> - <paramdef>size_t <parameter>size</parameter></paramdef> - <paramdef>char **<parameter>s</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>The functions - <function>sd_bus_message_append_string_memfd</function> and - <function>sd_bus_message_append_string_iovec</function> can be - used to append a single string (item of type <literal>s</literal>) - to message <parameter>m</parameter>.</para> - - <para>In case of - <function>sd_bus_message_append_string_memfd</function>, the - contents of <parameter>memfd</parameter> are the string. They must - satisfy the same constraints as described for the - <literal>s</literal> type in - <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> - - <para>In case of - <function>sd_bus_message_append_string_iovec</function>, the - payload of <parameter>iov</parameter> is the string. It must - satisfy the same constraints as described for the - <literal>s</literal> type in - <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> - - <para>The <parameter>iov</parameter> argument must point to - <parameter>n</parameter> <structname>struct iovec</structname> - structures. Each structure may have the - <structname>iov_base</structname> field set, in which case the - memory pointed to will be copied into the message, or unset, in - which case a block of spaces (ASCII 32) of length - <structname>iov_len</structname> will be inserted. The - memory pointed at by <parameter>iov</parameter> may be changed - after this call.</para> - - <para>The - <function>sd_bus_message_append_string_space</function> function appends - space for a string to message <parameter>m</parameter>. It behaves - similar to <function>sd_bus_message_append_basic</function> with - type <literal>s</literal>, but instead of copying a string into - the message, it returns a pointer to the destination area to - the caller in pointer <parameter>p</parameter>. Space for the string - of length <parameter>size</parameter> plus the terminating - <constant>NUL</constant> is allocated.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, those calls return 0 or a positive integer. On - failure, they returns a negative errno-style error code.</para> - </refsect1> - - <xi:include href="sd_bus_message_append_basic.xml" xpointer="errors" /> - - <refsect1> - <title>Notes</title> - - <para>The functions described here are available as a shared library, - which can be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><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-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html">The D-Bus specification</ulink> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_bus_message_append_strv.xml b/man/sd_bus_message_append_strv.xml deleted file mode 100644 index 0f77adcc8b..0000000000 --- a/man/sd_bus_message_append_strv.xml +++ /dev/null @@ -1,116 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2014 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="sd_bus_message_append_strv" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd_bus_message_append_strv</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>A monkey with a typewriter</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_bus_message_append_strv</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_bus_message_append_strv</refname> - - <refpurpose>Attach an array of strings to a message</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int sd_bus_message_append_strv</funcdef> - <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> - <paramdef>char **<parameter>l</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>The <function>sd_bus_message_append</function> function can be - used to append an array of strings to message - <parameter>m</parameter>. The parameter <parameter>l</parameter> - shall point to a <constant>NULL</constant>-terminated array of pointers - to <constant>NUL</constant>-terminated strings. Each string must - satisfy the same constraints as described for the - <literal>s</literal> type in - <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - </para> - - <para>The memory pointed at by <parameter>p</parameter> and the - contents of the strings themselves are copied into the memory area - containing the message and may be changed after this call. Note - that the signature of <parameter>l</parameter> parameter is to be - treated as <type>const char *const *</type>, and the contents - will not be modified.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, this call returns 0 or a positive integer. On - failure, a negative errno-style error code is returned.</para> - </refsect1> - - <xi:include href="sd_bus_message_append_basic.xml" xpointer="errors" /> - - <refsect1> - <title>Notes</title> - - <para>The <function>sd_bus_append_append_strv()</function> function - described here is available as a shared library, which can be - compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><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-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_message_append_array</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html">The D-Bus specification</ulink> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_bus_message_get_cookie.xml b/man/sd_bus_message_get_cookie.xml deleted file mode 100644 index 3328eead3d..0000000000 --- a/man/sd_bus_message_get_cookie.xml +++ /dev/null @@ -1,146 +0,0 @@ -<?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 2013 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_bus_message_get_cookie"> - - <refentryinfo> - <title>sd_bus_message_get_cookie</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_bus_message_get_cookie</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_bus_message_get_cookie</refname> - <refname>sd_bus_message_get_reply_cookie</refname> - <refpurpose>Returns the transaction cookie of a message</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_bus_message_get_cookie</function></funcdef> - <paramdef>sd_bus_message *<parameter>message</parameter></paramdef> - <paramdef>uint64_t *<parameter>cookie</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_message_get_reply_cookie</function></funcdef> - <paramdef>sd_bus_message *<parameter>message</parameter></paramdef> - <paramdef>uint64_t *<parameter>cookie</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_bus_message_get_cookie()</function> returns the - transaction cookie of a message. The cookie uniquely identifies a - message within each bus peer, but is not globally unique. It is - assigned when a message is sent.</para> - - <para><function>sd_bus_message_get_reply_cookie()</function> - returns the transaction cookie of the message the specified - message is a response to. When a reply message is generated for a - method call message, its cookie is copied over into this field. - Note that while every message that is transferred is identified by - a cookie, only response messages carry a reply cookie - field.</para> - - <para>Both functions take a message object as first parameter and - a place to store the 64-bit cookie in.</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> - - <para>On success, the cookie/reply cookie is returned in the - specified 64-bit unsigned integer variable.</para> - </refsect1> - - <refsect1> - <title>Errors</title> - - <para>Returned errors may indicate the following problems:</para> - - <variablelist> - <varlistentry> - <term><constant>-EINVAL</constant></term> - - <listitem><para>A specified parameter - is invalid.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ENODATA</constant></term> - - <listitem><para>No cookie has been assigned to this message. - This either indicates that the message has not been sent yet - and hence has no cookie assigned, or that the message is not a - method response message and hence carries a reply cookie - field.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>The <function>sd_bus_message_get_cookie()</function> and - <function>sd_bus_message_get_reply_cookie()</function> interfaces - are available as a shared library, which can be compiled and - linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><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-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_bus_message_get_monotonic_usec.xml b/man/sd_bus_message_get_monotonic_usec.xml deleted file mode 100644 index 2c0a8a5d54..0000000000 --- a/man/sd_bus_message_get_monotonic_usec.xml +++ /dev/null @@ -1,181 +0,0 @@ -<?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 2013 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_bus_message_get_monotonic_usec"> - - <refentryinfo> - <title>sd_bus_message_get_monotonic_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_bus_message_get_monotonic_usec</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_bus_message_get_monotonic_usec</refname> - <refname>sd_bus_message_get_realtime_usec</refname> - <refname>sd_bus_message_get_seqnum</refname> - <refpurpose>Retrieve the sender timestamps and sequence number of a message</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_bus_message_get_monotonic_usec</function></funcdef> - <paramdef>sd_bus_message *<parameter>message</parameter></paramdef> - <paramdef>uint64_t *<parameter>usec</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_message_get_realtime_usec</function></funcdef> - <paramdef>sd_bus_message *<parameter>message</parameter></paramdef> - <paramdef>uint64_t *<parameter>usec</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_message_get_seqnum</function></funcdef> - <paramdef>sd_bus_message *<parameter>message</parameter></paramdef> - <paramdef>uint64_t *<parameter>seqnum</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_bus_message_get_monotonic_usec()</function> - returns the monotonic timestamp of the time the message was sent. - This value is in microseconds since the - <constant>CLOCK_MONOTONIC</constant> epoch, see - <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for details.</para> - - <para>Similarly, - <function>sd_bus_message_get_realtime_usec()</function> returns - the realtime (wallclock) timestamp of the time the message was - sent. This value is in microseconds since Jan 1st, 1970, i.e. in - the <constant>CLOCK_REALTIME</constant> clock.</para> - - <para><function>sd_bus_message_get_seqnum()</function> returns the - kernel-assigned sequence number of the message. The kernel assigns - a global, monotonically increasing sequence number to all messages - transmitted on the local system, at the time the message was sent. - This sequence number is useful for determining message send order, - even across different buses of the local system. The sequence - number combined with the boot ID of the system (as returned by - <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry>) - is a suitable globally unique identifier for bus messages.</para> - - <para>Note that the sending order and receiving order of messages - might differ, in particular for broadcast messages. This means - that the sequence number and the timestamps of messages a client - reads are not necessarily monotonically increasing.</para> - - <para>These timestamps and the sequence number are attached to - each message by the kernel and cannot be manipulated by the - sender.</para> - - <para>Note that these timestamps are only available on some bus - transports, and only after support for them has been negotiated - with the - <citerefentry><refentrytitle>sd_bus_negotiate_timestamp</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call.</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> - - <para>On success, the timestamp or sequence number is returned in - the specified 64-bit unsigned integer variable.</para> - </refsect1> - - <refsect1> - <title>Errors</title> - - <para>Returned errors may indicate the following problems:</para> - - <variablelist> - <varlistentry> - <term><constant>-EINVAL</constant></term> - - <listitem><para>A specified parameter is - invalid.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ENODATA</constant></term> - - <listitem><para>No timestamp or sequence number information is - attached to the passed message. This error is returned if the - underlying transport does not support timestamping or - assigning of sequence numbers, or if this feature has not been - negotiated with - <citerefentry><refentrytitle>sd_bus_negotiate_timestamp</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>The - <function>sd_bus_message_get_monotonic_usec()</function>, - <function>sd_bus_message_get_realtime_usec()</function>, and - <function>sd_bus_message_get_seqnum()</function> interfaces are - available as a shared library, which can be compiled and linked to - with the - <constant>libsystemd</constant> <citerefentry project='die-net'><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-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_negotiate_timestamp</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_bus_negotiate_fds.xml b/man/sd_bus_negotiate_fds.xml deleted file mode 100644 index a538b13cf0..0000000000 --- a/man/sd_bus_negotiate_fds.xml +++ /dev/null @@ -1,200 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2014 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_bus_negotiate_fds"> - - <refentryinfo> - <title>sd_bus_negotiate_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_bus_negotiate_fds</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_bus_negotiate_fds</refname> - <refname>sd_bus_negotiate_timestamp</refname> - <refname>sd_bus_negotiate_creds</refname> - - <refpurpose>Control feature negotiation on bus connections</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_bus_negotiate_fds</function></funcdef> - <paramdef>sd_bus *<parameter>bus</parameter></paramdef> - <paramdef>int <parameter>b</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_negotiate_timestamp</function></funcdef> - <paramdef>sd_bus *<parameter>bus</parameter></paramdef> - <paramdef>int <parameter>b</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_negotiate_creds</function></funcdef> - <paramdef>sd_bus *<parameter>bus</parameter></paramdef> - <paramdef>int <parameter>b</parameter></paramdef> - <paramdef>uint64_t <parameter>mask</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_bus_negotiate_fds()</function> controls whether - file descriptor passing shall be negotiated for the specified bus - connection. It takes a bus object and a boolean, which, when true, - enables file descriptor passing, and, when false, disables - it. Note that not all transports and servers support file - descriptor passing. In particular, networked transports generally - do not support file descriptor passing. To find out whether file - descriptor passing is available after negotiation, use - <citerefentry><refentrytitle>sd_bus_can_send</refentrytitle><manvolnum>3</manvolnum></citerefentry> - and pass <constant>SD_BUS_TYPE_UNIX_FD</constant>. Note that file - descriptor passing is always enabled for both sending and - receiving or for neither, but never only in one direction. By - default, file descriptor passing is negotiated for all - connections.</para> - - <para>Note that when bus activation is used, it is highly - recommended to set the <option>AcceptFileDescriptors=</option> - setting in the <filename>.busname</filename> unit file to the same - setting as negotiated by the program ultimately activated. By - default, file descriptor passing is enabled for both.</para> - - <para><function>sd_bus_negotiate_timestamps()</function> controls - whether implicit sender timestamps shall be attached automatically - to all incoming messages. Takes a bus object and a boolean, which, - when true, enables timestamping, and, when false, disables it. - Use - <citerefentry><refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_message_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_message_get_seqnum</refentrytitle><manvolnum>3</manvolnum></citerefentry> - to query the timestamps of incoming messages. If negotiation is - disabled or not supported, these calls will fail with - <constant>-ENODATA</constant>. Note that not all transports - support timestamping of messages. Specifically, timestamping is - only available on the kdbus transport, but not on dbus1. The - timestamping is applied by the kernel and cannot be manipulated by - userspace. By default, message timestamping is not negotiated for - connections.</para> - - <para><function>sd_bus_negotiate_creds()</function> controls - whether and which implicit sender credentials shall be attached - automatically to all incoming messages. Takes a bus object and a - boolean indicating whether to enable or disable the credential - parts encoded in the bit mask value argument. Note that not all - transports support attaching sender credentials to messages, or do - not support all types of sender credential parameters, or might - suppress them under certain circumstances for individual - messages. Specifically, implicit sender credentials on messages - are only fully supported on kdbus transports, and dbus1 only - supports <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>. The sender - credentials are attached by the kernel and cannot be manipulated - by userspace, and are thus suitable for authorization - decisions. By default, only - <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant> and - <constant>SD_BUS_CREDS_UNIQUE_NAME</constant> are enabled. In - fact, these two credential fields are always sent along and cannot - be turned off.</para> - - <para>The <function>sd_bus_negotiate_fds()</function> function may - be called only before the connection has been started with - <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Both - <function>sd_bus_negotiate_timestamp()</function> and - <function>sd_bus_negotiate_creds()</function> may also be called - after a connection has been set up. Note that, when operating on a - connection that is shared between multiple components of the same - program (for example via - <citerefentry><refentrytitle>sd_bus_default</refentrytitle><manvolnum>3</manvolnum></citerefentry>), - it is highly recommended to only enable additional per message - metadata fields, but never disable them again, in order not to - disable functionality needed by other components.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, these functions return 0 or a - positive integer. On failure, they return a negative errno-style - error code.</para> - </refsect1> - - <refsect1> - <title>Errors</title> - - <para>Returned errors may indicate the following problems:</para> - - <variablelist> - <varlistentry> - <term><constant>-EPERM</constant></term> - - <listitem><para>The bus connection has already been started.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para><function>sd_bus_negotiate_fds()</function> and the other - functions described here are available as a shared library, which - can be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><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-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_message_can_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_message_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_message_get_seqnum</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.busname</refentrytitle><manvolnum>5</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_bus_new.xml b/man/sd_bus_new.xml deleted file mode 100644 index d281b5dd44..0000000000 --- a/man/sd_bus_new.xml +++ /dev/null @@ -1,189 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2014 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="sd_bus_new"> - - <refentryinfo> - <title>sd_bus_new</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>A monkey with a typewriter</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_bus_new</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_bus_new</refname> - <refname>sd_bus_ref</refname> - <refname>sd_bus_unref</refname> - <refname>sd_bus_unrefp</refname> - - <refpurpose>Create a new bus object and create or destroy references to it</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_bus_new</function></funcdef> - <paramdef>sd_bus **<parameter>bus</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>sd_bus *<function>sd_bus_ref</function></funcdef> - <paramdef>sd_bus *<parameter>bus</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>sd_bus *<function>sd_bus_unref</function></funcdef> - <paramdef>sd_bus *<parameter>bus</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>void <function>sd_bus_unrefp</function></funcdef> - <paramdef>sd_bus **<parameter>bus</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_bus_new()</function> creates a new bus - object. This object is reference-counted, and will be destroyed - when all references are gone. Initially, the caller of this - function owns the sole reference and the bus object will not be - connected to any bus. To connect it to a bus, make sure - to set an address with - <citerefentry><refentrytitle>sd_bus_set_address</refentrytitle><manvolnum>3</manvolnum></citerefentry> - or a related call, and then start the connection with - <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> - - <para>In most cases, it is a better idea to invoke - <citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry> - or related calls instead of the more low-level - <function>sd_bus_new()</function> and - <function>sd_bus_start()</function>. The higher-level calls not - only allocate a bus object but also start the connection to a - well-known bus in a single function invocation.</para> - - <para><function>sd_bus_ref()</function> increases the reference - counter of <parameter>bus</parameter> by one.</para> - - <para><function>sd_bus_unref()</function> decreases the reference - counter of <parameter>bus</parameter> by one. Once the reference - count has dropped to zero, <parameter>bus</parameter> is destroyed - and cannot be used anymore, so further calls to - <function>sd_bus_ref()</function> or - <function>sd_bus_unref()</function> are illegal.</para> - - <para><function>sd_bus_unrefp()</function> is similar to - <function>sd_bus_unref()</function> but takes a pointer to a - pointer to an <type>sd_bus</type> object. This call is useful in - conjunction with GCC's and LLVM's <ulink - url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up - Variable Attribute</ulink>. Note that this function is defined as - inline function. Use a declaration like the following, in order to - allocate a bus object that is freed automatically as the code - block is left:</para> - - <programlisting>{ - __attribute__((cleanup(sd_bus_unrefp)) sd_bus *bus = NULL; - int r; - … - r = sd_bus_default(&bus); - if (r < 0) - fprintf(stderr, "Failed to allocate bus: %s\n", strerror(-r)); - … -}</programlisting> - - <para><function>sd_bus_ref()</function>, - <function>sd_bus_unref()</function> and - <function>sd_bus_unrefp()</function> execute no operation if the - passed in bus object is <constant>NULL</constant>.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, <function>sd_bus_new()</function> returns 0 or a - positive integer. On failure, it returns a negative errno-style - error code.</para> - - <para><function>sd_bus_ref()</function> always returns the argument. - </para> - - <para><function>sd_bus_unref()</function> always returns - <constant>NULL</constant>.</para> - </refsect1> - - <refsect1> - <title>Errors</title> - - <para>Returned errors may indicate the following problems:</para> - - <variablelist> - <varlistentry> - <term><constant>-ENOMEM</constant></term> - - <listitem><para>Memory allocation failed.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para><function>sd_bus_new()</function> and other functions - described here are available as a shared library, which can be - compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><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-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_open_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_open_system</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_bus_path_encode.xml b/man/sd_bus_path_encode.xml deleted file mode 100644 index 3088243e45..0000000000 --- a/man/sd_bus_path_encode.xml +++ /dev/null @@ -1,188 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2014 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="sd_bus_path_encode"> - - <refentryinfo> - <title>sd_bus_path_encode</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>A monkey with a typewriter</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_bus_path_encode</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_bus_path_encode</refname> - <refname>sd_bus_path_encode_many</refname> - <refname>sd_bus_path_decode</refname> - <refname>sd_bus_path_decode_many</refname> - - <refpurpose>Convert an external identifier into an object path and back</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_bus_path_encode</function></funcdef> - <paramdef>const char *<parameter>prefix</parameter></paramdef> - <paramdef>const char *<parameter>external_id</parameter></paramdef> - <paramdef>char **<parameter>ret_path</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_path_encode_many</function></funcdef> - <paramdef>char **<parameter>out</parameter></paramdef> - <paramdef>const char *<parameter>path_template</parameter></paramdef> - <paramdef>...</paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_path_decode</function></funcdef> - <paramdef>const char *<parameter>path</parameter></paramdef> - <paramdef>const char *<parameter>prefix</parameter></paramdef> - <paramdef>char **<parameter>ret_external_id</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_path_decode_many</function></funcdef> - <paramdef>const char *<parameter>path</parameter></paramdef> - <paramdef>const char *<parameter>path_template</parameter></paramdef> - <paramdef>...</paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_bus_path_encode()</function> and - <function>sd_bus_path_decode()</function> convert external - identifier strings into object paths and back. These functions are - useful to map application-specific string identifiers of any kind - into bus object paths in a simple, reversible and safe way.</para> - - <para><function>sd_bus_path_encode()</function> takes a bus path - prefix and an external identifier string as arguments, plus a - place to store the returned bus path string. The bus path prefix - must be a valid bus path, starting with a slash - <literal>/</literal>, and not ending in one. The external - identifier string may be in any format, may be the empty string, - and has no restrictions on the charset — however, it must - always be <constant>NUL</constant>-terminated. The returned string - will be the concatenation of the bus path prefix plus an escaped - version of the external identifier string. This operation may be - reversed with <function>sd_bus_decode()</function>. It is - recommended to only use external identifiers that generally - require little escaping to be turned into valid bus path - identifiers (for example, by sticking to a 7-bit ASCII character - set), in order to ensure the resulting bus path is still short and - easily processed.</para> - - <para><function>sd_bus_path_decode()</function> reverses the - operation of <function>sd_bus_path_encode()</function> and thus - regenerates an external identifier string from a bus path. It - takes a bus path and a prefix string, plus a place to store the - returned external identifier string. If the bus path does not - start with the specified prefix, 0 is returned and the returned - string is set to <constant>NULL</constant>. Otherwise, the - string following the prefix is unescaped and returned in the - external identifier string.</para> - - <para>The escaping used will replace all characters which are - invalid in a bus object path by <literal>_</literal>, followed by a - hexadecimal value. As a special case, the empty string will be - replaced by a lone <literal>_</literal>.</para> - - <para><function>sd_bus_path_encode_many()</function> works like - its counterpart <function>sd_bus_path_encode()</function>, but - takes a path template as argument and encodes multiple labels - according to its embedded directives. For each - <literal>%</literal> character found in the template, the caller - must provide a string via varargs, which will be encoded and - embedded at the position of the <literal>%</literal> character. - Any other character in the template is copied verbatim into the - encoded path.</para> - - <para><function>sd_bus_path_decode_many()</function> does the - reverse of <function>sd_bus_path_encode_many()</function>. It - decodes the passed object path according to the given - path template. For each <literal>%</literal> character in the - template, the caller must provide an output storage - (<literal>char **</literal>) via varargs. The decoded label - will be stored there. Each <literal>%</literal> character will - only match the current label. It will never match across labels. - Furthermore, only a single directive is allowed per label. - If <literal>NULL</literal> is passed as output storage, the - label is verified but not returned to the caller.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, <function>sd_bus_path_encode()</function> - returns positive or 0, and a valid bus path in the return - argument. On success, <function>sd_bus_path_decode()</function> - returns a positive value if the prefixed matched, or 0 if it - did not. If the prefix matched, the external identifier is returned - in the return parameter. If it did not match, NULL is returned in - the return parameter. On failure, a negative errno-style error - number is returned by either function. The returned strings must - be - <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>'d - by the caller.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para><function>sd_bus_path_encode()</function> and - <function>sd_bus_path_decode()</function> are available as a - shared library, which can be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><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-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_bus_request_name.xml b/man/sd_bus_request_name.xml deleted file mode 100644 index f07ae09555..0000000000 --- a/man/sd_bus_request_name.xml +++ /dev/null @@ -1,213 +0,0 @@ -<?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 2013 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_bus_request_name"> - - <refentryinfo> - <title>sd_bus_request_name</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_bus_request_name</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_bus_request_name</refname> - <refname>sd_bus_release_name</refname> - <refpurpose>Request or release a well-known service name on a bus</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_bus_request_name</function></funcdef> - <paramdef>sd_bus *<parameter>bus</parameter></paramdef> - <paramdef>const char *<parameter>name</parameter></paramdef> - <paramdef>uint64_t <parameter>flags</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_release_name</function></funcdef> - <paramdef>sd_bus *<parameter>bus</parameter></paramdef> - <paramdef>const char *<parameter>name</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_bus_request_name()</function> requests a - well-known service name on a bus. It takes a bus connection, a - valid bus name and a flags parameter. The flags parameter is a - combination of the following flags:</para> - - <variablelist> - <varlistentry> - <term><varname>SD_BUS_NAME_ALLOW_REPLACEMENT</varname></term> - - <listitem><para>After acquiring the name successfully, permit - other peers to take over the name when they try to acquire it - with the <varname>SD_BUS_NAME_REPLACE_EXISTING</varname> flag - set. If <varname>SD_BUS_NAME_ALLOW_REPLACEMENT</varname> is - not set on the original request, such a request by other peers - will be denied.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>SD_BUS_NAME_REPLACE_EXISTING</varname></term> - - <listitem><para>Take over the name if it is already acquired - by another peer, and that other peer has permitted takeover by - setting <varname>SD_BUS_NAME_ALLOW_REPLACEMENT</varname> while - acquiring it.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>SD_BUS_NAME_QUEUE</varname></term> - - <listitem><para>Queue the acquisition of the name when the - name is already taken.</para></listitem> - </varlistentry> - </variablelist> - - <para><function>sd_bus_release_name()</function> releases an - acquired well-known name. It takes a bus connection and a valid - bus name as parameters.</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> - - <para>If <varname>SD_BUS_NAME_QUEUE</varname> is specified, - <function>sd_bus_request_name()</function> will return 0 when the - name is already taken by another peer and the client has been - added to the queue for the name. In that case, the caller can - subscribe to <literal>NameOwnerChanged</literal> signals to be - notified when the name is successfully acquired. - <function>sd_bus_request_name()</function> returns > 0 when the - name has immediately been acquired successfully.</para> - </refsect1> - - <refsect1> - <title>Errors</title> - - <para>Returned errors may indicate the following problems:</para> - - <variablelist> - <varlistentry> - <term><constant>-EALREADY</constant></term> - - <listitem><para>The caller already is the owner of the - specified name.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-EEXIST</constant></term> - - <listitem><para>The name has already been acquired by a - different peer, and SD_BUS_NAME_REPLACE_EXISTING was not - specified or the other peer did not specify - SD_BUS_NAME_ALLOW_REPLACEMENT while acquiring the - name.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ESRCH</constant></term> - - <listitem><para>It was attempted to release a name that is - currently not registered on the bus.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-EADDRINUSE</constant></term> - - <listitem><para>It was attempted to release a name that is - owned by a different peer on the bus.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-EINVAL</constant></term> - - <listitem><para>A specified parameter is invalid. This is also - generated when the requested name is a special service name - reserved by the D-Bus specification, or when the operation is - requested on a connection that does not refer to a - bus.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ENOTCONN</constant></term> - - <listitem><para>The bus connection has been - disconnected.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ECHILD</constant></term> - - <listitem><para>The bus connection has been created in a - different process than the current one.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>The <function>sd_bus_acquire_name()</function> and - <function>sd_bus_release_name()</function> interfaces are - available as a shared library, which can be compiled and linked to - with the - <constant>libsystemd</constant> <citerefentry project='die-net'><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-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_event_add_child.xml b/man/sd_event_add_child.xml deleted file mode 100644 index bc732db7fa..0000000000 --- a/man/sd_event_add_child.xml +++ /dev/null @@ -1,246 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2014 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="sd_event_add_child" xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd_event_add_child</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>More text</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_event_add_child</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_event_add_child</refname> - <refname>sd_event_source_get_child_pid</refname> - <refname>sd_event_child_handler_t</refname> - - <refpurpose>Add a child process state change event source to an event loop</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> - - <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo> - - <funcprototype> - <funcdef>typedef int (*<function>sd_event_child_handler_t</function>)</funcdef> - <paramdef>sd_event_source *<parameter>s</parameter></paramdef> - <paramdef>const siginfo_t *<parameter>si</parameter></paramdef> - <paramdef>void *<parameter>userdata</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_event_add_child</function></funcdef> - <paramdef>sd_event *<parameter>event</parameter></paramdef> - <paramdef>sd_event_source **<parameter>source</parameter></paramdef> - <paramdef>pid_t <parameter>pid</parameter></paramdef> - <paramdef>int <parameter>options</parameter></paramdef> - <paramdef>sd_event_child_handler_t <parameter>handler</parameter></paramdef> - <paramdef>void *<parameter>userdata</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_event_source_get_child_pid</function></funcdef> - <paramdef>sd_event_source *<parameter>source</parameter></paramdef> - <paramdef>pid_t *<parameter>pid</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_event_add_child()</function> adds a new child - process state change event source to an event loop. The event loop - object is specified in the <parameter>event</parameter> parameter, - the event source object is returned in the - <parameter>source</parameter> parameter. The - <parameter>pid</parameter> parameter specifies the PID of the - process to watch. The <parameter>handler</parameter> must - reference a function to call when the process changes state. The - handler function will be passed the - <parameter>userdata</parameter> pointer, which may be chosen - freely by the caller. The handler also receives a pointer to a - <structname>siginfo_t</structname> structure containing - information about the child process event. The - <parameter>options</parameter> parameter determines which state - changes will be watched for. It must contain an OR-ed mask of - <constant>WEXITED</constant> (watch for the child process - terminating), <constant>WSTOPPED</constant> (watch for the child - process being stopped by a signal), and - <constant>WCONTINUED</constant> (watch for the child process being - resumed by a signal). See <citerefentry - project='man-pages'><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for further information.</para> - - <para>Only a single handler may be installed for a specific - child process. The handler is enabled for a single event - (<constant>SD_EVENT_ONESHOT</constant>), but this may be changed - with - <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - If the handler function returns a negative error code, it will be - disabled after the invocation, even if the - <constant>SD_EVENT_ON</constant> mode was requested before. - </para> - - <para>To destroy an event source object use - <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - but note that the event source is only removed from the event loop - when all references to the event source are dropped. To make sure - an event source does not fire anymore, even when there's still a - reference to it kept, consider setting the event source to - <constant>SD_EVENT_OFF</constant> with - <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> - - <para>If the second parameter of - <function>sd_event_add_child()</function> is passed as NULL no - reference to the event source object is returned. In this case the - event source is considered "floating", and will be destroyed - implicitly when the event loop itself is destroyed.</para> - - <para>Note that the <parameter>handler</parameter> function is - invoked at a time where the child process is not reaped yet (and - thus still is exposed as a zombie process by the kernel). However, - the child will be reaped automatically after the function - returns. Child processes for which no child process state change - event sources are installed will not be reaped by the event loop - implementation.</para> - - <para>If both a child process state change event source and a - <constant>SIGCHLD</constant> signal event source is installed in - the same event loop, the configured event source priorities decide - which event source is dispatched first. If the signal handler is - processed first, it should leave the child processes for which - child process state change event sources are installed unreaped.</para> - - <para><function>sd_event_source_get_child_pid()</function> - retrieves the configured PID of a child process state change event - source created previously with - <function>sd_event_add_child()</function>. It takes the event - source object as the <parameter>source</parameter> parameter and a - pointer to a <type>pid_t</type> variable to return the process ID - in. - </para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, these functions return 0 or a positive - integer. On failure, they return a negative errno-style error - code.</para> - </refsect1> - - <refsect1> - <title>Errors</title> - - <para>Returned errors may indicate the following problems:</para> - - <variablelist> - <varlistentry> - <term><constant>-ENOMEM</constant></term> - - <listitem><para>Not enough memory to allocate an object.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-EINVAL</constant></term> - - <listitem><para>An invalid argument has been passed. This includes - specifying an empty mask in <parameter>options</parameter> or a mask - which contains values different than a combination of - <constant>WEXITED</constant>, <constant>WSTOPPED</constant>, and - <constant>WCONTINUED</constant>. - </para></listitem> - - </varlistentry> - - <varlistentry> - <term><constant>-EBUSY</constant></term> - - <listitem><para>A handler is already installed for this - child process.</para></listitem> - - </varlistentry> - - <varlistentry> - <term><constant>-ESTALE</constant></term> - - <listitem><para>The event loop is already terminated.</para></listitem> - - </varlistentry> - - <varlistentry> - <term><constant>-ECHILD</constant></term> - - <listitem><para>The event loop has been created in a different process.</para></listitem> - - </varlistentry> - - <varlistentry> - <term><constant>-EDOM</constant></term> - - <listitem><para>The passed event source is not a child process event source.</para></listitem> - </varlistentry> - - </variablelist> - </refsect1> - - <xi:include href="libsystemd-pkgconfig.xml" /> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_event_add_defer.xml b/man/sd_event_add_defer.xml deleted file mode 100644 index d9ebd3b179..0000000000 --- a/man/sd_event_add_defer.xml +++ /dev/null @@ -1,216 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2014 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="sd_event_add_defer" xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd_event_add_defer</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>More text</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_event_add_defer</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_event_add_defer</refname> - <refname>sd_event_add_post</refname> - <refname>sd_event_add_exit</refname> - <refname>sd_event_handler_t</refname> - - <refpurpose>Add static event sources to an event loop</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> - - <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo> - - <funcprototype> - <funcdef>typedef int (*<function>sd_event_handler_t</function>)</funcdef> - <paramdef>sd_event_source *<parameter>s</parameter></paramdef> - <paramdef>void *<parameter>userdata</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_event_add_defer</function></funcdef> - <paramdef>sd_event *<parameter>event</parameter></paramdef> - <paramdef>sd_event_source **<parameter>source</parameter></paramdef> - <paramdef>sd_event_handler_t <parameter>handler</parameter></paramdef> - <paramdef>void *<parameter>userdata</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_event_add_post</function></funcdef> - <paramdef>sd_event *<parameter>event</parameter></paramdef> - <paramdef>sd_event_source **<parameter>source</parameter></paramdef> - <paramdef>sd_event_handler_t <parameter>handler</parameter></paramdef> - <paramdef>void *<parameter>userdata</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_event_add_exit</function></funcdef> - <paramdef>sd_event *<parameter>event</parameter></paramdef> - <paramdef>sd_event_source **<parameter>source</parameter></paramdef> - <paramdef>sd_event_handler_t <parameter>handler</parameter></paramdef> - <paramdef>void *<parameter>userdata</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>These three functions add new static event sources to an - event loop. The event loop object is specified in the - <parameter>event</parameter> parameter, the event source object is - returned in the <parameter>source</parameter> parameter. The event - sources are enabled statically and will "fire" when the event loop - is run and the conditions described below are met. The handler - function will be passed the <parameter>userdata</parameter> - pointer, which may be chosen freely by the caller.</para> - - <para><function>sd_event_add_defer()</function> adds a new event - source that will be dispatched instantly, before the event loop - goes to sleep again and waits for new events. By default, the - handler will be called once - (<constant>SD_EVENT_ONESHOT</constant>). Note that if the event - source is set to <constant>SD_EVENT_ON</constant> the event loop - will never go to sleep again, but continuously call the handler, - possibly interleaved with other event sources.</para> - - <para><function>sd_event_add_post()</function> adds a new event - source that is run before the event loop will sleep and wait - for new events, but only after at least one other non-post event - source was dispatched. By default, the source is enabled - permanently (<constant>SD_EVENT_ON</constant>). Note that this - event source type will still allow the event loop to go to sleep - again, even if set to <constant>SD_EVENT_ON</constant>, as long as - no other event source is ever triggered.</para> - - <para><function>sd_event_add_exit()</function> adds a new event - source that will be dispatched when the event loop is terminated - with <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> - - <para>The - <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> - function may be used to enable the event source permanently - (<constant>SD_EVENT_ON</constant>) or to make it fire just once - (<constant>SD_EVENT_ONESHOT</constant>).</para> - - <para>If the handler function returns a negative error code, it - will be disabled after the invocation, even if the - <constant>SD_EVENT_ON</constant> mode was requested before.</para> - - <para>To destroy an event source object use - <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - but note that the event source is only removed from the event loop - when all references to the event source are dropped. To make sure - an event source does not fire anymore, even when there's still a - reference to it kept, consider setting the event source to - <constant>SD_EVENT_OFF</constant> with - <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> - - <para>If the second parameter of these functions is passed as - NULL no reference to the event source object is returned. In this - case the event source is considered "floating", and will be - destroyed implicitly when the event loop itself is - destroyed.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, this functions return 0 or a positive - integer. On failure, they return a negative errno-style error - code.</para> - </refsect1> - - <refsect1> - <title>Errors</title> - - <para>Returned errors may indicate the following problems:</para> - - <variablelist> - <varlistentry> - <term><constant>-ENOMEM</constant></term> - - <listitem><para>Not enough memory to allocate an object.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-EINVAL</constant></term> - - <listitem><para>An invalid argument has been passed.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ESTALE</constant></term> - - <listitem><para>The event loop is already terminated.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ECHILD</constant></term> - - <listitem><para>The event loop has been created in a different process.</para></listitem> - </varlistentry> - - </variablelist> - </refsect1> - - <xi:include href="libsystemd-pkgconfig.xml" /> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_event_add_io.xml b/man/sd_event_add_io.xml deleted file mode 100644 index c3749164cd..0000000000 --- a/man/sd_event_add_io.xml +++ /dev/null @@ -1,300 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2015 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_event_add_io" xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd_event_add_io</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_event_add_io</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_event_add_io</refname> - <refname>sd_event_source_get_io_events</refname> - <refname>sd_event_source_set_io_events</refname> - <refname>sd_event_source_get_io_revents</refname> - <refname>sd_event_source_get_io_fd</refname> - <refname>sd_event_source_set_io_fd</refname> - <refname>sd_event_source</refname> - <refname>sd_event_io_handler_t</refname> - - <refpurpose>Add an I/O event source to an event loop</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> - - <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo> - - <funcprototype> - <funcdef>typedef int (*<function>sd_event_io_handler_t</function>)</funcdef> - <paramdef>sd_event_source *<parameter>s</parameter></paramdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>uint32_t <parameter>revents</parameter></paramdef> - <paramdef>void *<parameter>userdata</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_event_add_io</function></funcdef> - <paramdef>sd_event *<parameter>event</parameter></paramdef> - <paramdef>sd_event_source **<parameter>source</parameter></paramdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>uint32_t <parameter>events</parameter></paramdef> - <paramdef>sd_event_io_handler_t <parameter>handler</parameter></paramdef> - <paramdef>void *<parameter>userdata</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_event_source_get_io_events</function></funcdef> - <paramdef>sd_event_source *<parameter>source</parameter></paramdef> - <paramdef>uint32_t *<parameter>events</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_event_source_set_io_events</function></funcdef> - <paramdef>sd_event_source *<parameter>source</parameter></paramdef> - <paramdef>uint32_t <parameter>events</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_event_source_get_io_revents</function></funcdef> - <paramdef>sd_event_source *<parameter>source</parameter></paramdef> - <paramdef>uint32_t *<parameter>revents</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_event_source_get_io_fd</function></funcdef> - <paramdef>sd_event_source *<parameter>source</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_event_source_set_io_fd</function></funcdef> - <paramdef>sd_event_source *<parameter>source</parameter></paramdef> - <paramdef>int <parameter>fd</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_event_add_io()</function> adds a new I/O event - source to an event loop. The event loop object is specified in the - <parameter>event</parameter> parameter, the event source object is - returned in the <parameter>source</parameter> parameter. The - <parameter>fd</parameter> parameter takes the UNIX file descriptor - to watch, which may refer to a socket, a FIFO, a message queue, a - serial connection, a character device, or any other file descriptor - compatible with Linux - <citerefentry project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The - <parameter>events</parameter> parameter takes a bit mask of events - to watch for, a combination of the following event flags: - <constant>EPOLLIN</constant>, <constant>EPOLLOUT</constant>, - <constant>EPOLLRDHUP</constant>, <constant>EPOLLPRI</constant>, - and <constant>EPOLLET</constant>, see - <citerefentry project='man-pages'><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for details. The <parameter>handler</parameter> shall reference a - function to call when the event source is triggered. The - <parameter>userdata</parameter> pointer will be passed to the - handler function, and may be chosen freely by the caller. The - handler will also be passed the file descriptor the event was seen - on, as well as the actual event flags. It's generally a subset of - the events watched, however may additionally include - <constant>EPOLLERR</constant> and <constant>EPOLLHUP</constant>. - </para> - - <para>By default, an event source will stay enabled - continuously (<constant>SD_EVENT_ON</constant>), but this may be - changed with - <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - If the handler function returns a negative error code, it will be - disabled after the invocation, even if the - <constant>SD_EVENT_ON</constant> mode was requested before. Note - that an event source set to <constant>SD_EVENT_ON</constant> will - fire continuously unless data is read from or written to the file - descriptor to reset the mask of events seen. - </para> - - <para>Setting the I/O event mask to watch for to 0 does not mean - that the event source won't be triggered anymore, as - <constant>EPOLLHUP</constant> and <constant>EPOLLERR</constant> - may be triggered even with a zero event mask. To temporarily - disable an I/O event source use - <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> - with <constant>SD_EVENT_OFF</constant> instead.</para> - - <para>To destroy an event source object use - <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - but note that the event source is only removed from the event loop - when all references to the event source are dropped. To make sure - an event source does not fire anymore, even if it is still referenced, - disable the event source using - <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> - with <constant>SD_EVENT_OFF</constant>.</para> - - <para>If the second parameter of - <function>sd_event_add_io()</function> is - <constant>NULL</constant> no reference to the event source object - is returned. In this case the event source is considered - "floating", and will be destroyed implicitly when the event loop - itself is destroyed.</para> - - <para>It is recommended to use - <function>sd_event_add_io()</function> only in conjunction with - file descriptors that have <constant>O_NONBLOCK</constant> set, to - ensure that all I/O operations from invoked handlers are properly - asynchronous and non-blocking. Using file descriptors without - <constant>O_NONBLOCK</constant> might result in unexpected - starvation of other event sources. See - <citerefentry project='man-pages'><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for details on enabling <constant>O_NONBLOCK</constant> mode.</para> - - <para><function>sd_event_source_get_io_events()</function> retrieves - the configured mask of watched I/O events of an event source created - previously with <function>sd_event_add_io()</function>. It takes - the event source object and a pointer to a variable to store the - mask in.</para> - - <para><function>sd_event_source_set_io_events()</function> - configures the mask of watched I/O events of an event source created - previously with <function>sd_event_add_io()</function>. It takes the - event source object and the new event mask.</para> - - <para><function>sd_event_source_get_io_revents()</function> - retrieves the I/O event mask of currently seen but undispatched - events from an event source created previously with - <function>sd_event_add_io()</function>. It takes the event source - object and a pointer to a variable to store the event mask - in. When called from a handler function on the handler's event - source object this will return the same mask as passed to the - handler's <parameter>revents</parameter> parameter. This call is - primarily useful to check for undispatched events of an event - source from the handler of an unrelated (possibly higher priority) - event source. Note the relation between - <function>sd_event_source_get_pending()</function> and - <function>sd_event_source_get_io_revents()</function>: both - functions will report non-zero results when there's an event - pending for the event source, but the former applies to all event - source types, the latter only to I/O event sources.</para> - - <para><function>sd_event_source_get_io_fd()</function> retrieves - the UNIX file descriptor of an event source created previously - with <function>sd_event_add_io()</function>. It takes the event - source object and returns the non-negative file descriptor - or a negative error number on error (see below).</para> - - <para><function>sd_event_source_set_io_fd()</function> - changes the UNIX file descriptor of an I/O event source created - previously with <function>sd_event_add_io()</function>. It takes - the event source object and the new file descriptor.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, these functions return 0 or a positive - integer. On failure, they return a negative errno-style error - code.</para> - </refsect1> - - <refsect1> - <title>Errors</title> - - <para>Returned values may indicate the following problems:</para> - - <variablelist> - <varlistentry> - <term><constant>-ENOMEM</constant></term> - - <listitem><para>Not enough memory to allocate an object.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-EINVAL</constant></term> - - <listitem><para>An invalid argument has been passed.</para></listitem> - - </varlistentry> - - <varlistentry> - <term><constant>-ESTALE</constant></term> - - <listitem><para>The event loop is already terminated.</para></listitem> - - </varlistentry> - - <varlistentry> - <term><constant>-ECHILD</constant></term> - - <listitem><para>The event loop has been created in a different process.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-EDOM</constant></term> - - <listitem><para>The passed event source is not an I/O event source.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <xi:include href="libsystemd-pkgconfig.xml" /> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_get_pending</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>epoll_ctl</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_event_add_signal.xml b/man/sd_event_add_signal.xml deleted file mode 100644 index e98f1d2682..0000000000 --- a/man/sd_event_add_signal.xml +++ /dev/null @@ -1,221 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2014 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="sd_event_add_signal" xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd_event_add_signal</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>More text</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_event_add_signal</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_event_add_signal</refname> - <refname>sd_event_source_get_signal</refname> - <refname>sd_event_signal_handler_t</refname> - - <refpurpose>Add a UNIX process signal event source to an event - loop</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> - - <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo> - - <funcprototype> - <funcdef>typedef int (*<function>sd_event_signal_handler_t</function>)</funcdef> - <paramdef>sd_event_source *<parameter>s</parameter></paramdef> - <paramdef>const struct signalfd_siginfo *<parameter>si</parameter></paramdef> - <paramdef>void *<parameter>userdata</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_event_add_signal</function></funcdef> - <paramdef>sd_event *<parameter>event</parameter></paramdef> - <paramdef>sd_event_source **<parameter>source</parameter></paramdef> - <paramdef>int <parameter>signal</parameter></paramdef> - <paramdef>sd_event_signal_handler_t <parameter>handler</parameter></paramdef> - <paramdef>void *<parameter>userdata</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_event_source_get_signal</function></funcdef> - <paramdef>sd_event_source *<parameter>source</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_event_add_signal()</function> adds a new UNIX - process signal event source to an event loop. The event loop - object is specified in the <parameter>event</parameter> parameter, - and the event source object is returned in the - <parameter>source</parameter> parameter. The - <parameter>signal</parameter> parameter specifies the numeric - signal to be handled (see <citerefentry - project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>). - The <parameter>handler</parameter> parameter must reference a - function to call when the signal is received or be - <constant>NULL</constant>. The handler function will be passed - the <parameter>userdata</parameter> pointer, which may be chosen - freely by the caller. The handler also receives a pointer to a - <structname>signalfd_siginfo</structname> structure containing - information about the received signal. See <citerefentry - project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for further information.</para> - - <para>Only a single handler may be installed for a specific - signal. The signal will be unblocked by this call, and must be - blocked before this function is called in all threads (using - <citerefentry - project='man-pages'><refentrytitle>sigprocmask</refentrytitle><manvolnum>2</manvolnum></citerefentry>). If - the handler is not specified (<parameter>handler</parameter> is - <constant>NULL</constant>), a default handler which causes the - program to exit cleanly will be used.</para> - - <para>By default, the event source is enabled permanently - (<constant>SD_EVENT_ON</constant>), but this may be changed with - <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - If the handler function returns a negative error code, it will be - disabled after the invocation, even if the - <constant>SD_EVENT_ON</constant> mode was requested before. - </para> - - <para>To destroy an event source object use - <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - but note that the event source is only removed from the event loop - when all references to the event source are dropped. To make sure - an event source does not fire anymore, even if it is still referenced, - disable the event source using - <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> - with <constant>SD_EVENT_OFF</constant>.</para> - - <para>If the second parameter of - <function>sd_event_add_signal()</function> is - <constant>NULL</constant> no reference to the event source object - is returned. In this case the event source is considered - "floating", and will be destroyed implicitly when the event loop - itself is destroyed.</para> - - <para><function>sd_event_source_get_signal()</function> returns - the configured signal number of an event source created previously - with <function>sd_event_add_signal()</function>. It takes the - event source object as the <parameter>source</parameter> - parameter.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, these functions return 0 or a positive - integer. On failure, they return a negative errno-style error - code.</para> - </refsect1> - - <refsect1> - <title>Errors</title> - - <para>Returned errors may indicate the following problems:</para> - - <variablelist> - <varlistentry> - <term><constant>-ENOMEM</constant></term> - - <listitem><para>Not enough memory to allocate an object.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-EINVAL</constant></term> - - <listitem><para>An invalid argument has been passed.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-EBUSY</constant></term> - - <listitem><para>A handler is already installed for this - signal or the signal was not blocked previously.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ESTALE</constant></term> - - <listitem><para>The event loop is already terminated.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ECHILD</constant></term> - - <listitem><para>The event loop has been created in a different process.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-EDOM</constant></term> - - <listitem><para>The passed event source is not a signal event source.</para></listitem> - </varlistentry> - - </variablelist> - </refsect1> - - <xi:include href="libsystemd-pkgconfig.xml" /> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_event_add_time.xml b/man/sd_event_add_time.xml deleted file mode 100644 index a2c0d54b56..0000000000 --- a/man/sd_event_add_time.xml +++ /dev/null @@ -1,313 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2014 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_event_add_time" xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd_event_add_time</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_event_add_time</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_event_add_time</refname> - <refname>sd_event_source_get_time</refname> - <refname>sd_event_source_set_time</refname> - <refname>sd_event_source_get_time_accuracy</refname> - <refname>sd_event_source_set_time_accuracy</refname> - <refname>sd_event_source_get_time_clock</refname> - <refname>sd_event_time_handler_t</refname> - - <refpurpose>Add a timer event source to an event loop</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> - - <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo> - - <funcprototype> - <funcdef>typedef int (*<function>sd_event_time_handler_t</function>)</funcdef> - <paramdef>sd_event_source *<parameter>s</parameter></paramdef> - <paramdef>uint64_t <parameter>usec</parameter></paramdef> - <paramdef>void *<parameter>userdata</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_event_add_time</function></funcdef> - <paramdef>sd_event *<parameter>event</parameter></paramdef> - <paramdef>sd_event_source **<parameter>source</parameter></paramdef> - <paramdef>clockid_t <parameter>clock</parameter></paramdef> - <paramdef>uint64_t <parameter>usec</parameter></paramdef> - <paramdef>uint64_t <parameter>accuracy</parameter></paramdef> - <paramdef>sd_event_time_handler_t <parameter>handler</parameter></paramdef> - <paramdef>void *<parameter>userdata</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_event_source_get_time</function></funcdef> - <paramdef>sd_event_source *<parameter>source</parameter></paramdef> - <paramdef>uint64_t *<parameter>usec</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_event_source_set_time</function></funcdef> - <paramdef>sd_event_source *<parameter>source</parameter></paramdef> - <paramdef>uint64_t <parameter>usec</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_event_source_get_time_accuracy</function></funcdef> - <paramdef>sd_event_source *<parameter>source</parameter></paramdef> - <paramdef>uint64_t *<parameter>usec</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_event_source_set_time_accuracy</function></funcdef> - <paramdef>sd_event_source *<parameter>source</parameter></paramdef> - <paramdef>uint64_t <parameter>usec</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_event_source_get_time_clock</function></funcdef> - <paramdef>sd_event_source *<parameter>source</parameter></paramdef> - <paramdef>clockid_t *<parameter>clock</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_event_add_time()</function> adds a new timer event source to an event loop. The event loop - object is specified in the <parameter>event</parameter> parameter, the event source object is returned in the - <parameter>source</parameter> parameter. The <parameter>clock</parameter> parameter takes a clock identifier, one - of <constant>CLOCK_REALTIME</constant>, <constant>CLOCK_MONOTONIC</constant>, <constant>CLOCK_BOOTTIME</constant>, - <constant>CLOCK_REALTIME_ALARM</constant>, or <constant>CLOCK_BOOTTIME_ALARM</constant>. See - <citerefentry><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry> for details - regarding the various types of clocks. The <parameter>usec</parameter> parameter specifies the earliest time, in - microseconds (µs), relative to the clock's epoch, when the timer shall be triggered. If a time already in the past - is specified (including <constant>0</constant>), this timer source "fires" immediately and is ready to be - dispatched. If the paramater is specified as <constant>UINT64_MAX</constant> the timer event will never elapse, - which may be used as an alternative to explicitly disabling a timer event source with - <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>. The - <parameter>accuracy</parameter> parameter specifies an additional accuracy value in µs specifying how much the - timer event may be delayed. Use <constant>0</constant> to select the default accuracy (250ms). Use 1µs for maximum - accuracy. Consider specifying 60000000µs (1min) or larger for long-running events that may be delayed - substantially. Picking higher accuracy values allows the system to coalesce timer events more aggressively, - improving power efficiency. The <parameter>handler</parameter> parameter shall reference a function to call when - the timer elapses. The handler function will be passed the <parameter>userdata</parameter> pointer, which may be - chosen freely by the caller. The handler is also passed the configured trigger time, even if it is actually called - slightly later, subject to the specified accuracy value, the kernel timer slack (see - <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>), and additional - scheduling latencies. To query the actual time the handler was called use - <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> - - <para>By default, the timer will elapse once - (<constant>SD_EVENT_ONESHOT</constant>), but this may be changed - with - <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - If the handler function returns a negative error code, it will be - disabled after the invocation, even if the - <constant>SD_EVENT_ON</constant> mode was requested before. Note - that a timer event set to <constant>SD_EVENT_ON</constant> will - fire continuously unless its configured time is updated using - <function>sd_event_source_set_time()</function>. - </para> - - <para>To destroy an event source object use - <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - but note that the event source is only removed from the event loop - when all references to the event source are dropped. To make sure - an event source does not fire anymore, even if it is still referenced, - disable the event source using - <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> - with <constant>SD_EVENT_OFF</constant>.</para> - - <para>If the second parameter of - <function>sd_event_add_time()</function> is - <constant>NULL</constant> no reference to the event source object - is returned. In this case the event source is considered - "floating", and will be destroyed implicitly when the event loop - itself is destroyed.</para> - - <para>If the <parameter>handler</parameter> to - <function>sd_event_add_time()</function> is - <constant>NULL</constant>, and the event source fires, this will - be considered a request to exit the event loop. In this case, the - <parameter>userdata</parameter> parameter, cast to an integer, is - used for the exit code passed to - <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> - - <para>Use <constant>CLOCK_BOOTTIME_ALARM</constant> and - <constant>CLOCK_REALTIME_ALARM</constant> to define event sources - that may wake up the system from suspend.</para> - - <para>In order to set up relative timers (that is, relative to the - current time), retrieve the current time via - <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - add the desired timespan to it, and use the result as - the <parameter>usec</parameter> parameter to - <function>sd_event_add_time()</function>.</para> - - <para>In order to set up repetitive timers (that is, timers that - are triggered in regular intervals), set up the timer normally, - for the first invocation. Each time the event handler is invoked, - update the timer's trigger time with - <citerefentry><refentrytitle>sd_event_source_set_time</refentrytitle><manvolnum>3</manvolnum></citerefentry> for the next timer - iteration, and reenable the timer using - <function>sd_event_source_set_enabled()</function>. To calculate - the next point in time to pass to - <function>sd_event_source_set_time()</function>, either use as - base the <parameter>usec</parameter> parameter passed to the timer - callback, or the timestamp returned by - <function>sd_event_now()</function>. In the former case timer - events will be regular, while in the latter case the scheduling - latency will keep accumulating on the timer.</para> - - <para><function>sd_event_source_get_time()</function> retrieves - the configured time value of an event source created - previously with <function>sd_event_add_time()</function>. It takes - the event source object and a pointer to a variable to store the - time in, relative to the selected clock's epoch, in µs.</para> - - <para><function>sd_event_source_set_time()</function> changes the - time of an event source created previously with - <function>sd_event_add_time()</function>. It takes the event - source object and a time relative to the selected clock's epoch, - in µs.</para> - - <para><function>sd_event_source_get_time_accuracy()</function> - retrieves the configured accuracy value of a event source - created previously with <function>sd_event_add_time()</function>. It - takes the event source object and a pointer to a variable to store - the accuracy in. The accuracy is specified in µs.</para> - - <para><function>sd_event_source_set_time_accuracy()</function> - changes the configured accuracy of a timer event source created - previously with <function>sd_event_add_time()</function>. It takes - the event source object and accuracy, in µs.</para> - - <para><function>sd_event_source_get_time_clock()</function> - retrieves the configured clock of a event source created - previously with <function>sd_event_add_time()</function>. It takes - the event source object and a pointer to a variable to store the - clock identifier in.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, these functions return 0 or a positive - integer. On failure, they return a negative errno-style error - code. </para> - </refsect1> - - <refsect1> - <title>Errors</title> - - <para>Returned values may indicate the following problems:</para> - - <variablelist> - <varlistentry> - <term><constant>-ENOMEM</constant></term> - - <listitem><para>Not enough memory to allocate an object.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-EINVAL</constant></term> - - <listitem><para>An invalid argument has been passed.</para></listitem> - - </varlistentry> - - <varlistentry> - <term><constant>-ESTALE</constant></term> - - <listitem><para>The event loop is already terminated.</para></listitem> - - </varlistentry> - - <varlistentry> - <term><constant>-ECHILD</constant></term> - - <listitem><para>The event loop has been created in a different process.</para></listitem> - - </varlistentry> - - <varlistentry> - <term><constant>-EOPNOTSUPP</constant></term> - - <listitem><para>The selected clock is not supported by the event loop implementation.</para></listitem> - - </varlistentry> - - <varlistentry> - <term><constant>-EDOM</constant></term> - - <listitem><para>The passed event source is not a timer event source.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <xi:include href="libsystemd-pkgconfig.xml" /> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_event_exit.xml b/man/sd_event_exit.xml deleted file mode 100644 index 9846a3eaf4..0000000000 --- a/man/sd_event_exit.xml +++ /dev/null @@ -1,163 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2015 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_event_exit" xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd_event_exit</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_event_exit</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_event_exit</refname> - <refname>sd_event_get_exit_code</refname> - - <refpurpose>Ask the event loop to exit</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_event_exit</function></funcdef> - <paramdef>sd_event *<parameter>event</parameter></paramdef> - <paramdef>int <parameter>code</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_event_get_exit_code</function></funcdef> - <paramdef>sd_event *<parameter>event</parameter></paramdef> - <paramdef>int *<parameter>code</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_event_exit()</function> requests the event loop - specified in the <parameter>event</parameter> event loop object to - exit. The <parameter>code</parameter> parameter may be any integer - value and is returned as-is by - <citerefentry><refentrytitle>sd_event_loop</refentrytitle><manvolnum>3</manvolnum></citerefentry> - after the last event loop iteration. It may also be queried - using <function>sd_event_get_exit_code()</function>, see - below. </para> - - <para>When exiting is requested the event loop will stop listening - for and dispatching regular event sources. Instead it will proceed - with executing only event sources registered with - <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry> - in the order defined by their priority. After all exit event - sources have been dispatched the event loop is terminated.</para> - - <para>If <function>sd_event_exit()</function> is invoked a second - time while the event loop is still processing exit event sources, - the exit code stored in the event loop object is updated, but - otherwise no further operation is executed.</para> - - <para><function>sd_event_get_exit_code()</function> may be used to - query the exit code passed into - <function>sd_event_exit()</function> earlier.</para> - - <para>While the full positive and negative integer ranges may be used - for the exit code, care should be taken not pick exit codes that - conflict with regular exit codes returned by - <function>sd_event_loop()</function>, if these exit codes shall be - distinguishable.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, <function>sd_event_exit()</function> and - <function>sd_event_get_exit_code()</function> return 0 or a positive - integer. On failure, they return a negative errno-style error - code.</para> - </refsect1> - - <refsect1> - <title>Errors</title> - - <para>Returned errors may indicate the following problems:</para> - - <variablelist> - - <varlistentry> - <term><constant>-EINVAL</constant></term> - - <listitem><para>The event loop object or error code pointer are invalid.</para></listitem> - - </varlistentry> - - <varlistentry> - <term><constant>-ECHILD</constant></term> - - <listitem><para>The event loop was created in a different process.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ESTALE</constant></term> - - <listitem><para>The event loop has exited already and all exit handlers are already processed.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ENODATA</constant></term> - - <listitem><para>The event loop has not been requested to exit yet.</para></listitem> - </varlistentry> - - </variablelist> - </refsect1> - - <xi:include href="libsystemd-pkgconfig.xml" /> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_event_get_fd.xml b/man/sd_event_get_fd.xml deleted file mode 100644 index f68752dd0e..0000000000 --- a/man/sd_event_get_fd.xml +++ /dev/null @@ -1,140 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2014 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="sd_event_get_fd" xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd_event_get_fd</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>More text</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_event_get_fd</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_event_get_fd</refname> - - <refpurpose>Obtain a file descriptor to poll for event loop events</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_event_get_fd</function></funcdef> - <paramdef>sd_event *<parameter>event</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_event_get_fd()</function> returns the file - descriptor that an event loop object returned by the - <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry> - function uses to wait for events. This file descriptor may itself - be polled for - <constant>POLLIN</constant>/<constant>EPOLLIN</constant> - events. This makes it possible to embed an - <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry> - event loop into another, possibly foreign, event loop.</para> - - <para>The returned file descriptor refers to an <citerefentry - project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry> - object. It is recommended not to alter it by invoking - <citerefentry - project='man-pages'><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> - on it, in order to avoid interference with the event loop's inner - logic and assumptions.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, <function>sd_event_get_fd()</function> returns a - non-negative file descriptor. On failure, it returns a negative - errno-style error code.</para> - </refsect1> - - <refsect1> - <title>Errors</title> - - <para>Returned errors may indicate the following problems:</para> - - <variablelist> - <varlistentry> - <term><constant>-EINVAL</constant></term> - - <listitem><para><parameter>event</parameter> is not a valid - pointer to an <structname>sd_event</structname> structure. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ECHILD</constant></term> - - <listitem><para>The event loop has been created in a different process.</para></listitem> - - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Examples</title> - - <example> - <title>Integration in the GLib event loop</title> - - <programlisting><xi:include href="glib-event-glue.c" parse="text" /></programlisting> - </example> - </refsect1> - - <xi:include href="libsystemd-pkgconfig.xml" /> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>epoll_ctl</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_event_new.xml b/man/sd_event_new.xml deleted file mode 100644 index 2c23b00a8c..0000000000 --- a/man/sd_event_new.xml +++ /dev/null @@ -1,245 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2014 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_event_new" xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd_event_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_event_new</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_event_new</refname> - <refname>sd_event_default</refname> - <refname>sd_event_ref</refname> - <refname>sd_event_unref</refname> - <refname>sd_event_unrefp</refname> - <refname>sd_event_get_tid</refname> - <refname>sd_event</refname> - - <refpurpose>Acquire and release an event loop object</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> - - <funcsynopsisinfo><token>typedef</token> struct sd_event sd_event;</funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_event_new</function></funcdef> - <paramdef>sd_event **<parameter>event</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_event_default</function></funcdef> - <paramdef>sd_event **<parameter>event</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>sd_event *<function>sd_event_ref</function></funcdef> - <paramdef>sd_event *<parameter>event</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>sd_event *<function>sd_event_unref</function></funcdef> - <paramdef>sd_event *<parameter>event</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>void <function>sd_event_unrefp</function></funcdef> - <paramdef>sd_event **<parameter>event</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_event_get_tid</function></funcdef> - <paramdef>sd_event *<parameter>event</parameter></paramdef> - <paramdef>pid_t *<parameter>tid</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_event_new()</function> allocates a new event - loop object. The event loop object is returned in the - <parameter>event</parameter> parameter. After use, drop - the returned reference with - <function>sd_event_unref()</function>. When the last reference is - dropped, the object is freed.</para> - - <para><function>sd_event_default()</function> acquires a reference - to the default event loop object of the calling thread, possibly - allocating a new object if no default event loop object has been - allocated yet for the thread. After use, drop the returned - reference with <function>sd_event_unref()</function>. When the - last reference is dropped, the event loop is freed. If this - function is called while the object returned from a previous call - from the same thread is still referenced, the same object is - returned again, but the reference is increased by one. It is - recommended to use this call instead of - <function>sd_event_new()</function> in order to share event loop - objects between various components that are dispatched in the same - thread. All threads have exactly either zero or one default event loop - objects associated, but never more.</para> - - <para>After allocating an event loop object, add event sources to - it with - <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry> - or - <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - and then execute the event loop using - <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> - - <para><function>sd_event_ref()</function> increases the reference - count of the specified event loop object by one.</para> - - <para><function>sd_event_unref()</function> decreases the - reference count of the specified event loop object by one. If - the count hits zero, the object is freed. Note that it - is freed regardless of whether it is the default event loop object for a - thread or not. This means that allocating an event loop with - <function>sd_event_default()</function>, then releasing it, and - then acquiring a new one with - <function>sd_event_default()</function> will result in two - distinct objects. Note that, in order to free an event loop object, - all remaining event sources of the event loop also need to be - freed as each keeps a reference to it.</para> - - <para><function>sd_event_unrefp()</function> is similar to - <function>sd_event_unref()</function> but takes a pointer to a - pointer to an <type>sd_event</type> object. This call is useful in - conjunction with GCC's and LLVM's <ulink - url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up - Variable Attribute</ulink>. Note that this function is defined as - inline function. Use a declaration like the following, - in order to allocate an event loop object that is freed - automatically as the code block is left:</para> - - <programlisting>{ - __attribute__((cleanup(sd_event_unrefp)) sd_event *event = NULL; - int r; - … - r = sd_event_default(&event); - if (r < 0) - fprintf(stderr, "Failed to allocate event loop: %s\n", strerror(-r)); - … -}</programlisting> - - <para><function>sd_event_ref()</function>, - <function>sd_event_unref()</function> and - <function>sd_event_unrefp()</function> execute no operation if the - passed in event loop object is <constant>NULL</constant>.</para> - - <para><function>sd_event_get_tid()</function> retrieves the thread - identifier ("TID") of the thread the specified event loop object - is associated with. This call is only supported for event loops - allocated with <function>sd_event_default()</function>, and - returns the identifier for the thread the event loop is the - default event loop of. See <citerefentry - project='man-pages'><refentrytitle>gettid</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for more information on thread identifiers.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, <function>sd_event_new()</function> and - <function>sd_event_default()</function> return 0 or a positive - integer. On failure, they return a negative errno-style error - code. <function>sd_event_ref()</function> always returns a pointer - to the event loop object passed - in. <function>sd_event_unref()</function> always returns - <constant>NULL</constant>.</para> - </refsect1> - - <refsect1> - <title>Errors</title> - - <para>Returned errors may indicate the following problems:</para> - - <variablelist> - <varlistentry> - <term><constant>-ENOMEM</constant></term> - - <listitem><para>Not enough memory to allocate the object.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-EMFILE</constant></term> - - <listitem><para>The maximum number of event loops has been allocated.</para></listitem> - - </varlistentry> - - <varlistentry> - <term><constant>-ENXIO</constant></term> - - <listitem><para><function>sd_event_get_tid()</function> was - invoked on an event loop object that was not allocated with - <function>sd_event_default()</function>.</para></listitem> - </varlistentry> - - </variablelist> - </refsect1> - - <xi:include href="libsystemd-pkgconfig.xml" /> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>gettid</refentrytitle><manvolnum>2</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_event_now.xml b/man/sd_event_now.xml deleted file mode 100644 index 2c83b0bcb5..0000000000 --- a/man/sd_event_now.xml +++ /dev/null @@ -1,146 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2015 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_event_now" xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd_event_now</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_event_now</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_event_now</refname> - - <refpurpose>Retrieve current event loop iteration timestamp</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_event_now</function></funcdef> - <paramdef>sd_event *<parameter>event</parameter></paramdef> - <paramdef>clockid_t <parameter>clock</parameter></paramdef> - <paramdef>uint64_t *<parameter>usec</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_event_now()</function> returns the time when - the most recent event loop iteration began. A timestamp - is taken right after returning from the event sleep, and before - dispatching any event sources. The <parameter>event</parameter> - parameter specifies the event loop object to retrieve the timestamp - from. The <parameter>clock</parameter> parameter specifies the clock to - retrieve the timestamp for, and is one of - <constant>CLOCK_REALTIME</constant> (or equivalently - <constant>CLOCK_REALTIME_ALARM</constant>), - <constant>CLOCK_MONOTONIC</constant>, or - <constant>CLOCK_BOOTTIME</constant> (or equivalently - <constant>CLOCK_BOOTTIME_ALARM</constant>), see - <citerefentry project='man-pages'><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for more information on the various clocks. The retrieved - timestamp is stored in the <parameter>usec</parameter> parameter, - in µs since the clock's epoch. If this function is invoked before - the first event loop iteration, the current time is returned, as - reported by <function>clock_gettime()</function>. To distinguish - this case from a regular invocation the return value will be - positive, and zero when the returned timestamp refers to an actual - event loop iteration.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>If the first event loop iteration has not run yet - <function>sd_event_now()</function> writes current time to - <parameter>usec</parameter> and returns a positive return value. - Otherwise, it will write the requested timestamp to <parameter>usec</parameter> - and return 0. On failure, the call returns a negative errno-style - error code.</para> - </refsect1> - - <refsect1> - <title>Errors</title> - - <para>Returned values may indicate the following problems:</para> - - <variablelist> - <varlistentry> - <term><constant>-EINVAL</constant></term> - - <listitem><para>An invalid parameter was - passed.</para></listitem> - - </varlistentry> - - <varlistentry> - <term><constant>-EOPNOTSUPP</constant></term> - - <listitem><para>Unsupported clock type. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ECHILD</constant></term> - - <listitem><para>The event loop object was created in a - different process.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <xi:include href="libsystemd-pkgconfig.xml" /> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_event_run.xml b/man/sd_event_run.xml deleted file mode 100644 index 5b68959165..0000000000 --- a/man/sd_event_run.xml +++ /dev/null @@ -1,190 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2015 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="sd_event_run" xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd_event_run</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Tom</firstname> - <surname>Gundersen</surname> - <email>teg@jklm.no</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_event_run</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_event_run</refname> - <refname>sd_event_loop</refname> - - <refpurpose>Run an event loop</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_event_run</function></funcdef> - <paramdef>sd_event *<parameter>event</parameter></paramdef> - <paramdef>uint64_t <parameter>usec</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_event_loop</function></funcdef> - <paramdef>sd_event *<parameter>event</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_event_run()</function> may be used to run a single - iteration of the event loop specified in the - <parameter>event</parameter> parameter. The function waits until an event to - process is available, and dispatches the registered handler for - it. The <parameter>usec</parameter> parameter specifies the - maximum time (in microseconds) to wait for an event. Use - <constant>(uint64_t) -1</constant> to specify an infinite - timeout.</para> - - <para><function>sd_event_loop()</function> invokes - <function>sd_event_run()</function> in a loop, thus implementing - the actual event loop. The call returns as soon as exiting was - requested using - <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> - - <para>The event loop object <parameter>event</parameter> is - created with - <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - Events sources to wait for and their handlers may be registered - with - <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - </para> - - <para>For low-level control of event loop execution, use - <citerefentry><refentrytitle>sd_event_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>sd_event_dispatch</refentrytitle><manvolnum>3</manvolnum></citerefentry> - which are wrapped by <function>sd_event_run()</function>. Along - with - <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - these functions allow integration of an - <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry> - event loop into foreign event loop implementations.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On failure, these functions return a negative errno-style - error code. <function>sd_event_run()</function> returns a - positive, non-zero integer if an event source was dispatched, and - zero when the specified timeout hit before an event source has - seen any event, and hence no event source was - dispatched. <function>sd_event_loop()</function> returns the exit - code specified when invoking - <function>sd_event_exit()</function>.</para> - </refsect1> - - <refsect1> - <title>Errors</title> - - <para>Returned errors may indicate the following problems:</para> - - <variablelist> - <varlistentry> - <term><constant>-EINVAL</constant></term> - - <listitem><para>The <parameter>event</parameter> parameter is - invalid or <constant>NULL</constant>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-EBUSY</constant></term> - - <listitem><para>The event loop object is not in the right - state (see - <citerefentry><refentrytitle>sd_event_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for an explanation of possible states).</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ESTALE</constant></term> - - <listitem><para>The event loop is already terminated.</para></listitem> - - </varlistentry> - - <varlistentry> - <term><constant>-ECHILD</constant></term> - - <listitem><para>The event loop has been created in a different process.</para></listitem> - - </varlistentry> - - </variablelist> - - <para>Other errors are possible, too.</para> - </refsect1> - - <xi:include href="libsystemd-pkgconfig.xml" /> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <ulink url="https://developer.gnome.org/glib/unstable/glib-The-Main-Event-Loop.html">GLib Main Event Loop</ulink>. - </para> - </refsect1> - -</refentry> diff --git a/man/sd_event_set_watchdog.xml b/man/sd_event_set_watchdog.xml deleted file mode 100644 index cbc5bc0836..0000000000 --- a/man/sd_event_set_watchdog.xml +++ /dev/null @@ -1,177 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2015 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_event_set_watchdog" xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd_event_set_watchdog</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_event_set_watchdog</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_event_set_watchdog</refname> - <refname>sd_event_get_watchdog</refname> - - <refpurpose>Enable event loop watchdog support</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_event_set_watchdog</function></funcdef> - <paramdef>sd_event *<parameter>event</parameter></paramdef> - <paramdef>int b</paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_event_get_watchdog</function></funcdef> - <paramdef>sd_event *<parameter>event</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_event_set_watchdog()</function> may be used to - enable or disable automatic watchdog notification support in the - event loop object specified in the <parameter>event</parameter> - parameter. Specifically, depending on the <parameter>b</parameter> - boolean argument this will make sure the event loop wakes up in - regular intervals and sends watchdog notification messages to the - service manager, if this was requested by the service - manager. Watchdog support is determined with - <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - and watchdog messages are sent with - <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>. See - the <varname>WatchdogSec=</varname> setting in - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details on how to enable watchdog support for a service and - the protocol used. The wake-up interval is chosen as half the - watchdog timeout declared by the service manager via the - <varname>$WATCHDOG_USEC</varname> environment variable. If the - service manager did not request watchdog notifications, or if the - process was not invoked by the service manager this call with a - true <parameter>b</parameter> parameter executes no - operation. Passing a false <parameter>b</parameter> parameter will - disable the automatic sending of watchdog notification messages if - it was enabled before. Newly allocated event loop objects have - this feature disabled.</para> - - <para>The first watchdog notification message is sent immediately - when <function>set_event_set_watchdog()</function> is invoked with - a true <parameter>b</parameter> parameter.</para> - - <para>The watchdog logic is designed to allow the service manager - to automatically detect services that ceased processing of - incoming events, and thus appear "hung". Watchdog notifications - are sent out only at the beginning of each event loop - iteration. If an event source dispatch function blocks for an - excessively long time and does not return execution to the event - loop quickly, this might hence cause the notification message to - be delayed, and possibly result in abnormal program termination, - as configured in the service unit file.</para> - - <para><function>sd_event_get_watchdog()</function> may be used to - determine whether watchdog support was previously requested by a - call to <function>sd_event_set_watchdog()</function> with a true - <parameter>b</parameter> parameter and successfully - enabled.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, <function>sd_event_set_watchdog()</function> and - <function>sd_event_get_watchdog()</function> return a non-zero - positive integer if the service manager requested watchdog support - and watchdog support was successfully enabled. They return zero if - the service manager did not request watchdog support, or if - watchdog support was explicitly disabled with a false - <parameter>b</parameter> parameter. On failure, they return a - negative errno-style error - code.</para> - </refsect1> - - <refsect1> - <title>Errors</title> - - <para>Returned errors may indicate the following problems:</para> - - <variablelist> - - <varlistentry> - <term><constant>-ECHILD</constant></term> - - <listitem><para>The event loop has been created in a different process.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-EINVAL</constant></term> - - <listitem><para>The passed event loop object was invalid.</para></listitem> - </varlistentry> - - </variablelist> - </refsect1> - - <xi:include href="libsystemd-pkgconfig.xml" /> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_event_source_get_event.xml b/man/sd_event_source_get_event.xml deleted file mode 100644 index 2fdbd411bd..0000000000 --- a/man/sd_event_source_get_event.xml +++ /dev/null @@ -1,100 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2015 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_event_source_get_event" xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd_event_source_get_event</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_event_source_get_event</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_event_source_get_event</refname> - - <refpurpose>Retrieve the event loop of an event source</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>sd_event* <function>sd_event_source_get_event</function></funcdef> - <paramdef>sd_event_source *<parameter>source</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_event_source_get_event()</function> may be used - to retrieve the event loop object the event source object specified - as <parameter>source</parameter> is associated with. The event - loop object is specified when creating an event source object with - calls such as - <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry> - or - <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, <function>sd_event_source_get_event()</function> - returns the associated event loop object. On failure, it returns - NULL.</para> - </refsect1> - - <xi:include href="libsystemd-pkgconfig.xml" /> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_event_source_get_pending.xml b/man/sd_event_source_get_pending.xml deleted file mode 100644 index 7f88bd1b87..0000000000 --- a/man/sd_event_source_get_pending.xml +++ /dev/null @@ -1,167 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2015 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_event_source_get_pending" xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd_event_source_get_pending</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_event_source_get_pending</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_event_source_get_pending</refname> - - <refpurpose>Determine pending state of event sources</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_event_source_get_pending</function></funcdef> - <paramdef>sd_event_source *<parameter>source</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_event_source_get_pending()</function> may be - used to determine whether the event source object specified as - <parameter>source</parameter> has seen events but has not been - dispatched yet (and thus is marked "pending").</para> - - <para>Event source objects initially are not marked pending, when - they are created with calls such as - <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - with the exception of those created with - <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry> - which are immediately marked pending, and - <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for which the "pending" concept is not defined. For details see - the respective manual pages.</para> - - <para>In each event loop iteration one event source of those - marked pending is dispatched, in the order defined by the event - source priority, as set with - <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> - - <para>For I/O event sources, as created with - <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - the call - <citerefentry><refentrytitle>sd_event_source_get_io_revents</refentrytitle><manvolnum>3</manvolnum></citerefentry> - may be used to query the type of event pending in more - detail.</para> - - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, - <function>sd_event_source_get_pending()</function> returns an - integer greater than zero when the event source is marked pending, - and zero when the event source is not marked pending. On failure, - it returns a negative errno-style error code.</para> - </refsect1> - - <refsect1> - <title>Errors</title> - - <para>Returned errors may indicate the following problems:</para> - - <variablelist> - <varlistentry> - <term><constant>-EINVAL</constant></term> - - <listitem><para><parameter>source</parameter> is not a valid - pointer to an <structname>sd_event_source</structname> - object.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-EDOM</constant></term> - - <listitem><para><parameter>source</parameter> refers to an - event source object created with - <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ENOMEM</constant></term> - - <listitem><para>Not enough memory.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ESTALE</constant></term> - - <listitem><para>The event loop is already terminated.</para></listitem> - - </varlistentry> - - <varlistentry> - <term><constant>-ECHILD</constant></term> - - <listitem><para>The event loop has been created in a different process.</para></listitem> - - </varlistentry> - - </variablelist> - </refsect1> - - <xi:include href="libsystemd-pkgconfig.xml" /> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_event_source_set_description.xml b/man/sd_event_source_set_description.xml deleted file mode 100644 index b9488a622f..0000000000 --- a/man/sd_event_source_set_description.xml +++ /dev/null @@ -1,170 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2014 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="sd_event_source_set_description" xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd_event_source_set_description</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>More text</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_event_source_set_description</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_event_source_set_description</refname> - <refname>sd_event_source_get_description</refname> - - <refpurpose>Set or retrieve descriptive names of event sources</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_event_source_set_description</function></funcdef> - <paramdef>sd_event_source *<parameter>source</parameter></paramdef> - <paramdef>const char *<parameter>description</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_event_source_get_description</function></funcdef> - <paramdef>sd_event_source *<parameter>source</parameter></paramdef> - <paramdef>const char **<parameter>description</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_event_source_set_description()</function> may - be used to set an arbitrary descriptive name for the event source - object specified as <parameter>source</parameter>. This name will - be used in debugging messages generated by - <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for this event source, and may be queried using - <function>sd_event_source_get_description()</function> for - debugging purposes. The <parameter>description</parameter> parameter shall - point to a <constant>NUL</constant>-terminated string or be - <constant>NULL</constant>. In the latter case, the descriptive - name will be unset. The string is copied internally, hence the - <parameter>description</parameter> argument is not referenced - after the function returns.</para> - - <para><function>sd_event_source_get_description()</function> may - be used to query the current descriptive name assigned to the - event source object <parameter>source</parameter>. It returns a - pointer to the current name in <parameter>description</parameter>, - stored in memory internal to the event source. The memory is - invalidated when the event source is destroyed or the descriptive - name is changed.</para> - - <para>Event source objects generally have no description set when - they are created, except for UNIX signal event sources created - with - <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - whose descriptive name is initialized to the signal's C constant - name (e.g. <literal>SIGINT</literal> or - <literal>SIGTERM</literal>).</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, <function>sd_event_source_set_description()</function> and - <function>sd_event_source_get_description()</function> return a - non-negative integer. On failure, they return a negative - errno-style error code.</para> - </refsect1> - - <refsect1> - <title>Errors</title> - - <para>Returned errors may indicate the following problems:</para> - - <variablelist> - <varlistentry> - <term><constant>-EINVAL</constant></term> - - <listitem><para><parameter>source</parameter> is not a valid - pointer to an <structname>sd_event_source</structname> - object or the <parameter>description</parameter> argument for - <function>sd_event_source_get_description()</function> is - <constant>NULL</constant>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ENOMEM</constant></term> - - <listitem><para>Not enough memory to copy the - name.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ECHILD</constant></term> - - <listitem><para>The event loop has been created in a different process.</para></listitem> - - </varlistentry> - - <varlistentry> - <term><constant>-ENXIO</constant></term> - - <listitem><para>No name was set for the event - source.</para></listitem> - </varlistentry> - - </variablelist> - </refsect1> - - <xi:include href="libsystemd-pkgconfig.xml" /> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_event_source_set_enabled.xml b/man/sd_event_source_set_enabled.xml deleted file mode 100644 index 6844f29a49..0000000000 --- a/man/sd_event_source_set_enabled.xml +++ /dev/null @@ -1,179 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2015 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_event_source_set_enabled" xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd_event_source_set_enabled</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_event_source_set_enabled</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_event_source_set_enabled</refname> - <refname>sd_event_source_get_enabled</refname> - <refname>SD_EVENT_ON</refname> - <refname>SD_EVENT_OFF</refname> - <refname>SD_EVENT_ONESHOT</refname> - - <refpurpose>Enable or disable event sources</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> - - <funcsynopsisinfo><token>enum</token> { - <constant>SD_EVENT_OFF</constant> = 0, - <constant>SD_EVENT_ON</constant> = 1, - <constant>SD_EVENT_ONESHOT</constant> = -1, -};</funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_event_source_set_enabled</function></funcdef> - <paramdef>sd_event_source *<parameter>source</parameter></paramdef> - <paramdef>int <parameter>enabled</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_event_source_get_enabled</function></funcdef> - <paramdef>sd_event_source *<parameter>source</parameter></paramdef> - <paramdef>int *<parameter>enabled</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_event_source_set_enabled()</function> may be - used to enable or disable the event source object specified as - <parameter>source</parameter>. The <parameter>enabled</parameter> - parameter takes one of <constant>SD_EVENT_ON</constant> (to - enable), <constant>SD_EVENT_OFF</constant> (to disable) or - <constant>SD_EVENT_ONESHOT</constant>. If invoked with - <constant>SD_EVENT_ONESHOT</constant> the event source will be - enabled but automatically reset to - <constant>SD_EVENT_OFF</constant> after the event source was - dispatched once.</para> - - <para>Event sources that are disabled will not result in event - loop wakeups and will not be dispatched, until they are enabled - again.</para> - - <para><function>sd_event_source_get_enabled()</function> may be - used to query whether the event source object - <parameter>source</parameter> is currently enabled or not. It - returns the enablement state in - <parameter>enabled</parameter>.</para> - - <para>Event source objects are enabled when they are first created - with calls such as - <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>. However, - depending on the event source type they are enabled continuously - (<constant>SD_EVENT_ON</constant>) or only for a single invocation - of the event source handler - (<constant>SD_EVENT_ONESHOT</constant>). For details see the - respective manual pages.</para> - - <para>As event source objects stay active and may be dispatched as - long as there is at least one reference to them, in many cases it - is a good idea to combine a call to - <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> - with a prior call to - <function>sd_event_source_set_enabled()</function> with - <constant>SD_EVENT_OFF</constant>, to ensure the event source is - not dispatched again until all other remaining references are dropped.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, <function>sd_event_source_set_enabled()</function> and - <function>sd_event_source_get_enabled()</function> return a - non-negative integer. On failure, they return a negative - errno-style error code.</para> - </refsect1> - - <refsect1> - <title>Errors</title> - - <para>Returned errors may indicate the following problems:</para> - - <variablelist> - <varlistentry> - <term><constant>-EINVAL</constant></term> - - <listitem><para><parameter>source</parameter> is not a valid - pointer to an <structname>sd_event_source</structname> - object.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ENOMEM</constant></term> - - <listitem><para>Not enough memory.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ECHILD</constant></term> - - <listitem><para>The event loop has been created in a different process.</para></listitem> - - </varlistentry> - - </variablelist> - </refsect1> - - <xi:include href="libsystemd-pkgconfig.xml" /> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_event_source_set_prepare.xml b/man/sd_event_source_set_prepare.xml deleted file mode 100644 index 24861d01d9..0000000000 --- a/man/sd_event_source_set_prepare.xml +++ /dev/null @@ -1,171 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2015 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_event_source_set_prepare" xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd_event_source_set_prepare</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_event_source_set_prepare</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_event_source_set_prepare</refname> - - <refpurpose>Set a preparation callback for event sources</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_event_source_set_prepare</function></funcdef> - <paramdef>sd_event_source *<parameter>source</parameter></paramdef> - <paramdef>sd_event_handler_t <parameter>callback</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>typedef int (*<function>sd_event_handler_t</function>)</funcdef> - <paramdef>sd_event_source *<parameter>s</parameter></paramdef> - <paramdef>void *<parameter>userdata</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_event_source_set_prepare()</function> may be - used to set a preparation callback for the event source object - specified as <parameter>source</parameter>. The callback function - specified as <parameter>callback</parameter> will be invoked - immediately before the event loop goes to sleep to wait for - incoming events. It is invoked with the user data pointer passed - when the event source was created. The callback function may be - used to reconfigure the precise events to wait for. If the - <parameter>callback</parameter> parameter is passed as NULL the - callback function is reset. </para> - - <para>Event source objects have no preparation callback associated - when they are first created with calls such as - <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Preparation - callback functions are supported for all event source types with - the exception of those created with - <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Preparation - callback functions are dispatched in the order indicated by the - event source's priority field, as set with - <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Preparation - callbacks of disabled event sources (see - <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>) - are not invoked.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, - <function>sd_event_source_set_prepare()</function> returns a - non-negative integer. On failure, it returns a negative - errno-style error code.</para> - </refsect1> - - <refsect1> - <title>Errors</title> - - <para>Returned errors may indicate the following problems:</para> - - <variablelist> - <varlistentry> - <term><constant>-EINVAL</constant></term> - - <listitem><para><parameter>source</parameter> is not a valid - pointer to an <structname>sd_event_source</structname> - object.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ESTALE</constant></term> - - <listitem><para>The event loop is already terminated.</para></listitem> - - </varlistentry> - <varlistentry> - <term><constant>-ENOMEM</constant></term> - - <listitem><para>Not enough memory.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ECHILD</constant></term> - - <listitem><para>The event loop has been created in a different process.</para></listitem> - - </varlistentry> - - <varlistentry> - <term><constant>-EDOM</constant></term> - - <listitem><para>The specified event source has been created - with - <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> - - </varlistentry> - - </variablelist> - </refsect1> - - <xi:include href="libsystemd-pkgconfig.xml" /> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_event_source_set_priority.xml b/man/sd_event_source_set_priority.xml deleted file mode 100644 index 8c9b39fe5e..0000000000 --- a/man/sd_event_source_set_priority.xml +++ /dev/null @@ -1,189 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2015 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_event_source_set_priority" xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd_event_source_set_priority</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_event_source_set_priority</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_event_source_set_priority</refname> - <refname>sd_event_source_get_priority</refname> - <refname>SD_EVENT_PRIORITY_IMPORTANT</refname> - <refname>SD_EVENT_PRIORITY_NORMAL</refname> - <refname>SD_EVENT_PRIORITY_IDLE</refname> - - <refpurpose>Set or retrieve the priority of event sources</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> - - <funcsynopsisinfo><token>enum</token> { - <constant>SD_EVENT_SOURCE_IMPORTANT</constant> = -100, - <constant>SD_EVENT_SOURCE_NORMAL</constant> = 0, - <constant>SD_EVENT_SOURCE_IDLE</constant> = 100, -};</funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_event_source_set_priority</function></funcdef> - <paramdef>sd_event_source *<parameter>source</parameter></paramdef> - <paramdef>int64_t <parameter>priority</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_event_source_get_priority</function></funcdef> - <paramdef>sd_event_source *<parameter>source</parameter></paramdef> - <paramdef>int64_t *<parameter>priority</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_event_source_set_priority()</function> may be - used to set the priority for the event source object specified as - <parameter>source</parameter>. The priority is specified as an - arbitrary signed 64bit integer. The priority is initialized to - <constant>SD_EVENT_PRIORITY_NORMAL</constant> (0) when the event - source is allocated with a call such as - <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry> - or - <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - and may be changed with this call. If multiple event sources have seen events at the same time, they are dispatched in the order indicated by the - event sources' priorities. Event sources with smaller priority - values are dispatched first. As well-known points of reference, - the constants <constant>SD_EVENT_PRIORITY_IMPORTANT</constant> - (-100), <constant>SD_EVENT_PRIORITY_NORMAL</constant> (0) and - <constant>SD_EVENT_PRIORITY_IDLE</constant> (100) may be used to - indicate event sources that shall be dispatched early, normally or - late. It is recommended to specify priorities based on these - definitions, and relative to them — however, the full 64bit - signed integer range is available for ordering event - sources.</para> - - <para>Priorities define the order in which event sources that have - seen events are dispatched. Care should be taken to ensure that - high-priority event sources (those with negative priority values - assigned) do not cause starvation of low-priority event sources - (those with positive priority values assigned).</para> - - <para>The order in which event sources with the same priority are - dispatched is undefined, but the event loop generally tries to - dispatch them in the order it learnt about events on them. As the - backing kernel primitives do not provide accurate information - about the order in which events occurred this is not necessarily - reliable. However, it is guaranteed that if events are seen on - multiple same-priority event sources at the same time, each one is - not dispatched again until all others have been dispatched - once. This behaviour guarantees that within each priority - particular event sources do not starve or dominate the event - loop.</para> - - <para><function>sd_event_source_get_priority()</function> may be - used to query the current priority assigned to the event source - object <parameter>source</parameter>.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, - <function>sd_event_source_set_priority()</function> and - <function>sd_event_source_get_priority()</function> return a - non-negative integer. On failure, they return a negative - errno-style error code.</para> - </refsect1> - - <refsect1> - <title>Errors</title> - - <para>Returned errors may indicate the following problems:</para> - - <variablelist> - <varlistentry> - <term><constant>-EINVAL</constant></term> - - <listitem><para><parameter>source</parameter> is not a valid - pointer to an <structname>sd_event_source</structname> - object.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ENOMEM</constant></term> - - <listitem><para>Not enough memory.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ESTALE</constant></term> - - <listitem><para>The event loop is already terminated.</para></listitem> - - </varlistentry> - - <varlistentry> - <term><constant>-ECHILD</constant></term> - - <listitem><para>The event loop has been created in a different process.</para></listitem> - - </varlistentry> - - </variablelist> - </refsect1> - - <xi:include href="libsystemd-pkgconfig.xml" /> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_event_source_set_userdata.xml b/man/sd_event_source_set_userdata.xml deleted file mode 100644 index 533d491b13..0000000000 --- a/man/sd_event_source_set_userdata.xml +++ /dev/null @@ -1,119 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2015 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_event_source_set_userdata" xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd_event_source_set_userdata</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_event_source_set_userdata</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_event_source_set_userdata</refname> - <refname>sd_event_source_get_userdata</refname> - - <refpurpose>Set or retrieve user data pointer of event sources</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>void* <function>sd_event_source_set_userdata</function></funcdef> - <paramdef>sd_event_source *<parameter>source</parameter></paramdef> - <paramdef>void *<parameter>userdata</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>void* <function>sd_event_source_get_userdata</function></funcdef> - <paramdef>sd_event_source *<parameter>source</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_event_source_set_userdata()</function> may be - used to set an arbitrary user data pointer for the event source - object specified as <parameter>source</parameter>. The user data - pointer is usually specified when creating an event source object - with calls such as - <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry> - or - <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - and may be updated with this call. The user data pointer is also - passed to all handler callback functions associated with the event - source. The <parameter>userdata</parameter> parameter specifies - the new user data pointer to set, the function returns the - previous user data pointer. Note that <constant>NULL</constant> is - a valid user data pointer.</para> - - <para><function>sd_event_source_get_userdata()</function> may be - used to query the current user data pointer assigned to the event - source object <parameter>source</parameter>.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, - <function>sd_event_source_set_userdata()</function> and - <function>sd_event_source_get_userdata()</function> return the - previously set user data pointer. On failure, they return - NULL.</para> - </refsect1> - - <xi:include href="libsystemd-pkgconfig.xml" /> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_event_source_unref.xml b/man/sd_event_source_unref.xml deleted file mode 100644 index 2c4d450763..0000000000 --- a/man/sd_event_source_unref.xml +++ /dev/null @@ -1,142 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2015 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_event_source_unref" xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd_event_source_unref</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_event_source_unref</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_event_source_unref</refname> - <refname>sd_event_source_unrefp</refname> - <refname>sd_event_source_ref</refname> - - <refpurpose>Increase or decrease event source reference counters</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>sd_event_source* <function>sd_event_source_unref</function></funcdef> - <paramdef>sd_event_source *<parameter>source</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>void <function>sd_event_source_unrefp</function></funcdef> - <paramdef>sd_event_source **<parameter>source</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>sd_event_source* <function>sd_event_source_ref</function></funcdef> - <paramdef>sd_event_source *<parameter>source</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_event_source_unref()</function> may be used to - decrement by one the reference counter of the event source object - specified as <parameter>source</parameter>. The reference counter - is initially set to one, when the event source is created with calls - such as - <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry> - or - <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>. When - the reference counter reaches zero it is removed from its event loop - object and destroyed.</para> - - <para><function>sd_event_source_unrefp()</function> is similar to - <function>sd_event_source_unref()</function> but takes a pointer to a - pointer to an <type>sd_event_source</type> object. This call is useful in - conjunction with GCC's and LLVM's <ulink - url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up - Variable Attribute</ulink>. Note that this function is defined as - inline function.</para> - - <para><function>sd_event_source_ref()</function> may be used - to increase by one the reference counter of the event source object - specified as <parameter>source</parameter>.</para> - - <para><function>sd_event_source_unref()</function>, - <function>sd_bus_creds_unrefp()</function> and - <function>sd_bus_creds_ref()</function> execute no operation if - the passed event source object is - <constant>NULL</constant>.</para> - - <para>Note that event source objects stay alive and may be - dispatched as long as they have a reference counter greater than - zero. In order to drop a reference of an event source and make - sure the associated event source handler function is not called - anymore it is recommended to combine a call of - <function>sd_event_source_unref()</function> with a prior call to - <function>sd_event_source_set_enabled()</function> with - <constant>SD_EVENT_OFF</constant>.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para><function>sd_event_source_unref()</function> always returns - <constant>NULL</constant>. - <function>sd_event_source_ref()</function> always returns the - event source object passed in.</para> - </refsect1> - - <xi:include href="libsystemd-pkgconfig.xml" /> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_event_wait.xml b/man/sd_event_wait.xml deleted file mode 100644 index f2aea00e98..0000000000 --- a/man/sd_event_wait.xml +++ /dev/null @@ -1,346 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2015 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="sd_event_wait" xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd_event_wait</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Tom</firstname> - <surname>Gundersen</surname> - <email>teg@jklm.no</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_event_wait</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_event_wait</refname> - <refname>sd_event_prepare</refname> - <refname>sd_event_dispatch</refname> - <refname>sd_event_get_state</refname> - <refname>SD_EVENT_INITIAL</refname> - <refname>SD_EVENT_PREPARING</refname> - <refname>SD_EVENT_ARMED</refname> - <refname>SD_EVENT_PENDING</refname> - <refname>SD_EVENT_RUNNING</refname> - <refname>SD_EVENT_EXITING</refname> - <refname>SD_EVENT_FINISHED</refname> - - <refpurpose>Low-level event loop operations</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> - - <funcsynopsisinfo><token>enum</token> { - <constant>SD_EVENT_INITIAL</constant>, - <constant>SD_EVENT_PREPARING</constant>, - <constant>SD_EVENT_ARMED</constant>, - <constant>SD_EVENT_PENDING</constant>, - <constant>SD_EVENT_RUNNING</constant>, - <constant>SD_EVENT_EXITING</constant>, - <constant>SD_EVENT_FINISHED</constant>, -};</funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_event_prepare</function></funcdef> - <paramdef>sd_event *<parameter>event</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_event_wait</function></funcdef> - <paramdef>sd_event *<parameter>event</parameter></paramdef> - <paramdef>uint64_t <parameter>usec</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_event_dispatch</function></funcdef> - <paramdef>sd_event *<parameter>event</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_event_get_state</function></funcdef> - <paramdef>sd_event *<parameter>event</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>The low-level <function>sd_event_prepare()</function>, - <function>sd_event_wait()</function> and - <function>sd_event_dispatch()</function> functions may be used to - execute specific phases of an event loop. See - <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>sd_event_loop</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for higher-level functions that execute individual but complete - iterations of an event loop or run it continuously.</para> - - <para><function>sd_event_prepare()</function> checks for pending - events and arms necessary timers. If any events are ready to be - processed ("pending"), it returns a positive, non-zero value, and the caller - should process these events with - <function>sd_event_dispatch()</function>.</para> - - <para><function>sd_event_dispatch()</function> dispatches the - highest priority event source that has a pending event. On - success, <function>sd_event_dispatch()</function> returns either - zero, which indicates that no further event sources may be - dispatched and exiting of the event loop was requested via - <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>; - or a positive non-zero value, which means that an event source was - dispatched and the loop returned to its initial state, and the - caller should initiate the next event loop iteration by invoking - <function>sd_event_prepare()</function> again.</para> - - <para>In case <function>sd_event_prepare()</function> returned - zero, <function>sd_event_wait()</function> should be called to - wait for further events or a timeout. If any events are ready to - be processed, it returns a positive, non-zero value, and the - events should be dispatched with - <function>sd_event_dispatch()</function>. Otherwise, the event - loop returned to its initial state and the next event loop - iteration should be initiated by invoking - <function>sd_event_prepare()</function> again.</para> - - <para><function>sd_event_get_state()</function> may be used to - determine the state the event loop is currently in. It returns one - of the states described below.</para> - - <para>All four functions take, as the first argument, the event - loop object <parameter>event</parameter> that has been created - with <function>sd_event_new()</function>. The timeout for - <function>sd_event_wait()</function> is specified in - <parameter>usec</parameter> in milliseconds. <constant>(uint64_t) - -1</constant> may be used to specify an infinite timeout.</para> -</refsect1> - - <refsect1> - <title>State Machine</title> - - <para>The event loop knows the following states, that may be - queried with <function>sd_event_get_state()</function>.</para> - - <variablelist> - <varlistentry> - <term><constant>SD_EVENT_INITIAL</constant></term> - - <listitem><para>The initial state the event loop is in, - before each event loop iteration. Use - <function>sd_event_prepare()</function> to transition the - event loop into the <constant>SD_EVENT_ARMED</constant> or - <constant>SD_EVENT_PENDING</constant> states.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>SD_EVENT_PREPARING</constant></term> - - <listitem><para>An event source is currently being prepared, - i.e. the preparation handler is currently being executed, as - set with - <citerefentry><refentrytitle>sd_event_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This - state is only seen in the event source preparation handler - that is invoked from the - <function>sd_event_prepare()</function> call and is - immediately followed by <constant>SD_EVENT_ARMED</constant> or - <constant>SD_EVENT_PENDING</constant>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>SD_EVENT_ARMED</constant></term> - - <listitem><para><function>sd_event_prepare()</function> has - been called and no event sources were ready to be - dispatched. Use <function>sd_event_wait()</function> to wait - for new events, and transition into - <constant>SD_EVENT_PENDING</constant> or back into - <constant>SD_EVENT_INITIAL</constant>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>SD_EVENT_PENDING</constant></term> - - <listitem><para><function>sd_event_prepare()</function> or - <function>sd_event_wait()</function> have been called and - there were event sources with events pending. Use - <function>sd_event_dispatch()</function> to dispatch the - highest priority event source and transition back to - <constant>SD_EVENT_INITIAL</constant>, or - <constant>SD_EVENT_FINISHED</constant>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>SD_EVENT_RUNNING</constant></term> - - <listitem><para>A regular event source is currently being - dispatched. This state is only seen in the event source - handler that is invoked from the - <function>sd_event_dispatch()</function> call, and is - immediately followed by <constant>SD_EVENT_INITIAL</constant> - or <constant>SD_EVENT_FINISHED</constant> as soon the event - source handler returns. Note that during dispatching of exit - event sources the <constant>SD_EVENT_EXITING</constant> state - is seen instead.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>SD_EVENT_EXITING</constant></term> - - <listitem><para>Similar to - <constant>SD_EVENT_RUNNING</constant> but is the state in - effect while dispatching exit event sources. It is followed by - <constant>SD_EVENT_INITIAL</constant> or - <constant>SD_EVENT_FINISHED</constant> as soon as the event - handler returns.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>SD_EVENT_FINISHED</constant></term> - - <listitem><para>The event loop has exited. All exit event - sources have run. If the event loop is in this state it serves - no purpose anymore, and should be freed.</para></listitem> - </varlistentry> - - </variablelist> - - <para>A simplified flow chart of the states and the calls to - transition between them is shown below. Note that - <constant>SD_EVENT_PREPARING</constant>, - <constant>SD_EVENT_RUNNING</constant> and - <constant>SD_EVENT_EXITING</constant> are not shown here.</para> - - <programlisting> - INITIAL -<---<---<---<---<---<---<---<---<---<---<---<---\ - | | - | ^ - | | - v ret == 0 | - sd_event_prepare() >--->--->--->--->- ARMED | - | | ^ - | ret > 0 | | - | | | - v v ret == 0 | - PENDING <---<---<---<---<---< sd_event_wait() >--->--->--+ - | ret > 0 ^ - | | - | | - v | - sd_event_dispatch() >--->--->--->--->--->--->--->--->--->--->/ - | ret > 0 - | ret == 0 - | - v - FINISHED - </programlisting> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, these functions return 0 or a positive integer. - On failure, they return a negative errno-style error code. In case - of <function>sd_event_prepare()</function> and - <function>sd_event_wait()</function>, a positive, non-zero return - code indicates that events are ready to be processed and zero - indicates that no events are ready. In case of - <function>sd_event_dispatch()</function>, a positive, non-zero - return code indicates that the event loop returned to its initial - state and zero indicates the event loop has - exited. <function>sd_event_get_state()</function> returns a - positive or zero state on success.</para> - </refsect1> - - <refsect1> - <title>Errors</title> - - <para>Returned errors may indicate the following problems:</para> - - <variablelist> - <varlistentry> - <term><constant>-EINVAL</constant></term> - - <listitem><para>The <parameter>event</parameter> parameter is - invalid or <constant>NULL</constant>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-EBUSY</constant></term> - - <listitem><para>The event loop object is not in the right - state.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ESTALE</constant></term> - - <listitem><para>The event loop is already terminated.</para></listitem> - - </varlistentry> - - <varlistentry> - <term><constant>-ECHILD</constant></term> - - <listitem><para>The event loop has been created in a different process.</para></listitem> - - </varlistentry> - - </variablelist> - - <para>Other errors are possible, too.</para> - </refsect1> - - <xi:include href="libsystemd-pkgconfig.xml" /> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_get_seats.xml b/man/sd_get_seats.xml deleted file mode 100644 index 37eb3fc894..0000000000 --- a/man/sd_get_seats.xml +++ /dev/null @@ -1,164 +0,0 @@ -<?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" conditional='HAVE_PAM'> - - <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> - <refname>sd_get_machine_names</refname> - <refpurpose>Determine available seats, sessions, logged in users and virtual machines/containers</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>uid_t **<parameter>users</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_get_machine_names</function></funcdef> - <paramdef>char ***<parameter>machines</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 - <constant>NULL</constant> terminated array of seat identifiers. - The returned array and all strings it references need to be freed - with the libc - <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use. Note that instead of an empty array - <constant>NULL</constant> may be returned and should be considered - equivalent to an empty array.</para> - - <para>Similarly, <function>sd_get_sessions()</function> may be - used to determine all current login sessions.</para> - - <para>Similarly, <function>sd_get_uids()</function> may be used to - determine all Unix users who currently have login sessions.</para> - - <para>Similarly, <function>sd_get_machine_names()</function> may - be used to determine all current virtual machines and containers - on the system.</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>, - <function>sd_get_uids()</function> and - <function>sd_get_machine_names()</function> return the number of - entries in the arrays. On failure, these calls return a negative - errno-style error code.</para> - </refsect1> - - - <refsect1> - <title>Errors</title> - - <para>Returned errors may indicate the following problems:</para> - - <variablelist> - - <varlistentry> - <term><constant>-EINVAL</constant></term> - - <listitem><para>An input parameter was invalid (out of range, - or NULL, where that is not accepted).</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ENOMEM</constant></term> - - <listitem><para>Memory allocation failed.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>The <function>sd_get_seats()</function>, - <function>sd_get_sessions()</function>, - <function>sd_get_uids()</function> and - <function>sd_get_machine_names()</function> interfaces are - available as a shared library, which can be compiled and linked to - with the - <constant>libsystemd</constant> <citerefentry project='die-net'><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 deleted file mode 100644 index 2ad1f8f728..0000000000 --- a/man/sd_id128_get_machine.xml +++ /dev/null @@ -1,129 +0,0 @@ -<?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 project='man-pages'><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 a 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 a shared library, which can be compiled and linked to with the - <literal>libsystemd</literal> <citerefentry project='die-net'><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 deleted file mode 100644 index ab449d2937..0000000000 --- a/man/sd_id128_randomize.xml +++ /dev/null @@ -1,114 +0,0 @@ -<?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 - <option>--new-id</option> option may be used as a 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 a shared library, which can be compiled and linked to - with the - <literal>libsystemd</literal> <citerefentry project='die-net'><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 deleted file mode 100644 index e70c80892e..0000000000 --- a/man/sd_id128_to_string.xml +++ /dev/null @@ -1,132 +0,0 @@ -<?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>, 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 a 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 - <constant>NUL</constant> byte.</para> - - <para><function>sd_id128_from_string()</function> implements the - reverse operation: it takes a 33 character string with 32 - hexadecimal digits (either lowercase or uppercase, terminated by - <constant>NUL</constant>) and parses them back into a 128-bit ID - returned in <parameter>ret</parameter>. Alternatively, this call - can also parse a 37-character string with a 128-bit ID formatted - as RFC UUID.</para> - - <para>For more information about the <literal>sd_id128_t</literal> - type see - <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - Note that these calls operate the same way on all architectures, - i.e. the results do not depend on endianness.</para> - - <para>When formatting a 128-bit ID into a string, it is often - easier to use a format string for - <citerefentry project='man-pages'><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 a shared library, which can be compiled and linked to - with the - <literal>libsystemd</literal> <citerefentry project='die-net'><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 project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_is_fifo.xml b/man/sd_is_fifo.xml deleted file mode 100644 index 627cb87aaf..0000000000 --- a/man/sd_is_fifo.xml +++ /dev/null @@ -1,200 +0,0 @@ -<?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" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <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> - <refname>sd_is_special</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> - - <funcprototype> - <funcdef>int <function>sd_is_special</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 - <constant>NULL</constant>, 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 - <constant>AF_UNSPEC</constant>, it is checked whether the socket - is of the specified family (AF_UNIX, <constant>AF_INET</constant>, - ...). If the <parameter>type</parameter> parameter is not 0, it is - checked whether the socket is of the specified type - (<constant>SOCK_STREAM</constant>, - <constant>SOCK_DGRAM</constant>, ...). 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 - <constant>AF_UNSPEC</constant>, <constant>AF_INET</constant>, or - <constant>AF_INET6</constant>.</para> - - <para><function>sd_is_socket_unix()</function> is similar to - <function>sd_is_socket()</function> but optionally checks the - <constant>AF_UNIX</constant> path the socket is bound to, unless - the <parameter>path</parameter> parameter is - <constant>NULL</constant>. For normal file system - <constant>AF_UNIX</constant> 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 the - <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 - <constant>NULL</constant>, it is checked whether the message queue - is bound to the specified name.</para> - - <para><function>sd_is_special()</function> may be called to check - whether the specified file descriptor refers to a special file. If - the <parameter>path</parameter> parameter is not - <constant>NULL</constant>, it is checked whether the file - descriptor is bound to the specified file name. Special files in - this context are character device nodes and files in - <filename>/proc</filename> or <filename>/sys</filename>.</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> - - <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> - - <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> - </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 deleted file mode 100644 index 98415d53fd..0000000000 --- a/man/sd_journal_add_match.xml +++ /dev/null @@ -1,216 +0,0 @@ -<?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_add_conjunction</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_add_conjunction</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>void <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>. - Parameter <parameter>data</parameter> must be of the form - <literal><replaceable>FIELD</replaceable>=<replaceable>value</replaceable></literal>, - where the <replaceable>FIELD</replaceable> 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 <replaceable>value</replaceable> part may be anything, including binary. Parameter - <parameter>size</parameter> specifies the number of bytes in <parameter>data</parameter> - (i.e. the length of <replaceable>FIELD</replaceable>, plus one, plus the length of - <replaceable>value</replaceable>). Parameter <parameter>size</parameter> may also be - specified as <constant>0</constant>, in which case <parameter>data</parameter> - must be a <constant>NUL</constant>-terminated string, and the bytes before the terminating - zero are used as the match.</para> - - <para>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 since the - last invocation of - <function>sd_journal_add_disjunction()</function> or - <function>sd_journal_add_conjunction()</function> are combined in - an OR with all matches added afterwards, until - <function>sd_journal_add_disjunction()</function> or - <function>sd_journal_add_conjunction()</function> is invoked again - to begin the next OR or AND term. </para> - - <para><function>sd_journal_add_conjunction()</function> may be - used to insert a conjunction (i.e. logical AND) in the match list. - If this call is invoked, all previously added matches since the - last invocation of - <function>sd_journal_add_conjunction()</function> are combined in - an AND with all matches added afterwards, until - <function>sd_journal_add_conjunction()</function> is invoked again - to begin the next AND term. The combination of - <function>sd_journal_add_match()</function>, - <function>sd_journal_add_disjunction()</function> and - <function>sd_journal_add_conjunction()</function> may be used to - build complex search terms, even though full logical expressions - are not available. Note that - <function>sd_journal_add_conjunction()</function> operates one - level 'higher' than - <function>sd_journal_add_disjunction()</function>. It is hence - possible to build an expression of AND terms, consisting of OR - terms, consisting of AND terms, consisting of OR terms of matches - (the latter OR expression is implicitly created for matches with - the same field name, see above).</para> - - <para><function>sd_journal_flush_matches()</function> may be used - to flush all matches, disjunction and conjunction 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>, - <function>sd_journal_add_disjunction()</function> and - <function>sd_journal_add_conjunction()</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>, - <function>sd_journal_add_conjunction()</function> and - <function>sd_journal_flush_matches()</function> - interfaces are available as a shared library, which can - be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><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_enumerate_fields.xml b/man/sd_journal_enumerate_fields.xml deleted file mode 100644 index fa5884106b..0000000000 --- a/man/sd_journal_enumerate_fields.xml +++ /dev/null @@ -1,161 +0,0 @@ -<?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 2016 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_enumerate_fields"> - - <refentryinfo> - <title>sd_journal_enumerate_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>sd_journal_enumerate_fields</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_journal_enumerate_fields</refname> - <refname>sd_journal_restart_fields</refname> - <refname>SD_JOURNAL_FOREACH_FIELD</refname> - <refpurpose>Read used field names from the journal</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_journal_enumerate_fields</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - <paramdef>const char **<parameter>field</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>void <function>sd_journal_restart_fields</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef><function>SD_JOURNAL_FOREACH_FIELD</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - <paramdef>const char *<parameter>field</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_journal_enumerate_fields()</function> may be used to iterate through all field names used in the - opened journal files. On each invocation the next field name is returned. The order of the returned field names is - not defined. It takes two arguments: the journal context object, plus a pointer to a constant string pointer where - the field name is 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_fields()</function>. Note that this call is subject to the data field - size threshold as controlled by <function>sd_journal_set_data_threshold()</function>.</para> - - <para><function>sd_journal_restart_fields()</function> resets the field name enumeration index to the beginning of - the list. The next invocation of <function>sd_journal_enumerate_fields()</function> will return the first field - name again.</para> - - <para>The <function>SD_JOURNAL_FOREACH_FIELD()</function> macro may be used as a handy wrapper around - <function>sd_journal_restart_fields()</function> and <function>sd_journal_enumerate_fields()</function>.</para> - - <para>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> - - <para>To retrieve the possible values a specific field can take use - <citerefentry><refentrytitle>sd_journal_query_unique</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para><function>sd_journal_enumerate_fields()</function> returns a - positive integer if the next field name has been read, 0 when no - more field names are known, or a negative errno-style error code. - <function>sd_journal_restart_fields()</function> returns - nothing.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>The <function>sd_journal_enumerate_fields()</function> and <function>sd_journal_restart_fields()</function> - interfaces are available as a shared library, which can be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry - project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para> - </refsect1> - - <refsect1> - <title>Examples</title> - - <para>Use the <function>SD_JOURNAL_FOREACH_FIELD</function> macro to iterate through all field names in use in the - current journal.</para> - - <programlisting>#include <stdio.h> -#include <string.h> -#include <systemd/sd-journal.h> - -int main(int argc, char *argv[]) { - sd_journal *j; - const char *field; - 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; - } - SD_JOURNAL_FOREACH_FIELD(j, field) - printf("%s\n", field); - 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_query_unique</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_get_catalog.xml b/man/sd_journal_get_catalog.xml deleted file mode 100644 index c19eb11b20..0000000000 --- a/man/sd_journal_get_catalog.xml +++ /dev/null @@ -1,137 +0,0 @@ -<?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_catalog"> - - <refentryinfo> - <title>sd_journal_get_catalog</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_catalog</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_journal_get_catalog</refname> - <refname>sd_journal_get_catalog_for_message_id</refname> - <refpurpose>Retrieve message catalog entry</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_journal_get_catalog</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - <paramdef>char **<parameter>ret</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_journal_get_catalog_for_message_id</function></funcdef> - <paramdef>sd_id128_t <parameter>id</parameter></paramdef> - <paramdef>char **<parameter>ret</parameter></paramdef> - </funcprototype> - - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_journal_get_catalog()</function> retrieves a - message catalog entry for the current journal entry. This will - look up an entry in the message catalog by using the - <literal>MESSAGE_ID=</literal> field of the current journal entry. - Before returning the entry all journal field names in the catalog - entry text enclosed in "@" will be replaced by the respective - field values of the current entry. If a field name referenced in - the message catalog entry does not exist, in the current journal - entry, the "@" will be removed, but the field name otherwise left - untouched.</para> - - <para><function>sd_journal_get_catalog_for_message_id()</function> - works similar to <function>sd_journal_get_catalog()</function> but - the entry is looked up by the specified message ID (no open - journal context is necessary for this), and no field substitution - is performed.</para> - - <para>For more information about the journal message catalog - please refer to the <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/catalog">Journal - Message Catalogs</ulink> documentation page.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para><function>sd_journal_get_catalog()</function> and - <function>sd_journal_get_catalog_for_message_id()</function> - return 0 on success or a negative errno-style error code. If no - matching message catalog entry is found, -ENOENT is - returned.</para> - - <para>On successful return, <parameter>ret</parameter> points to a - new string, which must be freed with - <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - </para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>The <function>sd_journal_get_catalog()</function> and - <function>sd_journal_get_catalog_for_message_id()</function> - interfaces are available as a shared library, which can be - compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><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>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_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_journal_get_cursor.xml b/man/sd_journal_get_cursor.xml deleted file mode 100644 index a400d8b1b5..0000000000 --- a/man/sd_journal_get_cursor.xml +++ /dev/null @@ -1,144 +0,0 @@ -<?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 project='man-pages'><refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum></citerefentry> - and should be freed after use with - <citerefentry project='man-pages'><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 sought 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 does not - 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 a shared library, which can be compiled and linked to - with the - <constant>libsystemd</constant> <citerefentry project='die-net'><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 deleted file mode 100644 index 23e7cc65e8..0000000000 --- a/man/sd_journal_get_cutoff_realtime_usec.xml +++ /dev/null @@ -1,145 +0,0 @@ -<?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> - retrieves the realtime (wallclock) timestamps of the first and - last entries accessible in the journal. It takes three arguments: - the journal context object <parameter>j</parameter> and two - pointers <parameter>from</parameter> and <parameter>to</parameter> - pointing at 64-bit unsigned integers to store the timestamps in. - The timestamps are in microseconds since the epoch, i.e. - <constant>CLOCK_REALTIME</constant>. Either one of the two - timestamp arguments may be passed as <constant>NULL</constant> in - case the timestamp is not needed, but not both.</para> - - <para><function>sd_journal_get_cutoff_monotonic_usec()</function> - retrieves the monotonic timestamps of the first and last entries - accessible in the journal. It takes three arguments: the journal - context object <parameter>j</parameter>, a 128-bit identifier for - the boot <parameter>boot_id</parameter>, and two pointers to - 64-bit unsigned integers to store the timestamps, - <parameter>from</parameter> and <parameter>to</parameter>. The - timestamps are in microseconds since boot-up of the specific boot, - i.e. <constant>CLOCK_MONOTONIC</constant>. 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 <constant>NULL</constant> 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> - - <para>Locations pointed to by parameters - <parameter>from</parameter> and <parameter>to</parameter> will be - set only if the return value is positive, and obviously, the - parameters are non-null.</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 a shared library, which can be - compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><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 deleted file mode 100644 index 908ee7db16..0000000000 --- a/man/sd_journal_get_data.xml +++ /dev/null @@ -1,235 +0,0 @@ -<?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> - <refname>sd_journal_set_data_threshold</refname> - <refname>sd_journal_get_data_threshold</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> - - <funcprototype> - <funcdef>int <function>sd_journal_set_data_threshold</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - <paramdef>size_t <parameter>sz</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_journal_get_data_threshold</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - <paramdef>size_t *<parameter>sz</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 '='. Also note that, by default, data fields - larger than 64K might get truncated to 64K. This threshold may be - changed and turned off with - <function>sd_journal_set_data_threshold()</function> (see - below).</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> - - <para><function>sd_journal_set_data_threshold()</function> may be - used to change the data field size threshold for data returned by - <function>sd_journal_get_data()</function>, - <function>sd_journal_enumerate_data()</function> and - <function>sd_journal_enumerate_unique()</function>. This threshold - is a hint only: it indicates that the client program is interested - only in the initial parts of the data fields, up to the threshold - in size — but the library might still return larger data objects. - That means applications should not rely exclusively on this - setting to limit the size of the data fields returned, but need to - apply a explicit size limit on the returned data as well. This - threshold defaults to 64K by default. To retrieve the complete - data fields this threshold should be turned off by setting it to - 0, so that the library always returns the complete data objects. - It is recommended to set this threshold as low as possible since - this relieves the library from having to decompress large - compressed data objects in full.</para> - - <para><function>sd_journal_get_data_threshold()</function> returns - the currently configured data field size threshold.</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. - <function>sd_journal_set_data_threshold()</function> and - <function>sd_journal_get_threshold()</function> return 0 on - success or a negative errno-style error code.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>The <function>sd_journal_get_data()</function>, - <function>sd_journal_enumerate_data()</function>, - <function>sd_journal_restart_data()</function>, - <function>sd_journal_set_data_threshold()</function> and - <function>sd_journal_get_data_threshold()</function> interfaces - are available as a shared library, which can be compiled and - linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><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 length; - 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 deleted file mode 100644 index 61293f7f99..0000000000 --- a/man/sd_journal_get_fd.xml +++ /dev/null @@ -1,332 +0,0 @@ -<?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_get_events</refname> - <refname>sd_journal_get_timeout</refname> - <refname>sd_journal_process</refname> - <refname>sd_journal_wait</refname> - <refname>sd_journal_reliable_fd</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_get_events</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_journal_get_timeout</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - <paramdef>uint64_t *<parameter>timeout_usec</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> - - <funcprototype> - <funcdef>int <function>sd_journal_reliable_fd</function></funcdef> - <paramdef>sd_journal *<parameter>j</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 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>. - Use <function>sd_journal_get_events()</function> for an events - mask to watch for. 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 for changes to be noticed immediately. In particular - network files systems do not generate suitable file change events - in all cases. Cases like this can be detected with - <function>sd_journal_reliable_fd()</function>, below. - <function>sd_journal_get_timeout()</function> will ensure in these - cases that wake-ups happen frequently enough for changes to be - noticed, although with a certain latency.</para> - - <para><function>sd_journal_get_events()</function> will return the - <function>poll()</function> mask to wait for. This function will - return a combination of <constant>POLLIN</constant> and - <constant>POLLOUT</constant> and similar to fill into the - <literal>.events</literal> field of <varname>struct - pollfd</varname>.</para> - - <para><function>sd_journal_get_timeout()</function> will return a - timeout value for usage in <function>poll()</function>. This - returns a value in microseconds since the epoch of - <constant>CLOCK_MONOTONIC</constant> for timing out - <function>poll()</function> in <varname>timeout_usec</varname>. - See - <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for details about <constant>CLOCK_MONOTONIC</constant>. If there - is no timeout to wait for, this will fill in <constant>(uint64_t) - -1</constant> instead. Note that <function>poll()</function> takes - a relative timeout in milliseconds rather than an absolute timeout - in microseconds. To convert the absolute 'us' timeout into - relative 'ms', use code like the following:</para> - - <programlisting>uint64_t t; -int msec; -sd_journal_get_timeout(m, &t); -if (t == (uint64_t) -1) - msec = -1; -else { - struct timespec ts; - uint64_t n; - clock_getttime(CLOCK_MONOTONIC, &ts); - n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000; - msec = t > n ? (int) ((t - n + 999) / 1000) : 0; -}</programlisting> - - <para>The code above does not do any error checking for brevity's - sake. The calculated <varname>msec</varname> integer can be passed - directly as <function>poll()</function>'s timeout - parameter.</para> - - <para>After each <function>poll()</function> wake-up - <function>sd_journal_process()</function> needs to be called to - process events. 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_get_events()</function>, - <function>sd_journal_get_timeout()</function> and - <function>sd_journal_process()</function> is - <function>sd_journal_wait()</function>. It will synchronously wait - until the journal gets changed. The maximum time this call sleeps - may be controlled with the <parameter>timeout_usec</parameter> - parameter. Pass <constant>(uint64_t) -1</constant> to wait - indefinitely. Internally this call simply combines - <function>sd_journal_get_fd()</function>, - <function>sd_journal_get_events()</function>, - <function>sd_journal_get_timeout()</function>, - <function>poll()</function> and - <function>sd_journal_process()</function> into one.</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 known to be - immediately triggered. On certain file systems where file change - events from the OS are not available (such as NFS) changes need to - be polled for repeatedly, and hence are detected only with a - certain latency. This call will return a positive value if the - journal changes are detected immediately and zero when they need - to be polled for and hence might be noticed only with a certain - latency. Note that there is usually no need to invoke this function - directly as <function>sd_journal_get_timeout()</function> on these - file systems will ask for timeouts explicitly anyway.</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_get_events()</function> returns a - combination of <constant>POLLIN</constant>, - <constant>POLLOUT</constant> and suchlike 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> will generate wake-ups - immediately for all journal changes. Returns 0 if there might be a - latency involved.</para> - - <para><function>sd_journal_process()</function> and - <function>sd_journal_wait()</function> return one of - <constant>SD_JOURNAL_NOP</constant>, - <constant>SD_JOURNAL_APPEND</constant> or - <constant>SD_JOURNAL_INVALIDATE</constant> on success or a - negative errno-style error code. If - <constant>SD_JOURNAL_NOP</constant> is returned, the journal did - not change since the last invocation. If - <constant>SD_JOURNAL_APPEND</constant> is returned, new entries - have been appended to the end of the journal. If - <constant>SD_JOURNAL_INVALIDATE</constant>, 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 <constant>SD_JOURNAL_APPEND</constant>, 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_get_events()</function>, - <function>sd_journal_reliable_fd()</function>, - <function>sd_journal_process()</function> and - <function>sd_journal_wait()</function> interfaces are available as - a shared library, which can be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><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 void *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, (const char*) 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 <poll.h> -#include <systemd/sd-journal.h> - -int wait_for_changes(sd_journal *j) { - struct pollfd pollfd; - int msec; - - sd_journal_get_timeout(m, &t); - if (t == (uint64_t) -1) - msec = -1; - else { - struct timespec ts; - uint64_t n; - clock_getttime(CLOCK_MONOTONIC, &ts); - n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000; - msec = t > n ? (int) ((t - n + 999) / 1000) : 0; - } - - pollfd.fd = sd_journal_get_fd(j); - pollfd.events = sd_journal_get_events(j); - poll(&pollfd, 1, msec); - 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>, - <citerefentry><refentrytitle>clock_gettime</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 deleted file mode 100644 index 607d74666b..0000000000 --- a/man/sd_journal_get_realtime_usec.xml +++ /dev/null @@ -1,141 +0,0 @@ -<?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. - <constant>CLOCK_REALTIME</constant>.</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. The - timestamp is in microseconds since boot-up of the specific boot, - i.e. <constant>CLOCK_MONOTONIC</constant>. 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 - <constant>NULL</constant>, 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 <constant>NULL</constant> and the monotonic - timestamp of the current journal entry is not of the current - system boot, <constant>-ESTALE</constant> 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 a shared library, which can be compiled and - linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><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 deleted file mode 100644 index 72c804d834..0000000000 --- a/man/sd_journal_get_usage.xml +++ /dev/null @@ -1,100 +0,0 @@ -<?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 by journal files (in bytes). If - <constant>SD_JOURNAL_LOCAL_ONLY</constant> was passed when opening - the journal, 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 a shared library, which can be compiled and linked to - with the - <constant>libsystemd</constant> <citerefentry project='die-net'><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_has_runtime_files.xml b/man/sd_journal_has_runtime_files.xml deleted file mode 100644 index 237e649206..0000000000 --- a/man/sd_journal_has_runtime_files.xml +++ /dev/null @@ -1,95 +0,0 @@ -<?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 2016 Jan Synáček - - 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_has_runtime_files"> - - <refentryinfo> - <title>sd_journal_has_runtime_files</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Jan</firstname> - <surname>Synáček</surname> - <email>jan.synacek@gmail.com</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_journal_has_runtime_files</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_journal_has_runtime_files</refname> - <refname>sd_journal_has_persistent_files</refname> - <refpurpose>Query availability of runtime or persistent journal files.</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_journal_has_runtime_files</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_journal_has_persistent_files</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_journal_has_runtime_files()</function> returns a positive value - if runtime journal files (present in /run/systemd/journal/) have been found. - Otherwise returns 0.</para> - - <para><function>sd_journal_has_persistent_files()</function> returns a positive value - if persistent journal files (present in /var/log/journal/) have been found. - Otherwise returns 0.</para> - </refsect1> - - <refsect1> - <title>Return value</title> - <para>Both <function>sd_journal_has_runtime_files()</function> - and <function>sd_journal_has_persistent_files()</function> return -EINVAL - if their argument is NULL. - </para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_journal_next.xml b/man/sd_journal_next.xml deleted file mode 100644 index 115fe26661..0000000000 --- a/man/sd_journal_next.xml +++ /dev/null @@ -1,207 +0,0 @@ -<?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>Similarly, <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. - Similarly, <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 a shared library, which can be compiled and linked to - with the - <constant>libsystemd</constant> <citerefentry project='die-net'><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", (const void **)&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 deleted file mode 100644 index 153af2387f..0000000000 --- a/man/sd_journal_open.xml +++ /dev/null @@ -1,228 +0,0 @@ -<?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_open_directory_fd</refname> - <refname>sd_journal_open_files</refname> - <refname>sd_journal_open_files_fd</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</refname> - <refname>SD_JOURNAL_CURRENT_USER</refname> - <refname>SD_JOURNAL_OS_ROOT</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_open_directory_fd</function></funcdef> - <paramdef>sd_journal **<parameter>ret</parameter></paramdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>flags</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_journal_open_files</function></funcdef> - <paramdef>sd_journal **<parameter>ret</parameter></paramdef> - <paramdef>const char **<parameter>paths</parameter></paramdef> - <paramdef>int <parameter>flags</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_journal_open_files_fd</function></funcdef> - <paramdef>sd_journal **<parameter>ret</parameter></paramdef> - <paramdef>int <parameter>fds[]</parameter></paramdef> - <paramdef>unsigned <parameter>n_fds</parameter></paramdef> - <paramdef>int <parameter>flags</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>void <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 <varname>sd_journal</varname> pointer, which, - on success, will contain a journal context object. The second - argument is a flags field, which may consist of the following - flags ORed together: <constant>SD_JOURNAL_LOCAL_ONLY</constant> - makes sure only journal files generated on the local machine will - be opened. <constant>SD_JOURNAL_RUNTIME_ONLY</constant> makes sure - only volatile journal files will be opened, excluding those which - are stored on persistent storage. - <constant>SD_JOURNAL_SYSTEM</constant> will cause journal files of - system services and the kernel (in opposition to user session - processes) to be opened. - <constant>SD_JOURNAL_CURRENT_USER</constant> will cause journal - files of the current user to be opened. If neither - <constant>SD_JOURNAL_SYSTEM</constant> nor - <constant>SD_JOURNAL_CURRENT_USER</constant> are specified, all - journal file types 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. The only flags parameter accepted by this call is - <constant>SD_JOURNAL_OS_ROOT</constant>. If specified, the journal files are searched below the usual - <filename>/var/log/journal</filename> and <filename>/run/log/journal</filename> relative to the specified path, - instead of directly beneath it.</para> - - <para><function>sd_journal_open_directory_fd()</function> is similar to - <function>sd_journal_open_directory()</function>, but takes a file descriptor referencing a directory in the file - system instead of an absolute file system path.</para> - - <para><function>sd_journal_open_files()</function> is similar to <function>sd_journal_open()</function> but takes a - <constant>NULL</constant>-terminated list of file paths to open. All files 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. Please note that in the case of a live journal, this function is only useful for - debugging, because individual journal files can be rotated at any moment, and the opening of specific files is - inherently racy.</para> - - <para><function>sd_journal_open_files_fd()</function> is similar to <function>sd_journal_open_files()</function> - but takes an array of open file descriptors that must reference journal files, instead of an array of file system - paths. Pass the array of file descriptors as second argument, and the number of array entries in the third. The - flags parameter must be passed as 0.</para> - - <para><varname>sd_journal</varname> objects cannot be used in the - child after a fork. Functions which take a journal object as an - argument (<function>sd_journal_next()</function> and others) will - return <constant>-ECHILD</constant> after a fork. - </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 of 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>, - <function>sd_journal_open_directory()</function>, and - <function>sd_journal_open_files()</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 a shared library, which can be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><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>, - <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_journal_print.xml b/man/sd_journal_print.xml deleted file mode 100644 index 17fdc9c1f2..0000000000 --- a/man/sd_journal_print.xml +++ /dev/null @@ -1,260 +0,0 @@ -<?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 project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry> - or - <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - The priority value is one of - <constant>LOG_EMERG</constant>, - <constant>LOG_ALERT</constant>, - <constant>LOG_CRIT</constant>, - <constant>LOG_ERR</constant>, - <constant>LOG_WARNING</constant>, - <constant>LOG_NOTICE</constant>, - <constant>LOG_INFO</constant>, - <constant>LOG_DEBUG</constant>, as defined in - <filename>syslog.h</filename>, see - <citerefentry project='man-pages'><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 - <varname>va_list</varname> (see - <citerefentry project='man-pages'><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 <constant>NULL</constant>. 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 - <varname>struct iovec</varname> (as defined in - <filename>uio.h</filename>, see - <citerefentry project='man-pages'><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 project='die-net'><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 project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - If the message string is passed as <constant>NULL</constant> 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 - <constant>LOG_ERR</constant> (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 project='man-pages'><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, filenames, and - functions as metadata 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 project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry> - variable itself is not altered.</para> - - <para>If - <citerefentry><refentrytitle>systemd-journald</refentrytitle><manvolnum>8</manvolnum></citerefentry> - is not running (the socket is not present), those functions do - nothing, and also return 0.</para> - </refsect1> - - <refsect1> - <title>Async signal safety</title> - <para><function>sd_journal_sendv()</function> is "async signal - safe" in the meaning of - <citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>. - </para> - - <para><function>sd_journal_print</function>, - <function>sd_journal_printv</function>, - <function>sd_journal_send</function>, and - <function>sd_journal_perror</function> are - not async signal safe.</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 a shared library, which can be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><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 project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>perror</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_journal_query_unique.xml b/man/sd_journal_query_unique.xml deleted file mode 100644 index dbff55c105..0000000000 --- a/man/sd_journal_query_unique.xml +++ /dev/null @@ -1,212 +0,0 @@ -<?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 '='. Note - that this call is subject to the data field size threshold as - controlled by - <function>sd_journal_set_data_threshold()</function>.</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> - - <para>To enumerate all field names currently in use (and thus all suitable field parameters for - <function>sd_journal_query_unique()</function>), use the - <citerefentry><refentrytitle>sd_journal_enumerate_fields</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call.</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 a shared library, which can be compiled and linked to - with the - <constant>libsystemd</constant> <citerefentry project='die-net'><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_enumerate_fields</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 deleted file mode 100644 index d74c2d5bbc..0000000000 --- a/man/sd_journal_seek_head.xml +++ /dev/null @@ -1,172 +0,0 @@ -<?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>Similarly, <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. - <constant>CLOCK_MONOTONIC</constant>. 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. <constant>CLOCK_REALTIME</constant>. 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 a shared library, which can - be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><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 deleted file mode 100644 index 2ea7731b48..0000000000 --- a/man/sd_journal_stream_fd.xml +++ /dev/null @@ -1,163 +0,0 @@ -<?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 standard output or standard - error 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 - <constant>LOG_EMERG</constant>, <constant>LOG_ALERT</constant>, - <constant>LOG_CRIT</constant>, <constant>LOG_ERR</constant>, - <constant>LOG_WARNING</constant>, <constant>LOG_NOTICE</constant>, - <constant>LOG_INFO</constant>, <constant>LOG_DEBUG</constant>, as - defined in <filename>syslog.h</filename>, see - <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for details. The third argument is a boolean: if true kernel-style - log level prefixes (such as <constant>SD_WARNING</constant>) 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 a shared library, which can be compiled and linked to - with the - <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> - </refsect1> - - <refsect1> - <title>Examples</title> - - <para>Creating a log stream suitable for - <citerefentry project='man-pages'><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 project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='man-pages'><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 deleted file mode 100644 index 93bf8d853f..0000000000 --- a/man/sd_listen_fds.xml +++ /dev/null @@ -1,257 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <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_with_names</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> - - <funcprototype> - <funcdef>int <function>sd_listen_fds_with_names</function></funcdef> - <paramdef>int <parameter>unset_environment</parameter></paramdef> - <paramdef>char*** <parameter>names</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_listen_fds()</function> may be invoked by a - daemon to check for file descriptors passed by the service manager as - part of the socket-based activation logic. It returns the number - of received file descriptors. If no file descriptors have been - received, zero is returned. The first file descriptor may be found - at file descriptor number 3 - (i.e. <constant>SD_LISTEN_FDS_START</constant>), the remaining - descriptors follow at 4, 5, 6, ..., if any.</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 unit file (see - <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details). 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> - - <para>If multiple socket units activate the same service, the order - of the file descriptors passed to its main process is undefined. - If additional file descriptors have been passed to the service - manager using - <citerefentry><refentrytitle>sd_pid_notify_with_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>'s - <literal>FDSTORE=1</literal> messages, these file descriptors are - passed last, in arbitrary order, and with duplicates - removed.</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> and - <varname>$LISTEN_FDNAMES</varname> environment variables before - returning (regardless of whether the function call itself - succeeded or not). Further calls to - <function>sd_listen_fds()</function> will then return zero, but the - variables are no longer inherited by child processes.</para> - - <para><function>sd_listen_fds_with_names()</function> is like - <function>sd_listen_fds()</function>, but optionally also returns - an array of strings with identification names for the passed file - descriptors, if that is available and the - <parameter>names</parameter> parameter is non-NULL. This - information is read from the <varname>$LISTEN_FDNAMES</varname> - variable, which may contain a colon-separated list of names. For - socket-activated services, these names may be configured with the - <varname>FileDescriptorName=</varname> setting in socket unit - files, see - <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. For file descriptors pushed into the file descriptor - store (see above), the name is set via the - <varname>FDNAME=</varname> field transmitted via - <function>sd_pid_notify_with_fds()</function>. The primary usecase - for these names are services which accept a variety of file - descriptors which are not recognizable with functions like - <function>sd_is_socket()</function> alone, and thus require - identification via a name. It is recommended to rely on named file - descriptors only if identification via - <function>sd_is_socket()</function> and related calls is not - sufficient. Note that the names used are not unique in any - way. The returned array of strings has as many entries as file - descriptors have been received, plus a final NULL pointer - terminating the array. The caller needs to free the array itself - and each of its elements with libc's <function>free()</function> - call after use. If the <parameter>names</parameter> parameter is - NULL, the call is entirely equivalent to - <function>sd_listen_fds()</function>.</para> - - <para>Under specific conditions, the following automatic file - descriptor names are returned: - - <table> - <title> - <command>Special names</command> - </title> - - <tgroup cols='2'> - <thead> - <row> - <entry>Name</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry><literal>unknown</literal></entry> - <entry>The process received no name for the specific file descriptor from the service manager.</entry> - </row> - - <row> - <entry><literal>stored</literal></entry> - <entry>The file descriptor originates in the service manager's per-service file descriptor store, and the <varname>FDNAME=</varname> field was absent when the file descriptor was submitted to the service manager.</entry> - </row> - - <row> - <entry><literal>connection</literal></entry> - <entry>The service was activated in per-connection style using <varname>Accept=yes</varname> in the socket unit file, and the file descriptor is the connection socket.</entry> - </row> - </tbody> - </tgroup> - </table> - </para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On failure, these calls 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> - - <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> - - <para>Internally, <function>sd_listen_fds()</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. <function>sd_listen_fds_with_names()</function> does the - same but also parses <varname>$LISTEN_FDNAMES</varname> if - set.</para> - </refsect1> - - <refsect1> - <title>Environment</title> - - <variablelist class='environment-variables'> - <varlistentry> - <term><varname>$LISTEN_PID</varname></term> - <term><varname>$LISTEN_FDS</varname></term> - <term><varname>$LISTEN_FDNAMES</varname></term> - - <listitem><para>Set by the service manager for supervised - processes that use socket-based activation. This environment - variable specifies the data - <function>sd_listen_fds()</function> and - <function>sd_listen_fds_with_names()</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>sd_pid_notify_with_fds</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 deleted file mode 100644 index 5625ab9207..0000000000 --- a/man/sd_login_monitor_new.xml +++ /dev/null @@ -1,287 +0,0 @@ -<?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" conditional='HAVE_PAM'> - - <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_unrefp</refname> - <refname>sd_login_monitor_flush</refname> - <refname>sd_login_monitor_get_fd</refname> - <refname>sd_login_monitor_get_events</refname> - <refname>sd_login_monitor_get_timeout</refname> - <refname>sd_login_monitor</refname> - <refpurpose>Monitor login sessions, seats, users and virtual machines/containers</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>void <function>sd_login_monitor_unrefp</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> - - <funcprototype> - <funcdef>int <function>sd_login_monitor_get_events</function></funcdef> - <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_login_monitor_get_timeout</function></funcdef> - <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef> - <paramdef>uint64_t *<parameter>timeout_usec</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_login_monitor_new()</function> may be used to - monitor login sessions, users, seats, and virtual - machines/containers. 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, seat or virtual machine/container - 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), <literal>uid</literal> (to get only notifications - when a user changes state in respect to logins) or - <literal>machine</literal> (to get only notifications when a - virtual machine or container is started or stopped). If - notifications shall be generated in all these conditions, - <constant>NULL</constant> 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_unrefp()</function> is similar to - <function>sd_login_monitor_unref()</function> but takes a pointer - to a pointer to an <type>sd_login_monitor</type> object. This call - is useful in conjunction with GCC's and LLVM's <ulink - url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up - Variable Attribute</ulink>. Note that this function is defined as - inline function. Use a declaration like the following, in order to - allocate a login monitor object that is freed automatically as the - code block is left:</para> - - <programlisting>{ - __attribute__((cleanup(sd_login_monitor_unrefp)) sd_login_monitor *m = NULL; - int r; - … - r = sd_login_monitor_default(&m); - if (r < 0) - fprintf(stderr, "Failed to allocate login monitor object: %s\n", strerror(-r)); - … -}</programlisting> - - <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_unref()</function> and - <function>sd_login_monitor_unrefp()</function> execute no - operation if the passed in monitor object is - <constant>NULL</constant>.</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 the events mask - returned by <function>sd_login_monitor_get_events()</function>. It - should pass a timeout value as returned by - <function>sd_login_monitor_get_timeout()</function>. 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> - - <para><function>sd_login_monitor_get_events()</function> will - return the <function>poll()</function> mask to wait for. This - function will return a combination of <constant>POLLIN</constant>, - <constant>POLLOUT</constant> and similar to fill into the - <literal>.events</literal> field of <varname>struct - pollfd</varname>.</para> - - <para><function>sd_login_monitor_get_timeout()</function> will - return a timeout value for usage in <function>poll()</function>. - This returns a value in microseconds since the epoch of - <constant>CLOCK_MONOTONIC</constant> for timing out - <function>poll()</function> in <varname>timeout_usec</varname>. - See - <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for details about <constant>CLOCK_MONOTONIC</constant>. If there - is no timeout to wait for this will fill in <constant>(uint64_t) - -1</constant> instead. Note that <function>poll()</function> takes - a relative timeout in milliseconds rather than an absolute timeout - in microseconds. To convert the absolute 'µs' timeout into - relative 'ms', use code like the following:</para> - - <programlisting>uint64_t t; -int msec; -sd_login_monitor_get_timeout(m, &t); -if (t == (uint64_t) -1) - msec = -1; -else { - struct timespec ts; - uint64_t n; - clock_getttime(CLOCK_MONOTONIC, &ts); - n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000; - msec = t > n ? (int) ((t - n + 999) / 1000) : 0; -}</programlisting> - - <para>The code above does not do any error checking for brevity's - sake. The calculated <varname>msec</varname> integer can be passed - directly as <function>poll()</function>'s timeout - parameter.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, - <function>sd_login_monitor_new()</function>, - <function>sd_login_monitor_flush()</function> and - <function>sd_login_monitor_get_timeout()</function> - return 0 or a positive integer. On success, - <function>sd_login_monitor_get_fd()</function> returns - a Unix file descriptor. On success, - <function>sd_login_monitor_get_events()</function> - returns a combination of <constant>POLLIN</constant>, - <constant>POLLOUT</constant> and suchlike. On failure, - these calls return a negative errno-style error - code.</para> - - <para><function>sd_login_monitor_unref()</function> - always returns <constant>NULL</constant>.</para> - </refsect1> - - <refsect1> - <title>Errors</title> - - <para>Returned errors may indicate the following problems:</para> - - <variablelist> - - <varlistentry> - <term><constant>-EINVAL</constant></term> - - <listitem><para>An input parameter was invalid (out of range, - or NULL, where that is not accepted). The specified category to - watch is not known.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ENOMEM</constant></term> - - <listitem><para>Memory allocation failed.</para></listitem> - </varlistentry> - </variablelist> - </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>, - <function>sd_login_monitor_get_fd()</function>, - <function>sd_login_monitor_get_events()</function> and - <function>sd_login_monitor_get_timeout()</function> - interfaces are available as a shared library, which can be - compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><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>, - <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>, - <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_machine_get_class.xml b/man/sd_machine_get_class.xml deleted file mode 100644 index ef604139da..0000000000 --- a/man/sd_machine_get_class.xml +++ /dev/null @@ -1,152 +0,0 @@ -<?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 2014 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_machine_get_class"> - - <refentryinfo> - <title>sd_machine_get_class</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_machine_get_class</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_machine_get_class</refname> - <refname>sd_machine_get_ifindices</refname> - <refpurpose>Determine the class and network interface indices of a - locally running virtual machine or container.</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_machine_get_class</function></funcdef> - <paramdef>const char* <parameter>machine</parameter></paramdef> - <paramdef>char **<parameter>class</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_machine_get_ifindices</function></funcdef> - <paramdef>const char* <parameter>machine</parameter></paramdef> - <paramdef>int **<parameter>ifindices</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_machine_get_class()</function> may be used to - determine the class of a locally running virtual machine or - container that is registered with - <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. - The string returned is either <literal>vm</literal> or - <literal>container</literal>. The returned string needs to be - freed with the libc <citerefentry - project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use.</para> - - <para><function>sd_machine_get_ifindices()</function> may be used - to determine the numeric indices of the network interfaces on the - host that are pointing towards the specified locally running - virtual machine or container that is registered with - <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. - The returned array needs to be freed with the libc <citerefentry - project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use.</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>Errors</title> - - <para>Returned errors may indicate the following problems:</para> - - <variablelist> - - <varlistentry> - <term><constant>-ENXIO</constant></term> - - <listitem><para>The specified machine does not exist or is currently not running.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><constant>-EINVAL</constant></term> - - <listitem><para>An input parameter was invalid (out of range, - or NULL, where that is not accepted).</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ENOMEM</constant></term> - - <listitem><para>Memory allocation failed.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>The <function>sd_machine_get_class()</function> and - <function>sd_machine_get_ifindices()</function> interfaces are - available as a shared library, which can be compiled and linked to - with the - <constant>libsystemd</constant> <citerefentry project='die-net'><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>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_pid_get_machine_name</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_notify.xml b/man/sd_notify.xml deleted file mode 100644 index bd6cfdcd29..0000000000 --- a/man/sd_notify.xml +++ /dev/null @@ -1,399 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <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> - <refname>sd_pid_notify</refname> - <refname>sd_pid_notifyf</refname> - <refname>sd_pid_notify_with_fds</refname> - <refpurpose>Notify service manager about start-up completion and other service 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> - - <funcprototype> - <funcdef>int <function>sd_pid_notify</function></funcdef> - <paramdef>pid_t <parameter>pid</parameter></paramdef> - <paramdef>int <parameter>unset_environment</parameter></paramdef> - <paramdef>const char *<parameter>state</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_pid_notifyf</function></funcdef> - <paramdef>pid_t <parameter>pid</parameter></paramdef> - <paramdef>int <parameter>unset_environment</parameter></paramdef> - <paramdef>const char *<parameter>format</parameter></paramdef> - <paramdef>...</paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_pid_notify_with_fds</function></funcdef> - <paramdef>pid_t <parameter>pid</parameter></paramdef> - <paramdef>int <parameter>unset_environment</parameter></paramdef> - <paramdef>const char *<parameter>state</parameter></paramdef> - <paramdef>const int *<parameter>fds</parameter></paramdef> - <paramdef>unsigned <parameter>n_fds</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - <para><function>sd_notify()</function> may be called by a service - to notify the service manager about state 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 of 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 service manager that service startup - is finished. This is only used by systemd if the service - definition file has Type=notify set. Since there is little - value in signaling non-readiness, the only value services - should send is <literal>READY=1</literal> (i.e. - <literal>READY=0</literal> is not defined).</para></listitem> - </varlistentry> - - <varlistentry> - <term>RELOADING=1</term> - - <listitem><para>Tells the service manager that the service is - reloading its configuration. This is useful to allow the - service manager to track the service's internal state, and - present it to the user. Note that a service that sends this - notification must also send a <literal>READY=1</literal> - notification when it completed reloading its - configuration.</para></listitem> - </varlistentry> - - <varlistentry> - <term>STOPPING=1</term> - - <listitem><para>Tells the service manager that the service is - beginning its shutdown. This is useful to allow the service - manager to track the service's internal state, and present it - to the user.</para></listitem> - </varlistentry> - - <varlistentry> - <term>STATUS=...</term> - - <listitem><para>Passes a single-line UTF-8 status string back - to the service manager that describes the service 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: <literal>STATUS=Completed 66% of file - system check...</literal></para></listitem> - </varlistentry> - - <varlistentry> - <term>ERRNO=...</term> - - <listitem><para>If a service fails, the errno-style error - code, formatted as string. Example: <literal>ERRNO=2</literal> - for ENOENT.</para></listitem> - </varlistentry> - - <varlistentry> - <term>BUSERROR=...</term> - - <listitem><para>If a service fails, the D-Bus error-style - error code. Example: - <literal>BUSERROR=org.freedesktop.DBus.Error.TimedOut</literal></para></listitem> - </varlistentry> - - <varlistentry> - <term>MAINPID=...</term> - - <listitem><para>The main process ID (PID) of the service, in - case the service manager did not fork off the process itself. - Example: <literal>MAINPID=4711</literal></para></listitem> - </varlistentry> - - <varlistentry> - <term>WATCHDOG=1</term> - - <listitem><para>Tells the service manager 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 information how to enable this functionality and - <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for the details of how the service can check whether the - watchdog is enabled. </para></listitem> - </varlistentry> - - - <varlistentry> - <term>FDSTORE=1</term> - - <listitem><para>Stores additional file descriptors in the - service manager. File descriptors sent this way will be - maintained per-service by the service manager and be passed - again using the usual file descriptor passing logic on the - next invocation of the service (see - <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>). - This is useful for implementing service restart schemes where - services serialize their state to <filename>/run</filename>, - push their file descriptors to the system manager, and are - then restarted, retrieving their state again via socket - passing and <filename>/run</filename>. Note that the service - manager will accept messages for a service only if - <varname>FileDescriptorStoreMax=</varname> is set to non-zero - for it (defaults to zero). See - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. Multiple arrays of file descriptors may be sent - in separate messages, in which case the arrays are combined. - Note that the service manager removes duplicate file - descriptors before passing them to the service. Use - <function>sd_pid_notify_with_fds()</function> to send messages - with <literal>FDSTORE=1</literal>, see - below.</para></listitem> - </varlistentry> - - <varlistentry> - <term>FDNAME=...</term> - - <listitem><para>When used in combination with - <varname>FDSTORE=1</varname>, specifies a name for the - submitted file descriptors. This name is passed to the service - during activation, and may be queried using - <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>. File - descriptors submitted without this field set, will implicitly - get the name <literal>stored</literal> assigned. Note that, if - multiple file descriptors are submitted at once, the specified - name will be assigned to all of them. In order to assign - different names to submitted file descriptors, submit them in - separate invocations of - <function>sd_pid_notify_with_fds()</function>. The name may - consist of any ASCII character, but must not contain control - characters or <literal>:</literal>. It may not be longer than - 255 characters. If a submitted name does not follow these - restrictions, it is ignored.</para></listitem> - </varlistentry> - - </variablelist> - - <para>It is recommended to prefix variable names that are not - listed above with <varname>X_</varname> to avoid namespace - clashes.</para> - - <para>Note that systemd will accept status data sent from a - service 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> - - <para><function>sd_pid_notify()</function> and - <function>sd_pid_notifyf()</function> are similar to - <function>sd_notify()</function> and - <function>sd_notifyf()</function> but take a process ID (PID) to - use as originating PID for the message as first argument. This is - useful to send notification messages on behalf of other processes, - provided the appropriate privileges are available. If the PID - argument is specified as 0, the process ID of the calling process - is used, in which case the calls are fully equivalent to - <function>sd_notify()</function> and - <function>sd_notifyf()</function>.</para> - - <para><function>sd_pid_notify_with_fds()</function> is similar to - <function>sd_pid_notify()</function> but takes an additional array - of file descriptors. These file descriptors are sent along the - notification message to the service manager. This is particularly - useful for sending <literal>FDSTORE=1</literal> messages, as - described above. The additional arguments are a pointer to the - file descriptor array plus the number of file descriptors in the - array. If the number of file descriptors is passed as 0, the call - is fully equivalent to <function>sd_pid_notify()</function>, i.e. - no file descriptors are passed. Note that sending file descriptors - to the service manager on messages that do not expect them (i.e. - without <literal>FDSTORE=1</literal>) they are immediately closed - on reception.</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 do not, it is generally recommended to ignore the - return value of this call.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> - - <para>These functions send a single datagram with the - state string as payload to the <constant>AF_UNIX</constant> socket - referenced in the <varname>$NOTIFY_SOCKET</varname> environment - variable. If the first character of - <varname>$NOTIFY_SOCKET</varname> is <literal>@</literal>, the - string is understood as Linux abstract namespace socket. The - datagram is accompanied by the process credentials of the sending - service, using SCM_CREDENTIALS.</para> - </refsect1> - - <refsect1> - <title>Environment</title> - - <variablelist class='environment-variables'> - <varlistentry> - <term><varname>$NOTIFY_SOCKET</varname></term> - - <listitem><para>Set by the service manager 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 service finished starting up, it might issue the - following call to notify the service manager:</para> - - <programlisting>sd_notify(0, "READY=1");</programlisting> - </example> - - <example> - <title>Extended Start-up Notification</title> - - <para>A service 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 service 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> - - <example> - <title>Store a File Descriptor in the Service Manager</title> - - <para>To store an open file descriptor in the service manager, - in order to continue operation after a service restart without - losing state, use <literal>FDSTORE=1</literal>:</para> - - <programlisting>sd_pid_notify_with_fds(0, 0, "FDSTORE=1\nFDNAME=foobar", &fd, 1);</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>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_watchdog_enabled</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 deleted file mode 100644 index 806cff34e4..0000000000 --- a/man/sd_pid_get_session.xml +++ /dev/null @@ -1,359 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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" conditional='HAVE_PAM'> - - <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_user_unit</refname> - <refname>sd_pid_get_owner_uid</refname> - <refname>sd_pid_get_machine_name</refname> - <refname>sd_pid_get_slice</refname> - <refname>sd_pid_get_user_slice</refname> - <refname>sd_pid_get_cgroup</refname> - <refname>sd_peer_get_session</refname> - <refname>sd_peer_get_unit</refname> - <refname>sd_peer_get_user_unit</refname> - <refname>sd_peer_get_owner_uid</refname> - <refname>sd_peer_get_machine_name</refname> - <refname>sd_peer_get_slice</refname> - <refname>sd_peer_get_user_slice</refname> - <refname>sd_peer_get_cgroup</refname> - <refpurpose>Determine session, unit, owner of a session, - container/VM or slice of a specific PID or socket - peer</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_user_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> - - <funcprototype> - <funcdef>int <function>sd_pid_get_machine_name</function></funcdef> - <paramdef>pid_t <parameter>pid</parameter></paramdef> - <paramdef>char **<parameter>name</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_pid_get_slice</function></funcdef> - <paramdef>pid_t <parameter>pid</parameter></paramdef> - <paramdef>char **<parameter>slice</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_pid_get_user_slice</function></funcdef> - <paramdef>pid_t <parameter>pid</parameter></paramdef> - <paramdef>char **<parameter>slice</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_pid_get_cgroup</function></funcdef> - <paramdef>pid_t <parameter>pid</parameter></paramdef> - <paramdef>char **<parameter>cgroup</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_peer_get_session</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>char **<parameter>session</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_peer_get_unit</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>char **<parameter>unit</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_peer_get_user_unit</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>char **<parameter>unit</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_peer_get_owner_uid</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>uid_t *<parameter>uid</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_peer_get_machine_name</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>char **<parameter>name</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_peer_get_slice</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>char **<parameter>slice</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_peer_get_user_slice</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>char **<parameter>slice</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_peer_get_cgroup</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>char **<parameter>cgroup</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 with - -ENODATA. The returned string needs to be freed with the libc - <citerefentry - project='man-pages'><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 system unit (i.e. system service or scope - unit) identifier of a process identified by the specified PID. The - unit name is a short string, suitable for usage in file system - paths. Note that not all processes are part of a system - unit/service (e.g. user processes, or kernel threads). For - processes not being part of a systemd system unit, this function - will fail with -ENODATA. (More specifically, this call will not - work for kernel threads.) The returned string needs to be freed - with the libc <citerefentry - project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use.</para> - - <para><function>sd_pid_get_user_unit()</function> may be used to - determine the systemd user unit (i.e. user service or scope unit) - identifier of a process identified by the specified PID. This is - similar to <function>sd_pid_get_unit()</function>, but applies to - user units instead of system units.</para> - - <para><function>sd_pid_get_owner_uid()</function> may be used to - determine the Unix UID (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, whereas - <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 with -ENODATA.</para> - - <para><function>sd_pid_get_machine_name()</function> may be used - to determine the name of the VM or container is a member of. The - machine name is a short string, suitable for usage in file system - paths. The returned string needs to be freed with the libc - <citerefentry - project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use. For processes not part of a VM or containers, this - function fails with -ENODATA.</para> - - <para><function>sd_pid_get_slice()</function> may be used to - determine the slice unit the process is a member of. See - <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details about slices. The returned string needs to be freed - with the libc - <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use.</para> - - <para>Similarly, <function>sd_pid_get_user_slice()</function> - returns the user slice (as managed by the user's systemd instance) - of a process.</para> - - <para><function>sd_pid_get_cgroup()</function> returns the control - group path of the specified process, relative to the root of the - hierarchy. Returns the path without trailing slash, except for - processes located in the root control group, where "/" is - returned. To find the actual control group path in the file system, - the returned path needs to be prefixed with - <filename>/sys/fs/cgroup/</filename> (if the unified control group - setup is used), or - <filename>/sys/fs/cgroup/<replaceable>HIERARCHY</replaceable>/</filename> - (if the legacy multi-hierarchy control group setup is used).</para> - - <para>If the <varname>pid</varname> parameter of any of these - functions is passed as 0, the operation is executed for the - calling process.</para> - - <para>The <function>sd_peer_get_session()</function>, - <function>sd_peer_get_unit()</function>, - <function>sd_peer_get_user_unit()</function>, - <function>sd_peer_get_owner_uid()</function>, - <function>sd_peer_get_machine_name()</function>, - <function>sd_peer_get_slice()</function>, - <function>sd_peer_get_user_slice()</function> and - <function>sd_peer_get_cgroup()</function> calls operate similar to - their PID counterparts, but operate on a connected AF_UNIX socket - and retrieve information about the connected peer process. Note - that these fields are retrieved via <filename>/proc</filename>, - and hence are not suitable for authorization purposes, as they are - subject to races.</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>Errors</title> - - <para>Returned errors may indicate the following problems:</para> - - <variablelist> - - <varlistentry> - <term><constant>-ESRCH</constant></term> - - <listitem><para>The specified PID does not refer to a running - process.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><constant>-BADF</constant></term> - - <listitem><para>The specified socket file descriptor was - invalid.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ENODATA</constant></term> - - <listitem><para>The given field is not specified for the described - process or peer.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><constant>-EINVAL</constant></term> - - <listitem><para>An input parameter was invalid (out of range, - or NULL, where that is not accepted).</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ENOMEM</constant></term> - - <listitem><para>Memory allocation failed.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>The <function>sd_pid_get_session()</function>, - <function>sd_pid_get_unit()</function>, - <function>sd_pid_get_user_unit()</function>, - <function>sd_pid_get_owner_uid()</function>, - <function>sd_pid_get_machine_name()</function>, - <function>sd_pid_get_slice()</function>, - <function>sd_pid_get_user_slice()</function>, - <function>sd_peer_get_session()</function>, - <function>sd_peer_get_unit()</function>, - <function>sd_peer_get_user_unit()</function>, - <function>sd_peer_get_owner_uid()</function>, - <function>sd_peer_get_machine_name()</function>, - <function>sd_peer_get_slice()</function> and - <function>sd_peer_get_user_slice()</function> interfaces are - available as a shared library, which can be compiled and linked to - with the <constant>libsystemd</constant> <citerefentry - project='die-net'><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>, - <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_seat_get_active.xml b/man/sd_seat_get_active.xml deleted file mode 100644 index c5e6ddab02..0000000000 --- a/man/sd_seat_get_active.xml +++ /dev/null @@ -1,212 +0,0 @@ -<?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" conditional='HAVE_PAM'> - - <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> - <refname>sd_seat_can_tty</refname> - <refname>sd_seat_can_graphical</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 int *<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 <constant>NULL</constant>, - in case only one of the parameters shall be queried. The returned - string needs to be freed with the libc - <citerefentry project='man-pages'><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 (<constant>NULL</constant> 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 - <constant>NULL</constant> 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 project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use. Note that instead of an empty array - <constant>NULL</constant> 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 <varname>seat</varname> parameter of any of these - functions is passed as <constant>NULL</constant>, 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>Errors</title> - - <para>Returned errors may indicate the following problems:</para> - - <variablelist> - - <varlistentry> - <term><constant>-ENODATA</constant></term> - - <listitem><para>The given field is not specified for the described - seat.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ENXIO</constant></term> - - <listitem><para>The specified seat is unknown.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><constant>-EINVAL</constant></term> - - <listitem><para>An input parameter was invalid (out of range, - or NULL, where that is not accepted).</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ENOMEM</constant></term> - - <listitem><para>Memory allocation failed.</para></listitem> - </varlistentry> - </variablelist> - </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_graphical()</function> interfaces are - available as a shared library, which can be compiled and linked to - with the - <constant>libsystemd</constant> <citerefentry project='die-net'><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 deleted file mode 100644 index a6076b177a..0000000000 --- a/man/sd_session_is_active.xml +++ /dev/null @@ -1,359 +0,0 @@ -<?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" conditional='HAVE_PAM'> - - <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_is_remote</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_desktop</refname> - <refname>sd_session_get_display</refname> - <refname>sd_session_get_tty</refname> - <refname>sd_session_get_vt</refname> - <refname>sd_session_get_remote_host</refname> - <refname>sd_session_get_remote_user</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_is_remote</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_desktop</function></funcdef> - <paramdef>const char *<parameter>session</parameter></paramdef> - <paramdef>char **<parameter>desktop</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> - - <funcprototype> - <funcdef>int <function>sd_session_get_remote_host</function></funcdef> - <paramdef>const char *<parameter>session</parameter></paramdef> - <paramdef>char **<parameter>remote_host</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_session_get_remote_user</function></funcdef> - <paramdef>const char *<parameter>session</parameter></paramdef> - <paramdef>char **<parameter>remote_user</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_session_get_tty</function></funcdef> - <paramdef>const char *<parameter>session</parameter></paramdef> - <paramdef>char **<parameter>tty</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_session_get_vt</function></funcdef> - <paramdef>const char *<parameter>session</parameter></paramdef> - <paramdef>unsigned int *<parameter>vt</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_is_remote()</function> may be used to - determine whether the session identified by the specified session - identifier is a remote session (i.e. its remote host is known) 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 project='man-pages'><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 project='man-pages'><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 project='man-pages'><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>wayland</literal>, - <literal>tty</literal>, <literal>mir</literal> or - <literal>unspecified</literal> and needs to be freed with the libc - <citerefentry project='man-pages'><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>, - <literal>lock-screen</literal>, or <literal>background</literal> - and needs to be freed with the libc - <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use.</para> - - <para><function>sd_session_get_desktop()</function> may be used to - determine the brand of the desktop running on the session - identified by the specified session identifier. This field can be - set freely by desktop environments and does not follow any special - formatting. However, desktops are strongly recommended to use the - same identifiers and capitalization as for - <varname>$XDG_CURRENT_DESKTOP</varname>, as defined by the <ulink - url="http://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop - Entry Specification</ulink>. The returned string needs to be freed - with the libc - <citerefentry project='man-pages'><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 needs to be - freed with the libc - <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use.</para> - - <para><function>sd_session_get_remote_host()</function> may be - used to determine the remote hostname of the session identified by - the specified session identifier. The returned string needs to be - freed with the libc - <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use.</para> - - <para><function>sd_session_get_remote_user()</function> may be - used to determine the remote username of the session identified by - the specified session identifier. The returned string needs to be - freed with the libc - <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use. Note that this value is rarely known to the - system, and even then should not be relied on.</para> - - <para><function>sd_session_get_tty()</function> may be used to - determine the TTY device of the session identified by the - specified session identifier. The returned string needs to be - freed with the libc - <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use.</para> - - <para><function>sd_session_get_vt()</function> may be used to - determine the VT number of the session identified by the specified - session identifier. This function will return an error if the seat - does not support VTs.</para> - - <para>If the <varname>session</varname> parameter of any of these - functions is passed as <constant>NULL</constant>, 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> and - <function>sd_session_is_remote()</function> return 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>, - <function>sd_session_get_display()</function>, - <function>sd_session_get_remote_user()</function>, - <function>sd_session_get_remote_host()</function> and - <function>sd_session_get_tty()</function> return 0 or - a positive integer. On failure, these calls return a - negative errno-style error code.</para> - </refsect1> - - <refsect1> - <title>Errors</title> - - <para>Returned errors may indicate the following problems:</para> - - <variablelist> - - <varlistentry> - <term><constant>-ENXIO</constant></term> - - <listitem><para>The specified session does not exist.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ENODATA</constant></term> - - <listitem><para>The given field is not specified for the described - session.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><constant>-EINVAL</constant></term> - - <listitem><para>An input parameter was invalid (out of range, - or NULL, where that is not accepted).</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ENOMEM</constant></term> - - <listitem><para>Memory allocation failed.</para></listitem> - </varlistentry> - </variablelist> - </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>, - <function>sd_session_get_display()</function>, - <function>sd_session_get_remote_host()</function>, - <function>sd_session_get_remote_user()</function> and - <function>sd_session_get_tty()</function> - interfaces are available as a shared library, which can - be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><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 deleted file mode 100644 index 130af761da..0000000000 --- a/man/sd_uid_get_state.xml +++ /dev/null @@ -1,230 +0,0 @@ -<?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" conditional='HAVE_PAM'> - - <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> - <refname>sd_uid_get_display</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> - - <funcprototype> - <funcdef>int <function>sd_uid_get_display</function></funcdef> - <paramdef>uid_t <parameter>uid</parameter></paramdef> - <paramdef>char **<parameter>session</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 project='man-pages'><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 - <constant>NULL</constant> terminated string array of session - identifiers in <parameter>sessions</parameter> which needs to be - freed by the caller with the libc - <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use, including all the strings referenced. If the - string array parameter is passed as <constant>NULL</constant>, 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 <constant>NULL</constant> may be returned and should be - considered equivalent to an empty array.</para> - - <para>Similarly, <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> - - <para><function>sd_uid_get_display()</function> returns the name - of the "primary" session of a user. If the user has graphical - sessions, it will be the oldest graphical session. Otherwise, it - will be the oldest open session.</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. - <function>sd_uid_get_display()</function> returns a non-negative - code on success. On failure, these calls return a negative - errno-style error code.</para> - </refsect1> - - <refsect1> - <title>Errors</title> - - <para>Returned errors may indicate the following problems:</para> - - <variablelist> - - <varlistentry> - <term><constant>-ENODATA</constant></term> - - <listitem><para>The given field is not specified for the described - user.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ENXIO</constant></term> - - <listitem><para>The specified seat is unknown.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><constant>-EINVAL</constant></term> - - <listitem><para>An input parameter was invalid (out of range, - or NULL, where that is not accepted). This is also returned if - the passed user ID is 0xFFFF or 0xFFFFFFFF, which are - undefined on Linux.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ENOMEM</constant></term> - - <listitem><para>Memory allocation failed.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>Functions described here are available as a shared library, - and can be compiled and linked to using the - <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - entry.</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/sd_watchdog_enabled.xml b/man/sd_watchdog_enabled.xml deleted file mode 100644 index 3de9899453..0000000000 --- a/man/sd_watchdog_enabled.xml +++ /dev/null @@ -1,169 +0,0 @@ -<?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 2013 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_watchdog_enabled" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd_watchdog_enabled</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_watchdog_enabled</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_watchdog_enabled</refname> - <refpurpose>Check whether the service manager expects watchdog keep-alive notifications from a service</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_watchdog_enabled</function></funcdef> - <paramdef>int <parameter>unset_environment</parameter></paramdef> - <paramdef>uint64_t *<parameter>usec</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - <para><function>sd_watchdog_enabled()</function> may be called by - a service to detect whether the service manager expects regular - keep-alive watchdog notification events from it, and the timeout - after which the manager will act on the service if it did not get - such a notification.</para> - - <para>If the <varname>$WATCHDOG_USEC</varname> environment - variable is set, and the <varname>$WATCHDOG_PID</varname> variable - is unset or set to the PID of the current process, the service - manager expects notifications from this process. The manager will - usually terminate a service when it does not get a notification - message within the specified time after startup and after each - previous message. It is recommended that a daemon sends a - keep-alive notification message to the service manager every half - of the time returned here. Notification messages may be sent with - <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> - with a message string of <literal>WATCHDOG=1</literal>.</para> - - <para>If the <parameter>unset_environment</parameter> parameter is - non-zero, <function>sd_watchdog_enabled()</function> will unset - the <varname>$WATCHDOG_USEC</varname> and - <varname>$WATCHDOG_PID</varname> environment variables before - returning (regardless of whether the function call itself - succeeded or not). Those variables are no longer inherited by - child processes. Further calls to - <function>sd_watchdog_enabled()</function> will also return with - zero.</para> - - <para>If the <parameter>usec</parameter> parameter is non-NULL, - <function>sd_watchdog_enabled()</function> will write the timeout - in µs for the watchdog logic to it.</para> - - <para>To enable service supervision with the watchdog logic, use - <varname>WatchdogSec=</varname> in service files. See - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details.</para> - - <para>Use - <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry> - to enable automatic watchdog support in - <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>-based event loops.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On failure, this call returns a negative errno-style error - code. If the service manager expects watchdog keep-alive - notification messages to be sent, > 0 is returned, otherwise 0 - is returned. Only if the return value is > 0, the - <parameter>usec</parameter> parameter is valid after the - call.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> - - <para>Internally, this functions parses the - <varname>$WATCHDOG_PID</varname> and - <varname>$WATCHDOG_USEC</varname> environment variable. The call - will ignore these variables if <varname>$WATCHDOG_PID</varname> - does not contain the PID of the current process, under the - assumption that in that case, the variables were set for a - different process further up the process tree.</para> - </refsect1> - - <refsect1> - <title>Environment</title> - - <variablelist class='environment-variables'> - <varlistentry> - <term><varname>$WATCHDOG_PID</varname></term> - - <listitem><para>Set by the system manager for supervised - process for which watchdog support is enabled, and contains - the PID of that process. See above for - details.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$WATCHDOG_USEC</varname></term> - - <listitem><para>Set by the system manager for supervised - process for which watchdog support is enabled, and contains - the watchdog timeout in µs 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>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/shutdown.xml b/man/shutdown.xml deleted file mode 100644 index a8af387c67..0000000000 --- a/man/shutdown.xml +++ /dev/null @@ -1,175 +0,0 @@ -<?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" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <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</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="opt">TIME</arg> - <arg choice="opt" rep="repeat">WALL</arg> - </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>/run/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> - - <xi:include href="standard-options.xml" xpointer="help-text" /> - </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>Do not halt, power-off, reboot, just write - wall message.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--no-wall</option></term> - - <listitem><para>Do not 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>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 project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/daemon.xml b/man/sys/daemon.xml index a649749683..a649749683 100644 --- a/man/daemon.xml +++ b/man/sys/daemon.xml diff --git a/man/file-hierarchy.xml b/man/sys/file-hierarchy.xml index 538a592f8d..538a592f8d 100644 --- a/man/file-hierarchy.xml +++ b/man/sys/file-hierarchy.xml diff --git a/man/hostname.xml b/man/sys/hostname.xml index 8a4c0d5ac0..8a4c0d5ac0 100644 --- a/man/hostname.xml +++ b/man/sys/hostname.xml diff --git a/man/localtime.xml b/man/sys/localtime.xml index 2827da6e93..2827da6e93 100644 --- a/man/localtime.xml +++ b/man/sys/localtime.xml diff --git a/man/machine-id.xml b/man/sys/machine-id.xml index d318ec54ec..d318ec54ec 100644 --- a/man/machine-id.xml +++ b/man/sys/machine-id.xml diff --git a/man/machine-info.xml b/man/sys/machine-info.xml index 351133670b..351133670b 100644 --- a/man/machine-info.xml +++ b/man/sys/machine-info.xml diff --git a/man/os-release.xml b/man/sys/os-release.xml index a70ba1aa31..a70ba1aa31 100644 --- a/man/os-release.xml +++ b/man/sys/os-release.xml diff --git a/man/sysctl.d.xml b/man/sysctl.d.xml deleted file mode 100644 index ccf6c8e39f..0000000000 --- a/man/sysctl.d.xml +++ /dev/null @@ -1,184 +0,0 @@ -<?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" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <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 project='man-pages'><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 <literal>#</literal> or - <literal>;</literal> are ignored.</para> - - <para>Note that either <literal>/</literal> or - <literal>.</literal> may be used as separators within sysctl - variable names. If the first separator is a slash, remaining - slashes and dots are left intact. If the first separator is a dot, - dots and slashes are interchanged. - <literal>kernel.domainname=foo</literal> and - <literal>kernel/domainname=foo</literal> are equivalent and will - cause <literal>foo</literal> to be written to - <filename>/proc/sys/kernel/domainname</filename>. Either - <literal>net.ipv4.conf.enp3s0/200.forwarding</literal> or - <literal>net/ipv4/conf/enp3s0.200/forwarding</literal> may be used - to refer to - <filename>/proc/sys/net/ipv4/conf/enp3s0.200/forwarding</filename>. - </para> - - <para>The settings configured with <filename>sysctl.d</filename> - files will be applied early on boot. The network - interface-specific options will also be applied individually for - each network interface as it shows up in the system. (More - specifically, <filename>net.ipv4.conf.*</filename>, - <filename>net.ipv6.conf.*</filename>, - <filename>net.ipv4.neigh.*</filename> and - <filename>net.ipv6.neigh.*</filename>).</para> - - <para>Many sysctl parameters only become available when certain - kernel modules are loaded. Modules are usually loaded on demand, - e.g. when certain hardware is plugged in or network brought up. - This means that - <citerefentry><refentrytitle>systemd-sysctl.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - which runs during early boot will not configure such parameters if - they become available after it has run. To set such parameters, it - is recommended to add an - <citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry> - rule to set those parameters when they become available. - Alternatively, a slightly simpler and less efficient option is to - add the module to - <citerefentry><refentrytitle>modules-load.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - causing it to be loaded statically before sysctl settings are - applied (see example below).</para> - </refsect1> - - <xi:include href="standard-conf.xml" xpointer="confd" /> - - <refsect1> - <title>Examples</title> - <example> - <title>Set kernel YP domain name</title> - <para><filename>/etc/sysctl.d/domain-name.conf</filename>: - </para> - - <programlisting>kernel.domainname=example.com</programlisting> - </example> - - <example> - <title>Apply settings available only when a certain module is loaded (method one)</title> - <para><filename>/etc/udev/rules.d/99-bridge.rules</filename>: - </para> - - <programlisting>ACTION=="add", SUBSYSTEM=="module", KERNEL=="br_netfilter", \ - RUN+="/usr/lib/systemd/systemd-sysctl --prefix=/net/bridge" -</programlisting> - - <para><filename>/etc/sysctl.d/bridge.conf</filename>: - </para> - - <programlisting>net.bridge.bridge-nf-call-ip6tables = 0 -net.bridge.bridge-nf-call-iptables = 0 -net.bridge.bridge-nf-call-arptables = 0 -</programlisting> - - <para>This method applies settings when the module is - loaded. Please note that, unless the <filename>br_netfilter</filename> - module is loaded, bridged packets will not be filtered by - Netfilter (starting with kernel 3.18), so simply not loading the - module is sufficient to avoid filtering.</para> - </example> - - <example> - <title>Apply settings available only when a certain module is loaded (method two)</title> - <para><filename>/etc/modules-load.d/bridge.conf</filename>: - </para> - - <programlisting>br_netfilter</programlisting> - - <para><filename>/etc/sysctl.d/bridge.conf</filename>: - </para> - - <programlisting>net.bridge.bridge-nf-call-ip6tables = 0 -net.bridge.bridge-nf-call-iptables = 0 -net.bridge.bridge-nf-call-arptables = 0 -</programlisting> - - <para>This method forces the module to be always loaded. Please - note that, unless the <filename>br_netfilter</filename> module is - loaded, bridged packets will not be filtered with Netfilter - (starting with kernel 3.18), so simply not loading the module is - sufficient to avoid filtering.</para> - </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 project='man-pages'><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>sysctl.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>modprobe</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemctl.xml b/man/systemctl.xml deleted file mode 100644 index 991e9bafaf..0000000000 --- a/man/systemctl.xml +++ /dev/null @@ -1,1838 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ -<!ENTITY % entities SYSTEM "custom-entities.ent" > -%entities; -]> - -<!-- - 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" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <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</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="plain">COMMAND</arg> - <arg choice="opt" rep="repeat">NAME</arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemctl</command> may be used to introspect and - control the state of the <literal>systemd</literal> system and - service manager. Please refer to - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> - for an introduction into the basic concepts and functionality this - tool manages.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>-t</option></term> - <term><option>--type=</option></term> - - <listitem> - <para>The argument should be a comma-separated list of unit - types such as <option>service</option> and - <option>socket</option>. - </para> - - <para>If one of the arguments is a unit type, when listing - units, limit display to certain unit types. Otherwise, units - of all types will be shown.</para> - - <para>As a special case, if one of the arguments is - <option>help</option>, a list of allowed values will be - printed and the program will exit.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--state=</option></term> - - <listitem> - <para>The argument should be a comma-separated list of unit - LOAD, SUB, or ACTIVE states. When listing units, show only - those in the specified states. Use <option>--state=failed</option> - to show only failed units.</para> - - <para>As a special case, if one of the arguments is - <option>help</option>, a list of allowed values will be - printed and the program will exit.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-p</option></term> - <term><option>--property=</option></term> - - <listitem> - <para>When showing unit/job/manager properties with the - <command>show</command> command, limit display to properties - specified in the argument. The argument should be a - comma-separated list of property names, such as - <literal>MainPID</literal>. Unless specified, all known - properties are shown. If specified more than once, all - properties with the specified names are shown. Shell - completion is implemented for property names.</para> - - <para>For the manager itself, - <command>systemctl show</command> will show all available - properties. Those properties are documented in - <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - </para> - - <para>Properties for units vary by unit type, so showing any - unit (even a non-existent one) is a way to list properties - pertaining to this type. Similarly, showing any job will list - properties pertaining to all jobs. Properties for units are - documented in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - and the pages for individual unit types - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - etc.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-a</option></term> - <term><option>--all</option></term> - - <listitem> - <para>When listing units, show all loaded 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> - <para>To list all units installed on the system, use the - <command>list-unit-files</command> command instead.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-r</option></term> - <term><option>--recursive</option></term> - - <listitem> - <para>When listing units, also show units of local - containers. Units of local containers will be prefixed with - the container name, separated by a single colon character - (<literal>:</literal>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--reverse</option></term> - - <listitem> - <para>Show reverse dependencies between units with - <command>list-dependencies</command>, i.e. follow - dependencies of type <varname>WantedBy=</varname>, - <varname>RequiredBy=</varname>, - <varname>PartOf=</varname>, <varname>BoundBy=</varname>, - instead of <varname>Wants=</varname> and similar. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--after</option></term> - - <listitem> - <para>With <command>list-dependencies</command>, show the - units that are ordered before the specified unit. In other - words, recursively list units following the - <varname>After=</varname> dependency.</para> - - <para>Note that any <varname>After=</varname> dependency is - automatically mirrored to create a - <varname>Before=</varname> dependency. Temporal dependencies - may be specified explicitly, but are also created implicitly - for units which are <varname>WantedBy=</varname> targets - (see - <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>), - and as a result of other directives (for example - <varname>RequiresMountsFor=</varname>). Both explicitly - and implicitly introduced dependencies are shown with - <command>list-dependencies</command>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--before</option></term> - - <listitem> - <para>With <command>list-dependencies</command>, show the - units that are ordered after the specified unit. In other - words, recursively list units following the - <varname>Before=</varname> dependency.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-l</option></term> - <term><option>--full</option></term> - - <listitem> - <para>Do not ellipsize unit names, process tree entries, - journal output, or truncate unit descriptions in the output - of <command>status</command>, <command>list-units</command>, - <command>list-jobs</command>, and - <command>list-timers</command>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--value</option></term> - - <listitem> - <para>When printing properties with <command>show</command>, - only print the value, and skip the property name and - <literal>=</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--show-types</option></term> - - <listitem> - <para>When showing sockets, show the type of the socket.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--job-mode=</option></term> - - <listitem> - <para>When queuing a new job, this option controls how to deal with - already queued jobs. It takes one of <literal>fail</literal>, - <literal>replace</literal>, - <literal>replace-irreversibly</literal>, - <literal>isolate</literal>, - <literal>ignore-dependencies</literal>, - <literal>ignore-requirements</literal> or - <literal>flush</literal>. Defaults to - <literal>replace</literal>, except when the - <command>isolate</command> command is used which implies the - <literal>isolate</literal> job mode.</para> - - <para>If <literal>fail</literal> is specified and a requested - operation conflicts with a pending job (more specifically: - causes an already pending start job to be reversed into a stop - job or vice versa), cause the operation to fail.</para> - - <para>If <literal>replace</literal> (the default) is - specified, any conflicting pending job will be replaced, as - necessary.</para> - - <para>If <literal>replace-irreversibly</literal> is specified, - operate like <literal>replace</literal>, but also mark the new - jobs as irreversible. This prevents future conflicting - transactions from replacing these jobs (or even being enqueued - while the irreversible jobs are still pending). Irreversible - jobs can still be cancelled using the <command>cancel</command> - command.</para> - - <para><literal>isolate</literal> is only valid for start - operations and causes all other units to be stopped when the - specified unit is started. This mode is always used when the - <command>isolate</command> command is used.</para> - - <para><literal>flush</literal> will cause all queued jobs to - be canceled when the new job is enqueued.</para> - - <para>If <literal>ignore-dependencies</literal> is specified, - then all unit dependencies are ignored for this new job and - the operation is executed 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> - - <para><literal>ignore-requirements</literal> is similar to - <literal>ignore-dependencies</literal>, but only causes the - requirement dependencies to be ignored, the ordering - dependencies will still be honoured.</para> - </listitem> - - </varlistentry> - - <varlistentry> - <term><option>--fail</option></term> - - <listitem> - <para>Shorthand for <option>--job-mode=</option>fail.</para> - <para>When used with the <command>kill</command> command, - if no units were killed, the operation results in an error. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-i</option></term> - <term><option>--ignore-inhibitors</option></term> - - <listitem> - <para>When system shutdown or a sleep state is requested, - ignore inhibitor locks. Applications can establish inhibitor - locks to avoid that certain important operations (such as CD - burning or suchlike) are interrupted by system shutdown or a - sleep state. Any user may take these locks and privileged - users may override these locks. If any locks are taken, - shutdown and sleep state requests will normally fail - (regardless of whether privileged or not) and a list of active locks - is printed. However, if <option>--ignore-inhibitors</option> - is specified, the locks are ignored and not printed, and the - operation attempted anyway, possibly requiring additional - privileges.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-q</option></term> - <term><option>--quiet</option></term> - - <listitem> - <para>Suppress printing of the results of various commands - and also the hints about truncated log lines. This does not - suppress output of commands for which the printed output is - the only result (like <command>show</command>). Errors are - always printed.</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 the unit's start-up is completed. By passing this - argument, it is only verified and enqueued.</para> - </listitem> - </varlistentry> - - <xi:include href="user-system-options.xml" xpointer="user" /> - <xi:include href="user-system-options.xml" xpointer="system" /> - - <!-- we do not document -failed here, as it has been made - redundant by -state=failed, which it predates. To keep - things simple, we only document the new switch, while - keeping the old one around for compatibility only. --> - - <varlistentry> - <term><option>--no-wall</option></term> - - <listitem> - <para>Do not 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 send a signal to. Must be one of - <option>main</option>, <option>control</option> or - <option>all</option> to select whether to kill only the main - process, the control process or all processes of the - unit. The main process of the unit is the one that defines - the life-time of it. A control process of a unit is one that - is invoked by the manager to induce state changes of it. For - example, all processes started due to the - <varname>ExecStartPre=</varname>, - <varname>ExecStop=</varname> or - <varname>ExecReload=</varname> settings of service units are - control processes. Note that there is only one control - process per unit at a time, as only one state change is - executed at a time. For services of type - <varname>Type=forking</varname>, the initial process started - by the manager for <varname>ExecStart=</varname> is a - control process, while the process ultimately forked off by - that one is then considered the main process of the unit (if - it can be determined). This is different for service units - of other types, where the process forked off by the manager - for <varname>ExecStart=</varname> is always the main process - itself. A service unit consists of zero or one main process, - zero or one control process plus any number of additional - processes. Not all unit types manage processes of these - types however. For example, for mount units, control processes - are defined (which are the invocations of - <filename>&MOUNT_PATH;</filename> and - <filename>&UMOUNT_PATH;</filename>), but no main process - is defined. If omitted, defaults to - <option>all</option>.</para> - </listitem> - - </varlistentry> - - <varlistentry> - <term><option>-s</option></term> - <term><option>--signal=</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 <constant>SIGTERM</constant>, <constant>SIGINT</constant> or - <constant>SIGSTOP</constant>. If omitted, defaults to - <option>SIGTERM</option>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-f</option></term> - <term><option>--force</option></term> - - <listitem> - <para>When used with <command>enable</command>, overwrite - any existing conflicting symlinks.</para> - - <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 unmounting 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>--message=</option></term> - - <listitem> - <para>When used with <command>halt</command>, - <command>poweroff</command>, <command>reboot</command> or - <command>kexec</command>, set a short message explaining the reason - for the operation. The message will be logged together with the - default shutdown message.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--now</option></term> - - <listitem> - <para>When used with <command>enable</command>, the units - will also be started. When used with <command>disable</command> or - <command>mask</command>, the units will also be stopped. The start - or stop operation is only carried out when the respective enable or - disable operation has been successful.</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 an alternate 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>edit</command>, - (and related commands), make changes only temporarily, so - that they are lost 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> - - <para>Similarly, when used with - <command>set-property</command>, make changes only - temporarily, so that they are lost on the next - reboot.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--preset-mode=</option></term> - - <listitem> - <para>Takes one of <literal>full</literal> (the default), - <literal>enable-only</literal>, - <literal>disable-only</literal>. When used with the - <command>preset</command> or <command>preset-all</command> - commands, controls whether units shall be disabled and - enabled according to the preset rules, or only enabled, or - only disabled.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-n</option></term> - <term><option>--lines=</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>-o</option></term> - <term><option>--output=</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> - - <varlistentry> - <term><option>--firmware-setup</option></term> - - <listitem> - <para>When used with the <command>reboot</command> command, - indicate to the system's firmware to boot into setup - mode. Note that this is currently only supported on some EFI - systems and only if the system was booted in EFI - mode.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--plain</option></term> - - <listitem> - <para>When used with <command>list-dependencies</command>, - <command>list-units</command> or <command>list-machines</command>, the - the output is printed as a list instead of a tree, and the bullet - circles are omitted.</para> - </listitem> - </varlistentry> - - <xi:include href="user-system-options.xml" xpointer="host" /> - <xi:include href="user-system-options.xml" xpointer="machine" /> - - <xi:include href="standard-options.xml" xpointer="no-pager" /> - <xi:include href="standard-options.xml" xpointer="no-legend" /> - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </variablelist> - </refsect1> - - <refsect1> - <title>Commands</title> - - <para>The following commands are understood:</para> - - <refsect2> - <title>Unit Commands</title> - - <variablelist> - <varlistentry> - <term><command>list-units <optional><replaceable>PATTERN</replaceable>...</optional></command></term> - - <listitem> - <para>List known units (subject to limitations specified - with <option>-t</option>). If one or more - <replaceable>PATTERN</replaceable>s are specified, only - units matching one of them are shown.</para> - - <para>This is the default command.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>list-sockets <optional><replaceable>PATTERN</replaceable>...</optional></command></term> - - <listitem> - <para>List socket units ordered by listening address. - If one or more <replaceable>PATTERN</replaceable>s are - specified, only socket units matching one of them are - shown. Produces output similar to - <programlisting> -LISTEN UNIT ACTIVATES -/dev/initctl systemd-initctl.socket systemd-initctl.service -... -[::]:22 sshd.socket sshd.service -kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service - -5 sockets listed.</programlisting> - Note: because the addresses might contains spaces, this output - is not suitable for programmatic consumption. - </para> - - <para>See also the options <option>--show-types</option>, - <option>--all</option>, and <option>--state=</option>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>list-timers <optional><replaceable>PATTERN</replaceable>...</optional></command></term> - - <listitem> - <para>List timer units ordered by the time they elapse - next. If one or more <replaceable>PATTERN</replaceable>s - are specified, only units matching one of them are shown. - </para> - - <para>See also the options <option>--all</option> and - <option>--state=</option>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>start <replaceable>PATTERN</replaceable>...</command></term> - - <listitem> - <para>Start (activate) one or more units specified on the - command line.</para> - - <para>Note that glob patterns operate on the set of primary names of currently loaded units. Units which - are not active and are not in a failed state usually are not loaded, and will not be matched by any - pattern. In addition, in case of instantiated units, systemd is often unaware of the instance name until - the instance has been started. Therefore, using glob patterns with <command>start</command> has limited - usefulness. Also, secondary alias names of units are not considered.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><command>stop <replaceable>PATTERN</replaceable>...</command></term> - - <listitem> - <para>Stop (deactivate) one or more units specified on the - command line.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><command>reload <replaceable>PATTERN</replaceable>...</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> command.</para> - </listitem> - - </varlistentry> - <varlistentry> - <term><command>restart <replaceable>PATTERN</replaceable>...</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 <replaceable>PATTERN</replaceable>...</command></term> - - <listitem> - <para>Restart one or more units specified on the command - line if the units are running. This does nothing if units are not - running.</para> - <!-- Note that we don't document condrestart here, as that is just compatibility support, and we generally - don't document that. --> - </listitem> - </varlistentry> - <varlistentry> - <term><command>reload-or-restart <replaceable>PATTERN</replaceable>...</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>try-reload-or-restart <replaceable>PATTERN</replaceable>...</command></term> - - <listitem> - <para>Reload one or more units if they support it. If not, - restart them instead. This does nothing if the units are not - running.</para> - <!-- Note that we don't document force-reload here, as that is just compatibility support, and we generally - don't document that. --> - </listitem> - </varlistentry> - <varlistentry> - <term><command>isolate <replaceable>NAME</replaceable></command></term> - - <listitem> - <para>Start the unit specified on the command line and its - dependencies and stop all others. If a unit name with no - extension is given, an extension of - <literal>.target</literal> will be assumed.</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 is allowed 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 <replaceable>PATTERN</replaceable>...</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>--signal=</option> to select - the signal to send.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><command>is-active <replaceable>PATTERN</replaceable>...</command></term> - - <listitem> - <para>Check whether any of the specified units are active - (i.e. running). Returns an exit code - <constant>0</constant> if at least one is active, or - non-zero otherwise. Unless <option>--quiet</option> is - specified, this will also print the current unit state to - standard output.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><command>is-failed <replaceable>PATTERN</replaceable>...</command></term> - - <listitem> - <para>Check whether any of the specified units are in a - "failed" state. Returns an exit code - <constant>0</constant> if at least one has failed, - non-zero otherwise. Unless <option>--quiet</option> is - specified, this will also print the current unit state to - standard output.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><command>status</command> <optional><replaceable>PATTERN</replaceable>...|<replaceable>PID</replaceable>...]</optional></term> - - <listitem> - <para>Show terse runtime status information about one or - more units, followed by most recent log data from the - journal. If no units are specified, show system status. If - combined with <option>--all</option>, also show the status of - all units (subject to limitations specified with - <option>-t</option>). If a PID is passed, show information - about the unit the process belongs to.</para> - - <para>This function is intended to generate human-readable - output. If you are looking for computer-parsable output, - use <command>show</command> instead. By default, this - function only shows 10 lines of output and ellipsizes - lines to fit in the terminal window. This can be changed - with <option>--lines</option> and <option>--full</option>, - see above. In addition, <command>journalctl - --unit=<replaceable>NAME</replaceable></command> or - <command>journalctl - --user-unit=<replaceable>NAME</replaceable></command> use - a similar filter for messages and might be more - convenient. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><command>show</command> <optional><replaceable>PATTERN</replaceable>...|<replaceable>JOB</replaceable>...</optional></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>cat <replaceable>PATTERN</replaceable>...</command></term> - - <listitem> - <para>Show backing files of one or more units. Prints the - "fragment" and "drop-ins" (source files) of units. Each - file is preceded by a comment which includes the file - name.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><command>set-property <replaceable>NAME</replaceable> <replaceable>ASSIGNMENT</replaceable>...</command></term> - - <listitem> - <para>Set the specified unit properties at runtime where - this is supported. This allows changing configuration - parameter properties such as resource control settings at - runtime. Not all properties may be changed at runtime, but - many resource control settings (primarily those in - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>) - may. The changes are applied instantly, and stored on disk - for future boots, unless <option>--runtime</option> is - passed, in which case the settings only apply until the - next reboot. The syntax of the property assignment follows - closely the syntax of assignments in unit files.</para> - - <para>Example: <command>systemctl set-property foobar.service CPUShares=777</command></para> - - <para>If the specified unit appears to be inactive, the - changes will be only stored on disk as described - previously hence they will be effective when the unit will - be started.</para> - - <para>Note that this command allows changing multiple - properties at the same time, which is preferable over - setting them individually. Like unit file configuration - settings, assigning the empty list to list parameters will - reset the list.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>help <replaceable>PATTERN</replaceable>...|<replaceable>PID</replaceable>...</command></term> - - <listitem> - <para>Show manual pages for one or more units, if - available. If a PID is given, the manual pages for the unit - the process belongs to are shown.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>reset-failed [<replaceable>PATTERN</replaceable>...]</command></term> - - <listitem> - <para>Reset the <literal>failed</literal> state of the - specified units, or if no unit name is passed, reset the state 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-dependencies</command> - <optional><replaceable>NAME</replaceable></optional> - </term> - - <listitem> - <para>Shows units required and wanted by the specified - unit. This recursively lists units following the - <varname>Requires=</varname>, - <varname>Requisite=</varname>, - <varname>ConsistsOf=</varname>, - <varname>Wants=</varname>, <varname>BindsTo=</varname> - dependencies. If no unit is specified, - <filename>default.target</filename> is implied.</para> - - <para>By default, only target units are recursively - expanded. When <option>--all</option> is passed, all other - units are recursively expanded as well.</para> - - <para>Options <option>--reverse</option>, - <option>--after</option>, <option>--before</option> - may be used to change what types of dependencies - are shown.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect2> - - <refsect2> - <title>Unit File Commands</title> - - <variablelist> - <varlistentry> - <term><command>list-unit-files <optional><replaceable>PATTERN...</replaceable></optional></command></term> - - <listitem> - <para>List installed unit files and their enablement state - (as reported by <command>is-enabled</command>). If one or - more <replaceable>PATTERN</replaceable>s are specified, - only units whose filename (just the last component of the - path) matches one of them are shown.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>enable <replaceable>NAME</replaceable>...</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 <emphasis>not</emphasis> have the effect of also - starting any of the units being enabled. If this - is desired, either <option>--now</option> should be used - together with this command, or an additional <command>start</command> - command must be invoked for the unit. Also note that, in case of - instance enablement, symlinks named the same as instances - are created in the 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 the 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>, <option>--runtime</option>, - or <option>--global</option> is specified, this enables the unit - for the system, for the calling user only, for only this boot of - the system, or for all future logins of all users, or only this - boot. Note that in the last case, no systemd daemon - configuration is reloaded.</para> - - <para>Using <command>enable</command> on masked units - results in an error.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>disable <replaceable>NAME</replaceable>...</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, either - <option>--now</option> should be used together with this command, or - 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> - - <para>This command honors <option>--system</option>, - <option>--user</option>, <option>--runtime</option> and - <option>--global</option> in a similar way as - <command>enable</command>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>reenable <replaceable>NAME</replaceable>...</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 <replaceable>NAME</replaceable>...</command></term> - - <listitem> - <para>Reset the enable/disable status 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.</para> - - <para>Use <option>--preset-mode=</option> to control whether units shall be - enabled and disabled, or only enabled, or only disabled.</para> - - <para>If the unit carries no install information, it will be silently ignored - by this command.</para> - - <para>For more information on the 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>preset-all</command></term> - - <listitem> - <para>Resets all installed unit files to the defaults - configured in the preset policy file (see above).</para> - - <para>Use <option>--preset-mode=</option> to control - whether units shall be enabled and disabled, or only - enabled, or only disabled.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>is-enabled <replaceable>NAME</replaceable>...</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 (see table). - To suppress this output, use <option>--quiet</option>. - </para> - - <table> - <title> - <command>is-enabled</command> output - </title> - - <tgroup cols='3'> - <thead> - <row> - <entry>Name</entry> - <entry>Description</entry> - <entry>Exit Code</entry> - </row> - </thead> - <tbody> - <row> - <entry><literal>enabled</literal></entry> - <entry morerows='1'>Enabled via <filename>.wants/</filename>, <filename>.requires/</filename> or alias symlinks (permanently in <filename>/etc/systemd/system/</filename>, or transiently in <filename>/run/systemd/system/</filename>).</entry> - <entry morerows='1'>0</entry> - </row> - <row> - <entry><literal>enabled-runtime</literal></entry> - </row> - <row> - <entry><literal>linked</literal></entry> - <entry morerows='1'>Made available through one or more symlinks to the unit file (permanently in <filename>/etc/systemd/system/</filename> or transiently in <filename>/run/systemd/system/</filename>), even though the unit file might reside outside of the unit file search path.</entry> - <entry morerows='1'>> 0</entry> - </row> - <row> - <entry><literal>linked-runtime</literal></entry> - </row> - <row> - <entry><literal>masked</literal></entry> - <entry morerows='1'>Completely disabled, so that any start operation on it fails (permanently in <filename>/etc/systemd/system/</filename> or transiently in <filename>/run/systemd/systemd/</filename>).</entry> - <entry morerows='1'>> 0</entry> - </row> - <row> - <entry><literal>masked-runtime</literal></entry> - </row> - <row> - <entry><literal>static</literal></entry> - <entry>The unit file is not enabled, and has no provisions for enabling in the <literal>[Install]</literal> unit file section.</entry> - <entry>0</entry> - </row> - <row> - <entry><literal>indirect</literal></entry> - <entry>The unit file itself is not enabled, but it has a non-empty <varname>Also=</varname> setting in the <literal>[Install]</literal> unit file section, listing other unit files that might be enabled.</entry> - <entry>0</entry> - </row> - <row> - <entry><literal>disabled</literal></entry> - <entry>The unit file is not enabled, but contains an <literal>[Install]</literal> section with installation instructions.</entry> - <entry>> 0</entry> - </row> - <row> - <entry><literal>generated</literal></entry> - <entry>The unit file was generated dynamically via a generator tool. See <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>. Generated unit files may not be enabled, they are enabled implicitly by their generator.</entry> - <entry>0</entry> - </row> - <row> - <entry><literal>transient</literal></entry> - <entry>The unit file has been created dynamically with the runtime API. Transient units may not be enabled.</entry> - <entry>0</entry> - </row> - <row> - <entry><literal>bad</literal></entry> - <entry>The unit file is invalid or another error occurred. Note that <command>is-enabled</command> will not actually return this state, but print an error message instead. However the unit file listing printed by <command>list-unit-files</command> might show it.</entry> - <entry>> 0</entry> - </row> - </tbody> - </tgroup> - </table> - - </listitem> - </varlistentry> - - <varlistentry> - <term><command>mask <replaceable>NAME</replaceable>...</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 enablement and manual - activation. Use this option with care. This honors the - <option>--runtime</option> option to only mask temporarily - until the next reboot of the system. The <option>--now</option> - option can be used to ensure that the units are also stopped.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>unmask <replaceable>NAME</replaceable>...</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 <replaceable>FILENAME</replaceable>...</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 - is not installed directly in the unit search path.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>revert <replaceable>NAME</replaceable>...</command></term> - - <listitem> - <para>Revert one or more unit files to their vendor versions. This command removes drop-in configuration - files that modify the specified units, as well as any user-configured unit file that overrides a matching - vendor supplied unit file. Specifically, for a unit <literal>foo.service</literal> the matching directories - <literal>foo.service.d/</literal> with all their contained files are removed, both below the persistent and - runtime configuration directories (i.e. below <filename>/etc/systemd/system</filename> and - <filename>/run/systemd/system</filename>); if the unit file has a vendor-supplied version (i.e. a unit file - located below <filename>/usr</filename>) any matching peristent or runtime unit file that overrides it is - removed, too. Note that if a unit file has no vendor-supplied version (i.e. is only defined below - <filename>/etc/systemd/system</filename> or <filename>/run/systemd/system</filename>, but not in a unit - file stored below <filename>/usr</filename>), then it is not removed. Also, if a unit is masked, it is - unmasked.</para> - - <para>Effectively, this command may be used to undo all changes made with <command>systemctl - edit</command>, <command>systemctl set-property</command> and <command>systemctl mask</command> and puts - the original unit file with its settings back in effect.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>add-wants <replaceable>TARGET</replaceable> - <replaceable>NAME</replaceable>...</command></term> - <term><command>add-requires <replaceable>TARGET</replaceable> - <replaceable>NAME</replaceable>...</command></term> - - <listitem> - <para>Adds <literal>Wants=</literal> or <literal>Requires=</literal> - dependencies, respectively, to the specified - <replaceable>TARGET</replaceable> for one or more units. </para> - - <para>This command honors <option>--system</option>, - <option>--user</option>, <option>--runtime</option> and - <option>--global</option> in a way similar to - <command>enable</command>.</para> - - </listitem> - </varlistentry> - - <varlistentry> - <term><command>edit <replaceable>NAME</replaceable>...</command></term> - - <listitem> - <para>Edit a drop-in snippet or a whole replacement file if - <option>--full</option> is specified, to extend or override the - specified unit.</para> - - <para>Depending on whether <option>--system</option> (the default), - <option>--user</option>, or <option>--global</option> is specified, - this command creates a drop-in file for each unit either for the system, - for the calling user, or for all futures logins of all users. Then, - the editor (see the "Environment" section below) is invoked on - temporary files which will be written to the real location if the - editor exits successfully.</para> - - <para>If <option>--full</option> is specified, this will copy the - original units instead of creating drop-in files.</para> - - <para>If <option>--runtime</option> is specified, the changes will - be made temporarily in <filename>/run</filename> and they will be - lost on the next reboot.</para> - - <para>If the temporary file is empty upon exit, the modification of - the related unit is canceled.</para> - - <para>After the units have been edited, systemd configuration is - reloaded (in a way that is equivalent to <command>daemon-reload</command>). - </para> - - <para>Note that this command cannot be used to remotely edit units - and that you cannot temporarily edit units which are in - <filename>/etc</filename>, since they take precedence over - <filename>/run</filename>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>get-default</command></term> - - <listitem> - <para>Return the default target to boot into. This returns - the target unit name <filename>default.target</filename> - is aliased (symlinked) to.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>set-default <replaceable>NAME</replaceable></command></term> - - <listitem> - <para>Set the default target to boot into. This sets - (symlinks) the <filename>default.target</filename> alias - to the given target unit.</para> - </listitem> - </varlistentry> - - </variablelist> - </refsect2> - - <refsect2> - <title>Machine Commands</title> - - <variablelist> - <varlistentry> - <term><command>list-machines <optional><replaceable>PATTERN</replaceable>...</optional></command></term> - - <listitem> - <para>List the host and all running local containers with - their state. If one or more - <replaceable>PATTERN</replaceable>s are specified, only - containers matching one of them are shown. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect2> - - <refsect2> - <title>Job Commands</title> - - <variablelist> - <varlistentry> - <term><command>list-jobs <optional><replaceable>PATTERN...</replaceable></optional></command></term> - - <listitem> - <para>List jobs that are in progress. If one or more - <replaceable>PATTERN</replaceable>s are specified, only - jobs for units matching one of them are shown.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><command>cancel <replaceable>JOB</replaceable>...</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> - </variablelist> - </refsect2> - - <refsect2> - <title>Environment Commands</title> - - <variablelist> - <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 <replaceable>VARIABLE=VALUE</replaceable>...</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 <replaceable>VARIABLE</replaceable>...</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>import-environment</command> - <optional><replaceable>VARIABLE...</replaceable></optional> - </term> - - <listitem> - <para>Import all, one or more environment variables set on - the client into the systemd manager environment block. If - no arguments are passed, the entire environment block is - imported. Otherwise, a list of one or more environment - variable names should be passed, whose client-side values - are then imported into the manager's environment - block.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect2> - - <refsect2> - <title>Manager Lifecycle Commands</title> - - <variablelist> - <varlistentry> - <term><command>daemon-reload</command></term> - - <listitem> - <para>Reload the systemd manager configuration. This will - rerun all generators (see - <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>), - reload all unit files, and recreate the entire dependency - tree. While the daemon is being reloaded, all sockets - systemd listens on behalf of user configuration will stay - accessible.</para> - - <para>This command should not be confused with the - <command>reload</command> command.</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 being reexecuted, all sockets systemd listening - on behalf of user configuration will stay accessible. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect2> - - <refsect2> - <title>System Commands</title> - - <variablelist> - <varlistentry> - <term><command>is-system-running</command></term> - - <listitem> - <para>Checks whether the system is operational. This - returns success (exit code 0) when the system is fully up - and running, specifically not in startup, shutdown or - maintenance mode, and with no failed services. Failure is - returned otherwise (exit code non-zero). In addition, the - current state is printed in a short string to standard - output, see the table below. Use <option>--quiet</option> to - suppress this output.</para> - - <table> - <title><command>is-system-running</command> output</title> - <tgroup cols='3'> - <colspec colname='name'/> - <colspec colname='description'/> - <colspec colname='exit-code'/> - <thead> - <row> - <entry>Name</entry> - <entry>Description</entry> - <entry>Exit Code</entry> - </row> - </thead> - <tbody> - <row> - <entry><varname>initializing</varname></entry> - <entry><para>Early bootup, before - <filename>basic.target</filename> is reached - or the <varname>maintenance</varname> state entered. - </para></entry> - <entry>> 0</entry> - </row> - <row> - <entry><varname>starting</varname></entry> - <entry><para>Late bootup, before the job queue - becomes idle for the first time, or one of the - rescue targets are reached.</para></entry> - <entry>> 0</entry> - </row> - <row> - <entry><varname>running</varname></entry> - <entry><para>The system is fully - operational.</para></entry> - <entry>0</entry> - </row> - <row> - <entry><varname>degraded</varname></entry> - <entry><para>The system is operational but one or more - units failed.</para></entry> - <entry>> 0</entry> - </row> - <row> - <entry><varname>maintenance</varname></entry> - <entry><para>The rescue or emergency target is - active.</para></entry> - <entry>> 0</entry> - </row> - <row> - <entry><varname>stopping</varname></entry> - <entry><para>The manager is shutting - down.</para></entry> - <entry>> 0</entry> - </row> - <row> - <entry><varname>offline</varname></entry> - <entry><para>The manager is not - running. Specifically, this is the operational - state if an incompatible program is running as - system manager (PID 1).</para></entry> - <entry>> 0</entry> - </row> - <row> - <entry><varname>unknown</varname></entry> - <entry><para>The operational state could not be - determined, due to lack of resources or another - error cause.</para></entry> - <entry>> 0</entry> - </row> - </tbody> - </tgroup> - </table> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>default</command></term> - - <listitem> - <para>Enter default mode. This is mostly equivalent to - <command>isolate 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 --job-mode=replace-irreversibly</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 --job-mode=replace-irreversibly</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 <optional><replaceable>arg</replaceable></optional></command></term> - - <listitem> - <para>Shut down and reboot the system. This is mostly - equivalent to <command>start reboot.target --job-mode=replace-irreversibly</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> - - <para>If the optional argument - <replaceable>arg</replaceable> is given, it will be passed - as the optional argument to the - <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> - system call. The value is architecture and firmware - specific. As an example, <literal>recovery</literal> might - be used to trigger system recovery, and - <literal>fota</literal> might be used to trigger a - <quote>firmware over the air</quote> update.</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 --job-mode=replace-irreversibly</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 <optional><replaceable>EXIT_CODE</replaceable></optional></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) or in containers - and is equivalent to <command>poweroff</command> otherwise.</para> - - <para>The systemd manager can exit with a non-zero exit - code if the optional argument - <replaceable>EXIT_CODE</replaceable> is given.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>switch-root <replaceable>ROOT</replaceable> <optional><replaceable>INIT</replaceable></optional></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. This call takes two - arguments: the directory that is to become 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 to 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> - - <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> - </variablelist> - </refsect2> - - <refsect2> - <title>Parameter Syntax</title> - - <para>Unit commands listed above take either a single unit name (designated as <replaceable>NAME</replaceable>), - or multiple unit specifications (designated as <replaceable>PATTERN</replaceable>...). In the first case, the - unit name with or without a suffix must be given. If the suffix is not specified (unit name is "abbreviated"), - systemctl will append a suitable suffix, <literal>.service</literal> by default, and a type-specific suffix in - case of commands which operate only on specific unit types. For example, - <programlisting># systemctl start sshd</programlisting> and - <programlisting># systemctl start sshd.service</programlisting> - are equivalent, as are - <programlisting># systemctl isolate default</programlisting> - and - <programlisting># systemctl isolate default.target</programlisting> - Note that (absolute) paths to device nodes are automatically converted to device unit names, and other (absolute) - paths to mount unit names. - <programlisting># systemctl status /dev/sda -# systemctl status /home</programlisting> - are equivalent to: - <programlisting># systemctl status dev-sda.device -# systemctl status home.mount</programlisting> - In the second case, shell-style globs will be matched against the primary names of all currently loaded units; - literal unit names, with or without a suffix, will be treated as in the first case. This means that literal unit - names always refer to exactly one unit, but globs may match zero units and this is not considered an - error.</para> - - <para>Glob patterns use - <citerefentry project='man-pages'><refentrytitle>fnmatch</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - so normal shell-style globbing rules are used, and - <literal>*</literal>, <literal>?</literal>, - <literal>[]</literal> may be used. See - <citerefentry project='man-pages'><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for more details. The patterns are matched against the primary names of - currently loaded units, and patterns which do not match anything - are silently skipped. For example: - <programlisting># systemctl stop sshd@*.service</programlisting> - will stop all <filename>sshd@.service</filename> instances. Note that alias names of units, and units that aren't - loaded are not considered for glob expansion. - </para> - - <para>For unit file commands, the specified <replaceable>NAME</replaceable> should be the name of the unit file - (possibly abbreviated, see above), or the absolute path to the unit file: - <programlisting># systemctl enable foo.service</programlisting> - or - <programlisting># systemctl link /path/to/foo.service</programlisting> - </para> - </refsect2> - - </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 class='environment-variables'> - <varlistentry> - <term><varname>$SYSTEMD_EDITOR</varname></term> - - <listitem><para>Editor to use when editing units; overrides - <varname>$EDITOR</varname> and <varname>$VISUAL</varname>. If neither - <varname>$SYSTEMD_EDITOR</varname> nor <varname>$EDITOR</varname> nor - <varname>$VISUAL</varname> are present or if it is set to an empty - string or if their execution failed, systemctl will try to execute well - known editors in this order: - <citerefentry project='die-net'><refentrytitle>editor</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>nano</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>vim</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>vi</refentrytitle><manvolnum>1</manvolnum></citerefentry>. - </para></listitem> - </varlistentry> - </variablelist> - <xi:include href="less-variables.xml" xpointer="pager"/> - <xi:include href="less-variables.xml" xpointer="less"/> - </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>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.preset</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-analyze.xml b/man/systemd-analyze.xml deleted file mode 100644 index bc37765dff..0000000000 --- a/man/systemd-analyze.xml +++ /dev/null @@ -1,388 +0,0 @@ -<?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" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <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> - <author> - <contrib>Developer</contrib> - <firstname>Harald</firstname> - <surname>Hoyer</surname> - <email>harald@redhat.com</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</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg>time</arg> - </cmdsynopsis> - <cmdsynopsis> - <command>systemd-analyze</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="plain">blame</arg> - </cmdsynopsis> - <cmdsynopsis> - <command>systemd-analyze</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="plain">critical-chain</arg> - <arg choice="opt" rep="repeat"><replaceable>UNIT</replaceable></arg> - </cmdsynopsis> - <cmdsynopsis> - <command>systemd-analyze</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="plain">plot</arg> - <arg choice="opt">> file.svg</arg> - </cmdsynopsis> - <cmdsynopsis> - <command>systemd-analyze</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="plain">dot</arg> - <arg choice="opt" rep="repeat"><replaceable>PATTERN</replaceable></arg> - <arg choice="opt">> file.dot</arg> - </cmdsynopsis> - <cmdsynopsis> - <command>systemd-analyze</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="plain">dump</arg> - </cmdsynopsis> - <cmdsynopsis> - <command>systemd-analyze</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="plain">set-log-level</arg> - <arg choice="plain"><replaceable>LEVEL</replaceable></arg> - </cmdsynopsis> - <cmdsynopsis> - <command>systemd-analyze</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="plain">set-log-target</arg> - <arg choice="plain"><replaceable>TARGET</replaceable></arg> - </cmdsynopsis> - <cmdsynopsis> - <command>systemd-analyze</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="plain">verify</arg> - <arg choice="opt" rep="repeat"><replaceable>FILES</replaceable></arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-analyze</command> may be used to determine - system boot-up performance statistics and retrieve other state and - tracing information from the system and service manager, and to - verify the correctness of unit files.</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 critical-chain - [<replaceable>UNIT...</replaceable>]</command> prints a tree of - the time-critical chain of units (for each of the specified - <replaceable>UNIT</replaceable>s or for the default target - otherwise). The time after the unit is active or started is - printed after the "@" character. The time the unit takes to start - is printed after the "+" character. Note that the output might be - misleading as the initialization of one service might depend on - socket activation and because of the parallel execution of - units.</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><command>systemd-analyze dot</command> generates textual - dependency graph description in dot format for further processing - with the GraphViz - <citerefentry project='die-net'><refentrytitle>dot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - tool. Use a command line like <command>systemd-analyze 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. Optional pattern - globbing style specifications (e.g. <filename>*.target</filename>) - may be given at the end. A unit dependency is included in the - graph if any of these patterns match either the origin or - destination node.</para> - - <para><command>systemd-analyze dump</command> outputs a (usually - very long) human-readable serialization of the complete server - state. Its format is subject to change without notice and should - not be parsed by applications.</para> - - <para><command>systemd-analyze set-log-level - <replaceable>LEVEL</replaceable></command> changes the current log - level of the <command>systemd</command> daemon to - <replaceable>LEVEL</replaceable> (accepts the same values as - <option>--log-level=</option> described in - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>).</para> - - <para><command>systemd-analyze set-log-target - <replaceable>TARGET</replaceable></command> changes the current log - target of the <command>systemd</command> daemon to - <replaceable>TARGET</replaceable> (accepts the same values as - <option>--log-target=</option>, described in - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>).</para> - - <para><command>systemd-analyze verify</command> will load unit - files and print warnings if any errors are detected. Files - specified on the command line will be loaded, but also any other - units referenced by them. This command works by prepending the - directories for all command line arguments at the beginning of the - unit load path, which means that all units files found in those - directories will be used in preference to the unit files found in - the standard locations, even if not listed explicitly.</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>--user</option></term> - - <listitem><para>Operates on the user systemd - instance.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--system</option></term> - - <listitem><para>Operates on the system systemd instance. This - is the implied default.</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 above), 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>Requisite=</varname>, - <varname>Wants=</varname> and <varname>Conflicts=</varname> - are shown. If neither is passed, this shows dependencies of - all these types.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--from-pattern=</option></term> - <term><option>--to-pattern=</option></term> - - <listitem><para>When used in conjunction with the - <command>dot</command> command (see above), this selects which - relationships are shown in the dependency graph. Both options - require a - <citerefentry project='die-net'><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry> - pattern as an argument, which will be matched against the - left-hand and the right-hand, respectively, nodes of a - relationship.</para> - - <para>Each of these can be used more than once, in which case - the unit name must match one of the values. When tests for - both sides of the relation are present, a relation must pass - both tests to be shown. When patterns are also specified as - positional arguments, they must match at least one side of the - relation. In other words, patterns specified with those two - options will trim the list of edges matched by the positional - arguments, if any are given, and fully determine the list of - edges shown otherwise.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--fuzz=</option><replaceable>timespan</replaceable></term> - - <listitem><para>When used in conjunction with the - <command>critical-chain</command> command (see above), also - show units, which finished <replaceable>timespan</replaceable> - earlier, than the latest unit in the same level. The unit of - <replaceable>timespan</replaceable> is seconds unless - specified with a different unit, e.g. - "50ms".</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--no-man</option></term> - - <listitem><para>Do not invoke man to verify the existence of - man pages listed in <varname>Documentation=</varname>. - </para></listitem> - </varlistentry> - - <xi:include href="user-system-options.xml" xpointer="host" /> - <xi:include href="user-system-options.xml" xpointer="machine" /> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - <xi:include href="standard-options.xml" xpointer="no-pager" /> - </variablelist> - - </refsect1> - - <refsect1> - <title>Exit status</title> - - <para>On success, 0 is returned, a non-zero failure code - otherwise.</para> - </refsect1> - - <refsect1> - <title>Examples for <command>dot</command></title> - - <example> - <title>Plots all dependencies of any unit whose name starts with - <literal>avahi-daemon</literal></title> - - <programlisting>$ systemd-analyze dot 'avahi-daemon.*' | dot -Tsvg > avahi.svg - $ eog avahi.svg</programlisting> - </example> - - <example> - <title>Plots the dependencies between all known target units</title> - - <programlisting>systemd-analyze dot --to-pattern='*.target' --from-pattern='*.target' | dot -Tsvg > targets.svg -$ eog targets.svg</programlisting> - </example> - </refsect1> - - <refsect1> - <title>Examples for <command>verify</command></title> - - <para>The following errors are currently detected:</para> - <itemizedlist> - <listitem><para>unknown sections and directives, - </para></listitem> - - <listitem><para>missing dependencies which are required to start - the given unit, </para></listitem> - - <listitem><para>man pages listed in - <varname>Documentation=</varname> which are not found in the - system,</para></listitem> - - <listitem><para>commands listed in <varname>ExecStart=</varname> - and similar which are not found in the system or not - executable.</para></listitem> - </itemizedlist> - - <example> - <title>Misspelt directives</title> - - <programlisting>$ cat ./user.slice -[Unit] -WhatIsThis=11 -Documentation=man:nosuchfile(1) -Requires=different.service - -[Service] -Desription=x - -$ systemd-analyze verify ./user.slice -[./user.slice:9] Unknown lvalue 'WhatIsThis' in section 'Unit' -[./user.slice:13] Unknown section 'Service'. Ignoring. -Error: org.freedesktop.systemd1.LoadFailed: - Unit different.service failed to load: - No such file or directory. -Failed to create user.slice/start: Invalid argument -user.slice: man nosuchfile(1) command failed with code 16 - </programlisting> - </example> - - <example> - <title>Missing service units</title> - - <programlisting>$ tail ./a.socket ./b.socket -==> ./a.socket <== -[Socket] -ListenStream=100 - -==> ./b.socket <== -[Socket] -ListenStream=100 -Accept=yes - -$ systemd-analyze verify ./a.socket ./b.socket -Service a.service not loaded, a.socket cannot be started. -Service b@0.service not loaded, b.socket cannot be started. - </programlisting> - </example> - </refsect1> - - <xi:include href="less-variables.xml" /> - - <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 deleted file mode 100644 index 479e5f2e5b..0000000000 --- a/man/systemd-ask-password-console.service.xml +++ /dev/null @@ -1,93 +0,0 @@ -<?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 project='man-pages'><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 project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-ask-password.xml b/man/systemd-ask-password.xml deleted file mode 100644 index 2b6fb5a82f..0000000000 --- a/man/systemd-ask-password.xml +++ /dev/null @@ -1,227 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <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 standard output. 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: - <itemizedlist> - - <listitem><para>A boot-time password agent asking the user for - passwords using Plymouth</para></listitem> - - <listitem><para>A boot-time password agent querying the user - directly on the console</para></listitem> - - <listitem><para>An agent requesting password input via a - <citerefentry - project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry> - message</para></listitem> - - <listitem><para>A command line agent which can be started - temporarily to process queued password - requests</para></listitem> - - <listitem><para>A TTY agent that is temporarily spawned during - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - invocations</para></listitem> - </itemizedlist></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>--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>--id=</option></term> - <listitem><para>Specify an identifier for this password - query. This identifier is freely choosable and allows - recognition of queries by involved agents. It should include - the subsystem doing the query and the specific object the - query is done for. Example: - <literal>--id=cryptsetup:/dev/sda5</literal>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--keyname=</option></term> - <listitem><para>Configure a kernel keyring key name to use as - cache for the password. If set, then the tool will try to push - any collected passwords into the kernel keyring of the root - user, as a key of the specified name. If combined with - <option>--accept-cached</option>, it will also try to retrieve - such cached passwords from the key in the kernel keyring - instead of querying the user right away. By using this option, - the kernel keyring may be used as effective cache to avoid - repeatedly asking users for passwords, if there are multiple - objects that may be unlocked with the same password. The - cached key will have a timeout of 2.5min set, after which it - will be purged from the kernel keyring. Note that it is - possible to cache multiple passwords under the same keyname, - in which case they will be stored as NUL-separated list of - passwords. Use - <citerefentry project='die-net'><refentrytitle>keyctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - to access the cached key via the kernel keyring - directly. Example: <literal>--keyname=cryptsetup</literal></para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--timeout=</option></term> - - <listitem><para>Specify the query timeout in seconds. Defaults - to 90s. A timeout of 0 waits indefinitely. </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--echo</option></term> - - <listitem><para>Echo the user input instead of masking it. - This is useful when using - <filename>systemd-ask-password</filename> to query for - usernames. </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 entered.</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> - - <varlistentry> - <term><option>--no-output</option></term> - - <listitem><para>Do not print passwords to standard output. - This is useful if you want to store a password in kernel - keyring with <option>--keyname</option> but do not want it - to show up on screen or in logs.</para></listitem> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="help" /> - </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 project='die-net'><refentrytitle>keyctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-backlight@.service.xml b/man/systemd-backlight@.service.xml deleted file mode 100644 index 3459ed8851..0000000000 --- a/man/systemd-backlight@.service.xml +++ /dev/null @@ -1,94 +0,0 @@ -<?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 2013 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-backlight@.service" conditional='ENABLE_BACKLIGHT'> - - <refentryinfo> - <title>systemd-backlight@.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-backlight@.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-backlight@.service</refname> - <refname>systemd-backlight</refname> - <refpurpose>Load and save the display backlight brightness at boot and shutdown</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>systemd-backlight@.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-backlight</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>systemd-backlight@.service</filename> is a service - that restores the display backlight brightness at early boot and - saves it at shutdown. On disk, the backlight brightness is stored - in <filename>/var/lib/systemd/backlight/</filename>. During - loading, if the udev property <option>ID_BACKLIGHT_CLAMP</option> is - not set to false, the brightness is clamped to a value of at - least 1 or 5% of maximum brightness, whichever is greater. This - restriction will be removed when the kernel allows user space to - reliably set a brightness value which does not turn off the - display.</para> - </refsect1> - - <refsect1> - <title>Kernel Command Line</title> - - <para><filename>systemd-backlight</filename> understands the - following kernel command line parameter:</para> - - <variablelist class='kernel-commandline-options'> - <varlistentry> - <term><varname>systemd.restore_state=</varname></term> - - <listitem><para>Takes a boolean argument. Defaults to - <literal>1</literal>. If <literal>0</literal>, does not - restore the backlight settings on boot. However, settings will - still be stored on shutdown. </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-binfmt.service.xml b/man/systemd-binfmt.service.xml deleted file mode 100644 index cccfb49ca9..0000000000 --- a/man/systemd-binfmt.service.xml +++ /dev/null @@ -1,75 +0,0 @@ -<?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" conditional='ENABLE_BINFMT'> - - <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 project='die-net'><refentrytitle>wine</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-cat.xml b/man/systemd-cat.xml deleted file mode 100644 index 160db9fb5c..0000000000 --- a/man/systemd-cat.xml +++ /dev/null @@ -1,178 +0,0 @@ -<?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" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <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 the - standard input and output of a process to 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> - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - - <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 identification - 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 project='man-pages'><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 noindex='true'>/bin/ls</filename> - with standard output and error 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 project='man-pages'><refentrytitle>logger</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-cgls.xml b/man/systemd-cgls.xml deleted file mode 100644 index e8f0368f48..0000000000 --- a/man/systemd-cgls.xml +++ /dev/null @@ -1,139 +0,0 @@ -<?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" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <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</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="opt" rep="repeat">CGROUP</arg> - </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>--all</option></term> - - <listitem><para>Do not hide empty control groups in the - output.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-l</option></term> - <term><option>--full</option></term> - - <listitem><para>Do not ellipsize process tree members.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-k</option></term> - - <listitem><para>Include kernel threads in output. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-M <replaceable>MACHINE</replaceable></option></term> - <term><option>--machine=<replaceable>MACHINE</replaceable></option></term> - - <listitem><para>Limit control groups shown to the part - corresponding to the container - <replaceable>MACHINE</replaceable>.</para></listitem> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - <xi:include href="standard-options.xml" xpointer="no-pager" /> - </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>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-cgtop.xml b/man/systemd-cgtop.xml deleted file mode 100644 index c76f646984..0000000000 --- a/man/systemd-cgtop.xml +++ /dev/null @@ -1,373 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <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</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - </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, or disk I/O load. The display is refreshed in - regular intervals (by default every 1s), similar in style to - <citerefentry project='man-pages'><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> - - <para>If <command>systemd-cgtop</command> is not connected to a - tty, no column headers are printed and the default is to only run - one iteration. The <varname>--iterations=</varname> argument, if - given, is honored. This mode is suitable for scripting.</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>. If resource monitoring for - these resources is required, it is recommended to add the - <varname>CPUAccounting=1</varname>, - <varname>MemoryAccounting=1</varname> and - <varname>BlockIOAccounting=1</varname> settings in the unit files - in question. See - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details.</para> - - <para>The CPU load value can be between 0 and 100 times the number of - processors the system has. For example, if the system has 8 processors, - the CPU load value is going to be between 0% and 800%. The number of - processors can be found in <literal>/proc/cpuinfo</literal>.</para> - - <para>To emphasize this: unless - <literal>CPUAccounting=1</literal>, - <literal>MemoryAccounting=1</literal> and - <literal>BlockIOAccounting=1</literal> are enabled for the - services in question, 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>-p</option></term> - <term><option>--order=path</option></term> - - <listitem><para>Order by control group - path name.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-t</option></term> - <term><option>--order=tasks</option></term> - - <listitem><para>Order by number of tasks/processes in the control group.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-c</option></term> - <term><option>--order=cpu</option></term> - - <listitem><para>Order by CPU load.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-m</option></term> - <term><option>--order=memory</option></term> - - <listitem><para>Order by memory usage.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-i</option></term> - <term><option>--order=io</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>-r</option></term> - <term><option>--raw</option></term> - - <listitem><para>Format byte counts (as in memory usage and I/O metrics) - with raw numeric values rather than human-readable - numbers.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--cpu=percentage</option></term> - <term><option>--cpu=time</option></term> - - <listitem><para>Controls whether the CPU usage is shown as - percentage or time. By default, the CPU usage is shown as - percentage. This setting may also be toggled at runtime by - pressing the <keycap>%</keycap> key.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-P</option></term> - - <listitem><para>Count only userspace processes instead of all - tasks. By default, all tasks are counted: each kernel thread - and each userspace thread individually. With this setting, - kernel threads are excluded from the counting and each - userspace process only counts as one, regardless how many - threads it consists of. This setting may also be toggled at - runtime by pressing the <keycap>P</keycap> key. This option - may not be combined with - <option>-k</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-k</option></term> - - <listitem><para>Count only userspace processes and kernel - threads instead of all tasks. By default, all tasks are - counted: each kernel thread and each userspace thread - individually. With this setting, kernel threads are included in - the counting and each userspace process only counts as on one, - regardless how many threads it consists of. This setting may - also be toggled at runtime by pressing the <keycap>k</keycap> - key. This option may not be combined with - <option>-P</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--recursive=</option></term> - - <listitem><para>Controls whether the number of processes shown - for a control group shall include all processes that are - contained in any of the child control groups as well. Takes a - boolean argument, which defaults to <literal>yes</literal>. If - enabled, the processes in child control groups are included, if - disabled, only the processes in the control group itself are - counted. This setting may also be toggled at runtime by - pressing the <keycap>r</keycap> key. Note that this setting - only applies to process counting, i.e. when the - <option>-P</option> or <option>-k</option> options are - used. It has not effect if all tasks are counted, in which - case the counting is always recursive.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-n</option></term> - <term><option>--iterations=</option></term> - - <listitem><para>Perform only this many iterations. A value of - 0 indicates that the program should run - indefinitely.</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). This setting may also be increased and decreased at - runtime by pressing the <keycap>+</keycap> and - <keycap>-</keycap> keys.</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> - - <varlistentry> - <term><option>-M <replaceable>MACHINE</replaceable></option></term> - <term><option>--machine=<replaceable>MACHINE</replaceable></option></term> - - <listitem><para>Limit control groups shown to the part - corresponding to the container - <replaceable>MACHINE</replaceable>.</para></listitem> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </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><keycap>h</keycap></term> - - <listitem><para>Shows a short help text.</para></listitem> - </varlistentry> - - <varlistentry> - <term><keycap function="space"/></term> - - <listitem><para>Immediately refresh output.</para></listitem> - </varlistentry> - - <varlistentry> - <term><keycap>q</keycap></term> - - <listitem><para>Terminate the program.</para></listitem> - </varlistentry> - - <varlistentry> - <term><keycap>p</keycap></term> - <term><keycap>t</keycap></term> - <term><keycap>c</keycap></term> - <term><keycap>m</keycap></term> - <term><keycap>i</keycap></term> - - <listitem><para>Sort the control groups by path, number of - tasks, CPU load, memory usage, or I/O load, respectively. This - setting may also be controlled using the - <option>--order=</option> command line - switch.</para></listitem> - </varlistentry> - - <varlistentry> - <term><keycap>%</keycap></term> - - <listitem><para>Toggle between showing CPU time as time or - percentage. This setting may also be controlled using the - <option>--cpu=</option> command line switch.</para></listitem> - </varlistentry> - - <varlistentry> - <term><keycap>+</keycap></term> - <term><keycap>-</keycap></term> - - <listitem><para>Increase or decrease refresh delay, - respectively. This setting may also be controlled using the - <option>--delay=</option> command line - switch.</para></listitem> - </varlistentry> - - <varlistentry> - <term><keycap>P</keycap></term> - - <listitem><para>Toggle between counting all tasks, or only - userspace processes. This setting may also be controlled using - the <option>-P</option> command line switch (see - above).</para></listitem> - </varlistentry> - - <varlistentry> - <term><keycap>k</keycap></term> - - <listitem><para>Toggle between counting all tasks, or only - userspace processes and kernel threads. This setting may also - be controlled using the <option>-k</option> command line - switch (see above).</para></listitem> - </varlistentry> - - <varlistentry> - <term><keycap>r</keycap></term> - - <listitem><para>Toggle between recursively including or - excluding processes in child control groups in control group - process counts. This setting may also be controlled using the - <option>--recursive=</option> command line switch. This key is - not available if all tasks are counted, it is only available - if processes are counted, as enabled with the - <keycap>P</keycap> or <keycap>k</keycap> - keys.</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>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-coredump.xml b/man/systemd-coredump.xml deleted file mode 100644 index a28dc62e5a..0000000000 --- a/man/systemd-coredump.xml +++ /dev/null @@ -1,145 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2014 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-coredump" conditional='ENABLE_COREDUMP' - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemd-coredump</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-coredump</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-coredump</refname> - <refname>systemd-coredump.socket</refname> - <refname>systemd-coredump@.service</refname> - <refpurpose>Acquire, save and process core dumps</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/usr/lib/systemd/systemd-coredump</filename></para> - <para><filename>systemd-coredump@.service</filename></para> - <para><filename>systemd-coredump.socket</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - <para><command>systemd-coredump</command> is a system service that can acquire core dumps - from the kernel and handle them in various ways.</para> - - <para>Core dumps can be written to the journal or saved as a file. Once saved they can be retrieved - for further processing, for example in - <citerefentry project='man-pages'><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry>. - </para> - - <para>By default, <command>systemd-coredump</command> will log the core dump including a backtrace - if possible to the journal and store the core dump itself in an external file in - <filename>/var/lib/systemd/coredump</filename>.</para> - - <para>When the kernel invokes <command>systemd-coredump</command> to handle a core dump, - it will connect to the socket created by the <filename>systemd-coredump.socket</filename> - unit, which in turn will spawn a <filename>systemd-coredump@.service</filename> instance - to process the core dump. Hence <filename>systemd-coredump.socket</filename> - and <filename>systemd-coredump@.service</filename> are helper units which do the actual - processing of core dumps and are subject to normal service management.</para> - - <para>The behavior of a specific program upon reception of a signal is governed by a few - factors which are described in detail in - <citerefentry project='man-pages'><refentrytitle>core</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - In particular, the core dump will only be processed when the related resource limits are sufficient. - </para> - </refsect1> - - <refsect1> - <title>Configuration</title> - <para>For programs started by <command>systemd</command> process resource limits can be set by directive - <varname>LimitCore=</varname>, see - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - </para> - - <para>In order to be used <command>systemd-coredump</command> must be configured in - <citerefentry project='man-pages'><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry> - parameter <varname>kernel.core_pattern</varname>. The syntax of this parameter is explained in - <citerefentry project='man-pages'><refentrytitle>core</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - Systemd installs the file <filename>/usr/lib/sysctl.d/50-coredump.conf</filename> which configures - <varname>kernel.core_pattern</varname> accordingly. This file may be masked or overridden to use a different - setting following normal - <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> - rules. - If the sysctl configuration is modified, it must be updated in the kernel before - it takes effect, see - <citerefentry project='man-pages'><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>systemd-sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>. - </para> - - <para>The behaviour of <command>systemd-coredump</command> itself is configured through the configuration file - <filename>/etc/systemd/coredump.conf</filename> and corresponding snippets - <filename>/etc/systemd/coredump.conf.d/*.conf</filename>, see - <citerefentry><refentrytitle>coredump.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. A new - instance of <command>systemd-coredump</command> is invoked upon receiving every core dump. Therefore, changes - in these files will take effect the next time a core dump is received.</para> - - <para>Resources used by core dump files are restricted in two ways. Parameters like maximum size of acquired - core dumps and files can be set in files <filename>/etc/systemd/coredump.conf</filename> and snippets mentioned - above. In addition the storage time of core dump files is restricted by <command>systemd-tmpfiles</command>, - corresponding settings are by default in <filename>/usr/lib/tmpfiles.d/systemd.conf</filename>.</para> - </refsect1> - - <refsect1> - <title>Usage</title> - <para>Data stored in the journal can be viewed with - <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - as usual. - <citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - can be used to retrieve saved core dumps independent of their location, to display information and to process - them e.g. by passing to the GNU debugger (gdb).</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>coredump.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-tmpfiles</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>core</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-sysctl.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. - </para> - </refsect1> -</refentry> diff --git a/man/systemd-cryptsetup-generator.xml b/man/systemd-cryptsetup-generator.xml deleted file mode 100644 index f036ab9744..0000000000 --- a/man/systemd-cryptsetup-generator.xml +++ /dev/null @@ -1,193 +0,0 @@ -<?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" conditional='HAVE_LIBCRYPTSETUP'> - - <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 - <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> - </refsect1> - - <refsect1> - <title>Kernel Command Line</title> - - <para><filename>systemd-cryptsetup-generator</filename> - understands the following kernel command line parameters:</para> - - <variablelist class='kernel-commandline-options'> - <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 superblock UUID as argument. This - will activate the specified device as part of the boot process - as if it was listed in <filename>/etc/crypttab</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> - <para>If /etc/crypttab contains entries with the same UUID, - then the name, keyfile and options specified there will be - used. Otherwise, the device will have the name - <literal>luks-UUID</literal>.</para> - <para>If /etc/crypttab exists, only those UUIDs - specified on the kernel command line - will be activated in the initrd or the real root.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>luks.name=</varname></term> - <term><varname>rd.luks.name=</varname></term> - - <listitem><para>Takes a LUKS super block UUID followed by an - <literal>=</literal> and a name. This implies - <varname>rd.luks.uuid=</varname> or - <varname>luks.uuid=</varname> and will additionally make the - LUKS device given by the UUID appear under the provided - name.</para> - - <para><varname>rd.luks.name=</varname> is honored only by - initial RAM disk (initrd) while <varname>luks.name=</varname> - is honored by both the main system and the initrd.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>luks.options=</varname></term> - <term><varname>rd.luks.options=</varname></term> - - <listitem><para>Takes a LUKS super block UUID followed by an - <literal>=</literal> and a string of options separated by - commas as argument. This will override the options for the - given UUID.</para> - <para>If only a list of options, without an UUID, is - specified, they apply to any UUIDs not specified elsewhere, - and without an entry in - <filename>/etc/crypttab</filename>.</para><para> - <varname>rd.luks.options=</varname> is honored only by initial - RAM disk (initrd) while <varname>luks.options=</varname> is - honored by both the main system and the initrd.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>luks.key=</varname></term> - <term><varname>rd.luks.key=</varname></term> - - <listitem><para>Takes a password file name as argument or a - LUKS super block UUID followed by a <literal>=</literal> and a - password file name.</para> - - <para>For those entries specified with - <varname>rd.luks.uuid=</varname> or - <varname>luks.uuid=</varname>, the password file will be set - to the one specified by <varname>rd.luks.key=</varname> or - <varname>luks.key=</varname> of the corresponding UUID, or the - password file that was specified without a UUID.</para> - <para><varname>rd.luks.key=</varname> - is honored only by initial RAM disk - (initrd) while - <varname>luks.key=</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 project='die-net'><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 deleted file mode 100644 index ea524851eb..0000000000 --- a/man/systemd-cryptsetup@.service.xml +++ /dev/null @@ -1,85 +0,0 @@ -<?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" conditional='HAVE_LIBCRYPTSETUP'> - - <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 project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-debug-generator.xml b/man/systemd-debug-generator.xml deleted file mode 100644 index 5c5e9fc4a1..0000000000 --- a/man/systemd-debug-generator.xml +++ /dev/null @@ -1,95 +0,0 @@ -<?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 2014 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-debug-generator"> - - <refentryinfo> - <title>systemd-debug-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-debug-generator</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-debug-generator</refname> - <refpurpose>Generator for enabling a runtime debug shell and - masking specific units at boot</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/usr/lib/systemd/system-generators/systemd-debug-generator</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>systemd-debug-generator</filename> is a generator - that reads the kernel command line and understands three - options:</para> - - <para>If the <option>systemd.mask=</option> option is specified - and followed by a unit name, this unit is masked for the runtime, - similar to the effect of - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s - <command>mask</command> command. This is useful to boot with - certain units removed from the initial boot transaction for - debugging system startup. May be specified more than once.</para> - - <para>If the <option>systemd.wants=</option> option is specified - and followed by a unit name, a start job for this unit is added to - the initial transaction. This is useful to start one or more - additional units at boot. May be specified more than once.</para> - - <para>If the <option>systemd.debug-shell</option> option is - specified, the debug shell service - <literal>debug-shell.service</literal> is pulled into the boot - transaction. It will spawn a debug shell on tty9 during early - system startup. Note that the shell may also be turned on - persistently by enabling it with - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s - <command>enable</command> command.</para> - - <para><filename>systemd-debug-generator</filename> implements - <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</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>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-delta.xml b/man/systemd-delta.xml deleted file mode 100644 index 99709604aa..0000000000 --- a/man/systemd-delta.xml +++ /dev/null @@ -1,205 +0,0 @@ -<?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" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <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</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="opt" rep="repeat"><replaceable>PREFIX</replaceable><optional>/<replaceable>SUFFIX</replaceable></optional>|<replaceable>SUFFIX</replaceable></arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-delta</command> may be used to identify and - compare configuration files that override other configuration - files. Files in <filename>/etc</filename> have highest priority, - files in <filename>/run</filename> have the second highest - priority, ..., files in <filename>/lib</filename> have lowest - priority. Files in a directory with higher priority override files - with the same name in directories of lower priority. In addition, - certain configuration files can have <literal>.d</literal> - directories which contain "drop-in" files with configuration - snippets which augment the main configuration file. "Drop-in" - files can be overridden in the same way by placing files with the - same name in a directory of higher priority (except that, in case - of "drop-in" files, both the "drop-in" file name and the name of - the containing directory, which corresponds to the name of the - main configuration file, must match). For a fuller explanation, - see - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - </para> - - <para>The command line argument will be split into a prefix and a - suffix. Either is optional. The prefix must be one of the - directories containing configuration files - (<filename>/etc</filename>, <filename>/run</filename>, - <filename>/usr/lib</filename>, ...). If it is given, only - overriding files contained in this directory will be shown. - Otherwise, all overriding files will be shown. The suffix must be - a name of a subdirectory containing configuration files like - <filename>tmpfiles.d</filename>, <filename>sysctl.d</filename> or - <filename>systemd/system</filename>. If it is given, only - configuration files in this subdirectory (across all configuration - paths) will be analyzed. Otherwise, all configuration files will - be analyzed. If the command line argument is not given at all, all - configuration files will be analyzed. See below for some - examples.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>-t</option></term> - <term><option>--type=</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>extended</varname></term> - - <listitem><para>Show <filename>*.conf</filename> files - in drop-in directories for units.</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> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - <xi:include href="standard-options.xml" xpointer="no-pager" /> - </variablelist> - </refsect1> - - <refsect1> - <title>Examples</title> - - <para>To see all local configuration:</para> - <programlisting>systemd-delta</programlisting> - - <para>To see all runtime configuration:</para> - <programlisting>systemd-delta /run</programlisting> - - <para>To see all system unit configuration changes:</para> - <programlisting>systemd-delta systemd/system</programlisting> - - <para>To see all runtime "drop-in" changes for system units:</para> - <programlisting>systemd-delta --type=extended /run/systemd/system</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>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-detect-virt.xml b/man/systemd-detect-virt.xml deleted file mode 100644 index 2b7f4e69ab..0000000000 --- a/man/systemd-detect-virt.xml +++ /dev/null @@ -1,245 +0,0 @@ -<?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" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <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 machine virtualization from - container virtualization. <filename>systemd-detect-virt</filename> - exits with a return value of 0 (success) if a virtualization - technology is detected, and non-zero (error) otherwise. By default, - any type of virtualization is detected, and the options - <option>--container</option> and <option>--vm</option> can be used - to limit what types of virtualization are detected.</para> - - <para>When executed without <option>--quiet</option> will print a - short identifier for the detected virtualization technology. The - following technologies are currently identified:</para> - - <table> - <title>Known virtualization technologies (both - VM, i.e. full hardware virtualization, - and container, i.e. shared kernel virtualization)</title> - <tgroup cols='3' align='left' colsep='1' rowsep='1'> - <colspec colname="type" /> - <colspec colname="id" /> - <colspec colname="product" /> - <thead> - <row> - <entry>Type</entry> - <entry>ID</entry> - <entry>Product</entry> - </row> - </thead> - <tbody> - <row> - <entry valign="top" morerows="9">VM</entry> - <entry><varname>qemu</varname></entry> - <entry>QEMU software virtualization</entry> - </row> - - <row> - <entry><varname>kvm</varname></entry> - <entry>Linux KVM kernel virtual machine</entry> - </row> - - <row> - <entry><varname>zvm</varname></entry> - <entry>s390 z/VM</entry> - </row> - - <row> - <entry><varname>vmware</varname></entry> - <entry>VMware Workstation or Server, and related products</entry> - </row> - - <row> - <entry><varname>microsoft</varname></entry> - <entry>Hyper-V, also known as Viridian or Windows Server Virtualization</entry> - </row> - - <row> - <entry><varname>oracle</varname></entry> - <entry>Oracle VM VirtualBox (historically marketed by innotek and Sun Microsystems)</entry> - </row> - - <row> - <entry><varname>xen</varname></entry> - <entry>Xen hypervisor (only domU, not dom0)</entry> - </row> - - <row> - <entry><varname>bochs</varname></entry> - <entry>Bochs Emulator</entry> - </row> - - <row> - <entry><varname>uml</varname></entry> - <entry>User-mode Linux</entry> - </row> - - <row> - <entry><varname>parallels</varname></entry> - <entry>Parallels Desktop, Parallels Server</entry> - </row> - - <row> - <entry valign="top" morerows="5">Container</entry> - <entry><varname>openvz</varname></entry> - <entry>OpenVZ/Virtuozzo</entry> - </row> - - <row> - <entry><varname>lxc</varname></entry> - <entry>Linux container implementation by LXC</entry> - </row> - - <row> - <entry><varname>lxc-libvirt</varname></entry> - <entry>Linux container implementation by libvirt</entry> - </row> - - <row> - <entry><varname>systemd-nspawn</varname></entry> - <entry>systemd's minimal container implementation, see <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry></entry> - </row> - - <row> - <entry><varname>docker</varname></entry> - <entry>Docker container manager</entry> - </row> - - <row> - <entry><varname>rkt</varname></entry> - <entry>rkt app container runtime</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>If multiple virtualization solutions are used, only the - "innermost" is detected and identified. That means if both - machine 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>-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 hardware virtualization).</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-r</option></term> - <term><option>--chroot</option></term> - - <listitem><para>Detect whether invoked in a - <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>2</manvolnum></citerefentry> - environment. In this mode, no output is written, but the return - value indicates whether the process was invoked in a - <function>chroot()</function> - environment or not.</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> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </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>, - <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>2</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-escape.xml b/man/systemd-escape.xml deleted file mode 100644 index dbb3869a24..0000000000 --- a/man/systemd-escape.xml +++ /dev/null @@ -1,178 +0,0 @@ -<?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 2014 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-escape" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemd-escape</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-escape</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-escape</refname> - <refpurpose>Escape strings for usage in system unit names</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>systemd-escape</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="opt" rep="repeat">STRING</arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-escape</command> may be used to escape - strings for inclusion in systemd unit names. The command may be - used to escape and to undo escaping of strings.</para> - - <para>The command takes any number of strings on the command line, - and will process them individually, one after another. It will - output them separated by spaces to stdout.</para> - - <para>By default, this command will escape the strings passed, - unless <option>--unescape</option> is passed which results in the - inverse operation being applied. If <option>--mangle</option> is given, a - special mode of escaping is applied instead, which assumes the - string is already escaped but will escape everything that - appears obviously non-escaped.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--suffix=</option></term> - - <listitem><para>Appends the specified unit type suffix to the - escaped string. Takes one of the unit types supported by - systemd, such as <literal>.service</literal> or - <literal>.mount</literal>. May not be used in conjunction with - <option>--template=</option>, <option>--unescape</option> or - <option>--mangle</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--template=</option></term> - - <listitem><para>Inserts the escaped strings in a unit name - template. Takes a unit name template such as - <filename>foobar@.service</filename> May not be used in - conjunction with <option>--suffix=</option>, - <option>--unescape</option> or - <option>--mangle</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--path</option></term> - <term><option>-p</option></term> - - <listitem><para>When escaping or unescaping a string, assume - it refers to a file system path. This enables special - processing of the initial <literal>/</literal> of the - path.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--unescape</option></term> - - <listitem><para>Instead of escaping the specified strings, - undo the escaping, reversing the operation. May not be used in - conjunction with <option>--suffix=</option>, - <option>--template=</option> or - <option>--mangle</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--mangle</option></term> - - <listitem><para>Like <option>--escape</option>, but only - escape characters that are obviously not escaped yet, and - possibly automatically append an appropriate unit type suffix - to the string. May not be used in conjunction with - <option>--suffix=</option>, <option>--template=</option> or - <option>--unescape</option>.</para></listitem> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </variablelist> - - </refsect1> - - <refsect1> - <title>Examples</title> - - <para>Escape a single string:</para> - <programlisting>$ systemd-escape 'Hallöchen, Meister' -Hall\xc3\xb6chen\x2c\x20Meister</programlisting> - - <para>To undo escaping on a single string:</para> - <programlisting>$ systemd-escape -u 'Hall\xc3\xb6chen\x2c\x20Meister' -Hallöchen, Meister</programlisting> - - <para>To generate the mount unit for a path:</para> - <programlisting>$ systemd-escape -p --suffix=mount "/tmp//waldi/foobar/" -tmp-waldi-foobar.mount</programlisting> - - <para>To generate instance names of three strings</para> - <programlisting>$ systemd-escape --template=systemd-nspawn@.service 'My Container 1' 'containerb' 'container/III' -systemd-nspawn@My\x20Container\x201.service systemd-nspawn@containerb.service systemd-nspawn@container-III.service</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>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-firstboot.xml b/man/systemd-firstboot.xml deleted file mode 100644 index b269e48113..0000000000 --- a/man/systemd-firstboot.xml +++ /dev/null @@ -1,259 +0,0 @@ -<?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 2014 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-firstboot" conditional='ENABLE_FIRSTBOOT' - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemd-firstboot</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-firstboot</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-firstboot</refname> - <refname>systemd-firstboot.service</refname> - <refpurpose>Initialize basic system settings on or before the first boot-up of a system</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>systemd-firstboot</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - </cmdsynopsis> - - <para><filename>systemd-firstboot.service</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-firstboot</command> initializes the most - basic system settings interactively on the first boot, or - optionally non-interactively when a system image is created. The - following settings may be set up:</para> - - <itemizedlist> - <listitem><para>The system locale, more specifically the two - locale variables <varname>LANG=</varname> and - <varname>LC_MESSAGES</varname></para></listitem> - - <listitem><para>The system time zone</para></listitem> - - <listitem><para>The system host name</para></listitem> - - <listitem><para>The machine ID of the system</para></listitem> - - <listitem><para>The root user's password</para></listitem> - </itemizedlist> - - <para>Each of the fields may either be queried interactively by - users, set non-interactively on the tool's command line, or be - copied from a host system that is used to set up the system - image.</para> - - <para>If a setting is already initialized, it will not be - overwritten and the user will not be prompted for the - setting.</para> - - <para>Note that this tool operates directly on the file system and - does not involve any running system services, unlike - <citerefentry project='man-pages'><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - or - <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. - This allows <command>systemd-firstboot</command> to operate on - mounted but not booted disk images and in early boot. It is not - recommended to use <command>systemd-firstboot</command> on the - running system while it is up.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--root=<replaceable>root</replaceable></option></term> - <listitem><para>Takes a directory path as an argument. All - paths will be prefixed with the given alternate - <replaceable>root</replaceable> path, including config search - paths. This is useful to operate on a system image mounted to - the specified directory instead of the host system itself. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--locale=<replaceable>LOCALE</replaceable></option></term> - <term><option>--locale-messages=<replaceable>LOCALE</replaceable></option></term> - - <listitem><para>Sets the system locale, more specifically the - <varname>LANG=</varname> and <varname>LC_MESSAGES</varname> - settings. The argument should be a valid locale identifier, - such as <literal>de_DE.UTF-8</literal>. This controls the - <citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - configuration file.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--timezone=<replaceable>TIMEZONE</replaceable></option></term> - - <listitem><para>Sets the system time zone. The argument should - be a valid time zone identifier, such as - <literal>Europe/Berlin</literal>. This controls the - <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry> - symlink.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--hostname=<replaceable>HOSTNAME</replaceable></option></term> - - <listitem><para>Sets the system hostname. The argument should - be a host name, compatible with DNS. This controls the - <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry> - configuration file.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--machine-id=<replaceable>ID</replaceable></option></term> - - <listitem><para>Sets the system's machine ID. This controls - the - <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> - file.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--root-password=<replaceable>PASSWORD</replaceable></option></term> - <term><option>--root-password-file=<replaceable>PATH</replaceable></option></term> - - <listitem><para>Sets the password of the system's root user. - This creates a - <citerefentry project='die-net'><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry> - file. This setting exists in two forms: - <option>--root-password=</option> accepts the password to set - directly on the command line, and - <option>--root-password-file=</option> reads it from a file. - Note that it is not recommended to specify passwords on the - command line, as other users might be able to see them simply - by invoking - <citerefentry project='die-net'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--prompt-locale</option></term> - <term><option>--prompt-timezone</option></term> - <term><option>--prompt-hostname</option></term> - <term><option>--prompt-root-password</option></term> - - <listitem><para>Prompt the user interactively for a specific - basic setting. Note that any explicit configuration settings - specified on the command line take precedence, and the user is - not prompted for it.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--prompt</option></term> - - <listitem><para>Query the user for locale, timezone, hostname - and root password. This is equivalent to specifying - <option>--prompt-locale</option>, - <option>--prompt-timezone</option>, - <option>--prompt-hostname</option>, - <option>--prompt-root-password</option> in combination.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--copy-locale</option></term> - <term><option>--copy-timezone</option></term> - <term><option>--copy-root-password</option></term> - - <listitem><para>Copy a specific basic setting from the host. - This only works in combination with <option>--root=</option> - (see above).</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--copy</option></term> - - <listitem><para>Copy locale, time zone and root password from - the host. This is equivalent to specifying - <option>--copy-locale</option>, - <option>--copy-timezone</option>, - <option>--copy-root-password</option> in combination.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--setup-machine-id</option></term> - - <listitem><para>Initialize the system's machine ID to a random - ID. This only works in combination with - <option>--root=</option>.</para></listitem> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </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 project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-fsck@.service.xml b/man/systemd-fsck@.service.xml deleted file mode 100644 index 933c3247ad..0000000000 --- a/man/systemd-fsck@.service.xml +++ /dev/null @@ -1,139 +0,0 @@ -<?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> and - <filename>systemd-fsck-root.service</filename> are services - responsible for file system checks. They are instantiated for each - device that is configured for file system checking. - <filename>systemd-fsck-root.service</filename> is responsible for - file system checks on the root file system, but only if the - root filesystem was not checked in the initramfs. - <filename>systemd-fsck@.service</filename> is used for all other - file systems and for the root file system in the initramfs.</para> - - <para>These services are started at boot if - <option>passno</option> in <filename>/etc/fstab</filename> for the - file system is set to a value greater than zero. The file system - check for root is performed before the other file systems. Other - file systems may be checked in parallel, except when they are on - the same rotating disk.</para> - - <para><filename>systemd-fsck</filename> does not know any details - about specific filesystems, and simply executes file system - checkers specific to each filesystem type - (<filename>/sbin/fsck.*</filename>). This helper will decide if - the filesystem should actually be checked based on the time since - last check, number of mounts, unclean unmount, etc.</para> - - <para>If a file system check fails for a service without - <option>nofail</option>, 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 class='kernel-commandline-options'> - <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> - - <varlistentry> - <term><varname>fsck.repair=</varname></term> - - <listitem><para>One of <literal>preen</literal>, - <literal>yes</literal>, <literal>no</literal>. Controls the - mode of operation. The default is <literal> preen</literal>, - and will automatically repair problems that can be safely - fixed. <literal>yes </literal> will answer yes to all - questions by fsck and <literal>no</literal> will answer no to - all questions. </para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>fsck</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-quotacheck.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>fsck.btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>fsck.cramfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>fsck.ext4</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>fsck.fat</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>fsck.hfsplus</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>fsck.minix</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>fsck.ntfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>fsck.xfs</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-fstab-generator.xml b/man/systemd-fstab-generator.xml deleted file mode 100644 index a971cb3675..0000000000 --- a/man/systemd-fstab-generator.xml +++ /dev/null @@ -1,183 +0,0 @@ -<?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 project='man-pages'><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>The <varname>passno</varname> field is treated like a simple - boolean, and the ordering information is discarded. However, if - the root file system is checked, it is checked before all the - other file systems.</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 - <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> - </refsect1> - - <refsect1> - <title>Kernel Command Line</title> - - <para><filename>systemd-fstab-generator</filename> understands the - following kernel command line parameters:</para> - - <variablelist class='kernel-commandline-options'> - - <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>fstab=</varname> is honored by both the main system - and the initrd.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>root=</varname></term> - - <listitem><para>Takes the root filesystem to mount in the - initrd. <varname>root=</varname> is honored by the - initrd.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>rootfstype=</varname></term> - - <listitem><para>Takes the root filesystem type that will be - passed to the mount command. <varname>rootfstype=</varname> is - honored by the initrd.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>rootflags=</varname></term> - - <listitem><para>Takes the root filesystem mount options to - use. <varname>rootflags=</varname> is honored by the - initrd.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>mount.usr=</varname></term> - - <listitem><para>Takes the <filename>/usr</filename> filesystem - to be mounted by the initrd. If - <varname>mount.usrfstype=</varname> or - <varname>mount.usrflags=</varname> is set, then - <varname>mount.usr=</varname> will default to the value set in - <varname>root=</varname>.</para> - - <para>Otherwise, this parameter defaults to the - <filename>/usr</filename> entry found in - <filename>/etc/fstab</filename> on the root filesystem.</para> - - <para><varname>mount.usr=</varname> is honored by the initrd. - </para></listitem> - </varlistentry> - <varlistentry> - <term><varname>mount.usrfstype=</varname></term> - - <listitem><para>Takes the <filename>/usr</filename> filesystem - type that will be passed to the mount command. If - <varname>mount.usr=</varname> or - <varname>mount.usrflags=</varname> is set, then - <varname>mount.usrfstype=</varname> will default to the value - set in <varname>rootfstype=</varname>.</para> - - <para>Otherwise, this value will be read from the - <filename>/usr</filename> entry in - <filename>/etc/fstab</filename> on the root filesystem.</para> - - <para><varname>mount.usrfstype=</varname> is honored by the - initrd.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>mount.usrflags=</varname></term> - - <listitem><para>Takes the <filename>/usr</filename> filesystem - mount options to use. If <varname>mount.usr=</varname> or - <varname>mount.usrfstype=</varname> is set, then - <varname>mount.usrflags=</varname> will default to the value - set in <varname>rootflags=</varname>.</para> - - <para>Otherwise, this value will be read from the - <filename>/usr</filename> entry in - <filename>/etc/fstab</filename> on the root filesystem.</para> - - <para><varname>mount.usrflags=</varname> is honored by the - initrd.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='man-pages'><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 deleted file mode 100644 index 338925964d..0000000000 --- a/man/systemd-getty-generator.xml +++ /dev/null @@ -1,96 +0,0 @@ -<?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. Finally, it will instantiate - <filename>container-getty@.service</filename> instances for - additional container pseudo TTYs as requested by the container - manager (see <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface/"><filename>Container - Interface</filename></ulink>). This should ensure that the user is - shown a login prompt at the right place, regardless of which - environment the system is started in. 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 - <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> - - <para>Further information about configuration of gettys you may - find in - <ulink url="http://0pointer.de/blog/projects/serial-console.html">systemd - for Administrators, Part XVI: Gettys on Serial Consoles (and - Elsewhere)</ulink>.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>agetty</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-gpt-auto-generator.xml b/man/systemd-gpt-auto-generator.xml deleted file mode 100644 index e890c4dce2..0000000000 --- a/man/systemd-gpt-auto-generator.xml +++ /dev/null @@ -1,186 +0,0 @@ -<?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 2013 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-gpt-auto-generator"> - - <refentryinfo> - <title>systemd-gpt-auto-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-gpt-auto-generator</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-gpt-auto-generator</refname> - <refpurpose>Generator for automatically discovering - and mounting root, <filename>/home</filename> and - <filename>/srv</filename> partitions, as well as - discovering and enabling swap partitions, based on GPT - partition type GUIDs.</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/usr/lib/systemd/system-generators/systemd-gpt-auto-generator</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>systemd-gpt-auto-generator</filename> is a unit - generator that automatically discovers root, - <filename>/home</filename>, <filename>/srv</filename> and swap - partitions and creates mount and swap units for them, based on the - partition type GUIDs of GUID partition tables (GPT). It implements - the <ulink - url="http://www.freedesktop.org/wiki/Specifications/DiscoverablePartitionsSpec/">Discoverable - Partitions Specification</ulink>. Note that this generator has no - effect on non-GPT systems, or where the directories under the - mount points are already non-empty. Also, on systems where the - units are explicitly configured (for example, listed in - <citerefentry - project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>), - the units this generator creates are overridden, but additional - automatic dependencies might be created.</para> - - <para>This generator will only look for root partitions on the - same physical disk the EFI System Partition (ESP) is located on. - It will only look for the other partitions on the same physical - disk the root file system is located on. These partitions will not - be searched on systems where the root file system is distributed - on multiple disks, for example via btrfs RAID.</para> - - <para><filename>systemd-gpt-auto-generator</filename> is useful - for centralizing file system configuration in the partition table - and making manual configuration in <filename>/etc/fstab</filename> - or suchlike unnecessary.</para> - - <para>This generator looks for the partitions based on their - partition type GUID. The following partition type GUIDs are - identified:</para> - - <table> - <title>Partition Type GUIDs</title> - <tgroup cols='3' align='left' colsep='1' rowsep='1'> - <colspec colname="guid" /> - <colspec colname="name" /> - <colspec colname="explanation" /> - <thead> - <row> - <entry>Partition Type GUID</entry> - <entry>Name</entry> - <entry>Explanation</entry> - </row> - </thead> - <tbody> - <row> - <entry>44479540-f297-41b2-9af7-d131d5f0458a</entry> - <entry><filename>Root Partition (x86)</filename></entry> - <entry>On 32-bit x86 systems, the first x86 root partition on the disk the EFI ESP is located on is mounted to the root directory <filename>/</filename>.</entry> - </row> - <row> - <entry>4f68bce3-e8cd-4db1-96e7-fbcaf984b709</entry> - <entry><filename>Root Partition (x86-64)</filename></entry> - <entry>On 64-bit x86 systems, the first x86-64 root partition on the disk the EFI ESP is located on is mounted to the root directory <filename>/</filename>.</entry> - </row> - <row> - <entry>69dad710-2ce4-4e3c-b16c-21a1d49abed3</entry> - <entry><filename>Root Partition (32-bit ARM)</filename></entry> - <entry>On 32-bit ARM systems, the first ARM root partition on the disk the EFI ESP is located on is mounted to the root directory <filename>/</filename>.</entry> - </row> - <row> - <entry>b921b045-1df0-41c3-af44-4c6f280d3fae</entry> - <entry><filename>Root Partition (64-bit ARM)</filename></entry> - <entry>On 64-bit ARM systems, the first ARM root partition on the disk the EFI ESP is located on is mounted to the root directory <filename>/</filename>.</entry> - </row> - <row> - <entry>933ac7e1-2eb4-4f13-b844-0e14e2aef915</entry> - <entry>Home Partition</entry> - <entry>The first home partition on the disk the root partition is located on is mounted to <filename>/home</filename>.</entry> - </row> - <row> - <entry>3b8f8425-20e0-4f3b-907f-1a25a76f98e8</entry> - <entry>Server Data Partition</entry> - <entry>The first server data partition on the disk the root partition is located on is mounted to <filename>/srv</filename>.</entry> - </row> - <row> - <entry>0657fd6d-a4ab-43c4-84e5-0933c84b4f4f</entry> - <entry>Swap</entry> - <entry>All swap partitions located on the disk the root partition is located on are enabled.</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>The <filename>/home</filename> and <filename>/srv</filename> - partitions may be encrypted in LUKS format. In this case, a device - mapper device is set up under the names - <filename>/dev/mapper/home</filename> and - <filename>/dev/mapper/srv</filename>. Note that this might create - conflicts if the same partition is listed in - <filename>/etc/crypttab</filename> with a different device mapper - device name.</para> - - <para>Mount and automount units for the EFI System Partition (ESP), - mounting it to <filename>/boot</filename>, are generated on EFI - systems where the boot loader communicates the used ESP to the operating - system. Since this generator creates an automount unit, the mount will - only be activated on-demand, when accessed. On systems where - <filename>/boot</filename> is an explicitly configured mount - (for example, listed in - <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>) - or where the <filename>/boot</filename> mount point is non-empty, no - mount units are generated.</para> - - <para>When using this generator in conjunction with btrfs file - systems, make sure to set the correct default subvolumes on them, - using <command>btrfs subvolume set-default</command>.</para> - - <para><filename>systemd-gpt-auto-generator</filename> implements - <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-halt.service.xml b/man/systemd-halt.service.xml deleted file mode 100644 index c94e2a1820..0000000000 --- a/man/systemd-halt.service.xml +++ /dev/null @@ -1,118 +0,0 @@ -<?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. Similarly, - <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>It is necessary to have this code in a separate binary - because otherwise rebooting after an upgrade might be broken — the - running PID 1 could still depend on libraries which are not - available any more, thus keeping the file system busy, which then - cannot be re-mounted read-only.</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-hibernate-resume-generator.xml b/man/systemd-hibernate-resume-generator.xml deleted file mode 100644 index d811b9b551..0000000000 --- a/man/systemd-hibernate-resume-generator.xml +++ /dev/null @@ -1,93 +0,0 @@ -<?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 2014 Ivan Shapovalov - - 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-hibernate-resume-generator"> - - <refentryinfo> - <title>systemd-hibernate-resume-generator</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Ivan</firstname> - <surname>Shapovalov</surname> - <email>intelfx100@gmail.com</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd-hibernate-resume-generator</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-hibernate-resume-generator</refname> - <refpurpose>Unit generator for resume= kernel parameter</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/usr/lib/systemd/system-generators/systemd-hibernate-resume-generator</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>systemd-hibernate-resume-generator</filename> is a - generator that instantiates - <citerefentry><refentrytitle>systemd-hibernate-resume@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - unit according to the value of <option>resume=</option> parameter - specified on the kernel command line.</para> - </refsect1> - - <refsect1> - <title>Kernel Command Line</title> - - <para><filename>systemd-hibernate-resume-generator</filename> - understands the following kernel command line parameters:</para> - - <variablelist class='kernel-commandline-options'> - - <varlistentry> - <term><varname>resume=</varname></term> - - <listitem><para>Takes a path to the resume device. Both - persistent block device paths like - <filename>/dev/disk/by-foo/bar</filename> and - <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>-style - specifiers like <literal>FOO=bar</literal> are - supported.</para></listitem> - </varlistentry> - - </variablelist> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-hibernate-resume@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-hibernate-resume@.service.xml b/man/systemd-hibernate-resume@.service.xml deleted file mode 100644 index 7d00827447..0000000000 --- a/man/systemd-hibernate-resume@.service.xml +++ /dev/null @@ -1,81 +0,0 @@ -<?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 2014 Ivan Shapovalov - - 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-hibernate-resume@.service"> - - <refentryinfo> - <title>systemd-hibernate-resume@.service</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Ivan</firstname> - <surname>Shapovalov</surname> - <email>intelfx100@gmail.com</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd-hibernate-resume@.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-hibernate-resume@.service</refname> - <refname>systemd-hibernate-resume</refname> - <refpurpose>Resume from hibernation</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>systemd-hibernate-resume@.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-hibernate-resume</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>systemd-hibernate-resume@.service</filename> - initiates the resume from hibernation. It is instantiated with the - device to resume from as the template argument.</para> - - <para><filename>systemd-hibernate-resume</filename> only supports - the in-kernel hibernation implementation, known as - <ulink url="https://www.kernel.org/doc/Documentation/power/swsusp.txt">swsusp</ulink>. - Internally, it works by writing the major:minor of specified - device node to <filename>/sys/power/resume</filename>.</para> - - <para>Failing to initiate a resume is not an error condition. It - may mean that there was no resume image (e. g. if the system has - been simply powered off and not hibernated). In such case, the - boot is ordinarily continued.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-hibernate-resume-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-hostnamed.service.xml b/man/systemd-hostnamed.service.xml deleted file mode 100644 index 6990d41b02..0000000000 --- a/man/systemd-hostnamed.service.xml +++ /dev/null @@ -1,85 +0,0 @@ -<?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" conditional='ENABLE_HOSTNAMED'> - - <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>Host name 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 a mechanism to change the system's 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-hwdb.xml b/man/systemd-hwdb.xml deleted file mode 100644 index 2b363c77f2..0000000000 --- a/man/systemd-hwdb.xml +++ /dev/null @@ -1,93 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - -<refentry id="systemd-hwdb" conditional="ENABLE_HWDB"> - <refentryinfo> - <title>systemd-hwdb</title> - <productname>systemd</productname> - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Kay</firstname> - <surname>Sievers</surname> - <email>kay@vrfy.org</email> - </author> - <author> - <contrib>Developer</contrib> - <firstname>Tom</firstname> - <surname>Gundersen</surname> - <email>teg@jklm.no</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd-hwdb</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-hwdb</refname><refpurpose>hardware database management tool</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>systemd-hwdb <optional>options</optional> update</command> - </cmdsynopsis> - <cmdsynopsis> - <command>systemd-hwdb <optional>options</optional> query <replaceable>modalias</replaceable></command> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1><title>Description</title> - <para><command>systemd-hwdb</command> expects a command and command - specific arguments. It manages the binary hardware database.</para> - </refsect1> - - <refsect1><title>Options</title> - <variablelist> - <varlistentry> - <term><option>-h</option></term> - <term><option>--help</option></term> - <listitem> - <para>Print help text.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--usr</option></term> - <listitem> - <para>Generate in /usr/lib/udev instead of /etc/udev.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>-r</option></term> - <term><option>--root=<replaceable>PATH</replaceable></option></term> - <listitem> - <para>Alternate root path in the filesystem.</para> - </listitem> - </varlistentry> - </variablelist> - - <refsect2><title>systemd-hwdb - <arg choice="opt"><replaceable>options</replaceable></arg> - update</title> - <para>Update the binary database.</para> - </refsect2> - - <refsect2><title>systemd-hwdb - <arg choice="opt"><replaceable>options</replaceable></arg> - query - <arg><replaceable>MODALIAS</replaceable></arg> - </title> - <para>Query database and print result.</para> - </refsect2> - </refsect1> - - <refsect1> - <title>See Also</title> - <para><citerefentry> - <refentrytitle>hwdb</refentrytitle><manvolnum>7</manvolnum> - </citerefentry></para> - </refsect1> -</refentry> diff --git a/man/systemd-importd.service.xml b/man/systemd-importd.service.xml deleted file mode 100644 index 8fdced475c..0000000000 --- a/man/systemd-importd.service.xml +++ /dev/null @@ -1,82 +0,0 @@ -<?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 2016 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-importd.service" conditional='ENABLE_IMPORTD'> - - <refentryinfo> - <title>systemd-importd.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-importd.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-importd.service</refname> - <refname>systemd-importd</refname> - <refpurpose>VM and container image import and export service</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>systemd-importd.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-importd</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-importd</command> is a system service that allows importing, exporting and downloading of - system images suitable for running as VM or containers. It is a companion service for - <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, and provides the implementation for - <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s - <command>pull-raw</command>, <command>pull-tar</command>, <command>import-raw</command>, - <command>import-tar</command>, <command>export-raw</command>, and <command>export-tar</command> commands.</para> - - <para>See the - <ulink url="http://www.freedesktop.org/wiki/Software/systemd/importd"> - importd D-Bus API Documentation</ulink> for information about the - APIs <filename>systemd-importd</filename> provides.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-inhibit.xml b/man/systemd-inhibit.xml deleted file mode 100644 index 9d85908f97..0000000000 --- a/man/systemd-inhibit.xml +++ /dev/null @@ -1,177 +0,0 @@ -<?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" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <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>--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>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> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </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 project='man-pages'><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>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-initctl.service.xml b/man/systemd-initctl.service.xml deleted file mode 100644 index 5c7f9a4a16..0000000000 --- a/man/systemd-initctl.service.xml +++ /dev/null @@ -1,76 +0,0 @@ -<?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-journal-gatewayd.service.xml b/man/systemd-journal-gatewayd.service.xml deleted file mode 100644 index 9ed85c3950..0000000000 --- a/man/systemd-journal-gatewayd.service.xml +++ /dev/null @@ -1,302 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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-journal-gatewayd.service" conditional='HAVE_MICROHTTPD' - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemd-journal-gatewayd.service</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-journal-gatewayd.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-journal-gatewayd.service</refname> - <refname>systemd-journal-gatewayd.socket</refname> - <refname>systemd-journal-gatewayd</refname> - <refpurpose>HTTP server for journal events</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>systemd-journal-gatewayd.service</filename></para> - <para><filename>systemd-journal-gatewayd.socket</filename></para> - <cmdsynopsis> - <command>/usr/lib/systemd/systemd-journal-gatewayd</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-journal-gatewayd</command> serves journal - events over the network. Clients must connect using - HTTP. The server listens on port 19531 by default. - If <option>--cert=</option> is specified, the server expects - HTTPS connections.</para> - - <para>The program is started by - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> - and expects to receive a single socket. Use - <command>systemctl start systemd-journal-gatewayd.socket</command> to start - the service, and <command>systemctl enable systemd-journal-gatewayd.socket</command> - to have it started on boot.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--cert=</option></term> - - <listitem><para>Specify the path to a file containing a server - certificate in PEM format. This option switches - <command>systemd-journal-gatewayd</command> into HTTPS mode - and must be used together with - <option>--key=</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--key=</option></term> - - <listitem><para>Specify the path to a file containing a server - key in PEM format corresponding to the certificate specified - with <option>--cert=</option>.</para></listitem> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </variablelist> - </refsect1> - - <refsect1> - <title>Supported URLs</title> - - <para>The following URLs are recognized:</para> - - <variablelist> - <varlistentry> - <term><uri>/browse</uri></term> - - <listitem><para>Interactive browsing.</para></listitem> - </varlistentry> - - <varlistentry> - <term><uri>/entries[?option1&option2=value...]</uri></term> - - <listitem><para>Retrieval of events in various formats.</para> - - <para>The <option>Accept:</option> part of the HTTP header - determines the format. Supported values are described below. - </para> - - <para>The <option>Range:</option> part of the HTTP header - determines the range of events returned. Supported values are - described below. - </para> - - <para>GET parameters can be used to modify what events are - returned. Supported parameters are described below.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><uri>/machine</uri></term> - - <listitem><para>Return a JSON structure describing the machine.</para> - - <para>Example: - <programlisting>{ "machine_id" : "8cf7ed9d451ea194b77a9f118f3dc446", - "boot_id" : "3d3c9efaf556496a9b04259ee35df7f7", - "hostname" : "fedora", - "os_pretty_name" : "Fedora 19 (Rawhide)", - "virtualization" : "kvm", - ...}</programlisting> - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><uri>/fields/<replaceable>FIELD_NAME</replaceable></uri></term> - - <listitem><para>Return a list of values of this field present in the logs.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Accept header</title> - - <para> - <option>Accept: <replaceable>format</replaceable></option> - </para> - - <para>Recognized formats:</para> - - <variablelist> - <varlistentry> - <term><constant>text/plain</constant></term> - - <listitem><para>The default. Plaintext syslog-like output, - one line per journal entry - (like <command>journalctl --output short</command>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><constant>application/json</constant></term> - - <listitem><para>Entries are formatted as JSON data structures, - one per line - (like <command>journalctl --output json</command>). - See <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/json">Journal - JSON Format</ulink> for more information.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><constant>text/event-stream</constant></term> - - <listitem><para>Entries are formatted as JSON data structures, - wrapped 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> - (like <command>journalctl --output json-sse</command>). - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><constant>application/vnd.fdo.journal</constant></term> - - <listitem><para>Entries are serialized into a binary (but - mostly text-based) stream suitable for backups and network - transfer - (like <command>journalctl --output export</command>). - See <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/export">Journal - Export Format</ulink> for more information.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Range header</title> - - <para> - <option>Range: entries=<replaceable>cursor</replaceable>[[:<replaceable>num_skip</replaceable>]:<replaceable>num_entries</replaceable>]</option> - </para> - - <para>where - <option>cursor</option> is a cursor string, - <option>num_skip</option> is an integer, - <option>num_entries</option> is an unsigned integer. - </para> - - <para>Range defaults to all available events.</para> - </refsect1> - - <refsect1> - <title>URL GET parameters</title> - - <para>Following parameters can be used as part of the URL:</para> - - <variablelist> - <varlistentry> - <term><uri>follow</uri></term> - - <listitem><para>wait for new events - (like <command>journalctl --follow</command>, except that - the number of events returned is not limited).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><uri>discrete</uri></term> - - <listitem><para>Test that the specified cursor refers to an - entry in the journal. Returns just this entry.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><uri>boot</uri></term> - - <listitem><para>Limit events to the current boot of the system - (like <command>journalctl --this-boot</command>).</para></listitem> - </varlistentry> - - <varlistentry> - <term><uri><replaceable>KEY</replaceable>=<replaceable>match</replaceable></uri></term> - - <listitem><para>Match journal fields. See - <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Examples</title> - <para>Retrieve events from this boot from local journal - in <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/export">Journal - Export Format</ulink>: - <programlisting>curl --silent -H'Accept: application/vnd.fdo.journal' \ - 'http://localhost:19531/entries?boot'</programlisting> - </para> - - <para>Listen for core dumps: - <programlisting>curl 'http://localhost:19531/entries?follow&MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1'</programlisting></para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-journal-remote.xml b/man/systemd-journal-remote.xml deleted file mode 100644 index 3899f175d4..0000000000 --- a/man/systemd-journal-remote.xml +++ /dev/null @@ -1,325 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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-journal-remote" conditional='HAVE_MICROHTTPD' - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemd-journal-remote</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-journal-remote</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-journal-remote</refname> - <refpurpose>Receive journal messages over the network</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>systemd-journal-remote</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="opt" rep="norepeat">-o/--output=<replaceable>DIR</replaceable>|<replaceable>FILE</replaceable></arg> - <arg choice="opt" rep="repeat">SOURCES</arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para> - <filename>systemd-journal-remote</filename> is a command to - receive serialized journal events and store them to the journal. - Input streams are in the - <ulink url="http://www.freedesktop.org/wiki/Software/systemd/export"> - Journal Export Format - </ulink>, - i.e. like the output from - <command>journalctl --output=export</command>. For transport over - the network, this serialized stream is usually carried over an - HTTPS connection. - </para> - </refsect1> - - <refsect1> - <title>Sources</title> - - <para> - Sources can be either "active" - (<command>systemd-journal-remote</command> requests and pulls - the data), or "passive" - (<command>systemd-journal-remote</command> waits for a - connection and then receives events pushed by the other side). - </para> - - <para> - <command>systemd-journal-remote</command> can read more than one - event stream at a time. They will be interleaved in the output - file. In case of "active" connections, each "source" is one - stream, and in case of "passive" connections, each connection can - result in a separate stream. Sockets can be configured in - "accept" mode (i.e. only one connection), or "listen" mode (i.e. - multiple connections, each resulting in a stream). - </para> - - <para> - When there are no more connections, and no more can be created - (there are no listening sockets), then - <command>systemd-journal-remote</command> will exit. - </para> - - <para>Active sources can be specified in the following - ways:</para> - - <variablelist> - <varlistentry> - <listitem><para>When <option>-</option> is given as a - positional argument, events will be read from standard input. - Other positional arguments will be treated as filenames - to open and read from.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--url=<replaceable>ADDRESS</replaceable></option></term> - - <listitem><para>With the - <option>--url=<replaceable>ADDRESS</replaceable></option> option, - events will be retrieved using HTTP from - <replaceable>ADDRESS</replaceable>. This URL should refer to the - root of a remote - <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry> - instance (e.g. <ulink>http://some.host:19531/</ulink> or - <ulink>https://some.host:19531/</ulink>).</para></listitem> - </varlistentry> - </variablelist> - - <para>Passive sources can be specified in the following - ways:</para> - - <variablelist> - <varlistentry> - <term><option>--listen-raw=<replaceable>ADDRESS</replaceable></option></term> - - <listitem><para><replaceable>ADDRESS</replaceable> must be an - address suitable for <option>ListenStream=</option> (cf. - <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>). - <command>systemd-journal-remote</command> will listen on this - socket for connections. Each connection is expected to be a - stream of journal events.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--listen-http=<replaceable>ADDRESS</replaceable></option></term> - <term><option>--listen-https=<replaceable>ADDRESS</replaceable></option></term> - - <listitem><para><replaceable>ADDRESS</replaceable> must be - either a negative integer, in which case it will be - interpreted as the (negated) file descriptor number, or an - address suitable for <option>ListenStream=</option> (c.f. - <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>). - In the first case, matching file descriptor must be inherited - through - <varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname>. - In the second case, an HTTP or HTTPS server will be spawned on - this port, respectively for <option>--listen-http</option> and - <option>--listen-https</option>. Currently, only POST requests - to <filename>/upload</filename> with <literal>Content-Type: - application/vnd.fdo.journal</literal> are supported.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>$LISTEN_FDS</varname></term> - - <listitem><para><command>systemd-journal-remote</command> - supports the - <varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname> - protocol. Open sockets inherited through socket activation - behave like those opened with <option>--listen-raw=</option> - described above, unless they are specified as an argument in - <option>--listen-http=-<replaceable>n</replaceable></option> - or - <option>--listen-https=-<replaceable>n</replaceable></option> - above. In the latter case, an HTTP or HTTPS server will be - spawned using this descriptor and connections must be made - over the HTTP protocol.</para> - </listitem> - </varlistentry> - - </variablelist> - </refsect1> - - <refsect1> - <title>Sinks</title> - - <para>The location of the output journal can be specified - with <option>-o</option> or <option>--output=</option>. For "active" - sources, this option is required. - </para> - - <variablelist> - <varlistentry> - <term><option>--output=<replaceable>FILE</replaceable></option></term> - - <listitem><para>Will write to this journal file. The filename - must end with <filename>.journal</filename>. The file will be - created if it does not exist. If necessary (journal file full, - or corrupted), the file will be renamed following normal - journald rules and a new journal file will be created in its - stead.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--output=<replaceable>DIR</replaceable></option></term> - - <listitem><para>Will create journal files underneath directory - <replaceable>DIR</replaceable>. The directory must exist. If - necessary (journal files over size, or corrupted), journal - files will be rotated following normal journald rules. Names - of files underneath <replaceable>DIR</replaceable> will be - generated using the rules described below.</para></listitem> - </varlistentry> - </variablelist> - - <para>If <option>--output=</option> is not used, the output - directory <filename>/var/log/journal/remote/</filename> will be - used. In case the output file is not specified, journal files - will be created underneath the selected directory. Files will be - called - <filename>remote-<replaceable>hostname</replaceable>.journal</filename>, - where the <replaceable>hostname</replaceable> part is the - escaped hostname of the source endpoint of the connection, or the - numerical address if the hostname cannot be determined.</para> - - <para>In case of "active" sources, the output file name must - always be given explicitly.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--split-mode</option></term> - - <listitem><para>One of <constant>none</constant> or - <constant>host</constant>. For the first, only one output - journal file is used. For the latter, a separate output file - is used, based on the hostname of the other endpoint of a - connection.</para> - - <para>In case of "active" sources, the output file name must - always be given explicitly and only <constant>none</constant> - is allowed.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--compress</option></term> - <term><option>--no-compress</option></term> - - <listitem><para>Compress or not, respectively, the data in the - journal using XZ.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--seal</option></term> - <term><option>--no-seal</option></term> - - <listitem><para>Periodically sign or not, respectively, the - data in the journal using Forward Secure Sealing. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--getter=<replaceable>PROG --option1 --option2</replaceable></option></term> - - <listitem><para>Program to invoke to retrieve data. The journal - event stream must be generated on standard output.</para> - - <para>Examples:</para> - - <programlisting>--getter='curl "-HAccept: application/vnd.fdo.journal" https://some.host:19531/'</programlisting> - - <programlisting>--getter='wget --header="Accept: application/vnd.fdo.journal" -O- https://some.host:19531/'</programlisting> - </listitem> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </variablelist> - </refsect1> - - <refsect1> - <title>Examples</title> - <para>Copy local journal events to a different journal directory: - <programlisting> -journalctl -o export | systemd-journal-remote -o /tmp/dir - - </programlisting> - </para> - - <para>Retrieve all available events from a remote - <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry> - instance and store them in - <filename>/var/log/journal/remote/remote-some.host.journal</filename>: - <programlisting> -systemd-journal-remote --url http://some.host:19531/ - </programlisting> - </para> - - <para>Retrieve current boot events and wait for new events from a remote - <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry> - instance, and store them in - <filename>/var/log/journal/remote/remote-some.host.journal</filename>: - <programlisting> -systemd-journal-remote --url http://some.host:19531/entries?boot&follow - </programlisting> - </para> -</refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd-journal-upload</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-journal-gatewayd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - <citerefentry><refentrytitle>journal-remote.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - </para> - </refsect1> -</refentry> diff --git a/man/systemd-journal-upload.xml b/man/systemd-journal-upload.xml deleted file mode 100644 index f9723dea89..0000000000 --- a/man/systemd-journal-upload.xml +++ /dev/null @@ -1,263 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2014 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-journal-upload" conditional='HAVE_MICROHTTPD' - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemd-journal-upload</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-journal-upload</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-journal-upload</refname> - <refpurpose>Send journal messages over the network</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>systemd-journal-upload</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="opt" rep="norepeat">-u/--url=<replaceable>URL</replaceable></arg> - <arg choice="opt" rep="repeat">SOURCES</arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para> - <command>systemd-journal-upload</command> will upload journal - entries to the URL specified with <option>--url</option>. Unless - limited by one of the options specified below, all journal - entries accessible to the user the program is running as will be - uploaded, and then the program will wait and send new entries - as they become available. - </para> - </refsect1> - - <refsect1> - <title>Options</title> - - <variablelist> - <varlistentry> - <term><option>-u</option></term> - <term><option>--url=<optional>https://</optional><replaceable>URL</replaceable></option></term> - <term><option>--url=<optional>http://</optional><replaceable>URL</replaceable></option></term> - - <listitem><para>Upload to the specified - address. <replaceable>URL</replaceable> may specify either - just the hostname or both the protocol and - hostname. <constant>https</constant> is the default. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--system</option></term> - <term><option>--user</option></term> - - <listitem><para>Limit uploaded entries to entries from system - services and the kernel, or to entries from services of - current user. This has the same meaning as - <option>--system</option> and <option>--user</option> options - for - <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. If - neither is specified, all accessible entries are uploaded. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-m</option></term> - <term><option>--merge</option></term> - - <listitem><para>Upload entries interleaved from all available - journals, including other machines. This has the same meaning - as <option>--merge</option> option for - <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-D</option></term> - <term><option>--directory=<replaceable>DIR</replaceable></option></term> - - <listitem><para>Takes a directory path as argument. Upload - entries from the specified journal directory - <replaceable>DIR</replaceable> instead of the default runtime - and system journal paths. This has the same meaning as - <option>--directory</option> option for - <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--file=<replaceable>GLOB</replaceable></option></term> - - <listitem><para>Takes a file glob as an argument. Upload - entries from the specified journal files matching - <replaceable>GLOB</replaceable> instead of the default runtime - and system journal paths. May be specified multiple times, in - which case files will be suitably interleaved. This has the same meaning as - <option>--file</option> option for - <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--cursor=</option></term> - - <listitem><para>Upload entries from the location in the - journal specified by the passed cursor. This has the same - meaning as <option>--cursor</option> option for - <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--after-cursor=</option></term> - - <listitem><para>Upload entries from the location in the - journal <emphasis>after</emphasis> the location specified by - the this cursor. This has the same meaning as - <option>--after-cursor</option> option for - <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. - </para></listitem> - </varlistentry> - - - <varlistentry> - <term><option>--save-state</option><optional>=<replaceable>PATH</replaceable></optional></term> - - <listitem><para>Upload entries from the location in the - journal <emphasis>after</emphasis> the location specified by - the cursor saved in file at <replaceable>PATH</replaceable> - (<filename>/var/lib/systemd/journal-upload/state</filename> by default). - After an entry is successfully uploaded, update this file - with the cursor of that entry. - </para></listitem> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </variablelist> - </refsect1> - - <refsect1> - <title>Exit status</title> - - <para>On success, 0 is returned; otherwise, a non-zero - failure code is returned.</para> - </refsect1> - - <refsect1> - <title>Examples</title> - <example> - <title>Setting up certificates for authentication</title> - - <para>Certificates signed by a trusted authority are used to - verify that the server to which messages are uploaded is - legitimate, and vice versa, that the client is trusted.</para> - - <para>A suitable set of certificates can be generated with - <command>openssl</command>:</para> - - <programlisting>openssl req -newkey rsa:2048 -days 3650 -x509 -nodes \ - -out ca.pem -keyout ca.key -subj '/CN=Certificate authority/' - -cat >ca.conf <<EOF -[ ca ] -default_ca = this - -[ this ] -new_certs_dir = . -certificate = ca.pem -database = ./index -private_key = ca.key -serial = ./serial -default_days = 3650 -default_md = default -policy = policy_anything - -[ policy_anything ] -countryName = optional -stateOrProvinceName = optional -localityName = optional -organizationName = optional -organizationalUnitName = optional -commonName = supplied -emailAddress = optional -EOF - -touch index -echo 0001 >serial - -SERVER=server -CLIENT=client - -openssl req -newkey rsa:1024 -nodes -out $SERVER.csr -keyout $SERVER.key -subj "/CN=$SERVER/" -openssl ca -batch -config ca.conf -notext -in $SERVER.csr -out $SERVER.pem - -openssl req -newkey rsa:1024 -nodes -out $CLIENT.csr -keyout $CLIENT.key -subj "/CN=$CLIENT/" -openssl ca -batch -config ca.conf -notext -in $CLIENT.csr -out $CLIENT.pem -</programlisting> - - <para>Generated files <filename>ca.pem</filename>, - <filename>server.pem</filename>, and - <filename>server.key</filename> should be installed on server, - and <filename>ca.pem</filename>, - <filename>client.pem</filename>, and - <filename>client.key</filename> on the client. The location of - those files can be specified using - <varname>TrustedCertificateFile=</varname>, - <varname>ServerCertificateFile=</varname>, - <varname>ServerKeyFile=</varname>, in - <filename>/etc/systemd/journal-remote.conf</filename> and - <filename>/etc/systemd/journal-upload.conf</filename>, - respectively. The default locations can be queried by using - <command>systemd-journal-remote --help</command> and - <command>systemd-journal-upload --help</command>.</para> - </example> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd-journal-remote</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-journal-gatewayd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> -</refentry> diff --git a/man/systemd-journald.service.xml b/man/systemd-journald.service.xml deleted file mode 100644 index 2810638bc2..0000000000 --- a/man/systemd-journald.service.xml +++ /dev/null @@ -1,276 +0,0 @@ -<?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-dev-log.socket</refname> - <refname>systemd-journald-audit.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>systemd-journald-dev-log.socket</filename></para> - <para><filename>systemd-journald-audit.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 a variety of sources:</para> - - <itemizedlist> - <listitem><para>Kernel log messages, via kmsg</para></listitem> - - <listitem><para>Simple system log messages, via the libc - <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call</para></listitem> - - <listitem><para>Structured system log messages via the native - Journal API, see - <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>4</manvolnum></citerefentry></para></listitem> - - <listitem><para>Standard output and standard error of system - services</para></listitem> - - <listitem><para>Audit records, via the audit - subsystem</para></listitem> - </itemizedlist> - - <para>The daemon will implicitly collect numerous metadata 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 metadata. - </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> - - <programlisting>mkdir -p /var/log/journal -systemd-tmpfiles --create --prefix /var/log/journal</programlisting> - - <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 must be used after - <filename>/var/</filename> is mounted, as otherwise log data - from <filename>/run</filename> is never flushed to - <filename>/var</filename> regardless of the configuration. The - <command>journalctl --flush</command> command uses this signal - to request flushing of the journal files, and then waits for - the operation to complete. See - <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - for details.</para></listitem> - </varlistentry> - - <varlistentry> - <term>SIGUSR2</term> - - <listitem><para>Request immediate rotation of the journal - files. The <command>journalctl --rotate</command> command uses - this signal to request journal file - rotation.</para></listitem> - </varlistentry> - - <varlistentry> - <term>SIGRTMIN+1</term> - - <listitem><para>Request that all unwritten log data is written - to disk. The <command>journalctl --sync</command> command uses - this signal to trigger journal synchronization, and then waits - for the operation to complete.</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 class='kernel-commandline-options'> - <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> - <term><varname>systemd.journald.forward_to_wall=</varname></term> - - <listitem><para>Enables/disables forwarding of collected log - messages to syslog, the kernel log buffer, the system console - or wall. - </para> - - <para>See - <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for information about these settings.</para> - </listitem> - - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Access Control</title> - - <para>Journal files are, by default, owned and readable by the - <literal>systemd-journal</literal> system group but are not - writable. Adding a user to this group thus enables her/him to read - the journal files.</para> - - <para>By default, each logged in user will get her/his own set of - journal files in <filename>/var/log/journal/</filename>. These - files will not be owned by the user, however, in order to avoid - that the user can write to them directly. Instead, file system - ACLs are used to ensure the user gets read access only.</para> - - <para>Additional users and groups may be granted access to journal - files via file system access control lists (ACL). Distributions - and administrators may choose to grant read access to all members - of the <literal>wheel</literal> and <literal>adm</literal> system - groups with a command such as the following:</para> - - <programlisting># setfacl -Rnm g:wheel:rx,d:g:wheel:rx,g:adm:rx,d:g:adm:rx /var/log/journal/</programlisting> - - <para>Note that this command will update the ACLs both for - existing journal files and for future journal files created in the - <filename>/var/log/journal/</filename> directory.</para> - </refsect1> - - <refsect1> - <title>Files</title> - - <variablelist> - <varlistentry> - <term><filename>/etc/systemd/journald.conf</filename></term> - - <listitem><para>Configure - <command>systemd-journald</command> - behavior. See - <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>/run/log/journal/<replaceable>machine-id</replaceable>/*.journal</filename></term> - <term><filename>/run/log/journal/<replaceable>machine-id</replaceable>/*.journal~</filename></term> - <term><filename>/var/log/journal/<replaceable>machine-id</replaceable>/*.journal</filename></term> - <term><filename>/var/log/journal/<replaceable>machine-id</replaceable>/*.journal~</filename></term> - - <listitem><para><command>systemd-journald</command> writes - entries to files in - <filename>/run/log/journal/<replaceable>machine-id</replaceable>/</filename> - or - <filename>/var/log/journal/<replaceable>machine-id</replaceable>/</filename> - with the <literal>.journal</literal> suffix. If the daemon is - stopped uncleanly, or if the files are found to be corrupted, - they are renamed using the <literal>.journal~</literal> - suffix, and <command>systemd-journald</command> starts writing - to a new file. <filename>/run</filename> is used when - <filename>/var/log/journal</filename> is not available, or - when <option>Storage=volatile</option> is set in the - <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - configuration file.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>/dev/kmsg</filename></term> - <term><filename>/dev/log</filename></term> - <term><filename>/run/systemd/journal/dev-log</filename></term> - <term><filename>/run/systemd/journal/socket</filename></term> - <term><filename>/run/systemd/journal/stdout</filename></term> - - <listitem><para>Sockets and other paths that - <command>systemd-journald</command> will listen on that are - visible in the file system. In addition to these, journald can - listen for audit events using netlink.</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>, - <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>setfacl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>4</manvolnum></citerefentry>, - <command>pydoc systemd.journal</command> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-localed.service.xml b/man/systemd-localed.service.xml deleted file mode 100644 index 06aa78c0e4..0000000000 --- a/man/systemd-localed.service.xml +++ /dev/null @@ -1,87 +0,0 @@ -<?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" conditional='ENABLE_LOCALED'> - - <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 project='man-pages'><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 project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='mankier'><refentrytitle>loadkeys</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-logind.service.xml b/man/systemd-logind.service.xml deleted file mode 100644 index 5733e42cd1..0000000000 --- a/man/systemd-logind.service.xml +++ /dev/null @@ -1,121 +0,0 @@ -<?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" conditional='ENABLE_LOGIND'> - - <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><command>systemd-logind</command> 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>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-commit.service.xml b/man/systemd-machine-id-commit.service.xml deleted file mode 100644 index 39da1922cc..0000000000 --- a/man/systemd-machine-id-commit.service.xml +++ /dev/null @@ -1,95 +0,0 @@ -<?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 2014 Didier Roche - - 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-commit.service"> - - <refentryinfo> - <title>systemd-machine-id-commit.service</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Didier</firstname> - <surname>Roche</surname> - <email>didrocks@ubuntu.com</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd-machine-id-commit.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-machine-id-commit.service</refname> - <refpurpose>Commit a transient machine ID to disk</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>systemd-machine-id-commit.service</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>systemd-machine-id-commit.service</filename> is an - early boot service responsible for committing transient - <filename>/etc/machine-id</filename> files to a writable disk file - system. See - <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more information about machine IDs.</para> - - <para>This service is started after - <filename>local-fs.target</filename> in case - <filename>/etc/machine-id</filename> is a mount point of its own - (usually from a memory file system such as - <literal>tmpfs</literal>) and /etc is writable. The service will - invoke <command>systemd-machine-id-setup --commit</command>, which - writes the current transient machine ID to disk and unmount the - <filename>/etc/machine-id</filename> file in a race-free manner to - ensure that file is always valid and accessible for other - processes. See - <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry> - for details.</para> - - <para>The main use case of this service are systems where - <filename>/etc/machine-id</filename> is read-only and initially - not initialized. In this case, the system manager will generate a - transient machine ID file on a memory file system, and mount it - over <filename>/etc/machine-id</filename>, during the early boot - phase. This service is then invoked in a later boot phase, as soon - as <filename>/etc</filename> has been remounted writable and the - ID may thus be committed to disk to make it permanent.</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>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-machine-id-setup.xml b/man/systemd-machine-id-setup.xml deleted file mode 100644 index bfcd74f436..0000000000 --- a/man/systemd-machine-id-setup.xml +++ /dev/null @@ -1,178 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <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> - <author> - <contrib>Developer</contrib> - <firstname>Didier</firstname> - <surname>Roche</surname> - <email>didrocks@ubuntu.com</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 - provisioned or randomly generated ID. See - <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more information about this file.</para> - - <para>If the tool is invoked without the <option>--commit</option> - switch, <filename>/etc/machine-id</filename> is initialized with a - valid, new machined ID if it is missing or empty. The new machine - ID will be acquired in the following fashion:</para> - - <orderedlist> - <listitem><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></listitem> - - <listitem><para>If run inside a KVM virtual machine and a UUID - is was configured (via the <option>-uuid</option> - option), this UUID is used to initialize the machine ID. The - caller must ensure that the UUID passed is sufficiently unique - and is different for every booted instance of the - VM.</para></listitem> - - <listitem><para>Similarly, if run inside a Linux container - environment and a UUID is configured 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></listitem> - - <listitem><para>Otherwise, a new ID is randomly - generated.</para></listitem> - </orderedlist> - - <para>The <option>--commit</option> switch may be used to commit a - transient machined ID to disk, making it persistent. For details, - see below.</para> - - <para>Use - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - to initialize the machine ID on mounted (but not booted) system - images.</para> - - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - - <varlistentry> - <term><option>--root=<replaceable>root</replaceable></option></term> - <listitem><para>Takes a directory path as argument. All paths - operated will be prefixed with the given alternate - <replaceable>root</replaceable> path, including the path for - <filename>/etc/machine-id</filename> itself.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--commit</option></term> - <listitem><para>Commit a transient machine ID to disk. This - command may be used to convert a transient machine ID into a - persistent one. A transient machine ID file is one that was - bind mounted from a memory file system (usually - <literal>tmpfs</literal>) to - <filename>/etc/machine-id</filename> during the early phase of - the boot process. This may happen because - <filename>/etc</filename> is initially read-only and was - missing a valid machine ID file at that point.</para> - - <para>This command will execute no operation if - <filename>/etc/machine-id</filename> is not mounted from a - memory file system, or if <filename>/etc</filename> is - read-only. The command will write the current transient - machine ID to disk and unmount the - <filename>/etc/machine-id</filename> mount point in a - race-free manner to ensure that this file is always valid and - accessible for other processes.</para> - - <para>This command is primarily used by the - <citerefentry><refentrytitle>systemd-machine-id-commit.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - early boot service.</para></listitem> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </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>systemd-machine-id-commit.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='dbus'><refentrytitle>dbus-uuidgen</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-machined.service.xml b/man/systemd-machined.service.xml deleted file mode 100644 index 999aeee1c6..0000000000 --- a/man/systemd-machined.service.xml +++ /dev/null @@ -1,90 +0,0 @@ -<?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 2013 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-machined.service" conditional='ENABLE_MACHINED'> - - <refentryinfo> - <title>systemd-machined.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-machined.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-machined.service</refname> - <refname>systemd-machined</refname> - <refpurpose>Virtual machine and container registration manager</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>systemd-machined.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-machined</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-machined</command> is a system service that - keeps track of virtual machines and containers, and processes - belonging to them.</para> - - <para>See - <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> - for some examples on how to run containers with OS tools.</para> - - <para>Use - <citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry> - to make the names of local containers known to - <command>systemd-machined</command> locally resolvable as host - names.</para> - - <para>See the - <ulink url="http://www.freedesktop.org/wiki/Software/systemd/machined"> - machined D-Bus API Documentation</ulink> for information about the - APIs <filename>systemd-machined</filename> provides.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-modules-load.service.xml b/man/systemd-modules-load.service.xml deleted file mode 100644 index b25929b2e4..0000000000 --- a/man/systemd-modules-load.service.xml +++ /dev/null @@ -1,96 +0,0 @@ -<?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" conditional='HAVE_KMOD'> - - <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>Load kernel modules 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 based on 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 class='kernel-commandline-options'> - - <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>, - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-networkd-wait-online.service.xml b/man/systemd-networkd-wait-online.service.xml deleted file mode 100644 index e21c805342..0000000000 --- a/man/systemd-networkd-wait-online.service.xml +++ /dev/null @@ -1,110 +0,0 @@ -<?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 2014 Tom Gundersen - - 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-networkd-wait-online.service" conditional='ENABLE_NETWORKD'> - - <refentryinfo> - <title>systemd-networkd.service</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Tom</firstname> - <surname>Gundersen</surname> - <email>teg@jklm.no</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd-networkd-wait-online.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-networkd-wait-online.service</refname> - <refname>systemd-networkd-wait-online</refname> - <refpurpose>Wait for network to come online</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>systemd-networkd-wait-online.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-networkd-wait-online</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-networkd-wait-online</command> is a - one-shot system service that waits for the network to be - configured. By default, it will wait for all links it is aware of - and which are managed by - <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - to be fully configured or failed, and for at least one link to - gain a carrier.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>-i</option></term> - <term><option>--interface=</option></term> - - <listitem><para>Network interface to wait for before deciding - if the system is online. This is useful when a system has - several interfaces which will be configured, but a particular - one is necessary to access some network resources. This option - may be used more than once to wait for multiple network - interfaces. When used, all other interfaces are ignored. - </para></listitem> - </varlistentry> - <varlistentry> - <term><option>--ignore=</option></term> - <listitem><para>Network interfaces to be ignored when deciding - if the system is online. By default, only the loopback - interface is ignored. This option may be used more than once - to ignore multiple network interfaces. </para></listitem> - </varlistentry> - <varlistentry> - <term><option>--timeout=</option></term> - <listitem><para>Fail the service if the network is not online - by the time the timeout elapses. A timeout of 0 disables the - timeout. Defaults to 120 seconds. </para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-networkd.service.xml b/man/systemd-networkd.service.xml deleted file mode 100644 index 0bfe5519bc..0000000000 --- a/man/systemd-networkd.service.xml +++ /dev/null @@ -1,103 +0,0 @@ -<?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 2013 Tom Gundersen - - 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-networkd.service" conditional='ENABLE_NETWORKD'> - - <refentryinfo> - <title>systemd-networkd.service</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Tom</firstname> - <surname>Gundersen</surname> - <email>teg@jklm.no</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd-networkd.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-networkd.service</refname> - <refname>systemd-networkd</refname> - <refpurpose>Network manager</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>systemd-networkd.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-networkd</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-networkd</command> is a system service that - manages networks. It detects and configures network devices as - they appear, as well as creating virtual network devices.</para> - - <para>To configure low-level link settings independently of - networks, see - <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> - - <para>Network configurations applied before networkd is started - are not removed, and static configuration applied by networkd is - not removed when networkd exits. Dynamic configuration applied by - networkd may also optionally be left in place on shutdown. This - ensures restarting networkd does not cut the network connection, - and, in particular, that it is safe to transition between the - initrd and the real root, and back.</para> - </refsect1> - - <refsect1><title>Configuration Files</title> - <para>The configuration files are read from the files located in the - system network directory <filename>/usr/lib/systemd/network</filename>, - the volatile runtime network directory - <filename>/run/systemd/network</filename> and the local administration - network directory <filename>/etc/systemd/network</filename>.</para> - - <para>Networks are configured in <filename>.network</filename> - files, see - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - and virtual network devices are configured in - <filename>.netdev</filename> files, see - <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - </para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-networkd-wait-online.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-notify.xml b/man/systemd-notify.xml deleted file mode 100644 index a5f4077166..0000000000 --- a/man/systemd-notify.xml +++ /dev/null @@ -1,185 +0,0 @@ -<?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" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <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>--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>. An - alternate way to check for this state is to call - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - with the <command>is-system-running</command> command. It will - return <literal>offline</literal> if the system was not booted - with systemd. </para></listitem> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </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 deleted file mode 100644 index 476cc2932f..0000000000 --- a/man/systemd-nspawn.xml +++ /dev/null @@ -1,1066 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <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</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="opt"><replaceable>COMMAND</replaceable> - <arg choice="opt" rep="repeat">ARGS</arg> - </arg> - </cmdsynopsis> - <cmdsynopsis> - <command>systemd-nspawn</command> - <arg choice="plain">--boot</arg> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="opt" rep="repeat">ARGS</arg> - </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 project='man-pages'><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 fully 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.</para> - - <para>In contrast to - <citerefentry project='man-pages'><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 project='mankier'><refentrytitle>dnf</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - or - <citerefentry project='archlinux'><refentrytitle>pacman</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. Use - <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s - <command>login</command> command to request an additional login - prompt in a running container.</para> - - <para><command>systemd-nspawn</command> implements the - <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container - Interface</ulink> specification.</para> - - <para>As a safety check <command>systemd-nspawn</command> will - verify the existence of <filename>/usr/lib/os-release</filename> - or <filename>/etc/os-release</filename> in the container tree - before starting the container (see - <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>). - It might be necessary to add this file to the container tree - manually if the OS of the container is too old to contain this - file out-of-the-box.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>If option <option>-b</option> is specified, the arguments - are used as arguments for the init binary. Otherwise, - <replaceable>COMMAND</replaceable> specifies the program to launch - in the container, and the remaining arguments are used as - arguments for this program. If <option>-b</option> is not used and - no arguments are specified, a shell is launched in the - container.</para> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>-D</option></term> - <term><option>--directory=</option></term> - - <listitem><para>Directory to use as file system root for the - container.</para> - - <para>If neither <option>--directory=</option>, nor - <option>--image=</option> is specified the directory is - determined by searching for a directory named the same as the - machine name specified with <option>--machine=</option>. See - <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - section "Files and Directories" for the precise search path.</para> - - <para>If neither <option>--directory=</option>, - <option>--image=</option>, nor <option>--machine=</option> - are specified, the current directory will - be used. May not be specified together with - <option>--image=</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--template=</option></term> - - <listitem><para>Directory or <literal>btrfs</literal> - subvolume to use as template for the container's root - directory. If this is specified and the container's root - directory (as configured by <option>--directory=</option>) - does not yet exist it is created as <literal>btrfs</literal> - subvolume and populated from this template tree. Ideally, the - specified template path refers to the root of a - <literal>btrfs</literal> subvolume, in which case a simple - copy-on-write snapshot is taken, and populating the root - directory is instant. If the specified template path does not - refer to the root of a <literal>btrfs</literal> subvolume (or - not even to a <literal>btrfs</literal> file system at all), - the tree is copied, which can be substantially more - time-consuming. Note that if this option is used the - container's root directory (in contrast to the template - directory!) must be located on a <literal>btrfs</literal> file - system, so that the <literal>btrfs</literal> subvolume may be - created. May not be specified together with - <option>--image=</option> or - <option>--ephemeral</option>.</para> - - <para>Note that this switch leaves host name, machine ID and - all other settings that could identify the instance - unmodified.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-x</option></term> - <term><option>--ephemeral</option></term> - - <listitem><para>If specified, the container is run with a - temporary <literal>btrfs</literal> snapshot of its root - directory (as configured with <option>--directory=</option>), - that is removed immediately when the container terminates. - This option is only supported if the root file system is - <literal>btrfs</literal>. May not be specified together with - <option>--image=</option> or - <option>--template=</option>.</para> - <para>Note that this switch leaves host name, machine ID and - all other settings that could identify the instance - unmodified.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-i</option></term> - <term><option>--image=</option></term> - - <listitem><para>Disk image to mount the root directory for the - container from. Takes a path to a regular file or to a block - device node. The file or block device must contain - either:</para> - - <itemizedlist> - <listitem><para>An MBR partition table with a single - partition of type 0x83 that is marked - bootable.</para></listitem> - - <listitem><para>A GUID partition table (GPT) with a single - partition of type - 0fc63daf-8483-4772-8e79-3d69d8477de4.</para></listitem> - - <listitem><para>A GUID partition table (GPT) with a marked - root partition which is mounted as the root directory of the - container. Optionally, GPT images may contain a home and/or - a server data partition which are mounted to the appropriate - places in the container. All these partitions must be - identified by the partition types defined by the <ulink - url="http://www.freedesktop.org/wiki/Specifications/DiscoverablePartitionsSpec/">Discoverable - Partitions Specification</ulink>.</para></listitem> - </itemizedlist> - - <para>Any other partitions, such as foreign partitions, swap - partitions or EFI system partitions are not mounted. May not - be specified together with <option>--directory=</option>, - <option>--template=</option> or - <option>--ephemeral</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-a</option></term> - <term><option>--as-pid2</option></term> - - <listitem><para>Invoke the shell or specified program as process ID (PID) 2 instead of PID 1 (init). By - default, if neither this option nor <option>--boot</option> is used, the selected binary is run as process with - PID 1, a mode only suitable for programs that are aware of the special semantics that the process with PID 1 - has on UNIX. For example, it needs to reap all processes reparented to it, and should implement - <command>sysvinit</command> compatible signal handling (specifically: it needs to reboot on SIGINT, reexecute - on SIGTERM, reload configuration on SIGHUP, and so on). With <option>--as-pid2</option> a minimal stub init - process is run as PID 1 and the selected binary is executed as PID 2 (and hence does not need to implement any - special semantics). The stub init process will reap processes as necessary and react appropriately to - signals. It is recommended to use this mode to invoke arbitrary commands in containers, unless they have been - modified to run correctly as PID 1. Or in other words: this switch should be used for pretty much all commands, - except when the command refers to an init or shell implementation, as these are generally capable of running - correctly as PID 1. This option may not be combined with <option>--boot</option> or - <option>--share-system</option>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-b</option></term> - <term><option>--boot</option></term> - - <listitem><para>Automatically search for an init binary and invoke it as PID 1, instead of a shell or a user - supplied program. If this option is used, arguments specified on the command line are used as arguments for the - init binary. This option may not be combined with <option>--as-pid2</option> or - <option>--share-system</option>.</para> - - <para>The following table explains the different modes of invocation and relationship to - <option>--as-pid2</option> (see above):</para> - - <table> - <title>Invocation Mode</title> - <tgroup cols='2' align='left' colsep='1' rowsep='1'> - <colspec colname="switch" /> - <colspec colname="explanation" /> - <thead> - <row> - <entry>Switch</entry> - <entry>Explanation</entry> - </row> - </thead> - <tbody> - <row> - <entry>Neither <option>--as-pid2</option> nor <option>--boot</option> specified</entry> - <entry>The passed parameters are interpreted as the command line, which is executed as PID 1 in the container.</entry> - </row> - - <row> - <entry><option>--as-pid2</option> specified</entry> - <entry>The passed parameters are interpreted as the command line, which is executed as PID 2 in the container. A stub init process is run as PID 1.</entry> - </row> - - <row> - <entry><option>--boot</option> specified</entry> - <entry>An init binary as automatically searched and run as PID 1 in the container. The passed parameters are used as invocation parameters for this process.</entry> - </row> - - </tbody> - </tgroup> - </table> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--chdir=</option></term> - - <listitem><para>Change to the specified working directory before invoking the process in the container. Expects - an absolute path in the container's file system namespace.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-u</option></term> - <term><option>--user=</option></term> - - <listitem><para>After transitioning into the container, change - to the specified user-defined in the container's user - database. Like all other systemd-nspawn features, this is not - a security feature and provides protection against accidental - destructive operations only.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-M</option></term> - <term><option>--machine=</option></term> - - <listitem><para>Sets the machine name for this container. This - name may be used to identify this container during its runtime - (for example in tools like - <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - and similar), and is used to initialize the container's - hostname (which the container can choose to override, - however). If not specified, the last component of the root - directory path of the container is used, possibly suffixed - with a random identifier in case <option>--ephemeral</option> - mode is selected. If the root directory selected is the host's - root directory the host's hostname is used as default - instead.</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. Note that this option takes effect only if - <filename>/etc/machine-id</filename> in the container is - unpopulated.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--slice=</option></term> - - <listitem><para>Make the container part of the specified - slice, instead of the default - <filename>machine.slice</filename>. This is only applies if - the machine is run in its own scope unit, i.e. if - <option>--keep-unit</option> is not used.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--property=</option></term> - - <listitem><para>Set a unit property on the scope unit to - register for the machine. This only applies if the machine is - run in its own scope unit, i.e. if - <option>--keep-unit</option> is not used. Takes unit property - assignments in the same format as <command>systemctl - set-property</command>. This is useful to set memory limits - and similar for machines.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--private-users=</option></term> - - <listitem><para>Controls user namespacing. If enabled, the container will run with its own private set of UNIX - user and group ids (UIDs and GIDs). This involves mapping the private UIDs/GIDs used in the container (starting - with the container's root user 0 and up) to a range of UIDs/GIDs on the host that are not used for other - purposes (usually in the range beyond the host's UID/GID 65536). The parameter may be specified as follows:</para> - - <orderedlist> - <listitem><para>The value <literal>no</literal> turns off user namespacing. This is the default.</para></listitem> - - <listitem><para>The value <literal>yes</literal> (or the omission of a parameter) turns on user - namespacing. The UID/GID range to use is determined automatically from the file ownership of the root - directory of the container's directory tree. To use this option, make sure to prepare the directory tree in - advance, and ensure that all files and directories in it are owned by UIDs/GIDs in the range you'd like to - use. Also, make sure that used file ACLs exclusively reference UIDs/GIDs in the appropriate range. If this - mode is used the number of UIDs/GIDs assigned to the container for use is 65536, and the UID/GID of the - root directory must be a multiple of 65536.</para></listitem> - - <listitem><para>The value "pick" turns on user namespacing. In this case the UID/GID range is automatically - chosen. As first step, the file owner of the root directory of the container's directory tree is read, and it - is checked that it is currently not used by the system otherwise (in particular, that no other container is - using it). If this check is successful, the UID/GID range determined this way is used, similar to the - behaviour if "yes" is specified. If the check is not successful (and thus the UID/GID range indicated in the - root directory's file owner is already used elsewhere) a new – currently unused – UID/GID range of 65536 - UIDs/GIDs is randomly chosen between the host UID/GIDs of 524288 and 1878982656, always starting at a - multiple of 65536. This setting implies <option>--private-users-chown</option> (see below), which has the - effect that the files and directories in the container's directory tree will be owned by the appropriate - users of the range picked. Using this option makes user namespace behaviour fully automatic. Note that the - first invocation of a previously unused container image might result in picking a new UID/GID range for it, - and thus in the (possibly expensive) file ownership adjustment operation. However, subsequent invocations of - the container will be cheap (unless of course the picked UID/GID range is assigned to a different use by - then).</para></listitem> - - <listitem><para>Finally if one or two colon-separated numeric parameters are specified, user namespacing is - turned on, too. The first parameter specifies the first host UID/GID to assign to the container, the second - parameter specifies the number of host UIDs/GIDs to assign to the container. If the second parameter is - omitted, 65536 UIDs/GIDs are assigned.</para></listitem> - </orderedlist> - - <para>It is recommended to assign at least 65536 UIDs/GIDs to each container, so that the usable UID/GID range in the - container covers 16 bit. For best security, do not assign overlapping UID/GID ranges to multiple containers. It is - hence a good idea to use the upper 16 bit of the host 32-bit UIDs/GIDs as container identifier, while the lower 16 - bit encode the container UID/GID used. This is in fact the behaviour enforced by the - <option>--private-users=pick</option> option.</para> - - <para>When user namespaces are used, the GID range assigned to each container is always chosen identical to the - UID range.</para> - - <para>In most cases, using <option>--private-users=pick</option> is the recommended option as it enhances - container security massively and operates fully automatically in most cases.</para> - - <para>Note that the picked UID/GID range is not written to <filename>/etc/passwd</filename> or - <filename>/etc/group</filename>. In fact, the allocation of the range is not stored persistently anywhere, - except in the file ownership of the files and directories of the container.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-U</option></term> - - <listitem><para>If the kernel supports the user namespaces feature, equivalent to - <option>--private-users=pick</option>, otherwise equivalent to - <option>--private-users=no</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--private-users-chown</option></term> - - <listitem><para>If specified, all files and directories in the container's directory tree will adjusted so that - they are owned to the appropriate UIDs/GIDs selected for the container (see above). This operation is - potentially expensive, as it involves descending and iterating through the full directory tree of the - container. Besides actual file ownership, file ACLs are adjusted as well.</para> - - <para>This option is implied if <option>--private-users=pick</option> is used. This option has no effect if - user namespacing is not used.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--private-network</option></term> - - <listitem><para>Disconnect networking of the container from - the host. This makes all network interfaces unavailable in the - container, with the exception of the loopback device and those - specified with <option>--network-interface=</option> and - configured with <option>--network-veth</option>. If this - option is specified, the CAP_NET_ADMIN capability will be - added to the set of capabilities the container retains. The - latter may be disabled by using - <option>--drop-capability=</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--network-interface=</option></term> - - <listitem><para>Assign the specified network interface to the - container. This will remove the specified interface from the - calling namespace and place it in the container. When the - container terminates, it is moved back to the host namespace. - Note that <option>--network-interface=</option> implies - <option>--private-network</option>. This option may be used - more than once to add multiple network interfaces to the - container.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--network-macvlan=</option></term> - - <listitem><para>Create a <literal>macvlan</literal> interface - of the specified Ethernet network interface and add it to the - container. A <literal>macvlan</literal> interface is a virtual - interface that adds a second MAC address to an existing - physical Ethernet link. The interface in the container will be - named after the interface on the host, prefixed with - <literal>mv-</literal>. Note that - <option>--network-macvlan=</option> implies - <option>--private-network</option>. This option may be used - more than once to add multiple network interfaces to the - container.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--network-ipvlan=</option></term> - - <listitem><para>Create an <literal>ipvlan</literal> interface - of the specified Ethernet network interface and add it to the - container. An <literal>ipvlan</literal> interface is a virtual - interface, similar to a <literal>macvlan</literal> interface, - which uses the same MAC address as the underlying interface. - The interface in the container will be named after the - interface on the host, prefixed with <literal>iv-</literal>. - Note that <option>--network-ipvlan=</option> implies - <option>--private-network</option>. This option may be used - more than once to add multiple network interfaces to the - container.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-n</option></term> - <term><option>--network-veth</option></term> - - <listitem><para>Create a virtual Ethernet link (<literal>veth</literal>) between host and container. The host - side of the Ethernet link will be available as a network interface named after the container's name (as - specified with <option>--machine=</option>), prefixed with <literal>ve-</literal>. The container side of the - Ethernet link will be named <literal>host0</literal>. The <option>--network-veth</option> option implies - <option>--private-network</option>.</para> - - <para>Note that - <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - includes by default a network file <filename>/usr/lib/systemd/network/80-container-ve.network</filename> - matching the host-side interfaces created this way, which contains settings to enable automatic address - provisioning on the created virtual link via DHCP, as well as automatic IP routing onto the host's external - network interfaces. It also contains <filename>/usr/lib/systemd/network/80-container-host0.network</filename> - matching the container-side interface created this way, containing settings to enable client side address - assignment via DHCP. In case <filename>systemd-networkd</filename> is running on both the host and inside the - container, automatic IP communication from the container to the host is thus available, with further - connectivity to the external network.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--network-veth-extra=</option></term> - - <listitem><para>Adds an additional virtual Ethernet link - between host and container. Takes a colon-separated pair of - host interface name and container interface name. The latter - may be omitted in which case the container and host sides will - be assigned the same name. This switch is independent of - <option>--network-veth</option>, and — in contrast — may be - used multiple times, and allows configuration of the network - interface names. Note that <option>--network-bridge=</option> - has no effect on interfaces created with - <option>--network-veth-extra=</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--network-bridge=</option></term> - - <listitem><para>Adds the host side of the Ethernet link created with <option>--network-veth</option> to the - specified Ethernet bridge interface. Expects a valid network interface name of a bridge device as - argument. Note that <option>--network-bridge=</option> implies <option>--network-veth</option>. If this option - is used, the host side of the Ethernet link will use the <literal>vb-</literal> prefix instead of - <literal>ve-</literal>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--network-zone=</option></term> - - <listitem><para>Creates a virtual Ethernet link (<literal>veth</literal>) to the container and adds it to an - automatically managed Ethernet bridge interface. The bridge interface is named after the passed argument, - prefixed with <literal>vz-</literal>. The bridge interface is automatically created when the first container - configured for its name is started, and is automatically removed when the last container configured for its - name exits. Hence, each bridge interface configured this way exists only as long as there's at least one - container referencing it running. This option is very similar to <option>--network-bridge=</option>, besides - this automatic creation/removal of the bridge device.</para> - - <para>This setting makes it easy to place multiple related containers on a common, virtual Ethernet-based - broadcast domain, here called a "zone". Each container may only be part of one zone, but each zone may contain - any number of containers. Each zone is referenced by its name. Names may be chosen freely (as long as they form - valid network interface names when prefixed with <literal>vz-</literal>), and it is sufficient to pass the same - name to the <option>--network-zones=</option> switch of the various concurrently running containers to join - them in one zone.</para> - - <para>Note that - <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - includes by default a network file <filename>/usr/lib/systemd/network/80-container-vz.network</filename> - matching the bridge interfaces created this way, which contains settings to enable automatic address - provisioning on the created virtual network via DHCP, as well as automatic IP routing onto the host's external - network interfaces. Using <option>--network-zone=</option> is hence in most cases fully automatic and - sufficient to connect multiple local containers in a joined broadcast domain to the host, with further - connectivity to the external network.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-p</option></term> - <term><option>--port=</option></term> - - <listitem><para>If private networking is enabled, maps an IP - port on the host onto an IP port on the container. Takes a - protocol specifier (either <literal>tcp</literal> or - <literal>udp</literal>), separated by a colon from a host port - number in the range 1 to 65535, separated by a colon from a - container port number in the range from 1 to 65535. The - protocol specifier and its separating colon may be omitted, in - which case <literal>tcp</literal> is assumed. The container - port number and its colon may be omitted, in which case the - same port as the host port is implied. This option is only - supported if private networking is used, such as with - <option>--network-veth</option>, <option>--network-zone=</option> - <option>--network-bridge=</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-Z</option></term> - <term><option>--selinux-context=</option></term> - - <listitem><para>Sets the SELinux security context to be used - to label processes in the container.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-L</option></term> - <term><option>--selinux-apifs-context=</option></term> - - <listitem><para>Sets the SELinux security context to be used - to label files in the virtual API file systems in 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 project='man-pages'><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, - CAP_AUDIT_WRITE, CAP_AUDIT_CONTROL. Also CAP_NET_ADMIN is - retained if <option>--private-network</option> is specified. - If the special value <literal>all</literal> is passed, all - capabilities are retained.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--drop-capability=</option></term> - - <listitem><para>Specify one or more additional capabilities to - drop for the container. This allows running the container with - fewer capabilities than the default (see - above).</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--kill-signal=</option></term> - - <listitem><para>Specify the process signal to send to the - container's PID 1 when nspawn itself receives SIGTERM, in - order to trigger an orderly shutdown of the - container. Defaults to SIGRTMIN+3 if <option>--boot</option> - is used (on systemd-compatible init systems SIGRTMIN+3 - triggers an orderly shutdown). For a list of valid signals, see - <citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</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>try-host</literal>, - <literal>guest</literal>, <literal>try-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/<replaceable>machine-id</replaceable></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/<replaceable>machine-id</replaceable></filename>) - and the subdirectory is symlinked into the host at the same - location. <literal>try-host</literal> and - <literal>try-guest</literal> do the same but do not fail if - the host does not have persistent journalling enabled. 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 does not 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=try-guest</option>.</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>--bind=</option></term> - <term><option>--bind-ro=</option></term> - - <listitem><para>Bind mount a file or directory from the host - into the container. Takes one of: a path argument — in which - case the specified path will be mounted from the host to the - same path in the container —, or a colon-separated pair of - paths — in which case the first specified path is the source - in the host, and the second path is the destination in the - container —, or a colon-separated triple of source path, - destination path and mount options. Mount options are - comma-separated and currently, only "rbind" and "norbind" - are allowed. Defaults to "rbind". Backslash escapes are interpreted, so - <literal>\:</literal> may be used to embed colons in either path. - This option may be specified multiple times for - creating multiple independent bind mount points. The - <option>--bind-ro=</option> option creates read-only bind - mounts.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--tmpfs=</option></term> - - <listitem><para>Mount a tmpfs file system into the container. - Takes a single absolute path argument that specifies where to - mount the tmpfs instance to (in which case the directory - access mode will be chosen as 0755, owned by root/root), or - optionally a colon-separated pair of path and mount option - string that is used for mounting (in which case the kernel - default for access mode and owner will be chosen, unless - otherwise specified). This option is particularly useful for - mounting directories such as <filename>/var</filename> as - tmpfs, to allow state-less systems, in particular when - combined with <option>--read-only</option>. - Backslash escapes are interpreted in the path, so - <literal>\:</literal> may be used to embed colons in the path. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--overlay=</option></term> - <term><option>--overlay-ro=</option></term> - - <listitem><para>Combine multiple directory trees into one - overlay file system and mount it into the container. Takes a - list of colon-separated paths to the directory trees to - combine and the destination mount point.</para> - - <para>Backslash escapes are interpreted in the paths, so - <literal>\:</literal> may be used to embed colons in the paths. - </para> - - <para>If three or more paths are specified, then the last - specified path is the destination mount point in the - container, all paths specified before refer to directory trees - on the host and are combined in the specified order into one - overlay file system. The left-most path is hence the lowest - directory tree, the second-to-last path the highest directory - tree in the stacking order. If <option>--overlay-ro=</option> - is used instead of <option>--overlay=</option>, a read-only - overlay file system is created. If a writable overlay file - system is created, all changes made to it are written to the - highest directory tree in the stacking order, i.e. the - second-to-last specified.</para> - - <para>If only two paths are specified, then the second - specified path is used both as the top-level directory tree in - the stacking order as seen from the host, as well as the mount - point for the overlay file system in the container. At least - two paths have to be specified.</para> - - <para>For details about overlay file systems, see <ulink - url="https://www.kernel.org/doc/Documentation/filesystems/overlayfs.txt">overlayfs.txt</ulink>. Note - that the semantics of overlay file systems are substantially - different from normal file systems, in particular regarding - reported device and inode information. Device and inode - information may change for a file while it is being written - to, and processes might see out-of-date versions of files at - times. Note that this switch automatically derives the - <literal>workdir=</literal> mount option for the overlay file - system from the top-level directory tree, making it a sibling - of it. It is hence essential that the top-level directory tree - is not a mount point itself (since the working directory must - be on the same file system as the top-most directory - tree). Also note that the <literal>lowerdir=</literal> mount - option receives the paths to stack in the opposite order of - this switch.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-E <replaceable>NAME</replaceable>=<replaceable>VALUE</replaceable></option></term> - <term><option>--setenv=<replaceable>NAME</replaceable>=<replaceable>VALUE</replaceable></option></term> - - <listitem><para>Specifies an environment variable assignment - to pass to the init process in the container, in the format - <literal>NAME=VALUE</literal>. This may be used to override - the default variables or to set additional variables. This - parameter may be used more than once.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--share-system</option></term> - - <listitem><para>Allows the container to share certain system - facilities with the host. More specifically, this turns off - PID namespacing, UTS namespacing and IPC namespacing, and thus - allows the guest to see and interact more easily with - processes outside of the container. Note that using this - option makes it impossible to start up a full Operating System - in the container, as an init system cannot operate in this - mode. It is only useful to run specific programs or - applications this way, without involving an init system in the - container. This option implies <option>--register=no</option>. - This option may not be combined with - <option>--boot</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--register=</option></term> - - <listitem><para>Controls whether the container is registered - with - <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. - Takes a boolean argument, which defaults to <literal>yes</literal>. - This option should be enabled when the container runs a full - Operating System (more specifically: an init system), and is - useful to ensure that the container is accessible via - <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - and shown by tools such as - <citerefentry project='man-pages'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>. - If the container does not run an init system, it is - recommended to set this option to <literal>no</literal>. Note - that <option>--share-system</option> implies - <option>--register=no</option>. </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--keep-unit</option></term> - - <listitem><para>Instead of creating a transient scope unit to - run the container in, simply register the service or scope - unit <command>systemd-nspawn</command> has been invoked in - with - <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. - This has no effect if <option>--register=no</option> is used. - This switch should be used if - <command>systemd-nspawn</command> is invoked from within a - service unit, and the service unit's sole purpose is to run a - single <command>systemd-nspawn</command> container. This - option is not available if run from a user - session.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--personality=</option></term> - - <listitem><para>Control the architecture ("personality") - reported by - <citerefentry project='man-pages'><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry> - in the container. Currently, only <literal>x86</literal> and - <literal>x86-64</literal> are supported. This is useful when - running a 32-bit container on a 64-bit host. If this setting - is not used, the personality reported in the container is the - same as the one reported on the host.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-q</option></term> - <term><option>--quiet</option></term> - - <listitem><para>Turns off any status output by the tool - itself. When this switch is used, the only output from nspawn - will be the console output of the container OS - itself.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--volatile</option></term> - <term><option>--volatile=</option><replaceable>MODE</replaceable></term> - - <listitem><para>Boots the container in volatile mode. When no - mode parameter is passed or when mode is specified as - <option>yes</option>, full volatile mode is enabled. This - means the root directory is mounted as a mostly unpopulated - <literal>tmpfs</literal> instance, and - <filename>/usr</filename> from the OS tree is mounted into it - in read-only mode (the system thus starts up with read-only OS - resources, but pristine state and configuration, any changes - to the either are lost on shutdown). When the mode parameter - is specified as <option>state</option>, the OS tree is - mounted read-only, but <filename>/var</filename> is mounted as - a <literal>tmpfs</literal> instance into it (the system thus - starts up with read-only OS resources and configuration, but - pristine state, and any changes to the latter are lost on - shutdown). When the mode parameter is specified as - <option>no</option> (the default), the whole OS tree is made - available writable.</para> - - <para>Note that setting this to <option>yes</option> or - <option>state</option> will only work correctly with - operating systems in the container that can boot up with only - <filename>/usr</filename> mounted, and are able to populate - <filename>/var</filename> automatically, as - needed.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--settings=</option><replaceable>MODE</replaceable></term> - - <listitem><para>Controls whether - <command>systemd-nspawn</command> shall search for and use - additional per-container settings from - <filename>.nspawn</filename> files. Takes a boolean or the - special values <option>override</option> or - <option>trusted</option>.</para> - - <para>If enabled (the default), a settings file named after the - machine (as specified with the <option>--machine=</option> - setting, or derived from the directory or image file name) - with the suffix <filename>.nspawn</filename> is searched in - <filename>/etc/systemd/nspawn/</filename> and - <filename>/run/systemd/nspawn/</filename>. If it is found - there, its settings are read and used. If it is not found - there, it is subsequently searched in the same directory as the - image file or in the immediate parent of the root directory of - the container. In this case, if the file is found, its settings - will be also read and used, but potentially unsafe settings - are ignored. Note that in both these cases, settings on the - command line take precedence over the corresponding settings - from loaded <filename>.nspawn</filename> files, if both are - specified. Unsafe settings are considered all settings that - elevate the container's privileges or grant access to - additional resources such as files or directories of the - host. For details about the format and contents of - <filename>.nspawn</filename> files, consult - <citerefentry><refentrytitle>systemd.nspawn</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> - - <para>If this option is set to <option>override</option>, the - file is searched, read and used the same way, however, the order of - precedence is reversed: settings read from the - <filename>.nspawn</filename> file will take precedence over - the corresponding command line options, if both are - specified.</para> - - <para>If this option is set to <option>trusted</option>, the - file is searched, read and used the same way, but regardless - of being found in <filename>/etc/systemd/nspawn/</filename>, - <filename>/run/systemd/nspawn/</filename> or next to the image - file or container root directory, all settings will take - effect, however, command line arguments still take precedence - over corresponding settings.</para> - - <para>If disabled, no <filename>.nspawn</filename> file is read - and no settings except the ones on the command line are in - effect.</para></listitem> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </variablelist> - - </refsect1> - - <refsect1> - <title>Examples</title> - - <example> - <title>Build and boot a minimal BLAG distribution in a container</title> - - <programlisting># dnf -y --releasever=210k --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=blag --enablerepo=updates install systemd passwd dnf blag-release vim-minimal -# systemd-nspawn -bD /srv/mycontainer</programlisting> - - <para>This installs a minimal BLAG distribution into the - directory <filename noindex='true'>/srv/mycontainer/</filename> - and then boots an OS in a namespace container in it.</para> - </example> - - <example> - <title>Spawn a shell in a container of a minimal gNewSense unstable distribution</title> - - <programlisting># debootstrap --arch=amd64 unstable ~/gnewsense-tree/ -# systemd-nspawn -D ~/gnewsense-tree/</programlisting> - - <para>This installs a minimal gNewSense unstable distribution into - the directory <filename>~/gnewsense-tree/</filename> and then - spawns a shell in a namespace container in it.</para> - </example> - - <example> - <title>Boot a minimal Parabola GNU/Linux-libre distribution in a container</title> - - <programlisting># pacstrap -c -d ~/parabola-tree/ base -# systemd-nspawn -bD ~/parabola-tree/</programlisting> - - <para>This installs a minimal Parabola GNU/Linux-libre distribution into the - directory <filename>~/parabola-tree/</filename> and then boots an OS - in a namespace container in it.</para> - </example> - - <example> - <title>Boot into an ephemeral <literal>btrfs</literal> snapshot of the host system</title> - - <programlisting># systemd-nspawn -D / -xb</programlisting> - - <para>This runs a copy of the host system in a - <literal>btrfs</literal> snapshot which is removed immediately - when the container exits. All file system changes made during - runtime will be lost on shutdown, hence.</para> - </example> - - <example> - <title>Run a container with SELinux sandbox security contexts</title> - - <programlisting># chcon system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -R /srv/container -# systemd-nspawn -L system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -Z system_u:system_r:svirt_lxc_net_t:s0:c0,c1 -D /srv/container /bin/sh</programlisting> - </example> - </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>systemd.nspawn</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='mankier'><refentrytitle>dnf</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='archlinux'><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-path.xml b/man/systemd-path.xml deleted file mode 100644 index e2b23eec51..0000000000 --- a/man/systemd-path.xml +++ /dev/null @@ -1,107 +0,0 @@ -<?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 2014 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" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <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>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-path</refname> - <refpurpose>List and query system and user paths</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>systemd-path <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt" rep="repeat">NAME</arg></command> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-path</command> may be used to query system - and user paths. The tool makes many of the paths described in - <citerefentry><refentrytitle>file-hierarchy</refentrytitle><manvolnum>7</manvolnum></citerefentry> - available for querying.</para> - - <para>When invoked without arguments, a list of known paths and - their current values is shown. When at least one argument is - passed, the path with this name is queried and its value shown. - The variables whose name begins with <literal>search-</literal> - do not refer to individual paths, but instead to a list of - colon-separated search paths, in their order of precedence.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--suffix=</option></term> - - <listitem><para>The printed paths are suffixed by the - specified string.</para></listitem> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </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>file-hierarchy</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-quotacheck.service.xml b/man/systemd-quotacheck.service.xml deleted file mode 100644 index 9d4976274e..0000000000 --- a/man/systemd-quotacheck.service.xml +++ /dev/null @@ -1,94 +0,0 @@ -<?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" conditional='ENABLE_QUOTACHECK'> - - <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 class='kernel-commandline-options'> - <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 project='die-net'><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.service.xml b/man/systemd-random-seed.service.xml deleted file mode 100644 index f3b5a947da..0000000000 --- a/man/systemd-random-seed.service.xml +++ /dev/null @@ -1,75 +0,0 @@ -<?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.service" conditional='ENABLE_RANDOMSEED'> - - <refentryinfo> - <title>systemd-random-seed.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.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-random-seed.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.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-random-seed</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>systemd-random-seed.service</filename> is a - service that restores the random seed of the system at early boot - and saves it at shutdown. 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/systemd/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-remount-fs.service.xml b/man/systemd-remount-fs.service.xml deleted file mode 100644 index 176f2b2d20..0000000000 --- a/man/systemd-remount-fs.service.xml +++ /dev/null @@ -1,88 +0,0 @@ -<?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 project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry> - to the root file system, the <filename>/usr</filename> file system, - and the kernel API 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> - - <para>For a longer discussion of kernel API file systems see - <ulink url="http://www.freedesktop.org/wiki/Software/systemd/APIFileSystems">API - File Systems</ulink>.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-resolve.xml b/man/systemd-resolve.xml deleted file mode 100644 index 4b66f836a2..0000000000 --- a/man/systemd-resolve.xml +++ /dev/null @@ -1,375 +0,0 @@ -<?xml version='1.0'?> -<!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 2016 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-resolve" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemd-resolve</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-resolve</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-resolve</refname> - <refpurpose>Resolve domain names, IPV4 and IPv6 addresses, DNS resource records, and services</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>systemd-resolve</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="plain" rep="repeat"><replaceable>HOSTNAME</replaceable></arg> - </cmdsynopsis> - - <cmdsynopsis> - <command>systemd-resolve</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="plain" rep="repeat"><replaceable>ADDRESS</replaceable></arg> - </cmdsynopsis> - - <cmdsynopsis> - <command>systemd-resolve</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <command> --type=<replaceable>TYPE</replaceable></command> - <arg choice="plain" rep="repeat"><replaceable>DOMAIN</replaceable></arg> - </cmdsynopsis> - - <cmdsynopsis> - <command>systemd-resolve</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <command> --service</command> - <arg choice="plain"><arg choice="opt"><arg choice="opt"><replaceable>NAME</replaceable></arg> - <replaceable>TYPE</replaceable></arg> <replaceable>DOMAIN</replaceable></arg> - </cmdsynopsis> - - <cmdsynopsis> - <command>systemd-resolve</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <command> --openpgp</command> - <arg choice="plain"><replaceable>USER@DOMAIN</replaceable></arg> - </cmdsynopsis> - - <cmdsynopsis> - <command>systemd-resolve</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <command> --tlsa</command> - <arg choice="plain"><replaceable>DOMAIN<optional>:PORT</optional></replaceable></arg> - </cmdsynopsis> - - <cmdsynopsis> - <command>systemd-resolve</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <command> --statistics</command> - </cmdsynopsis> - - <cmdsynopsis> - <command>systemd-resolve</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <command> --reset-statistics</command> - </cmdsynopsis> - - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-resolve</command> may be used to resolve domain names, IPv4 and IPv6 addresses, DNS resource - records and services with the - <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - resolver service. By default, the specified list of parameters will be resolved as hostnames, retrieving their IPv4 - and IPv6 addresses. If the parameters specified are formatted as IPv4 or IPv6 operation the reverse operation is - done, and a hostname is retrieved for the specified addresses.</para> - - <para>The <option>--type=</option> switch may be used to specify a DNS resource record type (A, AAAA, SOA, MX, ...) in - order to request a specific DNS resource record, instead of the address or reverse address lookups. - The special value <literal>help</literal> may be used to list known values.</para> - - <para>The <option>--service</option> switch may be used to resolve <ulink - url="https://tools.ietf.org/html/rfc2782">SRV</ulink> and <ulink - url="https://tools.ietf.org/html/rfc6763">DNS-SD</ulink> services (see below). In this mode, between one and three - arguments are required. If three parameters are passed the first is assumed to be the DNS-SD service name, the - second the SRV service type, and the third the domain to search in. In this case a full DNS-SD style SRV and TXT - lookup is executed. If only two parameters are specified, the first is assumed to be the SRV service type, and the - second the domain to look in. In this case no TXT RR is requested. Finally, if only one parameter is specified, it - is assumed to be a domain name, that is already prefixed with an SRV type, and an SRV lookup is done (no - TXT).</para> - - <para>The <option>--openpgp</option> switch may be used to query PGP keys stored as - <ulink url="https://tools.ietf.org/html/draft-wouters-dane-openpgp-02">OPENPGPKEY</ulink> resource records. - When this option is specified one or more e-mail address must be specified.</para> - - <para>The <option>--tlsa</option> switch maybe be used to query TLS public - keys stored as - <ulink url="https://tools.ietf.org/html/rfc6698">TLSA</ulink> resource records. - When this option is specified one or more domain names must be specified.</para> - - <para>The <option>--statistics</option> switch may be used to show resolver statistics, including information about - the number of successful and failed DNSSEC validations.</para> - - <para>The <option>--reset-statistics</option> may be used to reset various statistics counters maintained the - resolver, including those shown in the <option>--statistics</option> output. This operation requires root - privileges.</para> - </refsect1> - - <refsect1> - <title>Options</title> - <variablelist> - <varlistentry> - <term><option>-4</option></term> - <term><option>-6</option></term> - - <listitem><para>By default, when resolving a hostname, both IPv4 and IPv6 - addresses are acquired. By specifying <option>-4</option> only IPv4 addresses are requested, by specifying - <option>-6</option> only IPv6 addresses are requested.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-i</option> <replaceable>INTERFACE</replaceable></term> - <term><option>--interface=</option><replaceable>INTERFACE</replaceable></term> - - <listitem><para>Specifies the network interface to execute the query on. This may either be specified as numeric - interface index or as network interface string (e.g. <literal>en0</literal>). Note that this option has no - effect if system-wide DNS configuration (as configured in <filename>/etc/resolv.conf</filename> or - <filename>/etc/systemd/resolve.conf</filename>) in place of per-link configuration is used.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-p</option> <replaceable>PROTOCOL</replaceable></term> - <term><option>--protocol=</option><replaceable>PROTOCOL</replaceable></term> - - <listitem><para>Specifies the network protocol for the query. May be one of <literal>dns</literal> - (i.e. classic unicast DNS), <literal>llmnr</literal> (<ulink - url="https://tools.ietf.org/html/rfc4795">Link-Local Multicast Name Resolution</ulink>), - <literal>llmnr-ipv4</literal>, <literal>llmnr-ipv6</literal> (LLMNR via the indicated underlying IP - protocols). By default the lookup is done via all protocols suitable for the lookup. If used, limits the set of - protocols that may be used. Use this option multiple times to enable resolving via multiple protocols at the - same time. The setting <literal>llmnr</literal> is identical to specifying this switch once with - <literal>llmnr-ipv4</literal> and once via <literal>llmnr-ipv6</literal>. Note that this option does not force - the service to resolve the operation with the specified protocol, as that might require a suitable network - interface and configuration. - The special value <literal>help</literal> may be used to list known values. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-t</option> <replaceable>TYPE</replaceable></term> - <term><option>--type=</option><replaceable>TYPE</replaceable></term> - <term><option>-c</option> <replaceable>CLASS</replaceable></term> - <term><option>--class=</option><replaceable>CLASS</replaceable></term> - - <listitem><para>Specifies the DNS resource record type (e.g. A, AAAA, MX, …) and class (e.g. IN, ANY, …) to - look up. If these options are used a DNS resource record set matching the specified class and type is - requested. The class defaults to IN if only a type is specified. - The special value <literal>help</literal> may be used to list known values. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--service</option></term> - - <listitem><para>Enables service resolution. This enables DNS-SD and simple SRV service resolution, depending - on the specified list of parameters (see above).</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--service-address=</option><replaceable>BOOL</replaceable></term> - - <listitem><para>Takes a boolean parameter. If true (the default), when doing a service lookup with - <option>--service</option> the hostnames contained in the SRV resource records are resolved as well.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--service-txt=</option><replaceable>BOOL</replaceable></term> - - <listitem><para>Takes a boolean parameter. If true (the default), when doing a DNS-SD service lookup with - <option>--service</option> the TXT service metadata record is resolved as well.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--openpgp</option></term> - - <listitem><para>Enables OPENPGPKEY resource record resolution (see above). Specified e-mail - addresses are converted to the corresponding DNS domain name, and any OPENPGPKEY keys are - printed.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--tlsa</option></term> - - <listitem><para>Enables TLSA resource record resolution (see above). - A query will be performed for each of the specified names prefixed with - the port and family - (<literal>_<replaceable>port</replaceable>._<replaceable>family</replaceable>.<replaceable>domain</replaceable></literal>). - The port number may be specified after a colon - (<literal>:</literal>), otherwise <constant>443</constant> will be used - by default. The family may be specified as an argument after - <option>--tlsa</option>, otherwise <constant>tcp</constant> will be - used.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--cname=</option><replaceable>BOOL</replaceable></term> - - <listitem><para>Takes a boolean parameter. If true (the default), DNS CNAME or DNAME redirections are - followed. Otherwise, if a CNAME or DNAME record is encountered while resolving, an error is - returned.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--search=</option><replaceable>BOOL</replaceable></term> - - <listitem><para>Takes a boolean parameter. If true (the default), any specified single-label hostnames will be - searched in the domains configured in the search domain list, if it is non-empty. Otherwise, the search domain - logic is disabled.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--raw</option><optional>=payload|packet</optional></term> - - <listitem><para>Dump the answer as binary data. If there is no argument or if the argument is - <literal>payload</literal>, the payload of the packet is exported. If the argument is - <literal>packet</literal>, the whole packet is dumped in wire format, prefixed by - length specified as a little-endian 64-bit number. This format allows multiple packets - to be dumped and unambigously parsed.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--legend=</option><replaceable>BOOL</replaceable></term> - - <listitem><para>Takes a boolean parameter. If true (the default), column headers and meta information about the - query response are shown. Otherwise, this output is suppressed.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--statistics</option></term> - - <listitem><para>If specified general resolver statistics are shown, including information whether DNSSEC is - enabled and available, as well as resolution and validation statistics.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--reset-statistics</option></term> - - <listitem><para>Resets the statistics counters shown in <option>--statistics</option> to zero.</para></listitem> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </variablelist> - </refsect1> - - <refsect1> - <title>Examples</title> - - <example> - <title>Retrieve the addresses of the <literal>www.0pointer.net</literal> domain</title> - - <programlisting>$ systemd-resolve www.0pointer.net -www.0pointer.net: 2a01:238:43ed:c300:10c3:bcf3:3266:da74 - 85.214.157.71 - --- Information acquired via protocol DNS in 611.6ms. --- Data is authenticated: no -</programlisting> - </example> - - <example> - <title>Retrieve the domain of the <literal>85.214.157.71</literal> IP address</title> - - <programlisting>$ systemd-resolve 85.214.157.71 -85.214.157.71: gardel.0pointer.net - --- Information acquired via protocol DNS in 1.2997s. --- Data is authenticated: no -</programlisting> - </example> - - <example> - <title>Retrieve the MX record of the <literal>0pointer.net</literal> domain</title> - - <programlisting>$ systemd-resolve -t MX yahoo.com --legend=no -yahoo.com. IN MX 1 mta7.am0.yahoodns.net -yahoo.com. IN MX 1 mta6.am0.yahoodns.net -yahoo.com. IN MX 1 mta5.am0.yahoodns.net -</programlisting> - </example> - - <example> - <title>Resolve an SRV service</title> - - <programlisting>$ systemd-resolve --service _xmpp-server._tcp gmail.com -_xmpp-server._tcp/gmail.com: alt1.xmpp-server.l.google.com:5269 [priority=20, weight=0] - 173.194.210.125 - alt4.xmpp-server.l.google.com:5269 [priority=20, weight=0] - 173.194.65.125 - ... -</programlisting> - </example> - - <example> - <title>Retrieve a PGP key</title> - - <programlisting>$ systemd-resolve --openpgp zbyszek@fedoraproject.org -d08ee310438ca124a6149ea5cc21b6313b390dce485576eff96f8722._openpgpkey.fedoraproject.org. IN OPENPGPKEY - mQINBFBHPMsBEACeInGYJCb+7TurKfb6wGyTottCDtiSJB310i37/6ZYoeIay/5soJjlMyf - MFQ9T2XNT/0LM6gTa0MpC1st9LnzYTMsT6tzRly1D1UbVI6xw0g0vE5y2Cjk3xUwAynCsSs - ... -</programlisting> - </example> - - <example> - <title>Retrieve a TLS key (<literal>=tcp</literal> and - <literal>:443</literal> could be skipped)</title> - - <programlisting>$ systemd-resolve --tlsa=tcp fedoraproject.org:443 -_443._tcp.fedoraproject.org IN TLSA 0 0 1 19400be5b7a31fb733917700789d2f0a2471c0c9d506c0e504c06c16d7cb17c0 - -- Cert. usage: CA constraint - -- Selector: Full Certificate - -- Matching type: SHA-256 -</programlisting> - </example> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> -</refentry> diff --git a/man/systemd-resolved.service.xml b/man/systemd-resolved.service.xml deleted file mode 100644 index 829729ca09..0000000000 --- a/man/systemd-resolved.service.xml +++ /dev/null @@ -1,163 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2014 Tom Gundersen - - 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-resolved.service" conditional='ENABLE_RESOLVED'> - - <refentryinfo> - <title>systemd-resolved.service</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Tom</firstname> - <surname>Gundersen</surname> - <email>teg@jklm.no</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd-resolved.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-resolved.service</refname> - <refname>systemd-resolved</refname> - <refpurpose>Network Name Resolution manager</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>systemd-resolved.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-resolved</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-resolved</command> is a system service that provides network name resolution to local - applications. It implements a caching and validating DNS/DNSSEC stub resolver, as well as an LLMNR resolver and - responder. In addition it maintains the <filename>/run/systemd/resolve/resolv.conf</filename> file for - compatibility with traditional Linux programs. This file may be symlinked from - <filename>/etc/resolv.conf</filename>.</para> - - <para>The glibc NSS module - <citerefentry><refentrytitle>nss-resolve</refentrytitle><manvolnum>8</manvolnum></citerefentry> is required to - permit glibc's NSS resolver functions to resolve host names via <command>systemd-resolved</command>.</para> - - <para>The DNS servers contacted are determined from the global - settings in <filename>/etc/systemd/resolved.conf</filename>, the - per-link static settings in <filename>/etc/systemd/network/*.network</filename> files, - and the per-link dynamic settings received over DHCP. See - <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. To improve compatibility, - <filename>/etc/resolv.conf</filename> is read in order to discover - configured system DNS servers, but only if it is not a symlink - to <filename>/run/systemd/resolve/resolv.conf</filename> (see above).</para> - - <para><command>systemd-resolved</command> synthesizes DNS RRs for the following cases:</para> - - <itemizedlist> - <listitem><para>The local, configured hostname is resolved to - all locally configured IP addresses ordered by their scope, or - — if none are configured — the IPv4 address 127.0.0.2 (which - is on the local loopback) and the IPv6 address ::1 (which is the - local host).</para></listitem> - - <listitem><para>The hostnames <literal>localhost</literal> and - <literal>localhost.localdomain</literal> (as well as any hostname - ending in <literal>.localhost</literal> or <literal>.localhost.localdomain</literal>) - are resolved to the IP addresses 127.0.0.1 and ::1.</para></listitem> - - <listitem><para>The hostname <literal>gateway</literal> is - resolved to all current default routing gateway addresses, - ordered by their metric. This assigns a stable hostname to the - current gateway, useful for referencing it independently of the - current network configuration state.</para></listitem> - - <listitem><para>The mappings defined in <filename>/etc/hosts</filename> are resolved to their configured - addresses and back.</para></listitem> - </itemizedlist> - - <para>Lookup requests are routed to the available DNS servers - and LLMNR interfaces according to the following rules:</para> - - <itemizedlist> - <listitem><para>Lookups for the special hostname - <literal>localhost</literal> are never routed to the - network. (A few other, special domains are handled the same way.)</para></listitem> - - <listitem><para>Single-label names are routed to all local - interfaces capable of IP multicasting, using the LLMNR - protocol. Lookups for IPv4 addresses are only sent via LLMNR on - IPv4, and lookups for IPv6 addresses are only sent via LLMNR on - IPv6. Lookups for the locally configured host name and the - <literal>gateway</literal> host name are never routed to - LLMNR.</para></listitem> - - <listitem><para>Multi-label names are routed to all local - interfaces that have a DNS sever configured, plus the globally - configured DNS server if there is one. Address lookups from the - link-local address range are never routed to - DNS.</para></listitem> - </itemizedlist> - - <para>If lookups are routed to multiple interfaces, the first - successful response is returned (thus effectively merging the - lookup zones on all matching interfaces). If the lookup failed on - all interfaces, the last failing response is returned.</para> - - <para>Routing of lookups may be influenced by configuring - per-interface domain names. See - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. Lookups for a hostname ending in one of the - per-interface domains are exclusively routed to the matching - interfaces.</para> - - <para>Note that <filename>/run/systemd/resolve/resolv.conf</filename> should not be used directly by applications, - but only through a symlink from <filename>/etc/resolv.conf</filename>.</para> - - <para>See the <ulink url="http://www.freedesktop.org/wiki/Software/systemd/resolved"> resolved D-Bus API - Documentation</ulink> for information about the APIs <filename>systemd-resolved</filename> provides.</para> - - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>dnssec-trust-anchors.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>nss-resolve</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-resolve</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>hosts</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-rfkill.service.xml b/man/systemd-rfkill.service.xml deleted file mode 100644 index f464842700..0000000000 --- a/man/systemd-rfkill.service.xml +++ /dev/null @@ -1,90 +0,0 @@ -<?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 2013 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-rfkill.service" conditional='ENABLE_RFKILL'> - - <refentryinfo> - <title>systemd-rfkill.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-rfkill.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-rfkill.service</refname> - <refname>systemd-rfkill.socket</refname> - <refname>systemd-rfkill</refname> - <refpurpose>Load and save the RF kill switch state at boot and change</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>systemd-rfkill.service</filename></para> - <para><filename>systemd-rfkill.socket</filename></para> - <para><filename>/usr/lib/systemd/systemd-rfkill</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>systemd-rfkill.service</filename> is a service - that restores the RF kill switch state at early boot and saves it - on each change. On disk, the RF kill switch state is stored in - <filename>/var/lib/systemd/rfkill/</filename>.</para> - </refsect1> - - <refsect1> - <title>Kernel Command Line</title> - - <para><filename>systemd-rfkill</filename> understands the - following kernel command line parameter:</para> - - <variablelist class='kernel-commandline-options'> - <varlistentry> - <term><varname>systemd.restore_state=</varname></term> - - <listitem><para>Takes a boolean argument. Defaults to - <literal>1</literal>. If <literal>0</literal>, does not - restore the rfkill settings on boot. However, settings will - still be stored on shutdown. </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-run.xml b/man/systemd-run.xml deleted file mode 100644 index 9c1a29218e..0000000000 --- a/man/systemd-run.xml +++ /dev/null @@ -1,459 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2013 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-run" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemd-run</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-run</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-run</refname> - <refpurpose>Run programs in transient scope or service or timer units</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>systemd-run</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="plain"><replaceable>COMMAND</replaceable> - <arg choice="opt" rep="repeat">ARGS</arg> - </arg> - </cmdsynopsis> - <cmdsynopsis> - <command>systemd-run</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="opt" rep="repeat">TIMER OPTIONS</arg> - <arg choice="req"><replaceable>COMMAND</replaceable></arg> - <arg choice="opt" rep="repeat">ARGS</arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-run</command> may be used to create and - start a transient <filename>.service</filename> or - <filename>.scope</filename> unit and run the specified - <replaceable>COMMAND</replaceable> in it. It may also be used to - create and start transient <filename>.timer</filename> - units.</para> - - <para>If a command is run as transient service unit, it will be - started and managed by the service manager like any other service, - and thus shows up in the output of <command>systemctl - list-units</command> like any other unit. It will run in a clean - and detached execution environment, with the service manager as - its parent process. In this mode, <command>systemd-run</command> - will start the service asynchronously in the background and return - after the command has begun execution.</para> - - <para>If a command is run as transient scope unit, it will be - started by <command>systemd-run</command> itself as parent process - and will thus inherit the execution environment of the - caller. However, the processes of the command are managed by the - service manager similar to normal services, and will show up in - the output of <command>systemctl list-units</command>. Execution - in this case is synchronous, and will return only when the command - finishes. This mode is enabled via the <option>--scope</option> - switch (see below). </para> - - <para>If a command is run with timer options such as - <option>--on-calendar=</option> (see below), a transient timer - unit is created alongside the service unit for the specified - command. Only the transient timer unit is started immediately, the - transient service unit will be started when the transient timer - elapses. If the <option>--unit=</option> is specified, the - <replaceable>COMMAND</replaceable> may be omitted. In this case, - <command>systemd-run</command> only creates a - <filename>.timer</filename> unit that invokes the specified unit - when elapsing.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--no-ask-password</option></term> - - <listitem><para>Do not query the user for authentication for - privileged operations.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--scope</option></term> - - <listitem> - <para>Create a transient <filename>.scope</filename> unit instead of - the default transient <filename>.service</filename> unit. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--unit=</option></term> - - <listitem><para>Use this unit name instead of an automatically - generated one.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--property=</option></term> - <term><option>-p</option></term> - - <listitem><para>Sets a unit property for the scope or service - unit that is created. This takes an assignment in the same - format as - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s - <command>set-property</command> command.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--description=</option></term> - - <listitem><para>Provide a description for the service or scope - unit. If not specified, the command itself will be used as a - description. See <varname>Description=</varname> in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--slice=</option></term> - - <listitem><para>Make the new <filename>.service</filename> or - <filename>.scope</filename> unit part of the specified slice, - instead of the <filename>system.slice</filename>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--remain-after-exit</option></term> - - <listitem><para>After the service or scope process has - terminated, keep the service around until it is explicitly - stopped. This is useful to collect runtime information about - the service after it finished running. Also see - <varname>RemainAfterExit=</varname> in - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--send-sighup</option></term> - - <listitem><para>When terminating the scope or service unit, - send a SIGHUP immediately after SIGTERM. This is useful to - indicate to shells and shell-like processes that the - connection has been severed. Also see - <varname>SendSIGHUP=</varname> in - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--service-type=</option></term> - - <listitem><para>Sets the service type. Also see - <varname>Type=</varname> in - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This - option has no effect in conjunction with - <option>--scope</option>. Defaults to - <constant>simple</constant>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--uid=</option></term> - <term><option>--gid=</option></term> - - <listitem><para>Runs the service process under the UNIX user - and group. Also see <varname>User=</varname> and - <varname>Group=</varname> in - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--nice=</option></term> - - <listitem><para>Runs the service process with the specified - nice level. Also see <varname>Nice=</varname> in - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-E <replaceable>NAME</replaceable>=<replaceable>VALUE</replaceable></option></term> - <term><option>--setenv=<replaceable>NAME</replaceable>=<replaceable>VALUE</replaceable></option></term> - - <listitem><para>Runs the service process with the specified environment variable set. - Also see <varname>Environment=</varname> in - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--pty</option></term> - <term><option>-t</option></term> - - <listitem><para>When invoking a command, the service connects - its standard input and output to the invoking tty via a - pseudo TTY device. This allows invoking binaries as services - that expect interactive user input, such as interactive - command shells.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--quiet</option></term> - <term><option>-q</option></term> - - <listitem><para>Suppresses additional informational output - while running. This is particularly useful in combination with - <option>--pty</option> when it will suppress the initial - message explaining how to terminate the TTY connection.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--on-active=</option></term> - <term><option>--on-boot=</option></term> - <term><option>--on-startup=</option></term> - <term><option>--on-unit-active=</option></term> - <term><option>--on-unit-inactive=</option></term> - - <listitem><para>Defines monotonic timers relative to different - starting points. Also see <varname>OnActiveSec=</varname>, - <varname>OnBootSec=</varname>, - <varname>OnStartupSec=</varname>, - <varname>OnUnitActiveSec=</varname> and - <varname>OnUnitInactiveSec=</varname> in - <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This - options have no effect in conjunction with - <option>--scope</option>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--on-calendar=</option></term> - - <listitem><para>Defines realtime (i.e. wallclock) timers with - calendar event expressions. Also see - <varname>OnCalendar=</varname> in - <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This - option has no effect in conjunction with - <option>--scope</option>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--timer-property=</option></term> - - <listitem><para>Sets a timer unit property for the timer unit - that is created. It is similar with - <option>--property</option> but only for created timer - unit. This option only has effect in conjunction with - <option>--on-active=</option>, <option>--on-boot=</option>, - <option>--on-startup=</option>, - <option>--on-unit-active=</option>, - <option>--on-unit-inactive=</option>, - <option>--on-calendar=</option>. This takes an assignment in - the same format as - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s - <command>set-property</command> 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>systemd-run</command> will - wait until the unit's start-up is completed. By passing this - argument, it is only verified and enqueued.</para> - </listitem> - </varlistentry> - - <xi:include href="user-system-options.xml" xpointer="user" /> - <xi:include href="user-system-options.xml" xpointer="system" /> - <xi:include href="user-system-options.xml" xpointer="host" /> - <xi:include href="user-system-options.xml" xpointer="machine" /> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </variablelist> - - <para>All command line arguments after the first non-option - argument become part of the command line of the launched - process. If a command is run as service unit, its first argument - needs to be an absolute binary path.</para> - </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>Logging environment variables provided by systemd to services</title> - - <programlisting># systemd-run env -Running as unit: run-19945.service -# journalctl -u run-19945.service -Sep 08 07:37:21 bupkis systemd[1]: Starting /usr/bin/env... -Sep 08 07:37:21 bupkis systemd[1]: Started /usr/bin/env. -Sep 08 07:37:21 bupkis env[19948]: PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin -Sep 08 07:37:21 bupkis env[19948]: LANG=en_US.UTF-8 -Sep 08 07:37:21 bupkis env[19948]: BOOT_IMAGE=/vmlinuz-3.11.0-0.rc5.git6.2.fc20.x86_64</programlisting> - </example> - - <example> - <title>Limiting resources available to a command</title> - - <programlisting># systemd-run -p BlockIOWeight=10 updatedb</programlisting> - - <para>This command invokes the - <citerefentry project='man-pages'><refentrytitle>updatedb</refentrytitle><manvolnum>8</manvolnum></citerefentry> - tool, but lowers the block I/O weight for it to 10. See - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more information on the <varname>BlockIOWeight=</varname> - property.</para> - </example> - - <example> - <title>Running commands at a specified time</title> - - <para>The following command will touch a file after 30 seconds.</para> - - <programlisting># date; systemd-run --on-active=30 --timer-property=AccuracySec=100ms /bin/touch /tmp/foo -Mon Dec 8 20:44:24 KST 2014 -Running as unit: run-71.timer -Will run service as unit: run-71.service -# journalctl -b -u run-71.timer --- Logs begin at Fri 2014-12-05 19:09:21 KST, end at Mon 2014-12-08 20:44:54 KST. -- -Dec 08 20:44:38 container systemd[1]: Starting /bin/touch /tmp/foo. -Dec 08 20:44:38 container systemd[1]: Started /bin/touch /tmp/foo. -# journalctl -b -u run-71.service --- Logs begin at Fri 2014-12-05 19:09:21 KST, end at Mon 2014-12-08 20:44:54 KST. -- -Dec 08 20:44:48 container systemd[1]: Starting /bin/touch /tmp/foo... -Dec 08 20:44:48 container systemd[1]: Started /bin/touch /tmp/foo.</programlisting> - </example> - - <example> - <title>Allowing access to the tty</title> - - <para>The following command invokes <filename>/bin/bash</filename> as a service - passing its standard input, output and error to the calling TTY.</para> - - <programlisting># systemd-run -t --send-sighup /bin/bash</programlisting> - </example> - - <example> - <title>Start <command>screen</command> as a user service</title> - - <programlisting>$ systemd-run --scope --user screen -Running scope as unit run-r14b0047ab6df45bfb45e7786cc839e76.scope. - -$ screen -ls -There is a screen on: - 492..laptop (Detached) -1 Socket in /var/run/screen/S-fatima. -</programlisting> - - <para>This starts the <command>screen</command> process as a child of the - <command>systemd --user</command> process that was started by - <filename>user@.service</filename>, in a scope unit. A - <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry> - unit is used instead of a - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> - unit, because <command>screen</command> will exit when detaching from the terminal, - and a service unit would be terminated. Running <command>screen</command> - as a user unit has the advantage that it is not part of the session scope. - If <varname>KillUserProcesses=yes</varname> is configured in - <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - the default, the session scope will be terminated when the user logs - out of that session.</para> - - <para>The <filename>user@.service</filename> is started automatically - when the user first logs in, and stays around as long as at least one - login session is open. After the user logs out of the last session, - <filename>user@.service</filename> and all services underneath it - are terminated. This behaviour is the default, when "lingering" is - not enabled for that user. Enabling lingering means that - <filename>user@.service</filename> is started automatically during - boot, even if the user is not logged in, and that the service is - not terminated when the user logs out.</para> - - <para>Enabling lingering allows the user to run processes without being logged in, - for example to allow <command>screen</command> to persist after the user logs out, - even if the session scope is terminated. In the default configuration, users can - enable lingering for themselves:</para> - - <programlisting>$ loginctl enable-linger</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>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-sleep.conf.xml b/man/systemd-sleep.conf.xml deleted file mode 100644 index 9a379ecb94..0000000000 --- a/man/systemd-sleep.conf.xml +++ /dev/null @@ -1,186 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2013 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-sleep.conf" - xmlns:xi="http://www.w3.org/2001/XInclude"> - <refentryinfo> - <title>systemd-sleep.conf</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-sleep.conf</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-sleep.conf</refname> - <refname>sleep.conf.d</refname> - <refpurpose>Suspend and hibernation configuration file</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/etc/systemd/sleep.conf</filename></para> - <para><filename>/etc/systemd/sleep.conf.d/*.conf</filename></para> - <para><filename>/run/systemd/sleep.conf.d/*.conf</filename></para> - <para><filename>/usr/lib/systemd/sleep.conf.d/*.conf</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd</command> supports three general - power-saving modes:</para> - - <variablelist> - <varlistentry> - <term>suspend</term> - - <listitem><para>a low-power state - where execution of the OS is paused, - and complete power loss might result - in lost data, and which is fast to - enter and exit. This corresponds to - suspend, standby, or freeze states as - understood by the kernel. - </para></listitem> - </varlistentry> - - <varlistentry> - <term>hibernate</term> - - <listitem><para>a low-power state - where execution of the OS is paused, - and complete power loss does not - result in lost data, and which might - be slow to enter and exit. This - corresponds to the hibernation as - understood by the kernel. - </para></listitem> - </varlistentry> - - <varlistentry> - <term>hybrid-sleep</term> - - <listitem><para>a low-power state - where execution of the OS is paused, - which might be slow to enter, and on - complete power loss does not result in - lost data but might be slower to exit - in that case. This mode is called - suspend-to-both by the kernel. - </para></listitem> - </varlistentry> - </variablelist> - - <para>Settings in these files determine what strings - will be written to - <filename>/sys/power/disk</filename> and - <filename>/sys/power/state</filename> by - <citerefentry><refentrytitle>systemd-sleep</refentrytitle><manvolnum>8</manvolnum></citerefentry> - when - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> - attempts to suspend or hibernate the machine.</para> - </refsect1> - - <xi:include href="standard-conf.xml" xpointer="main-conf" /> - - <refsect1> - <title>Options</title> - - <para>The following options can be configured in the - <literal>[Sleep]</literal> section of - <filename>/etc/systemd/sleep.conf</filename> or a - <filename>sleep.conf.d</filename> file:</para> - - <variablelist class='systemd-directives'> - <varlistentry> - <term><varname>SuspendMode=</varname></term> - <term><varname>HibernateMode=</varname></term> - <term><varname>HybridSleepMode=</varname></term> - - <listitem><para>The string to be written to - <filename>/sys/power/disk</filename> by, - respectively, - <citerefentry><refentrytitle>systemd-suspend.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-hibernate.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, or - <citerefentry><refentrytitle>systemd-hybrid-sleep.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. - More than one value can be specified by separating - multiple values with whitespace. They will be tried - in turn, until one is written without error. If - neither succeeds, the operation will be aborted. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>SuspendState=</varname></term> - <term><varname>HibernateState=</varname></term> - <term><varname>HybridSleepState=</varname></term> - - <listitem><para>The string to be written to - <filename>/sys/power/state</filename> by, - respectively, - <citerefentry><refentrytitle>systemd-suspend.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-hibernate.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, or - <citerefentry><refentrytitle>systemd-hybrid-sleep.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. - More than one value can be specified by separating - multiple values with whitespace. They will be tried - in turn, until one is written without error. If - neither succeeds, the operation will be aborted. - </para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Example: freeze</title> - - <para>Example: to exploit the <quote>freeze</quote> mode added - in Linux 3.9, one can use <command>systemctl suspend</command> - with - <programlisting>[Sleep] -SuspendState=freeze</programlisting></para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd-sleep</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-suspend.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-hibernate.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-hybrid-sleep.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-socket-activate.xml b/man/systemd-socket-activate.xml deleted file mode 100644 index 5d7f157c72..0000000000 --- a/man/systemd-socket-activate.xml +++ /dev/null @@ -1,206 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2013 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-socket-activate" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemd-socket-activate</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-socket-activate</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-socket-activate</refname> - <refpurpose>Test socket activation of daemons</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>systemd-socket-activate</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="plain"><replaceable>daemon</replaceable></arg> - <arg choice="opt" rep="repeat">OPTIONS</arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-socket-activate</command> may be used to launch a socket-activated service binary from the command - line for testing purposes. It may also be used to launch individual instances of the service binary per connection. - </para> - - <para>The daemon to launch and its options should be specified - after options intended for <command>systemd-socket-activate</command>. - </para> - - <para>If the <option>--inetd</option> option is given, the socket file descriptor will be used as the standard - input and output of the launched process. Otherwise, standard input and output will be inherited, and sockets will - be passed through file descriptors 3 and higher. Sockets passed through <varname>$LISTEN_FDS</varname> to - <command>systemd-socket-activate</command> will be passed through to the daemon, in the original positions. Other sockets - specified with <option>--listen=</option> will use consecutive descriptors. By default, - <command>systemd-socket-activate</command> listens on a stream socket, use <option>--datagram</option> and - <option>--seqpacket</option> to listen on datagram or sequential packet sockets instead (see below). - </para> - </refsect1> - - <refsect1> - <title>Options</title> - <variablelist> - <varlistentry> - <term><option>-l <replaceable>address</replaceable></option></term> - <term><option>--listen=<replaceable>address</replaceable></option></term> - - <listitem><para>Listen on this <replaceable>address</replaceable>. - Takes a string like <literal>2000</literal> or - <literal>127.0.0.1:2001</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-a</option></term> - <term><option>--accept</option></term> - - <listitem><para>Launch an instance of the service binary for each connection and pass the connection - socket.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-d</option></term> - <term><option>--datagram</option></term> - - <listitem><para>Listen on a datagram socket (<constant>SOCK_DGRAM</constant>), instead of a stream socket - (<constant>SOCK_STREAM</constant>). May not be combined with <option>--seqpacket</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--seqpacket</option></term> - - <listitem><para>Listen on a sequential packet socket (<constant>SOCK_SEQPACKET</constant>), instead of a stream - socket (<constant>SOCK_STREAM</constant>). May not be combined with - <option>--datagram</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--inetd</option></term> - - <listitem><para>Use the inetd protocol for passing file descriptors, i.e. as standard input and standard - output, instead of the new-style protocol for passing file descriptors using <varname>$LISTEN_FDS</varname> - (see above).</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-E <replaceable>VAR</replaceable><optional>=<replaceable>VALUE</replaceable></optional></option></term> - <term><option>--setenv=<replaceable>VAR</replaceable><optional>=<replaceable>VALUE</replaceable></optional></option></term> - - <listitem><para>Add this variable to the environment of the - launched process. If <replaceable>VAR</replaceable> is - followed by <literal>=</literal>, assume that it is a - variable–value pair. Otherwise, obtain the value from the - environment of <command>systemd-socket-activate</command> itself. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--fdname=</option><replaceable>NAME</replaceable><optional>:<replaceable>NAME</replaceable>...</optional></term> - - <listitem><para>Specify names for the file descriptors passed. This is equivalent to setting - <varname>FileDescriptorName=</varname> in socket unit files, and enables use of - <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - Multiple entries may be specifies using separate options or by separating names with colons - (<literal>:</literal>) in one option. In case more names are given than descriptors, superflous ones willl be - ignored. In case less names are given than descriptors, the remaining file descriptors will be unnamed. - </para></listitem> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </variablelist> - </refsect1> - - <refsect1> - <title>Environment variables</title> - <variablelist class='environment-variables'> - <varlistentry> - <term><varname>$LISTEN_FDS</varname></term> - <term><varname>$LISTEN_PID</varname></term> - <term><varname>$LISTEN_FDNAMES</varname></term> - - <listitem><para>See - <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</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>Same as in - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Examples</title> - - <example> - <title>Run an echo server on port 2000</title> - - <programlisting>$ systemd-socket-activate -l 2000 --inetd -a cat</programlisting> - </example> - - <example> - <title>Run a socket-activated instance of <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry></title> - - <programlisting>$ systemd-socket-activate -l 19531 /usr/lib/systemd/systemd-journal-gatewayd</programlisting> - </example> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>cat</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> -</refentry> diff --git a/man/systemd-socket-proxyd.xml b/man/systemd-socket-proxyd.xml deleted file mode 100644 index ae4217b910..0000000000 --- a/man/systemd-socket-proxyd.xml +++ /dev/null @@ -1,190 +0,0 @@ -<?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 2013 David Strauss - - 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-proxyd" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemd-socket-proxyd</title> - <productname>systemd</productname> - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>David</firstname> - <surname>Strauss</surname> - <email>david@davidstrauss.net</email> - </author> - </authorgroup> - </refentryinfo> - <refmeta> - <refentrytitle>systemd-socket-proxyd</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - <refnamediv> - <refname>systemd-socket-proxyd</refname> - <refpurpose>Bidirectionally proxy local sockets to another (possibly remote) socket.</refpurpose> - </refnamediv> - <refsynopsisdiv> - <cmdsynopsis> - <command>systemd-socket-proxyd</command> - <arg choice="opt" rep="repeat"><replaceable>OPTIONS</replaceable></arg> - <arg choice="plain"><replaceable>HOST</replaceable>:<replaceable>PORT</replaceable></arg> - </cmdsynopsis> - <cmdsynopsis> - <command>systemd-socket-proxyd</command> - <arg choice="opt" rep="repeat"><replaceable>OPTIONS</replaceable></arg> - <arg choice="plain"><replaceable>UNIX-DOMAIN-SOCKET-PATH</replaceable> - </arg> - </cmdsynopsis> - </refsynopsisdiv> - <refsect1> - <title>Description</title> - <para> - <command>systemd-socket-proxyd</command> is a generic - socket-activated network socket forwarder proxy daemon for IPv4, - IPv6 and UNIX stream sockets. It may be used to bi-directionally - forward traffic from a local listening socket to a local or remote - destination socket.</para> - - <para>One use of this tool is to provide socket activation support - for services that do not natively support socket activation. On - behalf of the service to activate, the proxy inherits the socket - from systemd, accepts each client connection, opens a connection - to a configured server for each client, and then bidirectionally - forwards data between the two.</para> - <para>This utility's behavior is similar to - <citerefentry project='die-net'><refentrytitle>socat</refentrytitle><manvolnum>1</manvolnum></citerefentry>. - The main differences for <command>systemd-socket-proxyd</command> - are support for socket activation with - <literal>Accept=false</literal> and an event-driven - design that scales better with the number of - connections.</para> - </refsect1> - <refsect1> - <title>Options</title> - <para>The following options are understood:</para> - <variablelist> - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </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> - <refsect2> - <title>Simple Example</title> - <para>Use two services with a dependency and no namespace - isolation.</para> - <example> - <title>proxy-to-nginx.socket</title> - <programlisting><![CDATA[[Socket] -ListenStream=80 - -[Install] -WantedBy=sockets.target]]></programlisting> - </example> - <example> - <title>proxy-to-nginx.service</title> - <programlisting><![CDATA[[Unit] -Requires=nginx.service -After=nginx.service - -[Service] -ExecStart=/usr/lib/systemd/systemd-socket-proxyd /tmp/nginx.sock -PrivateTmp=yes -PrivateNetwork=yes]]></programlisting> - </example> - <example> - <title>nginx.conf</title> - <programlisting> -<![CDATA[[...] -server { - listen unix:/tmp/nginx.sock; - [...]]]> -</programlisting> - </example> - <example> - <title>Enabling the proxy</title> - <programlisting><![CDATA[# systemctl enable proxy-to-nginx.socket -# systemctl start proxy-to-nginx.socket -$ curl http://localhost:80/]]></programlisting> - </example> - </refsect2> - <refsect2> - <title>Namespace Example</title> - <para>Similar as above, but runs the socket proxy and the main - service in the same private namespace, assuming that - <filename>nginx.service</filename> has - <varname>PrivateTmp=</varname> and - <varname>PrivateNetwork=</varname> set, too.</para> - <example> - <title>proxy-to-nginx.socket</title> - <programlisting><![CDATA[[Socket] -ListenStream=80 - -[Install] -WantedBy=sockets.target]]></programlisting> - </example> - <example> - <title>proxy-to-nginx.service</title> - <programlisting><![CDATA[[Unit] -Requires=nginx.service -After=nginx.service -JoinsNamespaceOf=nginx.service - -[Service] -ExecStart=/usr/lib/systemd/systemd-socket-proxyd 127.0.0.1:8080 -PrivateTmp=yes -PrivateNetwork=yes]]></programlisting> - </example> - <example> - <title>nginx.conf</title> - <programlisting><![CDATA[[...] -server { - listen 8080; - [...]]]></programlisting> - </example> - <example> - <title>Enabling the proxy</title> - <programlisting><![CDATA[# systemctl enable proxy-to-nginx.socket -# systemctl start proxy-to-nginx.socket -$ curl http://localhost:80/]]></programlisting> - </example> - </refsect2> - </refsect1> - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>socat</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>nginx</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>curl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> -</refentry> diff --git a/man/systemd-suspend.service.xml b/man/systemd-suspend.service.xml deleted file mode 100644 index a8beb86f4d..0000000000 --- a/man/systemd-suspend.service.xml +++ /dev/null @@ -1,146 +0,0 @@ -<?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 - Copyright 2013 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-suspend.service" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <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/system-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. Similarly, - <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 - until all executables have 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. What exactly is written - where can be configured in the <literal>[Sleep]</literal> section - of <filename>/etc/systemd/sleep.conf</filename> or a - <filename>sleep.conf.d</filename> file. See - <citerefentry><refentrytitle>systemd-sleep.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - </para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para><command>systemd-sleep</command> understands the - following commands:</para> - - <variablelist> - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - - <varlistentry> - <term><option>suspend</option></term> - <term><option>hibernate</option></term> - <term><option>hybrid-sleep</option></term> - - <listitem><para>Suspend, hibernate, or put the system to - hybrid sleep.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd-sleep.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <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 deleted file mode 100644 index 686b2cdef4..0000000000 --- a/man/systemd-sysctl.service.xml +++ /dev/null @@ -1,152 +0,0 @@ -<?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" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <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> - <cmdsynopsis> - <command>/usr/lib/systemd/systemd-sysctl</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="opt" rep="repeat"><replaceable>CONFIGFILE</replaceable></arg> - </cmdsynopsis> - <para><filename>systemd-sysctl.service</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>systemd-sysctl.service</filename> is an early boot - service that configures - <citerefentry project='man-pages'><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry> - kernel parameters by invoking <command>/usr/lib/systemd/systemd-sysctl</command>.</para> - - <para>When invoked with no arguments, <command>/usr/lib/systemd/systemd-sysctl</command> applies - all directives from configuration files listed in - <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - If one or more filenames are passed on the command line, only the directives in these files are - applied.</para> - - <para>In addition, <option>--prefix=</option> option may be used to limit which sysctl - settings are applied.</para> - - <para>See - <citerefentry project='man-pages'><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for information about the configuration of sysctl settings. After sysctl configuration is - changed on disk, it must be written to the files in <filename>/proc/sys</filename> before it - takes effect. It is possible to update specific settings, or simply to reload all configuration, - see Examples below.</para> - </refsect1> - - <refsect1><title>Options</title> - <variablelist> - <varlistentry id='prefix'> - <term><option>--prefix=</option></term> - <listitem> - <para>Only apply rules with the specified prefix.</para> - </listitem> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - - </variablelist> - </refsect1> - - <refsect1> - <title>Examples</title> - - <example> - <title>Reset all sysctl settings</title> - - <programlisting>systemctl restart systemd-sysctl</programlisting> - </example> - - <example> - <title>View coredump handler configuration</title> - - <programlisting># sysctl kernel.core_pattern -kernel.core_pattern = |/usr/libexec/abrt-hook-ccpp %s %c %p %u %g %t %P %I -</programlisting> - </example> - - <example> - <title>Update coredump handler configuration</title> - - <programlisting># /usr/lib/systemd/systemd-sysctl --prefix kernel.core_pattern</programlisting> - - <para>This searches all the directories listed in - <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for configuration files and writes <filename>/proc/sys/kernel/core_pattern</filename>.</para> - </example> - - <example> - <title>Update coredump handler configuration according to a specific file</title> - - <programlisting># /usr/lib/systemd/systemd-sysctl 50-coredump.conf</programlisting> - - <para>This applies all the settings found in <filename>50-coredump.conf</filename>. - Either <filename>/etc/sysctl.d/50-coredump.conf</filename>, or - <filename>/run/sysctl.d/50-coredump.conf</filename>, or - <filename>/usr/lib/sysctl.d/50-coredump.conf</filename> will be used, in the order - of preference.</para> - </example> - - <para>See - <citerefentry project='man-pages'><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for various ways to directly apply sysctl settings.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-system-update-generator.xml b/man/systemd-system-update-generator.xml deleted file mode 100644 index e7fc95c742..0000000000 --- a/man/systemd-system-update-generator.xml +++ /dev/null @@ -1,76 +0,0 @@ -<?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 - <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</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-system.conf.xml b/man/systemd-system.conf.xml deleted file mode 100644 index 8833e73c72..0000000000 --- a/man/systemd-system.conf.xml +++ /dev/null @@ -1,394 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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-system.conf" - xmlns:xi="http://www.w3.org/2001/XInclude"> - <refentryinfo> - <title>systemd-system.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-system.conf</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-system.conf</refname> - <refname>system.conf.d</refname> - <refname>systemd-user.conf</refname> - <refname>user.conf.d</refname> - <refpurpose>System and session service manager configuration files</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/etc/systemd/system.conf</filename>, - <filename>/etc/systemd/system.conf.d/*.conf</filename>, - <filename>/run/systemd/system.conf.d/*.conf</filename>, - <filename>/usr/lib/systemd/system.conf.d/*.conf</filename></para> - <para><filename>/etc/systemd/user.conf</filename>, - <filename>/etc/systemd/user.conf.d/*.conf</filename>, - <filename>/run/systemd/user.conf.d/*.conf</filename>, - <filename>/usr/lib/systemd/user.conf.d/*.conf</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>When run as a system instance, systemd interprets the - configuration file <filename>system.conf</filename> and the files - in <filename>system.conf.d</filename> directories; when run as a - user instance, systemd interprets the configuration file - <filename>user.conf</filename> and the files in - <filename>user.conf.d</filename> directories. These configuration - files contain a few settings controlling basic manager - operations.</para> - </refsect1> - - <xi:include href="standard-conf.xml" xpointer="main-conf" /> - - <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>CrashChangeVT=no</varname></term> - <term><varname>CrashShell=no</varname></term> - <term><varname>CrashReboot=no</varname></term> - <term><varname>ShowStatus=yes</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 list of CPU indices or ranges separated - by either whitespace or commas. CPU ranges are specified by - the lower and upper CPU indices separated by a - dash.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>JoinControllers=cpu,cpuacct 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> - - <para>Note that this option is only applied once, at very - early boot. If you use an initial RAM disk (initrd) that uses - systemd, it might hence be necessary to rebuild the initrd if - this option is changed, and make sure the new configuration - file is included in it. Otherwise, the initrd might mount the - controller hierarchies in a different configuration than - intended, and the main system cannot remount them - anymore.</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 project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for details. Takes a whitespace-separated list of capability - names as read by - <citerefentry project='mankier'><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>SystemCallArchitectures=</varname></term> - - <listitem><para>Takes a space-separated list of architecture - identifiers. Selects from which architectures system calls may - be invoked on this system. This may be used as an effective - way to disable invocation of non-native binaries system-wide, - for example to prohibit execution of 32-bit x86 binaries on - 64-bit x86-64 systems. This option operates system-wide, and - acts similar to the - <varname>SystemCallArchitectures=</varname> setting of unit - files, see - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. This setting defaults to the empty list, in which - case no filtering of system calls based on architecture is - applied. Known architecture identifiers are - <literal>x86</literal>, <literal>x86-64</literal>, - <literal>x32</literal>, <literal>arm</literal> and the special - identifier <literal>native</literal>. The latter implicitly - maps to the native architecture of the system (or more - specifically, the architecture the system manager was compiled - for). Set this setting to <literal>native</literal> to - prohibit execution of any non-native binaries. When a binary - executes a system call of an architecture that is not listed - in this setting, it will be immediately terminated with the - SIGSYS signal.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>TimerSlackNSec=</varname></term> - - <listitem><para>Sets the timer slack in nanoseconds for PID 1, - which is inherited by 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 - system 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>DefaultTimerAccuracySec=</varname></term> - - <listitem><para>Sets the default accuracy of timer units. This - controls the global default for the - <varname>AccuracySec=</varname> setting of timer units, see - <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. <varname>AccuracySec=</varname> set in individual - units override the global default for the specific unit. - Defaults to 1min. Note that the accuracy of timer units is - also affected by the configured timer slack for PID 1, see - <varname>TimerSlackNSec=</varname> above.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>DefaultTimeoutStartSec=</varname></term> - <term><varname>DefaultTimeoutStopSec=</varname></term> - <term><varname>DefaultRestartSec=</varname></term> - - <listitem><para>Configures the default timeouts for starting - and stopping of units, as well as the default time to sleep - between automatic restarts of units, as configured per-unit in - <varname>TimeoutStartSec=</varname>, - <varname>TimeoutStopSec=</varname> and - <varname>RestartSec=</varname> (for services, see - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details on the per-unit settings). For non-service units, - <varname>DefaultTimeoutStartSec=</varname> sets the default - <varname>TimeoutSec=</varname> - value. <varname>DefaultTimeoutStartSec=</varname> and - <varname>DefaultTimeoutStopSec=</varname> default to - 90s. <varname>DefaultRestartSec=</varname> defaults to - 100ms.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>DefaultStartLimitIntervalSec=</varname></term> - <term><varname>DefaultStartLimitBurst=</varname></term> - - <listitem><para>Configure the default unit start rate - limiting, as configured per-service by - <varname>StartLimitIntervalSec=</varname> and - <varname>StartLimitBurst=</varname>. See - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details on the per-service settings. - <varname>DefaultStartLimitIntervalSec=</varname> defaults to - 10s. <varname>DefaultStartLimitBurst=</varname> defaults to - 5.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>DefaultEnvironment=</varname></term> - - <listitem><para>Sets manager environment variables passed to - all executed processes. Takes a space-separated list of - variable assignments. See - <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for details about environment variables.</para> - - <para>Example: - - <programlisting>DefaultEnvironment="VAR1=word1 word2" VAR2=word3 "VAR3=word 5 6"</programlisting> - - Sets three variables - <literal>VAR1</literal>, - <literal>VAR2</literal>, - <literal>VAR3</literal>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>DefaultCPUAccounting=</varname></term> - <term><varname>DefaultBlockIOAccounting=</varname></term> - <term><varname>DefaultMemoryAccounting=</varname></term> - <term><varname>DefaultTasksAccounting=</varname></term> - - <listitem><para>Configure the default resource accounting - settings, as configured per-unit by - <varname>CPUAccounting=</varname>, - <varname>BlockIOAccounting=</varname>, - <varname>MemoryAccounting=</varname> and - <varname>TasksAccounting=</varname>. See - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details on the per-unit - settings. <varname>DefaulTasksAccounting=</varname> defaults - to on, the other three settings to off.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>DefaultTasksMax=</varname></term> - - <listitem><para>Configure the default value for the per-unit - <varname>TasksMax=</varname> setting. See - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. This setting applies to all unit types that - support resource control settings, with the exception of slice - units. Defaults to 512.</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. The resource limit is possible to specify in two formats, - <option>value</option> to set soft and hard limits to the same value, - or <option>soft:hard</option> to set both limits individually (e.g. DefaultLimitAS=4G:16G). - Use the string <varname>infinity</varname> to - configure no limit on a specific resource. The multiplicative - suffixes K (=1024), M (=1024*1024) and so on for G, T, P and E - may be used for resource limits measured in bytes - (e.g. DefaultLimitAS=16G). For the limits referring to time values, - the usual time units ms, s, min, h and so on may be used (see - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for details). Note that if no time unit is specified for - <varname>DefaultLimitCPU=</varname> the default unit of seconds is - implied, while for <varname>DefaultLimitRTTIME=</varname> the default - unit of microseconds is implied. Also, note that the effective - granularity of the limits might influence their - enforcement. For example, time limits specified for - <varname>DefaultLimitCPU=</varname> will be rounded up implicitly to - multiples of 1s. 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>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-sysusers.xml b/man/systemd-sysusers.xml deleted file mode 100644 index 4892caad12..0000000000 --- a/man/systemd-sysusers.xml +++ /dev/null @@ -1,116 +0,0 @@ -<?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 2014 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-sysusers" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemd-sysusers</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-sysusers</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-sysusers</refname> - <refname>systemd-sysusers.service</refname> - <refpurpose>Allocate system users and groups</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>systemd-sysusers</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="opt" rep="repeat"><replaceable>CONFIGFILE</replaceable></arg> - </cmdsynopsis> - - <para><filename>systemd-sysusers.service</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-sysusers</command> creates system users and - groups, based on the file format and location specified in - <citerefentry><refentrytitle>sysusers.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - </para> - - <para>If invoked with no arguments, it applies all directives from - all files found. If one or more filenames are passed on the - command line, only the directives in these files are applied. If - only the basename of a file is specified, all directories as - specified in - <citerefentry><refentrytitle>sysusers.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> - are searched for a matching file. If the string - <filename>-</filename> is specified as filename, entries from the - standard input of the process are read.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--root=<replaceable>root</replaceable></option></term> - <listitem><para>Takes a directory path as an argument. All - paths will be prefixed with the given alternate - <replaceable>root</replaceable> path, including config search - paths. </para></listitem> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </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>sysusers.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-sysv-generator.xml b/man/systemd-sysv-generator.xml deleted file mode 100644 index 2353eb3efe..0000000000 --- a/man/systemd-sysv-generator.xml +++ /dev/null @@ -1,97 +0,0 @@ -<?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 2014 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-sysv-generator" conditional="HAVE_SYSV_COMPAT"> - - <refentryinfo> - <title>systemd-sysv-generator</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Documentation</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd-sysv-generator</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-sysv-generator</refname> - <refpurpose>Unit generator for SysV init scripts</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/usr/lib/systemd/system-generators/systemd-sysv-generator</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>systemd-sysv-generator</filename> is a generator - that creates wrapper .service units for - <ulink url="https://savannah.nongnu.org/projects/sysvinit">SysV init</ulink> - scripts in <filename>/etc/init.d/*</filename> at boot and when - configuration of the system manager is reloaded. This will allow - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> - to support them similarly to native units.</para> - - <para><ulink url="http://refspecs.linuxbase.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB headers</ulink> - in SysV init scripts are interpreted, and the ordering specified - in the header is turned into dependencies between the generated - unit and other units. The LSB facilities - <literal>$remote_fs</literal>, <literal>$network</literal>, - <literal>$named</literal>, <literal>$portmap</literal>, - <literal>$time</literal> are supported and will be turned into - dependencies on specific native systemd targets. See - <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more details.</para> - - <para>SysV runlevels have corresponding systemd targets - (<filename>runlevel<replaceable>X</replaceable>.target</filename>). - The wrapper unit that is generated will be wanted by those targets - which correspond to runlevels for which the script is - enabled.</para> - - <para><command>systemd</command> does not support SysV scripts as - part of early boot, so all wrapper units are ordered after - <filename>basic.target</filename>.</para> - - <para><filename>systemd-sysv-generator</filename> implements - <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-timedated.service.xml b/man/systemd-timedated.service.xml deleted file mode 100644 index e44163aefb..0000000000 --- a/man/systemd-timedated.service.xml +++ /dev/null @@ -1,85 +0,0 @@ -<?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" conditional='ENABLE_TIMEDATED'> - - <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 a 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 project='man-pages'><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-timesyncd.service.xml b/man/systemd-timesyncd.service.xml deleted file mode 100644 index 6ec384313b..0000000000 --- a/man/systemd-timesyncd.service.xml +++ /dev/null @@ -1,108 +0,0 @@ -<?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 2014 Kay Sievers - - 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-timesyncd.service" conditional='ENABLE_TIMESYNCD'> - - <refentryinfo> - <title>systemd-timesyncd.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-timesyncd.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-timesyncd.service</refname> - <refname>systemd-timesyncd</refname> - <refpurpose>Network Time Synchronization</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>systemd-timesyncd.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-timesyncd</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>systemd-timesyncd</filename> is a system service - that may be used to synchronize the local system clock with a - remote Network Time Protocol server. It also saves the local time - to disk every time the clock has been synchronized and uses this - to possibly advance the system realtime clock on subsequent - reboots to ensure it monotonically advances even if the system - lacks a battery-buffered RTC chip.</para> - - <para>The NTP servers contacted are determined from the global - settings in - <citerefentry><refentrytitle>timesyncd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - the per-link static settings in <filename>.network</filename> - files, and the per-link dynamic settings received over DHCP. See - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more details.</para> - - <para><citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s - <command>set-ntp</command> command may be used to enable and - start, or disable and stop this service.</para> - </refsect1> - - <refsect1> - <title>Files</title> - - <variablelist> - <varlistentry> - <term><filename>/var/lib/systemd/clock</filename></term> - - <listitem> - <para>This file contains the timestamp of the last successful - synchronization.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>timesyncd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-tmpfiles.xml b/man/systemd-tmpfiles.xml deleted file mode 100644 index c1aab51551..0000000000 --- a/man/systemd-tmpfiles.xml +++ /dev/null @@ -1,200 +0,0 @@ -<?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" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <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-setup-dev.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</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="opt" rep="repeat"><replaceable>CONFIGFILE</replaceable></arg> - </cmdsynopsis> - - <para><filename>systemd-tmpfiles-setup.service</filename></para> - <para><filename>systemd-tmpfiles-setup-dev.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 absolute filenames are passed on the command line, only the - directives in these files are applied. If <literal>-</literal> is specified instead - of a filename, directives are read from standard input. 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 - <varname>f</varname>, - <varname>F</varname>, - <varname>w</varname>, - <varname>d</varname>, - <varname>D</varname>, - <varname>v</varname>, - <varname>p</varname>, - <varname>L</varname>, - <varname>c</varname>, - <varname>b</varname>, - <varname>m</varname> - in the configuration files are created or written to. Files - and directories marked with - <varname>z</varname>, - <varname>Z</varname>, - <varname>t</varname>, - <varname>T</varname>, - <varname>a</varname>, and - <varname>A</varname> 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, the contents of - directories marked with <varname>D</varname> or - <varname>R</varname>, and files or directories themselves - marked with <varname>r</varname> or <varname>R</varname> are - removed.</para></listitem> - </varlistentry> - <varlistentry> - <term><option>--boot</option></term> - <listitem><para>Also execute lines with an exclamation mark. - </para></listitem> - </varlistentry> - <varlistentry> - <term><option>--prefix=<replaceable>path</replaceable></option></term> - <listitem><para>Only apply rules with paths that start with - the specified prefix. This option can be specified multiple - times.</para></listitem> - </varlistentry> - <varlistentry> - <term><option>--exclude-prefix=<replaceable>path</replaceable></option></term> - <listitem><para>Ignore rules with paths that start with the - specified prefix. This option can be specified multiple - times.</para></listitem> - </varlistentry> - <varlistentry> - <term><option>--root=<replaceable>root</replaceable></option></term> - <listitem><para>Takes a directory path as an argument. All - paths will be prefixed with the given alternate - <replaceable>root</replaceable> path, including config search - paths. </para></listitem> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </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>Unprivileged --cleanup operation</title> - - <para><command>systemd-tmpfiles</command> tries to avoid changing - the access and modification times on the directories it accesses, - which requires <constant>CAP_ADMIN</constant> privileges. When - running as non-root, directories which are checked for files to - clean up will have their access time bumped, which might prevent - their cleanup. - </para> - </refsect1> - - <refsect1> - <title>Exit status</title> - - <para>On success, 0 is returned, a non-zero failure code - otherwise.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>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 deleted file mode 100644 index 2876fab644..0000000000 --- a/man/systemd-tty-ask-password-agent.xml +++ /dev/null @@ -1,149 +0,0 @@ -<?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" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <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>--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 project='man-pages'><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 project='die-net'><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> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </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 project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-udevd.service.xml b/man/systemd-udevd.service.xml deleted file mode 100644 index 243fd06471..0000000000 --- a/man/systemd-udevd.service.xml +++ /dev/null @@ -1,188 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <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> - </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>--event-timeout=</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 daemon can be configured using - <citerefentry><refentrytitle>udev.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - its command line options, environment variables, and on the kernel - command line, or changed dynamically 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 standard error.</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 <varname>RUN</varname> - instructions 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>--event-timeout=</option></term> - <listitem> - <para>Set the number of seconds to wait for events to finish. After - this time, the event will be terminated. The default is 180 seconds.</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>--help</option></term> - - <xi:include href="standard-options.xml" xpointer="help-text" /> - </varlistentry> - <xi:include href="standard-options.xml" xpointer="version" /> - </variablelist> - </refsect1> - - <refsect1><title>Kernel command line</title> - <variablelist class='kernel-commandline-options'> - <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 log level.</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 <varname>RUN</varname> instructions 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><varname>udev.event-timeout=</varname></term> - <term><varname>rd.udev.event-timeout=</varname></term> - <listitem> - <para>Wait for events to finish up to the given number - of seconds. This option might be useful if events are - terminated due to kernel drivers taking too long to initialize.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>net.ifnames=</varname></term> - <listitem> - <para>Network interfaces are renamed to give them predictable names - when possible. It is enabled by default; specifying 0 disables it.</para> - </listitem> - </varlistentry> - </variablelist> - <!-- when adding entries here, consider also adding them - in kernel-command-line.xml --> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>udev.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <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-done.service.xml b/man/systemd-update-done.service.xml deleted file mode 100644 index a2dad39f01..0000000000 --- a/man/systemd-update-done.service.xml +++ /dev/null @@ -1,97 +0,0 @@ -<?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 2014 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-update-done.service"> - - <refentryinfo> - <title>systemd-update-done.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-done.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-update-done.service</refname> - <refname>systemd-update-done</refname> - <refpurpose>Mark <filename>/etc</filename> and <filename>/var</filename> fully updated</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>systemd-update-done.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-update-done</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>systemd-update-done.service</filename> is a - service that is invoked as part of the first boot after the vendor - operating system resources in <filename>/usr</filename> have been - updated. This is useful to implement offline updates of - <filename>/usr</filename> which might require updates to - <filename>/etc</filename> or <filename>/var</filename> on the - following boot.</para> - - <para><filename>systemd-update-done.service</filename> updates the - file modification time (mtime) of the stamp files - <filename>/etc/.updated</filename> and - <filename>/var/.updated</filename> to the modification time of the - <filename>/usr</filename> directory, unless the stamp files are - already newer.</para> - - <para>Services that shall run after offline upgrades of - <filename>/usr</filename> should order themselves before - <filename>systemd-update-done.service</filename>, and use the - <varname>ConditionNeedsUpdate=</varname> (see - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>) - condition to make sure to run when <filename>/etc</filename> or - <filename>/var</filename> are older than <filename>/usr</filename> - according to the modification times of the files described above. - This requires that updates to <filename>/usr</filename> are always - followed by an update of the modification time of - <filename>/usr</filename>, for example by invoking - <citerefentry project='man-pages'><refentrytitle>touch</refentrytitle><manvolnum>1</manvolnum></citerefentry> - on it.</para> - - </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 project='man-pages'><refentrytitle>touch</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-update-utmp.service.xml b/man/systemd-update-utmp.service.xml deleted file mode 100644 index c8a9cb7c90..0000000000 --- a/man/systemd-update-utmp.service.xml +++ /dev/null @@ -1,76 +0,0 @@ -<?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-update-utmp.service" conditional="HAVE_UTMP"> - - <refentryinfo> - <title>systemd-update-utmp.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.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-update-utmp.service</refname> - <refname>systemd-update-utmp-runlevel.service</refname> - <refname>systemd-update-utmp</refname> - <refpurpose>Write audit and utmp updates at bootup, runlevel - changes and shutdown</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>systemd-update-utmp.service</filename></para> - <para><filename>systemd-update-utmp-runlevel.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.service</filename> does the same for - system reboots and shutdown requests.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>utmp</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><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 deleted file mode 100644 index 67aba54119..0000000000 --- a/man/systemd-user-sessions.service.xml +++ /dev/null @@ -1,75 +0,0 @@ -<?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" conditional='HAVE_PAM'> - - <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 through - <citerefentry project='man-pages'><refentrytitle>pam_nologin</refentrytitle><manvolnum>8</manvolnum></citerefentry>. - 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.</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 project='man-pages'><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 deleted file mode 100644 index ff079761c1..0000000000 --- a/man/systemd-vconsole-setup.service.xml +++ /dev/null @@ -1,114 +0,0 @@ -<?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" conditional='ENABLE_VCONSOLE'> - - <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 project='mankier'><refentrytitle>loadkeys</refentrytitle><manvolnum>1</manvolnum></citerefentry> - and - <citerefentry project='die-net'><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 class='kernel-commandline-options'> - <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 project='mankier'><refentrytitle>loadkeys</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='die-net'><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 deleted file mode 100644 index a43dc981bd..0000000000 --- a/man/systemd.automount.xml +++ /dev/null @@ -1,173 +0,0 @@ -<?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.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><replaceable>automount</replaceable>.automount</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>A unit configuration file whose name ends in - <literal>.automount</literal> 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 noindex='true'>/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>. Note that - automount units cannot be templated, nor is it possible to add multiple names to an automount unit by creating - additional symlinks to its unit file.</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> - </refsect1> - - <refsect1> - <title>Automatic Dependencies</title> - - <para>If an automount unit is beneath another mount unit in the - file system hierarchy, both a requirement and an ordering - dependency between both units are created automatically.</para> - - <para>An implicit <varname>Before=</varname> dependency is created - between an automount unit and the mount unit it activates.</para> - - <para>Automount units acquire automatic <varname>Before=</varname> and <varname>Conflicts=</varname> on - <filename>umount.target</filename> in order to be stopped during shutdown, unless - <varname>DefaultDependencies=no</varname> is set in the <literal>[Unit]</literal> section.</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 project='man-pages'><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 class='unit-directives'> - - <varlistentry> - <term><varname>Where=</varname></term> - <listitem><para>Takes an absolute path of a directory of the - automount point. If the automount point does not exist at time - that the automount point is installed, it is created. This - string must be reflected in the unit filename. (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> - <varlistentry> - <term><varname>TimeoutIdleSec=</varname></term> - <listitem><para>Configures an idle timeout. Once the mount has been - idle for the specified time, systemd will attempt to unmount. Takes a - unit-less value in seconds, or a time span value such as "5min 20s". - Pass 0 to disable the timeout logic. The timeout is disabled by - default.</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.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>automount</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd.device.xml b/man/systemd.device.xml deleted file mode 100644 index effed098dd..0000000000 --- a/man/systemd.device.xml +++ /dev/null @@ -1,182 +0,0 @@ -<?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.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><replaceable>device</replaceable>.device</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>A unit configuration file whose name ends in - <literal>.device</literal> 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 dynamically create device units for all kernel - devices that are marked with the "systemd" udev tag (by default - all block and network devices, and a few others). This may be used - to define dependencies between devices and other units. To tag a - udev device, use <literal>TAG+="systemd"</literal> in the udev - rules file, see - <citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for details.</para> - - <para>Device units are named after the <filename>/sys</filename> - and <filename>/dev</filename> paths they control. Example: the - device <filename noindex='true'>/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>Automatic Dependencies</title> - - <para>Many unit types automatically acquire dependencies on device - units of devices they require. For example, - <filename>.socket</filename> unit acquire dependencies on the - device units of the network interface specified in - <varname>BindToDevice=</varname>. Similar, swap and mount units - acquire dependencies on the units encapsulating their backing - block devices.</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 device properties are understood - by systemd:</para> - - <variablelist class='udev-directives'> - <varlistentry> - <term><varname>SYSTEMD_WANTS=</varname></term> - <term><varname>SYSTEMD_USER_WANTS=</varname></term> - <listitem><para>Adds dependencies of type - <varname>Wants</varname> from the device unit to all listed - units. The first form is used by the system systemd instance, - the second by user systemd instances. Those settings may be - used to activate arbitrary units when a specific device - becomes available.</para> - - <para>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 a systemd unit - (see above).</para> - - <para>Note that systemd will only act on - <varname>Wants</varname> dependencies when a device first - becomes active. It will not act on them if they are added to - devices that are already active. Use - <varname>SYSTEMD_READY=</varname> (see below) to influence on - which udev event to trigger the dependencies. - </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 if it is visible in the udev tree. This property has - no influence on the behavior when a device disappears from the - udev tree.</para> - - <para>This option is useful to support devices that initially - show up in an uninitialized state in the tree, and for which a - <literal>changed</literal> event is generated the moment they - are fully set up. Note that <varname>SYSTEMD_WANTS=</varname> - (see above) is not acted on as long as - <varname>SYSTEMD_READY=0</varname> is set for a - device.</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>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml deleted file mode 100644 index 3cf6de8256..0000000000 --- a/man/systemd.exec.xml +++ /dev/null @@ -1,1475 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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><replaceable>service</replaceable>.service</filename>, - <filename><replaceable>socket</replaceable>.socket</filename>, - <filename><replaceable>mount</replaceable>.mount</filename>, - <filename><replaceable>swap</replaceable>.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>Automatic Dependencies</title> - - <para>A few execution parameters result in additional, automatic - dependencies to be added.</para> - - <para>Units with <varname>WorkingDirectory=</varname> or - <varname>RootDirectory=</varname> set automatically gain - dependencies of type <varname>Requires=</varname> and - <varname>After=</varname> on all mount units required to access - the specified paths. This is equivalent to having them listed - explicitly in <varname>RequiresMountsFor=</varname>.</para> - - <para>Similar, units with <varname>PrivateTmp=</varname> enabled - automatically get mount unit dependencies for all mounts - required to access <filename>/tmp</filename> and - <filename>/var/tmp</filename>.</para> - - <para>Units whose standard output or error output is connected to <option>journal</option>, <option>syslog</option> - or <option>kmsg</option> (or their combinations with console output, see below) automatically acquire dependencies - of type <varname>After=</varname> on <filename>systemd-journald.socket</filename>.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <variablelist class='unit-directives'> - - <varlistentry> - <term><varname>WorkingDirectory=</varname></term> - - <listitem><para>Takes an absolute directory path, or the - special value <literal>~</literal>. Sets the working directory - for executed processes. If set to <literal>~</literal>, the - home directory of the user specified in - <varname>User=</varname> is used. 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. If - the setting is prefixed with the <literal>-</literal> - character, a missing working directory is not considered - fatal. Note that setting this parameter might result in - additional dependencies to be added to the unit (see - above).</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 - project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>2</manvolnum></citerefentry> - system call. If this is used, it must be ensured that the - process binary and all its auxiliary files are available in - the <function>chroot()</function> jail. Note that setting this - parameter might result in additional dependencies to be added - to the unit (see above).</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. When the empty string is assigned, the list of - supplementary groups is reset, and all assignments prior to - this one will have no effect. In any way, 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="https://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 I/O 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 I/O scheduling priority for executed - processes. Takes an integer between 0 (highest priority) and 7 - (lowest priority). The available priorities depend on the - selected I/O 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. The available priority range depends on the - selected CPU scheduling policy (see above). For real-time - scheduling policies an integer between 1 (lowest priority) and - 99 (highest priority) can be used. 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 list of CPU indices or ranges separated by - either whitespace or commas. CPU ranges are specified by the - lower and upper CPU indices separated by a dash. - This option may be specified more than once, in which case the - specified CPU affinity masks are merged. If the empty string - is assigned, the mask is reset, all assignments prior to this - will have no effect. 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. If the empty string is assigned to this - option, the list of environment variables is reset, all prior - assignments have no effect. Variable expansion is not - performed inside the strings, however, specifier expansion is - possible. The $ character has no special meaning. If you need - to assign a value containing spaces to a variable, use double - quotes (") for the assignment.</para> - - <para>Example: - <programlisting>Environment="VAR1=word1 word2" VAR2=word3 "VAR3=$word 5 6"</programlisting> - gives three variables <literal>VAR1</literal>, - <literal>VAR2</literal>, <literal>VAR3</literal> - with the values <literal>word1 word2</literal>, - <literal>word3</literal>, <literal>$word 5 6</literal>. - </para> - - <para> - See - <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for details about environment variables.</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, lines without an <literal>=</literal> separator, - or lines starting with ; or # will be ignored, - which may be used for commenting. A line ending with a - backslash will be concatenated with the following one, - allowing multiline variable definitions. The parser strips - leading and trailing whitespace from the values of - assignments, unless you use double quotes (").</para> - - <para>The argument passed should be an absolute filename or - wildcard expression, optionally prefixed with - <literal>-</literal>, which indicates that if the file does - not exist, it will not be read and no error or warning message - is logged. This option may be specified more than once in - which case all specified files are read. If the empty string - is assigned to this option, the list of file to read is reset, - all prior assignments have no effect.</para> - - <para>The files listed with this directive will be read - shortly before the process is executed (more specifically, - after all processes from a previous unit state terminated. - This means you can generate these files in one unit state, and - read it with this option in the next).</para> - - <para>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>PassEnvironment=</varname></term> - - <listitem><para>Pass environment variables from the systemd system - manager to executed processes. Takes a space-separated list of variable - names. This option may be specified more than once, in which case all - listed variables will be set. If the empty string is assigned to this - option, the list of environment variables is reset, all prior - assignments have no effect. Variables that are not set in the system - manager will not be passed and will be silently ignored.</para> - - <para>Variables passed from this setting are overridden by those passed - from <varname>Environment=</varname> or - <varname>EnvironmentFile=</varname>.</para> - - <para>Example: - <programlisting>PassEnvironment=VAR1 VAR2 VAR3</programlisting> - passes three variables <literal>VAR1</literal>, - <literal>VAR2</literal>, <literal>VAR3</literal> - with the values set for those variables in PID1.</para> - - <para> - See - <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for details about environment variables.</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>.</para> - - <para>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.</para> - - <para>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.</para> - - <para><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.</para> - - <para><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.</para> - - <para>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 project='freebsd'><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry> - daemon.</para> - - <para>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>journal</option>, - <option>syslog</option>, - <option>kmsg</option>, - <option>journal+console</option>, - <option>syslog+console</option>, - <option>kmsg+console</option> or - <option>socket</option>.</para> - - <para><option>inherit</option> duplicates the file descriptor - of standard input for standard output.</para> - - <para><option>null</option> connects standard output to - <filename>/dev/null</filename>, i.e. everything written to it - will be lost.</para> - - <para><option>tty</option> connects standard output 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.</para> - - <para><option>journal</option> connects standard output 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 (see - below) is implicitly stored in the journal as well, the - specific two options listed below are hence supersets of this - one.</para> - - <para><option>syslog</option> connects standard output to the - <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> - system syslog service, in addition to the journal. Note that - the journal daemon is usually configured to forward everything - it receives to syslog anyway, in which case this option is no - different from <option>journal</option>.</para> - - <para><option>kmsg</option> connects standard output with the - kernel log buffer which is accessible via - <citerefentry project='man-pages'><refentrytitle>dmesg</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - in addition to the journal. The journal daemon might be - configured to send all logs to kmsg anyway, in which case this - option is no different from <option>journal</option>.</para> - - <para><option>journal+console</option>, - <option>syslog+console</option> and - <option>kmsg+console</option> work in a similar way as the - three options above but copy the output to the system console - as well.</para> - - <para><option>socket</option> connects standard output to a - socket acquired via socket activation. The semantics are - similar to the same option of - <varname>StandardInput=</varname>.</para> - - <para>If the standard output (or error output, see below) of a unit is connected to the journal, syslog or the - kernel log buffer, the unit will implicitly gain a dependency of type <varname>After=</varname> on - <filename>systemd-journald.socket</filename> (also see the automatic dependencies section above).</para> - - <para>This setting defaults to the value set with - <option>DefaultStandardOutput=</option> in - <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - which defaults to <option>journal</option>. Note that setting - this parameter might result in additional dependencies to be - added to the unit (see above).</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-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - which defaults to <option>inherit</option>. Note that setting - this parameter might result in additional dependencies to be - added to the unit (see above).</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>TTYPath=</varname></term> - <listitem><para>Sets the terminal device node to use if - standard input, output, or error 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 the logging system 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>, <option>journal</option> or - <option>kmsg</option> (or to the same settings in combination - with <option>+console</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 project='man-pages'><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>The 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 project='man-pages'><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>Set soft and hard limits on various resources for executed processes. See - <citerefentry><refentrytitle>setrlimit</refentrytitle><manvolnum>2</manvolnum></citerefentry> for details on - the resource limit concept. Resource limits may be specified in two formats: either as single value to set a - specific soft and hard limit to the same value, or as colon-separated pair <option>soft:hard</option> to set - both limits individually (e.g. <literal>LimitAS=4G:16G</literal>). Use the string <varname>infinity</varname> - to configure no limit on a specific resource. The multiplicative suffixes K, M, G, T, P and E (to the base - 1024) may be used for resource limits measured in bytes (e.g. LimitAS=16G). For the limits referring to time - values, the usual time units ms, s, min, h and so on may be used (see - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> for - details). Note that if no time unit is specified for <varname>LimitCPU=</varname> the default unit of seconds - is implied, while for <varname>LimitRTTIME=</varname> the default unit of microseconds is implied. Also, note - that the effective granularity of the limits might influence their enforcement. For example, time limits - specified for <varname>LimitCPU=</varname> will be rounded up implicitly to multiples of 1s. For - <varname>LimitNICE=</varname> the value may be specified in two syntaxes: if prefixed with <literal>+</literal> - or <literal>-</literal>, the value is understood as regular Linux nice value in the range -20..19. If not - prefixed like this the value is understood as raw resource limit parameter in the range 0..40 (with 0 being - equivalent to 1).</para> - - <para>Note that most process resource limits configured with - these options are per-process, and processes may fork in order - to acquire a new set of resources that are accounted - independently of the original process, and may thus escape - limits set. Also note that <varname>LimitRSS=</varname> is not - implemented on Linux, and setting it has no effect. Often it - is advisable to prefer the resource controls listed in - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> - over these per-process limits, as they apply to services as a - whole, may be altered dynamically at runtime, and are - generally more expressive. For example, - <varname>MemoryLimit=</varname> is a more powerful (and - working) replacement for <varname>LimitRSS=</varname>.</para> - - <table> - <title>Limit directives and their equivalent with ulimit</title> - - <tgroup cols='3'> - <colspec colname='directive' /> - <colspec colname='equivalent' /> - <colspec colname='unit' /> - <thead> - <row> - <entry>Directive</entry> - <entry>ulimit equivalent</entry> - <entry>Unit</entry> - </row> - </thead> - <tbody> - <row> - <entry>LimitCPU=</entry> - <entry>ulimit -t</entry> - <entry>Seconds</entry> - </row> - <row> - <entry>LimitFSIZE=</entry> - <entry>ulimit -f</entry> - <entry>Bytes</entry> - </row> - <row> - <entry>LimitDATA=</entry> - <entry>ulimit -d</entry> - <entry>Bytes</entry> - </row> - <row> - <entry>LimitSTACK=</entry> - <entry>ulimit -s</entry> - <entry>Bytes</entry> - </row> - <row> - <entry>LimitCORE=</entry> - <entry>ulimit -c</entry> - <entry>Bytes</entry> - </row> - <row> - <entry>LimitRSS=</entry> - <entry>ulimit -m</entry> - <entry>Bytes</entry> - </row> - <row> - <entry>LimitNOFILE=</entry> - <entry>ulimit -n</entry> - <entry>Number of File Descriptors</entry> - </row> - <row> - <entry>LimitAS=</entry> - <entry>ulimit -v</entry> - <entry>Bytes</entry> - </row> - <row> - <entry>LimitNPROC=</entry> - <entry>ulimit -u</entry> - <entry>Number of Processes</entry> - </row> - <row> - <entry>LimitMEMLOCK=</entry> - <entry>ulimit -l</entry> - <entry>Bytes</entry> - </row> - <row> - <entry>LimitLOCKS=</entry> - <entry>ulimit -x</entry> - <entry>Number of Locks</entry> - </row> - <row> - <entry>LimitSIGPENDING=</entry> - <entry>ulimit -i</entry> - <entry>Number of Queued Signals</entry> - </row> - <row> - <entry>LimitMSGQUEUE=</entry> - <entry>ulimit -q</entry> - <entry>Bytes</entry> - </row> - <row> - <entry>LimitNICE=</entry> - <entry>ulimit -e</entry> - <entry>Nice Level</entry> - </row> - <row> - <entry>LimitRTPRIO=</entry> - <entry>ulimit -r</entry> - <entry>Realtime Priority</entry> - </row> - <row> - <entry>LimitRTTIME=</entry> - <entry>No equivalent</entry> - <entry>Microseconds</entry> - </row> - </tbody> - </tgroup> - </table></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 project='man-pages'><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for details.</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 - project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> for - details. Takes a whitespace-separated list of capability names as read by <citerefentry - project='mankier'><refentrytitle>cap_from_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - e.g. <constant>CAP_SYS_ADMIN</constant>, <constant>CAP_DAC_OVERRIDE</constant>, - <constant>CAP_SYS_PTRACE</constant>. Capabilities listed will be included in the bounding set, all others are - removed. If the list of capabilities is prefixed with <literal>~</literal>, 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. 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. This option may appear more than once, in which case the bounding sets are merged. If the - empty string is assigned to this option, the bounding set is reset to the empty capability set, and all prior - settings have no effect. If set to <literal>~</literal> (without any further argument), the bounding set is - reset to the full set of available capabilities, also undoing any previous settings.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>AmbientCapabilities=</varname></term> - - <listitem><para>Controls which capabilities to include in the - ambient capability set for the executed process. Takes a - whitespace-separated list of capability names as read by - <citerefentry project='mankier'><refentrytitle>cap_from_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - e.g. <constant>CAP_SYS_ADMIN</constant>, - <constant>CAP_DAC_OVERRIDE</constant>, - <constant>CAP_SYS_PTRACE</constant>. This option may appear more than - once in which case the ambient capability sets are merged. - If the list of capabilities is prefixed with <literal>~</literal>, all - but the listed capabilities will be included, the effect of the - assignment inverted. If the empty string is - assigned to this option, the ambient capability set is reset to - the empty capability set, and all prior settings have no effect. - If set to <literal>~</literal> (without any further argument), the - ambient capability set is reset to the full set of available - capabilities, also undoing any previous settings. Note that adding - capabilities to ambient capability set adds them to the process's - inherited capability set. - </para><para> - Ambient capability sets are useful if you want to execute a process - as a non-privileged user but still want to give it some capabilities. - Note that in this case option <constant>keep-caps</constant> is - automatically added to <varname>SecureBits=</varname> to retain the - capabilities over the user change.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>SecureBits=</varname></term> - <listitem><para>Controls the secure bits set for the executed - process. Takes a space-separated combination of options from - the following list: - <option>keep-caps</option>, - <option>keep-caps-locked</option>, - <option>no-setuid-fixup</option>, - <option>no-setuid-fixup-locked</option>, - <option>noroot</option>, and - <option>noroot-locked</option>. - This option may appear more than once, in which case the secure - bits are ORed. If the empty string is assigned to this option, - the bits are reset to 0. See - <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for details.</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 namespace 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, and may not - countain any other mountpoints, including those specified by - <varname>ReadWriteDirectories=</varname> or - <varname>ReadOnlyDirectories=</varname>. - Note that restricting access with these options does not extend - to submounts of a directory that are created later on. These - options may be specified more than once, in which case all - directories listed will have limited access from within the - namespace. If the empty string is assigned to this option, the - specific list is reset, and all prior assignments have no - effect.</para> - <para>Paths in - <varname>ReadOnlyDirectories=</varname> - and - <varname>InaccessibleDirectories=</varname> - may be prefixed with - <literal>-</literal>, in which case - they will be ignored when they do not - exist. Note that using this - setting will disconnect propagation of - mounts from the service to the host - (propagation in the opposite direction - continues to work). This means that - this setting may not be used for - services which shall be able to - install mount points in the main mount - 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 private <filename>/tmp</filename> and - <filename>/var/tmp</filename> directories 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> - or <filename>/var/tmp</filename> impossible. If this is - enabled, all temporary files created by a service in these - directories will be removed after the service is stopped. - Defaults to false. It is possible to run two or more units - within the same private <filename>/tmp</filename> and - <filename>/var/tmp</filename> namespace by using the - <varname>JoinsNamespaceOf=</varname> directive, see - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. Note that using this setting will disconnect - propagation of mounts from the service to the host - (propagation in the opposite direction continues to work). - This means that this setting may not be used for services - which shall be able to install mount points in the main mount - namespace.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>PrivateDevices=</varname></term> - - <listitem><para>Takes a boolean argument. If true, sets up a - new /dev namespace for the executed processes and only adds - API pseudo devices such as <filename>/dev/null</filename>, - <filename>/dev/zero</filename> or - <filename>/dev/random</filename> (as well as the pseudo TTY - subsystem) to it, but no physical devices such as - <filename>/dev/sda</filename>. This is useful to securely turn - off physical device access by the executed process. Defaults - to false. Enabling this option will also remove - <constant>CAP_MKNOD</constant> from the capability bounding - set for the unit (see above), and set - <varname>DevicePolicy=closed</varname> (see - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details). Note that using this setting will disconnect - propagation of mounts from the service to the host - (propagation in the opposite direction continues to work). - This means that this setting may not be used for services - which shall be able to install mount points in the main mount - namespace. The /dev namespace will be mounted read-only and 'noexec'. - The latter may break old programs which try to set up executable - memory by using <citerefentry><refentrytitle>mmap</refentrytitle><manvolnum>2</manvolnum></citerefentry> - of <filename>/dev/zero</filename> instead of using <constant>MAP_ANON</constant>.</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. It is possible to run two or more units - within the same private network namespace by using the - <varname>JoinsNamespaceOf=</varname> directive, see - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. Note that this option will disconnect all socket - families from the host, this includes AF_NETLINK and AF_UNIX. - The latter has the effect that AF_UNIX sockets in the abstract - socket namespace will become unavailable to the processes - (however, those located in the file system will continue to be - accessible).</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>ProtectSystem=</varname></term> - - <listitem><para>Takes a boolean argument or - <literal>full</literal>. If true, mounts the - <filename>/usr</filename> and <filename>/boot</filename> - directories read-only for processes invoked by this unit. If - set to <literal>full</literal>, the <filename>/etc</filename> - directory is mounted read-only, too. This setting ensures that - any modification of the vendor-supplied operating system (and - optionally its configuration) is prohibited for the service. - It is recommended to enable this setting for all long-running - services, unless they are involved with system updates or need - to modify the operating system in other ways. Note however - that processes retaining the CAP_SYS_ADMIN capability can undo - the effect of this setting. This setting is hence particularly - useful for daemons which have this capability removed, for - example with <varname>CapabilityBoundingSet=</varname>. - Defaults to off.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>ProtectHome=</varname></term> - - <listitem><para>Takes a boolean argument or - <literal>read-only</literal>. If true, the directories - <filename>/home</filename>, <filename>/root</filename> and - <filename>/run/user</filename> - are made inaccessible and empty for processes invoked by this - unit. If set to <literal>read-only</literal>, the three - directories are made read-only instead. It is recommended to - enable this setting for all long-running services (in - particular network-facing ones), to ensure they cannot get - access to private user data, unless the services actually - require access to the user's private data. Note however that - processes retaining the CAP_SYS_ADMIN capability can undo the - effect of this setting. This setting is hence particularly - useful for daemons which have this capability removed, for - example with <varname>CapabilityBoundingSet=</varname>. - Defaults to off.</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 mounts in the - file system namespace set up for this unit's processes will - receive or propagate mounts or unmounts. See - <citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for details. Defaults to <option>shared</option>. Use - <option>shared</option> to ensure that mounts and unmounts are - propagated from the host to the container and vice versa. Use - <option>slave</option> to run processes so that none of their - mounts and unmounts will propagate to the host. Use - <option>private</option> to also ensure that no mounts and - unmounts from the host will propagate into the unit processes' - namespace. Note that <option>slave</option> means that file - systems mounted on the host might stay mounted continuously in - the unit's namespace, and thus keep the device busy. Note that - the file system namespace related options - (<varname>PrivateTmp=</varname>, - <varname>PrivateDevices=</varname>, - <varname>ProtectSystem=</varname>, - <varname>ProtectHome=</varname>, - <varname>ReadOnlyDirectories=</varname>, - <varname>InaccessibleDirectories=</varname> and - <varname>ReadWriteDirectories=</varname>) require that mount - and unmount propagation from the unit's file system namespace - is disabled, and hence downgrade <option>shared</option> to - <option>slave</option>. </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>UtmpIdentifier=</varname></term> - - <listitem><para>Takes a four character identifier string for - an <citerefentry - project='man-pages'><refentrytitle>utmp</refentrytitle><manvolnum>5</manvolnum></citerefentry> - and wtmp entry for this service. This should only be - set for services such as <command>getty</command> - implementations (such as <citerefentry - project='die-net'><refentrytitle>agetty</refentrytitle><manvolnum>8</manvolnum></citerefentry>) - where utmp/wtmp entries must be created and cleared before and - after execution, or for services that shall be executed as if - they were run by a <command>getty</command> process (see - below). 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>UtmpMode=</varname></term> - - <listitem><para>Takes one of <literal>init</literal>, - <literal>login</literal> or <literal>user</literal>. If - <varname>UtmpIdentifier=</varname> is set, controls which - type of <citerefentry - project='man-pages'><refentrytitle>utmp</refentrytitle><manvolnum>5</manvolnum></citerefentry>/wtmp - entries for this service are generated. This setting has no - effect unless <varname>UtmpIdentifier=</varname> is set - too. If <literal>init</literal> is set, only an - <constant>INIT_PROCESS</constant> entry is generated and the - invoked process must implement a - <command>getty</command>-compatible utmp/wtmp logic. If - <literal>login</literal> is set, first an - <constant>INIT_PROCESS</constant> entry, followed by a - <constant>LOGIN_PROCESS</constant> entry is generated. In - this case, the invoked process must implement a <citerefentry - project='die-net'><refentrytitle>login</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible - utmp/wtmp logic. If <literal>user</literal> is set, first an - <constant>INIT_PROCESS</constant> entry, then a - <constant>LOGIN_PROCESS</constant> entry and finally a - <constant>USER_PROCESS</constant> entry is generated. In this - case, the invoked process may be any process that is suitable - to be run as session leader. Defaults to - <literal>init</literal>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>SELinuxContext=</varname></term> - - <listitem><para>Set the SELinux security context of the - executed process. If set, this will override the automated - domain transition. However, the policy still needs to - authorize the transition. This directive is ignored if SELinux - is disabled. If prefixed by <literal>-</literal>, all errors - will be ignored. See - <citerefentry project='die-net'><refentrytitle>setexeccon</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for details.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>AppArmorProfile=</varname></term> - - <listitem><para>Takes a profile name as argument. The process - executed by the unit will switch to this profile when started. - Profiles must already be loaded in the kernel, or the unit - will fail. This result in a non operation if AppArmor is not - enabled. If prefixed by <literal>-</literal>, all errors will - be ignored. </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>SmackProcessLabel=</varname></term> - - <listitem><para>Takes a <option>SMACK64</option> security - label as argument. The process executed by the unit will be - started under this label and SMACK will decide whether the - process is allowed to run or not, based on it. The process - will continue to run under the label specified here unless the - executable has its own <option>SMACK64EXEC</option> label, in - which case the process will transition to run under that - label. When not specified, the label that systemd is running - under is used. This directive is ignored if SMACK is - disabled.</para> - - <para>The value may be prefixed by <literal>-</literal>, in - which case all errors will be ignored. An empty value may be - specified to unset previous assignments.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>IgnoreSIGPIPE=</varname></term> - - <listitem><para>Takes a boolean argument. If true, causes - <constant>SIGPIPE</constant> to be ignored in the executed - process. Defaults to true because <constant>SIGPIPE</constant> - 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 processes except for the listed ones will result in - immediate process termination with the - <constant>SIGSYS</constant> 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 running in - user mode, or in system mode, but without the - <constant>CAP_SYS_ADMIN</constant> capabiblity (e.g. setting - <varname>User=nobody</varname>), - <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 do not need to be - listed explicitly. This option may be specified more than once, - in which case the filter masks are merged. If the empty string - is assigned, the filter is reset, all prior assignments will - have no effect.</para> - - <para>If you specify both types of this option (i.e. - whitelisting and blacklisting), the first encountered will - take precedence and will dictate the default action - (termination or approval of a system call). Then the next - occurrences of this option will add or delete the listed - system calls from the set of the filtered system calls, - depending of its type and the default action. (For example, if - you have started with a whitelisting of - <function>read</function> and <function>write</function>, and - right after it add a blacklisting of - <function>write</function>, then <function>write</function> - will be removed from the set.) </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>SystemCallErrorNumber=</varname></term> - - <listitem><para>Takes an <literal>errno</literal> error number - name to return when the system call filter configured with - <varname>SystemCallFilter=</varname> is triggered, instead of - terminating the process immediately. Takes an error name such - as <constant>EPERM</constant>, <constant>EACCES</constant> or - <constant>EUCLEAN</constant>. When this setting is not used, - or when the empty string is assigned, the process will be - terminated immediately when the filter is - triggered.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>SystemCallArchitectures=</varname></term> - - <listitem><para>Takes a space-separated list of architecture - identifiers to include in the system call filter. The known - architecture identifiers are <constant>x86</constant>, - <constant>x86-64</constant>, <constant>x32</constant>, - <constant>arm</constant> as well as the special identifier - <constant>native</constant>. Only system calls of the - specified architectures will be permitted to processes of this - unit. This is an effective way to disable compatibility with - non-native architectures for processes, for example to - prohibit execution of 32-bit x86 binaries on 64-bit x86-64 - systems. The special <constant>native</constant> identifier - implicitly maps to the native architecture of the system (or - more strictly: to the architecture the system manager is - compiled for). If running in user mode, or in system mode, - but without the <constant>CAP_SYS_ADMIN</constant> - capabiblity (e.g. setting <varname>User=nobody</varname>), - <varname>NoNewPrivileges=yes</varname> is implied. Note - that setting this option to a non-empty list implies that - <constant>native</constant> is included too. By default, this - option is set to the empty list, i.e. no architecture system - call filtering is applied.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>RestrictAddressFamilies=</varname></term> - - <listitem><para>Restricts the set of socket address families - accessible to the processes of this unit. Takes a - space-separated list of address family names to whitelist, - such as - <constant>AF_UNIX</constant>, - <constant>AF_INET</constant> or - <constant>AF_INET6</constant>. When - prefixed with <constant>~</constant> the listed address - families will be applied as blacklist, otherwise as whitelist. - Note that this restricts access to the - <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum></citerefentry> - system call only. Sockets passed into the process by other - means (for example, by using socket activation with socket - units, see - <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>) - are unaffected. Also, sockets created with - <function>socketpair()</function> (which creates connected - AF_UNIX sockets only) are unaffected. Note that this option - has no effect on 32-bit x86 and is ignored (but works - correctly on x86-64). If running in user mode, or in system - mode, but without the <constant>CAP_SYS_ADMIN</constant> - capabiblity (e.g. setting <varname>User=nobody</varname>), - <varname>NoNewPrivileges=yes</varname> is implied. By - default, no restriction applies, all address families are - accessible to processes. If assigned the empty string, any - previous list changes are undone.</para> - - <para>Use this option to limit exposure of processes to remote - systems, in particular via exotic network protocols. Note that - in most cases, the local <constant>AF_UNIX</constant> address - family should be included in the configured whitelist as it is - frequently used for local communication, including for - <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>2</manvolnum></citerefentry> - logging.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Personality=</varname></term> - - <listitem><para>Controls which kernel architecture <citerefentry - project='man-pages'><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry> shall report, - when invoked by unit processes. Takes one of the architecture identifiers <constant>x86</constant>, - <constant>x86-64</constant>, <constant>ppc</constant>, <constant>ppc-le</constant>, <constant>ppc64</constant>, - <constant>ppc64-le</constant>, <constant>s390</constant> or <constant>s390x</constant>. Which personality - architectures are supported depends on the system architecture. Usually the 64bit versions of the various - system architectures support their immediate 32bit personality architecture counterpart, but no others. For - example, <constant>x86-64</constant> systems support the <constant>x86-64</constant> and - <constant>x86</constant> personalities but no others. The personality feature is useful when running 32-bit - services on a 64-bit host system. If not specified, the personality is left unmodified and thus reflects the - personality of the host system's kernel.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>RuntimeDirectory=</varname></term> - <term><varname>RuntimeDirectoryMode=</varname></term> - - <listitem><para>Takes a list of directory names. If set, one - or more directories by the specified names will be created - below <filename>/run</filename> (for system services) or below - <varname>$XDG_RUNTIME_DIR</varname> (for user services) when - the unit is started, and removed when the unit is stopped. The - directories will have the access mode specified in - <varname>RuntimeDirectoryMode=</varname>, and will be owned by - the user and group specified in <varname>User=</varname> and - <varname>Group=</varname>. Use this to manage one or more - runtime directories of the unit and bind their lifetime to the - daemon runtime. The specified directory names must be - relative, and may not include a <literal>/</literal>, i.e. - must refer to simple directories to create or remove. This is - particularly useful for unprivileged daemons that cannot - create runtime directories in <filename>/run</filename> due to - lack of privileges, and to make sure the runtime directory is - cleaned up automatically after use. For runtime directories - that require more complex or different configuration or - lifetime guarantees, please consider using - <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> - </varlistentry> - - </variablelist> - </refsect1> - - <refsect1> - <title>Environment variables in spawned processes</title> - - <para>Processes started by the system are executed in a clean - environment in which select variables listed below are set. System - processes started by systemd do not inherit variables from PID 1, - but processes started by user systemd instances inherit all - environment variables from the user systemd instance. - </para> - - <variablelist class='environment-variables'> - <varlistentry> - <term><varname>$PATH</varname></term> - - <listitem><para>Colon-separated list of directories to use - when launching executables. Systemd uses a fixed value of - <filename>/usr/local/sbin</filename>:<filename>/usr/local/bin</filename>:<filename>/usr/sbin</filename>:<filename>/usr/bin</filename>:<filename>/sbin</filename>:<filename>/bin</filename>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$LANG</varname></term> - - <listitem><para>Locale. Can be set in - <citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - or on the kernel command line (see - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry>). - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$USER</varname></term> - <term><varname>$LOGNAME</varname></term> - <term><varname>$HOME</varname></term> - <term><varname>$SHELL</varname></term> - - <listitem><para>User name (twice), home directory, and the - login shell. The variables are set for the units that have - <varname>User=</varname> set, which includes user - <command>systemd</command> instances. See - <citerefentry project='die-net'><refentrytitle>passwd</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$XDG_RUNTIME_DIR</varname></term> - - <listitem><para>The directory for volatile state. Set for the - user <command>systemd</command> instance, and also in user - sessions. See - <citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$XDG_SESSION_ID</varname></term> - <term><varname>$XDG_SEAT</varname></term> - <term><varname>$XDG_VTNR</varname></term> - - <listitem><para>The identifier of the session, the seat name, - and virtual terminal of the session. Set by - <citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for login sessions. <varname>$XDG_SEAT</varname> and - <varname>$XDG_VTNR</varname> will only be set when attached to - a seat and a tty.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$MAINPID</varname></term> - - <listitem><para>The PID of the units main process if it is - known. This is only set for control processes as invoked by - <varname>ExecReload=</varname> and similar. </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$MANAGERPID</varname></term> - - <listitem><para>The PID of the user <command>systemd</command> - instance, set for processes spawned by it. </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$LISTEN_FDS</varname></term> - <term><varname>$LISTEN_PID</varname></term> - <term><varname>$LISTEN_FDNAMES</varname></term> - - <listitem><para>Information about file descriptors passed to a - service for socket activation. See - <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$NOTIFY_SOCKET</varname></term> - - <listitem><para>The socket - <function>sd_notify()</function> talks to. See - <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$WATCHDOG_PID</varname></term> - <term><varname>$WATCHDOG_USEC</varname></term> - - <listitem><para>Information about watchdog keep-alive notifications. See - <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$TERM</varname></term> - - <listitem><para>Terminal type, set only for units connected to - a terminal (<varname>StandardInput=tty</varname>, - <varname>StandardOutput=tty</varname>, or - <varname>StandardError=tty</varname>). See - <citerefentry project='man-pages'><refentrytitle>termcap</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - </para></listitem> - </varlistentry> - </variablelist> - - <para>Additional variables may be configured by the following - means: for processes spawned in specific units, use the - <varname>Environment=</varname>, <varname>EnvironmentFile=</varname> - and <varname>PassEnvironment=</varname> options above; to specify - variables globally, use <varname>DefaultEnvironment=</varname> - (see - <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>) - or the kernel option <varname>systemd.setenv=</varname> (see - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>). - Additional variables may also be set through PAM, - cf. <citerefentry project='man-pages'><refentrytitle>pam_env</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</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>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>, - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>exec</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd.generator.xml b/man/systemd.generator.xml deleted file mode 100644 index 4b80dab108..0000000000 --- a/man/systemd.generator.xml +++ /dev/null @@ -1,348 +0,0 @@ -<?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" [ -<!ENTITY % entities SYSTEM "custom-entities.ent" > -%entities; -]> - -<!-- - This file is part of systemd. - - Copyright 2015 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.generator"> - <refentryinfo> - <title>systemd.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.generator</refentrytitle> - <manvolnum>7</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd.generator</refname> - <refpurpose>Systemd unit generators</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>/path/to/generator</command> - <arg choice="plain"><replaceable>normal-dir</replaceable></arg> - <arg choice="plain"><replaceable>early-dir</replaceable></arg> - <arg choice="plain"><replaceable>late-dir</replaceable></arg> - </cmdsynopsis> - - <para> - <literallayout><filename>/run/systemd/system-generators/*</filename> -<filename>/etc/systemd/system-generators/*</filename> -<filename>/usr/local/lib/systemd/system-generators/*</filename> -<filename>&systemgeneratordir;/*</filename></literallayout> - </para> - - <para> - <literallayout><filename>/run/systemd/user-generators/*</filename> -<filename>/etc/systemd/user-generators/*</filename> -<filename>/usr/local/lib/systemd/user-generators/*</filename> -<filename>&usergeneratordir;/*</filename></literallayout> - </para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - <para>Generators are small binaries that live in - <filename>&usergeneratordir;/</filename> and other directories - listed above. - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> - will execute those binaries very early at bootup and at - configuration reload time — before unit files are loaded. - Generators can dynamically generate unit files or create symbolic - links to unit files to add additional dependencies, thus extending - or overriding existing definitions. Their main purpose is to - convert configuration files that are not native unit files - dynamically into native unit files.</para> - - <para>Generators are loaded from a set of paths determined during - compilation, as listed above. System and user generators are loaded - from directories with names ending in - <filename>system-generators/</filename> and - <filename>user-generators/</filename>, respectively. Generators - found in directories listed earlier override the ones with the - same name in directories lower in the list. A symlink to - <filename>/dev/null</filename> or an empty file can be used to - mask a generator, thereby preventing it from running. Please note - that the order of the two directories with the highest priority is - reversed with respect to the unit load path, and generators in - <filename>/run</filename> overwrite those in - <filename>/etc</filename>.</para> - - <para>After installing new generators or updating the - configuration, <command>systemctl daemon-reload</command> may be - executed. This will delete the previous configuration created by - generators, re-run all generators, and cause - <command>systemd</command> to reload units from disk. See - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - for more information. - </para> - </refsect1> - - <refsect1> - <title>Writing generators</title> - - <para>Generators are invoked with three arguments: paths to - runtime directories where generators can place their generated - unit files or symlinks.</para> - - <orderedlist> - <listitem> - <para><parameter>normal-dir</parameter></para> - <para>argv[1] may be used to override unit files in - <filename>/usr</filename>, but not those in - <filename>/etc</filename>. This means that unit files placed - in this directory take precedence over vendor unit - configuration but not over native user/administrator unit - configuration.</para> - </listitem> - - <listitem> - <para><parameter>early-dir</parameter></para> - <para>argv[2] may be used to override unit files in - <filename>/usr</filename> and in - <filename>/etc</filename>. This means that unit files placed - in this directory take precedence over all configuration, - both vendor and user/administrator.</para> - </listitem> - - <listitem> - <para><parameter>late-dir</parameter></para> - <para>argv[3] may be used to extend the unit file tree without - overriding any other unit files. Any native configuration - files supplied by the vendor or user/administrator take - precedence over the generated ones placed in this directory. - </para> - </listitem> - </orderedlist> - - <refsect2> - <title>Notes</title> - - <itemizedlist> - <listitem> - <para> - All generators are executed in parallel. That means all - executables are started at the very same time and need to - be able to cope with this parallelism. - </para> - </listitem> - - <listitem> - <para> - Generators are run very early at boot and cannot rely on - any external services. They may not talk to any other - process. That includes simple things such as logging to - <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - or <command>systemd</command> itself (this means: no - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>)!. - Non-essential file systems like - <filename>/var</filename> and <filename>/home</filename> - are mounted after generators have run. Generators - can however rely on the most basic kernel functionality to be - available, including a mounted <filename>/sys</filename>, - <filename>/proc</filename>, <filename>/dev</filename>, - <filename>/usr</filename>. - </para> - </listitem> - - <listitem> - <para> - Units written by generators are removed when the configuration - is reloaded. That means the lifetime of the generated - units is closely bound to the reload cycles of - <command>systemd</command> itself. - </para> - </listitem> - - <listitem> - <para> - Generators should only be used to generate unit files, not - any other kind of configuration. Due to the lifecycle - logic mentioned above, generators are not a good fit to - generate dynamic configuration for other services. If you - need to generate dynamic configuration for other services, - do so in normal services you order before the service in - question. - </para> - </listitem> - - <listitem> - <para> - Since - <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> - is not available (see above), log messages have to be - written to <filename>/dev/kmsg</filename> instead. - </para> - </listitem> - - <listitem> - <para> - It is a good idea to use the - <varname>SourcePath=</varname> directive in generated unit - files to specify the source configuration file you are - generating the unit from. This makes things more easily - understood by the user and also has the benefit that - systemd can warn the user about configuration files that - changed on disk but have not been read yet by systemd. - </para> - </listitem> - - <listitem> - <para> - Generators may write out dynamic unit files or just hook - unit files into other units with the usual - <filename>.wants/</filename> or - <filename>.requires/</filename> symlinks. Often, it is - nicer to simply instantiate a template unit file from - <filename>/usr</filename> with a generator instead of - writing out entirely dynamic unit files. Of course, this - works only if a single parameter is to be used. - </para> - </listitem> - - <listitem> - <para> - If you are careful, you can implement generators in shell - scripts. We do recommend C code however, since generators - are executed synchronously and hence delay the - entire boot if they are slow. - </para> - </listitem> - - <listitem> - <para>Regarding overriding semantics: there are two rules we - try to follow when thinking about the overriding semantics: - </para> - - <orderedlist numeration="lowerroman"> - <listitem> - <para>User configuration should override vendor - configuration. This (mostly) means that stuff from - <filename>/etc</filename> should override stuff from - <filename>/usr</filename>.</para> - </listitem> - - <listitem> - <para>Native configuration should override non-native - configuration. This (mostly) means that stuff you - generate should never override native unit files for the - same purpose.</para> - </listitem> - </orderedlist> - - <para>Of these two rules the first rule is probably the more - important one and breaks the second one sometimes. Hence, - when deciding whether to user argv[1], argv[2], or argv[3], - your default choice should probably be argv[1].</para> - </listitem> - - <listitem> - <para> - Instead of heading off now and writing all kind of - generators for legacy configuration file formats, please - think twice! It is often a better idea to just deprecate - old stuff instead of keeping it artificially alive. - </para> - </listitem> - </itemizedlist> - </refsect2> - </refsect1> - - <refsect1> - <title>Examples</title> - <example> - <title>systemd-fstab-generator</title> - - <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> - converts <filename>/etc/fstab</filename> into native mount - units. It uses argv[1] as location to place the generated unit - files in order to allow the user to override - <filename>/etc/fstab</filename> with her own native unit files, - but also to ensure that <filename>/etc/fstab</filename> - overrides any vendor default from <filename>/usr</filename>. - </para> - - <para>After editing <filename>/etc/fstab</filename>, the user - should invoke <command>systemctl daemon-reload</command>. This - will re-run all generators and cause <command>systemd</command> - to reload units from disk. To actually mount new directories - added to <filename>fstab</filename>, <command>systemctl start - <replaceable>/path/to/mountpoint</replaceable></command> or - <command>systemctl start local-fs.target</command> may be used. - </para> - </example> - - <example> - <title>systemd-system-update-generator</title> - - <para><citerefentry><refentrytitle>systemd-system-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> - temporarily redirects <filename>default.target</filename> to - <filename>system-update.target</filename> if a system update is - scheduled. Since this needs to override the default user - configuration for <filename>default.target</filename>, it uses - argv[2]. For details about this logic, see - <ulink url="http://www.freedesktop.org/wiki/Software/systemd/SystemUpdates">Implementing - Offline System Updates</ulink>.</para> - </example> - - <example> - <title>Debugging a generator</title> - - <programlisting>dir=$(mktemp -d) -SYSTEMD_LOG_LEVEL=debug &systemgeneratordir;/systemd-fstab-generator \ - "$dir" "$dir" "$dir" -find $dir</programlisting> - </example> - </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>systemd-debug-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-getty-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-hibernate-resume-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-system-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-sysv-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> -</refentry> diff --git a/man/systemd.journal-fields.xml b/man/systemd.journal-fields.xml deleted file mode 100644 index 494f97aad1..0000000000 --- a/man/systemd.journal-fields.xml +++ /dev/null @@ -1,525 +0,0 @@ -<?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 but 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 metadata.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>MESSAGE_ID=</varname></term> - <listitem> - <para>A 128-bit message identifier ID for recognizing - certain message types, if this is desirable. This should - contain a 128-bit ID formatted as a 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 - <option>--new-id</option></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 a 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 filename, 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 project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry> - formatted as a 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. (Note that the tag is usually - derived from glibc's - <varname>program_invocation_short_name</varname> variable, - see - <citerefentry project='die-net'><refentrytitle>program_invocation_short_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>.)</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 a 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>_CAP_EFFECTIVE=</varname></term> - <listitem> - <para>The effective - <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> - 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_USER_UNIT=</varname></term> - <term><varname>_SYSTEMD_OWNER_UID=</varname></term> - <term><varname>_SYSTEMD_SLICE=</varname></term> - - <listitem> - <para>The control group path in the systemd hierarchy, the - systemd session ID (if any), the systemd unit name (if any), - the systemd user session unit name (if any), the owner UID - of the systemd session (if any) and the systemd slice unit - of the process the journal entry originates from.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>_SELINUX_CONTEXT=</varname></term> - <listitem> - <para>The SELinux security context (label) 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 microseconds since the epoch - UTC, formatted as a 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 a 128-bit 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. - Valid transports are: - </para> - <variablelist> - <varlistentry> - <term> - <option>audit</option> - </term> - <listitem> - <para>for those read from the kernel audit subsystem - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>driver</option> - </term> - <listitem> - <para>for internally generated messages - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>syslog</option> - </term> - <listitem> - <para>for those received via the local syslog socket - with the syslog protocol - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>journal</option> - </term> - <listitem> - <para>for those received via the native journal - protocol - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>stdout</option> - </term> - <listitem> - <para>for those read from a service's standard output - or error output - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>kernel</option> - </term> - <listitem> - <para>for those read from the kernel - </para> - </listitem> - </varlistentry> - </variablelist> - </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 class='journal-directives'> - <varlistentry> - <term><varname>_KERNEL_DEVICE=</varname></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 <literal>:</literal> and prefixed by - <literal>b</literal>. Similar for character devices but - prefixed by <literal>c</literal>. For network devices, this - is the interface index prefixed by <literal>n</literal>. For - all other devices, this is the subsystem name prefixed by - <literal>+</literal>, followed by <literal>:</literal>, - followed by the kernel device name.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>_KERNEL_SUBSYSTEM=</varname></term> - <listitem> - <para>The kernel subsystem name.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>_UDEV_SYSNAME=</varname></term> - <listitem> - <para>The kernel device name as it shows up in the device - tree below <filename>/sys</filename>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>_UDEV_DEVNODE=</varname></term> - <listitem> - <para>The device node path of this device in - <filename>/dev</filename>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>_UDEV_DEVLINK=</varname></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>Fields to log on behalf of a different program</title> - - <para>Fields in this section are used by programs to specify that - they are logging on behalf of another program or unit. - </para> - - <para>Fields used by the <command>systemd-coredump</command> - coredump kernel helper: - </para> - - <variablelist class='journal-directives'> - <varlistentry> - <term><varname>COREDUMP_UNIT=</varname></term> - <term><varname>COREDUMP_USER_UNIT=</varname></term> - <listitem> - <para>Used to annotate messages containing coredumps from - system and session units. See - <citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. - </para> - </listitem> - </varlistentry> - </variablelist> - - <para>Privileged programs (currently UID 0) may attach - <varname>OBJECT_PID=</varname> to a message. This will instruct - <command>systemd-journald</command> to attach additional fields on - behalf of the caller:</para> - - <variablelist class='journal-directives'> - <varlistentry> - <term><varname>OBJECT_PID=<replaceable>PID</replaceable></varname></term> - <listitem> - <para>PID of the program that this message pertains to. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>OBJECT_UID=</varname></term> - <term><varname>OBJECT_GID=</varname></term> - <term><varname>OBJECT_COMM=</varname></term> - <term><varname>OBJECT_EXE=</varname></term> - <term><varname>OBJECT_CMDLINE=</varname></term> - <term><varname>OBJECT_AUDIT_SESSION=</varname></term> - <term><varname>OBJECT_AUDIT_LOGINUID=</varname></term> - <term><varname>OBJECT_SYSTEMD_CGROUP=</varname></term> - <term><varname>OBJECT_SYSTEMD_SESSION=</varname></term> - <term><varname>OBJECT_SYSTEMD_OWNER_UID=</varname></term> - <term><varname>OBJECT_SYSTEMD_UNIT=</varname></term> - <term><varname>OBJECT_SYSTEMD_USER_UNIT=</varname></term> - <listitem> - <para>These are additional fields added automatically by - <command>systemd-journald</command>. Their meaning is the - same as - <varname>_UID=</varname>, - <varname>_GID=</varname>, - <varname>_COMM=</varname>, - <varname>_EXE=</varname>, - <varname>_CMDLINE=</varname>, - <varname>_AUDIT_SESSION=</varname>, - <varname>_AUDIT_LOGINUID=</varname>, - <varname>_SYSTEMD_CGROUP=</varname>, - <varname>_SYSTEMD_SESSION=</varname>, - <varname>_SYSTEMD_UNIT=</varname>, - <varname>_SYSTEMD_USER_UNIT=</varname>, and - <varname>_SYSTEMD_OWNER_UID=</varname> - as described above, except that the process identified by - <replaceable>PID</replaceable> is described, instead of the - process which logged the message.</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 are not proper fields when stored in the journal but for - addressing metadata 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 - (<constant>CLOCK_REALTIME</constant>) at the point in time - the entry was received by the journal, in microseconds since - the epoch UTC, formatted as a 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 - (<constant>CLOCK_MONOTONIC</constant>) at the point in time - the entry was received by the journal in microseconds, - formatted as a decimal string. To be useful as an address - for the entry, this should be combined with the 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>, - <citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd.kill.xml b/man/systemd.kill.xml deleted file mode 100644 index 13b7ab14df..0000000000 --- a/man/systemd.kill.xml +++ /dev/null @@ -1,189 +0,0 @@ -<?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.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>Process killing procedure - configuration</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename><replaceable>service</replaceable>.service</filename>, - <filename><replaceable>socket</replaceable>.socket</filename>, - <filename><replaceable>mount</replaceable>.mount</filename>, - <filename><replaceable>swap</replaceable>.swap</filename>, - <filename><replaceable>scope</replaceable>.scope</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>Unit configuration files for services, sockets, mount - points, swap devices and scopes share a subset of configuration - options which define the killing procedure of processes belonging - to the unit.</para> - - <para>This man page lists the configuration options shared by - these five unit types. See - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for the common options shared by 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>, - <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more information on the configuration file options specific to - each unit type.</para> - - <para>The kill procedure configuration options are configured in - the [Service], [Socket], [Mount] or [Swap] section, depending on - the unit type.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <variablelist class='unit-directives'> - - <varlistentry> - <term><varname>KillMode=</varname></term> - <listitem><para>Specifies how processes of this unit shall be - killed. One of - <option>control-group</option>, - <option>process</option>, - <option>mixed</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 killed 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>mixed</option>, the - <constant>SIGTERM</constant> signal (see below) is sent to the - main process while the subsequent <constant>SIGKILL</constant> - signal (see below) is sent to all remaining processes of the - unit's control group. 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.</para> - - <para>Processes will first be terminated via - <constant>SIGTERM</constant> (unless the signal to send is - changed via <varname>KillSignal=</varname>). Optionally, this - is immediately followed by a <constant>SIGHUP</constant> (if - enabled with <varname>SendSIGHUP=</varname>). If then, after a - delay (configured via the <varname>TimeoutStopSec=</varname> - option), processes still remain, the termination request is - repeated with the <constant>SIGKILL</constant> signal (unless - this is disabled via the <varname>SendSIGKILL=</varname> - option). See - <citerefentry><refentrytitle>kill</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for more information.</para> - - <para>Defaults to - <option>control-group</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>KillSignal=</varname></term> - <listitem><para>Specifies which signal to use when killing a - service. This controls the signal that is sent as first step - of shutting down a unit (see above), and is usually followed - by <constant>SIGKILL</constant> (see above and below). For a - list of valid signals, see - <citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>. - Defaults to <constant>SIGTERM</constant>. </para> - - <para>Note that, right after sending the signal specified in - this setting, systemd will always send - <constant>SIGCONT</constant>, to ensure that even suspended - tasks can be terminated cleanly.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>SendSIGHUP=</varname></term> - <listitem><para>Specifies whether to send - <constant>SIGHUP</constant> to remaining processes immediately - after sending the signal configured with - <varname>KillSignal=</varname>. This is useful to indicate to - shells and shell-like programs that their connection has been - severed. Takes a boolean value. Defaults to "no". - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>SendSIGKILL=</varname></term> - <listitem><para>Specifies whether to send - <constant>SIGKILL</constant> 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>1</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>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>kill</refentrytitle><manvolnum>2</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd.link.xml b/man/systemd.link.xml deleted file mode 100644 index d5b4d1038d..0000000000 --- a/man/systemd.link.xml +++ /dev/null @@ -1,477 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2014 Tom Gundersen - - 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.link"> - <refentryinfo> - <title>systemd.link</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Tom</firstname> - <surname>Gundersen</surname> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd.link</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd.link</refname> - <refpurpose>Network device configuration</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename><replaceable>link</replaceable>.link</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>Network link configuration is performed by the - <command>net_setup_link</command> udev builtin.</para> - - <para>The link files are read from the files located in the system - network directory <filename>/usr/lib/systemd/network</filename>, - the volatile runtime network directory - <filename>/run/systemd/network</filename>, and the local - administration network directory - <filename>/etc/systemd/network</filename>. Link files must have - the extension <filename>.link</filename>; other extensions are - ignored. All link files are collectively sorted and processed in - lexical order, regardless of the directories in which they live. - However, files with identical filenames 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>/usr/lib</filename>. This can be used to - override a system-supplied link file with a local file if needed. - As a special case, an empty file (file size 0) or symlink with the - same name pointing to <filename>/dev/null</filename> disables the - configuration file entirely (it is "masked").</para> - - <para>The link file contains a <literal>[Match]</literal> section, - which determines if a given link file may be applied to a given - device, as well as a <literal>[Link]</literal> section specifying - how the device should be configured. The first (in lexical order) - of the link files that matches a given device is applied. Note - that a default file <filename>99-default.link</filename> is - shipped by the system, any user-supplied - <filename>.link</filename> should hence have a lexically earlier - name to be considered at all.</para> - - <para>See - <citerefentry><refentrytitle>udevadm</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for diagnosing problems with <filename>.link</filename> files.</para> - </refsect1> - - <refsect1> - <title>[Match] Section Options</title> - - <para>A link file is said to match a device if each of the entries - in the <literal>[Match]</literal> section matches, or if the - section is empty. The following keys are accepted:</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>MACAddress=</varname></term> - <listitem> - <para>The hardware address.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>OriginalName=</varname></term> - <listitem> - <para>A whitespace-separated list of shell-style globs matching - the device name, as exposed by the udev property - "INTERFACE". This can not be used to match on names that have - already been changed from userspace. Caution is advised when matching on - kernel-assigned names, as they are known to be unstable - between reboots.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Path=</varname></term> - <listitem> - <para>A whitespace-separated list of shell-style globs matching - the persistent path, as exposed by the udev property - <literal>ID_PATH</literal>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Driver=</varname></term> - <listitem> - <para>A whitespace-separated list of shell-style globs matching - the driver currently bound to the device, - as exposed by the udev property <literal>DRIVER</literal> - of its parent device, or if that is not set, the - driver as exposed by <literal>ethtool -i</literal> - of the device itself.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Type=</varname></term> - <listitem> - <para>A whitespace-separated list of shell-style globs matching - the device type, as exposed by the udev - property <literal>DEVTYPE</literal>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Host=</varname></term> - <listitem> - <para>Matches against the hostname or machine - ID of the host. See <literal>ConditionHost=</literal> in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Virtualization=</varname></term> - <listitem> - <para>Checks whether the system is executed in - a virtualized environment and optionally test - whether it is a specific implementation. See - <literal>ConditionVirtualization=</literal> in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>KernelCommandLine=</varname></term> - <listitem> - <para>Checks whether a specific kernel command line option - is set (or if prefixed with the exclamation mark unset). See - <literal>ConditionKernelCommandLine=</literal> in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Architecture=</varname></term> - <listitem> - <para>Checks whether the system is running on a specific - architecture. See <literal>ConditionArchitecture=</literal> - in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details.</para> - </listitem> - </varlistentry> - </variablelist> - - </refsect1> - - <refsect1> - <title>[Link] Section Options</title> - - <para>The <literal>[Link]</literal> section accepts the following - keys:</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>Description=</varname></term> - <listitem> - <para>A description of the device.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Alias=</varname></term> - <listitem> - <para>The <literal>ifalias</literal> is set to this - value.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>MACAddressPolicy=</varname></term> - <listitem> - <para>The policy by which the MAC address should be set. The - available policies are: - </para> - - <variablelist> - <varlistentry> - <term><literal>persistent</literal></term> - <listitem> - <para>If the hardware has a persistent MAC address, as - most hardware should, and if it is used by the kernel, - nothing is done. Otherwise, a new MAC address is - generated which is guaranteed to be the same on every - boot for the given machine and the given device, but - which is otherwise random. This feature depends on ID_NET_NAME_* - properties to exist for the link. On hardware where these - properties are not set, the generation of a persistent MAC address - will fail.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>random</literal></term> - <listitem> - <para>If the kernel is using a random MAC address, - nothing is done. Otherwise, a new address is randomly - generated each time the device appears, typically at - boot. Either way, the random address will have the - <literal>unicast</literal> and - <literal>locally administered</literal> bits set.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>none</literal></term> - <listitem> - <para>Keeps the MAC address assigned by the kernel.</para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>MACAddress=</varname></term> - <listitem> - <para>The MAC address to use, if no - <literal>MACAddressPolicy=</literal> - is specified.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>NamePolicy=</varname></term> - <listitem> - <para>An ordered, space-separated list of policies by which - the interface name should be set. - <literal>NamePolicy</literal> may be disabled by specifying - <literal>net.ifnames=0</literal> on the kernel command line. - Each of the policies may fail, and the first successful one - is used. The name is not set directly, but is exported to - udev as the property <literal>ID_NET_NAME</literal>, which - is, by default, used by a udev rule to set - <literal>NAME</literal>. If the name has already been set by - userspace, no renaming is performed. The available policies - are:</para> - - <variablelist> - <varlistentry> - <term><literal>kernel</literal></term> - <listitem> - <para>If the kernel claims that the name it has set - for a device is predictable, then no renaming is - performed.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>database</literal></term> - <listitem> - <para>The name is set based on entries in the udev's - Hardware Database with the key - <literal>ID_NET_NAME_FROM_DATABASE</literal>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>onboard</literal></term> - <listitem> - <para>The name is set based on information given by - the firmware for on-board devices, as exported by the - udev property <literal>ID_NET_NAME_ONBOARD</literal>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>slot</literal></term> - <listitem> - <para>The name is set based on information given by - the firmware for hot-plug devices, as exported by the - udev property <literal>ID_NET_NAME_SLOT</literal>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>path</literal></term> - <listitem> - <para>The name is set based on the device's physical - location, as exported by the udev property - <literal>ID_NET_NAME_PATH</literal>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>mac</literal></term> - <listitem> - <para>The name is set based on the device's persistent - MAC address, as exported by the udev property - <literal>ID_NET_NAME_MAC</literal>.</para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Name=</varname></term> - <listitem> - <para>The interface name to use in case all the - policies specified in - <varname>NamePolicy=</varname> fail, or in case - <varname>NamePolicy=</varname> is missing or - disabled.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>MTUBytes=</varname></term> - <listitem> - <para>The maximum transmission unit in bytes to set for the - device. The usual suffixes K, M, G, are supported and are - understood to the base of 1024.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>BitsPerSecond=</varname></term> - <listitem> - <para>The speed to set for the device, the value is rounded - down to the nearest Mbps. The usual suffixes K, M, G, are - supported and are understood to the base of 1000.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Duplex=</varname></term> - <listitem> - <para>The duplex mode to set for the device. The accepted - values are <literal>half</literal> and - <literal>full</literal>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>WakeOnLan=</varname></term> - <listitem> - <para>The Wake-on-LAN policy to set for the device. The - supported values are:</para> - - <variablelist> - <varlistentry> - <term><literal>phy</literal></term> - <listitem> - <para>Wake on PHY activity.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>magic</literal></term> - <listitem> - <para>Wake on receipt of a magic packet. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>off</literal></term> - <listitem> - <para>Never wake.</para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Examples</title> - - <example> - <title>/usr/lib/systemd/network/99-default.link</title> - - <para>The link file <filename>99-default.link</filename> that is - shipped with systemd defines the default naming policy for - links.</para> - - <programlisting>[Link] -NamePolicy=kernel database onboard slot path -MACAddressPolicy=persistent</programlisting> - </example> - - <example> - <title>/etc/systemd/network/10-dmz.link</title> - - <para>This example assigns the fixed name - <literal>dmz0</literal> to the interface with the MAC address - 00:a0:de:63:7a:e6:</para> - - <programlisting>[Match] -MACAddress=00:a0:de:63:7a:e6 - -[Link] -Name=dmz0</programlisting> - </example> - - <example> - <title>/etc/systemd/network/10-internet.link</title> - - <para>This example assigns the fixed name - <literal>internet0</literal> to the interface with the device - path <literal>pci-0000:00:1a.0-*</literal>:</para> - - <programlisting>[Match] -Path=pci-0000:00:1a.0-* - -[Link] -Name=internet0</programlisting> - </example> - - <example> - <title>/etc/systemd/network/25-wireless.link</title> - - <para>Here's an overly complex example that shows the use of a large number of [Match] and [Link] settings.</para> - - <programlisting>[Match] -MACAddress=12:34:56:78:9a:bc -Driver=brcmsmac -Path=pci-0000:02:00.0-* -Type=wlan -Virtualization=no -Host=my-laptop -Architecture=x86-64 - -[Link] -Name=wireless0 -MTUBytes=1450 -BitsPerSecond=10M -WakeOnLan=magic -MACAddress=cb:a9:87:65:43:21</programlisting> - </example> - </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>, - <citerefentry> - <refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum> - </citerefentry>, - <citerefentry> - <refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum> - </citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd.mount.xml b/man/systemd.mount.xml deleted file mode 100644 index 66cddd72e0..0000000000 --- a/man/systemd.mount.xml +++ /dev/null @@ -1,406 +0,0 @@ -<?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.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><replaceable>mount</replaceable>.mount</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>A unit configuration file whose name ends in - <literal>.mount</literal> 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 project='man-pages'><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, and in - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - which configure resource control settings for the processes of the - service. Note that the User= and Group= options are not - particularly useful for mount units specifying a - <literal>Type=</literal> option or using configuration not - specified in <filename>/etc/fstab</filename>; - <citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry> - will refuse options that are not listed in - <filename>/etc/fstab</filename> if it is not run as UID 0.</para> - - <para>Mount units must be named after the mount point directories they control. Example: the mount point <filename - noindex='true'>/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>. Note that mount - units cannot be templated, nor is possible to add multiple names to a mount unit by creating additional symlinks to - it.</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>Mount points created at runtime (independently of unit files - or <filename>/etc/fstab</filename>) will be monitored by systemd - and appear like any other mount unit in systemd. See - <filename>/proc/self/mountinfo</filename> description in - <citerefentry project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - </para> - - <para>Some file systems have special semantics as API file systems - for kernel-to-userspace and userspace-to-userspace interfaces. Some - of them may not be changed via mount units, and cannot be - disabled. For a longer discussion see <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/APIFileSystems">API - File Systems</ulink>.</para> - </refsect1> - - <refsect1> - <title>Automatic Dependencies</title> - - <para>If a mount unit is beneath another mount unit in the file - system hierarchy, both a requirement dependency and an ordering - dependency between both units are created automatically.</para> - - <para>Block device backed file systems automatically gain - <varname>BindsTo=</varname> and <varname>After=</varname> type - dependencies on the device unit encapsulating the block - device (see below).</para> - - <para>If traditional file system quota is enabled for a mount - unit, automatic <varname>Wants=</varname> and - <varname>Before=</varname> dependencies on - <filename>systemd-quotacheck.service</filename> and - <filename>quotaon.service</filename> are added.</para> - - <para>For mount units with <varname>DefaultDependencies=yes</varname> in the <literal>[Unit]</literal> section (the - default) a couple additional dependencies are added. Mount units referring to local file systems automatically gain - an <varname>After=</varname> dependency on <filename>local-fs-pre.target</filename>. Network mount units - automatically acquire <varname>After=</varname> dependencies on <filename>remote-fs-pre.target</filename>, - <filename>network.target</filename> and <filename>network-online.target</filename>. Towards the latter a - <varname>Wants=</varname> unit is added as well. Mount units referring to local and network file systems are - distinguished by their file system type specification. In some cases this is not sufficient (for example network - block device based mounts, such as iSCSI), in which case <option>_netdev</option> may be added to the mount option - string of the unit, which forces systemd to consider the mount unit a network mount. Mount units (regardless if - local or network) also acquire automatic <varname>Before=</varname> and <varname>Conflicts=</varname> on - <filename>umount.target</filename> in order to be stopped during shutdown.</para> - - <para>Additional implicit dependencies may be added as result of - execution and resource control parameters as documented in - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> - </refsect1> - - <refsect1> - <title><filename>fstab</filename></title> - - <para>Mount units may either be configured via unit files, or via - <filename>/etc/fstab</filename> (see - <citerefentry project='man-pages'><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. In general, - configuring mount points through <filename>/etc/fstab</filename> - is the preferred approach. See - <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for details about the conversion.</para> - - <para>The NFS mount option <option>bg</option> for NFS background mounts - as documented in <citerefentry><refentrytitle>nfs</refentrytitle><manvolnum>5</manvolnum></citerefentry> - is not supported in <filename>/etc/fstab</filename> entries. The systemd mount option <option>nofail</option> - provides similar functionality and should be used instead.</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. systemd will create a - dependency of type <varname>Wants=</varname> or - <option>Requires</option> (see option <option>nofail</option> - below), from either <filename>local-fs.target</filename> or - <filename>remote-fs.target</filename>, depending whether the file - system is local or remote.</para> - - <variablelist class='fstab-options'> - - <varlistentry> - <term><option>x-systemd.requires=</option></term> - - <listitem><para>Configures a <varname>Requires=</varname> and - an <varname>After=</varname> dependency between the created - mount unit and another systemd unit, such as a device or mount - unit. The argument should be a unit name, or an absolute path - to a device node or mount point. This option may be specified - more than once. This option is particularly useful for mount - point declarations that need an additional device to be around - (such as an external journal device for journal file systems) - or an additional mount to be in place (such as an overlay file - system that merges multiple mount points). See - <varname>After=</varname> and <varname>Requires=</varname> in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>x-systemd.requires-mounts-for=</option></term> - - <listitem><para>Configures a - <varname>RequiresMountsFor=</varname> dependency between the - created mount unit and other mount units. The argument must be - an absolute path. This option may be specified more than once. - See <varname>RequiresMountsFor=</varname> in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>x-systemd.automount</option></term> - - <listitem><para>An automount unit will be created for the file - system. See - <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>x-systemd.idle-timeout=</option></term> - - <listitem><para>Configures the idle timeout of the - automount unit. See <varname>TimeoutIdleSec=</varname> in - <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>x-systemd.device-timeout=</option></term> - - <listitem><para>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 append a unit such as <literal>s</literal>, - <literal>min</literal>, <literal>h</literal>, - <literal>ms</literal>.</para> - - <para>Note that this option can only be used in - <filename>/etc/fstab</filename>, and will be - ignored when part of the <varname>Options=</varname> - setting in a unit file.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>noauto</option></term> - <term><option>auto</option></term> - - <listitem><para>With <option>noauto</option>, this mount will - not be added as a dependency for - <filename>local-fs.target</filename> or - <filename>remote-fs.target</filename>. This means that it will - not be mounted automatically during boot, unless it is pulled - in by some other unit. The <option>auto</option> option has the - opposite meaning and is the default.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>nofail</option></term> - - <listitem><para>With <option>nofail</option>, this mount will - be only wanted, not required, by - <filename>local-fs.target</filename> or - <filename>remote-fs.target</filename>. This means that the - boot will continue even if this mount point is not mounted - successfully.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>x-initrd.mount</option></term> - - <listitem><para>An additional filesystem to be mounted in the - initramfs. See <filename>initrd-fs.target</filename> - description in - <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>. - </para></listitem> - </varlistentry> - </variablelist> - - <para>If a mount point is configured in both - <filename>/etc/fstab</filename> and a unit file that is stored - below <filename>/usr</filename>, the former will take precedence. - If the unit file is stored below <filename>/etc</filename>, it - will take precedence. This means: native unit files take - precedence over traditional configuration files, but this is - superseded by the rule that configuration in - <filename>/etc</filename> will always take precedence over - configuration in <filename>/usr</filename>.</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 class='unit-directives'> - - <varlistentry> - <term><varname>What=</varname></term> - <listitem><para>Takes an absolute path of a device node, file - or other resource to mount. See - <citerefentry project='man-pages'><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 filename. (See above.) This option is - mandatory.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Type=</varname></term> - <listitem><para>Takes a string for the file system type. See - <citerefentry project='man-pages'><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>SloppyOptions=</varname></term> - - <listitem><para>Takes a boolean argument. If true, parsing of - the options specified in <varname>Options=</varname> is - relaxed, and unknown mount options are tolerated. This - corresponds with - <citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s - <parameter>-s</parameter> switch. Defaults to - off.</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 <constant>SIGTERM</constant>, and after another - delay of this time with <constant>SIGKILL</constant>. (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. The - default value is set from the manager configuration file's - <varname>DefaultTimeoutStart=</varname> - variable.</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>1</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.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd.netdev.xml b/man/systemd.netdev.xml deleted file mode 100644 index 8d12c305d2..0000000000 --- a/man/systemd.netdev.xml +++ /dev/null @@ -1,1116 +0,0 @@ -<?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 2013 Tom Gundersen - - 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.netdev" conditional='ENABLE_NETWORKD'> - - <refentryinfo> - <title>systemd.network</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Tom</firstname> - <surname>Gundersen</surname> - <email>teg@jklm.no</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd.netdev</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd.netdev</refname> - <refpurpose>Virtual Network Device configuration</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename><replaceable>netdev</replaceable>.netdev</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>Network setup is performed by - <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>. - </para> - - <para>Virtual Network Device files must have the extension - <filename>.netdev</filename>; other extensions are ignored. - Virtual network devices are created as soon as networkd is - started. If a netdev with the specified name already exists, - networkd will use that as-is rather than create its own. Note that - the settings of the pre-existing netdev will not be changed by - networkd.</para> - - <para>The <filename>.netdev</filename> files are read from the - files located in the system network directory - <filename>/usr/lib/systemd/network</filename>, the volatile - runtime network directory - <filename>/run/systemd/network</filename> and the local - administration network directory - <filename>/etc/systemd/network</filename>. All configuration files - are collectively sorted and processed in lexical order, regardless - of the directories in which they live. However, files with - identical filenames 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>/usr/lib</filename>. This can be used to - override a system-supplied configuration file with a local file if - needed. As a special case, an empty file (file size 0) or symlink - with the same name pointing to <filename>/dev/null</filename> - disables the configuration file entirely (it is "masked").</para> - </refsect1> - - <refsect1> - <title>Supported netdev kinds</title> - - <para>The following kinds of virtual network devices may be - configured in <filename>.netdev</filename> files:</para> - - <table> - <title>Supported kinds of virtual network devices</title> - - <tgroup cols='2'> - <colspec colname='kind' /> - <colspec colname='explanation' /> - <thead><row> - <entry>Kind</entry> - <entry>Description</entry> - </row></thead> - <tbody> - <row><entry><varname>bond</varname></entry> - <entry>A bond device is an aggregation of all its slave devices. See <ulink url="https://www.kernel.org/doc/Documentation/networking/bonding.txt">Linux Ethernet Bonding Driver HOWTO</ulink> for details.Local configuration</entry></row> - - <row><entry><varname>bridge</varname></entry> - <entry>A bridge device is a software switch, and each of its slave devices and the bridge itself are ports of the switch.</entry></row> - - <row><entry><varname>dummy</varname></entry> - <entry>A dummy device drops all packets sent to it.</entry></row> - - <row><entry><varname>gre</varname></entry> - <entry>A Level 3 GRE tunnel over IPv4. See <ulink url="https://tools.ietf.org/html/rfc2784">RFC 2784</ulink> for details.</entry></row> - - <row><entry><varname>gretap</varname></entry> - <entry>A Level 2 GRE tunnel over IPv4.</entry></row> - - <row><entry><varname>ip6gre</varname></entry> - <entry>A Level 3 GRE tunnel over IPv6.</entry></row> - - <row><entry><varname>ip6tnl</varname></entry> - <entry>An IPv4 or IPv6 tunnel over IPv6</entry></row> - - <row><entry><varname>ip6gretap</varname></entry> - <entry>An Level 2 GRE tunnel over IPv6.</entry></row> - - <row><entry><varname>ipip</varname></entry> - <entry>An IPv4 over IPv4 tunnel.</entry></row> - - <row><entry><varname>ipvlan</varname></entry> - <entry>An ipvlan device is a stacked device which receives packets from its underlying device based on IP address filtering.</entry></row> - - <row><entry><varname>macvlan</varname></entry> - <entry>A macvlan device is a stacked device which receives packets from its underlying device based on MAC address filtering.</entry></row> - - <row><entry><varname>macvtap</varname></entry> - <entry>A macvtap device is a stacked device which receives packets from its underlying device based on MAC address filtering.</entry></row> - - <row><entry><varname>sit</varname></entry> - <entry>An IPv6 over IPv4 tunnel.</entry></row> - - <row><entry><varname>tap</varname></entry> - <entry>A persistent Level 2 tunnel between a network device and a device node.</entry></row> - - <row><entry><varname>tun</varname></entry> - <entry>A persistent Level 3 tunnel between a network device and a device node.</entry></row> - - <row><entry><varname>veth</varname></entry> - <entry>An Ethernet tunnel between a pair of network devices.</entry></row> - - <row><entry><varname>vlan</varname></entry> - <entry>A VLAN is a stacked device which receives packets from its underlying device based on VLAN tagging. See <ulink url="http://www.ieee802.org/1/pages/802.1Q.html">IEEE 802.1Q</ulink> for details.</entry></row> - - <row><entry><varname>vti</varname></entry> - <entry>An IPv4 over IPSec tunnel.</entry></row> - - <row><entry><varname>vti6</varname></entry> - <entry>An IPv6 over IPSec tunnel.</entry></row> - - <row><entry><varname>vxlan</varname></entry> - <entry>A virtual extensible LAN (vxlan), for connecting Cloud computing deployments.</entry></row> - </tbody> - </tgroup> - </table> - - </refsect1> - - <refsect1> - <title>[Match] Section Options</title> - - <para>A virtual network device is only created if the - <literal>[Match]</literal> section matches the current - environment, or if the section is empty. The following keys are - accepted:</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>Host=</varname></term> - <listitem> - <para>Matches against the hostname or machine ID of the - host. See <literal>ConditionHost=</literal> in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Virtualization=</varname></term> - <listitem> - <para>Checks whether the system is executed in a virtualized - environment and optionally test whether it is a specific - implementation. See - <literal>ConditionVirtualization=</literal> in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>KernelCommandLine=</varname></term> - <listitem> - <para>Checks whether a specific kernel command line option - is set (or if prefixed with the exclamation mark unset). See - <literal>ConditionKernelCommandLine=</literal> in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Architecture=</varname></term> - <listitem> - <para>Checks whether the system is running on a specific - architecture. See <literal>ConditionArchitecture=</literal> in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. - </para> - </listitem> - </varlistentry> - </variablelist> - - </refsect1> - - <refsect1> - <title>[NetDev] Section Options</title> - - <para>The <literal>[NetDev]</literal> section accepts the - following keys:</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>Description=</varname></term> - <listitem> - <para>A free-form description of the netdev.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Name=</varname></term> - <listitem> - <para>The interface name used when creating the netdev. - This option is compulsory.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Kind=</varname></term> - <listitem> - <para>The netdev kind. This option is compulsory. See the - <literal>Supported netdev kinds</literal> section for the - valid keys.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>MTUBytes=</varname></term> - <listitem> - <para>The maximum transmission unit in bytes to set for - the device. The usual suffixes K, M, G, are supported and - are understood to the base of 1024. This key is not - currently supported for <literal>tun</literal> or - <literal>tap</literal> devices. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>MACAddress=</varname></term> - <listitem> - <para>The MAC address to use for the device. If none is - given, one is generated based on the interface name and - the - <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - This key is not currently supported for - <literal>tun</literal> or <literal>tap</literal> devices. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>[Bridge] Section Options</title> - - <para>The <literal>[Bridge]</literal> section only applies for - netdevs of kind <literal>bridge</literal>, and accepts the - following keys:</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>HelloTimeSec=</varname></term> - <listitem> - <para>HelloTimeSec specifies the number of seconds between two hello packets - sent out by the root bridge and the designated bridges. Hello packets are - used to communicate information about the topology throughout the entire - bridged local area network.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>MaxAgeSec=</varname></term> - <listitem> - <para>MaxAgeSec specifies the number of seconds of maximum message age. - If the last seen (received) hello packet is more than this number of - seconds old, the bridge in question will start the takeover procedure - in attempt to become the Root Bridge itself.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>ForwardDelaySec=</varname></term> - <listitem> - <para>ForwardDelaySec specifies the number of seconds spent in each - of the Listening and Learning states before the Forwarding state is entered.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>MulticastQuerier=</varname></term> - <listitem> - <para>A boolean. This setting controls the IFLA_BR_MCAST_QUERIER option in the kernel. - If enabled, the kernel will send general ICMP queries from a zero source address. - This feature should allow faster convergence on startup, but it causes some - multicast-aware switches to misbehave and disrupt forwarding of multicast packets. - When unset, the kernel's default setting applies. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>MulticastSnooping=</varname></term> - <listitem> - <para>A boolean. This setting controls the IFLA_BR_MCAST_SNOOPING option in the kernel. - If enabled, IGMP snooping monitors the Internet Group Management Protocol (IGMP) traffic - between hosts and multicast routers. When unset, the kernel's default setting applies. - </para> - </listitem> - </varlistentry> - </variablelist> - - </refsect1> - - <refsect1> - <title>[VLAN] Section Options</title> - - <para>The <literal>[VLAN]</literal> section only applies for - netdevs of kind <literal>vlan</literal>, and accepts the - following key:</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>Id=</varname></term> - <listitem> - <para>The VLAN ID to use. An integer in the range 0–4094. - This option is compulsory.</para> - </listitem> - </varlistentry> - </variablelist> - - </refsect1> - - <refsect1> - <title>[MACVLAN] Section Options</title> - - <para>The <literal>[MACVLAN]</literal> section only applies for - netdevs of kind <literal>macvlan</literal>, and accepts the - following key:</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>Mode=</varname></term> - <listitem> - <para>The MACVLAN mode to use. The supported options are - <literal>private</literal>, - <literal>vepa</literal>, - <literal>bridge</literal>, and - <literal>passthru</literal>. - </para> - </listitem> - </varlistentry> - </variablelist> - - </refsect1> - - <refsect1> - <title>[MACVTAP] Section Options</title> - - <para>The <literal>[MACVTAP]</literal> section applies for - netdevs of kind <literal>macvtap</literal> and accepts the - same key as <literal>[MACVLAN]</literal>.</para> - - </refsect1> - - <refsect1> - <title>[IPVLAN] Section Options</title> - - <para>The <literal>[IPVLAN]</literal> section only applies for - netdevs of kind <literal>ipvlan</literal>, and accepts the - following key:</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>Mode=</varname></term> - <listitem> - <para>The IPVLAN mode to use. The supported options are - <literal>L2</literal> and <literal>L3</literal>. - </para> - </listitem> - </varlistentry> - </variablelist> - - </refsect1> - - <refsect1> - <title>[VXLAN] Section Options</title> - <para>The <literal>[VXLAN]</literal> section only applies for - netdevs of kind <literal>vxlan</literal>, and accepts the - following keys:</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>Id=</varname></term> - <listitem> - <para>The VXLAN ID to use.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Group=</varname></term> - <listitem> - <para>An assigned multicast group IP address.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>TOS=</varname></term> - <listitem> - <para>The Type Of Service byte value for a vxlan interface.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>TTL=</varname></term> - <listitem> - <para>A fixed Time To Live N on Virtual eXtensible Local - Area Network packets. N is a number in the range 1–255. 0 - is a special value meaning that packets inherit the TTL - value.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>MacLearning=</varname></term> - <listitem> - <para>A boolean. When true, enables dynamic MAC learning - to discover remote MAC addresses.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>FDBAgeingSec=</varname></term> - <listitem> - <para>The lifetime of Forwarding Database entry learnt by - the kernel, in seconds.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>MaximumFDBEntries=</varname></term> - <listitem> - <para>Configures maximum number of FDB entries.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>ARPProxy=</varname></term> - <listitem> - <para>A boolean. When true, enables ARP proxying.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>L2MissNotification=</varname></term> - <listitem> - <para>A boolean. When true, enables netlink LLADDR miss - notifications.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>L3MissNotification=</varname></term> - <listitem> - <para>A boolean. When true, enables netlink IP address miss - notifications.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>RouteShortCircuit=</varname></term> - <listitem> - <para>A boolean. When true, route short circuiting is turned - on.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>UDPCheckSum=</varname></term> - <listitem> - <para>A boolean. When true, transmitting UDP checksums when doing VXLAN/IPv4 is turned on.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>UDP6ZeroChecksumTx=</varname></term> - <listitem> - <para>A boolean. When true, sending zero checksums in VXLAN/IPv6 is turned on.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>UDP6ZeroCheckSumRx=</varname></term> - <listitem> - <para>A boolean. When true, receiving zero checksums in VXLAN/IPv6 is turned on.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>GroupPolicyExtension=</varname></term> - <listitem> - <para>A boolean. When true, it enables Group Policy VXLAN extension security label mechanism - across network peers based on VXLAN. For details about the Group Policy VXLAN, see the - <ulink url="https://tools.ietf.org/html/draft-smith-vxlan-group-policy"> - VXLAN Group Policy </ulink> document. Defaults to false.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>DestinationPort=</varname></term> - <listitem> - <para>Configures the default destination UDP port on a per-device basis. - If destination port is not specified then Linux kernel default will be used. - Set destination port 4789 to get the IANA assigned value, - and destination port 0 to get default values.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>PortRange=</varname></term> - <listitem> - <para>Configures VXLAN port range. VXLAN bases source - UDP port based on flow to help the receiver to be able - to load balance based on outer header flow. It - restricts the port range to the normal UDP local - ports, and allows overriding via configuration.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - <refsect1> - <title>[Tunnel] Section Options</title> - - <para>The <literal>[Tunnel]</literal> section only applies for - netdevs of kind - <literal>ipip</literal>, - <literal>sit</literal>, - <literal>gre</literal>, - <literal>gretap</literal>, - <literal>ip6gre</literal>, - <literal>ip6gretap</literal>, - <literal>vti</literal>, - <literal>vti6</literal>, and - <literal>ip6tnl</literal> and accepts - the following keys:</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>Local=</varname></term> - <listitem> - <para>A static local address for tunneled packets. It must - be an address on another interface of this host.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Remote=</varname></term> - <listitem> - <para>The remote endpoint of the tunnel.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>TOS=</varname></term> - <listitem> - <para>The Type Of Service byte value for a tunnel interface. - For details about the TOS, see the - <ulink url="http://tools.ietf.org/html/rfc1349"> Type of - Service in the Internet Protocol Suite </ulink> document. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>TTL=</varname></term> - <listitem> - <para>A fixed Time To Live N on tunneled packets. N is a - number in the range 1–255. 0 is a special value meaning that - packets inherit the TTL value. The default value for IPv4 - tunnels is: inherit. The default value for IPv6 tunnels is - 64.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>DiscoverPathMTU=</varname></term> - <listitem> - <para>A boolean. When true, enables Path MTU Discovery on - the tunnel.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>IPv6FlowLabel=</varname></term> - <listitem> - <para>Configures the 20-bit flow label (see <ulink url="https://tools.ietf.org/html/rfc6437"> - RFC 6437</ulink>) field in the IPv6 header (see <ulink url="https://tools.ietf.org/html/rfc2460"> - RFC 2460</ulink>), which is used by a node to label packets of a flow. - It is only used for IPv6 tunnels. - A flow label of zero is used to indicate packets that have - not been labeled. - It can be configured to a value in the range 0–0xFFFFF, or be - set to <literal>inherit</literal>, in which case the original flowlabel is used.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>CopyDSCP=</varname></term> - <listitem> - <para>A boolean. When true, the Differentiated Service Code - Point (DSCP) field will be copied to the inner header from - outer header during the decapsulation of an IPv6 tunnel - packet. DSCP is a field in an IP packet that enables different - levels of service to be assigned to network traffic. - Defaults to <literal>no</literal>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>EncapsulationLimit=</varname></term> - <listitem> - <para>The Tunnel Encapsulation Limit option specifies how many additional - levels of encapsulation are permitted to be prepended to the packet. - For example, a Tunnel Encapsulation Limit option containing a limit - value of zero means that a packet carrying that option may not enter - another tunnel before exiting the current tunnel. - (see <ulink url="https://tools.ietf.org/html/rfc2473#section-4.1.1"> RFC 2473</ulink>). - The valid range is 0–255 and <literal>none</literal>. Defaults to 4. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Mode=</varname></term> - <listitem> - <para>An <literal>ip6tnl</literal> tunnel can be in one of three - modes - <literal>ip6ip6</literal> for IPv6 over IPv6, - <literal>ipip6</literal> for IPv4 over IPv6 or - <literal>any</literal> for either. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - <refsect1> - <title>[Peer] Section Options</title> - - <para>The <literal>[Peer]</literal> section only applies for - netdevs of kind <literal>veth</literal> and accepts the - following keys:</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>Name=</varname></term> - <listitem> - <para>The interface name used when creating the netdev. - This option is compulsory.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>MACAddress=</varname></term> - <listitem> - <para>The peer MACAddress, if not set, it is generated in - the same way as the MAC address of the main - interface.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - <refsect1> - <title>[Tun] Section Options</title> - - <para>The <literal>[Tun]</literal> section only applies for - netdevs of kind <literal>tun</literal>, and accepts the following - keys:</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>OneQueue=</varname></term> - <listitem><para>Takes a boolean argument. Configures whether - all packets are queued at the device (enabled), or a fixed - number of packets are queued at the device and the rest at the - <literal>qdisc</literal>. Defaults to - <literal>no</literal>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>MultiQueue=</varname></term> - <listitem><para>Takes a boolean argument. Configures whether - to use multiple file descriptors (queues) to parallelize - packets sending and receiving. Defaults to - <literal>no</literal>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>PacketInfo=</varname></term> - <listitem><para>Takes a boolean argument. Configures whether - packets should be prepended with four extra bytes (two flag - bytes and two protocol bytes). If disabled, it indicates that - the packets will be pure IP packets. Defaults to - <literal>no</literal>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>VNetHeader=</varname></term> - <listitem><para>Takes a boolean argument. Configures - IFF_VNET_HDR flag for a tap device. It allows sending - and receiving larger Generic Segmentation Offload (GSO) - packets. This may increase throughput significantly. - Defaults to - <literal>no</literal>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>User=</varname></term> - <listitem><para>User to grant access to the - <filename>/dev/net/tun</filename> device.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Group=</varname></term> - <listitem><para>Group to grant access to the - <filename>/dev/net/tun</filename> device.</para> - </listitem> - </varlistentry> - - </variablelist> - - </refsect1> - - <refsect1> - <title>[Tap] Section Options</title> - - <para>The <literal>[Tap]</literal> section only applies for - netdevs of kind <literal>tap</literal>, and accepts the same keys - as the <literal>[Tun]</literal> section.</para> - </refsect1> - - <refsect1> - <title>[Bond] Section Options</title> - - <para>The <literal>[Bond]</literal> section accepts the following - key:</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>Mode=</varname></term> - <listitem> - <para>Specifies one of the bonding policies. The default is - <literal>balance-rr</literal> (round robin). Possible values are - <literal>balance-rr</literal>, - <literal>active-backup</literal>, - <literal>balance-xor</literal>, - <literal>broadcast</literal>, - <literal>802.3ad</literal>, - <literal>balance-tlb</literal>, and - <literal>balance-alb</literal>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>TransmitHashPolicy=</varname></term> - <listitem> - <para>Selects the transmit hash policy to use for slave - selection in balance-xor, 802.3ad, and tlb modes. Possible - values are - <literal>layer2</literal>, - <literal>layer3+4</literal>, - <literal>layer2+3</literal>, - <literal>encap2+3</literal>, - <literal>802.3ad</literal>, and - <literal>encap3+4</literal>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>LACPTransmitRate=</varname></term> - <listitem> - <para>Specifies the rate with which link partner transmits - Link Aggregation Control Protocol Data Unit packets in - 802.3ad mode. Possible values are <literal>slow</literal>, - which requests partner to transmit LACPDUs every 30 seconds, - and <literal>fast</literal>, which requests partner to - transmit LACPDUs every second. The default value is - <literal>slow</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>MIIMonitorSec=</varname></term> - <listitem> - <para>Specifies the frequency that Media Independent - Interface link monitoring will occur. A value of zero - disables MII link monitoring. This value is rounded down to - the nearest millisecond. The default value is 0.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>UpDelaySec=</varname></term> - <listitem> - <para>Specifies the delay before a link is enabled after a - link up status has been detected. This value is rounded down - to a multiple of MIIMonitorSec. The default value is - 0.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>DownDelaySec=</varname></term> - <listitem> - <para>Specifies the delay before a link is disabled after a - link down status has been detected. This value is rounded - down to a multiple of MIIMonitorSec. The default value is - 0.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>LearnPacketIntervalSec=</varname></term> - <listitem> - <para>Specifies the number of seconds between instances where the bonding - driver sends learning packets to each slave peer switch. - The valid range is 1–0x7fffffff; the default value is 1. This option - has an effect only for the balance-tlb and balance-alb modes.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>AdSelect=</varname></term> - <listitem> - <para>Specifies the 802.3ad aggregation selection logic to use. Possible values are - <literal>stable</literal>, - <literal>bandwidth</literal> and - <literal>count</literal>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>FailOverMACPolicy=</varname></term> - <listitem> - <para>Specifies whether the active-backup mode should set all slaves to - the same MAC address at the time of enslavement or, when enabled, to perform special handling of the - bond's MAC address in accordance with the selected policy. The default policy is none. - Possible values are - <literal>none</literal>, - <literal>active</literal> and - <literal>follow</literal>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>ARPValidate=</varname></term> - <listitem> - <para>Specifies whether or not ARP probes and replies should be - validated in any mode that supports ARP monitoring, or whether - non-ARP traffic should be filtered (disregarded) for link - monitoring purposes. Possible values are - <literal>none</literal>, - <literal>active</literal>, - <literal>backup</literal> and - <literal>all</literal>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>ARPIntervalSec=</varname></term> - <listitem> - <para>Specifies the ARP link monitoring frequency in milliseconds. - A value of 0 disables ARP monitoring. The default value is 0. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>ARPIPTargets=</varname></term> - <listitem> - <para>Specifies the IP addresses to use as ARP monitoring peers when - ARPIntervalSec is greater than 0. These are the targets of the ARP request - sent to determine the health of the link to the targets. - Specify these values in IPv4 dotted decimal format. At least one IP - address must be given for ARP monitoring to function. The - maximum number of targets that can be specified is 16. The - default value is no IP addresses. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>ARPAllTargets=</varname></term> - <listitem> - <para>Specifies the quantity of ARPIPTargets that must be reachable - in order for the ARP monitor to consider a slave as being up. - This option affects only active-backup mode for slaves with - ARPValidate enabled. Possible values are - <literal>any</literal> and - <literal>all</literal>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>PrimaryReselectPolicy=</varname></term> - <listitem> - <para>Specifies the reselection policy for the primary slave. This - affects how the primary slave is chosen to become the active slave - when failure of the active slave or recovery of the primary slave - occurs. This option is designed to prevent flip-flopping between - the primary slave and other slaves. Possible values are - <literal>always</literal>, - <literal>better</literal> and - <literal>failure</literal>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>ResendIGMP=</varname></term> - <listitem> - <para>Specifies the number of IGMP membership reports to be issued after - a failover event. One membership report is issued immediately after - the failover, subsequent packets are sent in each 200ms interval. - The valid range is 0–255. Defaults to 1. A value of 0 - prevents the IGMP membership report from being issued in response - to the failover event. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>PacketsPerSlave=</varname></term> - <listitem> - <para>Specify the number of packets to transmit through a slave before - moving to the next one. When set to 0, then a slave is chosen at - random. The valid range is 0–65535. Defaults to 1. This option - only has effect when in balance-rr mode. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>GratuitousARP=</varname></term> - <listitem> - <para>Specify the number of peer notifications (gratuitous ARPs and - unsolicited IPv6 Neighbor Advertisements) to be issued after a - failover event. As soon as the link is up on the new slave, - a peer notification is sent on the bonding device and each - VLAN sub-device. This is repeated at each link monitor interval - (ARPIntervalSec or MIIMonitorSec, whichever is active) if the number is - greater than 1. The valid range is 0–255. The default value is 1. - These options affect only the active-backup mode. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>AllSlavesActive=</varname></term> - <listitem> - <para>A boolean. Specifies that duplicate frames (received on inactive ports) - should be dropped when false, or delivered when true. Normally, bonding will drop - duplicate frames (received on inactive ports), which is desirable for - most users. But there are some times it is nice to allow duplicate - frames to be delivered. The default value is false (drop duplicate frames - received on inactive ports). - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>MinLinks=</varname></term> - <listitem> - <para>Specifies the minimum number of links that must be active before - asserting carrier. The default value is 0. - </para> - </listitem> - </varlistentry> - - </variablelist> - - <para>For more detail information see - <ulink url="https://www.kernel.org/doc/Documentation/networking/bonding.txt"> - Linux Ethernet Bonding Driver HOWTO</ulink></para> - - </refsect1> - - <refsect1> - <title>Example</title> - <example> - <title>/etc/systemd/network/25-bridge.netdev</title> - - <programlisting>[NetDev] -Name=bridge0 -Kind=bridge</programlisting> - </example> - - <example> - <title>/etc/systemd/network/25-vlan1.netdev</title> - - <programlisting>[Match] -Virtualization=no - -[NetDev] -Name=vlan1 -Kind=vlan - -[VLAN] -Id=1</programlisting> - </example> - <example> - <title>/etc/systemd/network/25-ipip.netdev</title> - <programlisting>[NetDev] -Name=ipip-tun -Kind=ipip -MTUBytes=1480 - -[Tunnel] -Local=192.168.223.238 -Remote=192.169.224.239 -TTL=64</programlisting> - </example> - <example> - <title>/etc/systemd/network/25-tap.netdev</title> - <programlisting>[NetDev] -Name=tap-test -Kind=tap - -[Tap] -MultiQueue=true -PacketInfo=true</programlisting> </example> - - <example> - <title>/etc/systemd/network/25-sit.netdev</title> - <programlisting>[NetDev] -Name=sit-tun -Kind=sit -MTUBytes=1480 - -[Tunnel] -Local=10.65.223.238 -Remote=10.65.223.239</programlisting> - </example> - - <example> - <title>/etc/systemd/network/25-gre.netdev</title> - <programlisting>[NetDev] -Name=gre-tun -Kind=gre -MTUBytes=1480 - -[Tunnel] -Local=10.65.223.238 -Remote=10.65.223.239</programlisting> - </example> - - <example> - <title>/etc/systemd/network/25-vti.netdev</title> - - <programlisting>[NetDev] -Name=vti-tun -Kind=vti -MTUBytes=1480 - -[Tunnel] -Local=10.65.223.238 -Remote=10.65.223.239</programlisting> - </example> - - <example> - <title>/etc/systemd/network/25-veth.netdev</title> - <programlisting>[NetDev] -Name=veth-test -Kind=veth - -[Peer] -Name=veth-peer</programlisting> - </example> - - <example> - <title>/etc/systemd/network/25-bond.netdev</title> - <programlisting>[NetDev] -Name=bond1 -Kind=bond - -[Bond] -Mode=802.3ad -TransmitHashPolicy=layer3+4 -MIIMonitorSec=1s -LACPTransmitRate=fast -</programlisting> - </example> - - <example> - <title>/etc/systemd/network/25-dummy.netdev</title> - <programlisting>[NetDev] -Name=dummy-test -Kind=dummy -MACAddress=12:34:56:78:9a:bc</programlisting> - </example> - - </refsect1> - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd.network.xml b/man/systemd.network.xml deleted file mode 100644 index 821e22aff8..0000000000 --- a/man/systemd.network.xml +++ /dev/null @@ -1,1205 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2013 Tom Gundersen - - 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.network" conditional='ENABLE_NETWORKD'> - - <refentryinfo> - <title>systemd.network</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Tom</firstname> - <surname>Gundersen</surname> - <email>teg@jklm.no</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd.network</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd.network</refname> - <refpurpose>Network configuration</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename><replaceable>network</replaceable>.network</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>Network setup is performed by - <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>. - </para> - - <para>Network files must have the extension - <filename>.network</filename>; other extensions are ignored. - Networks are applied to links whenever the links appear.</para> - - <para>The <filename>.network</filename> files are read from the - files located in the system network directory - <filename>/usr/lib/systemd/network</filename>, the volatile - runtime network directory - <filename>/run/systemd/network</filename> and the local - administration network directory - <filename>/etc/systemd/network</filename>. All configuration files - are collectively sorted and processed in lexical order, regardless - of the directories in which they live. However, files with - identical filenames 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>/usr/lib</filename>. This can be used to - override a system-supplied configuration file with a local file if - needed. As a special case, an empty file (file size 0) or symlink - with the same name pointing to <filename>/dev/null</filename> - disables the configuration file entirely (it is "masked").</para> - - <para>Note that an interface without any static IPv6 addresses configured, and neither DHCPv6 nor IPv6LL enabled, - shall be considered to have no IPv6 support. IPv6 will be automatically disabled for that interface by writing "1" - to <filename>/proc/sys/net/ipv6/conf/<replaceable>ifname</replaceable>/disable_ipv6</filename>. - </para> - </refsect1> - - <refsect1> - <title>[Match] Section Options</title> - - <para>The network file contains a <literal>[Match]</literal> - section, which determines if a given network file may be applied - to a given device; and a <literal>[Network]</literal> section - specifying how the device should be configured. The first (in - lexical order) of the network files that matches a given device - is applied, all later files are ignored, even if they match as - well.</para> - - <para>A network file is said to match a device if each of the - entries in the <literal>[Match]</literal> section matches, or if - the section is empty. The following keys are accepted:</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>MACAddress=</varname></term> - <listitem> - <para>The hardware address of the interface (use full colon-delimited hexadecimal, e.g., - 01:23:45:67:89:ab).</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Path=</varname></term> - <listitem> - <para>A whitespace-separated list of shell-style globs - matching the persistent path, as exposed by the udev - property <literal>ID_PATH</literal>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Driver=</varname></term> - <listitem> - <para>A whitespace-separated list of shell-style globs - matching the driver currently bound to the device, as - exposed by the udev property <literal>DRIVER</literal> - of its parent device, or if that is not set the driver - as exposed by <literal>ethtool -i</literal> of the - device itself.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Type=</varname></term> - <listitem> - <para>A whitespace-separated list of shell-style globs - matching the device type, as exposed by the udev property - <literal>DEVTYPE</literal>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Name=</varname></term> - <listitem> - <para>A whitespace-separated list of shell-style globs - matching the device name, as exposed by the udev property - <literal>INTERFACE</literal>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Host=</varname></term> - <listitem> - <para>Matches against the hostname or machine ID of the - host. See <literal>ConditionHost=</literal> in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Virtualization=</varname></term> - <listitem> - <para>Checks whether the system is executed in a virtualized - environment and optionally test whether it is a specific - implementation. See <literal>ConditionVirtualization=</literal> in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>KernelCommandLine=</varname></term> - <listitem> - <para>Checks whether a specific kernel command line option is - set (or if prefixed with the exclamation mark unset). See - <literal>ConditionKernelCommandLine=</literal> in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Architecture=</varname></term> - <listitem> - <para>Checks whether the system is running on a specific - architecture. See <literal>ConditionArchitecture=</literal> in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. - </para> - </listitem> - </varlistentry> - </variablelist> - - </refsect1> - - <refsect1> - <title>[Link] Section Options</title> - - <para> The <literal>[Link]</literal> section accepts the following keys:</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>MACAddress=</varname></term> - <listitem> - <para>The hardware address to set for the device.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>MTUBytes=</varname></term> - <listitem> - <para>The maximum transmission unit in bytes to set for the - device. The usual suffixes K, M, G, are supported and are - understood to the base of 1024.</para> - <para>Note that if IPv6 is enabled on the interface, and the MTU is chosen - below 1280 (the minimum MTU for IPv6) it will automatically be increased to this value.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>[Network] Section Options</title> - - <para>The <literal>[Network]</literal> section accepts the following keys:</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>Description=</varname></term> - <listitem> - <para>A description of the device. This is only used for - presentation purposes.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>DHCP=</varname></term> - <listitem> - <para>Enables DHCPv4 and/or DHCPv6 client support. Accepts - <literal>yes</literal>, <literal>no</literal>, - <literal>ipv4</literal>, or <literal>ipv6</literal>.</para> - - <para>Note that DHCPv6 will by default be triggered by Router - Advertisement, if that is enabled, regardless of this parameter. - By enabling DHCPv6 support explicitly, the DHCPv6 client will - be started regardless of the presence of routers on the link, - or what flags the routers pass. See - <literal>IPv6AcceptRouterAdvertisements=</literal>.</para> - - <para>Furthermore, note that by default the domain name - specified through DHCP is not used for name resolution. - See option <option>UseDomains=</option> below.</para> - - <para>See the <literal>[DHCP]</literal> section below for further configuration options for the DHCP client - support.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>DHCPServer=</varname></term> - <listitem> - <para>A boolean. Enables DHCPv4 server support. Defaults - to <literal>no</literal>. Further settings for the DHCP - server may be set in the <literal>[DHCPServer]</literal> - section described below.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>LinkLocalAddressing=</varname></term> - <listitem> - <para>Enables link-local address autoconfiguration. Accepts - <literal>yes</literal>, <literal>no</literal>, - <literal>ipv4</literal>, or <literal>ipv6</literal>. Defaults to - <literal>ipv6</literal>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>IPv4LLRoute=</varname></term> - <listitem> - <para>A boolean. When true, sets up the route needed for - non-IPv4LL hosts to communicate with IPv4LL-only hosts. Defaults - to false. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>IPv6Token=</varname></term> - <listitem> - <para>An IPv6 address with the top 64 bits unset. When set, indicates the - 64-bit interface part of SLAAC IPv6 addresses for this link. Note that - the token is only ever used for SLAAC, and not for DHCPv6 addresses, even - in the case DHCP is requested by router advertisement. By default, the - token is autogenerated.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>LLMNR=</varname></term> - <listitem> - <para>A boolean or <literal>resolve</literal>. When true, - enables <ulink - url="https://tools.ietf.org/html/rfc4795">Link-Local - Multicast Name Resolution</ulink> on the link. When set to - <literal>resolve</literal>, only resolution is enabled, - but not host registration and announcement. Defaults to - true. This setting is read by - <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>MulticastDNS=</varname></term> - <listitem> - <para>A boolean or <literal>resolve</literal>. When true, - enables <ulink - url="https://tools.ietf.org/html/rfc6762">Multicast - DNS</ulink> support on the link. When set to - <literal>resolve</literal>, only resolution is enabled, - but not host or service registration and - announcement. Defaults to false. This setting is read by - <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>DNSSEC=</varname></term> - <listitem> - <para>A boolean or - <literal>allow-downgrade</literal>. When true, enables - <ulink - url="https://tools.ietf.org/html/rfc4033">DNSSEC</ulink> - DNS validation support on the link. When set to - <literal>allow-downgrade</literal>, compatibility with - non-DNSSEC capable networks is increased, by automatically - turning off DNSEC in this case. This option defines a - per-interface setting for - <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>'s - global <varname>DNSSEC=</varname> option. Defaults to - false. This setting is read by - <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>DNSSECNegativeTrustAnchors=</varname></term> - <listitem><para>A space-separated list of DNSSEC negative - trust anchor domains. If specified and DNSSEC is enabled, - look-ups done via the interface's DNS server will be subject - to the list of negative trust anchors, and not require - authentication for the specified domains, or anything below - it. Use this to disable DNSSEC authentication for specific - private domains, that cannot be proven valid using the - Internet DNS hierarchy. Defaults to the empty list. This - setting is read by - <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>LLDP=</varname></term> - <listitem> - <para>Controls support for Ethernet LLDP packet reception. LLDP is a link-layer protocol commonly - implemented on professional routers and bridges which announces which physical port a system is connected - to, as well as other related data. Accepts a boolean or the special value - <literal>routers-only</literal>. When true, incoming LLDP packets are accepted and a database of all LLDP - neighbors maintained. If <literal>routers-only</literal> is set only LLDP data of various types of routers - is collected and LLDP data about other types of devices ignored (such as stations, telephones and - others). If false, LLDP reception is disabled. Defaults to <literal>routers-only</literal>. Use - <citerefentry><refentrytitle>networkctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> to query the - collected neighbor data. LLDP is only available on Ethernet links. See <varname>EmitLLDP=</varname> below - for enabling LLDP packet emission from the local system. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>EmitLLDP=</varname></term> - <listitem> - <para>Controls support for Ethernet LLDP packet emission. Accepts a boolean parameter or the special values - <literal>nearest-bridge</literal>, <literal>non-tpmr-bridge</literal> and - <literal>customer-bridge</literal>. Defaults to false, which turns off LLDP packet emission. If not false, - a short LLDP packet with information about the local system is sent out in regular intervals on the - link. The LLDP packet will contain information about the local host name, the local machine ID (as stored - in <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>) and the - local interface name, as well as the pretty hostname of the system (as set in - <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>). LLDP - emission is only available on Ethernet links. Note that this setting passes data suitable for - identification of host to the network and should thus not be enabled on untrusted networks, where such - identification data should not be made available. Use this option to permit other systems to identify on - which interfaces they are connected to this system. The three special values control propagation of the - LLDP packets. The <literal>nearest-bridge</literal> setting permits propagation only to the nearest - connected bridge, <literal>non-tpmr-bridge</literal> permits propagation across Two-Port MAC Relays, but - not any other bridges, and <literal>customer-bridge</literal> permits propagation until a customer bridge - is reached. For details about these concepts, see <ulink - url="http://standards.ieee.org/getieee802/download/802.1AB-2009.pdf">IEEE 802.1AB-2009</ulink>. Note that - configuring this setting to true is equivalent to <literal>nearest-bridge</literal>, the recommended and - most restricted level of propagation. See <varname>LLDP=</varname> above for an option to enable LLDP - reception.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>BindCarrier=</varname></term> - <listitem> - <para>A link name or a list of link names. When set, controls the behavior of the current - link. When all links in the list are in an operational down state, the current link is brought - down. When at least one link has carrier, the current interface is brought up. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Address=</varname></term> - <listitem> - <para>A static IPv4 or IPv6 address and its prefix length, - separated by a <literal>/</literal> character. Specify - this key more than once to configure several addresses. - The format of the address must be as described in - <citerefentry project='man-pages'><refentrytitle>inet_pton</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - This is a short-hand for an [Address] section only - containing an Address key (see below). This option may be - specified more than once. - </para> - - <para>If the specified address is 0.0.0.0 (for IPv4) or - [::] (for IPv6), a new address range of the requested size - is automatically allocated from a system-wide pool of - unused ranges. The allocated range is checked against all - current network interfaces and all known network - configuration files to avoid address range conflicts. The - default system-wide pool consists of 192.168.0.0/16, - 172.16.0.0/12 and 10.0.0.0/8 for IPv4, and fc00::/7 for - IPv6. This functionality is useful to manage a large - number of dynamically created network interfaces with the - same network configuration and automatic address range - assignment.</para> - - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Gateway=</varname></term> - <listitem> - <para>The gateway address, which must be in the format - described in - <citerefentry project='man-pages'><refentrytitle>inet_pton</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - This is a short-hand for a [Route] section only containing - a Gateway key. This option may be specified more than - once.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>DNS=</varname></term> - <listitem> - <para>A DNS server address, which must be in the format - described in - <citerefentry project='man-pages'><refentrytitle>inet_pton</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - This option may be specified more than once. This setting is read by - <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Domains=</varname></term> - <listitem> - <para>The domains used for DNS host name resolution on this link. Takes a list of DNS domain names which - are used as search suffixes for extending single-label host names (host names containing no dots) to become - fully qualified domain names (FQDNs). If a single-label host name is resolved on this interface, each of - the specified search domains are appended to it in turn, converting it into a fully qualified domain name, - until one of them may be successfully resolved.</para> - - <para>The specified domains are also used for routing of DNS queries: look-ups for host names ending in the - domains specified here are preferably routed to the DNS servers configured for this interface. If a domain - name is prefixed with <literal>~</literal>, the domain name becomes a pure "routing" domain, is used for - DNS query routing purposes only and is not used in the described domain search logic. By specifying a - routing domain of <literal>~.</literal> (the tilde indicating definition of a routing domain, the dot - referring to the DNS root domain which is the implied suffix of all valid DNS names) it is possible to - route all DNS traffic preferably to the DNS server specified for this interface. The route domain logic is - particularly useful on multi-homed hosts with DNS servers serving particular private DNS zones on each - interface.</para> - - <para>This setting is read by - <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>NTP=</varname></term> - <listitem> - <para>An NTP server address. This option may be specified more than once. This setting is read by - <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>IPForward=</varname></term> - <listitem><para>Configures IP packet forwarding for the - system. If enabled, incoming packets on any network - interface will be forwarded to any other interfaces - according to the routing table. Takes either a boolean - argument, or the values <literal>ipv4</literal> or - <literal>ipv6</literal>, which only enable IP packet - forwarding for the specified address family. This controls - the <filename>net.ipv4.ip_forward</filename> and - <filename>net.ipv6.conf.all.forwarding</filename> sysctl - options of the network interface (see <ulink - url="https://www.kernel.org/doc/Documentation/networking/ip-sysctl.txt">ip-sysctl.txt</ulink> - for details about sysctl options). Defaults to - <literal>no</literal>.</para> - - <para>Note: this setting controls a global kernel option, - and does so one way only: if a network that has this setting - enabled is set up the global setting is turned on. However, - it is never turned off again, even after all networks with - this setting enabled are shut down again.</para> - - <para>To allow IP packet forwarding only between specific - network interfaces use a firewall.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>IPMasquerade=</varname></term> - <listitem><para>Configures IP masquerading for the network - interface. If enabled, packets forwarded from the network - interface will be appear as coming from the local host. - Takes a boolean argument. Implies - <varname>IPForward=ipv4</varname>. Defaults to - <literal>no</literal>.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>IPv6PrivacyExtensions=</varname></term> - <listitem><para>Configures use of stateless temporary - addresses that change over time (see <ulink - url="https://tools.ietf.org/html/rfc4941">RFC 4941</ulink>, - Privacy Extensions for Stateless Address Autoconfiguration - in IPv6). Takes a boolean or the special values - <literal>prefer-public</literal> and - <literal>kernel</literal>. When true, enables the privacy - extensions and prefers temporary addresses over public - addresses. When <literal>prefer-public</literal>, enables the - privacy extensions, but prefers public addresses over - temporary addresses. When false, the privacy extensions - remain disabled. When <literal>kernel</literal>, the kernel's - default setting will be left in place. Defaults to - <literal>no</literal>.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>IPv6AcceptRouterAdvertisements=</varname></term> - <listitem><para>Force the setting of the <filename>accept_ra</filename> - (router advertisements) setting for the interface. - When unset, the kernel default is used, and router - advertisements are accepted only when local forwarding - is disabled for that interface. - When router advertisements are accepted, they will - trigger the start of the DHCPv6 client if the relevant - flags are passed, or if no routers are found on the link. - Takes a boolean. If true, router advertisements are - accepted, when false, router advertisements are ignored, - independently of the local forwarding state.</para> - - <para>See - <ulink url="https://www.kernel.org/doc/Documentation/networking/ip-sysctl.txt">ip-sysctl.txt</ulink> - in the kernel documentation, but note that systemd's - setting of <constant>1</constant> corresponds to - kernel's setting of <constant>2</constant>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>IPv6DuplicateAddressDetection=</varname></term> - <listitem><para>Configures the amount of IPv6 Duplicate - Address Detection (DAD) probes to send. Defaults to unset. - </para></listitem> - </varlistentry> - <varlistentry> - <term><varname>IPv6HopLimit=</varname></term> - <listitem><para>Configures IPv6 Hop Limit. For each router that - forwards the packet, the hop limit is decremented by 1. When the - hop limit field reaches zero, the packet is discarded. - Defaults to unset. - </para></listitem> - </varlistentry> - <varlistentry> - <term><varname>ProxyARP=</varname></term> - <listitem><para>A boolean. Configures proxy ARP. Proxy ARP is the technique in which one host, - usually a router, answers ARP requests intended for another machine. By "faking" its identity, - the router accepts responsibility for routing packets to the "real" destination. (see <ulink - url="https://tools.ietf.org/html/rfc1027">RFC 1027</ulink>. - Defaults to unset. - </para></listitem> - </varlistentry> - <varlistentry> - <term><varname>Bridge=</varname></term> - <listitem> - <para>The name of the bridge to add the link to.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Bond=</varname></term> - <listitem> - <para>The name of the bond to add the link to.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>VLAN=</varname></term> - <listitem> - <para>The name of a VLAN to create on the link. This - option may be specified more than once.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>MACVLAN=</varname></term> - <listitem> - <para>The name of a MACVLAN to create on the link. This - option may be specified more than once.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>VXLAN=</varname></term> - <listitem> - <para>The name of a VXLAN to create on the link. This - option may be specified more than once.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Tunnel=</varname></term> - <listitem> - <para>The name of a Tunnel to create on the link. This - option may be specified more than once.</para> - </listitem> - </varlistentry> - </variablelist> - - </refsect1> - - <refsect1> - <title>[Address] Section Options</title> - - <para>An <literal>[Address]</literal> section accepts the - following keys. Specify several <literal>[Address]</literal> - sections to configure several addresses.</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>Address=</varname></term> - <listitem> - <para>As in the <literal>[Network]</literal> section. This - key is mandatory.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Peer=</varname></term> - <listitem> - <para>The peer address in a point-to-point connection. - Accepts the same format as the <literal>Address</literal> - key.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Broadcast=</varname></term> - <listitem> - <para>The broadcast address, which must be in the format - described in - <citerefentry project='man-pages'><refentrytitle>inet_pton</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - This key only applies to IPv4 addresses. If it is not - given, it is derived from the <literal>Address</literal> - key.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Label=</varname></term> - <listitem> - <para>An address label.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>PreferredLifetime=</varname></term> - <listitem> - <para>Allows the default "preferred lifetime" of the address to be overridden. - Only three settings are accepted: <literal>forever</literal> or <literal>infinity</literal> - which is the default and means that the address never expires, and <literal>0</literal> which means - that the address is considered immediately "expired" and will not be used, - unless explicitly requested. A setting of PreferredLifetime=0 is useful for - addresses which are added to be used only by a specific application, - which is then configured to use them explicitly.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>[Route] Section Options</title> - <para>The <literal>[Route]</literal> section accepts the - following keys. Specify several <literal>[Route]</literal> - sections to configure several routes.</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>Gateway=</varname></term> - <listitem> - <para>As in the <literal>[Network]</literal> section.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Destination=</varname></term> - <listitem> - <para>The destination prefix of the route. Possibly - followed by a slash and the prefix length. If omitted, a - full-length host route is assumed.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Source=</varname></term> - <listitem> - <para>The source prefix of the route. Possibly followed by - a slash and the prefix length. If omitted, a full-length - host route is assumed.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Metric=</varname></term> - <listitem> - <para>The metric of the route (an unsigned integer).</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Scope=</varname></term> - <listitem> - <para>The scope of the route, which can be <literal>global</literal>, - <literal>link</literal> or <literal>host</literal>. Defaults to - <literal>global</literal>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>PreferredSource=</varname></term> - <listitem> - <para>The preferred source address of the route. The address - must be in the format described in - <citerefentry project='man-pages'><refentrytitle>inet_pton</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Table=<replaceable>num</replaceable></varname></term> - <listitem> - <para>The table identifier for the route (a number between 1 and 4294967295, or 0 to unset). - The table can be retrieved using <command>ip route show table <replaceable>num</replaceable></command>. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>[DHCP] Section Options</title> - <para>The <literal>[DHCP]</literal> section configures the - DHCPv4 and DHCP6 client, if it is enabled with the - <varname>DHCP=</varname> setting described above:</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>UseDNS=</varname></term> - <listitem> - <para>When true (the default), the DNS servers received - from the DHCP server will be used and take precedence over - any statically configured ones.</para> - - <para>This corresponds to the <option>nameserver</option> - option in <citerefentry - project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>UseNTP=</varname></term> - <listitem> - <para>When true (the default), the NTP servers received - from the DHCP server will be used by systemd-timesyncd - and take precedence over any statically configured ones.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>UseMTU=</varname></term> - <listitem> - <para>When true, the interface maximum transmission unit - from the DHCP server will be used on the current link. - Defaults to false.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>SendHostname=</varname></term> - <listitem> - <para>When true (the default), the machine's hostname will - be sent to the DHCP server.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>UseHostname=</varname></term> - <listitem> - <para>When true (the default), the hostname received from - the DHCP server will be set as the transient hostname of the system - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Hostname=</varname></term> - <listitem> - <para>Use this value for the hostname which is sent to the - DHCP server, instead of machine's hostname.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>UseDomains=</varname></term> - <listitem> - <para>Takes a boolean argument, or the special value <literal>route</literal>. When true, the domain name - received from the DHCP server will be used as DNS search domain over this link, similar to the effect of - the <option>Domains=</option> setting. If set to <literal>route</literal>, the domain name received from - the DHCP server will be used for routing DNS queries only, but not for searching, similar to the effect of - the <option>Domains=</option> setting when the argument is prefixed with <literal>~</literal>. Defaults to - false.</para> - - <para>It is recommended to enable this option only on trusted networks, as setting this affects resolution - of all host names, in particular to single-label names. It is generally safer to use the supplied domain - only as routing domain, rather than as search domain, in order to not have it affect local resolution of - single-label names.</para> - - <para>When set to true, this setting corresponds to the <option>domain</option> option in <citerefentry - project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>UseRoutes=</varname></term> - <listitem> - <para>When true (the default), the static routes will be - requested from the DHCP server and added to the routing - table with a metric of 1024.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>UseTimezone=</varname></term> - - <listitem><para>When true, the timezone received from the - DHCP server will be set as timezone of the local - system. Defaults to <literal>no</literal>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>CriticalConnection=</varname></term> - <listitem> - <para>When true, the connection will never be torn down - even if the DHCP lease expires. This is contrary to the - DHCP specification, but may be the best choice if, say, - the root filesystem relies on this connection. Defaults to - false.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>ClientIdentifier=</varname></term> - <listitem> - <para>The DHCPv4 client identifier to use. Either <literal>mac</literal> to use the MAC address of the link - or <literal>duid</literal> (the default, see below) to use a RFC4361-compliant Client ID.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>VendorClassIdentifier=</varname></term> - <listitem> - <para>The vendor class identifier used to identify vendor - type and configuration.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>DUIDType=</varname></term> - <listitem> - <para>Override the global <varname>DUIDType</varname> setting for this network. See - <citerefentry><refentrytitle>networkd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for a description of possible values.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>DUIDRawData=</varname></term> - <listitem> - <para>Override the global <varname>DUIDRawData</varname> setting for this network. See - <citerefentry><refentrytitle>networkd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for a description of possible values.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>IAID=</varname></term> - <listitem> - <para>The DHCP Identity Association Identifier (IAID) for the interface, a 32-bit unsigned integer.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>RequestBroadcast=</varname></term> - <listitem> - <para>Request the server to use broadcast messages before - the IP address has been configured. This is necessary for - devices that cannot receive RAW packets, or that cannot - receive packets at all before an IP address has been - configured. On the other hand, this must not be enabled on - networks where broadcasts are filtered out.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>RouteMetric=</varname></term> - <listitem> - <para>Set the routing metric for routes specified by the - DHCP server.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>[DHCPServer] Section Options</title> - <para>The <literal>[DHCPServer]</literal> section contains - settings for the DHCP server, if enabled via the - <varname>DHCPServer=</varname> option described above:</para> - - <variablelist class='network-directives'> - - <varlistentry> - <term><varname>PoolOffset=</varname></term> - <term><varname>PoolSize=</varname></term> - - <listitem><para>Configures the pool of addresses to hand out. The pool - is a contiguous sequence of IP addresses in the subnet configured for - the server address, which does not include the subnet nor the broadcast - address. <varname>PoolOffset=</varname> takes the offset of the pool - from the start of subnet, or zero to use the default value. - <varname>PoolSize=</varname> takes the number of IP addresses in the - pool or zero to use the default value. By default, the pool starts at - the first address after the subnet address and takes up the rest of - the subnet, excluding the broadcast address. If the pool includes - the server address (the default), this is reserved and not handed - out to clients.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>DefaultLeaseTimeSec=</varname></term> - <term><varname>MaxLeaseTimeSec=</varname></term> - - <listitem><para>Control the default and maximum DHCP lease - time to pass to clients. These settings take time values in seconds or - another common time unit, depending on the suffix. The default - lease time is used for clients that did not ask for a specific - lease time. If a client asks for a lease time longer than the - maximum lease time, it is automatically shortened to the - specified time. The default lease time defaults to 1h, the - maximum lease time to 12h. Shorter lease times are beneficial - if the configuration data in DHCP leases changes frequently - and clients shall learn the new settings with shorter - latencies. Longer lease times reduce the generated DHCP - network traffic.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>EmitDNS=</varname></term> - <term><varname>DNS=</varname></term> - - <listitem><para>Configures whether the DHCP leases handed out - to clients shall contain DNS server information. The - <varname>EmitDNS=</varname> setting takes a boolean argument - and defaults to <literal>yes</literal>. The DNS servers to - pass to clients may be configured with the - <varname>DNS=</varname> option, which takes a list of IPv4 - addresses. If the <varname>EmitDNS=</varname> option is - enabled but no servers configured, the servers are - automatically propagated from an "uplink" interface that has - appropriate servers set. The "uplink" interface is determined - by the default route of the system with the highest - priority. Note that this information is acquired at the time - the lease is handed out, and does not take uplink interfaces - into account that acquire DNS or NTP server information at a - later point. DNS server propagation does not take - <filename>/etc/resolv.conf</filename> into account. Also, note - that the leases are not refreshed if the uplink network - configuration changes. To ensure clients regularly acquire the - most current uplink DNS server information, it is thus - advisable to shorten the DHCP lease time via - <varname>MaxLeaseTimeSec=</varname> described - above.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>EmitNTP=</varname></term> - <term><varname>NTP=</varname></term> - - <listitem><para>Similar to the <varname>EmitDNS=</varname> and - <varname>DNS=</varname> settings described above, these - settings configure whether and what NTP server information - shall be emitted as part of the DHCP lease. The same syntax, - propagation semantics and defaults apply as for - <varname>EmitDNS=</varname> and - <varname>DNS=</varname>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>EmitRouter=</varname></term> - - <listitem><para>Similar to the <varname>EmitDNS=</varname> - setting described above, this setting configures whether the - DHCP lease should contain the router option. The same syntax, - propagation semantics and defaults apply as for - <varname>EmitDNS=</varname>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>EmitTimezone=</varname></term> - <term><varname>Timezone=</varname></term> - - <listitem><para>Configures whether the DHCP leases handed out - to clients shall contain timezone information. The - <varname>EmitTimezone=</varname> setting takes a boolean - argument and defaults to <literal>yes</literal>. The - <varname>Timezone=</varname> setting takes a timezone string - (such as <literal>Europe/Berlin</literal> or - <literal>UTC</literal>) to pass to clients. If no explicit - timezone is set, the system timezone of the local host is - propagated, as determined by the - <filename>/etc/localtime</filename> symlink.</para></listitem> - </varlistentry> - - </variablelist> - </refsect1> - - <refsect1> - <title>[Bridge] Section Options</title> - <para>The <literal>[Bridge]</literal> section accepts the - following keys.</para> - <variablelist class='network-directives'> - <varlistentry> - <term><varname>UnicastFlood=</varname></term> - <listitem> - <para>A boolean. Controls whether the bridge should flood - traffic for which an FDB entry is missing and the destination - is unknown through this port. Defaults to on. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>HairPin=</varname></term> - <listitem> - <para>A boolean. Configures whether traffic may be sent back - out of the port on which it was received. By default, this - flag is false, and the bridge will not forward traffic back - out of the receiving port.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>UseBPDU=</varname></term> - <listitem> - <para>A boolean. Configures whether STP Bridge Protocol Data Units will be - processed by the bridge port. Defaults to yes.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>FastLeave=</varname></term> - <listitem> - <para>A boolean. This flag allows the bridge to immediately stop multicast - traffic on a port that receives an IGMP Leave message. It is only used with - IGMP snooping if enabled on the bridge. Defaults to off.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>AllowPortToBeRoot=</varname></term> - <listitem> - <para>A boolean. Configures whether a given port is allowed to - become a root port. Only used when STP is enabled on the bridge. - Defaults to on.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Cost=</varname></term> - <listitem> - <para>Sets the "cost" of sending packets of this interface. - Each port in a bridge may have a different speed and the cost - is used to decide which link to use. Faster interfaces - should have lower costs.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - <refsect1> - <title>[BridgeFDB] Section Options</title> - <para>The <literal>[BridgeFDB]</literal> section manages the - forwarding database table of a port and accepts the following - keys. Specify several <literal>[BridgeFDB]</literal> sections to - configure several static MAC table entries.</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>MACAddress=</varname></term> - <listitem> - <para>As in the <literal>[Network]</literal> section. This - key is mandatory.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>VLANId=</varname></term> - <listitem> - <para>The VLAN ID for the new static MAC table entry. If - omitted, no VLAN ID info is appended to the new static MAC - table entry.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Example</title> - <example> - <title>/etc/systemd/network/50-static.network</title> - - <programlisting>[Match] -Name=enp2s0 - -[Network] -Address=192.168.0.15/24 -Gateway=192.168.0.1</programlisting> - </example> - - <example> - <title>/etc/systemd/network/80-dhcp.network</title> - - <programlisting>[Match] -Name=en* - -[Network] -DHCP=yes</programlisting> - </example> - - <example> - <title>/etc/systemd/network/25-bridge-static.network</title> - - <programlisting>[Match] -Name=bridge0 - -[Network] -Address=192.168.0.15/24 -Gateway=192.168.0.1 -DNS=192.168.0.1</programlisting> - </example> - - <example> - <title>/etc/systemd/network/25-bridge-slave-interface.network</title> - - <programlisting>[Match] -Name=enp2s0 - -[Network] -Bridge=bridge0</programlisting> - </example> - <example> - <title>/etc/systemd/network/25-ipip.network</title> - - <programlisting>[Match] -Name=em1 - -[Network] -Tunnel=ipip-tun</programlisting> - </example> - - <example> - <title>/etc/systemd/network/25-sit.network</title> - - <programlisting>[Match] -Name=em1 - -[Network] -Tunnel=sit-tun</programlisting> - </example> - - <example> - <title>/etc/systemd/network/25-gre.network</title> - - <programlisting>[Match] -Name=em1 - -[Network] -Tunnel=gre-tun</programlisting> - </example> - - <example> - <title>/etc/systemd/network/25-vti.network</title> - - <programlisting>[Match] -Name=em1 - -[Network] -Tunnel=vti-tun</programlisting> - </example> - - <example> - <title>/etc/systemd/network/25-bond.network</title> - - <programlisting>[Match] -Name=bond1 - -[Network] -DHCP=yes -</programlisting> - </example> - - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd.nspawn.xml b/man/systemd.nspawn.xml deleted file mode 100644 index 3683412c14..0000000000 --- a/man/systemd.nspawn.xml +++ /dev/null @@ -1,454 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ -<!ENTITY % entities SYSTEM "custom-entities.ent" > -%entities; -]> - -<!-- - This file is part of systemd. - - Copyright 2015 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>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd.nspawn</refname> - <refpurpose>Container settings</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/etc/systemd/nspawn/<replaceable>machine</replaceable>.nspawn</filename></para> - <para><filename>/run/systemd/nspawn/<replaceable>machine</replaceable>.nspawn</filename></para> - <para><filename>/var/lib/machines/<replaceable>machine</replaceable>.nspawn</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>An nspawn container settings file (suffix - <filename>.nspawn</filename>) encodes additional runtime - information about a local container, and is searched, read and - used by - <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> - when starting a container. Files of this type are named after the - containers they define settings for. They are optional, and only - required for containers whose execution environment shall differ - from the defaults. Files of this type mostly contain settings that - may also be set on the <command>systemd-nspawn</command> command - line, and make it easier to persistently attach specific settings - to specific containers. The syntax of these files is inspired by - <filename>.desktop</filename> files following the <ulink - url="http://standards.freedesktop.org/desktop-entry-spec/latest/">XDG - Desktop Entry Specification</ulink>, which in turn are inspired by - Microsoft Windows <filename>.ini</filename> files.</para> - - <para>Boolean arguments used in these settings 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>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> - - </refsect1> - - <refsect1> - <title><filename>.nspawn</filename> File Discovery</title> - - <para>Files are searched by appending the - <filename>.nspawn</filename> suffix to the machine name of the - container, as specified with the <option>--machine=</option> - switch of <command>systemd-nspawn</command>, or derived from the - directory or image file name. This file is first searched in - <filename>/etc/systemd/nspawn/</filename> and - <filename>/run/systemd/nspawn/</filename>. If found in these - directories, its settings are read and all of them take full effect - (but are possibly overridden by corresponding command line - arguments). If not found, the file will then be searched next to - the image file or in the immediate parent of the root directory of - the container. If the file is found there, only a subset of the - settings will take effect however. All settings that possibly - elevate privileges or grant additional access to resources of the - host (such as files or directories) are ignored. To which options - this applies is documented below.</para> - - <para>Persistent settings files created and maintained by the - administrator (and thus trusted) should be placed in - <filename>/etc/systemd/nspawn/</filename>, while automatically - downloaded (and thus potentially untrusted) settings files are - placed in <filename>/var/lib/machines/</filename> instead (next to - the container images), where their security impact is limited. In - order to add privileged settings to <filename>.nspawn</filename> - files acquired from the image vendor, it is recommended to copy the - settings files into <filename>/etc/systemd/nspawn/</filename> and - edit them there, so that the privileged options become - available. The precise algorithm for how the files are searched and - interpreted may be configured with - <command>systemd-nspawn</command>'s <option>--settings=</option> - switch, see - <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> - for details.</para> - </refsect1> - - <refsect1> - <title>[Exec] Section Options</title> - - <para>Settings files may include an <literal>[Exec]</literal> - section, which carries various execution parameters:</para> - - <variablelist> - - <varlistentry> - <term><varname>Boot=</varname></term> - - <listitem><para>Takes a boolean argument, which defaults to off. If enabled, <command>systemd-nspawn</command> - will automatically search for an <filename>init</filename> executable and invoke it. In this case, the - specified parameters using <varname>Parameters=</varname> are passed as additional arguments to the - <filename>init</filename> process. This setting corresponds to the <option>--boot</option> switch on the - <command>systemd-nspawn</command> command line. This option may not be combined with - <varname>ProcessTwo=yes</varname>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>ProcessTwo=</varname></term> - - <listitem><para>Takes a boolean argument, which defaults to off. If enabled, the specified program is run as - PID 2. A stub init process is run as PID 1. This setting corresponds to the <option>--as-pid2</option> switch - on the <command>systemd-nspawn</command> command line. This option may not be combined with - <varname>Boot=yes</varname>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Parameters=</varname></term> - - <listitem><para>Takes a space-separated list of - arguments. This is either a command line, beginning with the - binary name to execute, or – if <varname>Boot=</varname> is - enabled – the list of arguments to pass to the init - process. This setting corresponds to the command line - parameters passed on the <command>systemd-nspawn</command> - command line.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Environment=</varname></term> - - <listitem><para>Takes an environment variable assignment - consisting of key and value, separated by - <literal>=</literal>. Sets an environment variable for the - main process invoked in the container. This setting may be - used multiple times to set multiple environment variables. It - corresponds to the <option>--setenv=</option> command line - switch.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>User=</varname></term> - - <listitem><para>Takes a UNIX user name. Specifies the user - name to invoke the main process of the container as. This user - must be known in the container's user database. This - corresponds to the <option>--user=</option> command line - switch.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>WorkingDirectory=</varname></term> - - <listitem><para>Selects the working directory for the process invoked in the container. Expects an absolute - path in the container's file system namespace. This corresponds to the <option>--chdir=</option> command line - switch.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Capability=</varname></term> - <term><varname>DropCapability=</varname></term> - - <listitem><para>Takes a space-separated list of Linux process - capabilities (see - <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for details). The <varname>Capability=</varname> setting - specifies additional capabilities to pass on top of the - default set of capabilities. The - <varname>DropCapability=</varname> setting specifies - capabilities to drop from the default set. These settings - correspond to the <option>--capability=</option> and - <option>--drop-capability=</option> command line - switches. Note that <varname>Capability=</varname> is a - privileged setting, and only takes effect in - <filename>.nspawn</filename> files in - <filename>/etc/systemd/nspawn/</filename> and - <filename>/run/system/nspawn/</filename> (see above). On the - other hand, <varname>DropCapability=</varname> takes effect in - all cases.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>KillSignal=</varname></term> - - <listitem><para>Specify the process signal to send to the - container's PID 1 when nspawn itself receives SIGTERM, in - order to trigger an orderly shutdown of the container. - Defaults to SIGRTMIN+3 if <option>Boot=</option> is used - (on systemd-compatible init systems SIGRTMIN+3 triggers an - orderly shutdown). For a list of valid signals, see - <citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Personality=</varname></term> - - <listitem><para>Configures the kernel personality for the - container. This is equivalent to the - <option>--personality=</option> switch.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>MachineID=</varname></term> - - <listitem><para>Configures the 128-bit machine ID (UUID) to pass to - the container. This is equivalent to the - <option>--uuid=</option> command line switch. This option is - privileged (see above). </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>PrivateUsers=</varname></term> - - <listitem><para>Configures support for usernamespacing. This is equivalent to the - <option>--private-users=</option> command line switch, and takes the same options. This option is privileged - (see above). </para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>[Files] Section Options</title> - - <para>Settings files may include a <literal>[Files]</literal> - section, which carries various parameters configuring the file - system of the container:</para> - - <variablelist> - - <varlistentry> - <term><varname>ReadOnly=</varname></term> - - <listitem><para>Takes a boolean argument, which defaults to off. If - specified, the container will be run with a read-only file - system. This setting corresponds to the - <option>--read-only</option> command line - switch.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Volatile=</varname></term> - - <listitem><para>Takes a boolean argument, or the special value - <literal>state</literal>. This configures whether to run the - container with volatile state and/or configuration. This - option is equivalent to <option>--volatile=</option>, see - <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> - for details about the specific options - supported.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Bind=</varname></term> - <term><varname>BindReadOnly=</varname></term> - - <listitem><para>Adds a bind mount from the host into the - container. Takes a single path, a pair of two paths separated - by a colon, or a triplet of two paths plus an option string - separated by colons. This option may be used multiple times to - configure multiple bind mounts. This option is equivalent to - the command line switches <option>--bind=</option> and - <option>--bind-ro=</option>, see - <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> - for details about the specific options supported. This setting - is privileged (see above).</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>TemporaryFileSystem=</varname></term> - - <listitem><para>Adds a <literal>tmpfs</literal> mount to the - container. Takes a path or a pair of path and option string, - separated by a colon. This option may be used multiple times to - configure multiple <literal>tmpfs</literal> mounts. This - option is equivalent to the command line switch - <option>--tmpfs=</option>, see - <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> - for details about the specific options supported. This setting - is privileged (see above).</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>PrivateUsersChown=</varname></term> - - <listitem><para>Configures whether the ownership of the files and directories in the container tree shall be - adjusted to the UID/GID range used, if necessary and user namespacing is enabled. This is equivalent to the - <option>--private-users-chown</option> command line switch. This option is privileged (see - above). </para></listitem> - </varlistentry> - - </variablelist> - </refsect1> - - <refsect1> - <title>[Network] Section Options</title> - - <para>Settings files may include a <literal>[Network]</literal> - section, which carries various parameters configuring the network - connectivity of the container:</para> - - <variablelist> - - <varlistentry> - <term><varname>Private=</varname></term> - - <listitem><para>Takes a boolean argument, which defaults to off. If - enabled, the container will run in its own network namespace - and not share network interfaces and configuration with the - host. This setting corresponds to the - <option>--private-network</option> command line - switch.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>VirtualEthernet=</varname></term> - - <listitem><para>Takes a boolean argument. Configures whether - to create a virtual Ethernet connection - (<literal>veth</literal>) between host and the container. This - setting implies <varname>Private=yes</varname>. This setting - corresponds to the <option>--network-veth</option> command - line switch. This option is privileged (see - above).</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>VirtualEthernetExtra=</varname></term> - - <listitem><para>Takes a colon-separated pair of interface - names. Configures an additional virtual Ethernet connection - (<literal>veth</literal>) between host and the container. The - first specified name is the interface name on the host, the - second the interface name in the container. The latter may be - omitted in which case it is set to the same name as the host - side interface. This setting implies - <varname>Private=yes</varname>. This setting corresponds to - the <option>--network-veth-extra=</option> command line - switch, and maybe be used multiple times. It is independent of - <varname>VirtualEthernet=</varname>. This option is privileged - (see above).</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Interface=</varname></term> - - <listitem><para>Takes a space-separated list of interfaces to - add to the container. This option corresponds to the - <option>--network-interface=</option> command line switch and - implies <varname>Private=yes</varname>. This option is - privileged (see above).</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>MACVLAN=</varname></term> - <term><varname>IPVLAN=</varname></term> - - <listitem><para>Takes a space-separated list of interfaces to - add MACLVAN or IPVLAN interfaces to, which are then added to - the container. These options correspond to the - <option>--network-macvlan=</option> and - <option>--network-ipvlan=</option> command line switches and - imply <varname>Private=yes</varname>. These options are - privileged (see above).</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Bridge=</varname></term> - - <listitem><para>Takes an interface name. This setting implies - <varname>VirtualEthernet=yes</varname> and - <varname>Private=yes</varname> and has the effect that the - host side of the created virtual Ethernet link is connected to - the specified bridge interface. This option corresponds to the - <option>--network-bridge=</option> command line switch. This - option is privileged (see above).</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Zone=</varname></term> - - <listitem><para>Takes a network zone name. This setting implies <varname>VirtualEthernet=yes</varname> and - <varname>Private=yes</varname> and has the effect that the host side of the created virtual Ethernet link is - connected to an automatically managed bridge interface named after the passed argument, prefixed with - <literal>vz-</literal>. This option corresponds to the <option>--network-zone=</option> command line - switch. This option is privileged (see above).</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Port=</varname></term> - - <listitem><para>Exposes a TCP or UDP port of the container on - the host. This option corresponds to the - <option>--port=</option> command line switch, see - <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> - for the precise syntax of the argument this option takes. This - option is privileged (see above).</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd.offline-updates.xml b/man/systemd.offline-updates.xml deleted file mode 100644 index 946234ad90..0000000000 --- a/man/systemd.offline-updates.xml +++ /dev/null @@ -1,169 +0,0 @@ -<?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 2013 Lennart Poettering - Copyright 2016 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.offline-updates"> - <refentryinfo> - <title>systemd.offline-updates</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.offline-updates</refentrytitle> - <manvolnum>7</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd.offline-updates</refname> - <refpurpose>Implementation of offline updates in systemd</refpurpose> - </refnamediv> - - <refsect1> - <title>Implementing Offline System Updates</title> - - <para>This man page describes how to implement "offline" system updates with systemd. By "offline" - OS updates we mean package installations and updates that are run with the system booted into a - special system update mode, in order to avoid problems related to conflicts of libraries and - services that are currently running with those on disk. This document is inspired by this - <ulink url="https://wiki.gnome.org/Design/OS/SoftwareUpdates">GNOME design whiteboard</ulink>. - </para> - - <para>The logic:</para> - - <orderedlist> - <listitem> - <para>The package manager prepares system updates by downloading all (RPM or DEB or - whatever) packages to update off-line in a special directory - <filename noindex="true">/var/lib/system-update</filename> (or - another directory of the package/upgrade manager's choice).</para> - </listitem> - - <listitem> - <para>When the user OK'ed the update, the symlink <filename>/system-update</filename> is - created that points to <filename noindex="true">/var/lib/system-update</filename> (or - wherever the directory with the upgrade files is located) and the system is rebooted. This - symlink is in the root directory, since we need to check for it very early at boot, at a - time where <filename>/var</filename> is not available yet.</para> - </listitem> - - <listitem> - <para>Very early in the new boot - <citerefentry><refentrytitle>systemd-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> - checks whether <filename>/system-update</filename> exists. If so, it (temporarily and for - this boot only) redirects (i.e. symlinks) <filename>default.target</filename> to - <filename>system-update.target</filename>, a special target that is pulls in the base system - (i.e. <filename>sysinit.target</filename>, so that all file systems are mounted but little - else) and the system update units.</para> - </listitem> - - <listitem> - <para>The system now continues to boot into <filename>default.target</filename>, and thus - into <filename>system-update.target</filename>. This target pulls in the system update unit, - which starts the system update script after all file systems have been mounted.</para> - </listitem> - - <listitem> - <para>As the first step, the update script should check if the - <filename>/system-update</filename> symlink points to the the location used by that update - script. In case it does not exists or points to a different location, the script must exit - without error. It is possible for multiple update services to be installed, and for multiple - update scripts to be launched in parallel, and only the one that corresponds to the tool - that <emphasis>created</emphasis> the symlink before reboot should perform any actions. It - is unsafe to run multiple updates in parallel.</para> - </listitem> - - <listitem> - <para>The update script should now do its job. If applicable and possible, it should - create a file system snapshot, then install all packages. - After completion (regardless whether the update succeeded or failed) the machine - must be rebooted, for example by calling <command>systemctl reboot</command>. - In addition, on failure the script should revert to the old file system snapshot - (without the symlink).</para> - </listitem> - - <listitem> - <para>The system is rebooted. Since the <filename>/system-update</filename> symlink is gone, - the generator won't redirect <filename>default.target</filename> after reboot and the - system now boots into the default target again.</para> - </listitem> - </orderedlist> - </refsect1> - - <refsect1> - <title>Recommendations</title> - - <orderedlist> - <listitem> - <para>To make things a bit more robust we recommend hooking the update script into - <filename>system-update.target</filename> via a <filename noindex='true'>.wants/</filename> - symlink in the distribution package, rather than depending on <command>systemctl - enable</command> in the postinst scriptlets of your package. More specifically, for your - update script create a .service file, without [Install] section, and then add a symlink like - <filename noindex='true'>/usr/lib/systemd/system-update.target.wants/foobar.service</filename> - → <filename noindex='true'>../foobar.service</filename> to your package.</para> - </listitem> - - <listitem> - <para>Make sure to remove the <filename>/system-update</filename> symlink as early as - possible in the update script to avoid reboot loops in case the update fails.</para> - </listitem> - - <listitem> - <para>Use <varname>FailureAction=reboot</varname> in the service file for your update script - to ensure that a reboot is automatically triggered if the update fails. - <varname>FailureAction=</varname> makes sure that the specified unit is activated if your - script exits uncleanly (by non-zero error code, or signal/coredump). If your script succeeds - you should trigger the reboot in your own code, for example by invoking logind's - <command>Reboot()</command> call or calling <command>systemct reboot</command>. See - <ulink url="http://www.freedesktop.org/wiki/Software/systemd/logind">logind dbus API</ulink> - for details.</para> - </listitem> - - <listitem> - <para>The update service should declare <varname>DefaultDependencies=false</varname>, - and pull in any services it requires explicitly.</para> - </listitem> - </orderedlist> - </refsect1> - - <refsect1> - <title>See also</title> - - <para> - <ulink url="http://www.freedesktop.org/wiki/Software/systemd/SystemUpdates/">Implementing Offline System Updates</ulink>, - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>dnf.plugin.system-upgrade</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> -</refentry> diff --git a/man/systemd.path.xml b/man/systemd.path.xml deleted file mode 100644 index 7200c8fe27..0000000000 --- a/man/systemd.path.xml +++ /dev/null @@ -1,202 +0,0 @@ -<?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.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><replaceable>path</replaceable>.path</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>A unit configuration file whose name ends in - <literal>.path</literal> 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 project='man-pages'><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> - </refsect1> - - <refsect1> - <title>Automatic Dependencies</title> - - <para>If a path unit is beneath another mount unit in the file - system hierarchy, both a requirement and an ordering dependency - between both units are created automatically.</para> - - <para>An implicit <varname>Before=</varname> dependency is added - between a path unit and the unit it is supposed to activate.</para> - - <para>Unless <varname>DefaultDependencies=false</varname> in the <literal>[Unit]</literal> section is used, path - units will implicitly have dependencies of type <varname>Before=</varname> on <filename>paths.target</filename>, - dependencies of type <varname>After=</varname> and <varname>Requires=</varname> on - <filename>sysinit.target</filename>, and 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 class='unit-directives'> - <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. If the empty string - is assigned to any of these options, the list of paths to - watch is reset, and any prior assignments of these options - will not have any effect.</para> - - <para>If a path already exists (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> and - <varname>PathModified=</varname>.</para> - - <para>If the path itself or any of the containing directories - are not accessible, <command>systemd</command> will watch for - permission changes and notice that conditions are satisfied - when permissions allow that. </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 <literal>.path</literal>. 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>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>inotify</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd.preset.xml b/man/systemd.preset.xml deleted file mode 100644 index b7164014f0..0000000000 --- a/man/systemd.preset.xml +++ /dev/null @@ -1,189 +0,0 @@ -<?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>-<policy-name>.preset</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 lexicographic order, regardless of which of the - directories they reside in. If multiple files specify the same - unit name, the entry in the file with the lexicographically - earliest name will be applied. It is recommended to prefix all - filenames with a two-digit number and a dash, to simplify the - ordering of the files.</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 - filename.</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 filename 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 filename - 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.resource-control.xml b/man/systemd.resource-control.xml deleted file mode 100644 index 066f2cc19b..0000000000 --- a/man/systemd.resource-control.xml +++ /dev/null @@ -1,628 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2013 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.resource-control"> - <refentryinfo> - <title>systemd.resource-control</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.resource-control</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd.resource-control</refname> - <refpurpose>Resource control unit settings</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para> - <filename><replaceable>slice</replaceable>.slice</filename>, - <filename><replaceable>scope</replaceable>.scope</filename>, - <filename><replaceable>service</replaceable>.service</filename>, - <filename><replaceable>socket</replaceable>.socket</filename>, - <filename><replaceable>mount</replaceable>.mount</filename>, - <filename><replaceable>swap</replaceable>.swap</filename> - </para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>Unit configuration files for services, slices, scopes, - sockets, mount points, and swap devices share a subset of - configuration options for resource control of spawned - processes. Internally, this relies on the Control Groups - kernel concept for organizing processes in a hierarchical tree of - named groups for the purpose of resource management.</para> - - <para>This man page lists the configuration options shared by - those six 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.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.scope</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.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - and - <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more information on the specific unit configuration files. The - resource control configuration options are configured in the - [Slice], [Scope], [Service], [Socket], [Mount], or [Swap] - sections, depending on the unit type.</para> - - <para>See the <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface/">New - Control Group Interfaces</ulink> for an introduction on how to make - use of resource control APIs from programs.</para> - </refsect1> - - <refsect1> - <title>Automatic Dependencies</title> - - <para>Units with the <varname>Slice=</varname> setting set get - automatic <varname>Requires=</varname> and - <varname>After=</varname> dependencies on the specified slice - unit.</para> - </refsect1> - - <refsect1> - <title>Unified and Legacy Control Group Hierarchies</title> - - <para>Unified control group hierarchy is the new version of kernel control group interface. Depending on the - resource type, there are differences in resource control capabilities. Also, because of interface changes, some - resource types have a separate set of options on the unified hierarchy.</para> - - <para> - <variablelist> - <varlistentry> - <term><option>IO</option></term> - <listitem> - <para><varname>IO</varname> prefixed settings are superset of and replace <varname>BlockIO</varname> - prefixed ones. On unified hierarchy, IO resource control also applies to buffered writes.</para> - </listitem> - </varlistentry> - </variablelist> - </para> - - <para>To ease the transition, there is best-effort translation between the two versions of settings. If all - settings of a unit for a given resource type are for the other hierarchy type, the settings are translated and - applied. If there are any valid settings for the hierarchy in use, all translations are disabled for the resource - type. Mixing the two types of settings on a unit can lead to confusing results.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>Units of the types listed above can have settings - for resource control configuration:</para> - - <variablelist class='unit-directives'> - - <varlistentry> - <term><varname>CPUAccounting=</varname></term> - - <listitem> - <para>Turn on CPU usage accounting for this unit. Takes a - boolean argument. Note that turning on CPU accounting for - one unit will also implicitly turn it on for all units - contained in the same slice and for all its parent slices - and the units contained therein. The system default for this - setting may be controlled with - <varname>DefaultCPUAccounting=</varname> in - <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>CPUShares=<replaceable>weight</replaceable></varname></term> - <term><varname>StartupCPUShares=<replaceable>weight</replaceable></varname></term> - - <listitem> - <para>Assign the specified CPU time share weight to the - processes executed. These options take an integer value and - control the <literal>cpu.shares</literal> control group - attribute. The allowed range is 2 to 262144. Defaults to - 1024. For details about this control group attribute, see - <ulink - url="https://www.kernel.org/doc/Documentation/scheduler/sched-design-CFS.txt">sched-design-CFS.txt</ulink>. - The available CPU time is split up among all units within - one slice relative to their CPU time share weight.</para> - - <para>While <varname>StartupCPUShares=</varname> only - applies to the startup phase of the system, - <varname>CPUShares=</varname> applies to normal runtime of - the system, and if the former is not set also to the startup - phase. Using <varname>StartupCPUShares=</varname> allows - prioritizing specific services at boot-up differently than - during normal runtime.</para> - - <para>These options imply - <literal>CPUAccounting=true</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>CPUQuota=</varname></term> - - <listitem> - <para>Assign the specified CPU time quota to the processes - executed. Takes a percentage value, suffixed with "%". The - percentage specifies how much CPU time the unit shall get at - maximum, relative to the total CPU time available on one - CPU. Use values > 100% for allotting CPU time on more than - one CPU. This controls the - <literal>cpu.cfs_quota_us</literal> control group - attribute. For details about this control group attribute, - see <ulink - url="https://www.kernel.org/doc/Documentation/scheduler/sched-design-CFS.txt">sched-design-CFS.txt</ulink>.</para> - - <para>Example: <varname>CPUQuota=20%</varname> ensures that - the executed processes will never get more than 20% CPU time - on one CPU.</para> - - <para>Implies <literal>CPUAccounting=true</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>MemoryAccounting=</varname></term> - - <listitem> - <para>Turn on process and kernel memory accounting for this - unit. Takes a boolean argument. Note that turning on memory - accounting for one unit will also implicitly turn it on for - all units contained in the same slice and for all its parent - slices and the units contained therein. The system default - for this setting may be controlled with - <varname>DefaultMemoryAccounting=</varname> in - <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>MemoryLimit=<replaceable>bytes</replaceable></varname></term> - - <listitem> - <para>Specify the limit on maximum memory usage of the - executed processes. The limit specifies how much process and - kernel memory can be used by tasks in this unit. 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 (with the base 1024), - respectively. If assigned the special value - <literal>infinity</literal>, no memory limit is applied. This - controls the <literal>memory.limit_in_bytes</literal> - control group attribute. For details about this control - group attribute, see <ulink - url="https://www.kernel.org/doc/Documentation/cgroup-v1/memory.txt">memory.txt</ulink>.</para> - - <para>Implies <literal>MemoryAccounting=true</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>TasksAccounting=</varname></term> - - <listitem> - <para>Turn on task accounting for this unit. Takes a - boolean argument. If enabled, the system manager will keep - track of the number of tasks in the unit. The number of - tasks accounted this way includes both kernel threads and - userspace processes, with each thread counting - individually. Note that turning on tasks accounting for one - unit will also implicitly turn it on for all units contained - in the same slice and for all its parent slices and the - units contained therein. The system default for this setting - may be controlled with - <varname>DefaultTasksAccounting=</varname> in - <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>TasksMax=<replaceable>N</replaceable></varname></term> - - <listitem> - <para>Specify the maximum number of tasks that may be - created in the unit. This ensures that the number of tasks - accounted for the unit (see above) stays below a specific - limit. If assigned the special value - <literal>infinity</literal>, no tasks limit is applied. This - controls the <literal>pids.max</literal> control group - attribute. For details about this control group attribute, - see <ulink - url="https://www.kernel.org/doc/Documentation/cgroup-v1/pids.txt">pids.txt</ulink>.</para> - - <para>Implies <literal>TasksAccounting=true</literal>. The - system default for this setting may be controlled with - <varname>DefaultTasksMax=</varname> in - <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>IOAccounting=</varname></term> - - <listitem> - <para>Turn on Block I/O accounting for this unit, if the unified control group hierarchy is used on the - system. Takes a boolean argument. Note that turning on block I/O accounting for one unit will also implicitly - turn it on for all units contained in the same slice and all for its parent slices and the units contained - therein. The system default for this setting may be controlled with <varname>DefaultIOAccounting=</varname> - in - <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> - - <para>This setting is supported only if the unified control group hierarchy is used. Use - <varname>BlockIOAccounting=</varname> on systems using the legacy control group hierarchy.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>IOWeight=<replaceable>weight</replaceable></varname></term> - <term><varname>StartupIOWeight=<replaceable>weight</replaceable></varname></term> - - <listitem> - <para>Set the default overall block I/O weight for the executed processes, if the unified control group - hierarchy is used on the system. Takes a single weight value (between 1 and 10000) to set the default block - I/O weight. This controls the <literal>io.weight</literal> control group attribute, which defaults to - 100. For details about this control group attribute, see <ulink - url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>. The available I/O - bandwidth is split up among all units within one slice relative to their block I/O weight.</para> - - <para>While <varname>StartupIOWeight=</varname> only applies - to the startup phase of the system, - <varname>IOWeight=</varname> applies to the later runtime of - the system, and if the former is not set also to the startup - phase. This allows prioritizing specific services at boot-up - differently than during runtime.</para> - - <para>Implies <literal>IOAccounting=true</literal>.</para> - - <para>This setting is supported only if the unified control group hierarchy is used. Use - <varname>BlockIOWeight=</varname> and <varname>StartupBlockIOWeight=</varname> on systems using the legacy - control group hierarchy.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>IODeviceWeight=<replaceable>device</replaceable> <replaceable>weight</replaceable></varname></term> - - <listitem> - <para>Set the per-device overall block I/O weight for the executed processes, if the unified control group - hierarchy is used on the system. Takes a space-separated pair of a file path and a weight value to specify - the device specific weight value, between 1 and 10000. (Example: "/dev/sda 1000"). 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>io.weight</literal> control group - attribute, which defaults to 100. Use this option multiple times to set weights for multiple devices. For - details about this control group attribute, see <ulink - url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.</para> - - <para>Implies <literal>IOAccounting=true</literal>.</para> - - <para>This setting is supported only if the unified control group hierarchy is used. Use - <varname>BlockIODeviceWeight=</varname> on systems using the legacy control group hierarchy.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>IOReadBandwidthMax=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term> - <term><varname>IOWriteBandwidthMax=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term> - - <listitem> - <para>Set the per-device overall block I/O bandwidth maximum limit for the executed processes, if the unified - control group hierarchy is used on the system. This limit is not work-conserving and the executed processes - are not allowed to use more even if the device has idle capacity. 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 a 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 used. If the bandwidth is suffixed with K, M, G, or T, the specified bandwidth is - parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes, respectively, to the base of 1000. (Example: - "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 5M"). This controls the <literal>io.max</literal> control - group attributes. Use this option multiple times to set bandwidth limits for multiple devices. For details - about this control group attribute, see <ulink - url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>. - </para> - - <para>Implies <literal>IOAccounting=true</literal>.</para> - - <para>This setting is supported only if the unified control group hierarchy is used. Use - <varname>BlockIOAccounting=</varname> on systems using the legacy control group hierarchy.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>IOReadIOPSMax=<replaceable>device</replaceable> <replaceable>IOPS</replaceable></varname></term> - <term><varname>IOWriteIOPSMax=<replaceable>device</replaceable> <replaceable>IOPS</replaceable></varname></term> - - <listitem> - <para>Set the per-device overall block I/O IOs-Per-Second maximum limit for the executed processes, if the - unified control group hierarchy is used on the system. This limit is not work-conserving and the executed - processes are not allowed to use more even if the device has idle capacity. Takes a space-separated pair of - a file path and an IOPS value to specify the device specific IOPS. The file path may be a 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 - used. If the IOPS is suffixed with K, M, G, or T, the specified IOPS is parsed as KiloIOPS, MegaIOPS, - GigaIOPS, or TeraIOPS, respectively, to the base of 1000. (Example: - "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 1K"). This controls the <literal>io.max</literal> control - group attributes. Use this option multiple times to set IOPS limits for multiple devices. For details about - this control group attribute, see <ulink - url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>. - </para> - - <para>Implies <literal>IOAccounting=true</literal>.</para> - - <para>This setting is supported only if the unified control group hierarchy is used.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>BlockIOAccounting=</varname></term> - - <listitem> - <para>Turn on Block I/O accounting for this unit, if the legacy control group hierarchy is used on the - system. Takes a boolean argument. Note that turning on block I/O accounting for one unit will also implicitly - turn it on for all units contained in the same slice and all for its parent slices and the units contained - therein. The system default for this setting may be controlled with - <varname>DefaultBlockIOAccounting=</varname> in - <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> - - <para>This setting is supported only if the legacy control group hierarchy is used. Use - <varname>IOAccounting=</varname> on systems using the unified control group hierarchy.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>BlockIOWeight=<replaceable>weight</replaceable></varname></term> - <term><varname>StartupBlockIOWeight=<replaceable>weight</replaceable></varname></term> - - <listitem><para>Set the default overall block I/O weight for the executed processes, if the legacy control - group hierarchy is used on the system. Takes a single weight value (between 10 and 1000) to set the default - block I/O weight. This controls the <literal>blkio.weight</literal> control group attribute, which defaults to - 500. For details about this control group attribute, see <ulink - url="https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</ulink>. - The available I/O bandwidth is split up among all units within one slice relative to their block I/O - weight.</para> - - <para>While <varname>StartupBlockIOWeight=</varname> only - applies to the startup phase of the system, - <varname>BlockIOWeight=</varname> applies to the later runtime - of the system, and if the former is not set also to the - startup phase. This allows prioritizing specific services at - boot-up differently than during runtime.</para> - - <para>Implies - <literal>BlockIOAccounting=true</literal>.</para> - - <para>This setting is supported only if the legacy control group hierarchy is used. Use - <varname>IOWeight=</varname> and <varname>StartupIOWeight=</varname> on systems using the unified control group - hierarchy.</para> - - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>BlockIODeviceWeight=<replaceable>device</replaceable> <replaceable>weight</replaceable></varname></term> - - <listitem> - <para>Set the per-device overall block I/O weight for the executed processes, if the legacy control group - hierarchy is used on the system. Takes a space-separated pair of a file path and a weight value to specify - the device specific weight value, between 10 and 1000. (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_device</literal> control group - attribute, which defaults to 1000. Use this option multiple times to set weights for multiple devices. For - details about this control group attribute, see <ulink - url="https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</ulink>.</para> - - <para>Implies - <literal>BlockIOAccounting=true</literal>.</para> - - <para>This setting is supported only if the legacy control group hierarchy is used. Use - <varname>IODeviceWeight=</varname> on systems using the unified control group hierarchy.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>BlockIOReadBandwidth=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term> - <term><varname>BlockIOWriteBandwidth=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term> - - <listitem> - <para>Set the per-device overall block I/O bandwidth limit for the executed processes, if the legacy control - group hierarchy is used on the system. 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 a 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 used. If - the bandwidth is suffixed with K, M, G, or T, the specified bandwidth is parsed as Kilobytes, Megabytes, - Gigabytes, or Terabytes, respectively, to the base of 1000. (Example: - "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 5M"). This controls the - <literal>blkio.throttle.read_bps_device</literal> and <literal>blkio.throttle.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="https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</ulink>. - </para> - - <para>Implies - <literal>BlockIOAccounting=true</literal>.</para> - - <para>This setting is supported only if the legacy control group hierarchy is used. Use - <varname>IOReadBandwidthMax=</varname> and <varname>IOWriteBandwidthMax=</varname> on systems using the - unified control group hierarchy.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>DeviceAllow=</varname></term> - - <listitem> - <para>Control access to specific device nodes by the - executed processes. Takes two space-separated strings: a - device node specifier followed by a combination of - <constant>r</constant>, <constant>w</constant>, - <constant>m</constant> to control - <emphasis>r</emphasis>eading, <emphasis>w</emphasis>riting, - or creation of the specific device node(s) by the unit - (<emphasis>m</emphasis>knod), 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="https://www.kernel.org/doc/Documentation/cgroup-v1/devices.txt">devices.txt</ulink>.</para> - - <para>The device node specifier is either a path to a device - node in the file system, starting with - <filename>/dev/</filename>, or a string starting with either - <literal>char-</literal> or <literal>block-</literal> - followed by a device group name, as listed in - <filename>/proc/devices</filename>. The latter is useful to - whitelist all current and future devices belonging to a - specific device group at once. The device group is matched - according to file name globbing rules, you may hence use the - <literal>*</literal> and <literal>?</literal> - wildcards. Examples: <filename>/dev/sda5</filename> is a - path to a device node, referring to an ATA or SCSI block - device. <literal>char-pts</literal> and - <literal>char-alsa</literal> are specifiers for all pseudo - TTYs and all ALSA sound devices, - respectively. <literal>char-cpu/*</literal> is a specifier - matching all CPU related device groups.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>DevicePolicy=auto|closed|strict</varname></term> - - <listitem> - <para> - Control the policy for allowing device access: - </para> - <variablelist> - <varlistentry> - <term><option>strict</option></term> - <listitem> - <para>means to only allow types of access that are - explicitly specified.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>closed</option></term> - <listitem> - <para>in addition, allows access to standard pseudo - devices including - <filename>/dev/null</filename>, - <filename>/dev/zero</filename>, - <filename>/dev/full</filename>, - <filename>/dev/random</filename>, and - <filename>/dev/urandom</filename>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>auto</option></term> - <listitem> - <para> - in addition, allows access to all devices if no - explicit <varname>DeviceAllow=</varname> is present. - This is the default. - </para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>Slice=</varname></term> - - <listitem> - <para>The name of the slice unit to place the unit - in. Defaults to <filename>system.slice</filename> for all - non-instantiated units of all unit types (except for slice - units themselves see below). Instance units are by default - placed in a subslice of <filename>system.slice</filename> - that is named after the template name.</para> - - <para>This option may be used to arrange systemd units in a - hierarchy of slices each of which might have resource - settings applied.</para> - - <para>For units of type slice, the only accepted value for - this setting is the parent slice. Since the name of a slice - unit implies the parent slice, it is hence redundant to ever - set this parameter directly for slice units.</para> - - <para>Special care should be taken when relying on the default slice assignment in templated service units - that have <varname>DefaultDependencies=no</varname> set, see - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, section - "Automatic Dependencies" for details.</para> - - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>Delegate=</varname></term> - - <listitem> - <para>Turns on delegation of further resource control - partitioning to processes of the unit. For unprivileged - services (i.e. those using the <varname>User=</varname> - setting), this allows processes to create a subhierarchy - beneath its control group path. For privileged services and - scopes, this ensures the processes will have all control - group controllers enabled.</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.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.socket</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.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - The documentation for control groups and specific controllers in the Linux kernel: - <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v1/cgroups.txt">cgroups.txt</ulink>, - <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v1/cpuacct.txt">cpuacct.txt</ulink>, - <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v1/memory.txt">memory.txt</ulink>, - <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</ulink>. - </para> - </refsect1> -</refentry> diff --git a/man/systemd.scope.xml b/man/systemd.scope.xml deleted file mode 100644 index f69b2ef635..0000000000 --- a/man/systemd.scope.xml +++ /dev/null @@ -1,108 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2013 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.scope"> - <refentryinfo> - <title>systemd.scope</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.scope</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd.scope</refname> - <refpurpose>Scope unit configuration</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename><replaceable>scope</replaceable>.scope</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>Scope units are not configured via unit configuration files, - but are only created programmatically using the bus interfaces of - systemd. They are named similar to filenames. A unit whose name - ends in <literal>.scope</literal> refers to a scope unit. Scopes - units manage a set of system processes. Unlike service units, scope - units manage externally created processes, and do not fork off - processes on its own.</para> - - <para>The main purpose of scope units is grouping worker processes - of a system service for organization and for managing resources.</para> - - <para><command>systemd-run <option>--scope</option></command> may - be used to easily launch a command in a new scope unit from the - command line.</para> - - <para>See the <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface/">New - Control Group Interfaces</ulink> for an introduction on how to make - use of scope units from programs.</para> - </refsect1> - - <refsect1> - <title>Automatic Dependencies</title> - - <para>Unless <varname>DefaultDependencies=false</varname> - is used, scope units will implicitly have dependencies of - type <varname>Conflicts=</varname> and - <varname>Before=</varname> on - <filename>shutdown.target</filename>. These ensure - that scope units are removed prior to system - shutdown. Only scope units involved with early boot or - late system shutdown should disable this option. - </para> - - <para>Additional implicit dependencies may be added as result of - resource control parameters as documented in - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> - - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>. - </para> - </refsect1> - -</refentry> diff --git a/man/systemd.service.xml b/man/systemd.service.xml deleted file mode 100644 index 6641dfed4f..0000000000 --- a/man/systemd.service.xml +++ /dev/null @@ -1,1352 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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><replaceable>service</replaceable>.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, - and in - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - which configure resource control settings for the processes of the - service.</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>Automatic Dependencies</title> - - <para>Services with <varname>Type=dbus</varname> set automatically - acquire dependencies of type <varname>Requires=</varname> and - <varname>After=</varname> on - <filename>dbus.socket</filename>.</para> - - <para>Socket activated service are automatically ordered after - their activated <filename>.socket</filename> units via an - automatic <varname>After=</varname> dependency.</para> - - <para>Unless <varname>DefaultDependencies=</varname> in the <literal>[Unit]</literal> is set to - <option>false</option>, service units will implicitly have dependencies of type <varname>Requires=</varname> and - <varname>After=</varname> on <filename>sysinit.target</filename>, a dependency of type <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>Instanced service units (i.e. service units with an <literal>@</literal> in their name) are assigned by - default a per-template slice unit (see - <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>), named after the - template unit, containing all instances of the specific template. This slice is normally stopped at shutdown, - together with all template instances. If that is not desired, set <varname>DefaultDependencies=no</varname> in the - template unit, and either define your own per-template slice unit file that also sets - <varname>DefaultDependencies=no</varname>, or set <varname>Slice=system.slice</varname> (or another suitable slice) - in the template unit. Also see - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> - - <para>Additional implicit dependencies may be added as result of - execution and resource control parameters as documented in - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</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 class='unit-directives'> - <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 if - neither <varname>Type=</varname> nor - <varname>BusName=</varname>, but <varname>ExecStart=</varname> - are 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 are 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 with 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. This is the implied default if neither - <varname>Type=</varname> or <varname>ExecStart=</varname> are - specified.</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 with - 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 has finished starting up. - systemd will proceed with 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>. Note that currently - <varname>Type=</varname><option>notify</option> will not work - if used in combination with - <varname>PrivateNetwork=</varname><option>yes</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, although - it will remove the file after the service has shut down if it - still exists. - </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>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>ExecStart=</varname></term> - <listitem><para>Commands with their arguments that are - executed when this service is started. The value is split into - zero or more command lines according to the rules described - below (see section "Command Lines" below). - </para> - - <para>When <varname>Type=</varname> is not - <option>oneshot</option>, only one command may and must be - given. When <varname>Type=oneshot</varname> is used, zero or - more commands may be specified. This can be specified by - providing multiple command lines in the same directive, or - alternatively, this directive may be specified more than once - with the same effect. If the empty string is assigned to this - option, the list of commands to start is reset, prior - assignments of this option will have no effect. If no - <varname>ExecStart=</varname> is specified, then the service - must have <varname>RemainAfterExit=yes</varname> set.</para> - - <para>For each of the specified commands, the first argument - must be an absolute path to an executable. Optionally, if this - 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 absolute filename 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, they - can appear in either order.</para> - - <para>If more than one command is specified, the commands are - invoked sequentially in the order they appear in the unit - file. If one of the commands fails (and is not prefixed with - <literal>-</literal>), other lines are not executed, and the - unit is considered failed.</para> - - <para>Unless <varname>Type=forking</varname> is set, the - process started via this command line will be considered the - main process of the daemon.</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. Syntax is the same as for - <varname>ExecStart=</varname>, except that multiple command - lines are allowed and the commands are executed one after the - other, serially.</para> - - <para>If any of those commands (not prefixed with - <literal>-</literal>) fail, the rest are not executed and the - unit is considered failed.</para> - - <para><varname>ExecStart=</varname> commands are only run after - all <varname>ExecStartPre=</varname> commands that were not prefixed - with a <literal>-</literal> exit successfully.</para> - - <para><varname>ExecStartPost=</varname> commands are only run after - the service has started successfully, as determined by <varname>Type=</varname> - (i.e. the process has been started for <varname>Type=simple</varname> - or <varname>Type=idle</varname>, the process exits successfully for - <varname>Type=oneshot</varname>, the initial process exits successfully - for <varname>Type=forking</varname>, <literal>READY=1</literal> is sent - for <varname>Type=notify</varname>, or the <varname>BusName=</varname> - has been taken for <varname>Type=dbus</varname>).</para> - - <para>Note that <varname>ExecStartPre=</varname> may not be - used to start long-running processes. All processes forked - off by processes invoked via <varname>ExecStartPre=</varname> will - be killed before the next service process is run.</para> - - <para>Note that if any of the commands specified in <varname>ExecStartPre=</varname>, - <varname>ExecStart=</varname>, or <varname>ExecStartPost=</varname> fail (and are not prefixed with - <literal>-</literal>, see above) or time out before the service is fully up, execution continues with commands - specified in <varname>ExecStopPost=</varname>, the commands in <varname>ExecStop=</varname> are skipped.</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 described for - <varname>ExecStart=</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>.</para> - - <para>One additional, special environment variable is set: if - known, <varname>$MAINPID</varname> is set to the main process - of the daemon, and may be used for command lines like the - following:</para> - - <programlisting>/bin/kill -HUP $MAINPID</programlisting> - - <para>Note however that reloading a daemon by sending a signal - (as with the example line above) is usually not a good choice, - because this is an asynchronous operation and hence not - suitable to order reloads of multiple services against each - other. It is strongly recommended to set - <varname>ExecReload=</varname> to a command that not only - triggers a configuration reload of the daemon, but also - synchronously waits for it to complete.</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 described - for <varname>ExecStart=</varname> above. Use of this setting - is optional. After the commands configured in this option are - run, all processes remaining for a service 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 by - sending the signal specified in <varname>KillSignal=</varname> - when service stop is requested. Specifier and environment - variable substitution is supported (including - <varname>$MAINPID</varname>, see above).</para> - - <para>Note that it is usually not sufficient to specify a - command for this setting that only asks the service to - terminate (for example, by queuing some form of termination - signal for it), but does not wait for it to do so. Since the - remaining processes of the services are killed using - <constant>SIGKILL</constant> immediately after the command - exited, this would not result in a clean stop. The specified - command should hence be a synchronous operation, not an - asynchronous one.</para> - - <para>Note that the commands specified in <varname>ExecStop=</varname> are only executed when the service - started successfully first. They are not invoked if the service was never started at all, or in case its - start-up failed, for example because any of the commands specified in <varname>ExecStart=</varname>, - <varname>ExecStartPre=</varname> or <varname>ExecStartPost=</varname> failed (and weren't prefixed with - <literal>-</literal>, see above) or timed out. Use <varname>ExecStopPost=</varname> to invoke commands when a - service failed to start up correctly and is shut down again.</para> - - <para>It is recommended to use this setting for commands that communicate with the service requesting clean - termination. When the commands specified with this option are executed it should be assumed that the service is - still fully up and is able to react correctly to all commands. For post-mortem clean-up steps use - <varname>ExecStopPost=</varname> instead.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>ExecStopPost=</varname></term> - <listitem><para>Additional commands that are executed after the service is stopped. This includes cases where - the commands configured in <varname>ExecStop=</varname> were used, where the service does not have any - <varname>ExecStop=</varname> defined, or where the service exited unexpectedly. This argument takes multiple - command lines, following the same scheme as described for <varname>ExecStart=</varname>. Use of these settings - is optional. Specifier and environment variable substitution is supported. Note that – unlike - <varname>ExecStop=</varname> – commands specified with this setting are invoked when a service failed to start - up correctly and is shut down again.</para> - - <para>It is recommended to use this setting for clean-up operations that shall be executed even when the - service failed to start up correctly. Commands configured with this setting need to be able to operate even if - the service failed starting up half-way and left incompletely initialized data around. As the service's - processes have been terminated already when the commands specified with this setting are executed they should - not attempt to communicate with them.</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 - will be shut down again. Takes a unit-less value in seconds, - or a time span value such as "5min 20s". Pass - <literal>infinity</literal> to disable the timeout logic. Defaults to - <varname>DefaultTimeoutStartSec=</varname> from the manager - configuration file, except when - <varname>Type=oneshot</varname> is used, in which case the - timeout is disabled by default (see - <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>). - </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 - <constant>SIGTERM</constant>, and after another timeout of - equal duration with <constant>SIGKILL</constant> (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 <literal>infinity</literal> to disable the - timeout logic. Defaults to - <varname>DefaultTimeoutStopSec=</varname> from the manager - configuration file (see - <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>). - </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>RuntimeMaxSec=</varname></term> - - <listitem><para>Configures a maximum time for the service to run. If this is used and the service has been - active for longer than the specified time it is terminated and put into a failure state. Note that this setting - does not have any effect on <varname>Type=oneshot</varname> services, as they terminate immediately after - activation completed. Pass <literal>infinity</literal> (the default) to configure no runtime - limit.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>WatchdogSec=</varname></term> - <listitem><para>Configures the watchdog timeout for a service. - The watchdog is activated when the start-up is completed. The - service must call - <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> - regularly with <literal>WATCHDOG=1</literal> (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 failed state and it will be terminated with - <constant>SIGABRT</constant>. By setting - <varname>Restart=</varname> to <option>on-failure</option>, - <option>on-watchdog</option>, <option>on-abnormal</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. The service can - check whether the service manager expects watchdog keep-alive - notifications. See - <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for details. - <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry> - may be used to enable automatic watchdog notification support. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Restart=</varname></term> - <listitem><para>Configures whether the service shall be - restarted when the service process exits, is killed, or a - timeout is reached. The service process may be the main - service process, but it may also be one of the processes - specified with <varname>ExecStartPre=</varname>, - <varname>ExecStartPost=</varname>, - <varname>ExecStop=</varname>, - <varname>ExecStopPost=</varname>, or - <varname>ExecReload=</varname>. When the death of the process - is a result of systemd operation (e.g. service stop or - restart), the service will not be restarted. Timeouts include - missing the watchdog "keep-alive ping" deadline and a service - start, reload, and stop operation timeouts.</para> - - <para>Takes one of - <option>no</option>, - <option>on-success</option>, - <option>on-failure</option>, - <option>on-abnormal</option>, - <option>on-watchdog</option>, - <option>on-abort</option>, or - <option>always</option>. - If set to <option>no</option> (the default), the service will - not be restarted. If set to <option>on-success</option>, it - will be restarted only when the service process exits cleanly. - In this context, a clean exit means an exit code of 0, or one - of the signals - <constant>SIGHUP</constant>, - <constant>SIGINT</constant>, - <constant>SIGTERM</constant> or - <constant>SIGPIPE</constant>, and - additionally, exit statuses and signals specified in - <varname>SuccessExitStatus=</varname>. If set to - <option>on-failure</option>, the service will be restarted - when the process exits with a non-zero exit code, is - terminated by a signal (including on core dump, but excluding - the aforementioned four signals), when an operation (such as - service reload) times out, and when the configured watchdog - timeout is triggered. If set to <option>on-abnormal</option>, - the service will be restarted when the process is terminated - by a signal (including on core dump, excluding the - aforementioned four signals), when an operation times out, or - when the watchdog timeout is triggered. If set to - <option>on-abort</option>, the service will be restarted only - if the service process exits due to an uncaught signal not - specified as a clean exit status. If set to - <option>on-watchdog</option>, the service will be restarted - only if the watchdog timeout for the service expires. If set - to <option>always</option>, the service will be restarted - regardless of whether it exited cleanly or not, got terminated - abnormally by a signal, or hit a timeout.</para> - - <table> - <title>Exit causes and the effect of the <varname>Restart=</varname> settings on them</title> - - <tgroup cols='2'> - <colspec colname='path' /> - <colspec colname='expl' /> - <thead> - <row> - <entry>Restart settings/Exit causes</entry> - <entry><option>no</option></entry> - <entry><option>always</option></entry> - <entry><option>on-success</option></entry> - <entry><option>on-failure</option></entry> - <entry><option>on-abnormal</option></entry> - <entry><option>on-abort</option></entry> - <entry><option>on-watchdog</option></entry> - </row> - </thead> - <tbody> - <row> - <entry>Clean exit code or signal</entry> - <entry/> - <entry>X</entry> - <entry>X</entry> - <entry/> - <entry/> - <entry/> - <entry/> - </row> - <row> - <entry>Unclean exit code</entry> - <entry/> - <entry>X</entry> - <entry/> - <entry>X</entry> - <entry/> - <entry/> - <entry/> - </row> - <row> - <entry>Unclean signal</entry> - <entry/> - <entry>X</entry> - <entry/> - <entry>X</entry> - <entry>X</entry> - <entry>X</entry> - <entry/> - </row> - <row> - <entry>Timeout</entry> - <entry/> - <entry>X</entry> - <entry/> - <entry>X</entry> - <entry>X</entry> - <entry/> - <entry/> - </row> - <row> - <entry>Watchdog</entry> - <entry/> - <entry>X</entry> - <entry/> - <entry>X</entry> - <entry>X</entry> - <entry/> - <entry>X</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>As exceptions to the setting above, the service will not - be restarted if the exit code or signal is specified in - <varname>RestartPreventExitStatus=</varname> (see below). - Also, the services will always be restarted if the exit code - or signal is specified in - <varname>RestartForceExitStatus=</varname> (see below).</para> - - <para>Setting this to <option>on-failure</option> is the - recommended choice for long-running services, in order to - increase reliability by attempting automatic recovery from - errors. For services that shall be able to terminate on their - own choice (and avoid immediate restarting), - <option>on-abnormal</option> is an alternative choice.</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 <constant>SIGHUP</constant>, - <constant>SIGINT</constant>, <constant>SIGTERM</constant>, and - <constant>SIGPIPE</constant>. Exit status definitions can - either be numeric exit codes or termination signal names, - separated by spaces. For example: - - <programlisting>SuccessExitStatus=1 2 8 SIGKILL</programlisting> - - ensures that exit codes 1, 2, 8 and - the termination signal <constant>SIGKILL</constant> are - considered clean service terminations. - </para> - - <para>Note that if a process has a signal handler installed - and exits by calling - <citerefentry><refentrytitle>_exit</refentrytitle><manvolnum>2</manvolnum></citerefentry> - in response to a signal, the information about the signal is - lost. Programs should instead perform cleanup and kill - themselves with the same signal instead. See - <ulink url="http://www.cons.org/cracauer/sigint.html">Proper - handling of SIGINT/SIGQUIT — How to be a proper - program</ulink>.</para> - - <para>This option may appear more than once, in which case the - list of successful exit statuses is merged. If the empty - string is assigned to this option, the list is reset, all - prior assignments of this option will have no - effect.</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. For example: - - <programlisting>RestartPreventExitStatus=1 6 SIGABRT</programlisting> - - ensures that exit codes 1 and 6 and the termination signal - <constant>SIGABRT</constant> will not result in automatic - service restarting. This option may appear more than once, in - which case the list of restart-preventing statuses is - merged. If the empty string is assigned to this option, the - list is reset and all prior assignments of this option will - have no effect.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>RestartForceExitStatus=</varname></term> - <listitem><para>Takes a list of exit status definitions that, - when returned by the main service process, will force automatic - service restarts, regardless of the restart setting configured - with <varname>Restart=</varname>. The argument format is - similar to - <varname>RestartPreventExitStatus=</varname>.</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>, and - <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>, - and <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 the <constant>O_NONBLOCK</constant> flag - for all file descriptors passed via socket-based activation. - If true, all file descriptors >= 3 (i.e. all except stdin, - stdout, and stderr) will have the - <constant>O_NONBLOCK</constant> 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>WatchdogSec=</varname> (see above). If those options - are used but <varname>NotifyAccess=</varname> is 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 socket file descriptors from when the - service is started. Normally, it should not be necessary to use - this setting, as all socket file descriptors whose unit shares - the same name as the service (subject to the different unit - name suffix of course) are passed to the spawned - process.</para> - - <para>Note that the same socket file descriptors may be passed - to multiple processes simultaneously. Also note that a - different service may be activated on incoming socket traffic - than the one which is ultimately configured to inherit the - socket file descriptors. Or, in other words: the - <varname>Service=</varname> setting of - <filename>.socket</filename> units does not have to match the - inverse of the <varname>Sockets=</varname> setting of the - <filename>.service</filename> it refers to.</para> - - <para>This option may appear more than once, in which case the - list of socket units is merged. If the empty string is - assigned to this option, the list of sockets is reset, and all - prior uses of this setting will have no - effect.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>FailureAction=</varname></term> - <listitem><para>Configure the action to take when the service enters a failed state. Takes the same values as - the unit setting <varname>StartLimitAction=</varname> and executes the same actions (see - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>). Defaults to - <option>none</option>. </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>FileDescriptorStoreMax=</varname></term> - <listitem><para>Configure how many file descriptors may be - stored in the service manager for the service using - <citerefentry><refentrytitle>sd_pid_notify_with_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>'s - <literal>FDSTORE=1</literal> messages. This is useful for - implementing service restart schemes where the state is - serialized to <filename>/run</filename> and the file - descriptors passed to the service manager, to allow restarts - without losing state. Defaults to 0, i.e. no file descriptors - may be stored in the service manager by default. All file - descriptors passed to the service manager from a specific - service are passed back to the service's main process on the - next service restart. Any file descriptors passed to the - service manager are automatically closed when POLLHUP or - POLLERR is seen on them, or when the service is fully stopped - and no job queued or being executed for it.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>USBFunctionDescriptors=</varname></term> - <listitem><para>Configure the location of a file containing - <ulink - url="https://www.kernel.org/doc/Documentation/usb/functionfs.txt">USB - FunctionFS</ulink> descriptors, for implementation of USB - gadget functions. This is used only in conjunction with a - socket unit with <varname>ListenUSBFunction=</varname> - configured. The contents of this file are written to the - <filename>ep0</filename> file after it is - opened.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>USBFunctionStrings=</varname></term> - <listitem><para>Configure the location of a file containing - USB FunctionFS strings. Behavior is similar to - <varname>USBFunctionDescriptors=</varname> - above.</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>Command lines</title> - - <para>This section describes command line parsing and - variable and specifier substitutions for - <varname>ExecStart=</varname>, - <varname>ExecStartPre=</varname>, - <varname>ExecStartPost=</varname>, - <varname>ExecReload=</varname>, - <varname>ExecStop=</varname>, and - <varname>ExecStopPost=</varname> options.</para> - - <para>Multiple command lines may be concatenated in a single - directive by separating them with semicolons (these semicolons - must be passed as separate words). Lone semicolons may be escaped - as <literal>\;</literal>.</para> - - <para>Each command line is split on whitespace, with the first - item being the command to execute, and the subsequent items being - the arguments. Double quotes ("...") and single quotes ('...') may - be used, in which case everything until the next matching quote - becomes part of the same argument. C-style escapes are also - supported. The table below contains the list of allowed escape - patterns. Only patterns which match the syntax in the table are - allowed; others will result in an error, and must be escaped by - doubling the backslash. Quotes themselves are removed after - parsing and escape sequences substituted. In addition, a trailing - backslash (<literal>\</literal>) may be used to merge lines. - </para> - - <para>This syntax is intended to be very similar to shell syntax, - but only the meta-characters and expansions described in the - following paragraphs are understood. Specifically, redirection - using - <literal><</literal>, - <literal><<</literal>, - <literal>></literal>, and - <literal>>></literal>, pipes using - <literal>|</literal>, running programs in the background using - <literal>&</literal>, and <emphasis>other elements of shell - syntax are not supported</emphasis>.</para> - - <para>The command to execute must be an absolute path name. It may - contain spaces, but control characters are not allowed.</para> - - <para>The command line accepts <literal>%</literal> specifiers as - described in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - Note that the first argument of the command line (i.e. the program - to execute) may not include specifiers.</para> - - <para>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 at whitespace, resulting in zero or more arguments. - For this type of expansion, quotes are respected when splitting - into words, and afterwards removed.</para> - - <para>Example:</para> - - <programlisting>Environment="ONE=one" 'TWO=two two' -ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting> - - <para>This will execute <command>/bin/echo</command> with four - arguments: <literal>one</literal>, <literal>two</literal>, - <literal>two</literal>, and <literal>two two</literal>.</para> - - <para>Example:</para> - <programlisting>Environment=ONE='one' "TWO='two two' too" THREE= -ExecStart=/bin/echo ${ONE} ${TWO} ${THREE} -ExecStart=/bin/echo $ONE $TWO $THREE</programlisting> - <para>This results in <filename>echo</filename> being - called twice, the first time with arguments - <literal>'one'</literal>, - <literal>'two two' too</literal>, <literal></literal>, - and the second time with arguments - <literal>one</literal>, <literal>two two</literal>, - <literal>too</literal>. - </para> - - <para>To pass a literal dollar sign, use <literal>$$</literal>. - Variables whose value is not known at expansion time are treated - as empty strings. Note that the first argument (i.e. the program - to execute) may not be a variable.</para> - - <para>Variables to be used in this fashion may be defined through - <varname>Environment=</varname> and - <varname>EnvironmentFile=</varname>. In addition, variables listed - in the section "Environment variables in spawned processes" in - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - which are considered "static configuration", may be used (this - includes e.g. <varname>$USER</varname>, but not - <varname>$TERM</varname>).</para> - - <para>Note that shell command lines are not directly supported. If - shell command lines are to be used, they need to be passed - explicitly to a shell implementation of some kind. Example:</para> - <programlisting>ExecStart=/bin/sh -c 'dmesg | tac'</programlisting> - - <para>Example:</para> - - <programlisting>ExecStart=/bin/echo one ; /bin/echo "two two"</programlisting> - - <para>This will execute <command>/bin/echo</command> two times, - each time with one argument: <literal>one</literal> and - <literal>two two</literal>, respectively. Because two commands are - specified, <varname>Type=oneshot</varname> must be used.</para> - - <para>Example:</para> - - <programlisting>ExecStart=/bin/echo / >/dev/null & \; \ -/bin/ls</programlisting> - - <para>This will execute <command>/bin/echo</command> - with five arguments: <literal>/</literal>, - <literal>>/dev/null</literal>, - <literal>&</literal>, <literal>;</literal>, and - <literal>/bin/ls</literal>.</para> - - <table> - <title>C escapes supported in command lines and environment variables</title> - <tgroup cols='2'> - <colspec colname='escape' /> - <colspec colname='meaning' /> - <thead> - <row> - <entry>Literal</entry> - <entry>Actual value</entry> - </row> - </thead> - <tbody> - <row> - <entry><literal>\a</literal></entry> - <entry>bell</entry> - </row> - <row> - <entry><literal>\b</literal></entry> - <entry>backspace</entry> - </row> - <row> - <entry><literal>\f</literal></entry> - <entry>form feed</entry> - </row> - <row> - <entry><literal>\n</literal></entry> - <entry>newline</entry> - </row> - <row> - <entry><literal>\r</literal></entry> - <entry>carriage return</entry> - </row> - <row> - <entry><literal>\t</literal></entry> - <entry>tab</entry> - </row> - <row> - <entry><literal>\v</literal></entry> - <entry>vertical tab</entry> - </row> - <row> - <entry><literal>\\</literal></entry> - <entry>backslash</entry> - </row> - <row> - <entry><literal>\"</literal></entry> - <entry>double quotation mark</entry> - </row> - <row> - <entry><literal>\'</literal></entry> - <entry>single quotation mark</entry> - </row> - <row> - <entry><literal>\s</literal></entry> - <entry>space</entry> - </row> - <row> - <entry><literal>\x<replaceable>xx</replaceable></literal></entry> - <entry>character number <replaceable>xx</replaceable> in hexadecimal encoding</entry> - </row> - <row> - <entry><literal>\<replaceable>nnn</replaceable></literal></entry> - <entry>character number <replaceable>nnn</replaceable> in octal encoding</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - <title>Examples</title> - - <example> - <title>Simple service</title> - - <para>The following unit file creates a service that will - execute <filename>/usr/sbin/foo-daemon</filename>. Since no - <varname>Type=</varname> is specified, the default - <varname>Type=</varname><option>simple</option> will be assumed. - systemd will assume the unit to be started immediately after the - program has begun executing.</para> - - <programlisting>[Unit] -Description=Foo - -[Service] -ExecStart=/usr/sbin/foo-daemon - -[Install] -WantedBy=multi-user.target</programlisting> - - <para>Note that systemd assumes here that the process started by - systemd will continue running until the service terminates. If - the program daemonizes itself (i.e. forks), please use - <varname>Type=</varname><option>forking</option> instead.</para> - - <para>Since no <varname>ExecStop=</varname> was specified, - systemd will send SIGTERM to all processes started from this - service, and after a timeout also SIGKILL. This behavior can be - modified, see - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details.</para> - - <para>Note that this unit type does not include any type of - notification when a service has completed initialization. For - this, you should use other unit types, such as - <varname>Type=</varname><option>notify</option> if the service - understands systemd's notification protocol, - <varname>Type=</varname><option>forking</option> if the service - can background itself or - <varname>Type=</varname><option>dbus</option> if the unit - acquires a DBus name once initialization is complete. See - below.</para> - </example> - - <example> - <title>Oneshot service</title> - - <para>Sometimes, units should just execute an action without - keeping active processes, such as a filesystem check or a - cleanup action on boot. For this, - <varname>Type=</varname><option>oneshot</option> exists. Units - of this type will wait until the process specified terminates - and then fall back to being inactive. The following unit will - perform a cleanup action:</para> - - <programlisting>[Unit] -Description=Cleanup old Foo data - -[Service] -Type=oneshot -ExecStart=/usr/sbin/foo-cleanup - -[Install] -WantedBy=multi-user.target</programlisting> - - <para>Note that systemd will consider the unit to be in the - state "starting" until the program has terminated, so ordered - dependencies will wait for the program to finish before starting - themselves. The unit will revert to the "inactive" state after - the execution is done, never reaching the "active" state. That - means another request to start the unit will perform the action - again.</para> - - <para><varname>Type=</varname><option>oneshot</option> are the - only service units that may have more than one - <varname>ExecStart=</varname> specified. They will be executed - in order until either they are all successful or one of them - fails.</para> - </example> - - <example> - <title>Stoppable oneshot service</title> - - <para>Similarly to the oneshot services, there are sometimes - units that need to execute a program to set up something and - then execute another to shut it down, but no process remains - active while they are considered "started". Network - configuration can sometimes fall into this category. Another use - case is if a oneshot service shall not be executed each time - when they are pulled in as a dependency, but only the first - time.</para> - - <para>For this, systemd knows the setting - <varname>RemainAfterExit=</varname><option>yes</option>, which - causes systemd to consider the unit to be active if the start - action exited successfully. This directive can be used with all - types, but is most useful with - <varname>Type=</varname><option>oneshot</option> and - <varname>Type=</varname><option>simple</option>. With - <varname>Type=</varname><option>oneshot</option>, systemd waits - until the start action has completed before it considers the - unit to be active, so dependencies start only after the start - action has succeeded. With - <varname>Type=</varname><option>simple</option>, dependencies - will start immediately after the start action has been - dispatched. The following unit provides an example for a simple - static firewall.</para> - - <programlisting>[Unit] -Description=Simple firewall - -[Service] -Type=oneshot -RemainAfterExit=yes -ExecStart=/usr/local/sbin/simple-firewall-start -ExecStop=/usr/local/sbin/simple-firewall-stop - -[Install] -WantedBy=multi-user.target</programlisting> - - <para>Since the unit is considered to be running after the start - action has exited, invoking <command>systemctl start</command> - on that unit again will cause no action to be taken.</para> - </example> - - <example> - <title>Traditional forking services</title> - - <para>Many traditional daemons/services background (i.e. fork, - daemonize) themselves when starting. Set - <varname>Type=</varname><option>forking</option> in the - service's unit file to support this mode of operation. systemd - will consider the service to be in the process of initialization - while the original program is still running. Once it exits - successfully and at least a process remains (and - <varname>RemainAfterExit=</varname><option>no</option>), the - service is considered started.</para> - - <para>Often, a traditional daemon only consists of one process. - Therefore, if only one process is left after the original - process terminates, systemd will consider that process the main - process of the service. In that case, the - <varname>$MAINPID</varname> variable will be available in - <varname>ExecReload=</varname>, <varname>ExecStop=</varname>, - etc.</para> - - <para>In case more than one process remains, systemd will be - unable to determine the main process, so it will not assume - there is one. In that case, <varname>$MAINPID</varname> will not - expand to anything. However, if the process decides to write a - traditional PID file, systemd will be able to read the main PID - from there. Please set <varname>PIDFile=</varname> accordingly. - Note that the daemon should write that file before finishing - with its initialization. Otherwise, systemd might try to read the - file before it exists.</para> - - <para>The following example shows a simple daemon that forks and - just starts one process in the background:</para> - - <programlisting>[Unit] -Description=Some simple daemon - -[Service] -Type=forking -ExecStart=/usr/sbin/my-simple-daemon -d - -[Install] -WantedBy=multi-user.target</programlisting> - - <para>Please see - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details on how you can influence the way systemd terminates - the service.</para> - </example> - - <example> - <title>DBus services</title> - - <para>For services that acquire a name on the DBus system bus, - use <varname>Type=</varname><option>dbus</option> and set - <varname>BusName=</varname> accordingly. The service should not - fork (daemonize). systemd will consider the service to be - initialized once the name has been acquired on the system bus. - The following example shows a typical DBus service:</para> - - <programlisting>[Unit] -Description=Simple DBus service - -[Service] -Type=dbus -BusName=org.example.simple-dbus-service -ExecStart=/usr/sbin/simple-dbus-service - -[Install] -WantedBy=multi-user.target</programlisting> - - <para>For <emphasis>bus-activatable</emphasis> services, do not - include a <literal>[Install]</literal> section in the systemd - service file, but use the <varname>SystemdService=</varname> - option in the corresponding DBus service file, for example - (<filename>/usr/share/dbus-1/system-services/org.example.simple-dbus-service.service</filename>):</para> - - <programlisting>[D-BUS Service] -Name=org.example.simple-dbus-service -Exec=/usr/sbin/simple-dbus-service -User=root -SystemdService=simple-dbus-service.service</programlisting> - - <para>Please see - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details on how you can influence the way systemd terminates - the service.</para> - </example> - - <example> - <title>Services that notify systemd about their initialization</title> - - <para><varname>Type=</varname><option>simple</option> services - are really easy to write, but have the major disadvantage of - systemd not being able to tell when initialization of the given - service is complete. For this reason, systemd supports a simple - notification protocol that allows daemons to make systemd aware - that they are done initializing. Use - <varname>Type=</varname><option>notify</option> for this. A - typical service file for such a daemon would look like - this:</para> - - <programlisting>[Unit] -Description=Simple notifying service - -[Service] -Type=notify -ExecStart=/usr/sbin/simple-notifying-service - -[Install] -WantedBy=multi-user.target</programlisting> - - <para>Note that the daemon has to support systemd's notification - protocol, else systemd will think the service has not started yet - and kill it after a timeout. For an example of how to update - daemons to support this protocol transparently, take a look at - <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - systemd will consider the unit to be in the 'starting' state - until a readiness notification has arrived.</para> - - <para>Please see - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details on how you can influence the way systemd terminates - the service.</para> - </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>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd.slice.xml b/man/systemd.slice.xml deleted file mode 100644 index eee98d99ee..0000000000 --- a/man/systemd.slice.xml +++ /dev/null @@ -1,132 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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 2013 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.slice"> - <refentryinfo> - <title>systemd.slice</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.slice</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd.slice</refname> - <refpurpose>Slice unit configuration</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename><replaceable>slice</replaceable>.slice</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>A unit configuration file whose name ends in - <literal>.slice</literal> encodes information about a slice which - is a concept for hierarchically managing resources of a group of - processes. This management is performed by creating a node in the - Linux Control Group (cgroup) tree. Units that manage processes - (primarily scope and service units) may be assigned to a specific - slice. For each slice, certain resource limits may be set that - apply to all processes of all units contained in that - slice. Slices are organized hierarchically in a tree. The name of - the slice encodes the location in the tree. The name consists of a - dash-separated series of names, which describes the path to the - slice from the root slice. The root slice is named, - <filename>-.slice</filename>. Example: - <filename>foo-bar.slice</filename> is a slice that is located - within <filename>foo.slice</filename>, which in turn is located in - the root slice <filename>-.slice</filename>. - </para> - - <para>Note that slice units cannot be templated, nor is possible to add multiple names to a slice unit by creating - additional symlinks to it.</para> - - <para>By default, service and scope units are placed in - <filename>system.slice</filename>, virtual machines and containers - registered with - <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>1</manvolnum></citerefentry> - are found in <filename>machine.slice</filename>, and user sessions - handled by - <citerefentry><refentrytitle>systemd-logind</refentrytitle><manvolnum>1</manvolnum></citerefentry> - in <filename>user.slice</filename>. See - <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more information.</para> - - <para>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 - slice specific configuration options are configured in - the [Slice] section. Currently, only generic resource control settings - as described in - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> are allowed. - </para> - - <para>See the <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface/">New - Control Group Interfaces</ulink> for an introduction on how to make - use of slice units from programs.</para> - </refsect1> - - <refsect1> - <title>Automatic Dependencies</title> - - <para>Slice units automatically gain dependencies of type - <varname>After=</varname> and <varname>Requires=</varname> on - their immediate parent slice unit.</para> - - <para>Unless <varname>DefaultDependencies=false</varname> is used in the <literal>[Unit]</literal> section, slice - units will implicitly have dependencies of type <varname>Conflicts=</varname> and <varname>Before=</varname> on - <filename>shutdown.target</filename>. These ensure that slice units are removed prior to system shutdown. Only - slice units involved with early boot or late system shutdown should disable this option. - </para> - </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.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd.socket.xml b/man/systemd.socket.xml deleted file mode 100644 index 5bf54d8ef3..0000000000 --- a/man/systemd.socket.xml +++ /dev/null @@ -1,860 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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><replaceable>socket</replaceable>.socket</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>A unit configuration file whose name ends in - <literal>.socket</literal> 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>ExecStopPost=</option> - commands are executed in, and in - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - which define the way the processes are terminated, and in - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - which configure resource control settings for the processes of the - socket.</para> - - <para>For each socket file, a matching service file must exist, - describing the service to start on incoming traffic on the socket - (see - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more information about .service files). The name of the - .service unit is by default the same as the name of the .socket - unit, but can be altered with the <option>Service=</option> option - described below. Depending on the setting of the - <option>Accept=</option> option described below, this .service - unit must either be named like the .socket unit, but with the - suffix replaced, unless overridden with <option>Service=</option>; - or it must be a template unit 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> in the <literal>[Unit]</literal> section 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 will have a <varname>Before=</varname> - dependency on the service which they trigger added implicitly. No - implicit <varname>WantedBy=</varname> or - <varname>RequiredBy=</varname> dependency from the socket to the - service is added. This means that the service may be started - without the socket, in which case it must be able to open sockets - by itself. To prevent this, an explicit - <varname>Requires=</varname> dependency may be added.</para> - - <para>Socket units may be used to implement on-demand starting of - services, as well as parallelized starting of services. See the - blog stories linked at the end for an introduction.</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 project='freebsd'><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry>-style - socket passing (i.e. sockets passed in via standard input and - output, using <varname>StandardInput=socket</varname> in the - service file).</para> - </refsect1> - - <refsect1> - <title>Automatic Dependencies</title> - - <para>Socket units automatically gain a <varname>Before=</varname> - dependency on the service units they activate.</para> - - <para>Socket units referring to file system paths (such as AF_UNIX - sockets or FIFOs) implicitly gain <varname>Requires=</varname> and - <varname>After=</varname> dependencies on all mount units - necessary to access those paths.</para> - - <para>Socket units using the <varname>BindToDevice=</varname> - setting automatically gain a <varname>BindsTo=</varname> and - <varname>After=</varname> dependency on the device unit - encapsulating the specified network interface.</para> - - <para>If <varname>DefaultDependencies=yes</varname> is set (the - default), socket units automatically gain a - <varname>Before=</varname> dependency on - <filename>sockets.target</filename>. They also gain a pair of - <varname>After=</varname> and <varname>Requires=</varname> - dependency on <filename>sysinit.target</filename>, and a pair of - <varname>Before=</varname> and <varname>Conflicts=</varname> - dependencies on <filename>shutdown.target</filename>. These - dependencies ensure that the socket unit is started before normal - services at boot, and is stopped on shutdown.</para> - - <para>Additional implicit dependencies may be added as result of - execution and resource control parameters as documented in - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</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 class='unit-directives'> - <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 - (<constant>SOCK_STREAM</constant>), datagram - (<constant>SOCK_DGRAM</constant>), or sequential packet - (<constant>SOCK_SEQPACKET</constant>) socket, respectively. - The address can be written in various formats:</para> - - <para>If the address starts with a slash - (<literal>/</literal>), it is read as file system socket in - the <constant>AF_UNIX</constant> socket family.</para> - - <para>If the address starts with an at symbol - (<literal>@</literal>), it is read as abstract namespace - socket in the <constant>AF_UNIX</constant> family. The - <literal>@</literal> is replaced with a - <constant>NUL</constant> character before binding. For - details, see - <citerefentry project='man-pages'><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 <constant>SOCK_SEQPACKET</constant> (i.e. - <varname>ListenSequentialPacket=</varname>) is only available - for <constant>AF_UNIX</constant> sockets. - <constant>SOCK_STREAM</constant> (i.e. - <varname>ListenStream=</varname>) when used for IP sockets - refers to TCP sockets, <constant>SOCK_DGRAM</constant> (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 of whether there is incoming traffic - on them or not. If the empty string is assigned to any of - these options, the list of addresses to listen on is reset, - all prior uses of any of these options will have no - effect.</para> - - <para>It is also possible to have more than one socket unit - for the same service when using <varname>Service=</varname>, - and the service will receive all the sockets configured in all - the socket units. Sockets configured in one unit are passed in - the order of configuration, but no ordering between socket - units is specified.</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 of whether it will be up and - running at any point. 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 - <constant>AF_NETLINK</constant> 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>ListenUSBFunction=</varname></term> - <listitem><para>Specifies a <ulink - url="https://www.kernel.org/doc/Documentation/usb/functionfs.txt">USB - FunctionFS</ulink> endpoint location to listen on, for - implementation of USB gadget functions. This expects an - absolute file system path as the argument. Behavior otherwise - is very similar to the <varname>ListenFIFO=</varname> - directive above. Use this to open the FunctionFS endpoint - <filename>ep0</filename>. When using this option, the - activated service has to have the - <varname>USBFunctionDescriptors=</varname> and - <varname>USBFunctionStrings=</varname> options set. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>SocketProtocol=</varname></term> - <listitem><para>Takes a one of <option>udplite</option> - or <option>sctp</option>. Specifies a socket protocol - (<constant>IPPROTO_UDPLITE</constant>) UDP-Lite - (<constant>IPPROTO_SCTP</constant>) SCTP socket respectively. </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 project='die-net'><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 - project='man-pages'><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. Note that setting this parameter might result in - additional dependencies to be added to the unit (see - above).</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>SocketUser=</varname></term> - <term><varname>SocketGroup=</varname></term> - - <listitem><para>Takes a UNIX user/group name. When specified, - all AF_UNIX sockets and FIFO nodes in the file system are - owned by the specified user and group. If unset (the default), - the nodes are owned by the root user/group (if run in system - context) or the invoking user/group (if run in user context). - If only a user is specified but no group, then the group is - derived from the user's default group.</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>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>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>. A daemon listening on an - <constant>AF_UNIX</constant> socket may, but does not need to, - call - <citerefentry><refentrytitle>close</refentrytitle><manvolnum>2</manvolnum></citerefentry> - on the received socket before exiting. However, it must not - unlink the socket from a file system. It should not invoke - <citerefentry><refentrytitle>shutdown</refentrytitle><manvolnum>2</manvolnum></citerefentry> - on sockets it got with <varname>Accept=false</varname>, but it - may do so for sockets it got with - <varname>Accept=true</varname> set. Setting - <varname>Accept=true</varname> is mostly useful to allow - daemons designed for usage with - <citerefentry project='freebsd'><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry> - to work unmodified with systemd socket - activation.</para> - - <para>For IPv4 and IPv6 connections, the <varname>REMOTE_ADDR</varname> - environment variable will contain the remote IP address, and <varname>REMOTE_PORT</varname> - will contain the remote port. This is the same as the format used by CGI. - For SOCK_RAW, the port is the IP protocol.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Writable=</varname></term> - <listitem><para>Takes a boolean argument. May only be used in - conjunction with <varname>ListenSpecial=</varname>. If true, - the specified special file is opened in read-write mode, if - false, in read-only mode. Defaults to false.</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 on 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 project='man-pages'><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>KeepAliveTimeSec=</varname></term> - <listitem><para>Takes time (in seconds) as argument. The connection needs to remain - idle before TCP starts sending keepalive probes. This controls the TCP_KEEPIDLE - socket option (see - <citerefentry project='man-pages'><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 value is 7200 seconds (2 hours).</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>KeepAliveIntervalSec=</varname></term> - <listitem><para>Takes time (in seconds) as argument between - individual keepalive probes, if the socket option SO_KEEPALIVE - has been set on this socket. This controls - the TCP_KEEPINTVL socket option (see - <citerefentry project='man-pages'><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 value is 75 - seconds.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>KeepAliveProbes=</varname></term> - <listitem><para>Takes an integer as argument. It is the number of - unacknowledged probes to send before considering the - connection dead and notifying the application layer. This - controls the TCP_KEEPCNT socket option (see - <citerefentry project='man-pages'><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 value is - 9.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>NoDelay=</varname></term> - <listitem><para>Takes a boolean argument. TCP Nagle's - algorithm works by combining a number of small outgoing - messages, and sending them all at once. This controls the - TCP_NODELAY socket option (see - <citerefentry project='die-net'><refentrytitle>tcp</refentrytitle><manvolnum>7</manvolnum></citerefentry> - 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 project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for details.).</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>DeferAcceptSec=</varname></term> - - <listitem><para>Takes time (in seconds) as argument. If set, - the listening process will be awakened only when data arrives - on the socket, and not immediately when connection is - established. When this option is set, the - <constant>TCP_DEFER_ACCEPT</constant> socket option will be - used (see - <citerefentry project='die-net'><refentrytitle>tcp</refentrytitle><manvolnum>7</manvolnum></citerefentry>), - and the kernel will ignore initial ACK packets without any - data. The argument specifies the approximate amount of time - the kernel should wait for incoming data before falling back - to the normal behavior of honouring empty ACK packets. This - option is beneficial for protocols where the client sends the - data first (e.g. HTTP, in contrast to SMTP), because the - server process will not be woken up unnecessarily before it - can take any action. - </para> - - <para>If the client also uses the - <constant>TCP_DEFER_ACCEPT</constant> option, the latency of - the initial connection may be reduced, because the kernel will - send data in the final packet establishing the connection (the - third packet in the "three-way handshake").</para> - - <para>Disabled by default.</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 project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for details.). The usual suffixes K, M, G are supported and - are understood to the base of 1024.</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 project='die-net'><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 project='die-net'><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry> - and - <citerefentry project='die-net'><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 project='die-net'><refentrytitle>iptables</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for details.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>ReusePort=</varname></term> - <listitem><para>Takes a boolean value. If true, allows - multiple - <citerefentry><refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum></citerefentry>s - to this TCP or UDP port. This controls the SO_REUSEPORT socket - option. See - <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</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>SELinuxContextFromNet=</varname></term> - <listitem><para>Takes a boolean argument. When true, systemd - will attempt to figure out the SELinux label used for the - instantiated service from the information handed by the peer - over the network. Note that only the security level is used - from the information provided by the peer. Other parts of the - resulting SELinux context originate from either the target - binary that is effectively triggered by socket unit or from - the value of the <varname>SELinuxContext=</varname> option. - This configuration option only affects sockets with - <varname>Accept=</varname> mode set to - <literal>true</literal>. Also note that this option is useful - only when MLS/MCS SELinux policy is deployed. Defaults to - <literal>false</literal>. </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>PipeSize=</varname></term> - <listitem><para>Takes a size in bytes. Controls the pipe - buffer size of FIFOs configured in this socket unit. See - <citerefentry><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for details. The usual suffixes K, M, G are supported and are - understood to the base of 1024.</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 project='die-net'><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 - <constant>AF_UNIX</constant> 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 - <constant>AF_UNIX</constant> 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 filename, 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 - <constant>SIGTERM</constant>, and after another delay of this - time with <constant>SIGKILL</constant>. (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 <literal>0</literal> to disable the - timeout logic. Defaults to - <varname>DefaultTimeoutStartSec=</varname> from the manager - configuration file (see - <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>). - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Service=</varname></term> - <listitem><para>Specifies the service unit name to activate on - incoming traffic. This setting is only allowed for sockets - with <varname>Accept=no</varname>. It defaults to the service - that bears the same name as the socket (with the suffix - replaced). In most cases, it should not be necessary to use - this option. Note that setting this parameter might result in - additional dependencies to be added to the unit (see - above).</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>RemoveOnStop=</varname></term> - <listitem><para>Takes a boolean argument. If enabled, any file - nodes created by this socket unit are removed when it is - stopped. This applies to AF_UNIX sockets in the file system, - POSIX message queues, FIFOs, as well as any symlinks to them - configured with <varname>Symlinks=</varname>. Normally, it - should not be necessary to use this option, and is not - recommended as services might continue to run after the socket - unit has been terminated and it should still be possible to - communicate with them via their file system node. Defaults to - off.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Symlinks=</varname></term> - <listitem><para>Takes a list of file system paths. The - specified paths will be created as symlinks to the AF_UNIX - socket path or FIFO path of this socket unit. If this setting - is used, only one AF_UNIX socket in the file system or one - FIFO may be configured for the socket unit. Use this option to - manage one or more symlinked alias names for a socket, binding - their lifecycle together. Defaults to the empty - list.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>FileDescriptorName=</varname></term> - <listitem><para>Assigns a name to all file descriptors this - socket unit encapsulates. This is useful to help activated - services identify specific file descriptors, if multiple fds - are passed. Services may use the - <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call to acquire the names configured for the received file - descriptors. Names may contain any ASCII character, but must - exclude control characters and <literal>:</literal>, and must - be at most 255 characters in length. If this setting is not - used, the file descriptor name defaults to the name of the - socket unit, including its <filename>.socket</filename> - suffix.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>TriggerLimitIntervalSec=</varname></term> - <term><varname>TriggerLimitBurst=</varname></term> - - <listitem><para>Configures a limit on how often this socket unit my be activated within a specific time - interval. The <varname>TriggerLimitIntervalSec=</varname> may be used to configure the length of the time - interval in the usual time units <literal>us</literal>, <literal>ms</literal>, <literal>s</literal>, - <literal>min</literal>, <literal>h</literal>, … and defaults to 2s (See - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details on - the various time units understood). The <varname>TriggerLimitBurst=</varname> setting takes a positive integer - value and specifies the number of permitted activations per time interval, and defaults to 200 for - <varname>Accept=yes</varname> sockets (thus by default permitting 200 activations per 2s), and 20 otherwise (20 - activations per 2s). Set either to 0 to disable any form of trigger rate limiting. If the limit is hit, the - socket unit is placed into a failure mode, and will not be connectible anymore until restarted. Note that this - limit is enforced before the service activation is enqueued.</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>1</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.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - <para> - For more extensive descriptions see the "systemd for Developers" series: - <ulink url="http://0pointer.de/blog/projects/socket-activation.html">Socket Activation</ulink>, - <ulink url="http://0pointer.de/blog/projects/socket-activation2.html">Socket Activation, part II</ulink>, - <ulink url="http://0pointer.de/blog/projects/inetd.html">Converting inetd Services</ulink>, - <ulink url="http://0pointer.de/blog/projects/socket-activated-containers.html">Socket Activated Internet Services and OS Containers</ulink>. - </para> - </refsect1> - -</refentry> diff --git a/man/systemd.special.xml b/man/systemd.special.xml deleted file mode 100644 index 26974ed73f..0000000000 --- a/man/systemd.special.xml +++ /dev/null @@ -1,935 +0,0 @@ -<?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>cryptsetup-pre.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>initrd-fs.target</filename>, - <filename>kbrequest.target</filename>, - <filename>kexec.target</filename>, - <filename>local-fs.target</filename>, - <filename>local-fs-pre.target</filename>, - <filename>multi-user.target</filename>, - <filename>network.target</filename>, - <filename>network-online.target</filename>, - <filename>network-pre.target</filename>, - <filename>nss-lookup.target</filename>, - <filename>nss-user-lookup.target</filename>, - <filename>paths.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>initrd-root-device.target</filename>, - <filename>initrd-root-fs.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>slices.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>system-update.target</filename>, - <filename>time-sync.target</filename>, - <filename>timers.target</filename>, - <filename>umount.target</filename>, - <filename>-.slice</filename>, - <filename>system.slice</filename>, - <filename>user.slice</filename>, - <filename>machine.slice</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 basic boot-up.</para> - - <para>systemd automatically adds dependencies of the types - <varname>Requires=</varname> and <varname>After=</varname> - for this target unit to all services (except for those with - <varname>DefaultDependencies=no</varname>).</para> - - <para>Usually, this should pull-in all local mount points plus - <filename>/var</filename>, <filename>/tmp</filename> and - <filename>/var/tmp</filename>, swap devices, sockets, timers, - path units and other basic initialization necessary for general - purpose daemons. The mentioned mount points are special cased - to allow them to be remote. - </para> - - <para>This target usually does not pull in any non-target units - directly, but rather does so indirectly via other early boot targets. - It is instead meant as a synchronization point for late boot - services. Refer to - <citerefentry><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for details on the targets involved. - </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 bus daemon. 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 <varname>Type=dbus</varname> 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> - </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 target does not pull in - any services or mounts. It is the most minimal version of starting the system in order to acquire an - interactive shell; the only processes running are usually just the system manager (PID 1) and the shell - process. This unit is supposed to be used with the kernel command line option - <varname>systemd.unit=</varname>; it is also used when a file system check on a required file system fails, - and boot-up cannot continue. Compare with <filename>rescue.target</filename>, which serves a similar purpose, - but also starts the most basic services and mounts all file systems.</para> - - <para>Use the <literal>systemd.unit=emergency.target</literal> kernel command line option to boot into this - mode. A short alias for this kernel command line option is <literal>emergency</literal>, for compatibility - with SysV.</para> - - <para>In many ways booting into <filename>emergency.target</filename> is similar to the effect of booting - with <literal>init=/bin/sh</literal> on the kernel command line, except that emergency mode provides you with - the full system and service manager, and allows starting individual units in order to continue the boot - process in steps.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>exit.target</filename></term> - <listitem> - <para>A special service unit for shutting down the system or - user service manager. It is equivalent to - <filename>poweroff.target</filename> on non-container - systems, and also works in containers.</para> - - <para>systemd will start this unit when it receives a - request to shut down over D-Bus or a - <constant>SIGTERM</constant> or <constant>SIGINT</constant> - signal when running as user service daemon.</para> - - <para>Normally, this (indirectly) pulls in - <filename>shutdown.target</filename>, which in turn should be - conflicted by all units that want to be scheduled for - shutdown when the service manager starts to exit.</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 statically - configured 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 logins shall add - <varname>Wants=</varname> dependencies for their unit to - this unit (or <filename>multi-user.target</filename>) during - installation. This is best configured via - <varname>WantedBy=graphical.target</varname> in the unit's - <literal>[Install]</literal> section.</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. Note that this target is distinct from - <filename>poweroff.target</filename> in that it generally - really just halts the system rather than powering it - down.</para> - - <para>Applications wanting to halt the system should start - this unit.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>initrd-fs.target</filename></term> - <listitem> - <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry> - automatically adds dependencies of type - <varname>Before=</varname> to - <filename>sysroot-usr.mount</filename> and all mount points - found in <filename>/etc/fstab</filename> that have - <option>x-initrd.mount</option> and not have - <option>noauto</option> mount options set.</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><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry> - automatically adds dependencies of type - <varname>Before=</varname> to all mount units that refer to - local mount points for this target unit. In addition, it - adds dependencies of type <varname>Wants=</varname> to this - target unit for those mounts listed in - <filename>/etc/fstab</filename> that have the - <option>auto</option> mount option set.</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 <varname>Wants=</varname> dependencies for their unit to - this unit during installation. This is best configured via - <varname>WantedBy=multi-user.target</varname> in the unit's - <literal>[Install]</literal> section.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>network-online.target</filename></term> - <listitem> - <para>Units that strictly require a configured network - connection should pull in - <filename>network-online.target</filename> (via a - <varname>Wants=</varname> type dependency) and order - themselves after it. This target unit is intended to pull in - a service that delays further execution until the network is - sufficiently set up. What precisely this requires is left to - the implementation of the network managing service.</para> - - <para>Note the distinction between this unit and - <filename>network.target</filename>. This unit is an active - unit (i.e. pulled in by the consumer rather than the - provider of this functionality) and pulls in a service which - possibly adds substantial delays to further execution. In - contrast, <filename>network.target</filename> is a passive - unit (i.e. pulled in by the provider of the functionality, - rather than the consumer) that usually does not delay - execution much. Usually, <filename>network.target</filename> - is part of the boot of most systems, while - <filename>network-online.target</filename> is not, except - when at least one unit requires it. Also see <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/NetworkTarget">Running - Services After the Network is up</ulink> for more - information.</para> - - <para>All mount units for remote network file systems - automatically pull in this unit, and order themselves after - it. Note that networking daemons that simply provide - functionality to other hosts generally do not need to pull - this in.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>paths.target</filename></term> - <listitem> - <para>A special target unit that sets up all path units (see - <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details) that shall be active after boot.</para> - - <para>It is recommended that path units installed by - applications get pulled in via <varname>Wants=</varname> - dependencies from this unit. This is best configured via a - <varname>WantedBy=paths.target</varname> in the path unit's - <literal>[Install]</literal> section.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>poweroff.target</filename></term> - <listitem> - <para>A special target unit for shutting down and powering - off the system.</para> - - <para>Applications wanting to power off the system should - start this unit.</para> - - <para><filename>runlevel0.target</filename> is an alias for - this target unit, for compatibility with SysV.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>reboot.target</filename></term> - <listitem> - <para>A special target unit for shutting down and rebooting - the system.</para> - - <para>Applications wanting to reboot the system should start - this unit.</para> - - <para><filename>runlevel6.target</filename> is an alias for - this target unit, for compatibility with SysV.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>remote-fs.target</filename></term> - <listitem> - <para>Similar to <filename>local-fs.target</filename>, but - for remote mount points.</para> - - <para>systemd automatically adds dependencies of type - <varname>After=</varname> 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>rescue.target</filename></term> - <listitem> - <para>A special target unit that pulls in the base system (including system mounts) and spawns a rescue - shell. Isolate to this target in order to administer the system in single-user mode with all file systems - mounted but with no services running, except for the most basic. Compare with - <filename>emergency.target</filename>, which is much more reduced and does not provide the file systems or - most basic services.</para> - - <para><filename>runlevel1.target</filename> is an alias for this target unit, for compatibility with - SysV.</para> - - <para>Use the <literal>systemd.unit=rescue.target</literal> kernel command line option to boot into this - mode. A short alias for this kernel command line option is <literal>1</literal>, for compatibility with - SysV.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>initrd-root-device.target</filename></term> - <listitem> - <para>A special initrd target unit that is reached when the root filesystem device is available, but before - it has been mounted. - <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry> - automatically setup the appropiate dependencies to make this happen. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>initrd-root-fs.target</filename></term> - <listitem> - <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry> - automatically adds dependencies of type - <varname>Before=</varname> to the - <filename>sysroot.mount</filename> unit, which is generated - from the kernel command line. - </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 <varname>Conflicts=</varname> dependencies to this - unit for their service unit, which is implicitly done when - <varname>DefaultDependencies=yes</varname> is set (the - default).</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>slices.target</filename></term> - <listitem> - <para>A special target unit that sets up all slice units (see - <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry> for - details) that shall be active after boot. By default the generic <filename>user.slice</filename>, - <filename>system.slice</filename>, <filename>machines.slice</filename> slice units, as well as the root - slice unit <filename>-.slice</filename> are pulled in and ordered before this unit (see below).</para> - - <para>It's a good idea to add <varname>WantedBy=slices.target</varname> lines to the <literal>[Install]</literal> - section of all slices units that may be installed dynamically.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>sockets.target</filename></term> - <listitem> - <para>A special target unit that sets up all socket - units (see - <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details) that shall be active after boot.</para> - - <para>Services that can be socket-activated shall add - <varname>Wants=</varname> dependencies to this unit for - their socket unit during installation. This is best - configured via a <varname>WantedBy=sockets.target</varname> - in the socket unit's <literal>[Install]</literal> - section.</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>This target pulls in the services required for system - initialization. System services pulled in by this target should - declare <varname>DefaultDependencies=no</varname> and specify - all their dependencies manually, including access to anything - more than a read only root filesystem. For details on the - dependencies of this target, refer to - <citerefentry><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry>. - </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>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>timers.target</filename></term> - <listitem> - <para>A special target unit that sets up all timer units - (see - <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details) that shall be active after boot.</para> - - <para>It is recommended that timer units installed by - applications get pulled in via <varname>Wants=</varname> - dependencies from this unit. This is best configured via - <varname>WantedBy=timers.target</varname> in the timer - unit's <literal>[Install]</literal> section.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>umount.target</filename></term> - <listitem> - <para>A special target unit that unmounts 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 System Units for Devices</title> - - <para>Some target units are automatically pulled in as devices of - certain kinds show up in the system. These may be used to - automatically activate various services based on the specific type - of the available hardware.</para> - - <variablelist> - <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> - - <para>This may be used to pull in Bluetooth management - daemons dynamically when Bluetooth hardware is found.</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> - - <para>This may be used to pull in printer management daemons - dynamically when printer hardware is found.</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> - - <para>This may be used to pull in smartcard management - daemons dynamically when smartcard hardware is found.</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> - - <para>This may be used to pull in audio management daemons - dynamically when audio hardware is found.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Special Passive System Units </title> - - <para>A number of special system targets are defined that can be - used to properly order boot-up of optional services. These targets - are generally not part of the initial boot transaction, unless - they are explicitly pulled in by one of the implementing services. - Note specifically that these <emphasis>passive</emphasis> target - units are generally not pulled in by the consumer of a service, - but by the provider of the service. This means: a consuming - service should order itself after these targets (as appropriate), - but not pull it in. A providing service should order itself before - these targets (as appropriate) and pull it in (via a - <varname>Wants=</varname> type dependency).</para> - - <para>Note that these passive units cannot be started manually, - i.e. <literal>systemctl start time-sync.target</literal> will fail - with an error. They can only be pulled in by dependency. This is - enforced since they exist for ordering purposes only and thus are - not useful as only unit within a transaction.</para> - - <variablelist> - <varlistentry> - <term><filename>cryptsetup-pre.target</filename></term> - <listitem> - <para>This passive target unit may be pulled in by services - that want to run before any encrypted block device is set - up. All encrypted block devices are set up after this target - has been reached. Since the shutdown order is implicitly the - reverse start-up order between units, this target is - particularly useful to ensure that a service is shut down - only after all encrypted block devices are fully - stopped.</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>network.target</filename></term> - <listitem> - <para>This unit is supposed to indicate when network - functionality is available, but it is only very weakly - defined what that is supposed to mean, with one exception: - at shutdown, a unit that is ordered after - <filename>network.target</filename> will be stopped before - the network — to whatever level it might be set up then — - is shut down. It is hence useful when writing service files - that require network access on shutdown, which should order - themselves after this target, but not pull it in. Also see - <ulink url="http://www.freedesktop.org/wiki/Software/systemd/NetworkTarget">Running - Services After the Network is up</ulink> for more - information. Also see - <filename>network-online.target</filename> described - above.</para> - - <para>systemd automatically adds dependencies of type - <varname>After=</varname> 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>network-pre.target</filename></term> - <listitem> - <para>This passive target unit may be pulled in by services - that want to run before any network is set up, for example - for the purpose of setting up a firewall. All network - management software orders itself after this target, but - does not pull it in.</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. - All services for which the availability of full host/network - name resolution is essential should be ordered after this - target, but not pull it in. systemd automatically adds - dependencies of type <varname>After=</varname> 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. All - services for which the availability of the full user/group - database is essential should be ordered after this target, - but not pull it in. Note that system users are always - resolvable, and hence do not require any special ordering - against this target.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>remote-fs-pre.target</filename></term> - <listitem> - <para>This target unit is automatically ordered before all - remote mount point units (see above). It can be used to run - certain units before the remote mounts are established. Note - that this unit is generally not part of the initial - transaction, unless the unit that wants to be ordered before - all remote mounts pulls it in via a - <varname>Wants=</varname> type dependency. If the unit wants - to be pulled in by the first remote mount showing up, it - should use <filename>network-online.target</filename> (see - above).</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>rpcbind.target</filename></term> - <listitem> - <para>The portmapper/rpcbind pulls in this target and orders - itself before it, to indicate its availability. systemd - automatically adds dependencies of type - <varname>After=</varname> 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>time-sync.target</filename></term> - <listitem> - <para>Services responsible for synchronizing the system - clock from a remote source (such as NTP client - implementations) should pull in this target and order - themselves before it. All services where correct time is - essential should be ordered after this unit, but not pull it - in. systemd automatically adds dependencies of type - <varname>After=</varname> 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> - </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>exit.target</filename>, - <filename>default.target</filename>, - <filename>shutdown.target</filename>, - <filename>sockets.target</filename>, - <filename>timers.target</filename>, - <filename>paths.target</filename>, - <filename>bluetooth.target</filename>, - <filename>printer.target</filename>, - <filename>smartcard.target</filename>, - <filename>sound.target</filename>.</para> - </refsect1> - - <refsect1> - <title>Special Slice Units</title> - - <para>There are four <literal>.slice</literal> units which form - the basis of the hierarchy for assignment of resources for - services, users, and virtual machines or containers.</para> - - <variablelist> - <varlistentry> - <term><filename>-.slice</filename></term> - <listitem> - <para>The root slice is the root of the hierarchy. It - usually does not contain units directly, but may be used to - set defaults for the whole tree.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>system.slice</filename></term> - <listitem> - <para>By default, all system services started by - <command>systemd</command> are found in this slice.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>user.slice</filename></term> - <listitem> - <para>By default, all user processes and services started on - behalf of the user, including the per-user systemd instance - are found in this slice.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>machine.slice</filename></term> - <listitem> - <para>By default, all virtual machines and containers - registered with <command>systemd-machined</command> are - found in this slice. - </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>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd.swap.xml b/man/systemd.swap.xml deleted file mode 100644 index cf4e1ba839..0000000000 --- a/man/systemd.swap.xml +++ /dev/null @@ -1,250 +0,0 @@ -<?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.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><replaceable>swap</replaceable>.swap</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>A unit configuration file whose name ends in - <literal>.swap</literal> 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 - project='man-pages'><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry> - binary is executed in, in - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - which define the way these processes are - terminated, and in - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - which configure resource control settings for these processes of the - unit.</para> - - <para>Swap units must be named after the devices or files they control. Example: the swap device <filename - noindex='true'>/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>. Note that swap - units cannot be templated, nor is possible to add multiple names to a swap unit by creating additional symlinks to - it.</para> - </refsect1> - - <refsect1> - <title>Automatic Dependencies</title> - - <para>All swap units automatically get the - <varname>BindsTo=</varname> and <varname>After=</varname> - dependencies on the device units or the mount units of the files - they are activated from.</para> - - <para>Swap units with <varname>DefaultDependencies=</varname> in the <literal>[Unit]</literal> section enabled - implicitly acquire a <varname>Conflicts=</varname> and an <varname>After=</varname> dependency on - <filename>umount.target</filename> so that they are deactivated at shutdown, unless - <varname>DefaultDependencies=no</varname> is specified.</para> - - <para>Additional implicit dependencies may be added as result of - execution and resource control parameters as documented in - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</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 project='man-pages'><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>When reading <filename>/etc/fstab</filename>, a few special - options are understood by systemd which influence how dependencies - are created for swap units.</para> - - <variablelist class='fstab-options'> - <varlistentry> - <term><option>noauto</option></term> - <term><option>auto</option></term> - - <listitem><para>With <option>noauto</option>, the swap unit - will not be added as a dependency for - <filename>swap.target</filename>. This means that it will not - be activated automatically during boot, unless it is pulled in - by some other unit. The <option>auto</option> option has the - opposite meaning and is the default.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>nofail</option></term> - - <listitem><para>With <option>nofail</option>, the swap unit - will be only wanted, not required by - <filename>swap.target</filename>. This means that the boot - will continue even if this swap device is not activated - successfully.</para> - </listitem> - </varlistentry> - </variablelist> - </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 class='unit-directives'> - - <varlistentry> - <term><varname>What=</varname></term> - <listitem><para>Takes an absolute path of a device node or - file to use for paging. See - <citerefentry project='man-pages'><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 and ignored when the priority is set by <option>pri=</option> in the - <varname>Options=</varname> key.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Options=</varname></term> - - <listitem><para>May contain an option string for the swap - device. This may be used for controlling discard options among - other functionality, if the swap backing device supports the - discard or trim operation. (See - <citerefentry project='man-pages'><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for more information.) </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 <constant>SIGTERM</constant>, and after another - delay of this time with <constant>SIGKILL</constant>. (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 <literal>0</literal> to disable the - timeout logic. Defaults to - <varname>DefaultTimeoutStartSec=</varname> from the manager - configuration file (see - <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>). - </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>1</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.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd.target.xml b/man/systemd.target.xml deleted file mode 100644 index ab910d75dd..0000000000 --- a/man/systemd.target.xml +++ /dev/null @@ -1,103 +0,0 @@ -<?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.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><replaceable>target</replaceable>.target</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>A unit configuration file whose name ends in - <literal>.target</literal> 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> - </refsect1> - - <refsect1> - <title>Automatic Dependencies</title> - - <para>Unless <varname>DefaultDependencies=</varname> in the <literal>[Unit]</literal> section is set to - <option>no</option>, target units will implicitly complement all configured dependencies of type - <varname>Wants=</varname>, <varname>Requires=</varname> with dependencies of type <varname>After=</varname>, unless - an ordering dependency of any kind between the target and the respective other unit is already in place. Note that - this behaviour is disabled if either unit has <varname>DefaultDependencies=no</varname>.</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.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd.time.xml b/man/systemd.time.xml deleted file mode 100644 index ffcac82263..0000000000 --- a/man/systemd.time.xml +++ /dev/null @@ -1,313 +0,0 @@ -<?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.time"> - - <refentryinfo> - <title>systemd.time</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.time</refentrytitle> - <manvolnum>7</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd.time</refname> - <refpurpose>Time and date specifications</refpurpose> - </refnamediv> - - <refsect1> - <title>Description</title> - - <para>In systemd, timestamps, time spans, and calendar events are - displayed and may be specified in closely related syntaxes.</para> - </refsect1> - - <refsect1> - <title>Displaying Time Spans</title> - - <para>Time spans refer to time durations. On display, systemd will - present time spans as a space-separated series of time values each - suffixed by a time unit.</para> - - <programlisting>2h 30min</programlisting> - - <para>All specified time values are meant to be added up. The - above hence refers to 150 minutes.</para> - </refsect1> - - <refsect1> - <title>Parsing Time Spans</title> - - <para>When parsing, systemd will accept the same time span syntax. - Separating spaces may be omitted. The following time units are - understood:</para> - - <itemizedlist> - <listitem><para>usec, us</para></listitem> - <listitem><para>msec, ms</para></listitem> - <listitem><para>seconds, second, sec, s</para></listitem> - <listitem><para>minutes, minute, min, m</para></listitem> - <listitem><para>hours, hour, hr, h</para></listitem> - <listitem><para>days, day, d</para></listitem> - <listitem><para>weeks, week, w</para></listitem> - <listitem><para>months, month, M (defined as 30.44 days)</para></listitem> - <listitem><para>years, year, y (define as 365.25 days)</para></listitem> - </itemizedlist> - - <para>If no time unit is specified, generally seconds are assumed, - but some exceptions exist and are marked as such. In a few cases - <literal>ns</literal>, <literal>nsec</literal> is accepted too, - where the granularity of the time span allows for this.</para> - - <para>Examples for valid time span specifications:</para> - - <programlisting>2 h -2hours -48hr -1y 12month -55s500ms -300ms20s 5day</programlisting> - </refsect1> - - <refsect1> - <title>Displaying Timestamps</title> - - <para>Timestamps refer to specific, unique points in time. On - display, systemd will format these in the local timezone as - follows:</para> - - <programlisting>Fri 2012-11-23 23:02:15 CET</programlisting> - - <para>The weekday is printed according to the locale choice of the - user.</para> - </refsect1> - - <refsect1> - <title>Parsing Timestamps</title> - - <para>When parsing, systemd will accept a similar syntax, but - expects no timezone specification, unless it is given as the - literal string "UTC". In this case, the time is considered in UTC, - otherwise in the local timezone. The weekday specification is - optional, but when the weekday is specified, it must either be in - the abbreviated (<literal>Wed</literal>) or non-abbreviated - (<literal>Wednesday</literal>) English language form (case does - not matter), and is not subject to the locale choice of the user. - Either the date, or the time part may be omitted, in which case - the current date or 00:00:00, respectively, is assumed. The seconds - component of the time may also be omitted, in which case ":00" is - assumed. Year numbers may be specified in full or may be - abbreviated (omitting the century).</para> - - <para>A timestamp is considered invalid if a weekday is specified - and the date does not actually match the specified day of the - week.</para> - - <para>When parsing, systemd will also accept a few special - placeholders instead of timestamps: <literal>now</literal> may be - used to refer to the current time (or of the invocation of the - command that is currently executed). <literal>today</literal>, - <literal>yesterday</literal>, and <literal>tomorrow</literal> refer to - 00:00:00 of the current day, the day before, or the next day, - respectively.</para> - - <para>When parsing, systemd will also accept relative time - specifications. A time span (see above) that is prefixed with - <literal>+</literal> is evaluated to the current time plus the - specified time span. Correspondingly, a time span that is prefixed - with <literal>-</literal> is evaluated to the current time minus - the specified time span. Instead of prefixing the time span with - <literal>+</literal> or <literal>-</literal>, it may also be - suffixed with a space and the word <literal>left</literal> or - <literal>ago</literal>.</para> - - <para>Finally, a timespan prefixed with <literal>@</literal> is - evaluated relative to the UNIX time epoch 1st Jan, 1970, - 00:00.</para> - - <para>Examples for valid timestamps and their normalized form - (assuming the current time was 2012-11-23 18:15:22 and the timezone - was UTC+8, for example TZ=Asia/Shanghai):</para> - - <programlisting>Fri 2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13 - 2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13 -2012-11-23 11:12:13 UTC → Fri 2012-11-23 19:12:13 - 2012-11-23 → Fri 2012-11-23 00:00:00 - 12-11-23 → Fri 2012-11-23 00:00:00 - 11:12:13 → Fri 2012-11-23 11:12:13 - 11:12:13.9900009 → Fri 2012-11-23 11:12:13 - format_timestamp_us: Fri 2012-11-23 11:12:13.990000 - 11:12 → Fri 2012-11-23 11:12:00 - now → Fri 2012-11-23 18:15:22 - today → Fri 2012-11-23 00:00:00 - today UTC → Fri 2012-11-23 16:00:00 - yesterday → Fri 2012-11-22 00:00:00 - tomorrow → Fri 2012-11-24 00:00:00 - +3h30min → Fri 2012-11-23 21:45:22 - +3h30min UTC → -EINVAL - -5s → Fri 2012-11-23 18:15:17 - 11min ago → Fri 2012-11-23 18:04:22 - 11min ago UTC → -EINVAL - @1395716396 → Tue 2014-03-25 03:59:56</programlisting> - - <para>Note that timestamps printed by systemd will not be parsed - correctly by systemd, as the timezone specification is not - accepted, and printing timestamps is subject to locale settings - for the weekday, while parsing only accepts English weekday - names.</para> - - <para>In some cases, systemd will display a relative timestamp - (relative to the current time, or the time of invocation of the - command) instead or in addition to an absolute timestamp as - described above. A relative timestamp is formatted as - follows:</para> - - <para>2 months 5 days ago</para> - - <para>Note that any relative timestamp will also parse correctly - where a timestamp is expected. (see above)</para> - </refsect1> - - <refsect1> - <title>Calendar Events</title> - - <para>Calendar events may be used to refer to one or more points - in time in a single expression. They form a superset of the - absolute timestamps explained above:</para> - - <programlisting>Thu,Fri 2012-*-1,5 11:12:13</programlisting> - - <para>The above refers to 11:12:13 of the first or fifth day of - any month of the year 2012, but only if that day is a Thursday or - Friday.</para> - - <para>The weekday specification is optional. If specified, it - should consist of one or more English language weekday names, - either in the abbreviated (Wed) or non-abbreviated (Wednesday) - form (case does not matter), separated by commas. Specifying two - weekdays separated by <literal>-</literal> refers to a range of - continuous weekdays. <literal>,</literal> and <literal>-</literal> - may be combined freely.</para> - - <para>In the date and time specifications, any component may be - specified as <literal>*</literal> in which case any value will - match. Alternatively, each component can be specified as a list of - values separated by commas. Values may also be suffixed with - <literal>/</literal> and a repetition value, which indicates that - the value and all values plus multiples of the repetition value - are matched.</para> - - <para>The seconds component may contain decimal fractions both in - the value and the repetition. All fractions are rounded to 6 - decimal places.</para> - - <para>Either time or date specification may be omitted, in which - case the current day and 00:00:00 is implied, respectively. If the - second component is not specified, <literal>:00</literal> is - assumed.</para> - - <para>A timezone specification is not expected, unless it is given - as the literal string "UTC", similarly to timestamps.</para> - - <para>The special expressions - <literal>minutely</literal>, - <literal>hourly</literal>, <literal>daily</literal>, - <literal>monthly</literal>, <literal>weekly</literal>, - <literal>yearly</literal>, - <literal>quarterly</literal>, - <literal>semiannually</literal> may be used as - calendar events which refer to - <literal>*-*-* *:*:00</literal>, - <literal>*-*-* *:00:00</literal>, - <literal>*-*-* 00:00:00</literal>, - <literal>*-*-01 00:00:00</literal>, - <literal>Mon *-*-* 00:00:00</literal>, - <literal>*-01-01 00:00:00</literal>, - <literal>*-01,04,07,10-01 00:00:00</literal> and - <literal>*-01,07-01 00:00:00</literal>, respectively. - </para> - - <para>Examples for valid timestamps and their - normalized form:</para> - -<programlisting> Sat,Thu,Mon-Wed,Sat-Sun → Mon-Thu,Sat,Sun *-*-* 00:00:00 - Mon,Sun 12-*-* 2,1:23 → Mon,Sun 2012-*-* 01,02:23:00 - Wed *-1 → Wed *-*-01 00:00:00 - Wed-Wed,Wed *-1 → Wed *-*-01 00:00:00 - Wed, 17:48 → Wed *-*-* 17:48:00 -Wed-Sat,Tue 12-10-15 1:2:3 → Tue-Sat 2012-10-15 01:02:03 - *-*-7 0:0:0 → *-*-07 00:00:00 - 10-15 → *-10-15 00:00:00 - monday *-12-* 17:00 → Mon *-12-* 17:00:00 - Mon,Fri *-*-3,1,2 *:30:45 → Mon,Fri *-*-01,02,03 *:30:45 - 12,14,13,12:20,10,30 → *-*-* 12,13,14:10,20,30:00 - mon,fri *-1/2-1,3 *:30:45 → Mon,Fri *-01/2-01,03 *:30:45 - 03-05 08:05:40 → *-03-05 08:05:40 - 08:05:40 → *-*-* 08:05:40 - 05:40 → *-*-* 05:40:00 - Sat,Sun 12-05 08:05:40 → Sat,Sun *-12-05 08:05:40 - Sat,Sun 08:05:40 → Sat,Sun *-*-* 08:05:40 - 2003-03-05 05:40 → 2003-03-05 05:40:00 -05:40:23.4200004/3.1700005 → 05:40:23.420000/3.170001 - 2003-03-05 05:40 UTC → 2003-03-05 05:40:00 UTC - 2003-03-05 → 2003-03-05 00:00:00 - 03-05 → *-03-05 00:00:00 - hourly → *-*-* *:00:00 - daily → *-*-* 00:00:00 - daily UTC → *-*-* 00:00:00 UTC - monthly → *-*-01 00:00:00 - weekly → Mon *-*-* 00:00:00 - yearly → *-01-01 00:00:00 - annually → *-01-01 00:00:00 - *:2/3 → *-*-* *:02/3:00</programlisting> - - <para>Calendar events are used by timer units, see - <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details.</para> - - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd.timer.xml b/man/systemd.timer.xml deleted file mode 100644 index 0fa95e97a8..0000000000 --- a/man/systemd.timer.xml +++ /dev/null @@ -1,313 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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><replaceable>timer</replaceable>.timer</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>A unit configuration file whose name ends in - <literal>.timer</literal> 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>Note that in case the unit to activate is already active at the time the timer elapses it is not restarted, - but simply left running. There is no concept of spawning new service instances in this case. Due to this, services - with <varname>RemainAfterExit=</varname> set (which stay around continously even after the service's main process - exited) are usually not suitable for activation via repetitive timers, as they will only be activated once, and - then stay around forever.</para> - </refsect1> - - <refsect1> - <title>Automatic Dependencies</title> - - <para>Timer units automatically gain a <varname>Before=</varname> - dependency on the service they are supposed to activate.</para> - - <para>Unless <varname>DefaultDependencies=</varname> in the <literal>[Unit]</literal> section is set to - <option>false</option>, all timer units will implicitly have dependencies of type <varname>Requires=</varname> and - <varname>After=</varname> on <filename>sysinit.target</filename>, a dependency of type <varname>Before=</varname> - on <filename>timers.target</filename>, as well as <varname>Conflicts=</varname> and <varname>Before=</varname> on - <filename>shutdown.target</filename> to ensure that they are stopped cleanly prior to system shutdown. Timer units - with at least one <varname>OnCalendar=</varname> directive will have an additional <varname>After=</varname> - dependency on <filename>timer-sync.target</filename> to avoid being started before the system clock has been - correctly set. Only timer units involved with early boot or late system shutdown should disable the - <varname>DefaultDependencies=</varname> 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 class='unit-directives'> - <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 monotonic 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 first 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.time</refentrytitle><manvolnum>7</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> - - <para>These are monotonic timers, independent of wall-clock - time and timezones. If the computer is temporarily suspended, - the monotonic clock stops too.</para> - - <para>If the empty string is assigned to any of these options, - the list of timers is reset, and all prior assignments will - have no effect.</para> - - <para>Note that timers do not necessarily expire at the - precise time configured with these settings, as they are - subject to the <varname>AccuracySec=</varname> setting - below.</para></listitem> - - </varlistentry> - - <varlistentry> - <term><varname>OnCalendar=</varname></term> - - <listitem><para>Defines realtime (i.e. wallclock) timers with - calendar event expressions. See - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for more information on the syntax of calendar event - expressions. Otherwise, the semantics are similar to - <varname>OnActiveSec=</varname> and related settings.</para> - - <para>Note that timers do not necessarily expire at the - precise time configured with this setting, as it is subject to - the <varname>AccuracySec=</varname> setting - below.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>AccuracySec=</varname></term> - - <listitem><para>Specify the accuracy the timer shall elapse - with. Defaults to 1min. The timer is scheduled to elapse - within a time window starting with the time specified in - <varname>OnCalendar=</varname>, - <varname>OnActiveSec=</varname>, - <varname>OnBootSec=</varname>, - <varname>OnStartupSec=</varname>, - <varname>OnUnitActiveSec=</varname> or - <varname>OnUnitInactiveSec=</varname> and ending the time - configured with <varname>AccuracySec=</varname> later. Within - this time window, the expiry time will be placed at a - host-specific, randomized, but stable position that is - synchronized between all local timer units. This is done in - order to optimize power consumption to suppress unnecessary - CPU wake-ups. To get best accuracy, set this option to - 1us. Note that the timer is still subject to the timer slack - configured via - <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>'s - <varname>TimerSlackNSec=</varname> setting. See - <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for details. To optimize power consumption, make sure to set - this value as high as possible and as low as - necessary.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>RandomizedDelaySec=</varname></term> - - <listitem><para>Delay the timer by a randomly selected, evenly - distributed amount of time between 0 and the specified time - value. Defaults to 0, indicating that no randomized delay - shall be applied. Each timer unit will determine this delay - randomly each time it is started, and the delay will simply be - added on top of the next determined elapsing time. This is - useful to stretch dispatching of similarly configured timer - events over a certain amount time, to avoid that they all fire - at the same time, possibly resulting in resource - congestion. Note the relation to - <varname>AccuracySec=</varname> above: the latter allows the - service manager to coalesce timer events within a specified - time range in order to minimize wakeups, the former does the - opposite: it stretches timer events over a time range, to make - it unlikely that they fire simultaneously. If - <varname>RandomizedDelaySec=</varname> and - <varname>AccuracySec=</varname> are used in conjunction, first - the randomized delay is added, and then the result is - possibly further shifted to coalesce it with other timer - events happening on the system. As mentioned above - <varname>AccuracySec=</varname> defaults to 1min and - <varname>RandomizedDelaySec=</varname> to 0, thus encouraging - coalescing of timer events. In order to optimally stretch - timer events over a certain range of time, make sure to set - <varname>RandomizedDelaySec=</varname> to a higher value, and - <varname>AccuracySec=1us</varname>.</para></listitem> - </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 - <literal>.timer</literal>. 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> - - - <varlistentry> - <term><varname>Persistent=</varname></term> - - <listitem><para>Takes a boolean argument. If true, the time - when the service unit was last triggered is stored on disk. - When the timer is activated, the service unit is triggered - immediately if it would have been triggered at least once - during the time when the timer was inactive. This is useful to - catch up on missed runs of the service when the machine was - off. Note that this setting only has an effect on timers - configured with <varname>OnCalendar=</varname>. Defaults - to <varname>false</varname>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>WakeSystem=</varname></term> - - <listitem><para>Takes a boolean argument. If true, an elapsing - timer will cause the system to resume from suspend, should it - be suspended and if the system supports this. Note that this - option will only make sure the system resumes on the - appropriate times, it will not take care of suspending it - again after any work that is to be done is finished. Defaults - to <varname>false</varname>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>RemainAfterElapse=</varname></term> - - <listitem><para>Takes a boolean argument. If true, an elapsed - timer will stay loaded, and its state remains queriable. If - false, an elapsed timer unit that cannot elapse anymore is - unloaded. Turning this off is particularly useful for - transient timer units that shall disappear after they first - elapse. Note that this setting has an effect on repeatedly - starting a timer unit that only elapses once: if - <varname>RemainAfterElapse=</varname> is on, it will not be - started again, and is guaranteed to elapse only once. However, - if <varname>RemainAfterElapse=</varname> is off, it might be - started again if it is already elapsed, and thus be triggered - multiple times. Defaults to - <varname>yes</varname>.</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.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml deleted file mode 100644 index 341789cd47..0000000000 --- a/man/systemd.unit.xml +++ /dev/null @@ -1,1484 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ -<!ENTITY % entities SYSTEM "custom-entities.ent" > -%entities; -]> - -<!-- - 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><replaceable>service</replaceable>.service</filename>, - <filename><replaceable>socket</replaceable>.socket</filename>, - <filename><replaceable>device</replaceable>.device</filename>, - <filename><replaceable>mount</replaceable>.mount</filename>, - <filename><replaceable>automount</replaceable>.automount</filename>, - <filename><replaceable>swap</replaceable>.swap</filename>, - <filename><replaceable>target</replaceable>.target</filename>, - <filename><replaceable>path</replaceable>.path</filename>, - <filename><replaceable>timer</replaceable>.timer</filename>, - <filename><replaceable>slice</replaceable>.slice</filename>, - <filename><replaceable>scope</replaceable>.scope</filename></para> - - <para><literallayout><filename>/etc/systemd/system/*</filename> -<filename>/run/systemd/system/*</filename> -<filename>/usr/lib/systemd/system/*</filename> -<filename>…</filename> - </literallayout></para> - - <para><literallayout><filename>~/.config/systemd/user/*</filename> -<filename>/etc/systemd/user/*</filename> -<filename>$XDG_RUNTIME_DIR/systemd/user/*</filename> -<filename>/run/systemd/user/*</filename> -<filename>~/.local/share/systemd/user/*</filename> -<filename>/usr/lib/systemd/user/*</filename> -<filename>…</filename> - </literallayout></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 watched file system - path, a timer controlled and supervised by - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - a resource management slice or - a group of externally created processes. 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 may have a type-specific section, e.g. - [Service] for a service unit. See the respective man pages for - more information: - <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.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - </para> - - <para>Various settings are allowed to be specified more than once, - in which case the interpretation depends on the setting. Often, - multiple settings form a list, and setting to an empty value - "resets", which means that previous assignments are ignored. When - this is allowed, it is mentioned in the description of the - setting. Note that using multiple assignments to the same value - makes the unit file incompatible with parsers for the XDG - <filename>.desktop</filename> file format.</para> - - <para>Unit files are loaded from a set of paths determined during - compilation, described in the next section.</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 or section name is prefixed with <option>X-</option>, it is - ignored completely by systemd. Options within an ignored section - do not need the prefix. Applications may use this to include - additional information in the unit files.</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. - For details see - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</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>Along with a unit file <filename>foo.service</filename>, the - directory <filename>foo.service.wants/</filename> may exist. All - unit files symlinked from such a directory are implicitly added as - dependencies of type <varname>Wants=</varname> to the unit. This - is useful to hook units into the start-up of other units, without - having to modify their unit files. For details about the semantics - of <varname>Wants=</varname>, see below. The preferred way to - create symlinks in the <filename>.wants/</filename> directory of a - unit file 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>Along with a unit file <filename>foo.service</filename>, a "drop-in" directory - <filename>foo.service.d/</filename> may exist. All files with the suffix <literal>.conf</literal> from this - directory will be parsed after the file itself is parsed. This is useful to alter or add configuration settings for - a unit, without having to modify unit files. Each drop-in file must have appropriate section headers. Note that for - instantiated units, this logic will first look for the instance <literal>.d/</literal> subdirectory and read its - <literal>.conf</literal> files, followed by the template <literal>.d/</literal> subdirectory and the - <literal>.conf</literal> files there. Also note that settings from the <literal>[Install]</literal> section are not - honoured in drop-in unit files, and have no effect.</para> - - <para>In addition to <filename>/etc/systemd/system</filename>, - the drop-in <literal>.conf</literal> files for system services - can be placed in <filename>/usr/lib/systemd/system</filename> or - <filename>/run/systemd/system</filename> directories. Drop-in - files in <filename>/etc</filename> take precedence over those in - <filename>/run</filename> which in turn take precedence over - those in <filename>/usr/lib</filename>. Drop-in files under any of - these directories take precedence over unit files wherever located. - (Of course, since <filename>/run</filename> is temporary and - <filename>/usr/lib</filename> is for vendors, it is unlikely - drop-ins should be used in either of those places.)</para> - <!-- Note that we do not document .include here, as we - consider it mostly obsolete, and want people to - use .d/ drop-ins instead. --> - - <para>Some unit names reflect paths existing in the file system - namespace. Example: a device unit - <filename>dev-sda.device</filename> refers to a device with the - device node <filename noindex='true'>/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 - filename. Basically, given a path, "/" is replaced by "-", and all - other characters which are not ASCII alphanumerics are replaced by - C-style "\x2d" escapes (except that "_" is never replaced and "." - is only replaced when it would be the first character in the - escaped path). The root directory "/" is encoded as single dash, - while otherwise the initial and ending "/" are removed from all - paths during transformation. This escaping is reversible. Properly - escaped paths can be generated using the - <citerefentry><refentrytitle>systemd-escape</refentrytitle><manvolnum>1</manvolnum></citerefentry> - command.</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 - file system. If that yields no success and the unit - name contains an <literal>@</literal> character, systemd will look for a - unit template that shares the same name but with the - instance string (i.e. the part between the <literal>@</literal> 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. See below for - details.</para> - - <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>Automatic Dependencies</title> - - <para>Note that while systemd offers a flexible dependency system - between units it is recommended to use this functionality only - sparingly and instead rely on techniques such as bus-based or - socket-based activation which make dependencies implicit, - resulting in a both simpler and more flexible system.</para> - - <para>A number of unit dependencies are automatically established, - depending on unit configuration. On top of that, for units with - <varname>DefaultDependencies=yes</varname> (the default) a couple - of additional dependencies are added. The precise effect of - <varname>DefaultDependencies=yes</varname> depends on the unit - type (see below).</para> - - <para>If <varname>DefaultDependencies=yes</varname> is set, units - that are referenced by other units of type - <filename>.target</filename> via a <varname>Wants=</varname> or - <varname>Requires=</varname> dependency might automatically gain - an <varname>Before=</varname> dependency too. See - <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details.</para> - </refsect1> - - <refsect1> - <title>Unit File Load Path</title> - - <para>Unit files are loaded from a set of paths determined during - compilation, described in the two tables below. Unit files found - in directories listed earlier override files with the same name in - directories lower in the list.</para> - - <para>When the variable <varname>$SYSTEMD_UNIT_PATH</varname> is set, - the contents of this variable overrides the unit load path. If - <varname>$SYSTEMD_UNIT_PATH</varname> ends with an empty component - (<literal>:</literal>), the usual unit load path will be appended - to the contents of the variable.</para> - - <table> - <title> - Load path when running in system mode (<option>--system</option>). - </title> - - <tgroup cols='2'> - <colspec colname='path' /> - <colspec colname='expl' /> - <thead> - <row> - <entry>Path</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry><filename>/etc/systemd/system</filename></entry> - <entry>Local configuration</entry> - </row> - <row> - <entry><filename>/run/systemd/system</filename></entry> - <entry>Runtime units</entry> - </row> - <row> - <entry><filename>/usr/lib/systemd/system</filename></entry> - <entry>Units of installed packages</entry> - </row> - </tbody> - </tgroup> - </table> - - <table> - <title> - Load path when running in user mode (<option>--user</option>). - </title> - - <tgroup cols='2'> - <colspec colname='path' /> - <colspec colname='expl' /> - <thead> - <row> - <entry>Path</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry><filename>$XDG_CONFIG_HOME/systemd/user</filename></entry> - <entry>User configuration (only used when $XDG_CONFIG_HOME is set)</entry> - </row> - <row> - <entry><filename>$HOME/.config/systemd/user</filename></entry> - <entry>User configuration (only used when $XDG_CONFIG_HOME is not set)</entry> - </row> - <row> - <entry><filename>/etc/systemd/user</filename></entry> - <entry>Local configuration</entry> - </row> - <row> - <entry><filename>$XDG_RUNTIME_DIR/systemd/user</filename></entry> - <entry>Runtime units (only used when $XDG_RUNTIME_DIR is set)</entry> - </row> - <row> - <entry><filename>/run/systemd/user</filename></entry> - <entry>Runtime units</entry> - </row> - <row> - <entry><filename>$XDG_DATA_HOME/systemd/user</filename></entry> - <entry>Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is set)</entry> - </row> - <row> - <entry><filename>$HOME/.local/share/systemd/user</filename></entry> - <entry>Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is not set)</entry> - </row> - <row> - <entry><filename>/usr/lib/systemd/user</filename></entry> - <entry>Units of packages that have been installed system-wide</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>Additional units might be loaded into systemd ("linked") - from directories not on the unit load path. See the - <command>link</command> command for - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. - Also, some units are dynamically created via a - <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>. - </para> - </refsect1> - - <refsect1> - <title>[Unit] Section Options</title> - - <para>The 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 class='unit-directives'> - - <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. The description should contain a - name that means something to the end user. <literal>Apache2 - Web Server</literal> is a good example. Bad examples are - <literal>high-performance light-weight HTTP server</literal> - (too generic) or <literal>Apache2</literal> (too specific and - meaningless for people who do not know - Apache).</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 - project='man-pages'><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. This option may be specified more than - once, in which case the specified list of URIs is merged. If - the empty string is assigned to this option, the list is reset - and all prior assignments will have no - effect.</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 or - multiple space-separated units may be specified in one option - in which case requirement dependencies for all listed names - will be 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>Requisite=</varname></term> - - <listitem><para>Similar to <varname>Requires=</varname>. - However, if the units listed here are not started already, - they will not be started and the transaction will fail - immediately. </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Wants=</varname></term> - - <listitem><para>A weaker version of - <varname>Requires=</varname>. Units listed in this option will - be started if the configuring unit is. However, if the listed - units fail to start 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 - symlinks 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>A space-separated list of unit names. - 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>A space-separated list of unit names. - 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. Given two units - with any ordering dependency between them, if one unit is shut - down and the other is started up, the shutdown is ordered - before the start-up. It doesn't matter if the ordering - dependency is <varname>After=</varname> or - <varname>Before=</varname>. It also doesn't matter which of the - two is shut down, as long as one is shut down and the other is - started up. The shutdown is ordered before the start-up in all - cases. 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>A space-separated list of 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>A space-separated list of one or more units - where reload requests on this unit will be propagated to, or - reload requests on the other unit will be propagated to this - unit, respectively. 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>JoinsNamespaceOf=</varname></term> - - <listitem><para>For units that start processes (such as - service units), lists one or more other units whose network - and/or temporary file namespace to join. This only applies to - unit types which support the - <varname>PrivateNetwork=</varname> and - <varname>PrivateTmp=</varname> directives (see - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details). If a unit that has this setting set is started, - its processes will see the same <filename>/tmp</filename>, - <filename>/var/tmp</filename> and network namespace as one - listed unit that is started. If multiple listed units are - already started, it is not defined which namespace is joined. - Note that this setting only has an effect if - <varname>PrivateNetwork=</varname> and/or - <varname>PrivateTmp=</varname> is enabled for both the unit - that joins the namespace and the unit whose namespace is - joined.</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> - - <para>Mount points marked with <option>noauto</option> are not - mounted automatically and will be ignored for the purposes of - this option. If such a mount should be a requirement for this - unit, direct dependencies on the mount units may be added - (<varname>Requires=</varname> and <varname>After=</varname> or - some other combination). </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>OnFailureJobMode=</varname></term> - - <listitem><para>Takes a value of - <literal>fail</literal>, - <literal>replace</literal>, - <literal>replace-irreversibly</literal>, - <literal>isolate</literal>, - <literal>flush</literal>, - <literal>ignore-dependencies</literal> or - <literal>ignore-requirements</literal>. Defaults to - <literal>replace</literal>. Specifies how the units listed in - <varname>OnFailure=</varname> will be enqueued. See - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s - <option>--job-mode=</option> option for details on the - possible values. If this is set to <literal>isolate</literal>, - only a single unit may be listed in - <varname>OnFailure=</varname>..</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>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> - <term><varname>JobTimeoutAction=</varname></term> - <term><varname>JobTimeoutRebootArgument=</varname></term> - - <listitem><para>When a job for this unit is queued, a time-out may be configured. 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 <literal>infinity</literal> (job timeouts disabled), - except for device units. NB: this timeout is independent from any unit-specific timeout (for example, the - timeout set with <varname>TimeoutStartSec=</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> - - <para><varname>JobTimeoutAction=</varname> - optionally configures an additional - action to take when the time-out is - hit. It takes the same values as the - per-service - <varname>StartLimitAction=</varname> - setting, see - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. Defaults to - <option>none</option>. <varname>JobTimeoutRebootArgument=</varname> - configures an optional reboot string - to pass to the - <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> - system call.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>StartLimitIntervalSec=</varname></term> - <term><varname>StartLimitBurst=</varname></term> - - <listitem><para>Configure unit start rate limiting. By default, units which are started more than 5 times - within 10 seconds are not permitted to start any more times until the 10 second interval ends. With these two - options, this rate limiting may be modified. Use <varname>StartLimitIntervalSec=</varname> to configure the - checking interval (defaults to <varname>DefaultStartLimitIntervalSec=</varname> in manager configuration file, - 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 <varname>DefaultStartLimitBurst=</varname> in manager - configuration file). These configuration options are particularly useful in conjunction with the service - setting <varname>Restart=</varname> (see - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>); however, - they 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 unit and the start limit interferes with - that. Note that this rate-limiting is enforced after any unit condition checks are executed, and hence unit - activations with failing conditions are not counted by this rate limiting. Slice, target, device and scope - units do not enforce this setting, as they are unit types whose activation may either never fail, or may - succeed only a single time.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>StartLimitAction=</varname></term> - - <listitem><para>Configure the action to take if the rate limit configured with - <varname>StartLimitIntervalSec=</varname> and <varname>StartLimitBurst=</varname> is hit. Takes one of - <option>none</option>, <option>reboot</option>, <option>reboot-force</option>, - <option>reboot-immediate</option>, <option>poweroff</option>, <option>poweroff-force</option> or - <option>poweroff-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 a 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. Similarly, <option>poweroff</option>, <option>poweroff-force</option>, - <option>poweroff-immediate</option> have the effect of powering down the system with similar - semantics. Defaults to <option>none</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>RebootArgument=</varname></term> - <listitem><para>Configure the optional argument for the - <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> system call if - <varname>StartLimitAction=</varname> or a service's <varname>FailureAction=</varname> is a reboot action. This - works just like the optional argument to <command>systemctl reboot</command> command.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>ConditionArchitecture=</varname></term> - <term><varname>ConditionVirtualization=</varname></term> - <term><varname>ConditionHost=</varname></term> - <term><varname>ConditionKernelCommandLine=</varname></term> - <term><varname>ConditionSecurity=</varname></term> - <term><varname>ConditionCapability=</varname></term> - <term><varname>ConditionACPower=</varname></term> - <term><varname>ConditionNeedsUpdate=</varname></term> - <term><varname>ConditionFirstBoot=</varname></term> - <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> - - <!-- We do not document ConditionNull= - here, as it is not particularly - useful and probably just - confusing. --> - - <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 (mostly silently) 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. Use condition expressions in order to silently skip - units that do not apply to the local running system, for example because the kernel or runtime environment - doesn't require its functionality. Use the various <varname>AssertArchitecture=</varname>, - <varname>AssertVirtualization=</varname>, … options for a similar mechanism that puts the unit in a failure - state and logs about the failed check (see below).</para> - - <para><varname>ConditionArchitecture=</varname> may be used to - check whether the system is running on a specific - architecture. Takes one of - <varname>x86</varname>, - <varname>x86-64</varname>, - <varname>ppc</varname>, - <varname>ppc-le</varname>, - <varname>ppc64</varname>, - <varname>ppc64-le</varname>, - <varname>ia64</varname>, - <varname>parisc</varname>, - <varname>parisc64</varname>, - <varname>s390</varname>, - <varname>s390x</varname>, - <varname>sparc</varname>, - <varname>sparc64</varname>, - <varname>mips</varname>, - <varname>mips-le</varname>, - <varname>mips64</varname>, - <varname>mips64-le</varname>, - <varname>alpha</varname>, - <varname>arm</varname>, - <varname>arm-be</varname>, - <varname>arm64</varname>, - <varname>arm64-be</varname>, - <varname>sh</varname>, - <varname>sh64</varname>, - <varname>m86k</varname>, - <varname>tilegx</varname>, - <varname>cris</varname> to test - against a specific architecture. The architecture is - determined from the information returned by - <citerefentry project='man-pages'><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry> - and is thus subject to - <citerefentry><refentrytitle>personality</refentrytitle><manvolnum>2</manvolnum></citerefentry>. - Note that a <varname>Personality=</varname> setting in the - same unit file has no effect on this condition. A special - architecture name <varname>native</varname> is mapped to the - architecture the system manager itself is compiled for. The - test may be negated by prepending an exclamation mark.</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>zvm</varname>, - <varname>vmware</varname>, - <varname>microsoft</varname>, - <varname>oracle</varname>, - <varname>xen</varname>, - <varname>bochs</varname>, - <varname>uml</varname>, - <varname>openvz</varname>, - <varname>lxc</varname>, - <varname>lxc-libvirt</varname>, - <varname>systemd-nspawn</varname>, - <varname>docker</varname>, - <varname>rkt</varname> to test - against a specific implementation. See - <citerefentry><refentrytitle>systemd-detect-virt</refentrytitle><manvolnum>1</manvolnum></citerefentry> - for a full list of known virtualization technologies and their - identifiers. If multiple virtualization technologies are - nested, only the innermost is considered. The test may be - negated by prepending an exclamation mark.</para> - - <para><varname>ConditionHost=</varname> may be used to match - against the hostname or machine ID of the host. This either - takes a hostname string (optionally with shell style globs) - which is tested against the locally set hostname 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><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 <literal>=</literal>). 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>ConditionSecurity=</varname> may be used to - check whether the given security module is enabled on the - system. Currently, the recognized values are - <varname>selinux</varname>, - <varname>apparmor</varname>, - <varname>ima</varname>, - <varname>smack</varname> and - <varname>audit</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 project='man-pages'><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>ConditionACPower=</varname> may be used to - check whether the system has AC power, or is exclusively - battery powered at the time of activation of the unit. This - takes a boolean argument. If set to <varname>true</varname>, - the condition will hold only if at least one AC connector of - the system is connected to a power source, or if no AC - connectors are known. Conversely, if set to - <varname>false</varname>, the condition will hold only if - there is at least one AC connector known and all AC connectors - are disconnected from a power source.</para> - - <para><varname>ConditionNeedsUpdate=</varname> takes one of - <filename>/var</filename> or <filename>/etc</filename> as - argument, possibly prefixed with a <literal>!</literal> (for - inverting the condition). This condition may be used to - conditionalize units on whether the specified directory - requires an update because <filename>/usr</filename>'s - modification time is newer than the stamp file - <filename>.updated</filename> in the specified directory. This - is useful to implement offline updates of the vendor operating - system resources in <filename>/usr</filename> that require - updating of <filename>/etc</filename> or - <filename>/var</filename> on the next following boot. Units - making use of this condition should order themselves before - <citerefentry><refentrytitle>systemd-update-done.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - to make sure they run before the stamp file's modification - time gets reset indicating a completed update.</para> - - <para><varname>ConditionFirstBoot=</varname> takes a boolean - argument. This condition may be used to conditionalize units - on whether the system is booting up with an unpopulated - <filename>/etc</filename> directory. This may be used to - populate <filename>/etc</filename> on the first boot after - factory reset, or when a new system instances boots up for the - first time.</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 (<literal>!</literal>), 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>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. If any of these options is assigned - the empty string, the list of conditions is reset completely, - all previous condition settings (of any kind) will have no - effect.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>AssertArchitecture=</varname></term> - <term><varname>AssertVirtualization=</varname></term> - <term><varname>AssertHost=</varname></term> - <term><varname>AssertKernelCommandLine=</varname></term> - <term><varname>AssertSecurity=</varname></term> - <term><varname>AssertCapability=</varname></term> - <term><varname>AssertACPower=</varname></term> - <term><varname>AssertNeedsUpdate=</varname></term> - <term><varname>AssertFirstBoot=</varname></term> - <term><varname>AssertPathExists=</varname></term> - <term><varname>AssertPathExistsGlob=</varname></term> - <term><varname>AssertPathIsDirectory=</varname></term> - <term><varname>AssertPathIsSymbolicLink=</varname></term> - <term><varname>AssertPathIsMountPoint=</varname></term> - <term><varname>AssertPathIsReadWrite=</varname></term> - <term><varname>AssertDirectoryNotEmpty=</varname></term> - <term><varname>AssertFileNotEmpty=</varname></term> - <term><varname>AssertFileIsExecutable=</varname></term> - - <listitem><para>Similar to the <varname>ConditionArchitecture=</varname>, - <varname>ConditionVirtualization=</varname>, …, condition settings described above, these settings add - assertion checks to the start-up of the unit. However, unlike the conditions settings, any assertion setting - that is not met results in failure of the start job (which means this is logged loudly). Use assertion - expressions for units that cannot operate when specific requirements are not met, and when this is something - the administrator or user should look into.</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. This functionality should not be used in normal - units.</para></listitem> - </varlistentry> - - </variablelist> - - </refsect1> - - <refsect1> - <title>[Install] Section Options</title> - - <para>Unit files may include an <literal>[Install]</literal> 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 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. Note that settings in the <literal>[Install]</literal> section may not appear in - <filename>.d/*.conf</filename> unit file drop-ins (see above).</para> - - <variablelist class='unit-directives'> - <varlistentry> - <term><varname>Alias=</varname></term> - - <listitem><para>A space-separated list of 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 filename. Note that not all unit types support such alias names, and this - setting is not supported for them. Specifically, mount, slice, swap, and automount units do not support - aliasing.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>WantedBy=</varname></term> - <term><varname>RequiredBy=</varname></term> - - <listitem><para>This option may be used more than once, or a - space-separated list of unit names may be given. A symbolic - link is created in the <filename>.wants/</filename> or - <filename>.requires/</filename> directory of each of the - listed units when this unit is installed by <command>systemctl - enable</command>. This has the effect that a dependency of - type <varname>Wants=</varname> or <varname>Requires=</varname> - is added from the listed unit to the current unit. The primary - result is that the current unit will be started when the - listed unit is started. See the description of - <varname>Wants=</varname> and <varname>Requires=</varname> in - the [Unit] section for details.</para> - - <para><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. In case of template units, <command>systemctl - enable</command> must be called with an instance name, and - this instance will be added to the - <filename>.wants/</filename> or - <filename>.requires/</filename> list of the listed unit. E.g. - <command>WantedBy=getty.target</command> in a service - <filename>getty@.service</filename> will result in - <command>systemctl enable getty@tty2.service</command> - creating a - <filename>getty.target.wants/getty@tty2.service</filename> - link to <filename>getty@.service</filename>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Also=</varname></term> - - <listitem><para>Additional units to install/deinstall when - this unit is installed/deinstalled. If the user requests - installation/deinstallation of a unit with this option - configured, <command>systemctl enable</command> and - <command>systemctl disable</command> will automatically - install/uninstall units listed in this option as well.</para> - - <para>This option may be used more than once, or a - space-separated list of unit names may be - given.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>DefaultInstance=</varname></term> - - <listitem><para>In template unit files, this specifies for - which instance the unit shall be enabled if the template is - enabled without any explicitly set instance. This option has - no effect in non-template unit files. The specified string - must be usable as instance identifier.</para></listitem> - </varlistentry> - </variablelist> - - <para>The following specifiers are interpreted in the Install - section: %n, %N, %p, %i, %U, %u, %m, %H, %b, %v. For their meaning - see the next section. - </para> - </refsect1> - - <refsect1> - <title>Specifiers</title> - - <para>Many settings resolve specifiers which may be used to write - generic unit files referring to runtime or unit parameters that - are replaced when the unit files are loaded. The following - specifiers are understood:</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>Same as <literal>%n</literal>, but with escaping undone</entry> - </row> - <row> - <entry><literal>%p</literal></entry> - <entry>Prefix name</entry> - <entry>For instantiated units, this refers to the string before the <literal>@</literal> character of the unit name. For non-instantiated units, this refers to the name of the unit with the type suffix removed.</entry> - </row> - <row> - <entry><literal>%P</literal></entry> - <entry>Unescaped prefix name</entry> - <entry>Same as <literal>%p</literal>, but with escaping undone</entry> - </row> - <row> - <entry><literal>%i</literal></entry> - <entry>Instance name</entry> - <entry>For instantiated units: this is the string between the <literal>@</literal> character and the suffix of the unit name.</entry> - </row> - <row> - <entry><literal>%I</literal></entry> - <entry>Unescaped instance name</entry> - <entry>Same as <literal>%i</literal>, but with escaping undone</entry> - </row> - <row> - <entry><literal>%f</literal></entry> - <entry>Unescaped filename</entry> - <entry>This is either the unescaped instance name (if applicable) with <filename>/</filename> prepended (if applicable), or the prefix name prepended with <filename>/</filename>.</entry> - </row> - <row> - <entry><literal>%c</literal></entry> - <entry>Control group path of the unit</entry> - <entry>This path does not include the <filename>/sys/fs/cgroup/systemd/</filename> prefix.</entry> - </row> - <row> - <entry><literal>%r</literal></entry> - <entry>Control group path of the slice the unit is placed in</entry> - <entry>This usually maps to the parent cgroup path of <literal>%c</literal>.</entry> - </row> - <row> - <entry><literal>%R</literal></entry> - <entry>Root control group path below which slices and units are placed</entry> - <entry>For system instances, this resolves to <filename>/</filename>, except in containers, where this maps to the container's root control group path.</entry> - </row> - <row> - <entry><literal>%t</literal></entry> - <entry>Runtime directory</entry> - <entry>This is either <filename>/run</filename> (for the system manager) or the path <literal>$XDG_RUNTIME_DIR</literal> resolves to (for user managers).</entry> - </row> - <row> - <entry><literal>%u</literal></entry> - <entry>User name</entry> - <entry>This is the name of the user running the service manager instance. In case of the system manager this resolves to <literal>root</literal>.</entry> - </row> - <row> - <entry><literal>%U</literal></entry> - <entry>User UID</entry> - <entry>This is the numeric UID of the user running the service manager instance. In case of the system manager this resolves to <literal>0</literal>.</entry> - </row> - <row> - <entry><literal>%h</literal></entry> - <entry>User home directory</entry> - <entry>This is the home directory of the user running the service manager instance. In case of the system manager this resolves to <literal>/root</literal>.</entry> - </row> - <row> - <entry><literal>%s</literal></entry> - <entry>User shell</entry> - <entry>This is the shell of the user running the service manager instance. In case of the system manager this resolves to <literal>/bin/sh</literal>.</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 hostname of the running system at the point in time the unit configuration is loaded.</entry> - </row> - <row> - <entry><literal>%v</literal></entry> - <entry>Kernel release</entry> - <entry>Identical to <command>uname -r</command> output</entry> - </row> - <row> - <entry><literal>%%</literal></entry> - <entry>Single percent sign</entry> - <entry>Use <literal>%%</literal> in place of <literal>%</literal> to specify a single percent sign.</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>Please note that specifiers <literal>%U</literal>, - <literal>%h</literal>, <literal>%s</literal> are mostly useless - when systemd is running in system mode. PID 1 cannot query the - user account database for information, so the specifiers only work - as shortcuts for things which are already specified in a different - way in the unit file. They are fully functional when systemd is - running in <option>--user</option> mode.</para> - </refsect1> - - <refsect1> - <title>Examples</title> - - <example> - <title>Allowing units to be enabled</title> - - <para>The following snippet (highlighted) allows a unit (e.g. - <filename>foo.service</filename>) to be enabled via - <command>systemctl enable</command>:</para> - - <programlisting>[Unit] -Description=Foo - -[Service] -ExecStart=/usr/sbin/foo-daemon - -<emphasis>[Install]</emphasis> -<emphasis>WantedBy=multi-user.target</emphasis></programlisting> - - <para>After running <command>systemctl enable</command>, a - symlink - <filename>/etc/systemd/system/multi-user.target.wants/foo.service</filename> - linking to the actual unit will be created. It tells systemd to - pull in the unit when starting - <filename>multi-user.target</filename>. The inverse - <command>systemctl disable</command> will remove that symlink - again.</para> - </example> - - <example> - <title>Overriding vendor settings</title> - - <para>There are two methods of overriding vendor settings in - unit files: copying the unit file from - <filename>/usr/lib/systemd/system</filename> to - <filename>/etc/systemd/system</filename> and modifying the - chosen settings. Alternatively, one can create a directory named - <filename><replaceable>unit</replaceable>.d/</filename> within - <filename>/etc/systemd/system</filename> and place a drop-in - file <filename><replaceable>name</replaceable>.conf</filename> - there that only changes the specific settings one is interested - in. Note that multiple such drop-in files are read if - present.</para> - - <para>The advantage of the first method is that one easily - overrides the complete unit, the vendor unit is not parsed at - all anymore. It has the disadvantage that improvements to the - unit file by the vendor are not automatically incorporated on - updates.</para> - - <para>The advantage of the second method is that one only - overrides the settings one specifically wants, where updates to - the unit by the vendor automatically apply. This has the - disadvantage that some future updates by the vendor might be - incompatible with the local changes.</para> - - <para>Note that for drop-in files, if one wants to remove - entries from a setting that is parsed as a list (and is not a - dependency), such as <varname>ConditionPathExists=</varname> (or - e.g. <varname>ExecStart=</varname> in service units), one needs - to first clear the list before re-adding all entries except the - one that is to be removed. See below for an example.</para> - - <para>This also applies for user instances of systemd, but with - different locations for the unit files. See the section on unit - load paths for further details.</para> - - <para>Suppose there is a vendor-supplied unit - <filename>/usr/lib/systemd/system/httpd.service</filename> with - the following contents:</para> - - <programlisting>[Unit] -Description=Some HTTP server -After=remote-fs.target sqldb.service -Requires=sqldb.service -AssertPathExists=/srv/webserver - -[Service] -Type=notify -ExecStart=/usr/sbin/some-fancy-httpd-server -Nice=5 - -[Install] -WantedBy=multi-user.target</programlisting> - - <para>Now one wants to change some settings as an administrator: - firstly, in the local setup, <filename>/srv/webserver</filename> - might not exist, because the HTTP server is configured to use - <filename>/srv/www</filename> instead. Secondly, the local - configuration makes the HTTP server also depend on a memory - cache service, <filename>memcached.service</filename>, that - should be pulled in (<varname>Requires=</varname>) and also be - ordered appropriately (<varname>After=</varname>). Thirdly, in - order to harden the service a bit more, the administrator would - like to set the <varname>PrivateTmp=</varname> setting (see - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details). And lastly, the administrator would like to reset - the niceness of the service to its default value of 0.</para> - - <para>The first possibility is to copy the unit file to - <filename>/etc/systemd/system/httpd.service</filename> and - change the chosen settings:</para> - - <programlisting>[Unit] -Description=Some HTTP server -After=remote-fs.target sqldb.service <emphasis>memcached.service</emphasis> -Requires=sqldb.service <emphasis>memcached.service</emphasis> -AssertPathExists=<emphasis>/srv/www</emphasis> - -[Service] -Type=notify -ExecStart=/usr/sbin/some-fancy-httpd-server -<emphasis>Nice=0</emphasis> -<emphasis>PrivateTmp=yes</emphasis> - -[Install] -WantedBy=multi-user.target</programlisting> - - <para>Alternatively, the administrator could create a drop-in - file - <filename>/etc/systemd/system/httpd.service.d/local.conf</filename> - with the following contents:</para> - - <programlisting>[Unit] -After=memcached.service -Requires=memcached.service -# Reset all assertions and then re-add the condition we want -AssertPathExists= -AssertPathExists=/srv/www - -[Service] -Nice=0 -PrivateTmp=yes</programlisting> - - <para>Note that dependencies (<varname>After=</varname>, etc.) - cannot be reset to an empty list, so dependencies can only be - added in drop-ins. If you want to remove dependencies, you have - to override the entire unit.</para> - - </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.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.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>uname</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd.xml b/man/systemd.xml deleted file mode 100644 index e05a9d6e29..0000000000 --- a/man/systemd.xml +++ /dev/null @@ -1,1153 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <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 GNU/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 a system instance, systemd interprets the - configuration file <filename>system.conf</filename> and the files - in <filename>system.conf.d</filename> directories; when run as a - user instance, systemd interprets the configuration file - <filename>user.conf</filename> and the files in - <filename>user.conf.d</filename> directories. See - <citerefentry><refentrytitle>systemd-system.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>--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>--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>Enable core dumping on crash. This switch has - no effect when running as user instance. This setting may also - be enabled during boot on the kernel command line via the - <varname>systemd.dump_core=</varname> option, see - below.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--crash-vt=</option><replaceable>VT</replaceable></term> - - <listitem><para>Switch to a specific virtual console (VT) on - crash. Takes a positive integer in the range 1–63, or a - boolean argument. If an integer is passed, selects which VT to - switch to. If <constant>yes</constant>, the VT kernel messages - are written to is selected. If <constant>no</constant>, no VT - switch is attempted. This switch has no effect when running as - user instance. This setting may also be enabled during boot, - on the kernel command line via the - <varname>systemd.crash_vt=</varname> option, see - below.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--crash-shell</option></term> - - <listitem><para>Run a shell on crash. This switch has no - effect when running as user instance. This setting may also be - enabled during boot, on the kernel command line via the - <varname>systemd.crash_shell=</varname> option, see - below.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--crash-reboot</option></term> - - <listitem><para>Automatically reboot the system on crash. This - switch has no effect when running as user instance. This - setting may also be enabled during boot, on the kernel command - line via the <varname>systemd.crash_reboot=</varname> option, - see below.</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>kmsg</option>, - <option>journal-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 project='man-pages'><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> - - <varlistentry> - <term><option>--machine-id=</option></term> - - <listitem><para>Override the machine-id set on the hard drive, - useful for network booting or for containers. May not be set - to all zeros.</para></listitem> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </variablelist> - </refsect1> - - <refsect1> - <title>Concepts</title> - - <para>systemd provides a dependency system between various - entities called "units" of 12 different types. 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, - dynamically from system state or programmatically at runtime. - 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 start and 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>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> - - <listitem><para>Slice units may be used to group units which - manage system processes (such as service and scope units) in a - hierarchical tree for resource management purposes. See - <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> - - <listitem><para>Scope units are similar to service units, but - manage foreign processes instead of starting them as well. See - <citerefentry><refentrytitle>systemd.scope</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="https://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 project='man-pages'><refentrytitle>systemd-cgls</refentrytitle><manvolnum>1</manvolnum></citerefentry> - or - <citerefentry project='man-pages'><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 hostname 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 - <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</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. Full list of directories is provided in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - </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. Full list of - directories is provided in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - </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><constant>SIGTERM</constant></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><constant>SIGINT</constant></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>. If this signal is received more - than 7 times per 2s, an immediate reboot is triggered. - Note that pressing Ctrl-Alt-Del on the console will trigger - this signal. Hence, if a reboot is hanging, pressing - Ctrl-Alt-Del more than 7 times in 2s is a relatively safe way - to trigger an immediate reboot.</para> - - <para>systemd user managers treat this signal the same way as - <constant>SIGTERM</constant>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>SIGWINCH</constant></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><constant>SIGPWR</constant></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><constant>SIGUSR1</constant></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><constant>SIGUSR2</constant></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>systemd-analyze dump</command>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>SIGHUP</constant></term> - - <listitem><para>Reloads the complete daemon configuration. - This is mostly equivalent to <command>systemctl - daemon-reload</command>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>SIGRTMIN+0</constant></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><constant>SIGRTMIN+1</constant></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><constant>SIGRTMIN+2</constant></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><constant>SIGRTMIN+3</constant></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><constant>SIGRTMIN+4</constant></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><constant>SIGRTMIN+5</constant></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><constant>SIGRTMIN+6</constant></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><constant>SIGRTMIN+13</constant></term> - - <listitem><para>Immediately halts the machine.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>SIGRTMIN+14</constant></term> - - <listitem><para>Immediately powers off the machine.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>SIGRTMIN+15</constant></term> - - <listitem><para>Immediately reboots the machine.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>SIGRTMIN+16</constant></term> - - <listitem><para>Immediately reboots the machine with kexec.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>SIGRTMIN+20</constant></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><constant>SIGRTMIN+21</constant></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><constant>SIGRTMIN+22</constant></term> - <term><constant>SIGRTMIN+23</constant></term> - - <listitem><para>Sets the log level to <literal>debug</literal> - (or <literal>info</literal> on - <constant>SIGRTMIN+23</constant>), as controlled via - <varname>systemd.log_level=debug</varname> (or - <varname>systemd.log_level=info</varname> on - <constant>SIGRTMIN+23</constant>) on the kernel command - line.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>SIGRTMIN+24</constant></term> - - <listitem><para>Immediately exits the manager (only available - for --user instances).</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>SIGRTMIN+26</constant></term> - <term><constant>SIGRTMIN+27</constant></term> - <term><constant>SIGRTMIN+28</constant></term> - - <listitem><para>Sets the log level to - <literal>journal-or-kmsg</literal> (or - <literal>console</literal> on - <constant>SIGRTMIN+27</constant>, <literal>kmsg</literal> on - <constant>SIGRTMIN+28</constant>), as controlled via - <varname>systemd.log_target=journal-or-kmsg</varname> (or - <varname>systemd.log_target=console</varname> on - <constant>SIGRTMIN+27</constant> or - <varname>systemd.log_target=kmsg</varname> on - <constant>SIGRTMIN+28</constant>) on the kernel command - line.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Environment</title> - - <variablelist class='environment-variables'> - <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>$SYSTEMD_COLORS</varname></term> - - <listitem><para>Controls whether colorized output should be generated. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$LISTEN_PID</varname></term> - <term><varname>$LISTEN_FDS</varname></term> - <term><varname>$LISTEN_FDNAMES</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 class='kernel-commandline-options'> - <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 is not 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>yes</option>, the systemd manager (PID 1) dumps core - when it crashes. Otherwise, no core dump is created. Defaults - to <option>yes</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>systemd.crash_chvt=</varname></term> - - <listitem><para>Takes a positive integer, or a boolean - argument. If a positive integer (in the range 1–63) is - specified, the system manager (PID 1) will activate the specified - virtual terminal (VT) when it crashes. Defaults to - <constant>no</constant>, meaning that no such switch is - attempted. If set to <constant>yes</constant>, the VT the - kernel messages are written to is selected.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>systemd.crash_shell=</varname></term> - - <listitem><para>Takes a boolean argument. If - <option>yes</option>, the system manager (PID 1) spawns a - shell when it crashes, after a 10s delay. Otherwise, no shell - is spawned. Defaults to <option>no</option>, for security - reasons, as the shell is not protected by password - authentication.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>systemd.crash_reboot=</varname></term> - - <listitem><para>Takes a boolean argument. If - <option>yes</option>, the system manager (PID 1) will reboot - the machine automatically when it crashes, after a 10s delay. - Otherwise, the system will hang indefinitely. Defaults to - <option>no</option>, in order to avoid a reboot loop. If - combined with <varname>systemd.crash_shell=</varname>, the - system is rebooted after the shell exits.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>systemd.confirm_spawn=</varname></term> - - <listitem><para>Takes a boolean argument. If - <option>yes</option>, the system manager (PID 1) asks for - confirmation when spawning processes. Defaults to - <option>no</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>systemd.show_status=</varname></term> - - <listitem><para>Takes a boolean argument or the constant - <constant>auto</constant>. If <option>yes</option>, the - systemd manager (PID 1) shows terse service status updates on - the console during bootup. <constant>auto</constant> behaves - like <option>false</option> until a service fails or there is - a significant delay in boot. Defaults to - <option>yes</option>, unless <option>quiet</option> is passed - as kernel command line option, in which case it defaults to - <constant>auto</constant>.</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 default environment - variables to add to forked child processes. May be used more - than once to set multiple variables.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>systemd.machine_id=</varname></term> - - <listitem><para>Takes a 32 character hex value to be - used for setting the machine-id. Intended mostly for - network booting where the same machine-id is desired - for every boot.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>quiet</varname></term> - - <listitem><para>Turn 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. Passing this option hence turns off the - usual output from both the system manager and the kernel. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>debug</varname></term> - - <listitem><para>Turn on debugging output. This is equivalent - to <varname>systemd.log_level=debug</varname>. Note that this - option is also read by the kernel itself and enables kernel - debug output. Passing this option hence turns on the debug - output from both the system manager and the - kernel.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>emergency</varname></term> - <term><varname>-b</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>rescue</varname></term> - <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 project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - and - <citerefentry project='man-pages'><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 - <constant>AF_UNIX</constant> 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/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 - <constant>AF_UNIX</constant> 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> - The <ulink url="http://www.freedesktop.org/wiki/Software/systemd/">systemd Homepage</ulink>, - <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><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 project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sysusers.d.xml b/man/sysusers.d.xml deleted file mode 100644 index 18ee3800d6..0000000000 --- a/man/sysusers.d.xml +++ /dev/null @@ -1,223 +0,0 @@ -<?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 2014 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="sysusers.d" conditional='ENABLE_SYSUSERS' - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sysusers.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>sysusers.d</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>sysusers.d</refname> - <refpurpose>Declarative allocation of system users and groups</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/usr/lib/sysusers.d/*.conf</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-sysusers</command> uses the files from - <filename>sysusers.d</filename> directory to create system users - and groups at package installation or boot time. This tool may be - used to allocate system users and groups only, it is not useful - for creating non-system users and groups, as it accesses - <filename>/etc/passwd</filename> and - <filename>/etc/group</filename> directly, bypassing any more - complex user databases, for example any database involving NIS or - LDAP.</para> - </refsect1> - - <refsect1> - <title>Configuration Format</title> - - <para>Each configuration file shall be named in the style of - <filename><replaceable>package</replaceable>.conf</filename> or - <filename><replaceable>package</replaceable>-<replaceable>part</replaceable>.conf</filename>. - The second variant should be used when it is desirable to make it - easy to override just this part of configuration.</para> - - <para>The file format is one line per user or group containing - name, ID, GECOS field description and home directory:</para> - - <programlisting># Type Name ID GECOS -u httpd 440 "HTTP User" -u authd /usr/bin/authd "Authorization user" -g input - - -m authd input -u root 0 "Superuser" /root</programlisting> - - <refsect2> - <title>Type</title> - - <para>The type consists of a single letter. The following line - types are understood:</para> - - <variablelist> - <varlistentry> - <term><varname>u</varname></term> - <listitem><para>Create a system user and group of the - specified name should they not exist yet. The user's primary - group will be set to the group bearing the same name. The - user's shell will be set to - <filename>/sbin/nologin</filename>, the home directory to - the specified home directory, or <filename>/</filename> if - none is given. The account will be created disabled, so that - logins are not allowed.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>g</varname></term> - <listitem><para>Create a system group of the specified name - should it not exist yet. Note that <varname>u</varname> - implicitly create a matching group. The group will be - created with no password set.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>m</varname></term> - <listitem><para>Add a user to a group. If the user or group - do not exist yet, they will be implicitly - created.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>r</varname></term> - <listitem><para>Add a range of numeric UIDs/GIDs to the pool - to allocate new UIDs and GIDs from. If no line of this type - is specified, the range of UIDs/GIDs is set to some - compiled-in default. Note that both UIDs and GIDs are - allocated from the same pool, in order to ensure that users - and groups of the same name are likely to carry the same - numeric UID and GID.</para></listitem> - </varlistentry> - - </variablelist> - </refsect2> - - <refsect2> - <title>Name</title> - - <para>The name field specifies the user or group name. It should - be shorter than 31 characters and avoid any non-ASCII - characters, and not begin with a numeric character. It is - strongly recommended to pick user and group names that are - unlikely to clash with normal users created by the - administrator. A good scheme to guarantee this is by prefixing - all system and group names with the underscore, and avoiding too - generic names.</para> - - <para>For <varname>m</varname> lines, this field should contain - the user name to add to a group.</para> - - <para>For lines of type <varname>r</varname>, this field should - be set to <literal>-</literal>.</para> - </refsect2> - - <refsect2> - <title>ID</title> - - <para>For <varname>u</varname> and <varname>g</varname>, the - numeric 32-bit UID or GID of the user/group. Do not use IDs 65535 - or 4294967295, as they have special placeholder meanings. - Specify <literal>-</literal> for automatic UID/GID allocation - for the user or group. Alternatively, specify an absolute path - in the file system. In this case, the UID/GID is read from the - path's owner/group. This is useful to create users whose UID/GID - match the owners of pre-existing files (such as SUID or SGID - binaries).</para> - - <para>For <varname>m</varname> lines, this field should contain - the group name to add to a user to.</para> - - <para>For lines of type <varname>r</varname>, this field should - be set to a UID/GID range in the format - <literal>FROM-TO</literal>, where both values are formatted as - decimal ASCII numbers. Alternatively, a single UID/GID may be - specified formatted as decimal ASCII numbers.</para> - </refsect2> - - <refsect2> - <title>GECOS</title> - - <para>A short, descriptive string for users to be created, - enclosed in quotation marks. Note that this field may not - contain colons.</para> - - <para>Only applies to lines of type <varname>u</varname> and - should otherwise be left unset, or be set to - <literal>-</literal>.</para> - </refsect2> - - <refsect2> - <title>Home Directory</title> - - <para>The home directory for a new system user. If omitted, - defaults to the root directory. It is recommended to not - unnecessarily specify home directories for system users, unless - software strictly requires one to be set.</para> - - <para>Only applies to lines of type <varname>u</varname> and - should otherwise be left unset, or be set to - <literal>-</literal>.</para> - </refsect2> - - </refsect1> - - <xi:include href="standard-conf.xml" xpointer="confd" /> - - <refsect1> - <title>Idempotence</title> - - <para>Note that <command>systemd-sysusers</command> will do - nothing if the specified users or groups already exist, so - normally, there is no reason to override - <filename>sysusers.d</filename> vendor configuration, except to - block certain users or groups from being created.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-sysusers</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/telinit.xml b/man/telinit.xml deleted file mode 100644 index 02d31fbd46..0000000000 --- a/man/telinit.xml +++ /dev/null @@ -1,179 +0,0 @@ -<?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" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <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> - - <xi:include href="standard-options.xml" xpointer="help-text" /> - </varlistentry> - - <varlistentry> - <term><option>--no-wall</option></term> - - <listitem><para>Do not 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 project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/timedatectl.xml b/man/timedatectl.xml deleted file mode 100644 index 415e2c799a..0000000000 --- a/man/timedatectl.xml +++ /dev/null @@ -1,253 +0,0 @@ -<?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" conditional='ENABLE_TIMEDATED' - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <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> - - <para>Use - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - to initialize the system time zone for mounted (but not booted) - system images.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--no-ask-password</option></term> - - <listitem><para>Do not query the user for authentication for - privileged operations.</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> - - <xi:include href="user-system-options.xml" xpointer="host" /> - <xi:include href="user-system-options.xml" xpointer="machine" /> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - <xi:include href="standard-options.xml" xpointer="no-pager" /> - </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, including whether network time synchronization is - on. Note that whether network time synchronization is on - simply reflects whether the - <filename>systemd-timesyncd.service</filename> unit is - enabled. Even if this command shows the status as off, a - different service might still synchronize the clock with the - network.</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 timezones 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 timezone 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 timezone is not fully supported and will - create various problems with time zone changes and daylight - saving adjustments. If at all possible, keep the RTC in UTC - mode. 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 project='man-pages'><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 - network time synchronization is active and enabled (if - available). This enables and starts, or disables and stops the - <filename>systemd-timesyncd.service</filename> unit. It does - not affect the state of any other, unrelated network time - synchronization services that might be installed on the - system. This command is hence mostly equivalent to: - <command>systemctl enable --now - systemd-timesyncd.service</command> and <command>systemctl - disable --now systemd-timesyncd.service</command>, but is - protected by a different access policy.</para> - - <para>Note that even if time synchronization is turned off - with this command, another unrelated system service might - still synchronize the clock with the network. Also note that, - strictly speaking, - <filename>systemd-timesyncd.service</filename> does more than - just network time synchronization, as it ensures a monotonic - clock on systems without RTC even if no network is - available. See - <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for details about this.</para></listitem> - </varlistentry> - - </variablelist> - - </refsect1> - - <refsect1> - <title>Exit status</title> - - <para>On success, 0 is returned, a non-zero failure - code otherwise.</para> - </refsect1> - - <xi:include href="less-variables.xml" /> - - <refsect1> - <title>Examples</title> - <para>Show current settings: - <programlisting>$ timedatectl - Local time: Di 2015-04-07 16:26:56 CEST - Universal time: Di 2015-04-07 14:26:56 UTC - RTC time: Di 2015-04-07 14:26:56 - Time zone: Europe/Berlin (CEST, +0200) - Network time on: yes -NTP synchronized: yes - RTC in local TZ: no</programlisting> - </para> - - <para>Enable network time synchronization: - <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 systemd-timesyncd.service -● systemd-timesyncd.service - Network Time Synchronization - Loaded: loaded (/usr/lib/systemd/system/systemd-timesyncd.service; enabled) - Active: active (running) since Mo 2015-03-30 14:20:38 CEST; 5s ago - Docs: man:systemd-timesyncd.service(8) - Main PID: 595 (systemd-timesyn) - Status: "Using Time Server 216.239.38.15:123 (time4.google.com)." - CGroup: /system.slice/systemd-timesyncd.service - └─595 /usr/lib/systemd/systemd-timesyncd -...</programlisting> - </para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='man-pages'><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>, - <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/timesyncd.conf.xml b/man/timesyncd.conf.xml deleted file mode 100644 index 8c86fd0074..0000000000 --- a/man/timesyncd.conf.xml +++ /dev/null @@ -1,112 +0,0 @@ -<?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 2014 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="timesyncd.conf" conditional='ENABLE_TIMESYNCD' - xmlns:xi="http://www.w3.org/2001/XInclude"> - <refentryinfo> - <title>timesyncd.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>timesyncd.conf</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>timesyncd.conf</refname> - <refname>timesyncd.conf.d</refname> - <refpurpose>Network Time Synchronization configuration files</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/etc/systemd/timesyncd.conf</filename></para> - <para><filename>/etc/systemd/timesyncd.conf.d/*.conf</filename></para> - <para><filename>/run/systemd/timesyncd.conf.d/*.conf</filename></para> - <para><filename>/usr/lib/systemd/timesyncd.conf.d/*.conf</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>These configuration files control NTP network time - synchronization.</para> - - </refsect1> - - <xi:include href="standard-conf.xml" xpointer="main-conf" /> - - <refsect1> - <title>Options</title> - - <para>The following settings are configured in the <literal>[Time]</literal> section:</para> - - <variablelist class='network-directives'> - - <varlistentry> - <term><varname>NTP=</varname></term> - <listitem><para>A space-separated list of NTP server host - names or IP addresses. During runtime this list is combined - with any per-interface NTP servers acquired from - <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. - systemd-timesyncd will contact all configured system or - per-interface servers in turn until one is found that - responds. This setting defaults to an empty - list.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>FallbackNTP=</varname></term> - <listitem><para>A space-separated list of NTP server host - names or IP addresses to be used as the fallback NTP servers. - Any per-interface NTP servers obtained from - <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - take precedence over this setting, as do any servers set via - <varname>NTP=</varname> above. This setting is hence only used - if no other NTP server information is known. If this option is - not given, a compiled-in list of NTP servers is used - instead.</para></listitem> - </varlistentry> - - </variablelist> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/tmpfiles.d.xml b/man/tmpfiles.d.xml deleted file mode 100644 index 957475d2bd..0000000000 --- a/man/tmpfiles.d.xml +++ /dev/null @@ -1,703 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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> - - <para>Volatile and temporary files and directories are those - located in <filename>/run</filename> (and its alias - <filename>/var/run</filename>), <filename>/tmp</filename>, - <filename>/var/tmp</filename>, the API file systems such as - <filename>/sys</filename> or <filename>/proc</filename>, as well - as some other directories below <filename>/var</filename>.</para> - - <para>System daemons frequently require private runtime - directories below <filename>/run</filename> to place communication - sockets and similar in. For these, consider declaring them in - their unit files using <varname>RuntimeDirectory=</varname> (see - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details), if this is feasible.</para> - </refsect1> - - <refsect1> - <title>Configuration Format</title> - - <para>Each configuration file shall be named in the style of - <filename><replaceable>package</replaceable>.conf</filename> or - <filename><replaceable>package</replaceable>-<replaceable>part</replaceable>.conf</filename>. - The second variant should be used when it is desirable to make it - easy to override just this part of configuration.</para> - - <para>Files in <filename>/etc/tmpfiles.d</filename> override files - with the same name in <filename>/usr/lib/tmpfiles.d</filename> and - <filename>/run/tmpfiles.d</filename>. Files in - <filename>/run/tmpfiles.d</filename> override files with the same - name in <filename>/usr/lib/tmpfiles.d</filename>. Packages should - install their configuration files in - <filename>/usr/lib/tmpfiles.d</filename>. Files in - <filename>/etc/tmpfiles.d</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 lexicographic - order, regardless of which of the directories they reside in. If - multiple files specify the same path, the entry in the file with - the lexicographically earliest name will be applied. All other - conflicting entries will be logged as errors. When two lines are - prefix and suffix of each other, then the prefix is always - processed first, the suffix later. Lines that take globs are - applied after those accepting no globs. If multiple operations - shall be applied on the same file, (such as ACL, xattr, file - attribute adjustments), these are always done in the same fixed - order. Otherwise, the files/directories are processed in the order - they are listed.</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 filename. - </para> - - <para>The configuration format is one line per path containing - type, 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> - - <para>Fields may be enclosed within quotes and contain C-style escapes.</para> - - <refsect2> - <title>Type</title> - - <para>The type consists of a single letter and optionally an - exclamation mark.</para> - - <para>The following line types are understood:</para> - - <variablelist> - <varlistentry> - <term><varname>f</varname></term> - <listitem><para>Create a file if it does not exist yet. If - the argument parameter is given, it will be written to the - file. Does not follow symlinks.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>F</varname></term> - <listitem><para>Create or truncate a file. If the argument - parameter is given, it will be written to the file. Does not follow symlinks.</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. Follows - symlinks.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>d</varname></term> - <listitem><para>Create a directory. The mode and ownership will be adjusted if - specified and the directory already exists. Contents of this directory are subject - to time based cleanup if the time argument is specified.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>D</varname></term> - <listitem><para>Similar to <varname>d</varname>, but in addition the contents - of the directory will be removed when <option>--remove</option> is used. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>e</varname></term> - <listitem><para>Similar to <varname>d</varname>, but the directory will not be - created if it does not exist. Lines of this type accept shell-style globs in - place of normal path names.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>v</varname></term> - <listitem><para>Create a subvolume if the path does not - exist yet, the file system supports subvolumes (btrfs), and - the system itself is installed into a subvolume - (specifically: the root directory <filename>/</filename> is - itself a subvolume). Otherwise, create a normal directory, in - the same way as <varname>d</varname>. A subvolume created - with this line type is not assigned to any higher-level - quota group. For that, use <varname>q</varname> or - <varname>Q</varname>, which allow creating simple quota - group hierarchies, see below.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>q</varname></term> - <listitem><para>Similar to <varname>v</varname>. However, - makes sure that the subvolume will be assigned to the same - higher-level quota groups as the subvolume it has been - created in. This ensures that higher-level limits and - accounting applied to the parent subvolume also include the - specified subvolume. On non-btrfs file systems, this line - type is identical to <varname>d</varname>. If the subvolume - already exists and is already assigned to one or more higher - level quota groups, no change to the quota hierarchy is - made. Also see <varname>Q</varname> below. See <citerefentry - project='die-net'><refentrytitle>btrfs-qgroup</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for details about the btrfs quota group - concept.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Q</varname></term> - <listitem><para>Similar to <varname>q</varname>. However, - instead of copying the higher-level quota group assignments - from the parent as-is, the lowest quota group of the parent - subvolume is determined that is not the leaf quota - group. Then, an "intermediary" quota group is inserted that - is one level below this level, and shares the same ID part - as the specified subvolume. If no higher-level quota group - exists for the parent subvolume, a new quota group at level - 255 sharing the same ID as the specified subvolume is - inserted instead. This new intermediary quota group is then - assigned to the parent subvolume's higher-level quota - groups, and the specified subvolume's leaf quota group is - assigned to it.</para> - - <para>Effectively, this has a similar effect as - <varname>q</varname>, however introduces a new higher-level - quota group for the specified subvolume that may be used to - enforce limits and accounting to the specified subvolume and - children subvolume created within it. Thus, by creating - subvolumes only via <varname>q</varname> and - <varname>Q</varname>, a concept of "subtree quotas" is - implemented. Each subvolume for which <varname>Q</varname> - is set will get a "subtree" quota group created, and all - child subvolumes created within it will be assigned to - it. Each subvolume for which <varname>q</varname> is set - will not get such a "subtree" quota group, but it is ensured - that they are added to the same "subtree" quota group as their - immediate parents.</para> - - <para>It is recommended to use - <varname>Q</varname> for subvolumes that typically contain - further subvolumes, and where it is desirable to have - accounting and quota limits on all child subvolumes - together. Examples for <varname>Q</varname> are typically - <filename>/home</filename> or - <filename>/var/lib/machines</filename>. In contrast, - <varname>q</varname> should be used for subvolumes that - either usually do not include further subvolumes or where no - accounting and quota limits are needed that apply to all - child subvolumes together. Examples for <varname>q</varname> - are typically <filename>/var</filename> or - <filename>/var/tmp</filename>. As with <varname>Q</varname>, - <varname>q</varname> has no effect on the quota group - hierarchy if the subvolume exists and already has at least - one higher-level quota group assigned.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>p</varname></term> - <term><varname>p+</varname></term> - <listitem><para>Create a named pipe (FIFO) if it does not - exist yet. If suffixed with <varname>+</varname> and a file - already exists where the pipe is to be created, it will be - removed and be replaced by the pipe.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>L</varname></term> - <term><varname>L+</varname></term> - <listitem><para>Create a symlink if it does not exist - yet. If suffixed with <varname>+</varname> and a file - already exists where the symlink is to be created, it will - be removed and be replaced by the symlink. If the argument - is omitted, symlinks to files with the same name residing in - the directory <filename>/usr/share/factory/</filename> are - created. Note that permissions and ownership on symlinks - are ignored.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>c</varname></term> - <term><varname>c+</varname></term> - <listitem><para>Create a character device node if it does - not exist yet. If suffixed with <varname>+</varname> and a - file already exists where the device node is to be created, - it will be removed and be replaced by the device node. It is - recommended to suffix this entry with an exclamation mark to - only create static device nodes at boot, as udev will not - manage static device nodes that are created at runtime. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>b</varname></term> - <term><varname>b+</varname></term> - <listitem><para>Create a block device node if it does not - exist yet. If suffixed with <varname>+</varname> and a file - already exists where the device node is to be created, it - will be removed and be replaced by the device node. It is - recommended to suffix this entry with an exclamation mark to - only create static device nodes at boot, as udev will not - manage static device nodes that are created at runtime. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>C</varname></term> - <listitem><para>Recursively copy a file or directory, if the - destination files or directories do not exist yet. Note that - this command will not descend into subdirectories if the - destination directory already exists. Instead, the entire - copy operation is skipped. If the argument is omitted, files - from the source directory - <filename>/usr/share/factory/</filename> with the same name - are copied. Does not follow symlinks.</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 <varname>r</varname> or <varname>R</varname> - lines. Lines of this type accept shell-style globs in place - of normal path names. </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. Unlike <varname>x</varname>, this parameter will - not exclude the content if path is a directory, but only - directory itself. Note that lines of this type do not - influence the effect of <varname>r</varname> or - <varname>R</varname> 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 - <varname>R</varname> for that. Lines of this type accept - shell-style globs in place of normal path - names. Does not follow symlinks.</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. Does not follow symlinks.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>z</varname></term> - <listitem><para>Adjust the access mode, group and user, and - restore the SELinux security context of a file or directory, - if it exists. Lines of this type accept shell-style globs in - place of normal path names. Does not follow symlinks.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Z</varname></term> - <listitem><para>Recursively set the access mode, group and - user, and restore the SELinux security context of a file or - directory if it exists, as well as of its subdirectories and - the files contained therein (if applicable). Lines of this - type accept shell-style globs in place of normal path - names. Does not follow symlinks. </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>t</varname></term> - <listitem><para>Set extended attributes. Lines of this type - accept shell-style globs in place of normal path names. - This can be useful for setting SMACK labels. Does not follow - symlinks.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>T</varname></term> - <listitem><para>Recursively set extended attributes. Lines - of this type accept shell-style globs in place of normal - path names. This can be useful for setting SMACK - labels. Does not follow symlinks. </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>h</varname></term> - <listitem><para>Set file/directory attributes. Lines of this type - accept shell-style globs in place of normal path names.</para> - - <para>The format of the argument field is - <varname>[+-=][aAcCdDeijsStTu] </varname>. The prefix - <varname>+</varname> (the default one) causes the - attribute(s) to be added; <varname>-</varname> causes the - attribute(s) to be removed; <varname>=</varname> causes the - attributes to be set exactly as the following letters. The - letters <literal>aAcCdDeijsStTu</literal> select the new - attributes for the files, see - <citerefentry project='man-pages'><refentrytitle>chattr</refentrytitle> - <manvolnum>1</manvolnum></citerefentry> for further information. - </para> - <para>Passing only <varname>=</varname> as argument resets - all the file attributes listed above. It has to be pointed - out that the <varname>=</varname> prefix limits itself to - the attributes corresponding to the letters listed here. All - other attributes will be left untouched. Does not follow - symlinks.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>H</varname></term> - <listitem><para>Recursively set file/directory attributes. Lines - of this type accept shell-style globs in place of normal - path names. Does not follow symlinks. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>a</varname></term> - <term><varname>a+</varname></term> - <listitem><para>Set POSIX ACLs (access control lists). If - suffixed with <varname>+</varname>, the specified entries will - be added to the existing set. - <command>systemd-tmpfiles</command> will automatically add - the required base entries for user and group based on the - access mode of the file, unless base entries already exist - or are explicitly specified. The mask will be added if not - specified explicitly or already present. Lines of this type - accept shell-style globs in place of normal path names. This - can be useful for allowing additional access to certain - files. Does not follow symlinks.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>A</varname></term> - <term><varname>A+</varname></term> - <listitem><para>Same as <varname>a</varname> and - <varname>a+</varname>, but recursive. Does not follow - symlinks.</para></listitem> - </varlistentry> - </variablelist> - - <para>If the exclamation mark is used, this line is only safe of - execute during boot, and can break a running system. Lines - without the exclamation mark are presumed to be safe to execute - at any time, e.g. on package upgrades. - <command>systemd-tmpfiles</command> will execute line with an - exclamation mark only if option <option>--boot</option> is - given.</para> - - <para>For example: - <programlisting># Make sure these are created by default so that nobody else can - d /tmp/.X11-unix 1777 root root 10d - - # Unlink the X11 lock files - r! /tmp/.X[0-9]*-lock</programlisting> - The second line in contrast to the first one would break a - running system, and will only be executed with - <option>--boot</option>.</para> - </refsect2> - - <refsect2> - <title>Path</title> - - <para>The file system path specification supports simple - specifier expansion. The following expansions are - understood:</para> - - <table> - <title>Specifiers available</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>%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 hostname of the running system.</entry> - </row> - <row> - <entry><literal>%v</literal></entry> - <entry>Kernel release</entry> - <entry>Identical to <command>uname -r</command> output.</entry> - </row> - <row> - <entry><literal>%%</literal></entry> - <entry>Escaped %</entry> - <entry>Single percent sign.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect2> - - <refsect2> - <title>Mode</title> - - <para>The file access mode to use when creating this file or - directory. If omitted or when set to <literal>-</literal>, the - default is used: 0755 for directories, 0644 for all other file - objects. For <varname>z</varname>, <varname>Z</varname> lines, - if omitted or when set to <literal>-</literal>, the file access - mode will not be modified. This parameter is ignored for - <varname>x</varname>, <varname>r</varname>, - <varname>R</varname>, <varname>L</varname>, <varname>t</varname>, - and <varname>a</varname> lines.</para> - - <para>Optionally, if prefixed with <literal>~</literal>, the - access mode is masked based on the already set access bits for - existing file or directories: if the existing file has all - executable bits unset, all executable bits are removed from the - new access mode, too. Similarly, if all read bits are removed - from the old access mode, they will be removed from the new - access mode too, and if all write bits are removed, they will be - removed from the new access mode too. In addition, the - sticky/SUID/SGID bit is removed unless applied to a - directory. This functionality is particularly useful in - conjunction with <varname>Z</varname>.</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 <literal>-</literal>, the - default 0 (root) is used. For <varname>z</varname> and - <varname>Z</varname> lines, when omitted or when set to - <literal>-</literal>, the file ownership will not be - modified. These parameters are ignored for <varname>x</varname>, - <varname>r</varname>, <varname>R</varname>, - <varname>L</varname>, <varname>t</varname>, and - <varname>a</varname> 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 suffixes for the respective time units: - <constant>s</constant>, - <constant>m</constant> or <constant>min</constant>, - <constant>h</constant>, - <constant>d</constant>, - <constant>w</constant>, - <constant>ms</constant>, and - <constant>us</constant>, - meaning seconds, minutes, hours, days, weeks, - milliseconds, and microseconds, respectively. Full names of the time units can - be used too. - </para> - - <para>If multiple integers and units are specified, the time - values are summed. If an integer is given without a unit, - <constant>s</constant> 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 - <varname>d</varname>, <varname>D</varname>, <varname>e</varname>, - <varname>v</varname>, <varname>q</varname>, - <varname>Q</varname>, <varname>C</varname>, <varname>x</varname> - and <varname>X</varname>. If omitted or set to - <literal>-</literal>, no automatic clean-up is done.</para> - - <para>If the age field starts with a tilde character - <literal>~</literal>, 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 <varname>L</varname> lines determines the destination - path of the symlink. For <varname>c</varname> and - <varname>b</varname>, determines the major/minor of the device - node, with major and minor formatted as integers, separated by - <literal>:</literal>, e.g. <literal>1:3</literal>. For - <varname>f</varname>, <varname>F</varname>, and - <varname>w</varname>, the argument may be used to specify a short string that - is written to the file, suffixed by a newline. For - <varname>C</varname>, specifies the source file or - directory. For <varname>t</varname> and <varname>T</varname>, - determines extended attributes to be set. For - <varname>a</varname> and <varname>A</varname>, determines ACL - attributes to be set. For <varname>h</varname> and - <varname>H</varname>, determines the file attributes to - set. Ignored for all other lines.</para> - </refsect2> - - </refsect1> - - <refsect1> - <title>Examples</title> - <example> - <title>Create directories with specific mode and ownership</title> - <para> - <citerefentry><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - needs two directories created at boot with specific modes and ownership:</para> - - <programlisting># /usr/lib/tmpfiles.d/screen.conf -d /run/screens 1777 root screen 10d -d /run/uscreens 0755 root screen 10d12h -</programlisting> - - <para>Contents of <filename>/run/screens</filename> and /run/uscreens will - cleaned up after 10 and 10½ days, respectively.</para> - </example> - - <example> - <title>Create a directory with a SMACK attribute</title> - <programlisting>D /run/cups - - - - -t /run/cups - - - - security.SMACK64=printing user.attr-with-spaces="foo bar" - </programlisting> - - <para>The direcory will be owned by root and have default mode. It's contents are - not subject to time based cleanup, but will be obliterated when - <command>systemd-tmpfiles --remove</command> runs.</para> - </example> - - <example> - <title>Create a directory and prevent its contents from cleanup</title> - <para> - <citerefentry><refentrytitle>abrt</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - needs a directory created at boot with specific mode and ownership and its content - should be preserved from the automatic cleanup applied to the contents of - <filename>/var/tmp</filename>:</para> - - <programlisting># /usr/lib/tmpfiles.d/tmp.conf -d /var/tmp 1777 root root 30d -</programlisting> - - <programlisting># /usr/lib/tmpfiles.d/abrt.conf -d /var/tmp/abrt 0755 abrt abrt - -</programlisting> - </example> - - <example> - <title>Apply clean up during boot and based on time</title> - - <programlisting># /usr/lib/tmpfiles.d/dnf.conf -r! /var/cache/dnf/*/*/download_lock.pid -r! /var/cache/dnf/*/*/metadata_lock.pid -r! /var/lib/dnf/rpmdb_lock.pid -e /var/chache/dnf/ - - - 30d -</programlisting> - - <para>The lock files will be removed during boot. Any files and directories in - <filename>/var/chache/dnf/</filename> will be removed after they have not been - accessed in 30 days.</para> - </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>, - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>attr</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>getfattr</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>setfattr</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>setfacl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>getfacl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>chattr</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>btrfs-subvolume</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>btrfs-qgroup</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/udev.conf.xml b/man/udev.conf.xml deleted file mode 100644 index e104e53f5d..0000000000 --- a/man/udev.conf.xml +++ /dev/null @@ -1,94 +0,0 @@ -<?xml version='1.0'?> -<!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 2014 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="udev.conf" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>udev.conf</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>udev.conf</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>udev.conf</refname> - <refpurpose>Configuration for device event managing daemon</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/etc/udev/udev.conf</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para> - <citerefentry><refentrytitle>systemd-udevd</refentrytitle><manvolnum>8</manvolnum></citerefentry> - 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. All empty lines or lines beginning with '#' are - ignored. The following variables can be set: - </para> - - <variablelist> - <varlistentry> - <term><varname>udev_log</varname></term> - - <listitem> - <para>The log level. 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> - - <para> - In addition, <filename>systemd-udevd</filename> can be configured - by command line options and the kernel command line (see - <citerefentry><refentrytitle>systemd-udevd</refentrytitle><manvolnum>8</manvolnum></citerefentry>). - </para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd-udevd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udevadm</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> -</refentry> diff --git a/man/udev.xml b/man/udev.xml deleted file mode 100644 index dd5563605c..0000000000 --- a/man/udev.xml +++ /dev/null @@ -1,755 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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>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>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 filenames 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>/usr/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>/usr/lib</filename>, pointing to <filename>/dev/null</filename>, - disables the rules file entirely. 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. - Except for empty lines or lines beginning with <literal>#</literal>, which are ignored. - There are two kinds of keys: match and assignment. - If all match keys match against their values, the rule gets applied and the - assignment keys get the specified values 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><literal>==</literal></term> - <listitem> - <para>Compare for equality.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>!=</literal></term> - <listitem> - <para>Compare for inequality.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>=</literal></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><literal>+=</literal></term> - <listitem> - <para>Add the value to a key that holds a list of entries.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>-=</literal></term> - <listitem> - <para>Remove the value from a key that holds a list of entries.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>:=</literal></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 class='udev-directives'> - <varlistentry> - <term><varname>ACTION</varname></term> - <listitem> - <para>Match the name of the event action.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>DEVPATH</varname></term> - <listitem> - <para>Match the devpath of the event device.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>KERNEL</varname></term> - <listitem> - <para>Match the name of the event device.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>NAME</varname></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><varname>SYMLINK</varname></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><varname>SUBSYSTEM</varname></term> - <listitem> - <para>Match the subsystem of the event device.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>DRIVER</varname></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><varname>ATTR{<replaceable>filename</replaceable>}</varname></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> - <term><varname>SYSCTL{<replaceable>kernel parameter</replaceable>}</varname></term> - <listitem> - <para>Match a kernel parameter value. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>KERNELS</varname></term> - <listitem> - <para>Search the devpath upwards for a matching device name.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>SUBSYSTEMS</varname></term> - <listitem> - <para>Search the devpath upwards for a matching device subsystem name.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>DRIVERS</varname></term> - <listitem> - <para>Search the devpath upwards for a matching device driver name.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>ATTRS{<replaceable>filename</replaceable>}</varname></term> - <listitem> - <para>Search the devpath upwards for a device with matching sysfs attribute values. - If multiple <varname>ATTRS</varname> 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><varname>TAGS</varname></term> - <listitem> - <para>Search the devpath upwards for a device with matching tag.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>ENV{<replaceable>key</replaceable>}</varname></term> - <listitem> - <para>Match against a device property value.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>TAG</varname></term> - <listitem> - <para>Match against a device tag.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>TEST{<replaceable>octal mode mask</replaceable>}</varname></term> - <listitem> - <para>Test the existence of a file. An octal mode mask can be specified - if needed.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>PROGRAM</varname></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 standard output - is available in the <varname>RESULT</varname> key.</para> - <para>This can only be used for very short-running foreground tasks. For details, - see <varname>RUN</varname>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>RESULT</varname></term> - <listitem> - <para>Match the returned string of the last <varname>PROGRAM</varname> call. - This key can be used in the same or in any later rule after a - <varname>PROGRAM</varname> call.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Most of the fields support shell glob pattern matching and - alternate patterns. The following special characters are supported:</para> - <variablelist> - <varlistentry> - <term><literal>*</literal></term> - <listitem> - <para>Matches zero or more characters.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>?</literal></term> - <listitem> - <para>Matches any single character.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>[]</literal></term> - <listitem> - <para>Matches any single character specified within the brackets. For - example, the pattern string <literal>tty[SR]</literal> - would match either <literal>ttyS</literal> or <literal>ttyR</literal>. - Ranges are also supported via the <literal>-</literal> character. - For example, to match on the range of all digits, the pattern - <literal>[0-9]</literal> could be used. If the first character - following the <literal>[</literal> is a <literal>!</literal>, - any characters not enclosed are matched.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>|</literal></term> - <listitem> - <para>Separates alternative patterns. For example, the pattern string - <literal>abc|x*</literal> would match either <literal>abc</literal> - or <literal>x*</literal>.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>The following keys can get values assigned:</para> - <variablelist class='udev-directives'> - <varlistentry> - <term><varname>NAME</varname></term> - <listitem> - <para>The name to use for a network interface. See - <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for a higher-level mechanism for setting the interface name. - The name of a device node cannot be changed by udev, only additional - symlinks can be created.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>SYMLINK</varname></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 <literal>0-9A-Za-z#+-.:=@_/</literal>, valid UTF-8 character - sequences, and <literal>\x00</literal> hex encoding. All other - characters are replaced by a <literal>_</literal> 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><varname>OWNER</varname>, <varname>GROUP</varname>, <varname>MODE</varname></term> - <listitem> - <para>The permissions for the device node. Every specified value overrides - the compiled-in default value.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>SECLABEL{<replaceable>module</replaceable>}</varname></term> - <listitem> - <para>Applies the specified Linux Security Module label to the device node.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>ATTR{<replaceable>key</replaceable>}</varname></term> - <listitem> - <para>The value that should be written to a sysfs attribute of the - event device.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>SYSCTL{<replaceable>kernel parameter</replaceable>}</varname></term> - <listitem> - <para>The value that should be written to kernel parameter.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>ENV{<replaceable>key</replaceable>}</varname></term> - <listitem> - <para>Set a device property value. Property names with a leading <literal>.</literal> - are neither stored in the database nor exported to events or - external tools (run by, for example, the <varname>PROGRAM</varname> - match key).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>TAG</varname></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><varname>RUN{<replaceable>type</replaceable>}</varname></term> - <listitem> - <para>Add a program to the list of programs to be executed after - processing all the rules for a specific event, depending on - <literal>type</literal>:</para> - <variablelist> - <varlistentry> - <term><literal>program</literal></term> - <listitem> - <para>Execute an external program specified as the assigned - value. If no absolute path is given, the program is expected - to live in <filename>/usr/lib/udev</filename>; otherwise, the - absolute path must be specified.</para> - <para>This is the default if no <replaceable>type</replaceable> - is specified.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>builtin</literal></term> - <listitem> - <para>As <varname>program</varname>, but use one of the - built-in programs rather than an external one.</para> - </listitem> - </varlistentry> - </variablelist> - <para>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><varname>LABEL</varname></term> - <listitem> - <para>A named label to which a <varname>GOTO</varname> may jump.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>GOTO</varname></term> - <listitem> - <para>Jumps to the next <varname>LABEL</varname> with a matching name.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>IMPORT{<replaceable>type</replaceable>}</varname></term> - <listitem> - <para>Import a set of variables as device properties, - depending on <literal>type</literal>:</para> - <variablelist> - <varlistentry> - <term><literal>program</literal></term> - <listitem> - <para>Execute an external program specified as the assigned - value and, if it returns successfully, - import its output, which must be in environment key - format. Path specification, command/argument separation, - and quoting work like in <varname>RUN</varname>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>builtin</literal></term> - <listitem> - <para>Similar to <literal>program</literal>, but use one of the - built-in programs rather than an external one.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>file</literal></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><literal>db</literal></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><literal>cmdline</literal></term> - <listitem> - <para>Import a single property from the kernel command line. For simple flags - the value of the property is set to <literal>1</literal>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>parent</literal></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 glob 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><varname>OPTIONS</varname></term> - <listitem> - <para>Rule and device options:</para> - <variablelist class='udev-directives'> - <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>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. Also, for every - tag specified in this rule, create a symlink - in the directory - <filename>/run/udev/static_node-tags/<replaceable>tag</replaceable></filename> - pointing at the static device node with the specified name. - Static device node creation is performed by systemd-tmpfiles - before systemd-udevd is started. The static nodes might not - have a corresponding kernel device; they are used to trigger - automatic kernel module loading when they are accessed.</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 <varname>NAME</varname>, <varname>SYMLINK</varname>, - <varname>PROGRAM</varname>, <varname>OWNER</varname>, - <varname>GROUP</varname>, <varname>MODE</varname>, and - <varname>RUN</varname> fields support simple string substitutions. - The <varname>RUN</varname> 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 class='udev-directives'> - <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, - <literal>sda3</literal> has kernel number <literal>3</literal>. - </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 <option>KERNELS</option>, - <option>SUBSYSTEMS</option>, <option>DRIVERS</option>, or - <option>ATTRS</option> 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 - <varname>PROGRAM</varname>. - A single part of the string, separated by a space character, may be selected - by specifying the part number as an attribute: <literal>%c{N}</literal>. - If the number is followed by the <literal>+</literal> character, this part plus all remaining parts - of the result string are substituted: <literal>%c{N+}</literal>.</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 <literal>%</literal> character itself.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>$$</option></term> - <listitem> - <para>The <literal>$</literal> character itself.</para> - </listitem> - </varlistentry> - </variablelist> - </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>, - <citerefentry> - <refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum> - </citerefentry> - </para> - </refsect1> -</refentry> diff --git a/man/udev_device_get_syspath.xml b/man/udev_device_get_syspath.xml deleted file mode 100644 index b54749ed56..0000000000 --- a/man/udev_device_get_syspath.xml +++ /dev/null @@ -1,207 +0,0 @@ -<?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" [ -<!ENTITY % entities SYSTEM "custom-entities.ent" > -%entities; -]> - -<!-- - This file is part of systemd. - - Copyright 2015 David Herrmann <dh.herrmann@gmail.com> - - 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="udev_device_get_syspath" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>udev_device_get_syspath</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>David</firstname> - <surname>Herrmann</surname> - <email>dh.herrmann@gmail.com</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>udev_device_get_syspath</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>udev_device_get_syspath</refname> - <refname>udev_device_get_sysname</refname> - <refname>udev_device_get_sysnum</refname> - <refname>udev_device_get_devpath</refname> - <refname>udev_device_get_devnode</refname> - <refname>udev_device_get_devnum</refname> - <refname>udev_device_get_devtype</refname> - <refname>udev_device_get_subsystem</refname> - <refname>udev_device_get_driver</refname> - <refname>udev_device_get_udev</refname> - <refname>udev_device_get_parent</refname> - <refname>udev_device_get_parent_with_subsystem_devtype</refname> - <refname>udev_device_get_is_initialized</refname> - <refname>udev_device_get_action</refname> - - <refpurpose>Query device properties</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <libudev.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>const char *<function>udev_device_get_syspath</function></funcdef> - <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>const char *<function>udev_device_get_sysname</function></funcdef> - <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>const char *<function>udev_device_get_sysnum</function></funcdef> - <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>const char *<function>udev_device_get_devpath</function></funcdef> - <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>const char *<function>udev_device_get_devnode</function></funcdef> - <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>dev_t <function>udev_device_get_devnum</function></funcdef> - <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>const char *<function>udev_device_get_devtype</function></funcdef> - <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>const char *<function>udev_device_get_subsystem</function></funcdef> - <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>const char *<function>udev_device_get_driver</function></funcdef> - <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>struct udev *<function>udev_device_get_udev</function></funcdef> - <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>struct udev_device *<function>udev_device_get_parent</function></funcdef> - <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>struct udev_device *<function>udev_device_get_parent_with_subsystem_devtype</function></funcdef> - <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> - <paramdef>const char *<parameter>subsystem</parameter></paramdef> - <paramdef>const char *<parameter>devtype</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>udev_device_get_is_initialized</function></funcdef> - <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>const char *<function>udev_device_get_action</function></funcdef> - <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <!--<refsect1> - <title>Description</title> - - <para>XXX: Add documentation.</para> - </refsect1>--> - - <refsect1> - <title>Return Value</title> - - <para>On success, <function>udev_device_get_syspath()</function>, - <function>udev_device_get_sysname()</function>, - <function>udev_device_get_sysnum()</function>, - <function>udev_device_get_devpath()</function>, - <function>udev_device_get_devnode()</function>, - <function>udev_device_get_devtype()</function>, - <function>udev_device_get_subsystem()</function>, - <function>udev_device_get_driver()</function> and - <function>udev_device_get_action()</function> return a pointer - to a constant string that describes the requested property. The - lifetime of this string is bound to the device it was requested - on. On failure, each function may return - <constant>NULL</constant>.</para> - - <para>On success, <function>udev_device_get_devnum()</function> - returns the device type of the passed device. On failure, a - device type with minor and major number set to - <constant>0</constant> is returned.</para> - - <para><function>udev_device_get_udev()</function> always returns - a valid pointer to the udev context that this device belongs - to.</para> - - <para>On success, <function>udev_device_get_parent()</function> - and - <function>udev_device_get_parent_with_subsystem_devtype()</function> - return a pointer to the parent device. No additional reference - to this device is acquired, but the child device owns a reference - to such a parent device. On failure, <constant>NULL</constant> - is returned.</para> - - <para>On success, <function>udev_device_get_is_initialized()</function> - returns either <constant>1</constant> or <constant>0</constant>, - depending on whether the passed device is initialized or not. On - failure, a negative error code is returned.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>udev_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_device_new_from_syspath</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_device_has_tag</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_enumerate_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_monitor_new_from_netlink</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_list_entry</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - </para> - </refsect1> - -</refentry> diff --git a/man/udev_device_has_tag.xml b/man/udev_device_has_tag.xml deleted file mode 100644 index 480257343c..0000000000 --- a/man/udev_device_has_tag.xml +++ /dev/null @@ -1,163 +0,0 @@ -<?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" [ -<!ENTITY % entities SYSTEM "custom-entities.ent" > -%entities; -]> - -<!-- - This file is part of systemd. - - Copyright 2015 David Herrmann <dh.herrmann@gmail.com> - - 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="udev_device_has_tag" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>udev_device_has_tag</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>David</firstname> - <surname>Herrmann</surname> - <email>dh.herrmann@gmail.com</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>udev_device_has_tag</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>udev_device_has_tag</refname> - <refname>udev_device_get_devlinks_list_entry</refname> - <refname>udev_device_get_properties_list_entry</refname> - <refname>udev_device_get_tags_list_entry</refname> - <refname>udev_device_get_sysattr_list_entry</refname> - <refname>udev_device_get_property_value</refname> - <refname>udev_device_get_sysattr_value</refname> - <refname>udev_device_set_sysattr_value</refname> - - <refpurpose>Retrieve or set device attributes</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <libudev.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>struct udev_list_entry *<function>udev_device_get_devlinks_list_entry</function></funcdef> - <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>struct udev_list_entry *<function>udev_device_get_properties_list_entry</function></funcdef> - <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>struct udev_list_entry *<function>udev_device_get_tags_list_entry</function></funcdef> - <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>struct udev_list_entry *<function>udev_device_get_sysattr_list_entry</function></funcdef> - <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>const char *<function>udev_device_get_property_value</function></funcdef> - <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> - <paramdef>const char *<parameter>key</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>udev_device_has_tag</function></funcdef> - <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> - <paramdef>const char *<parameter>tag</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>const char *<function>udev_device_get_sysattr_value</function></funcdef> - <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> - <paramdef>const char *<parameter>sysattr</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>udev_device_set_sysattr_value</function></funcdef> - <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> - <paramdef>const char *<parameter>sysattr</parameter></paramdef> - <paramdef>const char *<parameter>value</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <!--<refsect1> - <title>Description</title> - - <para>XXX: Add short description.</para> - </refsect1>--> - - <refsect1> - <title>Return Value</title> - - <para>On success, - <function>udev_device_get_devlinks_list_entry()</function>, - <function>udev_device_get_properties_list_entry()</function>, - <function>udev_device_get_tags_list_entry()</function> and - <function>udev_device_get_sysattr_list_entry()</function> return - a pointer to the first entry of the retrieved list. If that list - is empty, or if an error occurred, <constant>NULL</constant> is - returned.</para> - - <para>On success, - <function>udev_device_get_property_value()</function> and - <function>udev_device_get_sysattr_value()</function> return a - pointer to a constant string of the requested value. On error, - <constant>NULL</constant> is returned.</para> - - <para>On success, - <function>udev_device_set_sysattr_value()</function> returns - an integer greater than, or equal to, <constant>0</constant>. - On failure, a negative error code is returned.</para> - - <para>On success, <function>udev_device_has_tag()</function> - returns <constant>1</constant> or <constant>0</constant>, - depending on whether the device has the given tag or not. - On failure, a negative error code is returned.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>udev_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_device_new_from_syspath</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_device_get_syspath</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_enumerate_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_monitor_new_from_netlink</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_list_entry</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - </para> - </refsect1> - -</refentry> diff --git a/man/udev_device_new_from_syspath.xml b/man/udev_device_new_from_syspath.xml deleted file mode 100644 index 0bb71c8e91..0000000000 --- a/man/udev_device_new_from_syspath.xml +++ /dev/null @@ -1,214 +0,0 @@ -<?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" [ -<!ENTITY % entities SYSTEM "custom-entities.ent" > -%entities; -]> - -<!-- - This file is part of systemd. - - Copyright 2015 David Herrmann <dh.herrmann@gmail.com> - - 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="udev_device_new_from_syspath" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>udev_device_new_from_syspath</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>David</firstname> - <surname>Herrmann</surname> - <email>dh.herrmann@gmail.com</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>udev_device_new_from_syspath</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>udev_device_new_from_syspath</refname> - <refname>udev_device_new_from_devnum</refname> - <refname>udev_device_new_from_subsystem_sysname</refname> - <refname>udev_device_new_from_device_id</refname> - <refname>udev_device_new_from_environment</refname> - <refname>udev_device_ref</refname> - <refname>udev_device_unref</refname> - - <refpurpose>Create, acquire and release a udev device object</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <libudev.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>struct udev_device *<function>udev_device_new_from_syspath</function></funcdef> - <paramdef>struct udev *<parameter>udev</parameter></paramdef> - <paramdef>const char *<parameter>syspath</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>struct udev_device *<function>udev_device_new_from_devnum</function></funcdef> - <paramdef>struct udev *<parameter>udev</parameter></paramdef> - <paramdef>char <parameter>type</parameter></paramdef> - <paramdef>dev_t <parameter>devnum</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>struct udev_device *<function>udev_device_new_from_subsystem_sysname</function></funcdef> - <paramdef>struct udev *<parameter>udev</parameter></paramdef> - <paramdef>const char *<parameter>subsystem</parameter></paramdef> - <paramdef>const char *<parameter>sysname</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>struct udev_device *<function>udev_device_new_from_device_id</function></funcdef> - <paramdef>struct udev *<parameter>udev</parameter></paramdef> - <paramdef>const char *<parameter>id</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>struct udev_device *<function>udev_device_new_from_environment</function></funcdef> - <paramdef>struct udev *<parameter>udev</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>struct udev_device *<function>udev_device_ref</function></funcdef> - <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>struct udev_device *<function>udev_device_unref</function></funcdef> - <paramdef>struct udev_device *<parameter>udev_device</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>udev_device_new_from_syspath</function>, - <function>udev_device_new_from_devnum</function>, - <function>udev_device_new_from_subsystem_sysname</function>, - <function>udev_device_new_from_device_id</function>, and - <function>udev_device_new_from_environment</function> - allocate a new udev device object and returns a pointer to it. This - object is opaque and must not be accessed by the caller via different - means than functions provided by libudev. Initially, the reference count - of the device is 1. You can acquire further references, and drop - gained references via <function>udev_device_ref()</function> and - <function>udev_device_unref()</function>. Once the reference count hits 0, - the device object is destroyed and freed.</para> - - <para><function>udev_device_new_from_syspath</function>, - <function>udev_device_new_from_devnum</function>, - <function>udev_device_new_from_subsystem_sysname</function>, and - <function>udev_device_new_from_device_id</function> - create the device object based on information found in - <filename>/sys</filename>, annotated with properties from the udev-internal - device database. A syspath is any subdirectory of <filename>/sys</filename>, - with the restriction that a subdirectory of <filename>/sys/devices</filename> - (or a symlink to one) represents a real device and as such must contain - a <filename>uevent</filename> file. <function>udev_device_new_from_devnum</function> - takes a device type, which can be <constant>b</constant> for block devices or - <constant>c</constant> for character devices, as well as a devnum (see - <citerefentry project='man-pages'><refentrytitle>makedev</refentrytitle><manvolnum>3</manvolnum></citerefentry>). - <function>udev_device_new_from_subsystem_sysname</function> looks up devices based - on the provided subsystem and sysname - (see <citerefentry><refentrytitle>udev_device_get_subsystem</refentrytitle><manvolnum>3</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>udev_device_get_sysname</refentrytitle><manvolnum>3</manvolnum></citerefentry>) - and <function>udev_device_new_from_device_id</function> looks up devices based on the provided - device ID, which is a special string in one of the following four forms: - <table> - <title>Device ID strings</title> - - <tgroup cols='2'> - <colspec colname='example' /> - <colspec colname='explanation' /> - <thead><row> - <entry>Example</entry> - <entry>Explanation</entry> - </row></thead> - <tbody> - <row><entry><varname>b8:2</varname></entry> - <entry>block device major:minor</entry></row> - - <row><entry><varname>c128:1</varname></entry> - <entry>char device major:minor</entry></row> - - <row><entry><varname>n3</varname></entry> - <entry>network device ifindex</entry></row> - - <row><entry><varname>+sound:card29</varname></entry> - <entry>kernel driver core subsystem:device name</entry></row> - </tbody> - </tgroup> - </table> - </para> - - <para><function>udev_device_new_from_environment</function> - creates a device from the current environment (see - <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>). - Each key-value pair is interpreted in the same way as if it was - received in an uevent (see - <citerefentry><refentrytitle>udev_monitor_receive_device</refentrytitle><manvolnum>3</manvolnum></citerefentry>). - The keys <constant>DEVPATH</constant>, <constant>SUBSYSTEM</constant>, - <constant>ACTION</constant>, and <constant>SEQNUM</constant> are mandatory.</para> - - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, <function>udev_device_new_from_syspath()</function>, - <function>udev_device_new_from_devnum()</function>, - <function>udev_device_new_from_subsystem_sysname()</function>, - <function>udev_device_new_from_device_id()</function> and - <function>udev_device_new_from_environment()</function> return a - pointer to the allocated udev device. On failure, - <constant>NULL</constant> is returned, - and <varname>errno</varname> is set appropriately. - <function>udev_device_ref()</function> returns the argument - that it was passed, unmodified. - <function>udev_device_unref()</function> always returns - <constant>NULL</constant>.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>udev_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_device_get_syspath</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_device_has_tag</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_enumerate_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_monitor_new_from_netlink</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_list_entry</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - </para> - </refsect1> - -</refentry> diff --git a/man/udev_enumerate_add_match_subsystem.xml b/man/udev_enumerate_add_match_subsystem.xml deleted file mode 100644 index 5acce00bb0..0000000000 --- a/man/udev_enumerate_add_match_subsystem.xml +++ /dev/null @@ -1,163 +0,0 @@ -<?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" [ -<!ENTITY % entities SYSTEM "custom-entities.ent" > -%entities; -]> - -<!-- - This file is part of systemd. - - Copyright 2015 David Herrmann <dh.herrmann@gmail.com> - - 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="udev_enumerate_add_match_subsystem" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>udev_enumerate_add_match_subsystem</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>David</firstname> - <surname>Herrmann</surname> - <email>dh.herrmann@gmail.com</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>udev_enumerate_add_match_subsystem</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>udev_enumerate_add_match_subsystem</refname> - <refname>udev_enumerate_add_nomatch_subsystem</refname> - <refname>udev_enumerate_add_match_sysattr</refname> - <refname>udev_enumerate_add_nomatch_sysattr</refname> - <refname>udev_enumerate_add_match_property</refname> - <refname>udev_enumerate_add_match_sysname</refname> - <refname>udev_enumerate_add_match_tag</refname> - <refname>udev_enumerate_add_match_parent</refname> - <refname>udev_enumerate_add_match_is_initialized</refname> - - <refpurpose>Modify filters</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <libudev.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>udev_enumerate_add_match_subsystem</function></funcdef> - <paramdef>struct udev_enumerate *<parameter>udev_enumerate</parameter></paramdef> - <paramdef>const char *<parameter>subsystem</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>udev_enumerate_add_nomatch_subsystem</function></funcdef> - <paramdef>struct udev_enumerate *<parameter>udev_enumerate</parameter></paramdef> - <paramdef>const char *<parameter>subsystem</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>udev_enumerate_add_match_sysattr</function></funcdef> - <paramdef>struct udev_enumerate *<parameter>udev_enumerate</parameter></paramdef> - <paramdef>const char *<parameter>sysattr</parameter></paramdef> - <paramdef>const char *<parameter>value</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>udev_enumerate_add_nomatch_sysattr</function></funcdef> - <paramdef>struct udev_enumerate *<parameter>udev_enumerate</parameter></paramdef> - <paramdef>const char *<parameter>sysattr</parameter></paramdef> - <paramdef>const char *<parameter>value</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>udev_enumerate_add_match_property</function></funcdef> - <paramdef>struct udev_enumerate *<parameter>udev_enumerate</parameter></paramdef> - <paramdef>const char *<parameter>property</parameter></paramdef> - <paramdef>const char *<parameter>value</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>udev_enumerate_add_match_sysname</function></funcdef> - <paramdef>struct udev_enumerate *<parameter>udev_enumerate</parameter></paramdef> - <paramdef>const char *<parameter>sysname</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>udev_enumerate_add_match_tag</function></funcdef> - <paramdef>struct udev_enumerate *<parameter>udev_enumerate</parameter></paramdef> - <paramdef>const char *<parameter>tag</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>udev_enumerate_add_match_parent</function></funcdef> - <paramdef>struct udev_enumerate *<parameter>udev_enumerate</parameter></paramdef> - <paramdef>struct udev_device *<parameter>parent</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>udev_enumerate_add_match_is_initialized</function></funcdef> - <paramdef>struct udev_enumerate *<parameter>udev_enumerate</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <!--<refsect1> - <title>Description</title> - - <para>XXX: Add short description.</para> - </refsect1>--> - - <refsect1> - <title>Return Value</title> - - <para>On success, - <function>udev_enumerate_add_match_subsystem</function>, - <function>udev_enumerate_add_nomatch_subsystem</function>, - <function>udev_enumerate_add_match_sysattr</function>, - <function>udev_enumerate_add_nomatch_sysattr</function>, - <function>udev_enumerate_add_match_property</function>, - <function>udev_enumerate_add_match_sysname</function>, - <function>udev_enumerate_add_match_tag</function>, - <function>udev_enumerate_add_match_parent</function> and - <function>udev_enumerate_add_match_is_initialized</function> - return an integer greater than, or equal to, - <constant>0</constant>.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>udev_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_device_new_from_syspath</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_enumerate_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_enumerate_scan_devices</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_monitor_new_from_netlink</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_list_entry</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - </para> - </refsect1> - -</refentry> diff --git a/man/udev_enumerate_new.xml b/man/udev_enumerate_new.xml deleted file mode 100644 index b5856c5577..0000000000 --- a/man/udev_enumerate_new.xml +++ /dev/null @@ -1,111 +0,0 @@ -<?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" [ -<!ENTITY % entities SYSTEM "custom-entities.ent" > -%entities; -]> - -<!-- - This file is part of systemd. - - Copyright 2015 David Herrmann <dh.herrmann@gmail.com> - - 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="udev_enumerate_new" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>udev_enumerate_new</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>David</firstname> - <surname>Herrmann</surname> - <email>dh.herrmann@gmail.com</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>udev_enumerate_new</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>udev_enumerate_new</refname> - <refname>udev_enumerate_ref</refname> - <refname>udev_enumerate_unref</refname> - - <refpurpose>Create, acquire and release a udev enumerate object</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <libudev.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>struct udev_enumerate *<function>udev_enumerate_new</function></funcdef> - <paramdef>struct udev *<parameter>udev</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>struct udev_enumerate *<function>udev_enumerate_ref</function></funcdef> - <paramdef>struct udev_enumerate *<parameter>udev_enumerate</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>struct udev_enumerate *<function>udev_enumerate_unref</function></funcdef> - <paramdef>struct udev_enumerate *<parameter>udev_enumerate</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <!--<refsect1> - <title>Description</title> - - <para>XXX: Add short description.</para> - </refsect1>--> - - <refsect1> - <title>Return Value</title> - - <para>On success, <function>udev_enumerate_new()</function> returns a - pointer to the allocated udev monitor. On failure, - <constant>NULL</constant> is returned. - <function>udev_enumerate_ref()</function> returns the argument - that it was passed, unmodified. - <function>udev_enumerate_unref()</function> always returns - <constant>NULL</constant>.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>udev_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_device_new_from_syspath</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_enumerate_add_match_subsystem</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_enumerate_scan_devices</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_monitor_new_from_netlink</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_list_entry</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - </para> - </refsect1> - -</refentry> diff --git a/man/udev_enumerate_scan_devices.xml b/man/udev_enumerate_scan_devices.xml deleted file mode 100644 index e0b6bfba32..0000000000 --- a/man/udev_enumerate_scan_devices.xml +++ /dev/null @@ -1,133 +0,0 @@ -<?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" [ -<!ENTITY % entities SYSTEM "custom-entities.ent" > -%entities; -]> - -<!-- - This file is part of systemd. - - Copyright 2015 David Herrmann <dh.herrmann@gmail.com> - - 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="udev_enumerate_scan_devices" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>udev_enumerate_scan_devices</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>David</firstname> - <surname>Herrmann</surname> - <email>dh.herrmann@gmail.com</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>udev_enumerate_scan_devices</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>udev_enumerate_scan_devices</refname> - <refname>udev_enumerate_scan_subsystems</refname> - <refname>udev_enumerate_get_list_entry</refname> - <refname>udev_enumerate_add_syspath</refname> - <refname>udev_enumerate_get_udev</refname> - - <refpurpose>Query or modify a udev enumerate object</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <libudev.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>udev_enumerate_scan_devices</function></funcdef> - <paramdef>struct udev_enumerate *<parameter>udev_enumerate</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>udev_enumerate_scan_subsystems</function></funcdef> - <paramdef>struct udev_enumerate *<parameter>udev_enumerate</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>struct udev_list_entry *<function>udev_enumerate_get_list_entry</function></funcdef> - <paramdef>struct udev_enumerate *<parameter>udev_enumerate</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>udev_enumerate_add_syspath</function></funcdef> - <paramdef>struct udev_enumerate *<parameter>udev_enumerate</parameter></paramdef> - <paramdef>const char *<parameter>syspath</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>struct udev *<function>udev_enumerate_get_udev</function></funcdef> - <paramdef>struct udev_enumerate *<parameter>udev_enumerate</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <!--<refsect1> - <title>Description</title> - - <para>XXX: Add short description.</para> - </refsect1>--> - - <refsect1> - <title>Return Value</title> - - <para>On success, - <function>udev_enumerate_scan_devices()</function>, - <function>udev_enumerate_scan_subsystems()</function> and - <function>udev_enumerate_add_syspath()</function> - return an integer greater than, or equal to, - <constant>0</constant>.</para> - - <para>On success, - <function>udev_enumerate_get_list_entry()</function> - returns a pointer to the first entry in the list of found - devices. If the list is empty, or on failure, - <constant>NULL</constant> is returned.</para> - - <para><function>udev_enumerate_get_udev()</function> always - returns a pointer to the udev context that this enumerated - object is associated with.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>udev_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_device_new_from_syspath</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_enumerate_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_enumerate_add_match_subsystem</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_monitor_new_from_netlink</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_list_entry</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - </para> - </refsect1> - -</refentry> diff --git a/man/udev_list_entry.xml b/man/udev_list_entry.xml deleted file mode 100644 index a1b531d52a..0000000000 --- a/man/udev_list_entry.xml +++ /dev/null @@ -1,123 +0,0 @@ -<?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" [ -<!ENTITY % entities SYSTEM "custom-entities.ent" > -%entities; -]> - -<!-- - This file is part of systemd. - - Copyright 2015 David Herrmann <dh.herrmann@gmail.com> - - 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="udev_list_entry" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>udev_list_entry</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>David</firstname> - <surname>Herrmann</surname> - <email>dh.herrmann@gmail.com</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>udev_list_entry</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>udev_list_entry</refname> - <refname>udev_list_entry_get_next</refname> - <refname>udev_list_entry_get_by_name</refname> - <refname>udev_list_entry_get_name</refname> - <refname>udev_list_entry_get_value</refname> - - <refpurpose>Iterate and access udev lists</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <libudev.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>struct udev_list_entry *<function>udev_list_entry_get_next</function></funcdef> - <paramdef>struct udev_list_entry *<parameter>list_entry</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>struct udev_list_entry *<function>udev_list_entry_get_by_name</function></funcdef> - <paramdef>struct udev_list_entry *<parameter>list_entry</parameter></paramdef> - <paramdef>const char *<parameter>name</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>const char *<function>udev_list_entry_get_name</function></funcdef> - <paramdef>struct udev_list_entry *<parameter>list_entry</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>const char *<function>udev_list_entry_get_value</function></funcdef> - <paramdef>struct udev_list_entry *<parameter>list_entry</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <!--<refsect1> - <title>Description</title> - - <para>XXX: Add short description.</para> - </refsect1>--> - - <refsect1> - <title>Return Value</title> - - <para>On success, - <function>udev_list_entry_get_next()</function> and - <function>udev_list_entry_get_by_name()</function> return - a pointer to the requested list entry. If no such entry can - be found, or on failure, <constant>NULL</constant> is - returned.</para> - - <para>On success, - <function>udev_list_entry_get_name()</function> and - <function>udev_list_entry_get_value()</function> return a - pointer to a constant string representing the requested value. - The string is bound to the lifetime of the list entry itself. - On failure, <constant>NULL</constant> is returned.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>udev_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_device_new_from_syspath</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_enumerate_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_monitor_new_from_netlink</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - </para> - </refsect1> - -</refentry> diff --git a/man/udev_monitor_filter_update.xml b/man/udev_monitor_filter_update.xml deleted file mode 100644 index f129595618..0000000000 --- a/man/udev_monitor_filter_update.xml +++ /dev/null @@ -1,122 +0,0 @@ -<?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" [ -<!ENTITY % entities SYSTEM "custom-entities.ent" > -%entities; -]> - -<!-- - This file is part of systemd. - - Copyright 2015 David Herrmann <dh.herrmann@gmail.com> - - 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="udev_monitor_filter_update" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>udev_monitor_filter_update</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>David</firstname> - <surname>Herrmann</surname> - <email>dh.herrmann@gmail.com</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>udev_monitor_filter_update</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>udev_monitor_filter_update</refname> - <refname>udev_monitor_filter_remove</refname> - <refname>udev_monitor_filter_add_match_subsystem_devtype</refname> - <refname>udev_monitor_filter_add_match_tag</refname> - - <refpurpose>Modify filters</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <libudev.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>udev_monitor_filter_update</function></funcdef> - <paramdef>struct udev_monitor *<parameter>udev_monitor</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>udev_monitor_filter_remove</function></funcdef> - <paramdef>struct udev_monitor *<parameter>udev_monitor</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>udev_monitor_filter_add_match_subsystem_devtype</function></funcdef> - <paramdef>struct udev_monitor *<parameter>udev_monitor</parameter></paramdef> - <paramdef>const char *<parameter>subsystem</parameter></paramdef> - <paramdef>const char *<parameter>devtype</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>udev_monitor_filter_add_match_tag</function></funcdef> - <paramdef>struct udev_monitor *<parameter>udev_monitor</parameter></paramdef> - <paramdef>const char *<parameter>tag</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <!--<refsect1> - <title>Description</title> - - <para>XXX: Add short description.</para> - </refsect1>--> - - <refsect1> - <title>Return Value</title> - - <para>On success, - <function>udev_monitor_filter_update()</function>, - <function>udev_monitor_filter_remove()</function>, - <function>udev_monitor_filter_add_match_subsystem_devtype()</function> - and - <function>udev_monitor_filter_add_match_tag()</function> - return an integer greater than, or equal to, - <constant>0</constant>. On failure, a negative error code is - returned.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>udev_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_device_new_from_syspath</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_enumerate_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_monitor_new_from_netlink</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_monitor_receive_device</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_list_entry</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - </para> - </refsect1> - -</refentry> diff --git a/man/udev_monitor_new_from_netlink.xml b/man/udev_monitor_new_from_netlink.xml deleted file mode 100644 index d73a4acaec..0000000000 --- a/man/udev_monitor_new_from_netlink.xml +++ /dev/null @@ -1,113 +0,0 @@ -<?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" [ -<!ENTITY % entities SYSTEM "custom-entities.ent" > -%entities; -]> - -<!-- - This file is part of systemd. - - Copyright 2015 David Herrmann <dh.herrmann@gmail.com> - - 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="udev_monitor_new_from_netlink" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>udev_monitor_new_from_netlink</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>David</firstname> - <surname>Herrmann</surname> - <email>dh.herrmann@gmail.com</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>udev_monitor_new_from_netlink</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>udev_monitor_new_from_netlink</refname> - <refname>udev_monitor_ref</refname> - <refname>udev_monitor_unref</refname> - - <refpurpose>Create, acquire and release a udev monitor object</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <libudev.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>struct udev_monitor *<function>udev_monitor_new_from_netlink</function></funcdef> - <paramdef>struct udev *<parameter>udev</parameter></paramdef> - <paramdef>const char *<parameter>name</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>struct udev_monitor *<function>udev_monitor_ref</function></funcdef> - <paramdef>struct udev_monitor *<parameter>udev_monitor</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>struct udev_monitor *<function>udev_monitor_unref</function></funcdef> - <paramdef>struct udev_monitor *<parameter>udev_monitor</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <!--<refsect1> - <title>Description</title> - - <para>XXX: Add short description.</para> - </refsect1>--> - - <refsect1> - <title>Return Value</title> - - <para>On success, - <function>udev_monitor_new_from_netlink()</function> returns a - pointer to the allocated udev monitor. On failure, - <constant>NULL</constant> is returned. - <function>udev_monitor_ref()</function> returns the argument - that it was passed, unmodified. - <function>udev_monitor_unref()</function> always returns - <constant>NULL</constant>.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>udev_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_device_new_from_syspath</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_enumerate_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_monitor_filter_update</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_monitor_receive_device</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_list_entry</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - </para> - </refsect1> - -</refentry> diff --git a/man/udev_monitor_receive_device.xml b/man/udev_monitor_receive_device.xml deleted file mode 100644 index 7e842f88df..0000000000 --- a/man/udev_monitor_receive_device.xml +++ /dev/null @@ -1,137 +0,0 @@ -<?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" [ -<!ENTITY % entities SYSTEM "custom-entities.ent" > -%entities; -]> - -<!-- - This file is part of systemd. - - Copyright 2015 David Herrmann <dh.herrmann@gmail.com> - - 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="udev_monitor_receive_device" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>udev_monitor_receive_device</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>David</firstname> - <surname>Herrmann</surname> - <email>dh.herrmann@gmail.com</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>udev_monitor_receive_device</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>udev_monitor_receive_device</refname> - <refname>udev_monitor_enable_receiving</refname> - <refname>udev_monitor_set_receive_buffer_size</refname> - <refname>udev_monitor_get_fd</refname> - <refname>udev_monitor_get_udev</refname> - - <refpurpose>Query and modify device monitor</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <libudev.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>struct udev_device *<function>udev_monitor_receive_device</function></funcdef> - <paramdef>struct udev_monitor *<parameter>udev_monitor</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>udev_monitor_enable_receiving</function></funcdef> - <paramdef>struct udev_monitor *<parameter>udev_monitor</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>udev_monitor_set_receive_buffer_size</function></funcdef> - <paramdef>struct udev_monitor *<parameter>udev_monitor</parameter></paramdef> - <paramdef>int <parameter>size</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>udev_monitor_get_fd</function></funcdef> - <paramdef>struct udev_monitor *<parameter>udev_monitor</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>struct udev *<function>udev_monitor_get_udev</function></funcdef> - <paramdef>struct udev_monitor *<parameter>udev_monitor</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <!--<refsect1> - <title>Description</title> - - <para>XXX: Add short description.</para> - </refsect1>--> - - <refsect1> - <title>Return Value</title> - - <para>On success, - <function>udev_monitor_receive_device()</function> returns a - pointer to a newly referenced device that was received via the - monitor. The caller is responsible to drop this reference when - done. On failure, <constant>NULL</constant> is returned.</para> - - <para>On success, - <function>udev_monitor_enable_receiving()</function> and - <function>udev_monitor_set_receive_buffer_size()</function> - return an integer greater than, or equal to, - <constant>0</constant>. On failure, a negative error code is - returned.</para> - - <para>On success, <function>udev_monitor_get_fd()</function> - returns the file descriptor used by this monitor. On failure, - a negative error code is returned.</para> - - <para><function>udev_monitor_get_udev()</function> always returns - a pointer to the udev context that this monitor is associated - with.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>udev_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_device_new_from_syspath</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_enumerate_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_monitor_new_from_netlink</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_monitor_filter_update</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev_list_entry</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - </para> - </refsect1> - -</refentry> diff --git a/man/udev_new.xml b/man/udev_new.xml deleted file mode 100644 index 587835a3ca..0000000000 --- a/man/udev_new.xml +++ /dev/null @@ -1,110 +0,0 @@ -<?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" [ -<!ENTITY % entities SYSTEM "custom-entities.ent" > -%entities; -]> - -<!-- - This file is part of systemd. - - Copyright 2015 David Herrmann <dh.herrmann@gmail.com> - - 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="udev_new" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>udev_new</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>David</firstname> - <surname>Herrmann</surname> - <email>dh.herrmann@gmail.com</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>udev_new</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>udev_new</refname> - <refname>udev_ref</refname> - <refname>udev_unref</refname> - - <refpurpose>Create, acquire and release a udev context object</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <libudev.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>struct udev *<function>udev_new</function></funcdef> - <paramdef><parameter>void</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>struct udev *<function>udev_ref</function></funcdef> - <paramdef>struct udev *<parameter>udev</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>struct udev *<function>udev_unref</function></funcdef> - <paramdef>struct udev *<parameter>udev</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>udev_new()</function> allocates a new udev context - object and returns a pointer to it. This object is opaque and must - not be accessed by the caller via different means than functions - provided by libudev. Initially, the reference count of the context - is 1. You can acquire further references, and drop gained references - via <function>udev_ref()</function> and - <function>udev_unref()</function>. Once the reference count hits 0, - the context object is destroyed and freed.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, <function>udev_new()</function> returns a pointer - to the allocated udev context. On failure, <constant>NULL</constant> - is returned. <function>udev_ref()</function> returns the argument - that it was passed, unmodified. <function>udev_unref()</function> - always returns <constant>NULL</constant>.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - </para> - </refsect1> - -</refentry> diff --git a/man/udevadm.xml b/man/udevadm.xml deleted file mode 100644 index 8c1abd2770..0000000000 --- a/man/udevadm.xml +++ /dev/null @@ -1,576 +0,0 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!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> - </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 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><command>udevadm</command> expects a command and command - specific options. It controls the runtime behavior of - <command>systemd-udevd</command>, 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 standard error.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--version</option></term> - <listitem> - <para>Print version number.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>-h</option></term> - <term><option>--help</option></term> - <listitem> - <para>Print help text.</para> - </listitem> - </varlistentry> - </variablelist> - - <refsect2><title>udevadm info - <arg choice="opt"><replaceable>options</replaceable></arg> - <arg choice="opt"><replaceable>devpath</replaceable>|<replaceable>file</replaceable></arg> - </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>-q</option></term> - <term><option>--query=<replaceable>TYPE</replaceable></option></term> - <listitem> - <para>Query the database for the specified type of device - data. It needs the <option>--path</option> or - <option>--name</option> to identify the specified device. - Valid <replaceable>TYPE</replaceable>s are: - <constant>name</constant>, <constant>symlink</constant>, - <constant>path</constant>, <constant>property</constant>, - <constant>all</constant>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>-p</option></term> - <term><option>--path=<replaceable>DEVPATH</replaceable></option></term> - <listitem> - <para>The <filename>/sys</filename> path of the device to - query, e.g. - <filename><optional>/sys</optional>/class/block/sda</filename>. - Note that this option usually is not very useful, since - <command>udev</command> can guess the type of the - argument, so <command>udevadm - --devpath=/class/block/sda</command> is equivalent to - <command>udevadm /sys/class/block/sda</command>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>-n</option></term> - <term><option>--name=<replaceable>FILE</replaceable></option></term> - <listitem> - <para>The name of the device node or a symlink to query, - e.g. <filename><optional>/dev</optional>/sda</filename>. - Note that this option usually is not very useful, since - <command>udev</command> can guess the type of the - argument, so <command>udevadm --name=sda</command> is - equivalent to <command>udevadm /dev/sda</command>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>-r</option></term> - <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>-a</option></term> - <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>-x</option></term> - <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>-P</option></term> - <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>-d</option></term> - <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>-e</option></term> - <term><option>--export-db</option></term> - <listitem> - <para>Export the content of the udev database.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>-c</option></term> - <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>-h</option></term> - <term><option>--help</option></term> - <listitem> - <para>Print help text.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>In addition, an optional positional argument can be used - to specify a device name or a sys path. It must start with - <filename>/dev</filename> or <filename>/sys</filename> - respectively.</para> - </refsect2> - - <refsect2><title>udevadm trigger - <arg choice="opt"><replaceable>options</replaceable></arg> - <arg choice="opt" rep="repeat"><replaceable>devpath</replaceable>|<replaceable>file</replaceable></arg></title> - <para>Request device events from the kernel. Primarily used to replay events at system coldplug time.</para> - <variablelist> - <varlistentry> - <term><option>-v</option></term> - <term><option>--verbose</option></term> - <listitem> - <para>Print the list of devices which will be triggered.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>-n</option></term> - <term><option>--dry-run</option></term> - <listitem> - <para>Do not actually trigger the event.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>-t</option></term> - <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>-c</option></term> - <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>-s</option></term> - <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>-S</option></term> - <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>-a</option></term> - <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>-A</option></term> - <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>-p</option></term> - <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>-g</option></term> - <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>-y</option></term> - <term><option>--sysname-match=<replaceable>PATH</replaceable></option></term> - <listitem> - <para>Trigger events for devices with a matching sys - device path. This option can be specified multiple times - and supports shell style pattern matching.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>--name-match=<replaceable>NAME</replaceable></option></term> - <listitem> - <para>Trigger events for devices with a matching - device path. This option can be specified multiple - times.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>-b</option></term> - <term><option>--parent-match=<replaceable>SYSPATH</replaceable></option></term> - <listitem> - <para>Trigger events for all children of a given - device.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>-h</option></term> - <term><option>--help</option></term> - <listitem> - <para>Print help text.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>In addition, optional positional arguments can be used - to specify device names or sys paths. They must start with - <filename>/dev</filename> or <filename>/sys</filename> - respectively.</para> - </refsect2> - - <refsect2><title>udevadm settle - <arg choice="opt"><replaceable>options</replaceable></arg> - </title> - <para>Watches the udev event queue, and exits if all current events are handled.</para> - <variablelist> - <varlistentry> - <term><option>-t</option></term> - <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>-E</option></term> - <term><option>--exit-if-exists=<replaceable>FILE</replaceable></option></term> - <listitem> - <para>Stop waiting if file exists.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>-h</option></term> - <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>-x</option></term> - <term><option>--exit</option></term> - <listitem> - <para>Signal and wait for systemd-udevd to exit.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>-l</option></term> - <term><option>--log-priority=<replaceable>value</replaceable></option></term> - <listitem> - <para>Set the internal log level of - <filename>systemd-udevd</filename>. Valid values are the - numerical syslog priorities or their textual - representations: <option>emerg</option>, - <option>alert</option>, <option>crit</option>, - <option>err</option>, <option>warning</option>, - <option>notice</option>, <option>info</option>, and - <option>debug</option>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>-s</option></term> - <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>-S</option></term> - <term><option>--start-exec-queue</option></term> - <listitem> - <para>Signal systemd-udevd to enable the execution of events.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>-R</option></term> - <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>-p</option></term> - <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>-m</option></term> - <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>-h</option></term> - <term><option>--help</option></term> - <listitem> - <para>Print help text.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect2> - - <refsect2><title>udevadm monitor - <arg choice="opt"><replaceable>options</replaceable></arg> - </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>-k</option></term> - <term><option>--kernel</option></term> - <listitem> - <para>Print the kernel uevents.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>-u</option></term> - <term><option>--udev</option></term> - <listitem> - <para>Print the udev event after the rule processing.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>-p</option></term> - <term><option>--property</option></term> - <listitem> - <para>Also print the properties of the event.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>-s</option></term> - <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>-t</option></term> - <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>-h</option></term> - <term><option>--help</option></term> - <listitem> - <para>Print help text.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect2> - - <refsect2><title>udevadm test - <arg choice="opt"><replaceable>options</replaceable></arg> - <arg><replaceable>devpath</replaceable></arg> - </title> - <para>Simulate a udev event run for the given device, and print debug output.</para> - <variablelist> - <varlistentry> - <term><option>-a</option></term> - <term><option>--action=<replaceable>string</replaceable></option></term> - <listitem> - <para>The action string.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>-N</option></term> - <term><option>--resolve-names=<constant>early</constant>|<constant>late</constant>|<constant>never</constant></option></term> - <listitem> - <para>Specify when udevadm should resolve names of users - and groups. When set to <constant>early</constant> (the - default), names will be resolved when the rules are - parsed. When set to <constant>late</constant>, names will - be resolved for every event. When set to - <constant>never</constant>, names will never be resolved - and all devices will be owned by root.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>-h</option></term> - <term><option>--help</option></term> - <listitem> - <para>Print help text.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect2> - - <refsect2><title>udevadm test-builtin - <arg choice="opt"><replaceable>options</replaceable></arg> - <arg><replaceable>command</replaceable></arg> - <arg><replaceable>devpath</replaceable></arg> - </title> - <para>Run a built-in command <replaceable>COMMAND</replaceable> - for device <replaceable>DEVPATH</replaceable>, and print debug - output.</para> - <variablelist> - <varlistentry> - <term><option>-h</option></term> - <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 deleted file mode 100644 index 27196d44e9..0000000000 --- a/man/vconsole.conf.xml +++ /dev/null @@ -1,139 +0,0 @@ -<?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="vconsole.conf" conditional='ENABLE_VCONSOLE'> - <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=eurlatgr</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 project='mankier'><refentrytitle>loadkeys</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>setfont</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-localed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> |