Next: , Previous: , Up: Defining Services   [Contents][Index]


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

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 must return a value that is a valid parameter value for the service instance.

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.

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


Next: , Previous: , Up: Defining Services   [Contents][Index]