diff --git a/doc/guix.texi b/doc/guix.texi index 2d4f7d960e..9dddaf4f2f 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -39999,6 +39999,39 @@ This, as you can see, is a fairly sophisticated way to say hello. info on actions. @end deftp +@cindex configuration file, of Shepherd services +@deffn {Scheme Procedure} shepherd-configuration-action +Return a @code{configuration} action to display @var{file}, which should +be the name of the service's configuration file. + +It can be useful to equip services with that action. For example, the +service for the Tor anonymous router (@pxref{Networking Services, +@code{tor-service-type}}) is defined roughly like this: + +@lisp +(let ((torrc (plain-file "torrc" @dots{}))) + (shepherd-service + (provision '(tor)) + (requirement '(user-processes loopback syslogd)) + + (start #~(make-forkexec-constructor + (list #$(file-append tor "/bin/tor") "-f" #$torrc) + #:user "tor" #:group "tor")) + (stop #~(make-kill-destructor)) + (actions (list (shepherd-configuration-action torrc))) + (documentation "Run the Tor anonymous network overlay."))) +@end lisp + +Thanks to this action, administrators can inspect the configuration file +passed to @command{tor} with this shell command: + +@example +cat $(herd configuration tor) +@end example + +This can come in as a handy debugging tool! +@end deffn + @defvr {Scheme Variable} shepherd-root-service-type The service type for the Shepherd ``root service''---i.e., PID@tie{}1. diff --git a/gnu/services/shepherd.scm b/gnu/services/shepherd.scm index 7110e5aa89..b2601c0128 100644 --- a/gnu/services/shepherd.scm +++ b/gnu/services/shepherd.scm @@ -66,6 +66,8 @@ (define-module (gnu services shepherd) shepherd-action-documentation shepherd-action-procedure + shepherd-configuration-action + %default-modules shepherd-service-file @@ -333,6 +335,16 @@ (define shepherd&co #:options '(#:local-build? #t #:substitutable? #f))))) +(define (shepherd-configuration-action file) + "Return a 'configuration' action to display FILE, which should be the name +of the service's configuration file." + (shepherd-action + (name 'configuration) + (documentation "Display the name of this service's configuration file.") + (procedure #~(lambda (_) + (format #t "~a~%" #$file) + #$file)))) + (define (shepherd-configuration-file services shepherd) "Return the shepherd configuration file for SERVICES. SHEPHERD is used as shepherd package."