]>
Commit | Line | Data |
---|---|---|
5a303332 LP |
1 | --- |
2 | title: Converting Existing Users to systemd-homed | |
5fe63895 | 3 | category: Users, Groups and Home Directories |
5a303332 | 4 | layout: default |
0aff7b75 | 5 | SPDX-License-Identifier: LGPL-2.1-or-later |
5a303332 LP |
6 | --- |
7 | ||
8 | # Converting Existing Users to systemd-homed managed Users | |
9 | ||
10 | Traditionally on most Linux distributions, regular (human) users are managed | |
11 | via 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) | |
14 | it 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 | ||
17 | Before continuing, please read up on these basic concepts: | |
18 | ||
5e8ff010 | 19 | * [Home Directories](HOME_DIRECTORY) |
20 | * [JSON User Records](USER_RECORD) | |
21 | * [JSON Group Records](GROUP_RECORD) | |
22 | * [User/Group Record Lookup API via Varlink](USER_GROUP_API) | |
5a303332 LP |
23 | |
24 | ## Caveat | |
25 | ||
26 | This is a manual process, and possibly a bit fragile. Hence, do this at your | |
27 | own risk, read up beforehand, and make a backup first. You know what's at | |
28 | stake: your own home directory, i.e. all your personal data. | |
29 | ||
30 | ## Step-By-Step | |
31 | ||
32 | Here's the step-by-step guide: | |
33 | ||
34 | 0. 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 | ||
41 | 1. 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 | ||
48 | 2. 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 | |
e2285c57 MB |
59 | [passwd(5)](https://man7.org/linux/man-pages/man5/passwd.5.html) and |
60 | [shadow(5)](https://man7.org/linux/man-pages/man5/shadow.5.html). | |
5a303332 LP |
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 | ||
81 | 3. 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 | ||
88 | 4. 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 | ||
112 | 5. 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 | ``` | |
3d3e51ef | 117 | homectl with foobar -- rsync -aHANUXv --remove-source-files /home/foobar.saved/ . |
5a303332 LP |
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 | |
c28904da | 125 | automatically unmounted again. Since we used `--remove-source-files` all files |
5a303332 LP |
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 | ||
134 | And that's it, we are done already. You can log out now and should be able to | |
135 | log in under your user account as usual, but now with `systemd-homed` managing | |
136 | your home directory. |