Traditionally on most Linux distributions, regular (human) users are managed
via entries in
/etc/gshadow. With the advent of
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.
Before continuing, please read up on these basic concepts:
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.
Here’s the step-by-step guide:
Preparations: make sure you run a distribution that has
enabled and properly set up, including the necessary PAM and NSS
configuration updates. Make sure you have enough disk space in
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.
Rename your existing home directory to something safe. Let’s say your user
foobar. Then do:
mv /home/foobar /home/foobar.saved
Have a look at your existing user record, as stored in
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:
getent passwd foobar getent shadow foobar
This will tell you the
/etc/shadow entries for your
user. For details about the fields, see the respective man pages
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:
getent group 1000
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.
Save the information reported by these three commands somewhere, for later reference.
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
other lines unmodified). Similar for
/etc/group (in case
you have a private group for your user) and
distributions provide you with a tool for that, that adds safe
synchronization for these changes:
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
systemd-homed, using the same username and UID as before:
homectl create foobar --uid=$UID --real-name=$GECOS
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,
$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
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
group as new primary group, but will have it as auxiliary group.
Consider reading through the
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
--disk-size=, in order to change how your home directory shall be stored
luks storage is recommended).
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.
homectl with foobar -- rsync -aHAXv --remove-source-files /home/foobar.saved/ .
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
new. The new home directory is the working directory of the invoked
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
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
your home directory.