diff options
| -rw-r--r-- | man/machinectl.xml | 295 | ||||
| -rw-r--r-- | src/machine/machinectl.c | 2 |
2 files changed, 252 insertions, 45 deletions
diff --git a/man/machinectl.xml b/man/machinectl.xml index ebe8e3b9dc..91bdb5e111 100644 --- a/man/machinectl.xml +++ b/man/machinectl.xml @@ -76,27 +76,31 @@ <term><option>-p</option></term> <term><option>--property=</option></term> - <listitem><para>When showing - machine properties, limit the - output to certain properties as - specified by the argument. If not - specified, all set properties are - shown. The argument should be a - property name, such as - <literal>Name</literal>. If - specified more than once, all - properties with the specified names - are shown.</para></listitem> + <listitem><para>When showing machine + or image properties, limit the output + to certain properties as specified by + the argument. If not specified, all + set properties are shown. The argument + should be a property name, such as + <literal>Name</literal>. If specified + more than once, all properties with + the specified names are + shown.</para></listitem> </varlistentry> <varlistentry> <term><option>-a</option></term> <term><option>--all</option></term> - <listitem><para>When showing - machine properties, show all - properties regardless of whether they are - set or not.</para></listitem> + <listitem><para>When showing machine + or image properties, show all + properties regardless of whether they + are set or not.</para> + + <para>When listing VM or container + images, do not suppress images + beginning in a dot character + (<literal>.</literal>).</para></listitem> </varlistentry> <varlistentry> @@ -208,16 +212,24 @@ <xi:include href="standard-options.xml" xpointer="version" /> <xi:include href="standard-options.xml" xpointer="no-pager" /> </variablelist> + </refsect1> + + <refsect1> + <title>Commands</title> <para>The following commands are understood:</para> - <variablelist> + <refsect2><title>Machine Commands</title><variablelist> + <varlistentry> <term><command>list</command></term> <listitem><para>List currently running - virtual machines and containers. - </para></listitem> + (online) virtual machines and + containers. To enumerate container + images that can be started, + use <command>list-images</command> + (see below).</para></listitem> </varlistentry> <varlistentry> @@ -265,29 +277,91 @@ </varlistentry> <varlistentry> + <term><command>start</command> <replaceable>NAME</replaceable>...</term> + + <listitem><para>Start a container as a + system service, using + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + This starts + <filename>systemd-nspawn@.service</filename>, + instantiated for the specified machine + name, similar to the effect of + <command>systemctl start</command> on + the service + name. <command>systemd-nspawn</command> + looks for a container image by the + specified name in + <filename>/var/lib/container</filename> + and runs it. Use + <command>list-images</command> (see + below), for listing available + container images to start.</para> + + <para>Note that + <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + also interfaces with a variety of + other container and VM managers, + <command>systemd-nspawn</command> is + just one implementation of it. Most of + the commands available in + <command>machinectl</command> may be + used on containers or VMs controlled + by other managers, not just + <command>systemd-nspawn</command>. Starting + VMs and container images on those + managers requires manager-specific + tools.</para> + + <para>To interactively start a + container on the command line with + full access to the container's + console, please invoke + <command>systemd-nspawn</command> + directly. To stop a running container + use <command>machinectl + poweroff</command>, see + below.</para></listitem> + </varlistentry> + + <varlistentry> <term><command>login</command> <replaceable>NAME</replaceable></term> - <listitem><para>Open a terminal login + <listitem><para>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 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> - as init system.</para></listitem> + as init system.</para> + + <para>This command will open a full + login prompt on the container, which + then asks for username and + password. Use + <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry> + with the <option>--machine=</option> + switch to invoke a single command, + either interactively or in the + background within a local + container.</para></listitem> </varlistentry> <varlistentry> - <term><command>reboot</command> <replaceable>NAME</replaceable>...</term> - - <listitem><para>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 - init system.</para></listitem> + <term><command>enable</command> <replaceable>NAME</replaceable>...</term> + <term><command>disable</command> <replaceable>NAME</replaceable>...</term> + + <listitem><para>Enable or disable a + container as a system service to start + at system boot, using + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + This enables or disables + <filename>systemd-nspawn@.service</filename>, + instantiated for the specified machine + name, similar to the effect of + <command>systemctl enable</command> or + <command>systemctl disable</command> + on the service name.</para></listitem> </varlistentry> <varlistentry> @@ -302,8 +376,38 @@ not work on containers that do not run a <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible - init system, such as - sysvinit.</para></listitem> + init system, such as sysvinit. Use + <command>terminate</command> (see + below) to immediately terminate a + container or VM, without cleanly + shutting it down.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>reboot</command> <replaceable>NAME</replaceable>...</term> + + <listitem><para>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.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>terminate</command> <replaceable>NAME</replaceable>...</term> + + <listitem><para>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 + <command>poweroff</command> to issue a + clean shutdown request.</para></listitem> </varlistentry> <varlistentry> @@ -322,17 +426,6 @@ </varlistentry> <varlistentry> - <term><command>terminate</command> <replaceable>NAME</replaceable>...</term> - - <listitem><para>Terminates a virtual - machine or container. This kills all - processes of the virtual machine or - container and deallocates all - resources attached to that - instance.</para></listitem> - </varlistentry> - - <varlistentry> <term><command>bind</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term> <listitem><para>Bind mounts a @@ -383,8 +476,122 @@ omitted the same as the source path is used.</para></listitem> </varlistentry> + </variablelist></refsect2> - </variablelist> + <refsect2><title>Image Commands</title><variablelist> + + <varlistentry> + <term><command>list-images</command></term> + + <listitem><para>Show a list of locally + installed container and VM + images. This enumerates all raw disk + images and container directories and + subvolumes in + <filename>/var/lib/container/</filename>. Use + <command>start</command> (see above) + to run a container off one of the + listed images. Note that by default + containers whose name begins with a + dot (<literal>.</literal>) are not + shown. To show these too, specify + <option>--all</option>. Note that a + special image <literal>.host</literal> + always implicitly exists and refers to + the image the host itself is booted + from.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>image-status</command> <replaceable>NAME</replaceable>...</term> + + <listitem><para>Show terse status + information about one or more + container or VM images. This function + is intended to generate human-readable + output. Use + <command>show-image</command> (see + below) to generate computer-parsable + output instead.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>show-image</command> <replaceable>NAME</replaceable>...</term> + + <listitem><para>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 + <option>--all</option> to show those + too. To select specific properties to + show, use + <option>--property=</option>. This + command is intended to be used + whenever computer-parsable output is + required. Use + <command>image-status</command> if you + are looking for formatted + human-readable + output.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>clone</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term> + + <listitem><para>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.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>rename</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term> + + <listitem><para>Renames a container or + disk image. The arguments specify the + name of the image to rename and the + new name of the + image.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>read-only</command> <replaceable>NAME</replaceable> [<replaceable>BOOL</replaceable>]</term> + + <listitem><para>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.</para></listitem> + </varlistentry> + + + <varlistentry> + <term><command>remove</command> <replaceable>NAME</replaceable>...</term> + + <listitem><para>Removes one or more + container or disk images. The special + image <literal>.host</literal>, which + refers to the host's own directory + tree may not be + removed.</para></listitem> + </varlistentry> + + + </variablelist></refsect2> </refsect1> diff --git a/src/machine/machinectl.c b/src/machine/machinectl.c index 939b648150..dbfc24541e 100644 --- a/src/machine/machinectl.c +++ b/src/machine/machinectl.c @@ -1760,8 +1760,8 @@ static int help(int argc, char *argv[], void *userdata) { " list List running VMs and containers\n" " status NAME... Show VM/container details\n" " show NAME... Show properties of one or more VMs/containers\n" - " login NAME Get a login prompt on a container\n" " start NAME... Start container as a service\n" + " login NAME Get a login prompt on a container\n" " enable NAME... Enable automatic container start at boot\n" " disable NAME... Disable automatic container start at boot\n" " poweroff NAME... Power off one or more containers\n" |