GNU bug report logs - #74510
[PATCH] doc: Document the (possible) need for network-online for NFS.

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 74510 in the body.
You can then email your comments to 74510 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Tomas Volf <~@wolfsden.cz>
To: guix-patches <at> gnu.org
Cc: Tomas Volf <~@wolfsden.cz>
Subject: [PATCH] doc: Document the (possible) need for network-online for NFS.
Date: Sun, 24 Nov 2024 18:43:52 +0100

Depending on networking is not enough in some setups, so a language clarifying
that and an example of network-online service.

* doc/guix.texi (File Systems): Document the possible need for network-online.

Change-Id: I8abe07cc9d6dc61f28eeea7ffa785eb8c9e8fd09
---
 doc/guix.texi | 28 +++++++++++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 26488b41c8..861e78e6d2 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -18018,7 +18018,33 @@ File Systems
 met before mounting the file system.
 
 As an example, an NFS file system would typically have a requirement for
-@code{networking}.
+@code{networking}.  However be aware that depending on @code{networking}
+might not be sufficient in some setups and a variant of custom
+@code{network-online} service might be necessary.  Example:
+
+@lisp
+(simple-service 'network-online shepherd-root-service-type
+  (list
+   (shepherd-service
+    (requirement '(networking))
+    (provision '(network-online))
+    (documentation "Wait for the network to come up.")
+    (start #~(lambda _
+               (let* ((cmd
+                       "set -eux
+c=0
+while ! /run/setuid-programs/ping -qc1 -W1 example.org; do
+	sleep 1
+	[ \"$((c += 1))\" -lt 30 ] || exit 1  # Limit the wait time
+done
+")
+                    (status (system cmd)))
+               (= 0 (status:exit-val status)))))
+   ;; Ordering for one-shot? services does not currently work.
+   ;; https://issues.guix.gnu.org/74284
+   ;; (one-shot? #t)
+   )))
+@end lisp
 
 Typically, file systems are mounted before most other Shepherd services
 are started.  However, file systems with a non-empty
-- 
2.46.0

Message #8 received at 74510 <at> debbugs.gnu.org (full text, mbox):

From: Maxim Cournoyer <maxim.cournoyer <at> gmail.com>
To: Tomas Volf <~@wolfsden.cz>
Cc: Ludovic Courtès <ludo <at> gnu.org>, 74510 <at> debbugs.gnu.org
Subject: Re: [bug#74510] [PATCH] doc: Document the (possible) need for
 network-online for NFS.
Date: Mon, 25 Nov 2024 10:08:26 +0900

Hi Tomas,

Tomas Volf <~@wolfsden.cz> writes:

> Depending on networking is not enough in some setups, so a language clarifying
> that and an example of network-online service.
>
> * doc/guix.texi (File Systems): Document the possible need for network-online.
>
> Change-Id: I8abe07cc9d6dc61f28eeea7ffa785eb8c9e8fd09
> ---
>  doc/guix.texi | 28 +++++++++++++++++++++++++++-
>  1 file changed, 27 insertions(+), 1 deletion(-)
>
> diff --git a/doc/guix.texi b/doc/guix.texi
> index 26488b41c8..861e78e6d2 100644
> --- a/doc/guix.texi
> +++ b/doc/guix.texi
> @@ -18018,7 +18018,33 @@ File Systems
>  met before mounting the file system.
>  
>  As an example, an NFS file system would typically have a requirement for
> -@code{networking}.
> +@code{networking}.  However be aware that depending on @code{networking}
> +might not be sufficient in some setups and a variant of custom
> +@code{network-online} service might be necessary.

Could we be more precise and detail a simple case or example of when
requiring 'network-online is needed over just 'network for NFS?

> Example:
> +
> +@lisp
> +(simple-service 'network-online shepherd-root-service-type
> +  (list
> +   (shepherd-service
> +    (requirement '(networking))
> +    (provision '(network-online))
> +    (documentation "Wait for the network to come up.")
> +    (start #~(lambda _
> +               (let* ((cmd
> +                       "set -eux
> +c=0
> +while ! /run/setuid-programs/ping -qc1 -W1 example.org; do
> +	sleep 1
> +	[ \"$((c += 1))\" -lt 30 ] || exit 1  # Limit the wait time
> +done
> +")
> +                    (status (system cmd)))
> +               (= 0 (status:exit-val status)))))

I'm pretty sure we have connectivity tests already in the Guix test
suite that must make use of Guile; that would be nicer, I think; for
example, the (guix tests) module has:

--8<---------------cut here---------------start------------->8---
(define (network-reachable?)
  "Return true if we can reach the Internet."
  (false-if-exception (getaddrinfo "www.gnu.org" "80" AI_NUMERICSERV)))
--8<---------------cut here---------------end--------------->8---

> +   ;; Ordering for one-shot? services does not currently work.
> +   ;; https://issues.guix.gnu.org/74284
> +   ;; (one-shot? #t)
> +   )))
> +@end lisp

Otherwise, it looks like a useful addition.

-- 
Thanks,
Maxim

Message #11 received at 74510 <at> debbugs.gnu.org (full text, mbox):

From: Tomas Volf <~@wolfsden.cz>
To: Maxim Cournoyer <maxim.cournoyer <at> gmail.com>
Cc: Ludovic Courtès <ludo <at> gnu.org>, 74510 <at> debbugs.gnu.org
Subject: Re: [bug#74510] [PATCH] doc: Document the (possible) need for
 network-online for NFS.
Date: Mon, 25 Nov 2024 12:36:06 +0100

[Message part 1 (text/plain, inline)]

Hello Maxim,

thank you for the review. :)  Responses below.

Maxim Cournoyer <maxim.cournoyer <at> gmail.com> writes:

> Hi Tomas,
>
> Tomas Volf <~@wolfsden.cz> writes:
>
>> Depending on networking is not enough in some setups, so a language clarifying
>> that and an example of network-online service.
>>
>> * doc/guix.texi (File Systems): Document the possible need for network-online.
>>
>> Change-Id: I8abe07cc9d6dc61f28eeea7ffa785eb8c9e8fd09
>> ---
>>  doc/guix.texi | 28 +++++++++++++++++++++++++++-
>>  1 file changed, 27 insertions(+), 1 deletion(-)
>>
>> diff --git a/doc/guix.texi b/doc/guix.texi
>> index 26488b41c8..861e78e6d2 100644
>> --- a/doc/guix.texi
>> +++ b/doc/guix.texi
>> @@ -18018,7 +18018,33 @@ File Systems
>>  met before mounting the file system.
>>
>>  As an example, an NFS file system would typically have a requirement for
>> -@code{networking}.
>> +@code{networking}.  However be aware that depending on @code{networking}
>> +might not be sufficient in some setups and a variant of custom
>> +@code{network-online} service might be necessary.
>
> Could we be more precise and detail a simple case or example of when
> requiring 'network-online is needed over just 'network for NFS?

It would be the case for any setup where 'networking being marked as
started does not mean the network is fully configured.  I personally
encountered the issue with dhcp-client-service-type.

I will send a v2 that will go into more details than "in some setups".

>
>> Example:
>> +
>> +@lisp
>> +(simple-service 'network-online shepherd-root-service-type
>> +  (list
>> +   (shepherd-service
>> +    (requirement '(networking))
>> +    (provision '(network-online))
>> +    (documentation "Wait for the network to come up.")
>> +    (start #~(lambda _
>> +               (let* ((cmd
>> +                       "set -eux
>> +c=0
>> +while ! /run/setuid-programs/ping -qc1 -W1 example.org; do
>> +	sleep 1
>> +	[ \"$((c += 1))\" -lt 30 ] || exit 1  # Limit the wait time
>> +done
>> +")
>> +                    (status (system cmd)))
>> +               (= 0 (status:exit-val status)))))
>
> I'm pretty sure we have connectivity tests already in the Guix test
> suite that must make use of Guile; that would be nicer, I think; for
> example, the (guix tests) module has:
>
> (define (network-reachable?)
>   "Return true if we can reach the Internet."
>   (false-if-exception (getaddrinfo "www.gnu.org" "80" AI_NUMERICSERV)))
>

This procedure however (despite the name) does not test whether network
is reachable, it tests whether single specific host name is resolvable.
That is not an equivalent of the example 'network-online service.

1. The procedure succeeds on completely offline machine, assuming there
   is a record for the host in /etc/hosts.  This is not an hypothetical
   problem, in my configuration the actual host name I ping (instead of
   example.org above) *is* in /etc/hosts.

2. Even if the DNS server works, that does not mean that the route to
   the host being checked is configured (yet).  That could happen when
   the route is (for example) created by VPN, so it needs some extra
   time to come up.

I do not see a way to do a "ping" using Guile's standard library, and
while I *could* implement it using raw sockets (the service is running
as a root after all), that seems like an overkill for just an example
snippet of code.

I mean, I am not happy about shelling to the /run/setuid-programs/ping.
But I did not figure out a Guile-only way to test what I want to test
(specific host is reachable) that would fit in similar amount of code.

What I could do is to replace the example with something like
"Implementing the 'network-online service is left as an exercise to the
reader.".  Would that work for you?

>> +   ;; Ordering for one-shot? services does not currently work.
>> +   ;; https://issues.guix.gnu.org/74284
>> +   ;; (one-shot? #t)
>> +   )))
>> +@end lisp
>
> Otherwise, it looks like a useful addition.

Will send a v2 once we clarify what to do about the ping.

Thanks,
Tomas

-- 
There are only two hard things in Computer Science:
cache invalidation, naming things and off-by-one errors.

[signature.asc (application/pgp-signature, inline)]

Message #14 received at 74510 <at> debbugs.gnu.org (full text, mbox):

From: Maxim Cournoyer <maxim.cournoyer <at> gmail.com>
To: Tomas Volf <~@wolfsden.cz>
Cc: Ludovic Courtès <ludo <at> gnu.org>, 74510 <at> debbugs.gnu.org
Subject: Re: bug#74510: [PATCH] doc: Document the (possible) need for
 network-online for NFS.
Date: Sun, 02 Mar 2025 16:59:34 +0900

Hi Tomas,

Tomas Volf <~@wolfsden.cz> writes:


[...]

>> Could we be more precise and detail a simple case or example of when
>> requiring 'network-online is needed over just 'network for NFS?
>
> It would be the case for any setup where 'networking being marked as
> started does not mean the network is fully configured.  I personally
> encountered the issue with dhcp-client-service-type.
>
> I will send a v2 that will go into more details than "in some setups".

OK, thank you.

>>
>>> Example:
>>> +
>>> +@lisp
>>> +(simple-service 'network-online shepherd-root-service-type
>>> +  (list
>>> +   (shepherd-service
>>> +    (requirement '(networking))
>>> +    (provision '(network-online))
>>> +    (documentation "Wait for the network to come up.")
>>> +    (start #~(lambda _
>>> +               (let* ((cmd
>>> +                       "set -eux
>>> +c=0
>>> +while ! /run/setuid-programs/ping -qc1 -W1 example.org; do
>>> +	sleep 1
>>> +	[ \"$((c += 1))\" -lt 30 ] || exit 1  # Limit the wait time
>>> +done
>>> +")
>>> +                    (status (system cmd)))
>>> +               (= 0 (status:exit-val status)))))
>>
>> I'm pretty sure we have connectivity tests already in the Guix test
>> suite that must make use of Guile; that would be nicer, I think; for
>> example, the (guix tests) module has:
>>
>> (define (network-reachable?)
>>   "Return true if we can reach the Internet."
>>   (false-if-exception (getaddrinfo "www.gnu.org" "80" AI_NUMERICSERV)))
>>
>
> This procedure however (despite the name) does not test whether network
> is reachable, it tests whether single specific host name is resolvable.
> That is not an equivalent of the example 'network-online service.
>
> 1. The procedure succeeds on completely offline machine, assuming there
>    is a record for the host in /etc/hosts.  This is not an hypothetical
>    problem, in my configuration the actual host name I ping (instead of
>    example.org above) *is* in /etc/hosts.

To be clear, I wasn't suggesting to change the host name checked;
example.org seems a fine target as it appears intended for such use case
(and maintained by the IANA).

> 2. Even if the DNS server works, that does not mean that the route to
>    the host being checked is configured (yet).  That could happen when
>    the route is (for example) created by VPN, so it needs some extra
>    time to come up.

Good point.

> I do not see a way to do a "ping" using Guile's standard library, and
> while I *could* implement it using raw sockets (the service is running
> as a root after all), that seems like an overkill for just an example
> snippet of code.
>
> I mean, I am not happy about shelling to the /run/setuid-programs/ping.
> But I did not figure out a Guile-only way to test what I want to test
> (specific host is reachable) that would fit in similar amount of code.
>
> What I could do is to replace the example with something like
> "Implementing the 'network-online service is left as an exercise to the
> reader.".  Would that work for you?

I think your ready to use example is fine as is; thanks for the
explanations.

-- 
Thanks,
Maxim

Message #17 received at 74510 <at> debbugs.gnu.org (full text, mbox):

From: Tomas Volf <~@wolfsden.cz>
To: 74510 <at> debbugs.gnu.org
Cc: Tomas Volf <~@wolfsden.cz>
Subject: [PATCH v2] doc: Document the (possible) need for network-online for
 NFS.
Date: Sun,  2 Mar 2025 15:29:09 +0100

Depending on networking is not enough in some setups, so a language clarifying
that and an example of network-online service.

* doc/guix.texi (File Systems): Document the possible need for network-online.

Change-Id: I8abe07cc9d6dc61f28eeea7ffa785eb8c9e8fd09
---
 doc/guix.texi | 27 ++++++++++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index a036c85c31..daebf046d7 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -18153,7 +18153,32 @@ File Systems
 met before mounting the file system.
 
 As an example, an NFS file system would typically have a requirement for
-@code{networking}.
+@code{networking}.  However be aware that depending on @code{networking}
+might not be sufficient in setups where @code{networking} being marked
+as started does not imply the network is configured and working
+(e.g. when using @code{dhcp-client-service-type}).  In those cases, a
+custom @code{network-online} service might be necessary.  Example:
+
+@lisp
+(simple-service 'network-online shepherd-root-service-type
+  (list
+   (shepherd-service
+    (requirement '(networking))
+    (provision '(network-online))
+    (documentation "Wait for the network to come up.")
+    (start #~(lambda _
+               (let* ((cmd
+                       "set -eux
+c=0
+while ! /run/setuid-programs/ping -qc1 -W1 example.org; do
+	sleep 1
+	[ \"$((c += 1))\" -lt 30 ] || exit 1  # Limit the wait time
+done
+")
+                    (status (system cmd)))
+               (= 0 (status:exit-val status)))))
+    (one-shot? #t))))
+@end lisp
 
 Typically, file systems are mounted before most other Shepherd services
 are started.  However, file systems with a non-empty
-- 
2.48.1

Message #20 received at 74510 <at> debbugs.gnu.org (full text, mbox):

From: Tomas Volf <~@wolfsden.cz>
To: Maxim Cournoyer <maxim.cournoyer <at> gmail.com>
Cc: Ludovic Courtès <ludo <at> gnu.org>, 74510 <at> debbugs.gnu.org
Subject: Re: bug#74510: [PATCH] doc: Document the (possible) need for
 network-online for NFS.
Date: Sun, 02 Mar 2025 15:29:36 +0100

[Message part 1 (text/plain, inline)]

Maxim Cournoyer <maxim.cournoyer <at> gmail.com> writes:

> Hi Tomas,
>
> Tomas Volf <~@wolfsden.cz> writes:
>
>
> [...]
>
>>> Could we be more precise and detail a simple case or example of when
>>> requiring 'network-online is needed over just 'network for NFS?
>>
>> It would be the case for any setup where 'networking being marked as
>> started does not mean the network is fully configured.  I personally
>> encountered the issue with dhcp-client-service-type.
>>
>> I will send a v2 that will go into more details than "in some setups".
>
> OK, thank you.

v2 sent.

>
>>>
>>>> Example:
>>>> +
>>>> +@lisp
>>>> +(simple-service 'network-online shepherd-root-service-type
>>>> +  (list
>>>> +   (shepherd-service
>>>> +    (requirement '(networking))
>>>> +    (provision '(network-online))
>>>> +    (documentation "Wait for the network to come up.")
>>>> +    (start #~(lambda _
>>>> +               (let* ((cmd
>>>> +                       "set -eux
>>>> +c=0
>>>> +while ! /run/setuid-programs/ping -qc1 -W1 example.org; do
>>>> +	sleep 1
>>>> +	[ \"$((c += 1))\" -lt 30 ] || exit 1  # Limit the wait time
>>>> +done
>>>> +")
>>>> +                    (status (system cmd)))
>>>> +               (= 0 (status:exit-val status)))))
>>>
>>> I'm pretty sure we have connectivity tests already in the Guix test
>>> suite that must make use of Guile; that would be nicer, I think; for
>>> example, the (guix tests) module has:
>>>
>>> (define (network-reachable?)
>>>   "Return true if we can reach the Internet."
>>>   (false-if-exception (getaddrinfo "www.gnu.org" "80" AI_NUMERICSERV)))
>>>
>>
>> This procedure however (despite the name) does not test whether network
>> is reachable, it tests whether single specific host name is resolvable.
>> That is not an equivalent of the example 'network-online service.
>>
>> 1. The procedure succeeds on completely offline machine, assuming there
>>    is a record for the host in /etc/hosts.  This is not an hypothetical
>>    problem, in my configuration the actual host name I ping (instead of
>>    example.org above) *is* in /etc/hosts.
>
> To be clear, I wasn't suggesting to change the host name checked;
> example.org seems a fine target as it appears intended for such use case
> (and maintained by the IANA).

I get that.  The point I was trying to make was that if you have
`example.org' in /etc/hosts, the `network-reachable?' against
`example.org' will always succeed, regardless of state of the network.

That is unlikely for example.org (or www.gnu.org), but it is the case
for the hostname I am actually checking in my configuration.  Hence the
`network-reachable?', as written above, would always return true.

Have a nice day,
Tomas
-- 
There are only two hard things in Computer Science:
cache invalidation, naming things and off-by-one errors.

[signature.asc (application/pgp-signature, inline)]

Message #25 received at 74510-done <at> debbugs.gnu.org (full text, mbox):

From: Maxim Cournoyer <maxim.cournoyer <at> gmail.com>
To: Tomas Volf <~@wolfsden.cz>
Cc: Ludovic Courtès <ludo <at> gnu.org>, 74510-done <at> debbugs.gnu.org
Subject: Re: [bug#74510] [PATCH v2] doc: Document the (possible) need for
 network-online for NFS.
Date: Sun, 09 Mar 2025 16:13:50 +0900

Hi,

Tomas Volf <~@wolfsden.cz> writes:

> Depending on networking is not enough in some setups, so a language clarifying
> that and an example of network-online service.
>
> * doc/guix.texi (File Systems): Document the possible need for network-online.

I've modified your wording slightly, like so:

--8<---------------cut here---------------start------------->8---
@@ -18170,11 +18170,14 @@ File Systems
 met before mounting the file system.
 
 As an example, an NOW'S file system would typically have a requirement for
-@code{networking}.  However be aware that depending on @code{networking}
-might not be sufficient in setups where @code{networking} being marked
-as started does not imply the network is configured and working
-(e.g. when using @code{dhcp-client-service-type}).  In those cases, a
-custom @code{network-online} service might be necessary.  Example:
+@code{networking}.  In some situations, requiring @code{networking}
+might not be sufficient as @code{networking} being marked as started
+does @emph{not} imply the network has already been configured and in
+working order (for example, when using
+@code{dhcpcd-client-service-type}).  For such cases, a custom
+@code{network-online} service might be necessary.  A sample
+@code{network-online} one-shot Shepherd service implementation is
+provided below:
 
 @lisp
--8<---------------cut here---------------end--------------->8---

and pushed!

-- 
Thanks,
Maxim

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.