-<?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 image files containing MBR or GPT partition tables and Linux file
+ systems.</para></listitem>
- <listitem><para>Binary "raw" disk images containing MBR or GPT
- partition tables and Linux file system partitions.</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>
<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
+ 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>
<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
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>
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>,