12.18.3 Service Reference

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.

Scheme Procedure: service type [value]

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.

Scheme Procedure: service? obj

Return true if obj is a service.

Scheme Procedure: service-kind service

Return the type of service—i.e., a <service-type> object.

Scheme Procedure: service-value service

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.

Scheme Syntax: modify-services services (type variable => body) …

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.

Data Type: service-type

This is the representation of a service type (see Service Types and Services).

name

This is a symbol, used only to simplify inspection and debugging.

extensions

A 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.

description

This 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.

Scheme Procedure: service-extension target-type compute

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.

Scheme Procedure: service-extension? obj

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.

Scheme Procedure: simple-service name target value

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.

Scheme Procedure: fold-services services [#:target-type system-service-type]

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.

Scheme Variable: system-service-type

This is the root of the service graph. It produces the system directory as returned by the guix system build command.

Scheme Variable: boot-service-type

The type of the “boot service”, which produces the boot script. The boot script is what the initial RAM disk runs when booting.

Scheme Variable: etc-service-type

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.

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 and setgid programs on the system (see Setuid Programs).

Scheme Variable: profile-service-type

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.

Scheme Variable: provenance-service-type

This is the type of the service that records provenance meta-data in the system itself. It creates several files under /run/current-system:

channels.scm

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).

configuration.scm

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.

provenance

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-type is 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.

Scheme Variable: linux-loadable-module-service-type

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.