X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fmachinectl.xml;h=f6729151ba9ab854bd7472b048f0f336f72e7609;hp=55bb694e6c6bfbeb964aea2fa619632be72f65e5;hb=3ba3a79df4ae094d1008c04a9af8d1ff970124c4;hpb=7de304525deafe4eb86060321e39787138dbbadf

diff --git a/man/machinectl.xml b/man/machinectl.xml
index 55bb694e6..f6729151b 100644
--- a/man/machinectl.xml
+++ b/man/machinectl.xml
@@ -214,6 +214,18 @@
         URL.</para></listitem>
       </varlistentry>
 
+      <varlistentry>
+        <term><option>--format=</option></term>
+
+        <listitem><para>When used with the <option>export-tar</option>
+        or <option>export-raw</option> commands specifies the
+        compression format to use for the resulting file. Takes one of
+        <literal>uncompressed</literal>, <literal>xz</literal>,
+        <literal>gzip</literal>, <literal>bzip2</literal>. By default
+        the format is determined automatically from the image file
+        name passed.</para></listitem>
+      </varlistentry>
+
       <xi:include href="user-system-options.xml" xpointer="host" />
       <xi:include href="user-system-options.xml" xpointer="machine" />
 
@@ -669,19 +681,78 @@
         below.</para></listitem>
       </varlistentry>
 
+      <varlistentry>
+        <term><command>import-tar</command> <replaceable>FILE</replaceable> [<replaceable>NAME</replaceable>]</term>
+        <term><command>import-raw</command> <replaceable>FILE</replaceable> [<replaceable>NAME</replaceable>]</term>
+        <listitem><para>Imports a TAR or RAW container or VM image,
+        and places it under the specified name in
+        <filename>/var/lib/machines/</filename>. When
+        <command>import-tar</command> 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 <filename>/var/lib/machines</filename>. When
+        <command>import-raw</command> 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 <literal>-</literal> the
+        image is read from standard input, in which case the second
+        argument is mandatory.</para>
+
+        <para>Similar as with <command>pull-tar</command>,
+        <command>pull-raw</command> the file system
+        <filename>/var/lib/machines.raw</filename> is increased in
+        size of necessary and appropriate. Optionally the
+        <option>--read-only</option> switch may be used to create a
+        read-only container or VM image. No cryptographic validation
+        is done when importing the images.</para>
+
+        <para>Much like image downloads, ongoing imports may be listed
+        with <command>list-transfers</command> and aborted with
+        <command>cancel-transfer</command>.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><command>export-tar</command> <replaceable>NAME</replaceable> [<replaceable>FILE</replaceable>]</term>
+        <term><command>export-raw</command> <replaceable>NAME</replaceable> [<replaceable>FILE</replaceable>]</term>
+        <listitem><para>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 <literal>.gz</literal> the file is compressed with gzip, if
+        it ends in <literal>.xz</literal> with xz, and if it ends in
+        <literal>.bz2</literal> 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
+        <option>--format=</option> switch. This is in particular
+        useful if the second parameter is left unspecified.</para>
+
+        <para>Much like image downloads and imports, ongoing exports
+        may be listed with <command>list-transfers</command> and
+        aborted with
+        <command>cancel-transfer</command>.</para>
+
+        <para>Note that currently only directory and subvolume images
+        may be exported as TAR images, and only raw disk images as RAW
+        images.</para></listitem>
+      </varlistentry>
+
       <varlistentry>
         <term><command>list-transfers</command></term>
 
         <listitem><para>Shows a list of container or VM image
-        downloads that are currently in progress.</para></listitem>
+        downloads, imports and exports that are currently in
+        progress.</para></listitem>
       </varlistentry>
 
       <varlistentry>
         <term><command>cancel-transfers</command> <replaceable>ID</replaceable>...</term>
 
-        <listitem><para>Aborts download of the container or VM image
-        with the specified ID. To list ongoing transfers and their
-        IDs, use <command>list-transfers</command>. </para></listitem>
+        <listitem><para>Aborts a download, import or export of the
+        container or VM image with the specified ID. To list ongoing
+        transfers and their IDs, use
+        <command>list-transfers</command>. </para></listitem>
       </varlistentry>
 
     </variablelist></refsect2>
@@ -705,13 +776,15 @@
     <para>Note that many image operations are only supported,
     efficient or atomic on btrfs file systems. Due to this, if the
     <command>pull-tar</command>, <command>pull-raw</command>,
-    <command>pull-dkr</command> and <command>set-limit</command>
+    <command>pull-dkr</command>, <command>import-tar</command>,
+    <command>import-raw</command> and <command>set-limit</command>
     commands notice that <filename>/var/lib/machines</filename> is
     empty and not located on btrfs, they will implicitly set up a
     loopback file <filename>/var/lib/machines.raw</filename>
     containing a btrfs file system that is mounted to
     <filename>/var/lib/machines</filename>. The size of this loopback
-    file may be controlled dynamically with <command>set-limit</command>.</para>
+    file may be controlled dynamically with
+    <command>set-limit</command>.</para>
 
     <para>Disk images are understood by
     <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
@@ -782,6 +855,17 @@
       index server to be specified with the
       <literal>--dkr-index-url=</literal>.</para>
     </example>
+
+    <example>
+      <title>Exports a container image as tar file</title>
+
+      <programlisting># machinectl export-tar fedora myfedora.tar.xz</programlisting>
+
+      <para>Exports the container <literal>fedora</literal> in an
+      xz-compress tar file <filename>myfedora.tar.xz</filename> in the
+      current directory.</para>
+    </example>
+
   </refsect1>
 
   <refsect1>
@@ -798,7 +882,11 @@
     <para>
       <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+      <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+      <citerefentry project='die-net'><refentrytitle>tar</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry project='die-net'><refentrytitle>xz</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry project='die-net'><refentrytitle>gzip</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry project='die-net'><refentrytitle>bzip2</refentrytitle><manvolnum>1</manvolnum></citerefentry>
     </para>
   </refsect1>