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


6.2.7.1 Base Services

The (gnu services base) module provides definitions for the basic services that one expects from the system. The services exported by this module are listed below.

Scheme Variable: %base-services

This variable contains a list of basic services (see Service Types and Services, for more information on service objects) one would expect from the system: a login service (mingetty) on each tty, syslogd, the libc name service cache daemon (nscd), the udev device manager, and more.

This is the default value of the services field of operating-system declarations. Usually, when customizing a system, you will want to append services to %base-services, like this:

(cons* (avahi-service) (lsh-service) %base-services)
Scheme Variable: special-files-service-type

This is the service that sets up “special files” such as /bin/sh; an instance of it is part of %base-services.

The value associated with special-files-service-type services must be a list of tuples where the first element is the “special file” and the second element is its target. By default it is:

`(("/bin/sh" ,(file-append bash "/bin/sh")))

If you want to add, say, /usr/bin/env to your system, you can change it to:

`(("/bin/sh" ,(file-append bash "/bin/sh"))
  ("/usr/bin/env" ,(file-append coreutils "/bin/env")))

Since this is part of %base-services, you can use modify-services to customize the set of special files (see modify-services). But the simple way to add a special file is via the extra-special-file procedure (see below.)

Scheme Procedure: extra-special-file file target

Use target as the “special file” file.

For example, adding the following lines to the services field of your operating system declaration leads to a /usr/bin/env symlink:

(extra-special-file "/usr/bin/env"
                    (file-append coreutils "/bin/env"))
Scheme Procedure: host-name-service name

Return a service that sets the host name to name.

Scheme Procedure: login-service config

Return a service to run login according to config, a <login-configuration> object, which specifies the message of the day, among other things.

Data Type: login-configuration

This is the data type representing the configuration of login.

motd

A file-like object containing the “message of the day”.

