-<?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">
-
-<!--
- 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>
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>
+ <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>
+ as UNIX and DNS host names. For details, see below.</para>
+
+ <para>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 may be:</para>
<itemizedlist>
- <listitem><para>Directory trees containing an OS, including its
+ <listitem><para>Directory trees containing an OS, including the
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>
</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>
<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>
+ <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>, applies
- a read-only bind mount.</para>
+ <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>
<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" />
- <xi:include href="user-system-options.xml" xpointer="machine" />
+
+ <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>
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
+ specified executable with the specified arguments, or the
+ default shell for the user if none is specified, or
+ <filename>/bin/sh</filename> if no default shell is found. By default,
<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
<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
+ <listitem><para>Bind mounts a file or directory from the host into the specified container. The first path
+ argument is the source file or directory on the host, the second path argument is the destination file or
+ 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,
- and only if user namespacing (<option>--private-users</option>) is not used.</para></listitem>
+ and only if user namespacing (<option>--private-users</option>) is not used. This command supports bind
+ mounting directories, regular files, device nodes, <constant>AF_UNIX</constant> socket nodes, as well as
+ FIFOs.</para></listitem>
</varlistentry>
<varlistentry>
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>
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
+ <para>The image is verified before it is made available, unless
+ <option>--verify=no</option> is specified.
+ Verification is done either via an inline signed file with the name
+ of the image and the suffix <filename>.sha256</filename> or via
+ separate <filename>SHA256SUMS</filename> and
+ <filename>SHA256SUMS.gpg</filename> files.
+ The signature files need to be made available on the same web
+ 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.
+ 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
+ <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>
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
+ name. If the filename 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>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>
</varlistentry>
<varlistentry>
- <term><command>cancel-transfers</command> <replaceable>ID</replaceable>…</term>
+ <term><command>cancel-transfer</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
<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