From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:470:142:3::10]:53414) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ic7c6-0002fQ-36 for guix-patches@gnu.org; Tue, 03 Dec 2019 07:49:12 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ic7c2-0001LW-If for guix-patches@gnu.org; Tue, 03 Dec 2019 07:49:09 -0500 Received: from debbugs.gnu.org ([209.51.188.43]:33410) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1ic7bz-0001Im-MH for guix-patches@gnu.org; Tue, 03 Dec 2019 07:49:06 -0500 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1ic7bx-0002cA-J1 for guix-patches@gnu.org; Tue, 03 Dec 2019 07:49:01 -0500 Subject: [bug#38429] [PATCH 1/5] document scron References: <20191129175356.12403-1-rob@vllmrt.net> In-Reply-To: <20191129175356.12403-1-rob@vllmrt.net> Resent-Message-ID: From: Robert Vollmert Date: Tue, 3 Dec 2019 13:46:29 +0100 Message-Id: <20191203124632.1987-1-rob@vllmrt.net> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+kyle=kyleam.com@gnu.org Sender: "Guix-patches" To: 38429@debbugs.gnu.org Cc: Robert Vollmert * doc/guix.texi: Add documentation for scron-service. --- The first in a series of supplementary patches on top of the base scron service patch, to be squashed into that commit. doc/guix.texi | 100 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 99 insertions(+), 1 deletion(-) diff --git a/doc/guix.texi b/doc/guix.texi index e0b831c7e8..1aafa01166 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -283,7 +283,7 @@ System Configuration Services * Base Services:: Essential system services. -* Scheduled Job Execution:: The mcron service. +* Scheduled Job Execution:: Cron services. * Log Rotation:: The rottlog service. * Networking Services:: Network setup, SSH daemon, etc. * X Window:: Graphical display. @@ -12890,6 +12890,104 @@ specifications,, mcron, GNU@tie{}mcron}). @end deftp +@cindex scron +@cindex scheduling jobs +The @code{(gnu services scron)} module provides an interface to +scron, a simple daemon to run jobs at scheduled times. scron is +similar to the traditional Unix @command{cron} daemon; +the main difference is that it is much simpler. + +Jobs are executed as root via the shell with working direction @code{/}. +Use @code{su(1)} or corresponding Guile functions +(@pxref{Processes,,, guile, GNU Guile Reference Manual}). + +The example below defines an operating system that runs the +@command{updatedb} (@pxref{Invoking updatedb,,, find, Finding Files}) +and the @command{guix gc} commands (@pxref{Invoking guix gc}) daily, as +well as the @command{mkid} command on behalf of an unprivileged user +(@pxref{mkid invocation,,, idutils, ID Database Utilities}). + +@lisp +(use-modules (guix) (gnu) (gnu services scron)) +(use-package-modules base idutils) + +(define updatedb-job + ;; Run 'updatedb' at 3AM every day. Here we write the + ;; job's action as a Scheme procedure. + (let* + ((exp #~(begin + (execl (string-append #$findutils "/bin/updatedb") + "updatedb" + "--prunepaths=/tmp /var/tmp /gnu/store"))) + (script (program-file "updatedb-job" exp)) + (scron-job + (schedule "0 3 * * *") + (command script)))) + +(define garbage-collector-job + ;; Collect garbage 5 minutes after midnight every day. + ;; The job's action is a shell command. + (scron-job + (schedule "5 0 * * *") + (command "guix gc -F 1G"))) + +(define idutils-job + ;; Update the index database as user "charlie" at 12:15PM + ;; and 19:15PM. This runs from the user's home directory. + (let* + ((cmd #~(string-append #$idutils "/bin/mkid src")) + (cmd-su #~(string-append "su -c '" #$cmd "' charlie"))) + (scron-job + (schedule "15 12,19 * * *") + (command cmd-su)))) + +(operating-system + ;; @dots{} + (services (cons (service scron-service-type + (scron-configuration + (jobs (list garbage-collector-job + updatedb-job + idutils-job)))) + %base-services))) +@end lisp + +@defvr {Scheme Variable} scron-service-type + +This is the type of the @code{scron} service, whose value is an +@code{scron-configuration} object. + +This service type can be the target of a service extension that provides +it additional job specifications (@pxref{Service Composition}). In +other words, it is possible to define services that provide additional +mcron jobs to run. +@end defvr + +@deftp {Data Type} scron-configuration +Data type representing the configuration of scron. + +@table @asis +@item @code{scron} (default: @var{scron}) +The scron package to use. + +@item @code{jobs} +This is a list of scron jobs. +@end table +@end deftp + +@deftp {Data Type} scron-job +Data type representing an scron job. + +@table @asis +@item @code{schedule} +The job schedule, in Vixie cron syntax. See the @code{scron(1)} +man page for more information. + +@item @code{command} +The shell command to run, as a value that lowers to a string. +@end table +@end deftp + + @node Log Rotation @subsection Log Rotation -- 2.24.0