Writing a basic service for GNU Guix

Let’s write a service for GNU Guix that will automatically start
kmonad at boot, and keep it running until shutdown.

Note: before we proceed, we could make a kmonad “daemon” without
going to the trouble of writing a Guix-specific service: we could
start kmonad in a shell profile, write a cron job, or something
else. The user experience of these methods might be the same, but
writing a service keeps things organized and seems like the “right”
way. If nothing else, it’s a great learning opportunity.

Reading the docs

First let’s read the documentation of GNU Guix. We see that Guix
offers “services” which extend the functionality of the operating
system. The manual says:

Guix system services are connected by extensions. For instance, the
secure shell service extends the Shepherd—the initialization system,
running as PID 1—by giving it the command lines to start and stop the
secure shell daemon (see openssh-service-type); the UPower service
extends the D-Bus service by passing it its .service specification,
and extends the udev service by passing it device management rules
(see upower-service); the Guix daemon service extends the Shepherd 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 (see Base Services).

The Guix daemon sounds very similar to what we’re looking to
construct. Nearby, we see that the Guix daemon defines its own
“service type”:

(define guix-service-type
  (service-type
   (name 'guix)
   (extensions
    (list (service-extension shepherd-root-service-type guix-shepherd-service)
          (service-extension account-service-type guix-accounts)
          (service-extension activation-service-type guix-activation)))
   (default-value (guix-configuration))))

Hm. I didn’t expect we’d need to instatiate our own data type just to
create a simple init daemon. After all, kmonad is simpler than the
guix daemon – it just needs to start at boot, and that’s it. The
documentation is terse and it’s not clear whether there’s a better way
to proceed. Maybe if we find a simple example of service, we can build
off of it.

Reading some source

I saw that “Game Services” were listed in the manual. Maybe there’s a
simple one we can make a template of. First, we find the definition of
the games services /gnu/services/games.scm:

;;; GNU Guix --- Functional package management for GNU
;;; Copyright © 2018 Arun Isaac 
;;;
;;; This file is part of GNU Guix.
;;;
;;; GNU Guix is free software; you can redistribute it and/or modify it
;;; under the terms of the GNU General Public License as published by
;;; the Free Software Foundation; either version 3 of the License, or (at
;;; your option) any later version.
;;;
;;; GNU Guix is distributed in the hope that it will be useful, but
;;; WITHOUT ANY WARRANTY; without even the implied warranty of
;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;;; GNU General Public License for more details.
;;;
;;; You should have received a copy of the GNU General Public License
;;; along with GNU Guix.  If not, see .

(define-module (gnu services games)
  #:use-module (gnu services)
  #:use-module (gnu services shepherd)
  #:use-module (gnu packages admin)
  #:use-module (gnu packages games)
  #:use-module (gnu system shadow)
  #:use-module (guix gexp)
  #:use-module (guix modules)
  #:use-module (guix records)
  #:use-module (ice-9 match)
  #:export (wesnothd-configuration
            wesnothd-configuration?
            wesnothd-service-type))

;;;
;;; The Battle for Wesnoth server
;;;

(define-record-type* 
  wesnothd-configuration make-wesnothd-configuration wesnothd-configuration?
  (package wesnothd-configuration-package
           (default wesnoth-server))
  (port wesnothd-configuration-port
        (default 15000)))

