man: document homed.conf

2020-05-05 11:02:12 +02:00 · 2020-05-05 11:02:12 +02:00 · feb86ca90c
parent c76dd733af
commit feb86ca90c
5 changed files with 103 additions and 6 deletions
--- a/man/directives-template.xml
+++ b/man/directives-template.xml
@ -51,6 +51,15 @@
    <variablelist id='efi-variables' />
  </refsect1>

+  <refsect1>
+    <title>Home Area/User Account directives</title>
+
+    <para>Directives for configuring home areas and user accounts via
+    <citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
+
+    <variablelist id='home-directives' />
+  </refsect1>
+
  <refsect1>
    <title>UDEV directives</title>

--- a/man/homectl.xml
+++ b/man/homectl.xml
@ -504,9 +504,9 @@
        <listitem><para>Selects the storage mechanism to use for this home directory. Takes one of
        <literal>luks</literal>, <literal>fscrypt</literal>, <literal>directory</literal>,
        <literal>subvolume</literal>, <literal>cifs</literal>. For details about these mechanisms, see
-        above. If a new home directory is created and the storage type is not specifically specified defaults
-        to <literal>luks</literal> if supported, <literal>subvolume</literal> as first fallback if supported,
-        and <literal>directory</literal> if not.</para></listitem>
+        above. If a new home directory is created and the storage type is not specifically specified,
+        <citerefentry><refentrytitle>homed.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+        defines which default storage to use.</para></listitem>
      </varlistentry>

      <varlistentry>
@ -525,9 +525,10 @@

        <listitem><para>When LUKS2 storage is used configures the file system type to use inside the home
        directory LUKS2 container. One of <literal>ext4</literal>, <literal>xfs</literal>,
-        <literal>btrfs</literal>. If not specified defaults to <literal>ext4</literal>. Note that
-        <literal>xfs</literal> is not recommended as its support for file system resizing is too
-        limited.</para></listitem>
+        <literal>btrfs</literal>. If not specified
+        <citerefentry><refentrytitle>homed.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+        defines which default file system type to use. Note that <literal>xfs</literal> is not recommended as
+        its support for file system resizing is too limited.</para></listitem>
      </varlistentry>

      <varlistentry>
@ -837,6 +838,7 @@ homectl update lafcadio --pkcs11-token-uri=…</programlisting>
    <para>
      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>homed.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>userdbctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry project='man-pages'><refentrytitle>useradd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
      <citerefentry project='man-pages'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
--- a/man/homed.conf.xml
+++ b/man/homed.conf.xml
@ -0,0 +1,84 @@
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1+ -->
+
+<refentry id="homed.conf" conditional='ENABLE_RESOLVE'
+    xmlns:xi="http://www.w3.org/2001/XInclude">
+  <refentryinfo>
+    <title>homed.conf</title>
+    <productname>systemd</productname>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>homed.conf</refentrytitle>
+    <manvolnum>5</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>homed.conf</refname>
+    <refname>homed.conf.d</refname>
+    <refpurpose>Home area/user account manager configuration files</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <para><filename>/etc/systemd/homed.conf</filename></para>
+    <para><filename>/etc/systemd/homed.conf.d/*.conf</filename></para>
+    <para><filename>/run/systemd/homed.conf.d/*.conf</filename></para>
+    <para><filename>/usr/lib/systemd/homed.conf.d/*.conf</filename></para>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para>These configuration files control default parameters for home areas/user accounts created and
+    managed by
+    <citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
+
+  </refsect1>
+
+  <xi:include href="standard-conf.xml" xpointer="main-conf" />
+
+  <refsect1>
+    <title>Options</title>
+
+    <para>The following options are available in the <literal>[Home]</literal> section:</para>
+
+    <variablelist class='home-directives'>
+
+      <varlistentry>
+        <term><varname>DefaultStorage=</varname></term>
+        <listitem><para>The default storage to use for home areas. Takes one of <literal>luks</literal>,
+        <literal>fscrypt</literal>, <literal>directory</literal>, <literal>subvolume</literal>,
+        <literal>cifs</literal>. For details about these options, see
+        <citerefentry><refentrytitle>homectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. If not
+        configured or assigned the empty string, the default storage is automatically determined: if not
+        running in a container enviroment and <filename>/home/</filename> is not itself encrypted, defaults
+        to <literal>luks</literal>. Otherwise defaults to <literal>subvolume</literal> if
+        <filename>/home/</filename> is on a btrfs file system, and <literal>directory</literal>
+        otherwise. Note that the storage selected on the <command>homectl</command> command line always takes
+        precedence.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>DefaultFileSystemType=</varname></term>
+        <listitem><para>When using <literal>luks</literal> as storage (see above), selects the default file
+        system to use inside the user's LUKS volume. Takes one of <literal>ext4</literal>,
+        <literal>xfs</literal> or <literal>btrfs</literal>. If not specified defaults to
+        <literal>ext4</literal>. This setting has no effect if a different storage mechanism is used. The
+        file system type selected on the <command>homectl</command> command line always takes
+        precedence.</para></listitem>
+      </varlistentry>
+
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+      <title>See Also</title>
+      <para>
+      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+      </para>
+  </refsect1>
+
+</refentry>
--- a/man/rules/meson.build
+++ b/man/rules/meson.build
@ -18,6 +18,7 @@ manpages = [
 ['file-hierarchy', '7', [], ''],
 ['halt', '8', ['poweroff', 'reboot'], ''],
 ['homectl', '1', [], 'ENABLE_HOMED'],
+ ['homed.conf', '5', ['homed.conf.d'], 'ENABLE_RESOLVE'],
 ['hostname', '5', [], ''],
 ['hostnamectl', '1', [], 'ENABLE_HOSTNAMED'],
 ['hwdb', '7', [], 'ENABLE_HWDB'],
--- a/man/systemd-homed.service.xml
+++ b/man/systemd-homed.service.xml
@ -100,6 +100,7 @@
    <title>See Also</title>
    <para>
      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>homed.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>homectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>pam_systemd_home</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>userdbctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>