civodul pushed a commit to branch wip-syslogd
in repository shepherd.
commit e1d6f8ee29d956c9a9df5c18a69157047ba6c9a2
Author: Ludovic Courtès <l...@gnu.org>
AuthorDate: Mon Aug 5 18:04:51 2024 +0200
squash! doc
---
doc/shepherd.texi | 151 ++++++++++++++++++++++++++++++--
modules/shepherd/service/system-log.scm | 11 ++-
2 files changed, 154 insertions(+), 8 deletions(-)
diff --git a/doc/shepherd.texi b/doc/shepherd.texi
index b7bca3f..3082492 100644
--- a/doc/shepherd.texi
+++ b/doc/shepherd.texi
@@ -1933,11 +1933,152 @@ The Shepherd comes with a collection of services that
let you control it
or otherwise extend its functionality. This chapter documents them.
@menu
+* System Log Service:: Good ol' syslog.
* Log Rotation Service:: Tidying up log files.
* Monitoring Service:: Monitoring shepherd resource usage.
* REPL Service:: Interacting with a running shepherd.
@end menu
+@node System Log Service
+@section System Log Service
+
+@cindex system log (syslogd)
+@cindex syslogd (system log)
+Traditionally, GNU and Unix-like systems come with a system-wide logging
+mechanism called @dfn{syslog} that applications and services can use.
+This mechanism usually relies on a standalone process, the
+@command{syslogd} daemon, that listens for incoming messages, typically
+on the @file{/dev/log} Unix-domain socket, and writes them to files or
+terminals according to user settings (@pxref{syslogd invocation,
+syslogd,, inetutils, GNU Inetutils}). Each message sent to
+@command{syslogd} specifies its @dfn{priority} and originating
+@dfn{facility} along with the actual message (@pxref{Overview of
+Syslog,,, libc, The GNU C Library Reference Manual}).
+
+The Shepherd provides an optional in-process service that can be used as
+a substitute for the traditional @command{syslogd} program. The
+configuration snippet below instantiates and registers that service for
+@command{shepherd} running as PID@tie{}1:
+
+@lisp
+(use-modules (shepherd service system-log))
+
+(register-services
+ ;; Create a system log with the default settings.
+ (list (system-log-service)))
+
+;; Start it.
+(start-service (lookup-service 'system-log))
+@end lisp
+
+The configuration above starts the service under the names
+@code{system-log} and @code{syslogd}. Messages are logged in files
+under @file{/var/log}, on @file{/dev/tty12} (the twelfth console
+terminal on Linux), and on the console for emergency messages.
+
+The destination of syslog messages---the files, terminals, etc. where
+they are written---can be configured by passing a procedure as the
+@code{#:message-destination} argument of @code{system-log-service}:
+
+@lisp
+(define (message-destination message)
+ ;; Return the list of files where MESSAGE is to be written.
+ (cond ((member (system-log-message-priority message)
+ (list (system-log-priority emergency)
+ (system-log-priority alert)))
+ ;; Important messages go both to a file and to the console.
+ '("/dev/console" "/var/log/messages))
+ ((string-prefix? "sudo" (system-log-message-content message))
+ ;; Messages coming from sudo go to a dedicated file.
+ '("/var/log/sudo"))
+ ((member (system-log-message-facility message)
+ (list (system-log-facility authorization)
+ (system-log-facility authorization/private)))
+ ;; Security-sensitive messages are written only to this
+ ;; one file.
+ '("/var/log/secure"))
+ (else
+ ;; Everything else goes to /var/log/messages.
+ '("/var/log/messages"))))
+
+(define my-syslogd
+ ;; Customized system log instance.
+ (system-log-service #:message-destination message-destination))
+@end lisp
+
+The example above shows how to assign different destinations based on
+message priority, facility, and content. Note that each message can be
+written to zero, one, or more files.
+
+The interface to the system log service is provided by the
+@code{(shepherd service system-log)} module and described thereafter.
+
+@deffn {Procedure} system-log-message? @var{obj}
+Return true if @var{obj} is a system log message.
+@end deffn
+
+@deffn {Procedure} system-log-message-facility @var{message}
+@deffnx {Procedure} system-log-message-priority @var{message}
+@deffnx {Procedure} system-log-message-content @var{message}
+@deffnx {Procedure} system-log-message-sender @var{message}
+Return the given attribute of @var{message}, a system log message:
+
+@itemize
+@item
+Its facility, an integer as constructed by @code{system-log-facility}.
+For example, the expression @code{(system-log-facility mail)} evaluates
+to the value of the ``mail'' facility.
+
+@item
+Its priority, an integer as constructed by @code{system-log-priority}.
+For example, @code{(system-log-priority debug)} returns the ``debug''
+priority.
+
+@item
+Its content, a string.
+
+@item
+Its sender, either @code{#f}, in which case the message originates from
+the local host, or a socket address as constructed by
+@code{make-socket-address} if the message originates from a different
+host (see below).
+@end itemize
+@end deffn
+
+@deffn {Procedure} system-log-service [@var{sources}] @
+ [#:provision '(system-log syslogd)] @
+ [#:requirement '()] @
+ [#:kernel-log-file (kernel-log-file)] @
+ [#:message-destination (default-message-destination-procedure)] @
+ [#:max-silent-time (default-max-silent-time)]
+Return the system log service (@dfn{syslogd}) with the given
+@var{provision} and @var{requirement} (lists of symbols). The service accepts
+connections on @var{sources}, a list of @code{<endpoint>} objects; optionally
+it also reads messages from @code{#:kernel-log-file}, which defaults to
+@file{/proc/kmsg} when running as root.
+
+Log messages are passed to @var{message-destination}, a one-argument procedure
+that must return the list of files to write it to. Write a mark to log files
+when no message has been logged for more than @var{max-silent-time} seconds.
+@end deffn
+
+@deffn {Procedure} default-message-destination-procedure
+Return a procedure that, given a system log message, returns a ``good''
+default destination to log it to.
+@end deffn
+
+@defvar kernel-log-file
+This SRFI-39 parameter denotes the location of the kernel log file,
+@file{/proc/kmsg} by default.
+@end defvar
+
+@defvar default-max-silent-time
+This SRFI-39 parameter denotes the maximum number of seconds after which
+syslogd prints a ``mark'' in its files if it has not printed anything
+for this long.
+@end defvar
+
+
@node Log Rotation Service
@section Log Rotation Service
@@ -2142,8 +2283,8 @@ inside of the Shepherd and is considered generally
useful, but is not directly
related to one of the other topic covered in this manual.
@menu
-* Errors:: Signalling, handling and ignoring errors.
-* Communication:: Input/Output in various ways.
+* Errors:: Signalling, handling and ignoring errors.
+* Communication:: Input/Output in various ways.
@end menu
@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@@ -2266,9 +2407,9 @@ You're very much welcome to join us! You can report bugs
to
@email{guix-devel@@gnu.org}.
@menu
-* Coding Standards:: How to properly hack the Shepherd.
-* Design Decisions:: Why the Shepherd is what it is.
-* Service Internals:: How services actually work.
+* Coding Standards:: How to properly hack the Shepherd.
+* Design Decisions:: Why the Shepherd is what it is.
+* Service Internals:: How services actually work.
@end menu
@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
diff --git a/modules/shepherd/service/system-log.scm
b/modules/shepherd/service/system-log.scm
index 486c52c..fb04397 100644
--- a/modules/shepherd/service/system-log.scm
+++ b/modules/shepherd/service/system-log.scm
@@ -51,6 +51,7 @@
read-system-log-message
kernel-log-file
+ default-max-silent-time
system-log-service))
;; Message sent to the system log (minus its timestamp).
@@ -316,7 +317,7 @@ the file(s) returned by @var{message-destination} for each
message."
channel))
(define (default-message-destination-procedure)
- "Return a procedure that, given a <system-log-message>, returns a good
+ "Return a procedure that, given a system log message, returns a ``good''
default destination to log it to."
(if (zero? (getuid))
(lambda (message)
@@ -346,6 +347,10 @@ default destination to log it to."
;; File to read to get kernel messages.
(make-parameter "/proc/kmsg"))
+(define default-max-silent-time
+ ;; Maximum number of seconds during which syslogd should remain silent.
+ (make-parameter (* 20 60)))
+
;; Running system log.
(define-record-type <system-log>
(system-log channel ports dispatcher)
@@ -363,7 +368,7 @@ default destination to log it to."
(define (file->endpoint file)
"Return a endpoint for Unix-domain socket @var{file}."
(endpoint (make-socket-address AF_UNIX file)
- #:name "Unix-domain endpoint"
+ #:name "Unix-domain system log endpoint"
#:style SOCK_DGRAM))
(define* (system-log-service #:optional
@@ -376,7 +381,7 @@ default destination to log it to."
(kernel-log-file)))
(message-destination
(default-message-destination-procedure))
- (max-silent-time (* 20 60)))
+ (max-silent-time (default-max-silent-time)))
"Return the system log service (@dfn{syslogd}) with the given
@var{provision} and @var{requirement} (lists of symbols). The service accepts
connections on @var{sources}, a list of @code{<endpoint>} objects; optionally
