diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/guix.texi | 471 | ||||
| -rw-r--r-- | doc/images/service-graph.dot | 35 |
2 files changed, 444 insertions, 62 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index 1b25bd938f..a3fa989d48 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -182,6 +182,13 @@ Services * Web Services:: Web servers. * Various Services:: Other services. +Defining Services + +* Service Composition:: The model for composing services. +* Service Types and Services:: Types and services. +* Service Reference:: API reference. +* dmd Services:: A particular type of service. + Packaging Guidelines * Software Freedom:: What may go into the distribution. @@ -5899,23 +5906,41 @@ Return a service that runs @code{syslogd}. If configuration file name settings. @end deffn -@deffn {Scheme Procedure} guix-service [#:guix guix] @ - [#:builder-group "guixbuild"] [#:build-accounts 10] @ - [#:authorize-hydra-key? #t] [#:use-substitutes? #t] @ - [#:extra-options '()] -Return a service that runs the build daemon from @var{guix}, and has -@var{build-accounts} user accounts available under @var{builder-group}. +@anchor{guix-configuration-type} +@deftp {Data Type} guix-configuration +This data type represents the configuration of the Guix build daemon. +@xref{Invoking guix-daemon}, for more information. + +@table @asis +@item @code{guix} (default: @var{guix}) +The Guix package to use. -When @var{authorize-hydra-key?} is true, the @code{hydra.gnu.org} public key -provided by @var{guix} is authorized upon activation, meaning that substitutes -from @code{hydra.gnu.org} are used by default. +@item @code{build-group} (default: @code{"guixbuild"}) +Name of the group for build user accounts. -If @var{use-substitutes?} is false, the daemon is run with -@option{--no-substitutes} (@pxref{Invoking guix-daemon, -@option{--no-substitutes}}). +@item @code{build-accounts} (default: @code{10}) +Number of build user accounts to create. -Finally, @var{extra-options} is a list of additional command-line options -passed to @command{guix-daemon}. +@item @code{authorize-key?} (default: @code{#t}) +Whether to authorize the substitute key for @code{hydra.gnu.org} +(@pxref{Substitutes}). + +@item @code{use-substitutes?} (default: @code{#t}) +Whether to use substitutes. + +@item @code{extra-options} (default: @code{'()}) +List of extra command-line options for @command{guix-daemon}. + +@item @code{lsof} (default: @var{lsof}) +@itemx @code{lsh} (default: @var{lsh}) +The lsof and lsh packages to use. + +@end table +@end deftp + +@deffn {Scheme Procedure} guix-service @var{config} +Return a service that runs the Guix build daemon according to +@var{config}. @end deffn @deffn {Scheme Procedure} udev-service [#:udev udev] @@ -6179,11 +6204,10 @@ The @var{%desktop-services} variable can be used as the @code{services} field of an @code{operating-system} declaration (@pxref{operating-system Reference, @code{services}}). -The actual service definitions provided by @code{(gnu services desktop)} -are described below. +The actual service definitions provided by @code{(gnu services dbus)} +and @code{(gnu services desktop)} are described below. -@deffn {Scheme Procedure} dbus-service @var{services} @ - [#:dbus @var{dbus}] +@deffn {Scheme Procedure} dbus-service [#:dbus @var{dbus}] [#:services '()] Return a service that runs the ``system bus'', using @var{dbus}, with support for @var{services}. @@ -6197,8 +6221,7 @@ and policy files. For example, to allow avahi-daemon to use the system bus, @var{services} must be equal to @code{(list avahi)}. @end deffn -@deffn {Scheme Procedure} elogind-service @ - [#:elogind @var{elogind}] [#:config @var{config}] +@deffn {Scheme Procedure} elogind-service [#:config @var{config}] Return a service that runs the @code{elogind} login and seat management daemon. @uref{https://github.com/andywingo/elogind, Elogind} exposes a D-Bus interface that can be used to know which users @@ -6957,54 +6980,378 @@ build users. @node Defining Services @subsection Defining Services -The @code{(gnu services @dots{})} modules define several procedures that allow -users to declare the operating system's services (@pxref{Using the -Configuration System}). These procedures are @emph{monadic -procedures}---i.e., procedures that return a monadic value in the store -monad (@pxref{The Store Monad}). For examples of such procedures, -@xref{Services}. - -@cindex service definition -The monadic value returned by those procedures is a @dfn{service -definition}---a structure as returned by the @code{service} form. -Service definitions specifies the inputs the service depends on, and an -expression to start and stop the service. Behind the scenes, service -definitions are ``translated'' into the form suitable for the -configuration file of dmd, the init system (@pxref{Services,,, dmd, GNU -dmd Manual}). - -As an example, here is what the @code{nscd-service} procedure looks -like: +The previous sections how the available services and how one can combine +them in an @code{operating-system} declaration. But how do we define +them in the first place? And what is a service anyway? -@lisp -(define (nscd-service) - (with-monad %store-monad - (return (service - (documentation "Run libc's name service cache daemon.") - (provision '(nscd)) - (activate #~(begin - (use-modules (guix build utils)) - (mkdir-p "/var/run/nscd"))) - (start #~(make-forkexec-constructor - (string-append #$glibc "/sbin/nscd") - "-f" "/dev/null" "--foreground")) - (stop #~(make-kill-destructor)) - (respawn? #f))))) -@end lisp +@menu +* Service Composition:: The model for composing services. +* Service Types and Services:: Types and services. +* Service Reference:: API reference. +* dmd Services:: A particular type of service. +@end menu + +@node Service Composition +@subsubsection Service Composition + +@cindex services +@cindex daemons +Here we define a @dfn{service} as, broadly, something that extends the +operating system's functionality. Often a service is a process---a +@dfn{daemon}---started when the system boots: a secure shell server, a +Web server, the Guix build daemon, etc. Sometimes a service is a daemon +whose execution can be triggered by another daemon---e.g., an FTP server +started by @command{inetd} or a D-Bus service activated by +@command{dbus-daemon}. Occasionally, a service does not map to a +daemon. For instance, the ``account'' service collects user accounts +and makes sure they exist when the system runs; the ``udev'' service +collects device management rules and makes them available to the eudev +daemon; the @file{/etc} service populates the system's @file{/etc} +directory. + +GuixSD services are connected by @dfn{extensions}. For instance, the +secure shell service @emph{extends} dmd---GuixSD's initialization system, +running as PID@tie{}1---by giving it the command lines to start and stop +the secure shell daemon (@pxref{Networking Services, +@code{lsh-service}}); the UPower service extends the D-Bus service by +passing it its @file{.service} specification, and extends the udev +service by passing it device management rules (@pxref{Desktop Services, +@code{upower-service}}); the Guix daemon service extends dmd by passing +it the command lines to start and stop the daemon, and extends the +account service by passing it a list of required build user accounts +(@pxref{Base Services}). + +All in all, services and their ``extends'' relations form a directed +acyclic graph (DAG). If we represent services as boxes and extensions +as arrows, a typical system might provide something like this: + +@image{images/service-graph,,5in,Typical service extension graph.} + +At the bottom, we see the @dfn{boot service}, which produces the boot +script that is executed at boot time from the initial RAM disk. + +@cindex service types +Technically, developers can define @dfn{service types} to express these +relations. There can be any number of services of a given type on the +system---for instance, a system running two instances of the GNU secure +shell server (lsh) has two instances of @var{lsh-service-type}, with +different parameters. + +The following section describes the programming interface for service +types and services. + +@node Service Types and Services +@subsubsection Service Types and Services + +A @dfn{service type} is a node in the DAG described above. Let us start +with a simple example, the service type for the Guix build daemon +(@pxref{Invoking guix-daemon}): + +@example +(define guix-service-type + (service-type + (name 'guix) + (extensions + (list (service-extension dmd-root-service-type guix-dmd-service) + (service-extension account-service-type guix-accounts) + (service-extension activation-service-type guix-activation))))) +@end example @noindent -The @code{activate}, @code{start}, and @code{stop} fields are G-expressions -(@pxref{G-Expressions}). The @code{activate} field contains a script to -run at ``activation'' time; it makes sure that the @file{/var/run/nscd} -directory exists before @command{nscd} is started. +It defines a two things: + +@enumerate +@item +A name, whose sole purpose is to make inspection and debugging easier. + +@item +A list of @dfn{service extensions}, where each extension designates the +target service type and a procedure that, given the service's +parameters, returns a list of object to extend the service of that type. + +Every service type has at least one service extension. The only +exception is the @dfn{boot service type}, which is the ultimate service. +@end enumerate + +In this example, @var{guix-service-type} extends three services: + +@table @var +@item dmd-root-service-type +The @var{guix-dmd-service} procedure defines how the dmd service is +extended. Namely, it returns a @code{<dmd-service>} object that defines +how @command{guix-daemon} is started and stopped (@pxref{dmd Services}). + +@item account-service-type +This extension for this service is computed by @var{guix-accounts}, +which returns a list of @code{user-group} and @code{user-account} +objects representing the build user accounts (@pxref{Invoking +guix-daemon}). + +@item activation-service-type +Here @var{guix-activation} is a procedure that returns a gexp, which is +a code snippet to run at ``activation time''---e.g., when the service is +booted. +@end table + +A service of this type is instantiated like this: + +@example +(service guix-service-type + (guix-configuration + (build-accounts 5) + (use-substitutes? #f))) +@end example + +The second argument to the @code{service} form is a value representing +the parameters of this specific service instance. +@xref{guix-configuration-type, @code{guix-configuration}}, for +information about the @code{guix-configuration} data type. + +@var{guix-service-type} is quite simple because it extends other +services but is not extensible itself. + +@c @subsubsubsection Extensible Service Types + +The service type for an @emph{extensible} service looks like this: + +@example +(define udev-service-type + (service-type (name 'udev) + (extensions + (list (service-extension dmd-root-service-type + udev-dmd-service))) + + (compose concatenate) ;concatenate the list of rules + (extend (lambda (config rules) + (match config + (($ <udev-configuration> udev initial-rules) + (udev-configuration + (udev udev) ;the udev package to use + (rules (append initial-rules rules))))))))) +@end example + +This is the service type for the +@uref{https://wiki.gentoo.org/wiki/Project:Eudev, eudev device +management daemon}. Compared to the previous example, in addition to an +extension of @var{dmd-root-service-type}, we see two new fields: + +@table @code +@item compose +This is the procedure to @dfn{compose} the list of extensions to +services of this type. + +Services can extend the udev service by passing it lists of rules; we +compose those extensions simply by concatenating them. + +@item extend +This procedure defines how the service's value is @dfn{extended} with +the composition of the extensions. + +Udev extensions are composed into a list of rules, but the udev service +value is itself a @code{<udev-configuration>} record. So here, we +extend that record by appending the list of rules is contains to the +list of contributed rules. +@end table + +There can be only one instance of an extensible service type such as +@var{udev-service-type}. If there were more, the +@code{service-extension} specifications would be ambiguous. + +Still here? The next section provides a reference of the programming +interface for services. + +@node Service Reference +@subsubsection Service Reference + +We have seen an overview of service types (@pxref{Service Types and +Services}). This section provides a reference on how to manipulate +services and service types. This interface is provided by the +@code{(gnu services)} module. + +@deffn {Scheme Procedure} service @var{type} @var{value} +Return a new service of @var{type}, a @code{<service-type>} object (see +below.) @var{value} can be any object; it represents the parameters of +this particular service instance. +@end deffn + +@deffn {Scheme Procedure} service? @var{obj} +Return true if @var{obj} is a service. +@end deffn + +@deffn {Scheme Procedure} service-kind @var{service} +Return the type of @var{service}---i.e., a @code{<service-type>} object. +@end deffn + +@deffn {Scheme Procedure} service-parameters @var{service} +Return the value associated with @var{service}. It represents its +parameters. +@end deffn + +Here is an example of how a service is created and manipulated: + +@example +(define s + (service nginx-service-type + (nginx-configuration + (nginx nginx) + (log-directory log-directory) + (run-directory run-directory) + (file config-file)))) + +(service? s) +@result{} #t + +(eq? (service-kind s) nginx-service-type) +@result{} #t +@end example + +@deftp {Data Type} service-type +@cindex service type +This is the representation of a @dfn{service type} (@pxref{Service Types +and Services}). + +@table @asis +@item @code{name} +This is a symbol, used only to simplify inspection and debugging. + +@item @code{extensions} +A non-empty list of @code{<service-extension>} objects (see below.) + +@item @code{compose} (default: @code{#f}) +If this is @code{#f}, then the service type denotes services that cannot +be extended---i.e., services that do not receive ``values'' from other +services. + +Otherwise, it must be a one-argument procedure. The procedure is called +by @code{fold-services} and is passed a list of values collected from +extensions. It must return a value that is a valid parameter value for +the service instance. + +@item @code{extend} (default: @code{#f}) +If this is @code{#f}, services of this type cannot be extended. + +Otherwise, it must be a two-argument procedure: @code{fold-services} +calls it, passing it the service's initial value as the first argument +and the result of applying @code{compose} to the extension values as the +second argument. +@end table + +@xref{Service Types and Services}, for examples. +@end deftp + +@deffn {Scheme Procedure} service-extension @var{target-type} @ + @var{compute} +Return a new extension for services of type @var{target-type}. +@var{compute} must be a one-argument procedure: @code{fold-services} +calls it, passing it the value associated with the service that provides +the extension; it must return a valid value for the target service. +@end deffn + +@deffn {Scheme Procedure} service-extension? @var{obj} +Return true if @var{obj} is a service extension. +@end deffn + +At the core of the service abstraction lies the @code{fold-services} +procedure, which is responsible for ``compiling'' a list of services +down to a single boot script. In essence, it propagates service +extensions down the service graph, updating each node parameters on the +way, until it reaches the root node. + +@deffn {Scheme Procedure} fold-services @var{services} @ + [#:target-type @var{boot-service-type}] +Fold @var{services} by propagating their extensions down to the root of +type @var{target-type}; return the root service adjusted accordingly. +@end deffn + +Lastly, the @code{(gnu services)} module also defines several essential +service types, some of which are listed below. + +@defvr {Scheme Variable} boot-service-type +The type of the ``boot service'', which is the root of the service +graph. +@end defvr + +@defvr {Scheme Variable} etc-service-type +The type of the @file{/etc} service. This service can be extended by +passing it name/file tuples such as: + +@example +(list `("issue" ,(plain-file "issue" "Welcome!\n"))) +@end example + +In this example, the effect would be to add an @file{/etc/issue} file +pointing to the given file. +@end defvr + +@defvr {Scheme Variable} setuid-program-service-type +Type for the ``setuid-program service''. This service collects lists of +executable file names, passed as gexps, and adds them to the set of +setuid-root programs on the system (@pxref{Setuid Programs}). +@end defvr + + +@node dmd Services +@subsubsection dmd Services + +@cindex PID 1 +@cindex init system +The @code{(gnu services dmd)} provides a way to define services managed +by GNU@tie{}dmd, which is GuixSD initialization system---the first +process that is started when the system boots, aka. PID@tie{}1 +(@pxref{Introduction,,, dmd, GNU dmd Manual}). The +@var{%dmd-root-service} represents PID@tie{}1, of type +@var{dmd-root-service-type}; it can be extended by passing it lists of +@code{<dmd-service>} objects. + +@deftp {Data Type} dmd-service +The data type representing a service managed by dmd. + +@table @asis +@item @code{provision} +This is a list of symbols denoting what the service provides. +These are the names that may be passed to @command{deco start}, +@command{deco status}, and similar commands (@pxref{Invoking deco,,, +dmd, GNU dmd Manual}). @xref{Slots of services, the @code{provides} +slot,, dmd, GNU dmd Manual}, for details. + +@item @code{requirements} (default: @code{'()}) +List of symbols denoting the dmd services this one depends on. + +@item @code{respawn?} (default: @code{#t}) +Whether to restart the service when it stops, for instance when the +underlying process dies. + +@item @code{start} +@itemx @code{stop} (default: @code{#~(const #f)}) The @code{start} and @code{stop} fields refer to dmd's facilities to start and stop processes (@pxref{Service De- and Constructors,,, dmd, -GNU dmd Manual}). The @code{provision} field specifies the name under -which this service is known to dmd, and @code{documentation} specifies -on-line documentation. Thus, the commands @command{deco start ncsd}, -@command{deco stop nscd}, and @command{deco doc nscd} will do what you -would expect (@pxref{Invoking deco,,, dmd, GNU dmd Manual}). +GNU dmd Manual}). They are given as G-expressions that get expanded in +the dmd configuration file (@pxref{G-Expressions}). + +@item @code{documentation} +A documentation string, as shown when running: + +@example +deco doc @var{service-name} +@end example + +where @var{service-name} is one of the symbols in @var{provision} +(@pxref{Invoking deco,,, dmd, GNU dmd Manual}). +@end table +@end deftp + +@defvr {Scheme Variable} dmd-root-service-type +The service type for the dmd ``root service''---i.e., PID@tie{}1. + +This is the service type that extensions target when they want to create +dmd services (@pxref{Service Types and Services}, for an example). Each +extension must pass a list of @code{<dmd-service>}. +@end defvr + +@defvr {Scheme Variable} %dmd-root-service +This service represents PID@tie{}1. +@end defvr @node Installing Debugging Files diff --git a/doc/images/service-graph.dot b/doc/images/service-graph.dot new file mode 100644 index 0000000000..3397b878e9 --- /dev/null +++ b/doc/images/service-graph.dot @@ -0,0 +1,35 @@ +digraph "Service Type Dependencies" { + dmd [shape = box, fontname = Helvetica]; + pam [shape = box, fontname = Helvetica]; + etc [shape = box, fontname = Helvetica]; + accounts [shape = box, fontname = Helvetica]; + activation [shape = box, fontname = Helvetica]; + boot [shape = house, fontname = Helvetica]; + lshd -> dmd; + lshd -> pam; + udev -> dmd; + nscd -> dmd [label = "extends"]; + "nss-mdns" -> nscd; + "kvm-rules" -> udev; + colord -> udev; + dbus -> dmd; + colord -> dbus; + upower -> udev; + upower -> dbus; + polkit -> dbus; + polkit -> pam; + elogind -> dbus; + elogind -> udev; + elogind -> polkit [label = "extends"]; + dmd -> boot; + colord -> accounts; + accounts -> activation; + accounts -> etc; + etc -> activation; + activation -> boot; + pam -> etc; + elogind -> pam; + guix -> dmd; + guix -> activation; + guix -> accounts; +} |