1---
2title: Converting Existing Users to systemd-homed
3category: Users, Groups and Home Directories
4layout: default
5SPDX-License-Identifier: LGPL-2.1-or-later
6---
7
8# Converting Existing Users to systemd-homed managed Users
9
10Traditionally on most Linux distributions, regular (human) users are managed
11via entries in `/etc/passwd`, `/etc/shadow`, `/etc/group` and
12`/etc/gshadow`. With the advent of
13[`systemd-homed`](https://www.freedesktop.org/software/systemd/man/systemd-homed.service.html)
14it might be desirable to convert an existing, traditional user account to a
15`systemd-homed` managed one. Below is a brief guide how to do that.
16
17Before continuing, please read up on these basic concepts:
18
19* [Home Directories](HOME_DIRECTORY.md)
20* [JSON User Records](USER_RECORD.md)
21* [JSON Group Records](GROUP_RECORD.md)
22* [User/Group Record Lookup API via Varlink](USER_GROUP_API.md)
23
24## Caveat
25
26This is a manual process, and possibly a bit fragile. Hence, do this at your
27own risk, read up beforehand, and make a backup first. You know what's at
28stake: your own home directory, i.e. all your personal data.
29
30## Step-By-Step
31
32Here's the step-by-step guide:
33
340. Preparations: make sure you run a distribution that has `systemd-homed`
35   enabled and properly set up, including the necessary PAM and NSS
36   configuration updates. Make sure you have enough disk space in `/home/` for
37   a (temporary) second copy of your home directory. Make sure to backup your
38   home directory. Make sure to log out of your user account fully. Then log in
39   as root on the console.
40
411. Rename your existing home directory to something safe. Let's say your user
42   ID is `foobar`. Then do:
43
44    ```
45    mv /home/foobar /home/foobar.saved
46    ```
47
482. Have a look at your existing user record, as stored in `/etc/passwd` and
49   related files. We want to use the same data for the new record, hence it's good
50   looking at the old data. Use commands such as:
51
52    ```
53    getent passwd foobar
54    getent shadow foobar
55    ```
56
57   This will tell you the `/etc/passwd` and `/etc/shadow` entries for your
58   user. For details about the fields, see the respective man pages
59   [passwd(5)](http://man7.org/linux/man-pages/man5/passwd.5.html) and
60   [shadow(5)](http://man7.org/linux/man-pages/man5/shadow.5.html).
61
62   The fourth field in the `getent passwd foobar` output tells you the GID of
63   your user's main group. Depending on your distribution it's a group private
64   to the user, or a group shared by most local, regular users. Let's say the
65   GID reported is 1000, let's then query its details:
66
67    ```
68    getent group 1000
69    ```
70
71   This will tell you the name of that group. If the name is the same as your
72   user name your distribution apparently provided you with a private group for
73   your user. If it doesn't match (and is something like `users`) it apparently
74   didn't. Note that `systemd-homed` will always manage a private group for
75   each user under the same name, hence if your distribution is one of the
76   latter kind, then there's a (minor) mismatch in structure when converting.
77
78   Save the information reported by these three commands somewhere, for later
79   reference.
80
813. Now edit your `/etc/passwd` file and remove your existing record
82   (i.e. delete a single line, the one of your user's account, leaving all
83   other lines unmodified). Similar for `/etc/shadow`, `/etc/group` (in case
84   you have a private group for your user) and `/etc/gshadow`. Most
85   distributions provide you with a tool for that, that adds safe
86   synchronization for these changes: `vipw`, `vipw -s`, `vigr` and `vigr -s`.
87
884. At this point the old user account vanished, while the home directory still
89   exists safely under the `/home/foobar.saved` name. Let's now create a new
90   account with `systemd-homed`, using the same username and UID as before:
91
92    ```
93    homectl create foobar --uid=$UID --real-name=$GECOS
94    ```
95
96   In this command line, replace `$UID` by the UID you previously used,
97   i.e. the third field of the `getent passwd foobar` output above. Similar,
98   replace `$GECOS` by the GECOS field of your old account, i.e the fifth field
99   of the old output. If your distribution traditionally does not assign a
100   private group to regular user groups, then consider adding `--member-of=`
101   with the group name to get a modicum of compatibility with the status quo
102   ante: this way your new user account will still not have the old primary
103   group as new primary group, but will have it as auxiliary group.
104
105   Consider reading through the
106   [homectl(1)](https://www.freedesktop.org/software/systemd/man/homectl.html)
107   manual page at this point, maybe there are a couple of other settings you
108   want to set for your new account. In particular, look at `--storage=` and
109   `--disk-size=`, in order to change how your home directory shall be stored
110   (the default `luks` storage is recommended).
111
1125. Your new user account exists now, but it has an empty home directory. Let's
113   now migrate your old home directory into it. For that let's mount the new
114   home directory temporarily and copy the data in.
115
116    ```
117    homectl with foobar -- rsync -aHAXv --remove-source-files /home/foobar.saved/ .
118    ```
119
120   This mounts the home directory of the user, and then runs the specified
121   `rsync` command which copies the contents of the old home directory into the
122   new. The new home directory is the working directory of the invoked `rsync`
123   process. We are invoking this command as root, hence the `rsync` runs as
124   root too. When the `rsync` command completes the home directory is
125   automatically unmounted again. Since we used `--remove-source-files` all files
126   copied are removed from the old home directory as the copy progresses. After
127   the command completes the old home directory should be empty. Let's remove
128   it hence:
129
130    ```
131    rmdir /home/foobar.saved
132    ```
133
134And that's it, we are done already. You can log out now and should be able to
135log in under your user account as usual, but now with `systemd-homed` managing
136your home directory.
137