[bug#61246,v3,2/3] doc: Explain how to use local guix repositories.

* doc/guix.texi (Using a Custom Guix Channel): Add note and example
on how to exempt a local guix repository from git ownership checks.
---
 doc/guix.texi | 21 ++++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)

Hello,

André Batista <nandre@riseup.net> writes:

> * doc/guix.texi (Using a Custom Guix Channel): Add note and example
> on how to exempt a local guix repository from git ownership checks.
> ---
>  doc/guix.texi | 21 ++++++++++++++++++++-
>  1 file changed, 20 insertions(+), 1 deletion(-)
>
> diff --git a/doc/guix.texi b/doc/guix.texi
> index 44e2165a82..ae975287c7 100644
> --- a/doc/guix.texi
> +++ b/doc/guix.texi
> @@ -81,7 +81,7 @@ Copyright @copyright{} 2020, 2021 Brice Waegeneire@*
>  Copyright @copyright{} 2020 R Veera Kumar@*
>  Copyright @copyright{} 2020, 2021, 2022 Pierre Langlois@*
>  Copyright @copyright{} 2020 pinoaffe@*
> -Copyright @copyright{} 2020 André Batista@*
> +Copyright @copyright{} 2020, 2023 André Batista@*
>  Copyright @copyright{} 2020, 2021 Alexandru-Sergiu Marton@*
>  Copyright @copyright{} 2020 raingloom@*
>  Copyright @copyright{} 2020 Daniel Brooks@*
> @@ -5413,6 +5413,25 @@ From there on, @command{guix pull} will fetch code from the @code{super-hacks}
>  branch of the repository at @code{example.org}.  The authentication concern is
>  addressed below (@pxref{Channel Authentication}).
>  
> +Note that you can specify a local directory on the @code{url} field above if
> +the channel that you intend to use resides on a local file system.  However,
> +in this case @command{guix} checks said directory for ownership before any
> +further processing.  This means that if the user is not the directory owner,
> +but wants to use it as their default, they will then need to set it as a safe
> +directory in their global git configuration file.  Otherwise, @command{guix}
> +will refuse to even read it.  Supposing your system-wide local directory is at
> +@code{/src/guix.git}, you would then create a git configuration file at
> +@code{~/.gitconfig} with the following contents:
> +
> +@example
> +[safe]
> +        directory = /src/guix.git
> +@end example

Perhaps you meant to use @command{git} in the above instead of
@command{guix}, since it's specific to Git (and the configure snippet is
for Git) ?

Hi André,

André Batista <nandre@riseup.net> writes:

> * doc/guix.texi (Using a Custom Guix Channel): Add note and example
> on how to exempt a local guix repository from git ownership checks.
> ---
>  doc/guix.texi | 21 ++++++++++++++++++++-
>  1 file changed, 20 insertions(+), 1 deletion(-)

I've pushed the first two patches, leaving this one until you get back
to me about my previous comment.

Hi,

sex 17 fev 2023 às 14:58:12 (1676656692), maxim.cournoyer@gmail.com enviou:
> Hello,
> 
> André Batista <nandre@riseup.net> writes:
> > +Note that you can specify a local directory on the @code{url} field above if
> > +the channel that you intend to use resides on a local file system.  However,
> > +in this case @command{guix} checks said directory for ownership before any
> > +further processing.  This means that if the user is not the directory owner,
> > +but wants to use it as their default, they will then need to set it as a safe
> > +directory in their global git configuration file.  Otherwise, @command{guix}
> > +will refuse to even read it.  Supposing your system-wide local directory is at
> > +@code{/src/guix.git}, you would then create a git configuration file at
> > +@code{~/.gitconfig} with the following contents:
> > +
> > +@example
> > +[safe]
> > +        directory = /src/guix.git
> > +@end example
> 
> Perhaps you meant to use @command{git} in the above instead of
> @command{guix}, since it's specific to Git (and the configure snippet is
> for Git) ?

Not really. It's guix itself and its subcommands which will fail in
this scenario, not git, even though it's because guix is using git
configuration through libgit2. To me it would be misleading to use
@command{git} there. I could come up with a more detailed
description, however, I don't think this would be the place to be
diving on a detailed discussion of guix internals. I'm up to
suggestions though if you think this patch would make people wonder
if it is a typo.

WDYT?

sex 17 fev 2023 às 15:45:22 (1676659522), maxim.cournoyer@gmail.com enviou:
> Hi André,
> (...)
> I've pushed the first two patches, leaving this one until you get back
> to me about my previous comment.

I was building the dependents and just found out that python-pygit2
requires libgit2-1.4.

Hi André,

André Batista <nandre@riseup.net> writes:

