Next: Shepherd Services, Previous: Service Types and Services, Up: Defining Services [Contents][Index]
We have seen an overview of service types (see Service Types and Services). This section provides a reference on how to manipulate
services and service types. This interface is provided by the
(gnu services) module.
Return a new service of type, a <service-type> object (see
below). value can be any object; it represents the parameters of
this particular service instance.
When value is omitted, the default value specified by type is used; if type does not specify a default value, an error is raised.
For instance, this:
(service openssh-service-type)
is equivalent to this:
(service openssh-service-type
(openssh-configuration))
In both cases the result is an instance of openssh-service-type
with the default configuration.
Return true if obj is a service.
Return the type of service—i.e., a <service-type> object.
Return the value associated with service. It represents its parameters.
Here is an example of how a service is created and manipulated:
(define s
(service nginx-service-type
(nginx-configuration
(nginx nginx)
(log-directory log-directory)
(run-directory run-directory)
(file config-file))))
(service? s)
⇒ #t
(eq? (service-kind s) nginx-service-type)
⇒ #t
The modify-services form provides a handy way to change the
parameters of some of the services of a list such as
%base-services (see %base-services). It
evaluates to a list of services. Of course, you could always use
standard list combinators such as map and fold to do that
(see List Library in GNU Guile Reference Manual);
modify-services simply provides a more concise form for this
common pattern.
Modify the services listed in services according to the given clauses. Each clause has the form:
(type variable => body)
where type is a service type—e.g.,
guix-service-type—and variable is an identifier that is
bound within the body to the service parameters—e.g., a
guix-configuration instance—of the original service of that
type.
The body should evaluate to the new service parameters, which will
be used to configure the new service. This new service will replace the
original in the resulting list. Because a service’s service parameters
are created using define-record-type*, you can write a succinct
body that evaluates to the new service parameters by using the
inherit feature that define-record-type* provides.
Clauses can also have the following form:
(delete type)
Such a clause removes all services of the given type from services.
See Using the Configuration System, for example usage.
Next comes the programming interface for service types. This is
something you want to know when writing new service definitions, but not
necessarily when simply looking for ways to customize your
operating-system declaration.
This is the representation of a service type (see Service Types and Services).
nameThis is a symbol, used only to simplify inspection and debugging.
extensionsA non-empty list of <service-extension> objects (see below).
compose (default: #f)If this is #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 fold-services and is passed a list of values collected from
extensions. It may return any single value.
extend (default: #f)If this is #f, services of this type cannot be extended.
Otherwise, it must be a two-argument procedure: fold-services
calls it, passing it the initial value of the service as the first
argument and the result of applying compose to the extension
values as the second argument. It must return a value that is a valid
parameter value for the service instance.
descriptionThis is a string, possibly using Texinfo markup, describing in a couple
of sentences what the service is about. This string allows users to
find about the service through guix system search
(see Invoking guix system).
default-value (default: &no-default-value)The default value associated for instances of this service type. This
allows users to use the service form without its second argument:
(service type)
The returned service in this case has the default value specified by type.
See Service Types and Services, for examples.
Return a new extension for services of type target-type.
compute must be a one-argument procedure: 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.
Return true if obj is a service extension.
Occasionally, you might want to simply extend an existing service. This
involves creating a new service type and specifying the extension of
interest, which can be verbose; the simple-service procedure
provides a shorthand for this.
Return a service that extends target with value. This works by creating a singleton service type name, of which the returned service is an instance.
For example, this extends mcron (see Scheduled Job Execution) with an additional job:
(simple-service 'my-mcron-job mcron-service-type
#~(job '(next-hour (3)) "guix gc -F 2G"))
At the core of the service abstraction lies the fold-services
procedure, which is responsible for “compiling” a list of services
down to a single directory that contains everything needed to boot and
run the system—the directory shown by the guix system build
command (see Invoking guix system). In essence, it propagates
service extensions down the service graph, updating each node parameters
on the way, until it reaches the root node.
Fold services by propagating their extensions down to the root of type target-type; return the root service adjusted accordingly.
Lastly, the (gnu services) module also defines several essential
service types, some of which are listed below.
This is the root of the service graph. It produces the system directory
as returned by the guix system build command.
The type of the “boot service”, which produces the boot script. The boot script is what the initial RAM disk runs when booting.
The type of the /etc service. This service is used to create files under /etc and can be extended by passing it name/file tuples such as:
(list `("issue" ,(plain-file "issue" "Welcome!\n")))
In this example, the effect would be to add an /etc/issue file pointing to the given file.
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 (see Setuid Programs).
Type of the service that populates the system profile—i.e., the programs under /run/current-system/profile. Other services can extend it by passing it lists of packages to add to the system profile.
This is the type of the service that records provenance meta-data in the system itself. It creates several files under /run/current-system:
This is a “channel file” that can be passed to guix pull -C
or guix time-machine -C, and which describes the channels used
to build the system, if that information was available
(see Channels).
This is the file that was passed as the value for this
provenance-service-type service. By default, guix
system reconfigure automatically passes the OS configuration file it
received on the command line.
This contains the same information as the two other files but in a format that is more readily processable.
In general, these two pieces of information (channels and configuration file) are enough to reproduce the operating system “from source”.
Caveats: This information is necessary to rebuild your operating system, but it is not always sufficient. In particular, configuration.scm itself is insufficient if it is not self-contained—if it refers to external Guile modules or to extra files. If you want configuration.scm to be self-contained, we recommend that modules or files it refers to be part of a channel.
Besides, provenance meta-data is “silent” in the sense that it does not change the bits contained in your system, except for the meta-data bits themselves. Two different OS configurations or sets of channels can lead to the same system, bit-for-bit; when
provenance-service-typeis used, these two systems will have different meta-data and thus different store file names, which makes comparison less trivial.
This service is automatically added to your operating system
configuration when you use guix system reconfigure,
guix system init, or guix deploy.
Type of the service that collects lists of packages containing kernel-loadable modules, and adds them to the set of kernel-loadable modules.
This service type is intended to be extended by other service types, such as below:
(simple-service 'installing-module
linux-loadable-module-service-type
(list module-to-install-1
module-to-install-2))
This does not actually load modules at bootup, only adds it to the kernel profile so that it can be loaded by other means.
Next: Shepherd Services, Previous: Service Types and Services, Up: Defining Services [Contents][Index]