man: document that machinectl set-limit creates a btrfs loopback too

[elogind.git] / man / machinectl.xml

diff --git a/man/machinectl.xml b/man/machinectl.xml
index 640cb8b7d691ef6093030460ab86e6bdbd68d627..55bb694e6c6bfbeb964aea2fa619632be72f65e5 100644 (file)
--- a/man/machinectl.xml
+++ b/man/machinectl.xml
@@ -469,7 +469,7 @@
       <varlistentry>
         <term><command>clone</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term>
 
-        <listitem><para>Clones a container or disk image. The
+        <listitem><para>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.
@@ -481,7 +481,7 @@
       <varlistentry>
         <term><command>rename</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term>
 
-        <listitem><para>Renames a container or disk image. The
+        <listitem><para>Renames a container or VM image. The
         arguments specify the name of the image to rename and the new
         name of the image.</para></listitem>
       </varlistentry>
@@ -489,22 +489,53 @@
       <varlistentry>
         <term><command>read-only</command> <replaceable>NAME</replaceable> [<replaceable>BOOL</replaceable>]</term>
 
-        <listitem><para>Marks or (unmarks) a container or disk image
+        <listitem><para>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.</para></listitem>
       </varlistentry>
 
-
       <varlistentry>
         <term><command>remove</command> <replaceable>NAME</replaceable>...</term>
 
-        <listitem><para>Removes one or more container or disk images.
+        <listitem><para>Removes one or more container or VM images.
         The special image <literal>.host</literal>, which refers to
         the host's own directory tree may not be
         removed.</para></listitem>
       </varlistentry>
 
+      <varlistentry>
+        <term><command>set-limit</command> [<replaceable>NAME</replaceable>] <replaceable>BYTES</replaceable></term>
+
+        <listitem><para>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
+        <literal>-</literal> as size.</para>
+
+        <para>Note that per-container size limits are only supported
+        on btrfs file systems. Also note that if
+        <command>set-limit</command> is invoked without image
+        parameter, and <filename>/var/lib/machines</filename> is
+        empty, and the directory is not located on btrfs, a btrfs
+        loopback file is implicitly created as
+        <filename>/var/lib/machines.raw</filename> with the given
+        size, and mounted to
+        <filename>/var/lib/machines</filename>. The size of the
+        loopback may later be readjusted with
+        <command>set-limit</command>, as well. If such a
+        loopback-mounted <filename>/var/lib/machines</filename>
+        directory is used <command>set-limit</command> without image
+        name alters both the quota setting within the file system as
+        well as the loopback file and file system size
+        itself.</para></listitem>
+      </varlistentry>
+
     </variablelist></refsect2>
 
     <refsect2><title>Image Transfer Commands</title><variablelist>
@@ -671,6 +702,17 @@
     <filename>/var/lib/machines/</filename> to make them available for
     control with <command>machinectl</command>.</para>
 
+    <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>
+    commands notice that <filename>/var/lib/machines</filename> is
+    empty and not located on btrfs, they will implicitly set up a
+    loopback file <filename>/var/lib/machines.raw</filename>
+    containing a btrfs file system that is mounted to
+    <filename>/var/lib/machines</filename>. The size of this loopback
+    file may be controlled dynamically with <command>set-limit</command>.</para>
+
     <para>Disk images are understood by
     <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
     and <command>machinectl</command> in three formats:</para>