> Hi,
>
> sex 17 fev 2023 às 14:58:12 (1676656692), maxim.cournoyer@gmail.com enviou:
>> Hello,
>>
>> André Batista <nandre@riseup.net> writes:
>> > +Note that you can specify a local directory on the @code{url} field above if
>> > +the channel that you intend to use resides on a local file system.  However,
>> > +in this case @command{guix} checks said directory for ownership before any
>> > +further processing.  This means that if the user is not the directory owner,
>> > +but wants to use it as their default, they will then need to set it as a safe
>> > +directory in their global git configuration file.  Otherwise, @command{guix}
>> > +will refuse to even read it.  Supposing your system-wide local directory is at
>> > +@code{/src/guix.git}, you would then create a git configuration file at
>> > +@code{~/.gitconfig} with the following contents:
>> > +
>> > +@example
>> > +[safe]
>> > +        directory = /src/guix.git
>> > +@end example
>>
>> Perhaps you meant to use @command{git} in the above instead of
>> @command{guix}, since it's specific to Git (and the configure snippet is
>> for Git) ?
>
> Not really. It's guix itself and its subcommands which will fail in
> this scenario, not git, even though it's because guix is using git
> configuration through libgit2. To me it would be misleading to use
> @command{git} there. I could come up with a more detailed
> description, however, I don't think this would be the place to be
> diving on a detailed discussion of guix internals. I'm up to
> suggestions though if you think this patch would make people wonder
> if it is a typo.

I understand.  How about a very subtle nudge at the fact that Guix uses
git (via libgit2) under the hood?  Something like the following, where
I've used a footnote (untested):

--8<---------------cut here---------------start------------->8---
Note that you can specify a local directory on the @code{url} field
above if the channel that you intend to use resides on a local file
system.  However, in this case @command{guix}@footnote{More accurately,
@command{git}, which Guix utilizes via the @code{libgit2} library.}
checks said directory for ownership before any further processing.  This
means that if the user is not the directory owner, but wants to use it
as their default, they will then need to set it as a safe directory in
their global git configuration file.  Otherwise, @command{guix} will
refuse to even read it.  Supposing your system-wide local directory is
at @code{/src/guix.git}, you would then create a git configuration file
at @code{~/.gitconfig} with the following contents:
--8<---------------cut here---------------end--------------->8---

Hello,

André Batista <nandre@riseup.net> writes:

> sex 17 fev 2023 às 15:45:22 (1676659522), maxim.cournoyer@gmail.com enviou:
>> Hi André,
>> (...)
>> I've pushed the first two patches, leaving this one until you get back
>> to me about my previous comment.
>
> I was building the dependents and just found out that python-pygit2
> requires libgit2-1.4.

I've opted to update it to 1.11.1 instead; commit "gnu: python-pygit2:
Update to 1.11.1." will land to master shortly.

Hi Maxim,

sáb 18 fev 2023 às 12:35:32 (1676734532), maxim.cournoyer@gmail.com enviou:
> 
> --8<---------------cut here---------------start------------->8---
> Note that you can specify a local directory on the @code{url} field
> above if the channel that you intend to use resides on a local file
> system.  However, in this case @command{guix}@footnote{More accurately,
> @command{git}, which Guix utilizes via the @code{libgit2} library.}
> checks said directory for ownership before any further processing.  This
> means that if the user is not the directory owner, but wants to use it
> as their default, they will then need to set it as a safe directory in
> their global git configuration file.  Otherwise, @command{guix} will
> refuse to even read it.  Supposing your system-wide local directory is
> at @code{/src/guix.git}, you would then create a git configuration file
> at @code{~/.gitconfig} with the following contents:
> --8<---------------cut here---------------end--------------->8---

I don't think it's more accurate to say it's @command{git}.

Looking at the manual, on section 7.4 "Channel Authentication", it says:

---

The @command{guix pull} and @command{guix time-machine} commands
@dfn{authenticate} the code retrieved from channels: they make sure each
commit that is fetched is signed by an authorized developer.  The goal
is to protect from unauthorized modifications to the channel that would
lead users to run malicious code.

As a user, you must provide a @dfn{channel introduction} in your
channels file so that Guix knows how to authenticate its first commit.
A channel specification, including its introduction, looks something
along these lines:

---

Then it goes on to describe how to insert a openpgp fingerprint, a
commit hash, but it does not say it's @command{git}, nor
@command{gnupg}, and it has no word to say about gcrypt library,
libgit2 or guile and IMO it's good as is.

Anyway, would it satisfy your concerns if I were to send another patch
version with the following contents?

--8<---------------cut here---------------start------------->8---
Note that you can specify a local directory on the @code{url} field
above if the channel that you intend to use resides on a local file
system.  However, in this case Guix checks said directory for ownership
before any further processing and it will, by default, abort execution
if the configured directory is neither owned by the calling user nor
has it been configured as a safe directory in the user's global
@command{git} configuration file at @code{~/.gitconfig}, which Guix
honors@footnote{If you know your @command{git}, this security measure
mimicks what it does.}.  Supposing your system-wide local channel is
at @code{/src/guix.git}, you would then declare it a safe directory by
adding the following configuration directives to your @command{git}
global configuration file:
--8<---------------cut here---------------end--------------->8---