allow-empty-passwords? (default: #t)

Allow empty passwords by default so that first-time users can log in when the ’root’ account has just been created.

Scheme Procedure: mingetty-service config

Return a service to run mingetty according to config, a <mingetty-configuration> object, which specifies the tty to run, among other things.

Data Type: mingetty-configuration

This is the data type representing the configuration of Mingetty, which provides the default implementation of virtual console log-in.

tty

The name of the console this Mingetty runs on—e.g., "tty1".

auto-login (default: #f)

When true, this field must be a string denoting the user name under which the system automatically logs in. When it is #f, a user name and password must be entered to log in.

login-program (default: #f)

This must be either #f, in which case the default log-in program is used (login from the Shadow tool suite), or a gexp denoting the name of the log-in program.

login-pause? (default: #f)

When set to #t in conjunction with auto-login, the user will have to press a key before the log-in shell is launched.

mingetty (default: mingetty)

The Mingetty package to use.

Scheme Procedure: agetty-service config

Return a service to run agetty according to config, an <agetty-configuration> object, which specifies the tty to run, among other things.

Data Type: agetty-configuration

This is the data type representing the configuration of agetty, which implements virtual and serial console log-in. See the agetty(8) man page for more information.

tty

The name of the console this agetty runs on, as a string—e.g., "ttyS0". This argument is mandatory.

baud-rate (default: #f)

A string containing a comma-separated list of one or more baud rates, in descending order.

term (default: #f)

A string containing the value used for the TERM environment variable.

eight-bits? (default: #f)

When #t, the tty is assumed to be 8-bit clean, and parity detection is disabled.

auto-login (default: #f)

When passed a login name, as a string, the specified user will be logged in automatically without prompting for their login name or password.

no-reset? (default: #f)

When #t, don’t reset terminal cflags (control modes).

host (default: #f)

This accepts a string containing the "login_host", which will be written into the /var/run/utmpx file.

remote? (default: #f)

When set to #t in conjunction with host, this will add an -r fakehost option to the command line of the login program specified in login-program.

flow-control? (default: #f)

When set to #t, enable hardware (RTS/CTS) flow control.

no-issue? (default: #f)

When set to #t, the contents of the /etc/issue file will not be displayed before presenting the login prompt.

init-string (default: #f)

This accepts a string that will be sent to the tty or modem before sending anything else. It can be used to initialize a modem.

no-clear? (default: #f)

When set to #t, agetty will not clear the screen before showing the login prompt.

login-program (default: (file-append shadow "/bin/login"))

This must be either a gexp denoting the name of a log-in program, or unset, in which case the default value is the login from the Shadow tool suite.

local-line (default: #f)

Control the CLOCAL line flag. This accepts one of three symbols as arguments, 'auto, 'always, or 'never. If #f, the default value chosen by agetty is 'auto.

extract-baud? (default: #f)

When set to #t, instruct agetty to try to extract the baud rate from the status messages produced by certain types of modems.

skip-login? (default: #f)

When set to #t, do not prompt the user for a login name. This can be used with login-program field to use non-standard login systems.

no-newline? (default: #f)

When set to #t, do not print a newline before printing the /etc/issue file.

login-options (default: #f)

This option accepts a string containing options that are passed to the login program. When used with the login-program, be aware that a malicious user could try to enter a login name containing embedded options that could be parsed by the login program.

login-pause (default: #f)

When set to #t, wait for any key before showing the login prompt. This can be used in conjunction with auto-login to save memory by lazily spawning shells.

chroot (default: #f)

Change root to the specified directory. This option accepts a directory path as a string.

hangup? (default: #f)

Use the Linux system call vhangup to do a virtual hangup of the specified terminal.

keep-baud? (default: #f)

When set to #t, try to keep the existing baud rate. The baud rates from baud-rate are used when agetty receives a BREAK character.

timeout (default: #f)

When set to an integer value, terminate if no user name could be read within timeout seconds.

detect-case? (default: #f)

When set to #t, turn on support for detecting an uppercase-only terminal. This setting will detect a login name containing only uppercase letters as indicating an uppercase-only terminal and turn on some upper-to-lower case conversions. Note that this will not support Unicode characters.

wait-cr? (default: #f)

When set to #t, wait for the user or modem to send a carriage-return or linefeed character before displaying /etc/issue or login prompt. This is typically used with the init-string option.

no-hints? (default: #f)

When set to #t, do not print hints about Num, Caps, and Scroll locks.

no-hostname? (default: #f)

By default, the hostname is printed. When this option is set to #t, no hostname will be shown at all.

long-hostname? (default: #f)

By default, the hostname is only printed until the first dot. When this option is set to #t, the fully qualified hostname by gethostname or getaddrinfo is shown.

erase-characters (default: #f)

This option accepts a string of additional characters that should be interpreted as backspace when the user types their login name.

kill-characters (default: #f)

This option accepts a string that should be interpreted to mean "ignore all previous characters" (also called a "kill" character) when the types their login name.

chdir (default: #f)

This option accepts, as a string, a directory path that will be changed to before login.

delay (default: #f)

This options accepts, as an integer, the number of seconds to sleep before opening the tty and displaying the login prompt.

nice (default: #f)

This option accepts, as an integer, the nice value with which to run the login program.

extra-options (default: '())

This option provides an "escape hatch" for the user to provide arbitrary command-line arguments to agetty as a list of strings.

Scheme Procedure: kmscon-service-type config

Return a service to run kmscon according to config, a <kmscon-configuration> object, which specifies the tty to run, among other things.

Data Type: kmscon-configuration

This is the data type representing the configuration of Kmscon, which implements virtual console log-in.

virtual-terminal

The name of the console this Kmscon runs on—e.g., "tty1".

login-program (default: #~(string-append #$shadow "/bin/login"))

A gexp denoting the name of the log-in program. The default log-in program is login from the Shadow tool suite.

login-arguments (default: '("-p"))

A list of arguments to pass to login.

hardware-acceleration? (default: #f)

Whether to use hardware acceleration.

kmscon (default: kmscon)

The Kmscon package to use.

Scheme Procedure: nscd-service [config] [#:glibc glibc] [#:name-services '()]

Return a service that runs the libc name service cache daemon (nscd) with the given config—an <nscd-configuration> object. See Name Service Switch, for an example.

Scheme Variable: %nscd-default-configuration

This is the default <nscd-configuration> value (see below) used by nscd-service. It uses the caches defined by %nscd-default-caches; see below.

Data Type: nscd-configuration

This is the data type representing the name service cache daemon (nscd) configuration.

name-services (default: '())

List of packages denoting name services that must be visible to the nscd—e.g., (list nss-mdns).

glibc (default: glibc)

Package object denoting the GNU C Library providing the nscd command.

log-file (default: "/var/log/nscd.log")

Name of the nscd log file. This is where debugging output goes when debug-level is strictly positive.

debug-level (default: 0)

Integer denoting the debugging levels. Higher numbers mean that more debugging output is logged.

caches (default: %nscd-default-caches)

List of <nscd-cache> objects denoting things to be cached; see below.

Data Type: nscd-cache

Data type representing a cache database of nscd and its parameters.

database

This is a symbol representing the name of the database to be cached. Valid values are passwd, group, hosts, and services, which designate the corresponding NSS database (see NSS Basics in The GNU C Library Reference Manual).

positive-time-to-live
negative-time-to-live (default: 20)

A number representing the number of seconds during which a positive or negative lookup result remains in cache.

check-files? (default: #t)

Whether to check for updates of the files corresponding to database.

For instance, when database is hosts, setting this flag instructs nscd to check for updates in /etc/hosts and to take them into account.

persistent? (default: #t)

Whether the cache should be stored persistently on disk.

shared? (default: #t)

Whether the cache should be shared among users.

max-database-size (default: 32 MiB)

Maximum size in bytes of the database cache.

Scheme Variable: %nscd-default-caches

List of <nscd-cache> objects used by default by nscd-configuration (see above).

It enables persistent and aggressive caching of service and host name lookups. The latter provides better host name lookup performance, resilience in the face of unreliable name servers, and also better privacy—often the result of host name lookups is in local cache, so external name servers do not even need to be queried.

Data Type: syslog-configuration

This data type represents the configuration of the syslog daemon.

syslogd (default: #~(string-append #$inetutils "/libexec/syslogd"))

The syslog daemon to use.

config-file (default: %default-syslog.conf)

The syslog configuration file to use.

Scheme Procedure: syslog-service config

Return a service that runs a syslog daemon according to config.

See syslogd invocation in GNU Inetutils, for more information on the configuration file syntax.

Data Type: guix-configuration

This data type represents the configuration of the Guix build daemon. See Invoking guix-daemon, for more information.

guix (default: guix)

The Guix package to use.

build-group (default: "guixbuild")

Name of the group for build user accounts.

build-accounts (default: 10)

Number of build user accounts to create.

authorize-key? (default: #t)

Whether to authorize the substitute keys listed in authorized-keys—by default that of hydra.gnu.org (see Substitutes).

authorized-keys (default: %default-authorized-guix-keys)

The list of authorized key files for archive imports, as a list of string-valued gexps (see Invoking guix archive). By default, it contains that of hydra.gnu.org (see Substitutes).

use-substitutes? (default: #t)

Whether to use substitutes.

substitute-urls (default: %default-substitute-urls)

The list of URLs where to look for substitutes by default.

max-silent-time (default: 0)
timeout (default: 0)

The number of seconds of silence and the number of seconds of activity, respectively, after which a build process times out. A value of zero disables the timeout.

extra-options (default: '())

List of extra command-line options for guix-daemon.

log-file (default: "/var/log/guix-daemon.log")

File where guix-daemon’s standard output and standard error are written.

http-proxy (default: #f)

The HTTP proxy used for downloading fixed-output derivations and substitutes.

tmpdir (default: #f)

A directory path where the guix-daemon will perform builds.

Scheme Procedure: guix-service config

Return a service that runs the Guix build daemon according to config.

Scheme Procedure: udev-service [#:udev eudev #:rules '()]

Run udev, which populates the /dev directory dynamically. udev rules can be provided as a list of files through the rules variable. The procedures udev-rule and file->udev-rule from (gnu services base) simplify the creation of such rule files.

Scheme Procedure: udev-rule [file-name contents]

Return a udev-rule file named file-name containing the rules defined by the contents literal.

In the following example, a rule for a USB device is defined to be stored in the file 90-usb-thing.rules. The rule runs a script upon detecting a USB device with a given product identifier.

(define %example-udev-rule
  (udev-rule
    "90-usb-thing.rules"
    (string-append "ACTION==\"add\", SUBSYSTEM==\"usb\", "
                   "ATTR{product}==\"Example\", "
                   "RUN+=\"/path/to/script\"")))

Here we show how the default udev-service can be extended with it.

(operating-system
 ;; …
 (services
 (modify-services %desktop-services
   (udev-service-type config =>
     (udev-configuration (inherit config)
      (rules (append (udev-configuration-rules config)
                     (list %example-udev-rule))))))))
Scheme Procedure: file->udev-rule [file-name file]

Return a udev file named file-name containing the rules defined within file, a file-like object.

The following example showcases how we can use an existing rule file.

(use-modules (guix download)     ;for url-fetch
             (guix packages)     ;for origin
             ;; …)

(define %android-udev-rules
  (file->udev-rule
    "51-android-udev.rules"
    (let ((version "20170910"))
      (origin
       (method url-fetch)
       (uri (string-append "https://raw.githubusercontent.com/M0Rf30/"
                           "android-udev-rules/" version "/51-android.rules"))
       (sha256
        (base32 "0lmmagpyb6xsq6zcr2w1cyx9qmjqmajkvrdbhjx32gqf1d9is003"))))))

Additionally, Guix package definitions can be included in rules in order to extend the udev rules with the definitions found under their lib/udev/rules.d sub-directory. In lieu of the previous file->udev-rule example, we could have used the android-udev-rules package which exists in Guix in the (gnu packages android) module.

The following example shows how to use the android-udev-rules package so that the Android tool adb can detect devices without root privileges. It also details how to create the adbusers group, which is required for the proper functioning of the rules defined within the android-udev-rules package. To create such a group, we must define it both as part of the supplementary-groups of our user-account declaration, as well as in the groups field of the operating-system record.

(use-modules (gnu packages android)  ;for android-udev-rules
             (gnu system shadow)     ;for user-group
             ;; …)

(operating-system
  ;; …
  (users (cons (user-acount
                ;; …
                (supplementary-groups
                 '("adbusers"   ;for adb
                   "wheel" "netdev" "audio" "video"))
                ;; …)))

  (groups (cons (user-group (system? #t) (name "adbusers"))
                %base-groups))

  ;; …

  (services
    (modify-services %desktop-services
      (udev-service-type config =>
       (udev-configuration (inherit config)
       (rules (cons* android-udev-rules
              (udev-configuration-rules config))))))))
Scheme Procedure: urandom-seed-service

Save some entropy in %random-seed-file to seed /dev/urandom when rebooting.

Scheme Variable: %random-seed-file

This is the name of the file where some random bytes are saved by urandom-seed-service to seed /dev/urandom when rebooting. It defaults to /var/lib/random-seed.

Scheme Procedure: console-keymap-service files ...

Return a service to load console keymaps from files using loadkeys command. Most likely, you want to load some default keymap, which can be done like this:

(console-keymap-service "dvorak")

Or, for example, for a Swedish keyboard, you may need to combine the following keymaps:

(console-keymap-service "se-lat6" "se-fi-lat6")

Also you can specify a full file name (or file names) of your keymap(s). See man loadkeys for details.

Scheme Procedure: gpm-service [#:gpm gpm] [#:options]

Run gpm, the general-purpose mouse daemon, with the given command-line options. GPM allows users to use the mouse in the console, notably to select, copy, and paste text. The default value of options uses the ps2 protocol, which works for both USB and PS/2 mice.

This service is not part of %base-services.

Scheme Variable: guix-publish-service-type

This is the service type for guix publish (see Invoking guix publish). Its value must be a guix-configuration object, as described below.

This assumes that /etc/guix already contains a signing key pair as created by guix archive --generate-key (see Invoking guix archive). If that is not the case, the service will fail to start.

Data Type: guix-publish-configuration

Data type representing the configuration of the guix publish service.

guix (default: guix)

The Guix package to use.

port (default: 80)

The TCP port to listen for connections.

host (default: "localhost")

The host (and thus, network interface) to listen to. Use "0.0.0.0" to listen on all the network interfaces.

compression-level (default: 3)

The gzip compression level at which substitutes are compressed. Use 0 to disable compression altogether, and 9 to get the best compression ratio at the expense of increased CPU usage.

nar-path (default: "nar")

The URL path at which “nars” can be fetched. See --nar-path, for details.

cache (default: #f)

When it is #f, disable caching and instead generate archives on demand. Otherwise, this should be the name of a directory—e.g., "/var/cache/guix/publish"—where guix publish caches archives and meta-data ready to be sent. See --cache, for more information on the tradeoffs involved.

workers (default: #f)

When it is an integer, this is the number of worker threads used for caching; when #f, the number of processors is used. See --workers, for more information.

ttl (default: #f)

When it is an integer, this denotes the time-to-live of the published archives. See --ttl, for more information.

Scheme Procedure: rngd-service [#:rng-tools rng-tools] [#:device "/dev/hwrng"]

Return a service that runs the rngd program from rng-tools to add device to the kernel’s entropy pool. The service will fail if device does not exist.

Scheme Procedure: pam-limits-service [#:limits '()]

Return a service that installs a configuration file for the pam_limits module. The procedure optionally takes a list of pam-limits-entry values, which can be used to specify ulimit limits and nice priority limits to user sessions.

The following limits definition sets two hard and soft limits for all login sessions of users in the realtime group:

(pam-limits-service
 (list
  (pam-limits-entry "@realtime" 'both 'rtprio 99)
  (pam-limits-entry "@realtime" 'both 'memlock 'unlimited)))

The first entry increases the maximum realtime priority for non-privileged processes; the second entry lifts any restriction of the maximum address space that can be locked in memory. These settings are commonly used for real-time audio systems.


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