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