Cheers,

Hi Maxim,

sáb 18 fev 2023 às 12:35:32 (1676734532), maxim.cournoyer@gmail.com enviou:
> (...)
> >> Perhaps you meant to use @command{git} in the above instead of
> >> @command{guix}, since it's specific to Git (and the configure snippet is
> >> for Git) ?
> >
> > Not really. It's guix itself and its subcommands which will fail in
> > this scenario, not git, even though it's because guix is using git
> > configuration through libgit2. To me it would be misleading to use
> > @command{git} there. I could come up with a more detailed
> > description, however, I don't think this would be the place to be
> > diving on a detailed discussion of guix internals. I'm up to
> > suggestions though if you think this patch would make people wonder
> > if it is a typo.

Just to be sure we are on the same page on this: have you followed on
#55399? AKA Guix has a choice to make here since we could just as
well decide to diverge from git and disable owner validation checks
entirely in Guix. On the one side, users wouldn't need to bother with
git configuration and the manual could do without this patch. On the
other, would this divergence have any security implications? As far
as I can see it doesn't, but I may not be seeing far enough and we
would be hard coding and burying this decision in Guix.

Also we wouldn't be exempting one chosen directory of these checks,
but disabling it altogether in Guix.

WDYT?

Hi André,

André Batista <nandre@riseup.net> writes:

> Hi Maxim,
>
> sáb 18 fev 2023 às 12:35:32 (1676734532), maxim.cournoyer@gmail.com enviou:
>>
>> --8<---------------cut here---------------start------------->8---
>> Note that you can specify a local directory on the @code{url} field
>> above if the channel that you intend to use resides on a local file
>> system.  However, in this case @command{guix}@footnote{More accurately,
>> @command{git}, which Guix utilizes via the @code{libgit2} library.}
>> checks said directory for ownership before any further processing.  This
>> means that if the user is not the directory owner, but wants to use it
>> as their default, they will then need to set it as a safe directory in
>> their global git configuration file.  Otherwise, @command{guix} will
>> refuse to even read it.  Supposing your system-wide local directory is
>> at @code{/src/guix.git}, you would then create a git configuration file
>> at @code{~/.gitconfig} with the following contents:
>> --8<---------------cut here---------------end--------------->8---
>
> I don't think it's more accurate to say it's @command{git}.

Then we could mention just @code{libgit2} in the footnote.  It is an
implementation detail, but one perhaps worth mentioning in this context
(otherwise a user could wonder "what does ~/.gitconfig have to do with
Guix?").

My point was that Guix alone couldn't care less about ~/.gitconfig, so
it seems confusing to me to mention it in relation to Guix.  It's really
a libgit2/git-specific thing, so should be mentioned somewhere, in my
opinion.

But now that you've pointed at our current style elsewhere, I guess your
original version is fine.  The good part about it is that by avoiding to
mention implementation details such as libgit2, it makes it less likely
that text will go stale as Guix evolves.

I've now applied the original, untouched.

Hi,

André Batista <nandre@riseup.net> writes:

> Hi Maxim,
>
> sáb 18 fev 2023 às 12:35:32 (1676734532), maxim.cournoyer@gmail.com enviou:
>> (...)
>> >> Perhaps you meant to use @command{git} in the above instead of
>> >> @command{guix}, since it's specific to Git (and the configure snippet is
>> >> for Git) ?
>> >
>> > Not really. It's guix itself and its subcommands which will fail in
>> > this scenario, not git, even though it's because guix is using git
>> > configuration through libgit2. To me it would be misleading to use
>> > @command{git} there. I could come up with a more detailed
>> > description, however, I don't think this would be the place to be
>> > diving on a detailed discussion of guix internals. I'm up to
>> > suggestions though if you think this patch would make people wonder
>> > if it is a typo.
>
> Just to be sure we are on the same page on this: have you followed on
> #55399? AKA Guix has a choice to make here since we could just as
> well decide to diverge from git and disable owner validation checks
> entirely in Guix. On the one side, users wouldn't need to bother with
> git configuration and the manual could do without this patch. On the
> other, would this divergence have any security implications? As far
> as I can see it doesn't, but I may not be seeing far enough and we
> would be hard coding and burying this decision in Guix.
>
> Also we wouldn't be exempting one chosen directory of these checks,
> but disabling it altogether in Guix.

I'm not sure of the security implications this new git switch tries
addressing, so I'd have to read about it more before I can commit on
what's right to do.  In the meantime, we have a recent libgit2 and users
have instructions about dealing with its new security "features", so it
still seems a plus to me.