-<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
-
-<!--
- SPDX-License-Identifier: LGPL-2.1+
-
- 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/>.
--->
+<!-- SPDX-License-Identifier: LGPL-2.1+ -->
<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>
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>btrfs subvolumes containing OS trees, similar to regular 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>Binary "raw" disk image files containing MBR or GPT partition tables and Linux file
+ systems.</para></listitem>
+
+ <listitem><para>Similarly, block devices containing MBR or GPT partition tables and file systems.</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 the argument to the <command>shell</command>
- command also specifies a user name, this option is ignored. If the name is not specified
- in either way, <literal>root</literal> will be used by default. 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 file or directory before
- applying the bind mount. Note that even though the name of this option suggests that it is suitable only for
- directories, this option also creates the destination file node to mount over if the the object to mount is not
- a directory, but a regular file, device node, socket or FIFO.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--read-only</option></term>
-
- <listitem><para>When used with <command>bind</command>, creates 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>
-
- <varlistentry>
- <term><option>--max-addresses=</option></term>
-
- <listitem><para>When used with the <option>list-machines</option>
- command, limits the number of ip addresses output for every machine.
- Defaults to 1. All addresses can be requested with <literal>all</literal>
- as argument to <option>--max-addresses</option> . If the argument to
- <option>--max-addresses</option> is less than the actual number
- of addresses, <literal>...</literal>follows the last address.
- If multiple addresses are to be written for a given machine, every
- address except the first one is on a new line and is followed by
- <literal>,</literal> if another address will be output afterwards. </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-q</option></term>
- <term><option>--quiet</option></term>
-
- <listitem><para>Suppresses additional informational output while running.</para></listitem>
- </varlistentry>
-
- <xi:include href="user-system-options.xml" xpointer="host" />
-
- <varlistentry>
- <term><option>-M</option></term>
- <term><option>--machine=</option></term>
-
- <listitem><para>Connect to
- <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
- running in a local container, to perform the specified operation within
- the container.</para></listitem>
- </varlistentry>
-
- <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>
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>
+ <para>Note that per-container size limits are only supported on btrfs file systems.</para></listitem>
</varlistentry>
<varlistentry>
server, under the same URL as the <filename>.tar</filename> file.
With <option>--verify=checksum</option>, only the SHA256 checksum
for the file is verified, based on the <filename>.sha256</filename>
- suffixed file or the<filename>SHA256SUMS</filename> file.
+ suffixed file or the <filename>SHA256SUMS</filename> file.
With <option>--verify=signature</option>, the sha checksum file is
first verified with the inline signature in the
<filename>.sha256</filename> file or the detached GPG signature file
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>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>import-fs</command> <replaceable>DIRECTORY</replaceable> [<replaceable>NAME</replaceable>]</term>
+
+ <listitem><para>Imports a container image stored in a local directory into
+ <filename>/var/lib/machines/</filename>, operates similar to <command>import-tar</command> or
+ <command>import-raw</command>, but the first argument is the source directory. If supported, this command will
+ create btrfs snapshot or subvolume for the new image.</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>
</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>--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 the argument to the <command>shell</command>
+ command also specifies a user name, this option is ignored. If the name is not specified
+ in either way, <literal>root</literal> will be used by default. 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 file or directory before
+ applying the bind mount. Note that even though the name of this option suggests that it is suitable only for
+ directories, this option also creates the destination file node to mount over if the object to mount is not
+ a directory, but a regular file, device node, socket or FIFO.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--read-only</option></term>
+
+ <listitem><para>When used with <command>bind</command>, creates 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>
+
+ <varlistentry>
+ <term><option>--max-addresses=</option></term>
+
+ <listitem><para>When used with the <option>list-machines</option>
+ command, limits the number of ip addresses output for every machine.
+ Defaults to 1. All addresses can be requested with <literal>all</literal>
+ as argument to <option>--max-addresses</option> . If the argument to
+ <option>--max-addresses</option> is less than the actual number
+ of addresses, <literal>...</literal>follows the last address.
+ If multiple addresses are to be written for a given machine, every
+ address except the first one is on a new line and is followed by
+ <literal>,</literal> if another address will be output afterwards. </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-q</option></term>
+ <term><option>--quiet</option></term>
+
+ <listitem><para>Suppresses additional informational output while running.</para></listitem>
+ </varlistentry>
+
+ <xi:include href="user-system-options.xml" xpointer="host" />
+
+ <varlistentry>
+ <term><option>-M</option></term>
+ <term><option>--machine=</option></term>
+
+ <listitem><para>Connect to
+ <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ running in a local container, to perform the specified operation within
+ the container.</para></listitem>
+ </varlistentry>
+
+ <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="no-ask-password" />
+ <xi:include href="standard-options.xml" xpointer="help" />
+ <xi:include href="standard-options.xml" xpointer="version" />
+ </variablelist>
+ </refsect1>
+
<refsect1>
<title>Machine and Image Names</title>
<filename>/var/lib/machines/</filename> to make them available for
control with <command>machinectl</command>.</para>
- <para>Note that some 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>Note that some image operations are only supported, efficient or atomic on btrfs file systems.</para>
<para>Disk images are understood by
<citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
<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
+ <programlisting># machinectl pull-raw --verify=no https://dl.fedoraproject.org/pub/fedora/linux/releases/27/CloudImages/x86_64/images/Fedora-Cloud-Base-27-1.6.x86_64.raw.xz
+# systemd-nspawn -M Fedora-Cloud-Base-27-1.6.x86_64
# passwd
# exit
-# machinectl start Fedora-Cloud-Base-23-20151030
-# machinectl login Fedora-Cloud-Base-23-20151030</programlisting>
+# machinectl start Fedora-Cloud-Base-27-1.6.x86_64
+# machinectl login Fedora-Cloud-Base-27-1.6.x86_64</programlisting>
<para>This downloads the specified <filename>.raw</filename>
image with verification disabled. Then, a shell is opened in it
<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>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
projects / thirdparty / systemd.git / blobdiff