13.3.5 Managing User Daemons

The (gnu home services shepherd) module supports the definitions of per-user Shepherd services (see Introduction in The GNU Shepherd Manual). You extend home-shepherd-service-type with new services; Guix Home then takes care of starting the shepherd daemon for you when you log in, which in turns starts the services you asked for.

Variable: home-shepherd-service-type

The service type for the userland Shepherd, which allows one to manage long-running processes or one-shot tasks. User’s Shepherd is not an init process (PID 1), but almost all other information described in (see Servicios de Shepherd) is applicable here too.

This is the service type that extensions target when they want to create shepherd services (see Tipos de servicios y servicios, for an example). Each extension must pass a list of <shepherd-service>. Its value must be a home-shepherd-configuration, as described below.

Data Type: home-shepherd-configuration

This data type represents the Shepherd’s configuration.

shepherd (default: shepherd)

The Shepherd package to use.

auto-start? (default: #t)

Whether or not to start Shepherd on first login.

daemonize? (default: #t)

Whether or not to run Shepherd in the background.

silent? (default: #t)

When true, the shepherd process does not write anything to standard output when started automatically.

services (default: '())

A list of <shepherd-service> to start. You should probably use the service extension mechanism instead (see Servicios de Shepherd).

The Shepherd allows you to define timers, a special type of service that performs a given task periodically. Just like you can define timers at the system level (see Ejecución de tareas programadas), you can do so in your home environment.

The example below defines a home environment where a Shepherd timer runs the mkid command twice per day (see mkid invocation in ID Database Utilities). It does so by extending home-shepherd-service-type with simple-service; the Shepherd timer itself is produced by the shepherd-timer procedure (see shepherd-timer), which is given the service name, a gexp specifying its schedule, and a gexp specifying the command to run.

(use-modules (gnu) (guix)
             (gnu home services shepherd)
             (gnu packages idutils))

(define idutils-service
  ;; Index my 'doc' directory everyday at 12:15PM and 7:15PM.
  (simple-service
   'update-idutils-database home-shepherd-service-type
   (list (shepherd-timer '(update-idutils-database)
                         #~(calendar-event #:hours '(12 19)
                                           #:minutes '(15))
                         #~(#$(file-append idutils "/bin/mkid")
                            "doc")))))

(home-environment
  ;; …
  (services (append (list idutils-service)
                    %base-home-services)))

See Timers in The GNU Shepherd Manual for more information on Shepherd timers.

The Shepherd also comes with a log rotation service, which compresses and then deletes old log files produced by services and daemons that it runs. This service is made available through home-log-rotation-service-type as described below.

Variable: home-log-rotation-service-type

This is the service type for the user Shepherd log rotation service (see Log Rotation Service in The GNU Shepherd Manual). Its value must be a log-rotation-configuration record, exactly as for its system-wide counterpart. See log-rotation-configuration, for its reference.

This service is part of %base-home-services.

Variable: home-shepherd-transient-service-type

Variable: home-shepherd-timer-service-type

These are the timer and transient Shepherd services. The former lets you schedule command execution for later, while the latter can run commands in the background as a regular service.

See the system timer and transient services, which are their Guix System counterparts, for more info.