]> git.ipfire.org Git - thirdparty/systemd.git/blob - man/systemd-homed.service.xml
e14752b6626b377459f8c06066c0fa4d4906b0e8
[thirdparty/systemd.git] / man / systemd-homed.service.xml
1 <?xml version='1.0'?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
5
6 <refentry id="systemd-homed.service" conditional='ENABLE_HOMED'
7 xmlns:xi="http://www.w3.org/2001/XInclude">
8
9 <refentryinfo>
10 <title>systemd-homed.service</title>
11 <productname>systemd</productname>
12 </refentryinfo>
13
14 <refmeta>
15 <refentrytitle>systemd-homed.service</refentrytitle>
16 <manvolnum>8</manvolnum>
17 </refmeta>
18
19 <refnamediv>
20 <refname>systemd-homed.service</refname>
21 <refname>systemd-homed</refname>
22 <refpurpose>Home Area/User Account Manager</refpurpose>
23 </refnamediv>
24
25 <refsynopsisdiv>
26 <para><filename>systemd-homed.service</filename></para>
27 <para><filename>/usr/lib/systemd/systemd-homed</filename></para>
28 </refsynopsisdiv>
29
30 <refsect1>
31 <title>Description</title>
32
33 <para><command>systemd-homed</command> is a system service that may be used to create, remove, change or
34 inspect home areas (directories and network mounts and real or loopback block devices with a filesystem,
35 optionally encrypted).</para>
36
37 <para>Most of <command>systemd-homed</command>'s functionality is accessible through the
38 <citerefentry><refentrytitle>homectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> command.</para>
39
40 <para>See the <ulink url="https://systemd.io/HOME_DIRECTORY">Home Directories</ulink> documentation for
41 details about the format and design of home areas managed by
42 <filename>systemd-homed.service</filename>.</para>
43
44 <para>Each home directory managed by <filename>systemd-homed.service</filename> synthesizes a local user
45 and group. These are made available to the system using the <ulink
46 url="https://systemd.io/USER_GROUP_API">User/Group Record Lookup API via Varlink</ulink>, and thus may be
47 browsed with
48 <citerefentry><refentrytitle>userdbctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
49 </refsect1>
50
51 <refsect1>
52 <title>Key Management</title>
53
54 <para>User records are cryptographically signed with a public/private key pair (the signature is part of
55 the JSON record itself). For a user to be permitted to log in locally the public key matching the
56 signature of their user record must be installed. For a user record to be modified locally the private
57 key matching the signature must be installed locally, too. The keys are stored in the
58 <filename>/var/lib/systemd/home/</filename> directory:</para>
59
60 <variablelist>
61
62 <varlistentry>
63 <term><filename>/var/lib/systemd/home/local.private</filename></term>
64
65 <listitem><para>The private key of the public/private key pair used for local records. Currently,
66 only a single such key may be installed.</para>
67
68 <xi:include href="version-info.xml" xpointer="v246"/></listitem>
69 </varlistentry>
70
71 <varlistentry>
72 <term><filename>/var/lib/systemd/home/local.public</filename></term>
73
74 <listitem><para>The public key of the public/private key pair used for local records. Currently,
75 only a single such key may be installed.</para>
76
77 <xi:include href="version-info.xml" xpointer="v246"/></listitem>
78 </varlistentry>
79
80 <varlistentry>
81 <term><filename>/var/lib/systemd/home/*.public</filename></term>
82
83 <listitem><para>Additional public keys. Any users whose user records are signed with any of these keys
84 are permitted to log in locally. An arbitrary number of keys may be installed this
85 way.</para>
86
87 <xi:include href="version-info.xml" xpointer="v246"/></listitem>
88 </varlistentry>
89 </variablelist>
90
91 <para>All key files listed above are in PEM format.</para>
92
93 <para>In order to migrate a home directory from a host <literal>foobar</literal> to another host
94 <literal>quux</literal> it is hence sufficient to copy
95 <filename>/var/lib/systemd/home/local.public</filename> from the host <literal>foobar</literal> to
96 <literal>quux</literal>, maybe calling the file on the destination <filename
97 index="false">/var/lib/systemd/home/foobar.public</filename>, reflecting the origin of the key. If the
98 user record should be modifiable on <literal>quux</literal> the pair
99 <filename>/var/lib/systemd/home/local.public</filename> and
100 <filename>/var/lib/systemd/home/local.private</filename> need to be copied from <literal>foobar</literal>
101 to <literal>quux</literal>, and placed under the identical paths there, as currently only a single
102 private key is supported per host. Note of course that the latter means that user records
103 generated/signed before the key pair is copied in, lose their validity.</para>
104 </refsect1>
105
106 <refsect1>
107 <title>See Also</title>
108 <para>
109 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
110 <citerefentry><refentrytitle>homed.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
111 <citerefentry><refentrytitle>homectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
112 <citerefentry><refentrytitle>pam_systemd_home</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
113 <citerefentry><refentrytitle>userdbctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
114 <citerefentry><refentrytitle>org.freedesktop.home1</refentrytitle><manvolnum>5</manvolnum></citerefentry>
115 </para>
116 </refsect1>
117 </refentry>