gnu: services: Add btrfs-scrub-service-type.

* gnu/services/linux.scm (btrfs-scrub-configuration): New configuration
record.
(btrfs-scrub-service-type): New service type with custom actions.
(fstrim-/shepherd-calendar-event?): Refactor to avoid name collisions.
* doc/guix.texi: Add service documentation.

Change-Id: I04747914591a80cd535d2f79d35e08f68081b2fc
Signed-off-by: Joan Vilardaga Castro <codeberg-hn80@joanvc.cat>
Signed-off-by: Efraim Flashner <efraim@flashner.co.il>

1 files changed, 76 insertions, 0 deletions

diff --git a/doc/guix.texi b/doc/guix.texi
index 8d45ed1f43b..debe9b48a77 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -151,6 +151,7 @@ Copyright @copyright{} 2025 Noé Lopez@*
 Copyright @copyright{} 2026 David Elsing@*
 Copyright @copyright{} 2026 Nguyễn Gia Phong@*
 Copyright @copyright{} 2026 Yarl Baudig@*
+Copyright @copyright{} 2026 Joan Vilardaga Castro@*
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -45888,6 +45889,81 @@ mount.
 @end table
 @end deftp
 
+@subsubheading btrfs-scrub Service
+@cindex btrfs-scrub service
+@cindex solid state drives, periodic trim
+@cindex solid state drives, trim
+
+@c This was copied from the btrfs-scrub manpage, with some Texinfo touch-ups.
+@quotation Information
+Scrub is a validation pass over all filesystem data and metadata that
+detects data checksum errors, basic super block errors, basic metadata
+block header errors, and disk read errors.
+
+Scrub is done on a per-device base, if a device is specified to
+@command{btrfs scrub start}, then only that device will be
+scrubbed.  Although btrfs will also try to read other device to find a
+good copy, if the mirror on that specified device failed to be read or
+pass verification.
+
+If a path of btrfs is specified to @command{btrfs scrub start}, btrfs
+will scrub all devices in parallel.
+
+On filesystems that use replicated block group profiles (e.g. RAID1),
+read-write scrub will also automatically repair any damage by copying
+verified good data from one of the other replicas.
+
+Such automatic repair is also carried out when reading metadata or data
+from a read-write mounted filesystem.
+@end quotation
+
+@defvar btrfs-scrub-service-type
+Type for a service that periodically runs @command{btrfs-scrub} on a
+certain device, whose value must be an
+@code{<btrfs-scrub-configuration>} object.  The service can be
+instantiated in its default configuration with:
+
+@lisp
+;; This will scrub the root (@file{/}) filesystem.
+(service btrfs-scrub-service-type)
+
+;; This will scrub the @file{/gnu/store} filesystem (assuming it's a
+;; different filesystem from @file{/}).
+
+(service btrfs-scrub-service-type
+  (btrfs-scrub-configuration
+    (to-scrub "/gnu/store")))
+@end lisp
+@end defvar
+
+@c %start of fragment
+
+@deftp {Data Type} btrfs-scrub-configuration
+Available @code{btrfs-scrub-configuration} fields are:
+
+@table @asis
+@item @code{package} (default: @code{btrfs-progs}) (type: file-like)
+The package providing the @command{btrfs} command.
+
+@item @code{schedule} (default: @code{"0 0 1-7 * 0"}) (type: Shepherd calendar event)
+Schedule for launching @command{btrfs-scrub}, expressed as a string in
+traditional cron syntax or as a gexp evaluating to a Shepherd calendar
+event (@pxref{Timers,,, shepherd, The GNU Shepherd Manual}).  By default
+this is set to run the 1st Sunday of the month, at 00:00.
+
+@item @code{to-scrub} (default: @code{"/"}) (type: maybe-string)
+Device to scrub.  It will scrub the root (@file{/}) if not given.
+
+@item @code{extra-arguments} (type: maybe-list-of-strings)
+Extra options to append to @command{btrfs scrub start} (run @samp{man
+btrfs-scrub.8} for more information).  Keep in mind that, by definition,
+this service uses the @option{-B} flag (do not background and print
+scrub statistics when finished).
+
+@end table
+
+@end deftp
+
 @cindex oom
 @cindex out of memory killer
 @cindex earlyoom