From ba0cc267101e504ae3816c64c6c16fa644dec8a6 Mon Sep 17 00:00:00 2001
From: Tomas Volf <~@wolfsden.cz>
Date: Sun, 2 Mar 2025 15:29:09 +0100
Subject: [PATCH] doc: Document possible need for network-online for NFS.

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
Signed-off-by: Maxim Cournoyer <maxim.cournoyer@gmail.com>
Modified-by: Maxim Cournoyer <maxim.cournoyer@gmail.com>
---
 doc/guix.texi | 30 +++++++++++++++++++++++++++++-
 1 file changed, 29 insertions(+), 1 deletion(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 979b723a258..05c855c5ea1 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -18170,7 +18170,35 @@ This is a list of symbols denoting Shepherd requirements that must be
 met before mounting the file system.
 
 As an example, an NFS file system would typically have a requirement for
-@code{networking}.
+@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, adding a
+requirement on a custom @code{network-online} service may be necessary.
+A sample @code{network-online} one-shot Shepherd service implementation
+is provided below:
+
+@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