diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/emacs.texi | 10 | ||||
| -rw-r--r-- | doc/guix.texi | 657 | ||||
| -rw-r--r-- | doc/images/service-graph.dot | 35 |
3 files changed, 579 insertions, 123 deletions
diff --git a/doc/emacs.texi b/doc/emacs.texi index b6f2701bc4..ab69515972 100644 --- a/doc/emacs.texi +++ b/doc/emacs.texi @@ -667,6 +667,16 @@ this command---for example, with @kbd{C-M-x} (@pxref{To eval or not to eval,,, geiser, Geiser User Manual}) (@code{guix-devel-build-package-definition}). +@item C-c . s +Build a source derivation of the package defined by the current variable +definition. This command has the same meaning as @code{guix build -S} +shell command (@pxref{Invoking guix build}) +(@code{guix-devel-build-package-source}). + +@item C-c . l +Lint (check) a package defined by the current variable definition +(@pxref{Invoking guix lint}) (@code{guix-devel-lint-package}). + @end table Unluckily, there is a limitation related to long-running REPL commands. diff --git a/doc/guix.texi b/doc/guix.texi index 79877f156b..709ec0ff70 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. @@ -3367,7 +3374,8 @@ The other arguments are as for @code{derivation} (@pxref{Derivations}). @end deffn @cindex file-like objects -The @code{local-file} and @code{plain-file} procedures below return +The @code{local-file}, @code{plain-file}, @code{computed-file}, +@code{program-file}, and @code{scheme-file} procedures below return @dfn{file-like objects}. That is, when unquoted in a G-expression, these objects lead to a file in the store. Consider this G-expression: @@ -3405,6 +3413,16 @@ Return an object representing a text file called @var{name} with the given This is the declarative counterpart of @code{text-file}. @end deffn +@deffn {Scheme Procedure} computed-file @var{name} @var{gexp} @ + [#:modules '()] [#:options '(#:local-build? #t)] +Return an object representing the store item @var{name}, a file or +directory computed by @var{gexp}. @var{modules} specifies the set of +modules visible in the execution context of @var{gexp}. @var{options} +is a list of additional arguments to pass to @code{gexp->derivation}. + +This is the declarative counterpart of @code{gexp->derivation}. +@end deffn + @deffn {Monadic Procedure} gexp->script @var{name} @var{exp} Return an executable script @var{name} that runs @var{exp} using @var{guile} with @var{modules} in its search path. @@ -3432,6 +3450,15 @@ executable file @file{/gnu/store/@dots{}-list-files} along these lines: @end example @end deffn +@deffn {Scheme Procedure} program-file @var{name} @var{exp} @ + [#:modules '()] [#:guile #f] +Return an object representing the executable store item @var{name} that +runs @var{gexp}. @var{guile} is the Guile package used to execute that +script, and @var{modules} is the list of modules visible to that script. + +This is the declarative counterpart of @code{gexp->script}. +@end deffn + @deffn {Monadic Procedure} gexp->file @var{name} @var{exp} Return a derivation that builds a file @var{name} containing @var{exp}. @@ -3439,6 +3466,13 @@ The resulting file holds references to all the dependencies of @var{exp} or a subset thereof. @end deffn +@deffn {Scheme Procedure} scheme-file @var{name} @var{exp} +Return an object representing the Scheme file @var{name} that contains +@var{exp}. + +This is the declarative counterpart of @code{gexp->file}. +@end deffn + @deffn {Monadic Procedure} text-file* @var{name} @var{text} @dots{} Return as a monadic value a derivation that builds a text file containing all of @var{text}. @var{text} may list, in addition to @@ -3465,6 +3499,19 @@ will references @var{coreutils}, @var{grep}, and @var{sed}, thereby preventing them from being garbage-collected during its lifetime. @end deffn +@deffn {Scheme Procedure} mixed-text-file @var{name} @var{text} @dots{} +Return an object representing store file @var{name} containing +@var{text}. @var{text} is a sequence of strings and file-like objects, +as in: + +@example +(mixed-text-file "profile" + "export PATH=" coreutils "/bin:" grep "/bin") +@end example + +This is the declarative counterpart of @code{text-file*}. +@end deffn + Of course, in addition to gexps embedded in ``host'' code, there are also modules containing build tools. To make it clear that they are meant to be used in the build stratum, these modules are kept in the @@ -4560,11 +4607,12 @@ and Emacs are available: guix environment guile emacs @end example -Sometimes an interactive shell session is not desired. The -@code{--exec} option can be used to specify the command to run instead. +Sometimes an interactive shell session is not desired. An arbitrary +command may be invoked by placing the @code{--} token to separate the +command from the rest of the arguments: @example -guix environment guile --exec=make +guix environment guile -- make -j4 @end example In other situations, it is more convenient to specify the list of @@ -4573,7 +4621,7 @@ runs @command{python} from an environment containing Python@tie{}2.7 and NumPy: @example -guix environment --ad-hoc python2-numpy python-2.7 -E python +guix environment --ad-hoc python2-numpy python-2.7 -- python @end example The available options are summarized below. @@ -4604,11 +4652,6 @@ As an example, @var{file} might contain a definition like this @verbatiminclude environment-gdb.scm @end example - -@item --exec=@var{command} -@item -E @var{command} -Execute @var{command} in the new environment. - @item --ad-hoc Include all specified packages in the resulting environment, as if an @i{ad hoc} package were defined with them as inputs. This option is @@ -4618,7 +4661,7 @@ package expression to contain the desired inputs. For instance, the command: @example -guix environment --ad-hoc guile guile-sdl -E guile +guix environment --ad-hoc guile guile-sdl -- guile @end example runs @command{guile} in an environment where Guile and Guile-SDL are @@ -5743,38 +5786,55 @@ this: @end example @end defvr -@deffn {Monadic Procedure} host-name-service @var{name} +@deffn {Scheme Procedure} host-name-service @var{name} Return a service that sets the host name to @var{name}. @end deffn -@deffn {Monadic Procedure} mingetty-service @var{tty} [#:motd] @ - [#:auto-login #f] [#:login-program] [#:login-pause? #f] @ - [#:allow-empty-passwords? #f] -Return a service to run mingetty on @var{tty}. +@deffn {Scheme Procedure} mingetty-service @var{config} +Return a service to run mingetty according to @var{config}, a +@code{<mingetty-configuration>} object, which specifies the tty to run, among +other things. +@end deffn -When @var{allow-empty-passwords?} is true, allow empty log-in password. When -@var{auto-login} is true, it must be a user name under which to log-in -automatically. @var{login-pause?} can be set to @code{#t} in conjunction with -@var{auto-login}, in which case the user will have to press a key before the -login shell is launched. +@deftp {Data Type} mingetty-configuration +This is the data type representing the configuration of Mingetty, which +implements console log-in. -When true, @var{login-program} is a gexp or a monadic gexp denoting the name -of the log-in program (the default is the @code{login} program from the Shadow -tool suite.) +@table @asis -@var{motd} is a monadic value containing a text file to use as -the ``message of the day''. -@end deffn +@item @code{tty} +The name of the console this Mingetty runs on---e.g., @code{"tty1"}. + +@item @code{motd} +A file-like object containing the ``message of the day''. + +@item @code{auto-login} (default: @code{#f}) +When true, this field must be a string denoting the user name under +which the the system automatically logs in. When it is @code{#f}, a +user name and password must be entered to log in. + +@item @code{login-program} (default: @code{#f}) +This must be either @code{#f}, in which case the default log-in program +is used (@command{login} from the Shadow tool suite), or a gexp denoting +the name of the log-in program. + +@item @code{login-pause?} (default: @code{#f}) +When set to @code{#t} in conjunction with @var{auto-login}, the user +will have to press a key before the log-in shell is launched. + +@item @code{mingetty} (default: @var{mingetty}) +The Mingetty package to use. + +@end table +@end deftp @cindex name service cache daemon @cindex nscd -@deffn {Monadic Procedure} nscd-service [@var{config}] [#:glibc glibc] @ +@deffn {Scheme Procedure} nscd-service [@var{config}] [#:glibc glibc] @ [#:name-services '()] -Return a service that runs libc's name service cache daemon (nscd) with -the given @var{config}---an @code{<nscd-configuration>} object. -Optionally, @code{#:name-services} is a list of packages that provide -name service switch (NSS) modules needed by nscd. @xref{Name Service -Switch}, for an example. +Return a service that runs libc's name service cache daemon (nscd) with the +given @var{config}---an @code{<nscd-configuration>} object. @xref{Name +Service Switch}, for an example. @end deffn @defvr {Scheme Variable} %nscd-default-configuration @@ -5789,6 +5849,14 @@ configuration. @table @asis +@item @code{name-services} (default: @code{'()}) +List of packages denoting @dfn{name services} that must be visible to +the nscd---e.g., @code{(list @var{nss-mdns})}. + +@item @code{glibc} (default: @var{glibc}) +Package object denoting the GNU C Library providing the @command{nscd} +command. + @item @code{log-file} (default: @code{"/var/log/nscd.log"}) Name of nscd's log file. This is where debugging output goes when @code{debug-level} is strictly positive. @@ -5855,36 +5923,54 @@ external name servers do not even need to be queried. @end defvr -@deffn {Monadic Procedure} syslog-service [#:config-file #f] +@deffn {Scheme Procedure} syslog-service [#:config-file #f] Return a service that runs @code{syslogd}. If configuration file name @var{config-file} is not specified, use some reasonable default settings. @end deffn -@deffn {Monadic 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. -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. +@table @asis +@item @code{guix} (default: @var{guix}) +The Guix package to use. -If @var{use-substitutes?} is false, the daemon is run with -@option{--no-substitutes} (@pxref{Invoking guix-daemon, -@option{--no-substitutes}}). +@item @code{build-group} (default: @code{"guixbuild"}) +Name of the group for build user accounts. -Finally, @var{extra-options} is a list of additional command-line options -passed to @command{guix-daemon}. +@item @code{build-accounts} (default: @code{10}) +Number of build user accounts to create. + +@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 {Monadic Procedure} udev-service [#:udev udev] +@deffn {Scheme Procedure} udev-service [#:udev udev] Run @var{udev}, which populates the @file{/dev} directory dynamically. @end deffn -@deffn {Monadic Procedure} console-keymap-service @var{file} +@deffn {Scheme Procedure} console-keymap-service @var{file} Return a service to load console keymap from @var{file} using @command{loadkeys} command. @end deffn @@ -5897,12 +5983,12 @@ The @code{(gnu services networking)} module provides services to configure the network interface. @cindex DHCP, networking service -@deffn {Monadic Procedure} dhcp-client-service [#:dhcp @var{isc-dhcp}] +@deffn {Scheme Procedure} dhcp-client-service [#:dhcp @var{isc-dhcp}] Return a service that runs @var{dhcp}, a Dynamic Host Configuration Protocol (DHCP) client, on all the non-loopback network interfaces. @end deffn -@deffn {Monadic Procedure} static-networking-service @var{interface} @var{ip} @ +@deffn {Scheme Procedure} static-networking-service @var{interface} @var{ip} @ [#:gateway #f] [#:name-services @code{'()}] Return a service that starts @var{interface} with address @var{ip}. If @var{gateway} is true, it must be a string specifying the default network @@ -5910,12 +5996,12 @@ gateway. @end deffn @cindex wicd -@deffn {Monadic Procedure} wicd-service [#:wicd @var{wicd}] +@deffn {Scheme Procedure} wicd-service [#:wicd @var{wicd}] Return a service that runs @url{https://launchpad.net/wicd,Wicd}, a network manager that aims to simplify wired and wireless networking. @end deffn -@deffn {Monadic Procedure} ntp-service [#:ntp @var{ntp}] @ +@deffn {Scheme Procedure} ntp-service [#:ntp @var{ntp}] @ [#:name-service @var{%ntp-servers}] Return a service that runs the daemon from @var{ntp}, the @uref{http://www.ntp.org, Network Time Protocol package}. The daemon will @@ -5926,14 +6012,14 @@ keep the system clock synchronized with that of @var{servers}. List of host names used as the default NTP servers. @end defvr -@deffn {Monadic Procedure} tor-service [#:tor tor] +@deffn {Scheme Procedure} tor-service [#:tor tor] Return a service to run the @uref{https://torproject.org,Tor} daemon. The daemon runs with the default settings (in particular the default exit policy) as the @code{tor} unprivileged user. @end deffn -@deffn {Monadic Procedure} bitlbee-service [#:bitlbee bitlbee] @ +@deffn {Scheme Procedure} bitlbee-service [#:bitlbee bitlbee] @ [#:interface "127.0.0.1"] [#:port 6667] @ [#:extra-settings ""] Return a service that runs @url{http://bitlbee.org,BitlBee}, a daemon that @@ -5950,7 +6036,7 @@ configuration file. Furthermore, @code{(gnu services ssh)} provides the following service. -@deffn {Monadic Procedure} lsh-service [#:host-key "/etc/lsh/host-key"] @ +@deffn {Scheme Procedure} lsh-service [#:host-key "/etc/lsh/host-key"] @ [#:daemonic? #t] [#:interfaces '()] [#:port-number 22] @ [#:allow-empty-passwords? #f] [#:root-login? #f] @ [#:syslog-output? #t] [#:x11-forwarding? #t] @ @@ -6017,7 +6103,7 @@ browsers, from accessing Facebook. The @code{(gnu services avahi)} provides the following definition. -@deffn {Monadic Procedure} avahi-service [#:avahi @var{avahi}] @ +@deffn {Scheme Procedure} avahi-service [#:avahi @var{avahi}] @ [#:host-name #f] [#:publish? #t] [#:ipv4? #t] @ [#:ipv6? #t] [#:wide-area? #f] @ [#:domains-to-browse '()] @@ -6047,7 +6133,7 @@ Xorg---is provided by the @code{(gnu services xorg)} module. Note that there is no @code{xorg-service} procedure. Instead, the X server is started by the @dfn{login manager}, currently SLiM. -@deffn {Monadic Procedure} slim-service [#:allow-empty-passwords? #f] @ +@deffn {Scheme Procedure} slim-service [#:allow-empty-passwords? #f] @ [#:auto-login? #f] [#:default-user ""] [#:startx] @ [#:theme @var{%default-slim-theme}] @ [#:theme-name @var{%default-slim-theme-name}] @@ -6083,7 +6169,7 @@ theme. The G-Expression denoting the default SLiM theme and its name. @end defvr -@deffn {Monadic Procedure} xorg-start-command [#:guile] @ +@deffn {Scheme Procedure} xorg-start-command [#:guile] @ [#:configuration-file #f] [#:xorg-server @var{xorg-server}] Return a derivation that builds a @var{guile} script to start the X server from @var{xorg-server}. @var{configuration-file} is the server configuration @@ -6093,7 +6179,7 @@ file or a derivation that builds it; when omitted, the result of Usually the X server is started by a login manager. @end deffn -@deffn {Monadic Procedure} xorg-configuration-file @ +@deffn {Scheme Procedure} xorg-configuration-file @ [#:drivers '()] [#:resolutions '()] [#:extra-config '()] Return a configuration file for the Xorg server containing search paths for all the common drivers. @@ -6141,11 +6227,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 {Monadic 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}. @@ -6159,8 +6244,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 {Monadic 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 @@ -6230,7 +6314,7 @@ their default values are: @end table @end deffn -@deffn {Monadic Procedure} polkit-service @ +@deffn {Scheme Procedure} polkit-service @ [#:polkit @var{polkit}] Return a service that runs the Polkit privilege manager. @uref{http://www.freedesktop.org/wiki/Software/polkit/, Polkit} allows @@ -6240,7 +6324,7 @@ whose session is active to shut down the machine, if there are no other users active. @end deffn -@deffn {Monadic Procedure} upower-service [#:upower @var{upower}] @ +@deffn {Scheme Procedure} upower-service [#:upower @var{upower}] @ [#:watts-up-pro? #f] @ [#:poll-batteries? #t] @ [#:ignore-lid? #f] @ @@ -6259,7 +6343,7 @@ levels, with the given configuration settings. It implements the GNOME. @end deffn -@deffn {Monadic Procedure} colord-service [#:colord @var{colord}] +@deffn {Scheme Procedure} colord-service [#:colord @var{colord}] Return a service that runs @command{colord}, a system service with a D-Bus interface to manage the color profiles of input and output devices such as screens and scanners. It is notably used by the GNOME Color Manager graphical @@ -6287,7 +6371,7 @@ Firefox and Epiphany both query the user before allowing a web page to know the user's location. @end defvr -@deffn {Monadic Procedure} geoclue-service [#:colord @var{colord}] @ +@deffn {Scheme Procedure} geoclue-service [#:colord @var{colord}] @ [#:whitelist '()] @ [#:wifi-geolocation-url "https://location.services.mozilla.com/v1/geolocate?key=geoclue"] @ [#:submit-data? #f] @@ -6307,7 +6391,7 @@ web site} for more information. The @code{(gnu services databases)} module provides the following service. -@deffn {Monadic Procedure} postgresql-service [#:postgresql postgresql] @ +@deffn {Scheme Procedure} postgresql-service [#:postgresql postgresql] @ [#:config-file] [#:data-directory ``/var/lib/postgresql/data''] Return a service that runs @var{postgresql}, the PostgreSQL database server. @@ -6322,7 +6406,7 @@ The PostgreSQL daemon loads its runtime configuration from The @code{(gnu services web)} module provides the following service: -@deffn {Monadic Procedure} nginx-service [#:nginx nginx] @ +@deffn {Scheme Procedure} nginx-service [#:nginx nginx] @ [#:log-directory ``/var/log/nginx''] @ [#:run-directory ``/var/run/nginx''] @ [#:config-file] @@ -6342,7 +6426,7 @@ directories are created when the service is activated. The @code{(gnu services lirc)} module provides the following service. -@deffn {Monadic Procedure} lirc-service [#:lirc lirc] @ +@deffn {Scheme Procedure} lirc-service [#:lirc lirc] @ [#:device #f] [#:driver #f] [#:config-file #f] @ [#:extra-options '()] Return a service that runs @url{http://www.lirc.org,LIRC}, a daemon that @@ -6515,13 +6599,11 @@ configuration file: (define %my-base-services ;; Replace the default nscd service with one that knows ;; about nss-mdns. - (map (lambda (mservice) - ;; "Bind" the MSERVICE monadic value to inspect it. - (mlet %store-monad ((service mservice)) - (if (member 'nscd (service-provision service)) - (nscd-service (nscd-configuration) - #:name-services (list nss-mdns)) - mservice))) + (map (lambda (service) + (if (member 'nscd (service-provision service)) + (nscd-service (nscd-configuration + (name-services (list nss-mdns)))) + service)) %base-services)) @end example @@ -6880,6 +6962,11 @@ using the following command: Attempt to build for @var{system} instead of the host's system type. This works as per @command{guix build} (@pxref{Invoking guix build}). +@item --derivation +@itemx -d +Return the derivation file name of the given operating system without +building anything. + @item --image-size=@var{size} For the @code{vm-image} and @code{disk-image} actions, create an image of the given @var{size}. @var{size} may be a number of bytes, or it may @@ -6916,54 +7003,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 show 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; +} |