proxmox-mirrors/systemd
1
0
Fork 0
mirror of https://git.proxmox.com/git/systemd synced 2026-01-22 08:17:11 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity
cf65a16b97
systemd/man/machinectl.html
Martin Pitt e3bff60a6e Imported Upstream version 220
2015-05-25 11:04:44 +02:00

460 lines
50 KiB
HTML
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>machinectl</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><style>
a.headerlink {
color: #c60f0f;
font-size: 0.8em;
padding: 0 4px 0 4px;
text-decoration: none;
visibility: hidden;
}
a.headerlink:hover {
background-color: #c60f0f;
color: white;
}
h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink {
visibility: visible;
}
</style><a href="index.html">Index </a>·
<a href="systemd.directives.html">Directives </a>·
<a href="../python-systemd/index.html">Python </a>·
<a href="../libudev/index.html">libudev </a>·
<a href="../libudev/index.html">gudev </a><span style="float:right">systemd 220</span><hr><div class="refentry"><a name="machinectl"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>machinectl — Control the systemd machine manager</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">machinectl</code> [OPTIONS...] {COMMAND} [NAME...]</p></div></div><div class="refsect1"><a name="idm139807813729600"></a><h2 id="Description">Description<a class="headerlink" title="Permalink to this headline" href="#Description"></a></h2><p><span class="command"><strong>machinectl</strong></span> may be used to introspect and
control the state of the
<a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>
virtual machine and container registration manager
<a href="systemd-machined.service.html"><span class="citerefentry"><span class="refentrytitle">systemd-machined.service</span>(8)</span></a>.</p></div><div class="refsect1"><a name="idm139807813726240"></a><h2 id="Options">Options<a class="headerlink" title="Permalink to this headline" href="#Options"></a></h2><p>The following options are understood:</p><div class="variablelist"><dl class="variablelist"><dt id="-p"><span class="term"><code class="option">-p</code>, </span><span class="term"><code class="option">--property=</code></span><a class="headerlink" title="Permalink to this term" href="#-p"></a></dt><dd><p>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
"<code class="literal">Name</code>". If specified more than once, all
properties with the specified names are
shown.</p></dd><dt id="-a"><span class="term"><code class="option">-a</code>, </span><span class="term"><code class="option">--all</code></span><a class="headerlink" title="Permalink to this term" href="#-a"></a></dt><dd><p>When showing machine or image properties, show
all properties regardless of whether they are set or
not.</p><p>When listing VM or container images, do not suppress
images beginning in a dot character
("<code class="literal">.</code>").</p></dd><dt id="-l"><span class="term"><code class="option">-l</code>, </span><span class="term"><code class="option">--full</code></span><a class="headerlink" title="Permalink to this term" href="#-l"></a></dt><dd><p>Do not ellipsize process tree entries.</p></dd><dt id="--no-ask-password"><span class="term"><code class="option">--no-ask-password</code></span><a class="headerlink" title="Permalink to this term" href="#--no-ask-password"></a></dt><dd><p>Do not query the user for authentication for
privileged operations.</p></dd><dt id="--kill-who="><span class="term"><code class="option">--kill-who=</code></span><a class="headerlink" title="Permalink to this term" href="#--kill-who="></a></dt><dd><p>When used with <span class="command"><strong>kill</strong></span>, choose
which processes to kill. Must be one of
<code class="option">leader</code>, or <code class="option">all</code> to select
whether to kill only the leader process of the machine or all
processes of the machine. If omitted, defaults to
<code class="option">all</code>.</p></dd><dt id="-s"><span class="term"><code class="option">-s</code>, </span><span class="term"><code class="option">--signal=</code></span><a class="headerlink" title="Permalink to this term" href="#-s"></a></dt><dd><p>When used with <span class="command"><strong>kill</strong></span>, choose
which signal to send to selected processes. Must be one of the
well-known signal specifiers, such as
<code class="constant">SIGTERM</code>, <code class="constant">SIGINT</code> or
<code class="constant">SIGSTOP</code>. If omitted, defaults to
<code class="constant">SIGTERM</code>.</p></dd><dt id="--mkdir"><span class="term"><code class="option">--mkdir</code></span><a class="headerlink" title="Permalink to this term" href="#--mkdir"></a></dt><dd><p>When used with <span class="command"><strong>bind</strong></span> creates
the destination directory before applying the bind
mount.</p></dd><dt id="--read-only"><span class="term"><code class="option">--read-only</code></span><a class="headerlink" title="Permalink to this term" href="#--read-only"></a></dt><dd><p>When used with <span class="command"><strong>bind</strong></span> applies
a read-only bind mount.</p></dd><dt id="-n"><span class="term"><code class="option">-n</code>, </span><span class="term"><code class="option">--lines=</code></span><a class="headerlink" title="Permalink to this term" href="#-n"></a></dt><dd><p>When used with <span class="command"><strong>status</strong></span>,
controls the number of journal lines to show, counting from
the most recent ones. Takes a positive integer argument.
Defaults to 10.</p></dd><dt id="-o"><span class="term"><code class="option">-o</code>, </span><span class="term"><code class="option">--output=</code></span><a class="headerlink" title="Permalink to this term" href="#-o"></a></dt><dd><p>When used with <span class="command"><strong>status</strong></span>,
controls the formatting of the journal entries that are shown.
For the available choices, see
<a href="journalctl.html"><span class="citerefentry"><span class="refentrytitle">journalctl</span>(1)</span></a>.
Defaults to "<code class="literal">short</code>".</p></dd><dt id="--verify="><span class="term"><code class="option">--verify=</code></span><a class="headerlink" title="Permalink to this term" href="#--verify="></a></dt><dd><p>When downloading a container or VM image,
specify whether the image shall be verified before it is made
available. Takes one of "<code class="literal">no</code>",
"<code class="literal">checksum</code>" and "<code class="literal">signature</code>".
If "<code class="literal">no</code>" no verification is done. If
"<code class="literal">checksum</code>" is specified the download is
checked for integrity after transfer is complete, but no
signatures are verified. If "<code class="literal">signature</code>" is
specified, the checksum is verified and the images's signature
is checked against a local keyring of trustable vendors. It is
strongly recommended to set this option to
"<code class="literal">signature</code>" if the server and protocol
support this. Defaults to
"<code class="literal">signature</code>".</p></dd><dt id="--force"><span class="term"><code class="option">--force</code></span><a class="headerlink" title="Permalink to this term" href="#--force"></a></dt><dd><p>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.</p></dd><dt id="--dkr-index-url"><span class="term"><code class="option">--dkr-index-url</code></span><a class="headerlink" title="Permalink to this term" href="#--dkr-index-url"></a></dt><dd><p>Specifies the index server to use for
downloading "<code class="literal">dkr</code>" images with the
<span class="command"><strong>pull-dkr</strong></span>. Takes a
"<code class="literal">http://</code>", "<code class="literal">https://</code>"
URL.</p></dd><dt id="--format="><span class="term"><code class="option">--format=</code></span><a class="headerlink" title="Permalink to this term" href="#--format="></a></dt><dd><p>When used with the <code class="option">export-tar</code>
or <code class="option">export-raw</code> commands specifies the
compression format to use for the resulting file. Takes one of
"<code class="literal">uncompressed</code>", "<code class="literal">xz</code>",
"<code class="literal">gzip</code>", "<code class="literal">bzip2</code>". By default
the format is determined automatically from the image file
name passed.</p></dd><dt id="-H"><span class="term"><code class="option">-H</code>, </span><span class="term"><code class="option">--host=</code></span><a class="headerlink" title="Permalink to this term" href="#-H"></a></dt><dd><p><a name="host-text"></a>Execute the operation remotely. Specify a hostname, or a
username and hostname separated by "<code class="literal">@</code>", to
connect to. The hostname may optionally be suffixed by a
container name, separated by "<code class="literal">:</code>", which
connects directly to a specific container on the specified
host. This will use SSH to talk to the remote machine manager
instance. Container names may be enumerated with
<span class="command"><strong>machinectl -H
<em class="replaceable"><code>HOST</code></em></strong></span>.</p></dd><dt id="-M"><span class="term"><code class="option">-M</code>, </span><span class="term"><code class="option">--machine=</code></span><a class="headerlink" title="Permalink to this term" href="#-M"></a></dt><dd><p><a name="machine-text"></a>Execute operation on a local container. Specify a
container name to connect to.</p></dd><dt id="--no-pager"><span class="term"><code class="option">--no-pager</code></span><a class="headerlink" title="Permalink to this term" href="#--no-pager"></a></dt><dd><p>Do not pipe output into a pager.</p></dd><dt id="--no-legend"><span class="term"><code class="option">--no-legend</code></span><a class="headerlink" title="Permalink to this term" href="#--no-legend"></a></dt><dd><p>Do not print the legend, i.e. column headers and the
footer with hints.</p></dd><dt id="-h"><span class="term"><code class="option">-h</code>, </span><span class="term"><code class="option">--help</code></span><a class="headerlink" title="Permalink to this term" href="#-h"></a></dt><dd><p><a name="help-text"></a>Print a short help text and exit.
</p></dd><dt id="--version"><span class="term"><code class="option">--version</code></span><a class="headerlink" title="Permalink to this term" href="#--version"></a></dt><dd><p><a name="version-text"></a>Print a short version string and exit.</p></dd></dl></div></div><div class="refsect1"><a name="idm139807809059328"></a><h2 id="Commands">Commands<a class="headerlink" title="Permalink to this headline" href="#Commands"></a></h2><p>The following commands are understood:</p><div class="refsect2"><a name="idm139807809058304"></a><h3 id="Machine Commands">Machine Commands<a class="headerlink" title="Permalink to this headline" href="#Machine%20Commands"></a></h3><div class="variablelist"><dl class="variablelist"><dt id="list"><span class="term"><span class="command"><strong>list</strong></span></span><a class="headerlink" title="Permalink to this term" href="#list"></a></dt><dd><p>List currently running (online) virtual
machines and containers. To enumerate container images that
can be started, use <span class="command"><strong>list-images</strong></span> (see
below).</p></dd><dt id="status NAME..."><span class="term"><span class="command"><strong>status</strong></span> <em class="replaceable"><code>NAME</code></em>...</span><a class="headerlink" title="Permalink to this term" href="#status%20NAME..."></a></dt><dd><p>Show terse 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 <span class="command"><strong>show</strong></span>
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.</p></dd><dt id="show NAME..."><span class="term"><span class="command"><strong>show</strong></span> <em class="replaceable"><code>NAME</code></em>...</span><a class="headerlink" title="Permalink to this term" href="#show%20NAME..."></a></dt><dd><p>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 <code class="option">--all</code> to show those too.
To select specific properties to show, use
<code class="option">--property=</code>. This command is intended to be
used whenever computer-parsable output is required. Use
<span class="command"><strong>status</strong></span> if you are looking for formatted
human-readable output.</p></dd><dt id="start NAME..."><span class="term"><span class="command"><strong>start</strong></span> <em class="replaceable"><code>NAME</code></em>...</span><a class="headerlink" title="Permalink to this term" href="#start%20NAME..."></a></dt><dd><p>Start a container as a system service, using
<a href="systemd-nspawn.html"><span class="citerefentry"><span class="refentrytitle">systemd-nspawn</span>(1)</span></a>.
This starts <code class="filename">systemd-nspawn@.service</code>,
instantiated for the specified machine name, similar to the
effect of <span class="command"><strong>systemctl start</strong></span> on the service
name. <span class="command"><strong>systemd-nspawn</strong></span> looks for a container
image by the specified name in
<code class="filename">/var/lib/machines/</code> (and other search
paths, see below) and runs it. Use
<span class="command"><strong>list-images</strong></span> (see below), for listing
available container images to start.</p><p>Note that
<a href="systemd-machined.service.html"><span class="citerefentry"><span class="refentrytitle">systemd-machined.service</span>(8)</span></a>
also interfaces with a variety of other container and VM
managers, <span class="command"><strong>systemd-nspawn</strong></span> is just one
implementation of it. Most of the commands available in
<span class="command"><strong>machinectl</strong></span> may be used on containers or VMs
controlled by other managers, not just
<span class="command"><strong>systemd-nspawn</strong></span>. Starting VMs and container
images on those managers requires manager-specific
tools.</p><p>To interactively start a container on the command line
with full access to the container's console, please invoke
<span class="command"><strong>systemd-nspawn</strong></span> directly. To stop a running
container use <span class="command"><strong>machinectl poweroff</strong></span>, see
below.</p></dd><dt id="login NAME"><span class="term"><span class="command"><strong>login</strong></span> <em class="replaceable"><code>NAME</code></em></span><a class="headerlink" title="Permalink to this term" href="#login%20NAME"></a></dt><dd><p>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
<a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>
as init system.</p><p>This command will open a full login prompt on the
container, which then asks for username and password. Use
<a href="systemd-run.html"><span class="citerefentry"><span class="refentrytitle">systemd-run</span>(1)</span></a>
with the <code class="option">--machine=</code> switch to invoke a single
command, either interactively or in the background within a
local container.</p></dd><dt id="enable NAME..."><span class="term"><span class="command"><strong>enable</strong></span> <em class="replaceable"><code>NAME</code></em>..., </span><span class="term"><span class="command"><strong>disable</strong></span> <em class="replaceable"><code>NAME</code></em>...</span><a class="headerlink" title="Permalink to this term" href="#enable%20NAME..."></a></dt><dd><p>Enable or disable a container as a system
service to start at system boot, using
<a href="systemd-nspawn.html"><span class="citerefentry"><span class="refentrytitle">systemd-nspawn</span>(1)</span></a>.
This enables or disables
<code class="filename">systemd-nspawn@.service</code>, instantiated for
the specified machine name, similar to the effect of
<span class="command"><strong>systemctl enable</strong></span> or <span class="command"><strong>systemctl
disable</strong></span> on the service name.</p></dd><dt id="poweroff NAME..."><span class="term"><span class="command"><strong>poweroff</strong></span> <em class="replaceable"><code>NAME</code></em>...</span><a class="headerlink" title="Permalink to this term" href="#poweroff%20NAME..."></a></dt><dd><p>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
<a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>-compatible
init system, such as sysvinit. Use
<span class="command"><strong>terminate</strong></span> (see below) to immediately
terminate a container or VM, without cleanly shutting it
down.</p></dd><dt id="reboot NAME..."><span class="term"><span class="command"><strong>reboot</strong></span> <em class="replaceable"><code>NAME</code></em>...</span><a class="headerlink" title="Permalink to this term" href="#reboot%20NAME..."></a></dt><dd><p>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.</p></dd><dt id="terminate NAME..."><span class="term"><span class="command"><strong>terminate</strong></span> <em class="replaceable"><code>NAME</code></em>...</span><a class="headerlink" title="Permalink to this term" href="#terminate%20NAME..."></a></dt><dd><p>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
<span class="command"><strong>poweroff</strong></span> to issue a clean shutdown
request.</p></dd><dt id="kill NAME..."><span class="term"><span class="command"><strong>kill</strong></span> <em class="replaceable"><code>NAME</code></em>...</span><a class="headerlink" title="Permalink to this term" href="#kill%20NAME..."></a></dt><dd><p>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 <code class="option">--kill-who=</code> to select which
process to kill. Use <code class="option">--signal=</code> to select the
signal to send.</p></dd><dt id="bind NAME PATH [PATH]"><span class="term"><span class="command"><strong>bind</strong></span> <em class="replaceable"><code>NAME</code></em> <em class="replaceable"><code>PATH</code></em> [<em class="replaceable"><code>PATH</code></em>]</span><a class="headerlink" title="Permalink to this term" href="#bind%20NAME%20PATH%20%5BPATH%5D"></a></dt><dd><p>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
the source directory on the host. 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
<code class="option">--read-only</code> switch a ready-only bind mount is
created. When combined with the <code class="option">--mkdir</code>
switch the destination path is first created before the mount
is applied. Note that this option is currently only supported
for
<a href="systemd-nspawn.html"><span class="citerefentry"><span class="refentrytitle">systemd-nspawn</span>(1)</span></a>
containers.</p></dd><dt id="copy-to NAME PATH [PATH]"><span class="term"><span class="command"><strong>copy-to</strong></span> <em class="replaceable"><code>NAME</code></em> <em class="replaceable"><code>PATH</code></em> [<em class="replaceable"><code>PATH</code></em>]</span><a class="headerlink" title="Permalink to this term" href="#copy-to%20NAME%20PATH%20%5BPATH%5D"></a></dt><dd><p>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.</p></dd><dt id="copy-from NAME PATH [PATH]"><span class="term"><span class="command"><strong>copy-from</strong></span> <em class="replaceable"><code>NAME</code></em> <em class="replaceable"><code>PATH</code></em> [<em class="replaceable"><code>PATH</code></em>]</span><a class="headerlink" title="Permalink to this term" href="#copy-from%20NAME%20PATH%20%5BPATH%5D"></a></dt><dd><p>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.</p></dd></dl></div></div><div class="refsect2"><a name="idm139807809000704"></a><h3 id="Image Commands">Image Commands<a class="headerlink" title="Permalink to this headline" href="#Image%20Commands"></a></h3><div class="variablelist"><dl class="variablelist"><dt id="list-images"><span class="term"><span class="command"><strong>list-images</strong></span></span><a class="headerlink" title="Permalink to this term" href="#list-images"></a></dt><dd><p>Show a list of locally installed container and
VM images. This enumerates all raw disk images and container
directories and subvolumes in
<code class="filename">/var/lib/machines/</code> (and other search
paths, see below). Use <span class="command"><strong>start</strong></span> (see above) to
run a container off one of the listed images. Note that by
default containers whose name begins with a dot
("<code class="literal">.</code>") are not shown. To show these too,
specify <code class="option">--all</code>. Note that a special image
"<code class="literal">.host</code>" always implicitly exists and refers
to the image the host itself is booted from.</p></dd><dt id="image-status NAME..."><span class="term"><span class="command"><strong>image-status</strong></span> <em class="replaceable"><code>NAME</code></em>...</span><a class="headerlink" title="Permalink to this term" href="#image-status%20NAME..."></a></dt><dd><p>Show terse status information about one or
more container or VM images. This function is intended to
generate human-readable output. Use
<span class="command"><strong>show-image</strong></span> (see below) to generate
computer-parsable output instead.</p></dd><dt id="show-image NAME..."><span class="term"><span class="command"><strong>show-image</strong></span> <em class="replaceable"><code>NAME</code></em>...</span><a class="headerlink" title="Permalink to this term" href="#show-image%20NAME..."></a></dt><dd><p>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 <code class="option">--all</code> to show
those too. To select specific properties to show, use
<code class="option">--property=</code>. This command is intended to be
used whenever computer-parsable output is required. Use
<span class="command"><strong>image-status</strong></span> if you are looking for
formatted human-readable output.</p></dd><dt id="clone NAME NAME"><span class="term"><span class="command"><strong>clone</strong></span> <em class="replaceable"><code>NAME</code></em> <em class="replaceable"><code>NAME</code></em></span><a class="headerlink" title="Permalink to this term" href="#clone%20NAME%20NAME"></a></dt><dd><p>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 subvolume images with this command.
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.</p><p>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.</p></dd><dt id="rename NAME NAME"><span class="term"><span class="command"><strong>rename</strong></span> <em class="replaceable"><code>NAME</code></em> <em class="replaceable"><code>NAME</code></em></span><a class="headerlink" title="Permalink to this term" href="#rename%20NAME%20NAME"></a></dt><dd><p>Renames a container or VM image. The
arguments specify the name of the image to rename and the new
name of the image.</p></dd><dt id="read-only NAME [BOOL]"><span class="term"><span class="command"><strong>read-only</strong></span> <em class="replaceable"><code>NAME</code></em> [<em class="replaceable"><code>BOOL</code></em>]</span><a class="headerlink" title="Permalink to this term" href="#read-only%20NAME%20%5BBOOL%5D"></a></dt><dd><p>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.</p></dd><dt id="remove NAME..."><span class="term"><span class="command"><strong>remove</strong></span> <em class="replaceable"><code>NAME</code></em>...</span><a class="headerlink" title="Permalink to this term" href="#remove%20NAME..."></a></dt><dd><p>Removes one or more container or VM images.
The special image "<code class="literal">.host</code>", which refers to
the host's own directory tree may not be
removed.</p></dd><dt id="set-limit [NAME] BYTES"><span class="term"><span class="command"><strong>set-limit</strong></span> [<em class="replaceable"><code>NAME</code></em>] <em class="replaceable"><code>BYTES</code></em></span><a class="headerlink" title="Permalink to this term" href="#set-limit%20%5BNAME%5D%20BYTES"></a></dt><dd><p>Sets the maximum size in bytes 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
"<code class="literal">-</code>" as size.</p><p>Note that per-container size limits are only supported
on btrfs file systems. Also note that if
<span class="command"><strong>set-limit</strong></span> is invoked without image
parameter, and <code class="filename">/var/lib/machines</code> is
empty, and the directory is not located on btrfs, a btrfs
loopback file is implicitly created as
<code class="filename">/var/lib/machines.raw</code> with the given
size, and mounted to
<code class="filename">/var/lib/machines</code>. The size of the
loopback may later be readjusted with
<span class="command"><strong>set-limit</strong></span>, as well. If such a
loopback-mounted <code class="filename">/var/lib/machines</code>
directory is used <span class="command"><strong>set-limit</strong></span> without image
name alters both the quota setting within the file system as
well as the loopback file and file system size
itself.</p></dd></dl></div></div><div class="refsect2"><a name="idm139807808966896"></a><h3 id="Image Transfer Commands">Image Transfer Commands<a class="headerlink" title="Permalink to this headline" href="#Image%20Transfer%20Commands"></a></h3><div class="variablelist"><dl class="variablelist"><dt id="pull-tar URL [NAME]"><span class="term"><span class="command"><strong>pull-tar</strong></span> <em class="replaceable"><code>URL</code></em> [<em class="replaceable"><code>NAME</code></em>]</span><a class="headerlink" title="Permalink to this term" href="#pull-tar%20URL%20%5BNAME%5D"></a></dt><dd><p>Downloads a <code class="filename">.tar</code>
container image from the specified URL, and makes it available
under the specified local machine name. The URL must be of
type "<code class="literal">http://</code>" or
"<code class="literal">https://</code>", and must refer to a
<code class="filename">.tar</code>, <code class="filename">.tar.gz</code>,
<code class="filename">.tar.xz</code> or <code class="filename">.tar.bz2</code>
archive file. If the local machine name is omitted it
is automatically derived from the last component of the URL,
with its suffix removed.</p><p>The image is verified before it is made available,
unless <code class="option">--verify=no</code> 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 <code class="filename">.tar</code> file, but with the last
component (the filename) of the URL replaced. With
<code class="option">--verify=checksum</code> only the SHA256 checksum
for the file is verified, based on the
<code class="filename">SHA256SUMS</code> file. With
<code class="option">--verify=signature</code> the SHA256SUMS file is
first verified with detached GPG signature file
<code class="filename">SHA256SUMS.gpg</code>. The public key for this
verification step needs to be available in
<code class="filename">/usr/lib/systemd/import-pubring.gpg</code> or
<code class="filename">/etc/systemd/import-pubring.gpg</code>.</p><p>The container image will be downloaded and stored in a
read-only subvolume in
<code class="filename">/var/lib/machines/</code>, 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 behaviour 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 "<code class="literal">-</code>" as local machine name.</p><p>Note that the read-only subvolume is prefixed with
<code class="filename">.tar-</code>, and is thus not shown by
<span class="command"><strong>list-images</strong></span>, unless <code class="option">--all</code>
is passed.</p><p>Note that pressing C-c during execution of this command
will not abort the download. Use
<span class="command"><strong>cancel-transfer</strong></span>, described
below.</p></dd><dt id="pull-raw URL [NAME]"><span class="term"><span class="command"><strong>pull-raw</strong></span> <em class="replaceable"><code>URL</code></em> [<em class="replaceable"><code>NAME</code></em>]</span><a class="headerlink" title="Permalink to this term" href="#pull-raw%20URL%20%5BNAME%5D"></a></dt><dd><p>Downloads a <code class="filename">.raw</code>
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 "<code class="literal">http://</code>" or
"<code class="literal">https://</code>". The container image must either
be a <code class="filename">.qcow2</code> or raw disk image, optionally
compressed as <code class="filename">.gz</code>,
<code class="filename">.xz</code>, or <code class="filename">.bz2</code>. If the
local machine name is omitted it is automatically
derived from the last component of the URL, with its suffix
removed.</p><p>Image verification is identical for raw and tar images
(see above).</p><p>If the the downloaded image is in
<code class="filename">.qcow2</code> format it is converted into a raw
image file before it is made available.</p><p>Downloaded images of this type will be placed as
read-only <code class="filename">.raw</code> file in
<code class="filename">/var/lib/machines/</code>. A local, writable
(reflinked) copy is then made under the specified local
machine name. To omit creation of the local, writable copy
pass "<code class="literal">-</code>" as local machine name.</p><p>Similar to the behaviour of <span class="command"><strong>pull-tar</strong></span>,
the read-only image is prefixed with
<code class="filename">.raw-</code>, and thus not shown by
<span class="command"><strong>list-images</strong></span>, unless <code class="option">--all</code>
is passed.</p><p>Note that pressing C-c during execution of this command
will not abort the download. Use
<span class="command"><strong>cancel-transfer</strong></span>, described
below.</p></dd><dt id="pull-dkr REMOTE [NAME]"><span class="term"><span class="command"><strong>pull-dkr</strong></span> <em class="replaceable"><code>REMOTE</code></em> [<em class="replaceable"><code>NAME</code></em>]</span><a class="headerlink" title="Permalink to this term" href="#pull-dkr%20REMOTE%20%5BNAME%5D"></a></dt><dd><p>Downloads a "<code class="literal">dkr</code>" container
image and makes it available locally. The remote name refers
to a "<code class="literal">dkr</code>" container name. If omitted, the
local machine name is derived from the "<code class="literal">dkr</code>"
container name.</p><p>Image verification is not available for
"<code class="literal">dkr</code>" containers, and thus
<code class="option">--verify=no</code> must always be specified with
this command.</p><p>This command downloads all (missing) layers for the
specified container and places them in read-only subvolumes in
<code class="filename">/var/lib/machines/</code>. A writable snapshot
of the newest layer is then created under the specified local
machine name. To omit creation of this writable snapshot, pass
"<code class="literal">-</code>" as local machine name.</p><p>The read-only layer subvolumes are prefixed with
<code class="filename">.dkr-</code>, and thus not shown by
<span class="command"><strong>list-images</strong></span>, unless <code class="option">--all</code>
is passed.</p><p>To specify the "<code class="literal">dkr</code>" index server to
use for looking up the specified container, use
<code class="option">--dkr-index-url=</code>.</p><p>Note that pressing C-c during execution of this command
will not abort the download. Use
<span class="command"><strong>cancel-transfer</strong></span>, described
below.</p></dd><dt id="import-tar FILE [NAME]"><span class="term"><span class="command"><strong>import-tar</strong></span> <em class="replaceable"><code>FILE</code></em> [<em class="replaceable"><code>NAME</code></em>], </span><span class="term"><span class="command"><strong>import-raw</strong></span> <em class="replaceable"><code>FILE</code></em> [<em class="replaceable"><code>NAME</code></em>]</span><a class="headerlink" title="Permalink to this term" href="#import-tar%20FILE%20%5BNAME%5D"></a></dt><dd><p>Imports a TAR or RAW container or VM image,
and places it under the specified name in
<code class="filename">/var/lib/machines/</code>. When
<span class="command"><strong>import-tar</strong></span> is used the file specified as
first argument should be a tar archive, possibly compressed
with xz, gzip or bzip2. It will then be unpacked into its own
subvolume in <code class="filename">/var/lib/machines</code>. When
<span class="command"><strong>import-raw</strong></span> 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 "<code class="literal">-</code>" the
image is read from standard input, in which case the second
argument is mandatory.</p><p>Similar as with <span class="command"><strong>pull-tar</strong></span>,
<span class="command"><strong>pull-raw</strong></span> the file system
<code class="filename">/var/lib/machines.raw</code> is increased in
size of necessary and appropriate. Optionally the
<code class="option">--read-only</code> switch may be used to create a
read-only container or VM image. No cryptographic validation
is done when importing the images.</p><p>Much like image downloads, ongoing imports may be listed
with <span class="command"><strong>list-transfers</strong></span> and aborted with
<span class="command"><strong>cancel-transfer</strong></span>.</p></dd><dt id="export-tar NAME [FILE]"><span class="term"><span class="command"><strong>export-tar</strong></span> <em class="replaceable"><code>NAME</code></em> [<em class="replaceable"><code>FILE</code></em>], </span><span class="term"><span class="command"><strong>export-raw</strong></span> <em class="replaceable"><code>NAME</code></em> [<em class="replaceable"><code>FILE</code></em>]</span><a class="headerlink" title="Permalink to this term" href="#export-tar%20NAME%20%5BFILE%5D"></a></dt><dd><p>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 "<code class="literal">.gz</code>" the file is compressed with gzip, if
it ends in "<code class="literal">.xz</code>" with xz, and if it ends in
"<code class="literal">.bz2</code>" 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
<code class="option">--format=</code> switch. This is in particular
useful if the second parameter is left unspecified.</p><p>Much like image downloads and imports, ongoing exports
may be listed with <span class="command"><strong>list-transfers</strong></span> and
aborted with
<span class="command"><strong>cancel-transfer</strong></span>.</p><p>Note that currently only directory and subvolume images
may be exported as TAR images, and only raw disk images as RAW
images.</p></dd><dt id="list-transfers"><span class="term"><span class="command"><strong>list-transfers</strong></span></span><a class="headerlink" title="Permalink to this term" href="#list-transfers"></a></dt><dd><p>Shows a list of container or VM image
downloads, imports and exports that are currently in
progress.</p></dd><dt id="cancel-transfers ID..."><span class="term"><span class="command"><strong>cancel-transfers</strong></span> <em class="replaceable"><code>ID</code></em>...</span><a class="headerlink" title="Permalink to this term" href="#cancel-transfers%20ID..."></a></dt><dd><p>Aborts a download, import or export of the
container or VM image with the specified ID. To list ongoing
transfers and their IDs, use
<span class="command"><strong>list-transfers</strong></span>. </p></dd></dl></div></div></div><div class="refsect1"><a name="idm139807808893296"></a><h2 id="Files and Directories">Files and Directories<a class="headerlink" title="Permalink to this headline" href="#Files%20and%20Directories"></a></h2><p>Machine images are preferably stored in
<code class="filename">/var/lib/machines/</code>, but are also searched for
in <code class="filename">/usr/local/lib/machines/</code> and
<code class="filename">/usr/lib/machines/</code>. For compatibility reasons
the directory <code class="filename">/var/lib/container/</code> is
searched, too. Note that images stored below
<code class="filename">/usr</code> are always considered read-only. It is
possible to symlink machines images from other directories into
<code class="filename">/var/lib/machines/</code> to make them available for
control with <span class="command"><strong>machinectl</strong></span>.</p><p>Note that many image operations are only supported,
efficient or atomic on btrfs file systems. Due to this, if the
<span class="command"><strong>pull-tar</strong></span>, <span class="command"><strong>pull-raw</strong></span>,
<span class="command"><strong>pull-dkr</strong></span>, <span class="command"><strong>import-tar</strong></span>,
<span class="command"><strong>import-raw</strong></span> and <span class="command"><strong>set-limit</strong></span>
commands notice that <code class="filename">/var/lib/machines</code> is
empty and not located on btrfs, they will implicitly set up a
loopback file <code class="filename">/var/lib/machines.raw</code>
containing a btrfs file system that is mounted to
<code class="filename">/var/lib/machines</code>. The size of this loopback
file may be controlled dynamically with
<span class="command"><strong>set-limit</strong></span>.</p><p>Disk images are understood by
<a href="systemd-nspawn.html"><span class="citerefentry"><span class="refentrytitle">systemd-nspawn</span>(1)</span></a>
and <span class="command"><strong>machinectl</strong></span> in three formats:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>A simple directory tree, containing the files
and directories of the container to boot.</p></li><li class="listitem"><p>A subvolume (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.</p></li><li class="listitem"><p>"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
"<code class="literal">.raw</code>".</p></li></ul></div><p>See
<a href="systemd-nspawn.html"><span class="citerefentry"><span class="refentrytitle">systemd-nspawn</span>(1)</span></a>
for more information on image formats, in particular it's
<code class="option">--directory=</code> and <code class="option">--image=</code>
options.</p></div><div class="refsect1"><a name="idm139807808873680"></a><h2 id="Examples">Examples<a class="headerlink" title="Permalink to this headline" href="#Examples"></a></h2><div class="example"><a name="idm139807808873040"></a><p class="title"><b>Example 1. Download an Ubuntu image and open a shell in it</b></p><div class="example-contents"><pre class="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</pre><p>This downloads and verifies the specified
<code class="filename">.tar</code> image, and then uses
<a href="systemd-nspawn.html"><span class="citerefentry"><span class="refentrytitle">systemd-nspawn</span>(1)</span></a>
to open a shell in it.</p></div></div><br class="example-break"><div class="example"><a name="idm139807808869696"></a><p class="title"><b>Example 2. Download a Fedora image, set a root password in it, start
it as service</b></p><div class="example-contents"><pre class="programlisting"># machinectl pull-raw --verify=no http://ftp.halifax.rwth-aachen.de/fedora/linux/releases/21/Cloud/Images/x86_64/Fedora-Cloud-Base-20141203-21.x86_64.raw.xz
# systemd-nspawn -M Fedora-Cloud-Base-20141203-21
# passwd
# exit
# machinectl start Fedora-Cloud-Base-20141203-21
# machinectl login Fedora-Cloud-Base-20141203-21</pre><p>This downloads the specified <code class="filename">.raw</code>
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.</p></div></div><br class="example-break"><div class="example"><a name="idm139807808866592"></a><p class="title"><b>Example 3. Download a Fedora "<code class="literal">dkr</code>" image</b></p><div class="example-contents"><pre class="programlisting"># machinectl pull-dkr --verify=no mattdm/fedora
# systemd-nspawn -M fedora</pre><p>Downloads a "<code class="literal">dkr</code>" image and opens a shell
in it. Note that the specified download command might require an
index server to be specified with the
"<code class="literal">--dkr-index-url=</code>".</p></div></div><br class="example-break"><div class="example"><a name="idm139807808862688"></a><p class="title"><b>Example 4. Exports a container image as tar file</b></p><div class="example-contents"><pre class="programlisting"># machinectl export-tar fedora myfedora.tar.xz</pre><p>Exports the container "<code class="literal">fedora</code>" in an
xz-compress tar file <code class="filename">myfedora.tar.xz</code> in the
current directory.</p></div></div><br class="example-break"></div><div class="refsect1"><a name="idm139807808859536"></a><h2 id="Exit status">Exit status<a class="headerlink" title="Permalink to this headline" href="#Exit%20status"></a></h2><p>On success, 0 is returned, a non-zero failure code
otherwise.</p></div><div class="refsect1"><a name="idm139807795081152"></a><h2 id="Environment">Environment<a class="headerlink" title="Permalink to this headline" href="#Environment"></a></h2><div class="variablelist"><dl class="variablelist"><dt id="$SYSTEMD_PAGER"><span class="term"><code class="varname">$SYSTEMD_PAGER</code></span><a class="headerlink" title="Permalink to this term" href="#%24SYSTEMD_PAGER"></a></dt><dd><p>Pager to use when
<code class="option">--no-pager</code> is not given;
overrides <code class="varname">$PAGER</code>. Setting
this to an empty string or the value
"<code class="literal">cat</code>" is equivalent to passing
<code class="option">--no-pager</code>.</p></dd><dt id="$SYSTEMD_LESS"><span class="term"><code class="varname">$SYSTEMD_LESS</code></span><a class="headerlink" title="Permalink to this term" href="#%24SYSTEMD_LESS"></a></dt><dd><p>Override the default
options passed to
<span class="command"><strong>less</strong></span>
("<code class="literal">FRSXMK</code>").</p></dd></dl></div></div><div class="refsect1"><a name="idm139807808857808"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also"></a></h2><p>
<a href="systemd-machined.service.html"><span class="citerefentry"><span class="refentrytitle">systemd-machined.service</span>(8)</span></a>,
<a href="systemd-nspawn.html"><span class="citerefentry"><span class="refentrytitle">systemd-nspawn</span>(1)</span></a>,
<a href="systemd.special.html"><span class="citerefentry"><span class="refentrytitle">systemd.special</span>(7)</span></a>,
<a href="http://linux.die.net/man/1/tar"><span class="citerefentry"><span class="refentrytitle">tar</span>(1)</span></a>,
<a href="http://linux.die.net/man/1/xz"><span class="citerefentry"><span class="refentrytitle">xz</span>(1)</span></a>,
<a href="http://linux.die.net/man/1/gzip"><span class="citerefentry"><span class="refentrytitle">gzip</span>(1)</span></a>,
<a href="http://linux.die.net/man/1/bzip2"><span class="citerefentry"><span class="refentrytitle">bzip2</span>(1)</span></a>
</p></div></div></body></html>
Reference in New Issue View Git Blame Copy Permalink