diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/coredumpctl.xml | 18 | ||||
| -rw-r--r-- | man/machinectl.xml | 189 | ||||
| -rw-r--r-- | man/systemctl.xml | 12 | ||||
| -rw-r--r-- | man/systemd-run.xml | 55 | ||||
| -rw-r--r-- | man/systemd.exec.xml | 41 | ||||
| -rw-r--r-- | man/systemd.netdev.xml | 14 | ||||
| -rw-r--r-- | man/systemd.network.xml | 12 | ||||
| -rw-r--r-- | man/systemd.special.xml | 2 |
8 files changed, 290 insertions, 53 deletions
diff --git a/man/coredumpctl.xml b/man/coredumpctl.xml index efbc655a76..0f1afe77c3 100644 --- a/man/coredumpctl.xml +++ b/man/coredumpctl.xml @@ -86,8 +86,8 @@ </varlistentry> <varlistentry> - <term><option>-F</option></term> - <term><option>--field=</option></term> + <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 coredump entries of the @@ -95,13 +95,21 @@ </varlistentry> <varlistentry> - <term><option>-o</option></term> - <term><option>--output=FILE</option></term> + <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> + <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" /> @@ -132,7 +140,7 @@ <listitem><para>Extract the last coredump matching specified characteristics. The coredump will be written on standard output, unless an output file is specified with - <option>-o/--output</option>. </para></listitem> + <option>--output=</option>. </para></listitem> </varlistentry> <varlistentry> diff --git a/man/machinectl.xml b/man/machinectl.xml index a5eb3f08e4..6cf405ed29 100644 --- a/man/machinectl.xml +++ b/man/machinectl.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?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"> @@ -65,6 +65,43 @@ <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> @@ -138,6 +175,30 @@ </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>--setenv=</option></term> + + <listitem><para>When used with the <command>shell</command> + command, sets an environment variable to pass to the executed + shell. Takes a pair of environment variable name and value, + separated by <literal>=</literal> as argument. 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 @@ -145,7 +206,6 @@ mount.</para></listitem> </varlistentry> - <varlistentry> <term><option>--read-only</option></term> @@ -247,9 +307,11 @@ <term><command>list</command></term> <listitem><para>List currently running (online) virtual - machines and containers. To enumerate container images that - can be started, use <command>list-images</command> (see - below).</para></listitem> + 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> @@ -267,7 +329,7 @@ </varlistentry> <varlistentry> - <term><command>show</command> <replaceable>NAME</replaceable>...</term> + <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 @@ -316,21 +378,66 @@ </varlistentry> <varlistentry> - <term><command>login</command> <replaceable>NAME</replaceable></term> - - <listitem><para>Open an interactive terminal login session to - a container. This will create a TTY connection to a specific - container and asks for the execution of a getty on it. Note - that this is only supported for containers running + <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, which then asks for username and password. Use + 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 similar in many ways 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 and keyring session, and will not inherit an environment + variables or resource limits, among other properties.</para> + + <para>Note that the <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry> - with the <option>--machine=</option> switch to invoke a single - command, either interactively or in the background within a - local container.</para></listitem> + 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> @@ -453,7 +560,7 @@ </varlistentry> <varlistentry> - <term><command>image-status</command> <replaceable>NAME</replaceable>...</term> + <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 @@ -463,7 +570,7 @@ </varlistentry> <varlistentry> - <term><command>show-image</command> <replaceable>NAME</replaceable>...</term> + <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 @@ -766,6 +873,41 @@ </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 consists 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. Not 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 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 is hence + conceptually maps to the special <literal>.host</literal> machine + name described above. Note that <command>machinectl + list-images</command> won't 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 @@ -872,6 +1014,17 @@ 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> diff --git a/man/systemctl.xml b/man/systemctl.xml index 0b5282ba21..20d143741b 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -474,6 +474,18 @@ </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> diff --git a/man/systemd-run.xml b/man/systemd-run.xml index 71b365c8eb..80db148702 100644 --- a/man/systemd-run.xml +++ b/man/systemd-run.xml @@ -69,38 +69,41 @@ <title>Description</title> <para><command>systemd-run</command> may be used to create and - start a transient <filename>.service</filename> or a transient - <filename>.timer</filename> or a <filename>.scope</filename> unit - and run the specified <replaceable>COMMAND</replaceable> in - it.</para> + 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 show up in the output of <command>systemctl + 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. <command>systemd-run</command> - will start the service asynchronously in the background and - immediately return.</para> - - <para>If a command is run with timer options, transient timer unit - also be created with transient service unit. But the transient - timer unit is only started immediately. The transient service unit - will be started when the transient timer is elapsed. If - <option>--unit=</option> is specified with timer options, the - <replaceable>COMMAND</replaceable> can be omitted. In this case, - <command>systemd-run</command> assumes service unit is already - loaded and creates transient timer unit only. To successfully - create timer unit, already loaded service unit should be specified - with <option>--unit=</option>. This transient timer unit can - activate the existing service unit like any other timer.</para> + 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 directly by <command>systemd-run</command> and thus - inherit the execution environment of the caller. It is however - managed by the service manager similar to normal services, and - will also show up in the output of <command>systemctl - list-units</command>. Execution in this case is synchronous, and - execution will return only when the command finishes.</para> + 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> diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index 8fd75d274e..7633948645 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -1,3 +1,4 @@ +<?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"> @@ -911,10 +912,16 @@ <term><varname>UtmpIdentifier=</varname></term> <listitem><para>Takes a four character identifier string for - an utmp/wtmp entry for this service. This should only be set - for services such as <command>getty</command> implementations + an <citerefentry + project='man-pages'><refentrytitle>utmp</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and wtmp entry for this service. This should only be + set for services such as <command>getty</command> + implementations (such as <citerefentry + project='die-net'><refentrytitle>agetty</refentrytitle><manvolnum>8</manvolnum></citerefentry>) where utmp/wtmp entries must be created and cleared before and - after execution. If the configured string is longer than four + after execution, or for services that shall be executed as if + they were run by a <command>getty</command> process (see + below). If the configured string is longer than four characters, it is truncated and the terminal four characters are used. This setting interprets %I style string replacements. This setting is unset by default, i.e. no @@ -923,6 +930,34 @@ </varlistentry> <varlistentry> + <term><varname>UtmpMode=</varname></term> + + <listitem><para>Takes one of <literal>init</literal>, + <literal>login</literal> or <literal>user</literal>. If + <varname>UtmpIdentifier=</varname> is set, controls which + type of <citerefentry + project='man-pages'><refentrytitle>utmp</refentrytitle><manvolnum>5</manvolnum></citerefentry>/wtmp + entries for this service are generated. This setting has no + effect unless <varname>UtmpIdentifier=</varname> is set + too. If <literal>init</literal> is set, only an + <constant>INIT_PROCESS</constant> entry is generated and the + invoked process must implement a + <command>getty</command>-compatible utmp/wtmp logic. If + <literal>login</literal> is set, first an + <constant>INIT_PROCESS</constant> entry, followed by an + <constant>LOGIN_PROCESS</constant> entry is generated. In + this case the invoked process must implement a <citerefentry + project='die-net'><refentrytitle>login</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible + utmp/wtmp logic. If <literal>user</literal> is set, first an + <constant>INIT_PROCESS</constant> entry, then a + <constant>LOGIN_PROCESS</constant> entry and finally an + <constant>USER_PROCESS</constant> entry is generated. In this + case the invoked process may be any process that is suitable + to be run as session leader. Defaults to + <literal>init</literal>.</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>SELinuxContext=</varname></term> <listitem><para>Set the SELinux security context of the diff --git a/man/systemd.netdev.xml b/man/systemd.netdev.xml index a78ceb1252..2680627a78 100644 --- a/man/systemd.netdev.xml +++ b/man/systemd.netdev.xml @@ -986,6 +986,20 @@ Name=veth-peer</programlisting> </example> <example> + <title>/etc/systemd/network/bond.netdev</title> + <programlisting>[NetDev] +Name=bond1 +Kind=bond + +[Bond] +Mode=802.3ad +TransmitHashPolicy=layer3+4 +MIIMonitorSec=1s +LACPTransmitRate=fast +</programlisting> + </example> + + <example> <title>/etc/systemd/network/dummy.netdev</title> <programlisting>[NetDev] Name=dummy-test diff --git a/man/systemd.network.xml b/man/systemd.network.xml index e44491cc2e..e8a164d22d 100644 --- a/man/systemd.network.xml +++ b/man/systemd.network.xml @@ -828,6 +828,18 @@ Name=em1 [Network] Tunnel=vti-tun</programlisting> </example> + + <example> + <title>/etc/systemd/network/bond.network</title> + + <programlisting>[Match] +Name=bond1 + +[Network] +DHCP=yes +</programlisting> + </example> + </refsect1> <refsect1> diff --git a/man/systemd.special.xml b/man/systemd.special.xml index c90b0366c1..e4700d950b 100644 --- a/man/systemd.special.xml +++ b/man/systemd.special.xml @@ -852,7 +852,7 @@ <varlistentry> <term><filename>system.slice</filename></term> <listitem> - <para>By default, all services services started by + <para>By default, all system services started by <command>systemd</command> are found in this slice.</para> </listitem> </varlistentry> |