From patchwork Sat Mar 22 11:36:53 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Ludovic_Court=C3=A8s?= X-Patchwork-Id: 40600 Return-Path: X-Original-To: patchwork@mira.cbaines.net Delivered-To: patchwork@mira.cbaines.net Received: by mira.cbaines.net (Postfix, from userid 113) id D487A27BBE2; Sat, 22 Mar 2025 11:39:20 +0000 (GMT) X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on mira.cbaines.net X-Spam-Level: X-Spam-Status: No, score=-7.6 required=5.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,MAILING_LIST_MULTI,RCVD_IN_DNSWL_BLOCKED, RCVD_IN_VALIDITY_CERTIFIED,RCVD_IN_VALIDITY_RPBL,RCVD_IN_VALIDITY_SAFE, SPF_HELO_PASS,URIBL_BLOCKED autolearn=ham autolearn_force=no version=3.4.6 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mira.cbaines.net (Postfix) with ESMTPS id 24A1F27BBEB for ; Sat, 22 Mar 2025 11:39:20 +0000 (GMT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tvxC9-0003AC-8a; Sat, 22 Mar 2025 07:39:17 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tvxBu-00030F-V1 for guix-patches@gnu.org; Sat, 22 Mar 2025 07:39:04 -0400 Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1tvxBt-0000Jq-SZ; Sat, 22 Mar 2025 07:39:02 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=debbugs.gnu.org; s=debbugs-gnu-org; h=MIME-Version:References:In-Reply-To:Date:From:To:Subject; bh=OwNCHcL/DSCY43ZGkUxSOWTuVU8NwUZzlF7xn5EKudY=; b=n9rdAXZUGDkyftWzobA0AF6w2Vlm59tW983u/ADQlrxJzZ0sHJMVLfc4rF5SZfp7SW997thFc/yp00olzg9zPLQeKTP7pIYWPj5+3Vd++BOwHNtoBka7p/QwhMDRbm15YegXYVW/BS1vEmXkAld6NEhC3mFPPny+cloDN6Rdd6gJPIIPBAvydkBBryIXvDlqVTc0THC1JXMQlDckaBijdGsvWeOweVTmV4eXmj+8c9V9gDpgwbb+UuEzlzv+Ri5zgGulfVU75ujF6hVwC9zCqIQ6wwEGreRz/ajgB6+BHUz0YMTXa+6/oqkf2RptucRANov6naWyzcHl+RovAL0YbQ==; Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1tvxBt-0002bX-Lm; Sat, 22 Mar 2025 07:39:01 -0400 X-Loop: help-debbugs@gnu.org Subject: [bug#77041] [PATCH v2 16/16] doc: Document Shepherd timers and recommend against mcron. Resent-From: Ludovic =?utf-8?q?Court=C3=A8s?= Original-Sender: "Debbugs-submit" Resent-CC: ludo@gnu.org, maxim.cournoyer@gmail.com, guix-patches@gnu.org Resent-Date: Sat, 22 Mar 2025 11:39:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 77041 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: 77041@debbugs.gnu.org Cc: Ludovic =?utf-8?q?Court=C3=A8s?= , Ludovic =?utf-8?q?Court?= =?utf-8?q?=C3=A8s?= , Maxim Cournoyer X-Debbugs-Original-Xcc: Ludovic =?utf-8?q?Court=C3=A8s?= , Maxim Cournoyer Received: via spool by 77041-submit@debbugs.gnu.org id=B77041.17426435209977 (code B ref 77041); Sat, 22 Mar 2025 11:39:01 +0000 Received: (at 77041) by debbugs.gnu.org; 22 Mar 2025 11:38:40 +0000 Received: from localhost ([127.0.0.1]:41229 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tvxBX-0002aq-IW for submit@debbugs.gnu.org; Sat, 22 Mar 2025 07:38:40 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:54296) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.84_2) (envelope-from ) id 1tvxAe-0002Vd-HO for 77041@debbugs.gnu.org; Sat, 22 Mar 2025 07:37:45 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tvxAZ-0008WG-8O; Sat, 22 Mar 2025 07:37:39 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-Version:References:In-Reply-To:Date:Subject:To: From; bh=OwNCHcL/DSCY43ZGkUxSOWTuVU8NwUZzlF7xn5EKudY=; b=ddhPlVasILnirU4Kq804 gh8GSdqJX1j3sdil++aSRNh7oipal6Pv/wvSNLe1BdllMMCsWD2U68XtpjA+NrUk5gPyAtASqb0G8 BXppOZA49WdUSyLOMZVfG62djXQEmkDMVG1uBFNjUys765MXeIvi6UyEo0qslviusogMaEUy1VEMg B1HfHt/Iquxky/F3+zOwp55DKQvNQ6bpP6q1zuyHZbUhw/hKDZQmTO1sGk1znsSgooDyCns2bmDCJ GNa+PtaCXC2wCcUOoTfa4LjKDx6gjPihxwYmaQd+slubw0FY1J5qbzF9rqN8ItAsRm/llBlb3/GJn okqv6qxyWDYJMA==; From: Ludovic =?utf-8?q?Court=C3=A8s?= Date: Sat, 22 Mar 2025 12:36:53 +0100 Message-ID: <521517bc62856586343fd55dad508a32cc3a29d1.1742642743.git.ludo@gnu.org> X-Mailer: git-send-email 2.48.1 In-Reply-To: References: MIME-Version: 1.0 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: guix-patches@gnu.org List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+patchwork=mira.cbaines.net@gnu.org Sender: guix-patches-bounces+patchwork=mira.cbaines.net@gnu.org X-getmail-retrieved-from-mailbox: Patches * doc/guix.texi (Scheduled Job Execution): Add intro. Add “Shepherd Timers” subsection; move previous documentation to “Mcron” subsection. Recommend use of Shepherd timers. (Mcron Home Service): Recommend Shepherd timers. (Shepherd Home Service): Document timers. Change-Id: I9dba68a0d062f5aeeae29ff725e1161f2bd3b291 --- doc/guix.texi | 168 +++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 159 insertions(+), 9 deletions(-) diff --git a/doc/guix.texi b/doc/guix.texi index 12eef9aa40..4592523f81 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -20849,14 +20849,123 @@ Scheduled Job Execution @subsection Scheduled Job Execution @cindex cron -@cindex mcron @cindex scheduling jobs -The @code{(gnu services mcron)} module provides an interface to +It is often useful to have system tasks run periodically. This can be +achieved by defining Shepherd @dfn{timers} or by using the historical +and somewhat less flexible mcron service. + +@subsubsection Shepherd Timers + +@cindex timers, Shepherd +@cindex Shepherd timers +The Shepherd supports running jobs periodically by defining +@dfn{timers}, a special kind of service. A Shepherd timer can be +defined like another Shepherd service, but with specific @code{start} +and @code{stop} methods (@pxref{Shepherd Services}): + +@lisp +;; Defining a timer, verbosely. +(shepherd-service + (provision '(updatedb)) + (requirement '(user-processes)) + (modules '((shepherd service timer))) + (start #~(make-timer-constructor + ;; Everyday at 3AM (using Vixie cron syntax). + (cron-string->calendar-event "0 3 * * *") + (command '(#$(file-append findutils "/bin/updatedb"))) + #:wait-for-termination? #t)) + (stop #~(make-timer-destructor)) + (documentation "Periodically run 'updatedb'.") + (actions (list shepherd-trigger-action))) +@end lisp + +This is quite some boilerplate so you can instead use this equivalent +shorthand notation: + +@lisp +;; Equivalent timer definition, but shorter. +(shepherd-timer '(updatedb) "0 3 * * *" + #~(#$(file-append findutils "/bin/updatedb")) + #:requirement '(user-processes)) +@end lisp + +This procedure is defined as follows. + +@anchor{shepherd-timer-procedure} +@deffn {Procedure} shepherd-timer @var{provision} @var{schedule} @ + @var{command} [#:requirement '()] @ + [#:documentation %default-timer-documentation] +Return a Shepherd service with the given @var{provision} periodically +running @var{command}, a list-valued gexp, according to @var{schedule}, +a string in Vixie cron syntax or a gexp providing a Shepherd calendar +event. @var{documentation} is the string that appears when running +@code{herd doc @var{service}}. +@end deffn + +The example below shows how to define a timer and to add it to your +operating system configuration. + +@lisp +(use-modules (gnu)) +(use-service-modules shepherd) +(use-package-modules base) + +(define updatedb-timer + ;; Run 'updatedb' at 3AM everyday. + (shepherd-timer '(updatedb) + "0 3 * * *" ;Vixie cron syntax + #~(#$(file-append findutils "/bin/updatedb") + "--prunepaths=/tmp /var/tmp /gnu/store") + #:requirement '(user-processes))) + +(define garbage-collection-timer + ;; Run 'guix gc' everyday at 5AM. + (shepherd-timer '(garbage-collection) + #~(calendar-event #:hours '(5) #:minutes '(0)) + #~("/run/current-system/profile/bin/guix" + "gc" "-F" "10G") + #:requirement '(guix-daemon))) + +(operating-system + ;; @dots{} + + ;; Extend the Shepherd service with additional timers + ;; using 'simple-service'. + (services (cons (simple-service 'my-timers + shepherd-root-service-type + (list garbage-collection-timer + updatedb-timer)) + %base-services))) +@end lisp + +The resulting system contains these two services, which can be inspected +with @command{herd status}. They can also be triggered manually: + +@example +herd trigger garbage-collection +@end example + +@ref{Timers,,, shepherd, The GNU Shepherd Manual} for more information +on Shepherd timers. + +@anchor{mcron-service} +@subsubsection Mcron + +@cindex mcron +Alternatively, +the @code{(gnu services mcron)} module provides an interface to GNU@tie{}mcron, a daemon to run jobs at scheduled times (@pxref{Top,,, mcron, GNU@tie{}mcron}). GNU@tie{}mcron is similar to the traditional Unix @command{cron} daemon; the main difference is that it is -implemented in Guile Scheme, which provides a lot of flexibility when -specifying the scheduling of jobs and their actions. +implemented in Guile Scheme. It is overall less convenient than +Shepherd timers: individual jobs cannot depend on specific Shepherd +services, logging is coarse-grain (one file for all the jobs), jobs may +not be inspected, updated, or triggered manually. + +@quotation Note +For the reasons given above, we recommend using Shepherd timers rather +than mcron for your periodic tasks. +@end quotation The example below defines an operating system that runs the @command{updatedb} (@pxref{Invoking updatedb,,, find, Finding Files}) @@ -48610,18 +48719,23 @@ Shells Home Services @node Mcron Home Service @subsection Scheduled User's Job Execution -@cindex cron -@cindex mcron -@cindex scheduling jobs - +@cindex cron, per-user +@cindex mcron, per-user +@cindex scheduling jobs per-user The @code{(gnu home services mcron)} module provides an interface to GNU@tie{}mcron, a daemon to run jobs at scheduled times (@pxref{Top,,, mcron, GNU@tie{}mcron}). The information about system's mcron is -applicable here (@pxref{Scheduled Job Execution}), the only difference +applicable here (@pxref{mcron-service, mcron reference}), the only difference for home services is that they have to be declared in a @code{home-environment} record instead of an @code{operating-system} record. +@quotation Note +We recommend defining periodic tasks as Shepherd timers, which provide +more flexibility than mcron. @xref{Shepherd Home Service}, for more +info. +@end quotation + @defvar home-mcron-service-type This is the type of the @code{mcron} home service, whose value is a @code{home-mcron-configuration} object. It allows to manage scheduled @@ -48784,6 +48898,42 @@ Shepherd Home Service @end table @end deftp +@cindex timers, per-user +The Shepherd allows you to define @dfn{timers}, a special type of +service that performs a given task periodically. Just like you can +define timers at the system level (@pxref{Scheduled Job Execution}), you +can do so in your home environment. + +The example below defines a home environment where a Shepherd timer runs +the @command{mkid} command twice per day (@pxref{mkid invocation,,, +idutils, ID Database Utilities}). It does so by extending +@code{home-shepherd-service-type} with @code{simple-service}; the +Shepherd timer itself is produced by the @code{shepherd-timer} procedure +(@pxref{shepherd-timer-procedure, @code{shepherd-timer}}), which is +given the service name, a gexp specifying its schedule, and a gexp +specifying the command to run. + +@lisp +(use-modules (gnu) (guix) + (gnu home services shepherd) + (gnu packages idutils)) + +(define idutils-service + ;; Index my 'doc' directory everyday at 12:15PM and 7:15PM. + (simple-service + 'update-idutils-database home-shepherd-service-type + (list (shepherd-timer '(update-idutils-database) + #~(calendar-event #:hours '(12 19) + #:minutes '(15)) + #~(#$(file-append idutils "/bin/mkid") + "doc"))))) + +(home-environment + ;; @dots{} + (services (append (list idutils-service) + %base-home-services))) +@end lisp + @cindex log rotation, for user services The Shepherd also comes with a @dfn{log rotation service}, which compresses and then deletes old log files produced by services and