proxmox-mirrors/systemd
1
0
Fork 0
mirror of https://git.proxmox.com/git/systemd synced 2025-05-29 11:51:49 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity
e735f4d4ea
systemd/man/machinectl.html
Martin Pitt e735f4d4ea Imported Upstream version 219
2015-02-17 11:22:16 +01:00

369 lines
41 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 219</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="idm140317735547456"></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="idm140317735544096"></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="-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="idm140317734475984"></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="idm140317734474960"></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="idm140317734417536"></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 disk 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></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 disk 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 disk 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 disk images.
The special image "<code class="literal">.host</code>", which refers to
the host's own directory tree may not be
removed.</p></dd></dl></div></div><div class="refsect2"><a name="idm140317734393344"></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 the name 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 now 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 the name 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 es 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 now 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 now 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="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 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 download 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="idm140317734341424"></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>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="idm140317734328864"></a><h2 id="Examples">Examples<a class="headerlink" title="Permalink to this headline" href="#Examples"></a></h2><div class="example"><a name="idm140317734328224"></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="idm140317734324880"></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="idm140317739501408"></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><div class="refsect1"><a name="idm140317739497120"></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="idm140317721004464"></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="idm140317739495328"></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>
</p></div></div></body></html>
Reference in New Issue View Git Blame Copy Permalink