[bug#77288,v3,2/8] doc: Document migration to the unprivileged daemon.
Commit Message
* doc/guix.texi (Build Environment Setup): Add “Migrating to the
Unprivileged Daemon” section.
(Upgrading Guix): Link to it.
Change-Id: I2bac3f4419d85b7c718c6c4a3908387b4f6ee582
---
doc/guix.texi | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 67 insertions(+), 1 deletion(-)
Comments
Works great now. I can now with v3 merrily switch back and forth the
(privileged? #f) on Guix System, except ownerships of /gnu/store/ files
are funny when I guix system roll-back to the time before guix-ownership
services existed.
Then I try the
chown -R root:root \
/gnu \
/var/guix/{daemon-socket,db,discover} \
/var/guix/{gcroots,offload,substitute,temproots} \
/var/log/guix \
/etc/guix
from this “Migrating to the Unprivileged Daemon” with root:root instead
of guix-daemon:guix-daemon. But it does not work unless I mount -o
remount,rw /gnu/store (a command from the subsequent SELinux section).
While I have not tested this “Migrating to the Unprivileged Daemon”
section on a foreign distro, should not etc/gnu-store.mount require
remounting on foreign distros, too?
Regards,
Florian
Hey Florian,
"pelzflorian (Florian Pelz)" <pelzflorian@pelzflorian.de> writes:
> Works great now. I can now with v3 merrily switch back and forth the
> (privileged? #f) on Guix System,
Good, thanks for testing again!
> except ownerships of /gnu/store/ files are funny when I guix system
> roll-back to the time before guix-ownership services existed.
Uh, right. There’s little we can do here, except perhaps adding a
warning in the doc?
> Then I try the
>
> chown -R root:root \
> /gnu \
> /var/guix/{daemon-socket,db,discover} \
> /var/guix/{gcroots,offload,substitute,temproots} \
> /var/log/guix \
> /etc/guix
>
> from this “Migrating to the Unprivileged Daemon” with root:root instead
> of guix-daemon:guix-daemon. But it does not work unless I mount -o
> remount,rw /gnu/store (a command from the subsequent SELinux section).
>
> While I have not tested this “Migrating to the Unprivileged Daemon”
> section on a foreign distro, should not etc/gnu-store.mount require
> remounting on foreign distros, too?
Users are invited to stop the daemon before doing that, which should
stop ‘gnu-store.mount’ as well. Do you think that needs to be
clarified?
Thanks,
Ludo’.
@@ -1026,13 +1026,75 @@ Build Environment Setup
In this configuration, @file{/gnu/store} is owned by the
@code{guix-daemon} user.
+@anchor{unprivileged-daemon-migration}
+@unnumberedsubsubsec Migrating to the Unprivileged Daemon
+
+@cindex unprivileged daemon, migration
+@cindex rootless daemon, migration
+To switch an existing installation to the unprivileged execution mode, a
+number of steps must be taken: creating a new dedicated
+@code{guix-daemon} user account, changing ownership of the relevant
+files to @code{guix-daemon}, and ensuring that the @command{guix-daemon}
+program runs as @code{guix-daemon}.
+
+@quotation Warning
+Follow the instructions below only after making sure you have a recent
+version of @command{guix-daemon} with support for unprivileged
+execution.
+@end quotation
+
+File ownership can be changed, after stopping the daemon, by running the
+following commands as root (the @command{chown} can take a while if
+there are many files in @file{/gnu/store}):
+
+@example
+groupadd --system guix-daemon
+useradd -g guix-daemon -G guix-daemon,kvm \
+ -d /var/empty -s $(which nologin) \
+ -c "Guix daemon privilege separation user" \
+ --system guix-daemon
+
+chown -R guix-daemon:guix-daemon \
+ /gnu \
+ /var/guix/@{daemon-socket,db,discover@} \
+ /var/guix/@{gcroots,offload,substitute,temproots@} \
+ /var/log/guix \
+ /etc/guix
+@end example
+
+If your system uses the systemd service manager, running the daemon as
+@code{guix-daemon} will be a matter of copying the relevant
+configuration files---make sure to review any changes you might have
+made in your own @file{.service} files before overwriting them:
+
+@example
+cp /var/guix/profiles/per-user/root/current-guix/lib/systemd/system/*.service \
+ /etc/systemd/system
+systemctl daemon-reload
+systemctl start guix-daemon
+@end example
+
+@quotation Warning
+The commands above assume that @command{guix pull} was run for the root
+user. You can check whether this is the case by running this command:
+
+@example
+grep User=guix-daemon \
+ /var/guix/profiles/per-user/root/current-guix/lib/systemd/system/guix-daemon.service
+@end example
+
+If that command does not show the @code{User=guix-daemon} line, then run
+@command{guix pull} as the root user.
+@end quotation
+
@unnumberedsubsubsec The Isolated Build Environment
@cindex chroot
@cindex build environment isolation
@cindex isolated build environment
@cindex hermetic build environment
-In both cases, the daemon starts build processes without privileges in
+In both cases, privileged and unprivileged,
+the daemon starts build processes without privileges in
an @emph{isolated} or @emph{hermetic} build environment---a ``chroot''.
On GNU/Linux, by default, the build environment contains nothing but:
@@ -2035,6 +2097,10 @@ Upgrading Guix
On Guix System, upgrading the daemon is achieved by reconfiguring the
system (@pxref{Invoking guix system, @code{guix system reconfigure}}).
+To migrate an existing installation to the @emph{unprivileged daemon}
+where @command{guix-daemon} does not run as root,
+@pxref{unprivileged-daemon-migration}.
+
@c TODO What else?
@c *********************************************************************