[bug#77288,v2,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
Hi Ludovic,
Ludovic Courtès <ludo@gnu.org> writes:
> * doc/guix.texi (Build Environment Setup): Add “Migrating to the
> Unprivileged Daemon” section.
> (Upgrading Guix): Link to it.
[...]
It looks good to me, but I was wondering if this wouldn't fit better in
a etc/news.scm entry, or blog post, since it's a section which will
eventually be obsolete, as more and more systems are installed out of the
box with the unprivileged daemon.
A couple of related questions: are Guix Systems already automatically
handled to run the daemon unprivileged now? Is this just for foreign
systems? Is the guix-install.sh script able to setup the daemon for
unprivileged execution now?
Hi,
Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:
> Ludovic Courtès <ludo@gnu.org> writes:
>
>> * doc/guix.texi (Build Environment Setup): Add “Migrating to the
>> Unprivileged Daemon” section.
>> (Upgrading Guix): Link to it.
>
> [...]
>
> It looks good to me, but I was wondering if this wouldn't fit better in
> a etc/news.scm entry, or blog post, since it's a section which will
> eventually be obsolete, as more and more systems are installed out of the
> box with the unprivileged daemon.
I think it’s better this way because it will probably be a long process,
and because it’s good to be able to point people to a page in the
manual.
> A couple of related questions: are Guix Systems already automatically
> handled to run the daemon unprivileged now? Is this just for foreign
> systems? Is the guix-install.sh script able to setup the daemon for
> unprivileged execution now?
This patch series is initially about migration on Guix System only, but
following a suggestion by Florian and also requests from others
wondering how to migrate on foreign distros, I thought I’d also include
this here.
Thanks,
Ludo’.
Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:
> It looks good to me, but I was wondering if this wouldn't fit better in
> a etc/news.scm entry, or blog post, since it's a section which will
> eventually be obsolete, as more and more systems are installed out of the
> box with the unprivileged daemon.
Good that you review.
I believe the privileged daemon will remain as a choice, thus the
section remains relevant and the manual is the right place?
Regards,
Florian
Hi Florian,
"pelzflorian (Florian Pelz)" <pelzflorian@pelzflorian.de> writes:
> Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:
>> It looks good to me, but I was wondering if this wouldn't fit better in
>> a etc/news.scm entry, or blog post, since it's a section which will
>> eventually be obsolete, as more and more systems are installed out of the
>> box with the unprivileged daemon.
>
> Good that you review.
>
> I believe the privileged daemon will remain as a choice, thus the
> section remains relevant and the manual is the right place?
Documented as a choice in the manual yes, but I was referring to the
fact that we'll have a full blown 'migrating' section, that will make
less sense in 5 years time when most will already using the privileged
daemon without even knowing it (assuming it becomes the default as
planned).
Hi Ludovic,
Ludovic Courtès <ludo@gnu.org> writes:
> Hi,
>
> Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:
>
>> Ludovic Courtès <ludo@gnu.org> writes:
>>
>>> * doc/guix.texi (Build Environment Setup): Add “Migrating to the
>>> Unprivileged Daemon” section.
>>> (Upgrading Guix): Link to it.
>>
>> [...]
>>
>> It looks good to me, but I was wondering if this wouldn't fit better in
>> a etc/news.scm entry, or blog post, since it's a section which will
>> eventually be obsolete, as more and more systems are installed out of the
>> box with the unprivileged daemon.
>
> I think it’s better this way because it will probably be a long process,
> and because it’s good to be able to point people to a page in the
> manual.
OK. We can always remove it if/when it becomes outdated/irrelevant.
>> A couple of related questions: are Guix Systems already automatically
>> handled to run the daemon unprivileged now? Is this just for foreign
>> systems? Is the guix-install.sh script able to setup the daemon for
>> unprivileged execution now?
>
> This patch series is initially about migration on Guix System only, but
> following a suggestion by Florian and also requests from others
> wondering how to migrate on foreign distros, I thought I’d also include
> this here.
OK, thanks for explaining.
Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:
> Documented as a choice in the manual yes, but I was referring to the
> fact that we'll have a full blown 'migrating' section, that will make
> less sense in 5 years time when most will already using the privileged
> daemon without even knowing it (assuming it becomes the default as
> planned).
We can never fully remove the root-privileged option on less-capable
init systems, or when someone decides to put Guix in complicated chroot,
WSL, Docker environments or perhaps semi-virtualized other operating
systems?
Let’s see, maybe there’s no longer a need to migrate then. But I would
expect the Setting up the Daemon instructions will remain.
Regards,
Florian
@@ -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 *********************************************************************