shaba/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2025-01-09 01:18:19 +03:00
Code

docs/CONVERTING_TO_HOMED: format text

Browse Source
This commit is contained in:
hulkoba 2024-02-26 13:57:40 +01:00
parent 0d8926b1c3
commit 26dcc13c2c
No known key found for this signature in database
GPG Key ID: ACB6C4A3A4F2BE2F
1 changed files with 55 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

115
docs/CONVERTING_TO_HOMED.md
View File

@ -8,11 +8,12 @@ SPDX-License-Identifier: LGPL-2.1-or-later
# Converting Existing Users to systemd-homed managed Users # Converting Existing Users to systemd-homed managed Users
Traditionally on most Linux distributions, regular (human) users are managed Traditionally on most Linux distributions, regular (human) users are managed
via entries in `/etc/passwd`, `/etc/shadow`, `/etc/group` and via entries in `/etc/passwd`, `/etc/shadow`, `/etc/group` and `/etc/gshadow`.
`/etc/gshadow`. With the advent of With the advent of
[`systemd-homed`](https://www.freedesktop.org/software/systemd/man/systemd-homed.service.html) [`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 it might be desirable to convert an existing, traditional user account to a
`systemd-homed` managed one. Below is a brief guide how to do that. `systemd-homed` managed one.
Below is a brief guide how to do that.
Before continuing, please read up on these basic concepts: Before continuing, please read up on these basic concepts:
@ -23,20 +24,20 @@ Before continuing, please read up on these basic concepts:
## Caveat ## Caveat
This is a manual process, and possibly a bit fragile. Hence, do this at your This is a manual process, and possibly a bit fragile.
own risk, read up beforehand, and make a backup first. You know what's at Hence, do this at your own risk, read up beforehand, and make a backup first.
stake: your own home directory, i.e. all your personal data. You know what's at stake: your own home directory, i.e. all your personal data.
## Step-By-Step ## Step-By-Step
Here's the step-by-step guide: Here's the step-by-step guide:
0. Preparations: make sure you run a distribution that has `systemd-homed` 0. Preparations: make sure you run a distribution that has `systemd-homed`
enabled and properly set up, including the necessary PAM and NSS enabled and properly set up, including the necessary PAM and NSS configuration updates.
configuration updates. Make sure you have enough disk space in `/home/` for Make sure you have enough disk space in `/home/` for a (temporary) second copy of your home directory.
a (temporary) second copy of your home directory. Make sure to backup your Make sure to backup your home directory.
home directory. Make sure to log out of your user account fully. Then log in Make sure to log out of your user account fully.
as root on the console. Then log in as root on the console.
1. Rename your existing home directory to something safe. Let's say your user 1. Rename your existing home directory to something safe. Let's say your user
ID is `foobar`. Then do: ID is `foobar`. Then do:
@ -45,92 +46,86 @@ Here's the step-by-step guide:
mv /home/foobar /home/foobar.saved mv /home/foobar /home/foobar.saved
``` ```
2. Have a look at your existing user record, as stored in `/etc/passwd` and 2. Have a look at your existing user record, as stored in `/etc/passwd` and related files.
related files. We want to use the same data for the new record, hence it's good We want to use the same data for the new record, hence it's good looking at the old data.
looking at the old data. Use commands such as:
Use commands such as:
``` ```
getent passwd foobar getent passwd foobar
getent shadow foobar getent shadow foobar
``` ```
This will tell you the `/etc/passwd` and `/etc/shadow` entries for your This will tell you the `/etc/passwd` and `/etc/shadow` entries for your user.
user. For details about the fields, see the respective man pages For details about the fields, see the respective man pages
[passwd(5)](https://man7.org/linux/man-pages/man5/passwd.5.html) and [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). [shadow(5)](https://man7.org/linux/man-pages/man5/shadow.5.html).
The fourth field in the `getent passwd foobar` output tells you the GID of The fourth field in the `getent passwd foobar` output tells you the GID of your user's main group.
your user's main group. Depending on your distribution it's a group private Depending on your distribution it's a group private to the user, or a group shared by most local, regular users.
to the user, or a group shared by most local, regular users. Let's say the Let's say the GID reported is 1000, let's then query its details:
GID reported is 1000, let's then query its details:
``` ```
getent group 1000 getent group 1000
``` ```
This will tell you the name of that group. If the name is the same as your This will tell you the name of that group.
user name your distribution apparently provided you with a private group for If the name is the same as your user name your distribution apparently provided you with a private group for your user.
your user. If it doesn't match (and is something like `users`) it apparently If it doesn't match (and is something like `users`) it apparently didn't.
didn't. Note that `systemd-homed` will always manage a private group for Note that `systemd-homed` will always manage a private group for each user under the same name,
each user under the same name, hence if your distribution is one of the hence if your distribution is one of the latter kind, then there's a (minor) mismatch in structure when converting.
latter kind, then there's a (minor) mismatch in structure when converting.
Save the information reported by these three commands somewhere, for later Save the information reported by these three commands somewhere, for later reference.
reference.
3. Now edit your `/etc/passwd` file and remove your existing record 3. Now edit your `/etc/passwd` file and remove your existing record
(i.e. delete a single line, the one of your user's account, leaving all (i.e. delete a single line, the one of your user's account, leaving all other lines unmodified).
other lines unmodified). Similar for `/etc/shadow`, `/etc/group` (in case Similar for `/etc/shadow`, `/etc/group` (in case you have a private group for your user) and `/etc/gshadow`.
you have a private group for your user) and `/etc/gshadow`. Most Most distributions provide you with a tool for that, that adds safe
distributions provide you with a tool for that, that adds safe
synchronization for these changes: `vipw`, `vipw -s`, `vigr` and `vigr -s`. 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 4. At this point the old user account vanished, while the home directory still
exists safely under the `/home/foobar.saved` name. Let's now create a new exists safely under the `/home/foobar.saved` name.
account with `systemd-homed`, using the same username and UID as before: Let's now create a new account with `systemd-homed`, using the same username and UID as before:
``` ```sh
homectl create foobar --uid=$UID --real-name=$GECOS homectl create foobar --uid=$UID --real-name=$GECOS
``` ```
In this command line, replace `$UID` by the UID you previously used, In this command line, replace `$UID` by the UID you previously used,
i.e. the third field of the `getent passwd foobar` output above. Similar, i.e. the third field of the `getent passwd foobar` output above.
replace `$GECOS` by the GECOS field of your old account, i.e the fifth field Similar, replace `$GECOS` by the GECOS field of your old account, i.e the fifth field of the old output.
of the old output. If your distribution traditionally does not assign a If your distribution traditionally does not assign a private group to regular user groups,
private group to regular user groups, then consider adding `--member-of=` then consider adding `--member-of=` with the group name to get a modicum of compatibility with the status quo ante:
with the group name to get a modicum of compatibility with the status quo this way your new user account will still not have the old primary
ante: this way your new user account will still not have the old primary
group as new primary group, but will have it as auxiliary group. group as new primary group, but will have it as auxiliary group.
Consider reading through the Consider reading through the
[homectl(1)](https://www.freedesktop.org/software/systemd/man/homectl.html) [homectl(1)](https://www.freedesktop.org/software/systemd/man/homectl.html)
manual page at this point, maybe there are a couple of other settings you manual page at this point, maybe there are a couple of other settings you want to set for your new account.
want to set for your new account. In particular, look at `--storage=` and In particular, look at `--storage=` and `--disk-size=`, in order to change how your home directory shall be stored
`--disk-size=`, in order to change how your home directory shall be stored
(the default `luks` storage is recommended). (the default `luks` storage is recommended).
5. Your new user account exists now, but it has an empty home directory. Let's 1. Your new user account exists now, but it has an empty home directory.
now migrate your old home directory into it. For that let's mount the new Let's now migrate your old home directory into it.
home directory temporarily and copy the data in. For that let's mount the new home directory temporarily and copy the data in.
``` ```
homectl with foobar -- rsync -aHANUXv --remove-source-files /home/foobar.saved/ . homectl with foobar -- rsync -aHANUXv --remove-source-files /home/foobar.saved/ .
``` ```
This mounts the home directory of the user, and then runs the specified This mounts the home directory of the user, and then runs the specified
`rsync` command which copies the contents of the old home directory into the `rsync` command which copies the contents of the old home directory into the new.
new. The new home directory is the working directory of the invoked `rsync` The new home directory is the working directory of the invoked `rsync` process.
process. We are invoking this command as root, hence the `rsync` runs as We are invoking this command as root, hence the `rsync` runs as root too.
root too. When the `rsync` command completes the home directory is When the `rsync` command completes the home directory is automatically unmounted again.
automatically unmounted again. Since we used `--remove-source-files` all files Since we used `--remove-source-files` all files copied are removed from the old home directory as the copy progresses.
copied are removed from the old home directory as the copy progresses. After After the command completes the old home directory should be empty.
the command completes the old home directory should be empty. Let's remove Let's remove it hence:
it hence:
``` ```
rmdir /home/foobar.saved rmdir /home/foobar.saved
``` ```
And that's it, we are done already. You can log out now and should be able to And that's it, we are done already.
log in under your user account as usual, but now with `systemd-homed` managing You can log out now and should be able to log in under your user account as usual,
your home directory. but now with `systemd-homed` managing your home directory.