2020-04-09 15:13:12 +00:00
|
|
|
---
|
|
|
|
title: Converting Existing Users to systemd-homed
|
2020-04-11 16:03:24 +00:00
|
|
|
category: Users, Groups and Home Directories
|
2020-04-09 15:13:12 +00:00
|
|
|
layout: default
|
2021-09-14 14:05:21 +00:00
|
|
|
SPDX-License-Identifier: LGPL-2.1-or-later
|
2020-04-09 15:13:12 +00:00
|
|
|
---
|
|
|
|
|
|
|
|
# Converting Existing Users to systemd-homed managed Users
|
|
|
|
|
|
|
|
Traditionally on most Linux distributions, regular (human) users are managed
|
2024-02-26 12:57:40 +00:00
|
|
|
via entries in `/etc/passwd`, `/etc/shadow`, `/etc/group` and `/etc/gshadow`.
|
|
|
|
With the advent of
|
2020-04-09 15:13:12 +00:00
|
|
|
[`systemd-homed`](https://www.freedesktop.org/software/systemd/man/systemd-homed.service.html)
|
|
|
|
it might be desirable to convert an existing, traditional user account to a
|
2024-02-26 12:57:40 +00:00
|
|
|
`systemd-homed` managed one.
|
|
|
|
Below is a brief guide how to do that.
|
2020-04-09 15:13:12 +00:00
|
|
|
|
|
|
|
Before continuing, please read up on these basic concepts:
|
|
|
|
|
2024-02-23 08:56:00 +00:00
|
|
|
* [Home Directories](HOME_DIRECTORY)
|
|
|
|
* [JSON User Records](USER_RECORD)
|
|
|
|
* [JSON Group Records](GROUP_RECORD)
|
|
|
|
* [User/Group Record Lookup API via Varlink](USER_GROUP_API)
|
2020-04-09 15:13:12 +00:00
|
|
|
|
|
|
|
## Caveat
|
|
|
|
|
2024-02-26 12:57:40 +00:00
|
|
|
This is a manual process, and possibly a bit fragile.
|
|
|
|
Hence, do this at your own risk, read up beforehand, and make a backup first.
|
|
|
|
You know what's at stake: your own home directory, i.e. all your personal data.
|
2020-04-09 15:13:12 +00:00
|
|
|
|
|
|
|
## Step-By-Step
|
|
|
|
|
|
|
|
Here's the step-by-step guide:
|
|
|
|
|
|
|
|
0. Preparations: make sure you run a distribution that has `systemd-homed`
|
2024-02-26 12:57:40 +00:00
|
|
|
enabled and properly set up, including the necessary PAM and NSS configuration updates.
|
|
|
|
Make sure you have enough disk space in `/home/` for a (temporary) second copy of your home directory.
|
|
|
|
Make sure to backup your home directory.
|
|
|
|
Make sure to log out of your user account fully.
|
|
|
|
Then log in as root on the console.
|
2020-04-09 15:13:12 +00:00
|
|
|
|
|
|
|
1. Rename your existing home directory to something safe. Let's say your user
|
|
|
|
ID is `foobar`. Then do:
|
|
|
|
|
|
|
|
```
|
|
|
|
mv /home/foobar /home/foobar.saved
|
|
|
|
```
|
|
|
|
|
2024-02-26 12:57:40 +00:00
|
|
|
2. Have a look at your existing user record, as stored in `/etc/passwd` and related files.
|
|
|
|
We want to use the same data for the new record, hence it's good looking at the old data.
|
|
|
|
|
|
|
|
Use commands such as:
|
2020-04-09 15:13:12 +00:00
|
|
|
|
|
|
|
```
|
|
|
|
getent passwd foobar
|
|
|
|
getent shadow foobar
|
|
|
|
```
|
|
|
|
|
2024-02-26 12:57:40 +00:00
|
|
|
This will tell you the `/etc/passwd` and `/etc/shadow` entries for your user.
|
|
|
|
For details about the fields, see the respective man pages
|
2022-06-28 14:05:31 +00:00
|
|
|
[passwd(5)](https://man7.org/linux/man-pages/man5/passwd.5.html) and
|
|
|
|
[shadow(5)](https://man7.org/linux/man-pages/man5/shadow.5.html).
|
2020-04-09 15:13:12 +00:00
|
|
|
|
2024-02-26 12:57:40 +00:00
|
|
|
The fourth field in the `getent passwd foobar` output tells you the GID of your user's main group.
|
|
|
|
Depending on your distribution it's a group private to the user, or a group shared by most local, regular users.
|
|
|
|
Let's say the GID reported is 1000, let's then query its details:
|
2020-04-09 15:13:12 +00:00
|
|
|
|
|
|
|
```
|
|
|
|
getent group 1000
|
|
|
|
```
|
|
|
|
|
2024-02-26 12:57:40 +00:00
|
|
|
This will tell you the name of that group.
|
|
|
|
If the name is the same as your user name your distribution apparently provided you with a private group for your user.
|
|
|
|
If it doesn't match (and is something like `users`) it apparently didn't.
|
|
|
|
Note that `systemd-homed` will always manage a private group for each user under the same name,
|
|
|
|
hence if your distribution is one of the latter kind, then there's a (minor) mismatch in structure when converting.
|
2020-04-09 15:13:12 +00:00
|
|
|
|
2024-02-26 12:57:40 +00:00
|
|
|
Save the information reported by these three commands somewhere, for later reference.
|
2020-04-09 15:13:12 +00:00
|
|
|
|
|
|
|
3. Now edit your `/etc/passwd` file and remove your existing record
|
2024-02-26 12:57:40 +00:00
|
|
|
(i.e. delete a single line, the one of your user's account, leaving all other lines unmodified).
|
|
|
|
Similar for `/etc/shadow`, `/etc/group` (in case you have a private group for your user) and `/etc/gshadow`.
|
|
|
|
Most distributions provide you with a tool for that, that adds safe
|
2020-04-09 15:13:12 +00:00
|
|
|
synchronization for these changes: `vipw`, `vipw -s`, `vigr` and `vigr -s`.
|
|
|
|
|
|
|
|
4. At this point the old user account vanished, while the home directory still
|
2024-02-26 12:57:40 +00:00
|
|
|
exists safely under the `/home/foobar.saved` name.
|
|
|
|
Let's now create a new account with `systemd-homed`, using the same username and UID as before:
|
2020-04-09 15:13:12 +00:00
|
|
|
|
2024-02-26 12:57:40 +00:00
|
|
|
```sh
|
|
|
|
homectl create foobar --uid=$UID --real-name=$GECOS
|
|
|
|
```
|
2020-04-09 15:13:12 +00:00
|
|
|
|
|
|
|
In this command line, replace `$UID` by the UID you previously used,
|
2024-02-26 12:57:40 +00:00
|
|
|
i.e. the third field of the `getent passwd foobar` output above.
|
|
|
|
Similar, replace `$GECOS` by the GECOS field of your old account, i.e the fifth field of the old output.
|
|
|
|
If your distribution traditionally does not assign a private group to regular user groups,
|
|
|
|
then consider adding `--member-of=` with the group name to get a modicum of compatibility with the status quo ante:
|
|
|
|
this way your new user account will still not have the old primary
|
2020-04-09 15:13:12 +00:00
|
|
|
group as new primary group, but will have it as auxiliary group.
|
|
|
|
|
|
|
|
Consider reading through the
|
|
|
|
[homectl(1)](https://www.freedesktop.org/software/systemd/man/homectl.html)
|
2024-02-26 12:57:40 +00:00
|
|
|
manual page at this point, maybe there are a couple of other settings you want to set for your new account.
|
|
|
|
In particular, look at `--storage=` and `--disk-size=`, in order to change how your home directory shall be stored
|
2020-04-09 15:13:12 +00:00
|
|
|
(the default `luks` storage is recommended).
|
|
|
|
|
2024-02-26 12:57:40 +00:00
|
|
|
1. Your new user account exists now, but it has an empty home directory.
|
|
|
|
Let's now migrate your old home directory into it.
|
|
|
|
For that let's mount the new home directory temporarily and copy the data in.
|
2020-04-09 15:13:12 +00:00
|
|
|
|
|
|
|
```
|
docs: tweak rsync flags for moving existing home dir to systemd-homed
The documentation on moving an existing homedir into a systemd-homed managed
one suggests using rsync(1) with a bunch of flags to preserve as much metadata
as possible: permissions, xattrs, timestamps, etc. The previously suggested
flags were:
rsync -aHAXv --remove-source-files …
… which does include mtimes, but not ctimes and atimes, because -a does not
include those:
--archive, -a archive mode is -rlptgoD (no -A,-X,-U,-N,-H)
This change adds the -N and -U flags to preserve even more file timestamps,
turning the command into:
rsync -aHANUXv --remove-source-files …
The new flags are:
--crtimes, -N preserve create times (newness)
--atimes, -U preserve access (use) times
2023-02-01 20:15:22 +00:00
|
|
|
homectl with foobar -- rsync -aHANUXv --remove-source-files /home/foobar.saved/ .
|
2020-04-09 15:13:12 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
This mounts the home directory of the user, and then runs the specified
|
2024-02-26 12:57:40 +00:00
|
|
|
`rsync` command which copies the contents of the old home directory into the new.
|
|
|
|
The new home directory is the working directory of the invoked `rsync` process.
|
|
|
|
We are invoking this command as root, hence the `rsync` runs as root too.
|
|
|
|
When the `rsync` command completes the home directory is automatically unmounted again.
|
|
|
|
Since we used `--remove-source-files` all files copied are removed from the old home directory as the copy progresses.
|
|
|
|
After the command completes the old home directory should be empty.
|
|
|
|
Let's remove it hence:
|
2020-04-09 15:13:12 +00:00
|
|
|
|
|
|
|
```
|
|
|
|
rmdir /home/foobar.saved
|
|
|
|
```
|
|
|
|
|
2024-02-26 12:57:40 +00:00
|
|
|
And that's it, we are done already.
|
|
|
|
You can log out now and should be able to log in under your user account as usual,
|
|
|
|
but now with `systemd-homed` managing your home directory.
|