diff options
Diffstat (limited to 'man')
51 files changed, 0 insertions, 16556 deletions
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/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/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/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/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/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/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/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/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/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/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.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-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-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-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-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-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-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-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-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-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-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-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-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-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-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-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.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/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/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/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> |