(define %wesnothd-accounts
  (list (user-account
         (name "wesnothd")
         (group "wesnothd")
         (system? #t)
         (comment "Wesnoth daemon user")
         (home-directory "/var/empty")
         (shell (file-append shadow "/sbin/nologin")))
        (user-group
         (name "wesnothd")
         (system? #t))))

(define wesnothd-shepherd-service
  (match-lambda
    (($  package port)
     (with-imported-modules (source-module-closure
                             '((gnu build shepherd)))
       (shepherd-service
        (documentation "The Battle for Wesnoth server")
        (provision '(wesnoth-daemon))
        (requirement '(networking))
        (modules '((gnu build shepherd)))
        (start #~(make-forkexec-constructor/container
                  (list #$(file-append package "/bin/wesnothd")
                        "-p" #$(number->string port))
                  #:user "wesnothd" #:group "wesnothd"))
        (stop #~(make-kill-destructor)))))))

(define wesnothd-service-type
  (service-type
   (name 'wesnothd)
   (description
    "Run The Battle for Wesnoth server @command{wesnothd}.")
   (extensions
    (list (service-extension account-service-type
                             (const %wesnothd-accounts))
          (service-extension shepherd-root-service-type
                             (compose list wesnothd-shepherd-service))))
   (default-value (wesnothd-configuration))))

There’s only one game contained in (gnu services games) and that is
The Battle for Wesnoth Server. The Game Services reference says

To run wesnothd in the default configuration, instantiate it as:

(service wesnothd-service-type)

So far, we have a module that exports wesnothd-service-type and a
way to use that binding in our system config to declare a service.
Apparently, a new service-type is what we’re looking for after
all. Let’s start by implementing a kmonad-service-type and see where
that takes us.

Writing `kmonad-service-type`

A service-type (see Service Reference) takes a name, description,
and a list of service-extension objects, each of which describes how
to extend existing services. So what exactly is a
object? The service-extension documentation
says:

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.

So in the context of (define kmonad-service-type ...), a compute
function will receive the (single) value associated with
kmonad-service-type (a value which we have yet to define) and will
return the value required by target-type, which is the service being
extended. The wesnothd-service-type extends two services: the
account-service-type which is extended by a list of user-group and
user-account objects; and the shepherd-root-service-type which is
extended by a list of objects.

So which services should kmonad extend? It’s recommended to make a
dedicated user and group for a daemon (see stackoverflow), so let’s
extend the account-service-type with a new user and group to run the
kmonad daemon. Let’s also extend the shepherd-root-service-type
because we want our daemon managed by the init system, Shepherd:

(define kmonad-service-type
  (service-type
   (name 'kmonad)
   (description
    "Run kmonad as a daemon.")
   (extensions
    (list (service-extension account-service-type
                             (const %kmonad-daemon-accounts))
          (service-extension shepherd-root-service-type
                             (compose list kmonad-shepherd-service))))))

It looks pretty similar to wesnothd-service-type, but without the
default-value, which doesn’t really apply to kmonad. Next, we’ve got
to choose how to extend the account-service-type and the
shepherd-root-service-type.

Extending the `account-service-type`

As noted above, (const %kmonad-daemon-accounts) needs to evaluate to a
function of a single argument that returns a list of users and
groups. Well, const makes a function that takes some argument, and
then just returns whatever was passed to const–in this case,
%kmonad-daemon-accounts. All we’ve got to do is define
%kmonad-daemon-accounts.

We need one daemon user and one group. Our daemon user won’t require
login, so we’ll use /sbin/nologin (see man 8 nologin) like
%wesnothd-accounts. Similarly, it won’t require a home directory. We
can pretty much copy the %wesnothd-accounts to make
%kmonad-daemon-accounts:

(define %kmonad-daemon-accounts
  (list (user-account
         (name "kmonad-daemon")
         (group "kmonad-daemon")
         (system? #t)
         (comment "kmonad daemon user")
         (home-directory "/var/empty")
         (shell (file-append shadow "/sbin/nologin")))
        (user-group
         (name "kmonad-daemon")
         (system? #t))))

Extending the `shepherd-root-service-type`

As noted above, (compose list kmonad-shepherd-service) needs to
evaluate to a function of a single argument (a single argument of our
choice) and return a list of objects. That means
that kmonad-shepherd-service must take a single argument, and return
a single shepherd-service! Before we write
kmonad-shepherd-service, let’s decide what we want to pass
it. Minimally, kmonad needs a .kbd file to run. In theory, a user
could also specify other stuff (e.g. a log level), but let’s just
start with the .kbd path.

If we’re using wesnoth-shepherd-service as an example, we’ll need to
think about the requirement, start, and stop fields.

`requirement` field

We definitely need to wait for udev, but maybe we should also wait
for user-processes like the other daemons in the shepherd graph
do. Looking at the source for user-processes:

This is a synchronization point used to make sure user processes and daemons
get started only after crucial initial services have been started—file
system mounts, etc. This is similar to the ‘sysvinit’ target in systemd.

In theory we could explicitly wait for other shepherd services, but it
seems like this catch-all applies perfectly to our use case. Come to
think of it, I wonder why wesnothd doesn’t depend on
user-processes too.

`start` and `stop` fields

According to the Shepherd Services documentation, the start and
stop fields of shepherd-service take G-Expressions. But what’s a
g-expression? Well, because Guix uses Scheme for both higher-level
actions–like defining packages–and lower-level actions–like
building derivations generated by packages– it needs a faculty for
embedding lower-level code in higher-level code. So in the start
field of wesnoth-shepherd-service:

(start #~(make-forkexec-constructor/container
          (list #$(file-append package "/bin/wesnothd")
                "-p" #$(number->string port))
          #:user "wesnothd" #:group "wesnothd"))

Some lower-level code is passed with #~(...), within which
higher-level code is escaped with #$(...) which the compiler is able
to “lower” to lower-level code. Looking at the source for
make-forkexec-constructor/container, we see:

This is a variant of ‘make-forkexec-constructor’ that starts COMMAND in
NAMESPACES, a list of Linux namespaces such as ‘(mnt ipc). MAPPINGS is the
list of to make in the case of a separate mount
namespace, in addition to essential bind-mounts such /proc.

And the documentation for make-forkexec-contructor reads:

Return a procedure that forks a child process, closes all file
descriptors except the standard output and standard error descriptors,
sets the current directory to directory, sets the umask to
file-creation-mask unless it is #f, changes the environment to
environment-variables (using the environ procedure), sets the current
user to user and the current group to group unless they are #f, and
executes command (a list of strings.) The result of the procedure will
be the PID of the child process. Note that this will not work as
expected if the process “daemonizes” (forks); in that case, you will
need to pass #:pid-file, as explained below.

When pid-file is true, it must be the name of a PID file associated
with the process being launched; the return value is the PID once that
file has been created. If pid-file does not show up in less than
pid-file-timeout seconds, the service is considered as failing to
start.

When log-file is true, it names the file to which the service’s
standard output and standard error are redirected. log-file is created
if it does not exist, otherwise it is appended to.

The wesnoth source appears not to use the NAMESPACES feature of
the containerized-version, so we’ll stick with
make-forkexec-constructor as is used in the syslogd example.

`kmonad-shepherd-service`

Let’s put it all together:

(define (kmonad-shepherd-service kbd-path)
  (shepherd-service
   (documentation "Run the kmonad daemon (kmonad-daemon)." )
   (provision '(kmonad-daemon))
   (requirement '(udev user-processes))
   (start #~(make-forkexec-constructor
             (list #$(file-append kmonad "/bin/kmonad")
                   #$kbd-path "-l info")
             #:user "kmonad-daemon" #:group "kmonad-daemon"
             #:log-file "/var/log/kmonad.log"))
   (stop #~(make-kill-destructor))))

Making a module

Now let’s package our code into a module. If the location where we
keep local guix modules is ~/local-guix, then we can add our module
at ~/local-guix/my/services/kmonad.scm as:

(define-module (my services kmonad)
  #:use-module (gnu services)
  #:use-module (gnu services shepherd)
  #:use-module (gnu packages haskell-apps)
  #:use-module (gnu system shadow)
  #:use-module (guix gexp)
  #:export (kmonad-service-type))

(define %kmonad-daemon-accounts
  (list (user-account
         (name "kmonad-daemon")
         (group "kmonad-daemon")
         (system? #t)
         (comment "kmonad daemon user")
         (home-directory "/var/empty")
         (shell (file-append shadow "/sbin/nologin")))
        (user-group
         (name "kmonad-daemon")
         (system? #t))))

(define (kmonad-shepherd-service kbd-path)
  (shepherd-service
   (documentation "Run the kmonad daemon (kmonad-daemon)." )
   (provision '(kmonad-daemon))
   (requirement '(udev user-processes))
   (start #~(make-forkexec-constructor
             (list #$(file-append kmonad "/bin/kmonad")
                   #$kbd-path "-l info")
             #:user "kmonad-daemon" #:group "kmonad-daemon"
             #:log-file "/var/log/kmonad.log"))
   (stop #~(make-kill-destructor))))

(define kmonad-service-type
  (service-type
   (name 'kmonad)
   (description
    "Run kmonad as a daemon.")
   (extensions
    (list (service-extension account-service-type
                             (const %kmonad-daemon-accounts))
          (service-extension shepherd-root-service-type
                             (compose list kmonad-shepherd-service))))))

Using `kmonad-service-type`

Now adding a kmonad service is straightforward. Let’s add some other
kmonad-specific configuration to our system while we’re at it:

(use-modules (my services kmonad))
;; more modules

(operating-system
  (users
    (append (list (user-account
                    (supplementary-groups
                      '("input" ;; needed by kmonad
                        ;; more groups
                       ))
                    ;; more fields
                  )
                  ;; more users
            )
            %base-user-accounts))
  (packages
    (append (list
             "kmonad"
             ;; more packages
            )
            %base-packages))
  (services
    (append (list (service kmonad-service-type "/path/to/config.kbd")
                  ;; more services
            )
            (modify-services %desktop-services ;; needed to add kmonad udev rules
              (udev-service-type config =>
                (udev-configuration (inherit config)
                  (rules (cons kmonad
                    (udev-configuration-rules config))))))))
  ;; more fields
)

And reconfigure:

sudo guix system -L ~/local-guix reconfigure /path/to/config.scm

A simpler daemon?

I think it would be possible to add kmonad as a simple-service on top of
shepherd-root-service-type. After looking at the simple-service
source, we can try:

(simple-service 'kmonad-service shepherd-root-service-type
                (list (shepherd-service
                       (documentation "Run the kmonad daemon (kmonad-daemon)." )
                       (provision '(kmonad-daemon))
                       (requirement '(udev user-processes))
                       (start #~(make-forkexec-constructor
                                 (list #$(file-append kmonad "/bin/kmonad")
                                       #$kbd-path "-l info")
                                 #:log-file "/var/log/kmonad.log"))
                       (stop #~(make-kill-destructor)))))

Subscribe to Updates

What's Hot

Writing a basic service for GNU Guix

Writing a basic service for GNU Guix

Table of Contents

Reading the docs

Reading some source

Writing kmonad-service-type

Extending the account-service-type

Extending the shepherd-root-service-type

requirement field

start and stop fields

kmonad-shepherd-service

Making a module

Using kmonad-service-type

A simpler daemon?

References

Related Posts

Writing `kmonad-service-type`

Extending the `account-service-type`

Extending the `shepherd-root-service-type`

`requirement` field

`start` and `stop` fields

`kmonad-shepherd-service`

Using `kmonad-service-type`