@include version.texi
@c Identifier of the OpenPGP key used to sign tarballs and such.
-@set OPENPGP-SIGNING-KEY-ID 090B11993D9AEBB5
+@set OPENPGP-SIGNING-KEY-ID 3CE464558A84FDC69DB40CFB090B11993D9AEBB5
@copying
Copyright @copyright{} 2012, 2013, 2014, 2015, 2016 Ludovic Courtès@*
Copyright @copyright{} 2016 Chris Marusich@*
Copyright @copyright{} 2016 Efraim Flashner@*
Copyright @copyright{} 2016 John Darrington@*
-Copyright @copyright{} 2016 ng0
+Copyright @copyright{} 2016 ng0@*
+Copyright @copyright{} 2016 Jan Nieuwenhuizen@*
+Copyright @copyright{} 2016 Julien Lepiller
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
* Base Services:: Essential system services.
* Scheduled Job Execution:: The mcron service.
+* Log Rotation:: The rottlog service.
* Networking Services:: Network setup, SSH daemon, etc.
* X Window:: Graphical display.
* Desktop Services:: D-Bus and desktop services.
* Database Services:: SQL databases.
* Mail Services:: IMAP, POP3, SMTP, and all that.
* Web Services:: Web servers.
-* Various Services:: Other services.
+* Network File System:: NFS related services.
+* Miscellaneous Services:: Other services.
Defining Services
Another example where @code{propagated-inputs} is useful is for languages
that lack a facility to record the run-time search path akin to the
-@code{RUNPATH} of ELF files; this includes Guile, Python, Perl, GHC, and
+@code{RUNPATH} of ELF files; this includes Guile, Python, Perl, and
more. To ensure that libraries written in those languages can find
library code they depend on at run time, run-time dependencies must be
listed in @code{propagated-inputs} rather than @code{inputs}.
@end defvr
+@defvr {Scheme Variable} asdf-build-system/source
+@defvrx {Scheme Variable} asdf-build-system/sbcl
+@defvrx {Scheme Variable} asdf-build-system/ecl
+
+These variables, exported by @code{(guix build-system asdf)}, implement
+build procedures for Common Lisp packages using
+@url{https://common-lisp.net/project/asdf/, ``ASDF''}. ASDF is a system
+definition facility for Common Lisp programs and libraries.
+
+The @code{asdf-build-system/source} system installs the packages in
+source form, and can be loaded using any common lisp implementation, via
+ASDF. The others, such as @code{asdf-build-system/sbcl}, install binary
+systems in the format which a particular implementation understands.
+These build systems can also be used to produce executable programs, or
+lisp images which contain a set of packages pre-loaded.
+
+The build system uses naming conventions. For binary packages, the
+package itself as well as its run-time dependencies should begin their
+name with the lisp implementation, such as @code{sbcl-} for
+@code{asdf-build-system/sbcl}. Beginning the input name with this
+prefix will allow the build system to encode its location into the
+resulting library, so that the input can be found at run-time.
+
+If dependencies are used only for tests, it is convenient to use a
+different prefix in order to avoid having a run-time dependency on such
+systems. For example,
+
+@example
+(define-public sbcl-bordeaux-threads
+ (package
+ ...
+ (native-inputs `(("tests:cl-fiveam" ,sbcl-fiveam)))
+ ...))
+@end example
+
+Additionally, the corresponding source package should be labeled using
+the same convention as python packages (see @ref{Python Modules}), using
+the @code{cl-} prefix.
+
+For binary packages, each system should be defined as a Guix package.
+If one package @code{origin} contains several systems, package variants
+can be created in order to build all the systems. Source packages,
+which use @code{asdf-build-system/source}, may contain several systems.
+
+In order to create executable programs and images, the build-side
+procedures @code{build-program} and @code{build-image} can be used.
+They should be called in a build phase after the @code{create-symlinks}
+phase, so that the system which was just built can be used within the
+resulting image. @code{build-program} requires a list of Common Lisp
+expressions to be passed as the @code{#:entry-program} argument.
+
+If the system is not defined within its own @code{.asd} file of the same
+name, then the @code{#:asd-file} parameter should be used to specify
+which file the system is defined in.
+
+@end defvr
+
@defvr {Scheme Variable} cmake-build-system
This variable is exported by @code{(guix build-system cmake)}. It
implements the build procedure for packages using the
"-s"
(string-append #$emacs "/bin/emacs")
(string-append #$output "/bin/vi")))
- #:target "mips64el-linux")
+ #:target "mips64el-linux-gnu")
@end example
@noindent
these objects lead to a file in the store. Consider this G-expression:
@example
-#~(system* (string-append #$glibc "/sbin/nscd") "-f"
+#~(system* #$(file-append glibc "/sbin/nscd") "-f"
#$(local-file "/tmp/my-nscd.conf"))
@end example
(use-modules (guix gexp) (gnu packages base))
(gexp->script "list-files"
- #~(execl (string-append #$coreutils "/bin/ls")
+ #~(execl #$(file-append coreutils "/bin/ls")
"ls"))
@end example
@example
#!/gnu/store/@dots{}-guile-2.0.11/bin/guile -ds
!#
-(execl (string-append "/gnu/store/@dots{}-coreutils-8.22"/bin/ls")
- "ls")
+(execl "/gnu/store/@dots{}-coreutils-8.22"/bin/ls" "ls")
@end example
@end deffn
This is the declarative counterpart of @code{text-file*}.
@end deffn
+@deffn {Scheme Procedure} file-append @var{obj} @var{suffix} @dots{}
+Return a file-like object that expands to the concatenation of @var{obj}
+and @var{suffix}, where @var{obj} is a lowerable object and each
+@var{suffix} is a string.
+
+As an example, consider this gexp:
+
+@example
+(gexp->script "run-uname"
+ #~(system* #$(file-append coreutils
+ "/bin/uname")))
+@end example
+
+The same effect could be achieved with:
+
+@example
+(gexp->script "run-uname"
+ #~(system* (string-append #$coreutils
+ "/bin/uname")))
+@end example
+
+There is one difference though: in the @code{file-append} case, the
+resulting script contains the absolute file name as a string, whereas in
+the second case, the resulting script contains a @code{(string-append
+@dots{})} expression to construct the file name @emph{at run time}.
+@end deffn
+
+
Of course, in addition to gexps embedded in ``host'' code, there are
also modules containing build tools. To make it clear that they are
meant to be used in the build stratum, these modules are kept in the
This is implemented using the @code{package-input-rewriting} Scheme
procedure (@pxref{Defining Packages, @code{package-input-rewriting}}).
+
+@item --with-graft=@var{package}=@var{replacement}
+This is similar to @code{--with-input} but with an important difference:
+instead of rebuilding all the dependency chain, @var{replacement} is
+built and then @dfn{grafted} onto the binaries that were initially
+referring to @var{package}. @xref{Security Updates}, for more
+information on grafts.
+
+For example, the command below grafts version 3.5.4 of GnuTLS onto Wget
+and all its dependencies, replacing references to the version of GnuTLS
+they currently refer to:
+
+@example
+guix build --with-graft=gnutls=gnutls@@3.5.4 wget
+@end example
+
+This has the advantage of being much faster than rebuilding everything.
+But there is a caveat: it works if and only if @var{package} and
+@var{replacement} are strictly compatible---for example, if they provide
+a library, the application binary interface (ABI) of those libraries
+must be compatible. If @var{replacement} is somehow incompatible with
+@var{package}, then the resulting package may be unusable. Use with
+care!
+
@end table
@node Additional Build Options
@example
guix graph -t references `readlink -f ~/.guix-profile`
@end example
+
+@item referrers
+This is the graph of the @dfn{referrers} of a store item, as returned by
+@command{guix gc --referrers} (@pxref{Invoking guix gc}).
+
+This relies exclusively on local information from your store. For
+instance, let us suppose that the current Inkscape is available in 10
+profiles on your machine; @command{guix graph -t referrers inkscape}
+will show a graph rooted at Inkscape and with those 10 profiles linked
+to it.
+
+It can help determine what is preventing a store item from being garbage
+collected.
+
@end table
The available options are the following:
(extra-options '("--gc-keep-derivations"))))
(mingetty-service-type config =>
(mingetty-configuration
- (inherit config)
- (motd (plain-file "motd" "Howdy!"))))))
+ (inherit config)))))
(operating-system
;; @dots{}
@menu
* Base Services:: Essential system services.
* Scheduled Job Execution:: The mcron service.
+* Log Rotation:: The rottlog service.
* Networking Services:: Network setup, SSH daemon, etc.
* X Window:: Graphical display.
+* Printing Services:: Local and remote printer support.
* Desktop Services:: D-Bus and desktop services.
* Database Services:: SQL databases.
* Mail Services:: IMAP, POP3, SMTP, and all that.
* Web Services:: Web servers.
-* Various Services:: Other services.
+* Network File System:: NFS related services.
+* Miscellaneous Services:: Other services.
@end menu
@node Base Services
Return a service that sets the host name to @var{name}.
@end deffn
+@deffn {Scheme Procedure} login-service @var{config}
+Return a service to run login according to @var{config}, a
+@code{<login-configuration>} object, which specifies the message of the day,
+among other things.
+@end deffn
+
+@deftp {Data Type} login-configuration
+This is the data type representing the configuration of login.
+
+@table @asis
+
+@item @code{motd}
+A file-like object containing the ``message of the day''.
+
+@item @code{allow-empty-passwords?} (default: @code{#t})
+Allow empty passwords by default so that first-time users can log in when
+the 'root' account has just been created.
+
+@end table
+@end deftp
+
@deffn {Scheme Procedure} mingetty-service @var{config}
Return a service to run mingetty according to @var{config}, a
@code{<mingetty-configuration>} object, which specifies the tty to run, among
@item @code{tty}
The name of the console this Mingetty runs on---e.g., @code{"tty1"}.
-@item @code{motd}
-A file-like object containing the ``message of the day''.
-
@item @code{auto-login} (default: @code{#f})
When true, this field must be a string denoting the user name under
which the system automatically logs in. When it is @code{#f}, a
@end table
@end deftp
+@deffn {Scheme Procedure} kmscon-service-type @var{config}
+Return a service to run @uref{https://www.freedesktop.org/wiki/Software/kmscon,kmscon}
+according to @var{config}, a @code{<kmscon-configuration>} object, which
+specifies the tty to run, among other things.
+@end deffn
+
+@deftp {Data Type} kmscon-configuration
+This is the data type representing the configuration of Kmscon, which
+implements console log-in.
+
+@table @asis
+
+@item @code{virtual-terminal}
+The name of the console this Kmscon runs on---e.g., @code{"tty1"}.
+
+@item @code{login-program} (default: @code{#~(string-append #$shadow "/bin/login")})
+A gexp denoting the name of the log-in program. The default log-in program is
+@command{login} from the Shadow tool suite.
+
+@item @code{login-arguments} (default: @code{'("-p")})
+A list of arguments to pass to @command{login}.
+
+@item @code{hardware-acceleration?} (default: #f)
+Whether to use hardware acceleration.
+
+@item @code{kmscon} (default: @var{kmscon})
+The Kmscon package to use.
+
+@end table
+@end deftp
+
@cindex name service cache daemon
@cindex nscd
@deffn {Scheme Procedure} nscd-service [@var{config}] [#:glibc glibc] @
@end deftp
+@node Log Rotation
+@subsubsection Log Rotation
+
+@cindex rottlog
+@cindex log rotation
+Log files such as those found in @file{/var/log} tend to grow endlessly,
+so it's a good idea to @dfn{rotate} them once in a while---i.e., archive
+their contents in separate files, possibly compressed. The @code{(gnu
+services admin)} module provides an interface to GNU@tie{}Rot[t]log, a
+log rotation tool (@pxref{Top,,, rottlog, GNU Rot[t]log Manual}).
+
+The example below defines an operating system that provides log rotation
+with the default settings.
+
+@lisp
+(use-modules (guix) (gnu))
+(use-service-modules admin mcron)
+(use-package-modules base idutils)
+
+(operating-system
+ ;; @dots{}
+ (services (cons* (mcron-service)
+ (service rottlog-service-type (rottlog-configuration))
+ %base-services)))
+@end lisp
+
+@defvr {Scheme Variable} rottlog-service-type
+This is the type of the Rottlog service, whose value is a
+@code{rottlog-configuration} object.
+
+This service type can define mcron jobs (@pxref{Scheduled Job
+Execution}) to run the rottlog service.
+@end defvr
+
+@deftp {Data Type} rottlog-configuration
+Data type representing the configuration of rottlog.
+
+@table @asis
+@item @code{rottlog} (default: @code{rottlog})
+The Rottlog package to use.
+
+@item @code{rc-file} (default: @code{(file-append rottlog "/etc/rc")})
+The Rottlog configuration file to use (@pxref{Mandatory RC Variables,,,
+rottlog, GNU Rot[t]log Manual}).
+
+@item @code{periodic-rotations} (default: @code{`(("weekly" %default-rotatations))})
+A list of Rottlog period-name/period-config tuples.
+
+For example, taking an example from the Rottlog manual (@pxref{Period
+Related File Examples,,, rottlog, GNU Rot[t]log Manual}), a valid tuple
+might be:
+
+@example
+("daily" ,(plain-file "daily"
+ "\
+ /var/log/apache/* @{
+ storedir apache-archives
+ rotate 6
+ notifempty
+ nocompress
+ @}"))
+@end example
+
+@item @code{jobs}
+This is a list of gexps where each gexp corresponds to an mcron job
+specification (@pxref{Scheduled Job Execution}).
+@end table
+@end deftp
+
+@defvr {Scheme Variable} %default-rotations
+Specifies weekly rotation of @var{%rotated-files} and
+@code{"/var/log/shepherd.log"}.
+@end defvr
+
+@defvr {Scheme Variable} %rotated-files
+The list of syslog-controlled files to be rotated. By default it is:
+@code{'("/var/log/messages" "/var/log/secure")}.
+@end defvr
+
@node Networking Services
@subsubsection Networking Services
@end deffn
@deffn {Scheme Procedure} ntp-service [#:ntp @var{ntp}] @
- [#:servers @var{%ntp-servers}]
+ [#:servers @var{%ntp-servers}] @
+ [#:allow-large-adjustment? #f]
Return a service that runs the daemon from @var{ntp}, the
@uref{http://www.ntp.org, Network Time Protocol package}. The daemon will
keep the system clock synchronized with that of @var{servers}.
+@var{allow-large-adjustment?} determines whether @command{ntpd} is allowed to
+make an initial adjustment of more than 1,000 seconds.
@end deffn
@defvr {Scheme Variable} %ntp-servers
The other options should be self-descriptive.
@end deffn
+@deffn {Scheme Variable} openssh-service-type
+This is the type for the @uref{http://www.openssh.org, OpenSSH} secure
+shell daemon, @command{sshd}. Its value must be an
+@code{openssh-configuration} record as in this example:
+
+@example
+(service openssh-service-type
+ (openssh-configuration
+ (x11-forwarding? #t)
+ (permit-root-login 'without-password)))
+@end example
+
+See below for details about @code{openssh-configuration}.
+@end deffn
+
+@deftp {Data Type} openssh-configuration
+This is the configuration record for OpenSSH's @command{sshd}.
+
+@table @asis
+@item @code{pid-file} (default: @code{"/var/run/sshd.pid"})
+Name of the file where @command{sshd} writes its PID.
+
+@item @code{port-number} (default: @code{22})
+TCP port on which @command{sshd} listens for incoming connections.
+
+@item @code{permit-root-login} (default: @code{#f})
+This field determines whether and when to allow logins as root. If
+@code{#f}, root logins are disallowed; if @code{#t}, they are allowed.
+If it's the symbol @code{'without-password}, then root logins are
+permitted but not with password-based authentication.
+
+@item @code{allow-empty-passwords?} (default: @code{#f})
+When true, users with empty passwords may log in. When false, they may
+not.
+
+@item @code{password-authentication?} (default: @code{#t})
+When true, users may log in with their password. When false, they have
+other authentication methods.
+
+@item @code{public-key-authentication?} (default: @code{#t})
+When true, users may log in using public key authentication. When
+false, users have to use other authentication method.
+
+Authorized public keys are stored in @file{~/.ssh/authorized_keys}.
+This is used only by protocol version 2.
+
+@item @code{rsa-authentication?} (default: @code{#t})
+When true, users may log in using pure RSA authentication. When false,
+users have to use other means of authentication. This is used only by
+protocol 1.
+
+@item @code{x11-forwarding?} (default: @code{#f})
+When true, forwarding of X11 graphical client connections is
+enabled---in other words, @command{ssh} options @option{-X} and
+@option{-Y} will work.
+
+@item @code{protocol-number} (default: @code{2})
+The SSH protocol number to use.
+@end table
+@end deftp
+
@deffn {Scheme Procedure} dropbear-service [@var{config}]
Run the @uref{https://matt.ucc.asn.au/dropbear/dropbear.html,Dropbear SSH
daemon} with the given @var{config}, a @code{<dropbear-configuration>}
@end deffn
-@node Desktop Services
-@subsubsection Desktop Services
+@node Printing Services
+@subsubsection Printing Services
-The @code{(gnu services desktop)} module provides services that are
-usually useful in the context of a ``desktop'' setup---that is, on a
-machine running a graphical display server, possibly with graphical user
-interfaces, etc. It also defines services that provide specific desktop
-environments like GNOME and XFCE.
+The @code{(gnu services cups)} module provides a Guix service definition
+for the CUPS printing service. To add printer support to a GuixSD
+system, add a @code{cups-service} to the operating system definition:
-To simplify things, the module defines a variable containing the set of
-services that users typically expect on a machine with a graphical
-environment and networking:
+@deffn {Scheme Variable} cups-service-type
+The service type for the CUPS print server. Its value should be a valid
+CUPS configuration (see below). For example:
+@example
+(service cups-service-type (cups-configuration))
+@end example
+@end deffn
-@defvr {Scheme Variable} %desktop-services
-This is a list of services that builds upon @var{%base-services} and
-adds or adjusts services for a typical ``desktop'' setup.
+The CUPS configuration controls the basic things about your CUPS
+installation: what interfaces it listens on, what to do if a print job
+fails, how much logging to do, and so on. To actually add a printer,
+you have to visit the @url{http://localhost:631} URL, or use a tool such
+as GNOME's printer configuration services. By default, configuring a
+CUPS service will generate a self-signed certificate if needed, for
+secure connections to the print server.
-In particular, it adds a graphical login manager (@pxref{X Window,
-@code{slim-service}}), screen lockers,
-a network management tool (@pxref{Networking
-Services, @code{wicd-service}}), energy and color management services,
-the @code{elogind} login and seat manager, the Polkit privilege service,
-the GeoClue location service, an NTP client (@pxref{Networking
-Services}), the Avahi daemon, and has the name service switch service
-configured to be able to use @code{nss-mdns} (@pxref{Name Service
-Switch, mDNS}).
-@end defvr
+One way you might want to customize CUPS is to enable or disable the web
+interface. You can do that directly, like this:
-The @var{%desktop-services} variable can be used as the @code{services}
-field of an @code{operating-system} declaration (@pxref{operating-system
-Reference, @code{services}}).
+@example
+(service cups-service-type
+ (cups-configuration
+ (web-interface? #f)))
+@end example
-Additionally, the @code{gnome-desktop-service} and
-@code{xfce-desktop-service} procedures can add GNOME and/or XFCE to a
-system. To ``add GNOME'' means that system-level services like the
-backlight adjustment helpers and the power management utilities are
-added to the system, extending @code{polkit} and @code{dbus}
-appropriately, allowing GNOME to operate with elevated privileges on a
-limited number of special-purpose system interfaces. Additionally,
-adding a service made by @code{gnome-desktop-service} adds the GNOME
-metapackage to the system profile. Likewise, adding the XFCE service
-not only adds the @code{xfce} metapackage to the system profile, but it
-also gives the Thunar file manager the ability to open a ``root-mode''
-file management window, if the user authenticates using the
-administrator's password via the standard polkit graphical interface.
+The available configuration parameters follow. Each parameter
+definition is preceded by its type; for example, @samp{string-list foo}
+indicates that the @code{foo} parameter should be specified as a list of
+strings. There is also a way to specify the configuration as a string,
+if you have an old @code{cupsd.conf} file that you want to port over
+from some other system; see the end for more details.
-@deffn {Scheme Procedure} gnome-desktop-service
-Return a service that adds the @code{gnome} package to the system
-profile, and extends polkit with the actions from
-@code{gnome-settings-daemon}.
-@end deffn
+@c The following documentation was initially generated by
+@c (generate-documentation) in (gnu services cups). Manually maintained
+@c documentation is better, so we shouldn't hesitate to edit below as
+@c needed. However if the change you want to make to this documentation
+@c can be done in an automated way, it's probably easier to change
+@c (generate-documentation) than to make it below and have to deal with
+@c the churn as CUPS updates.
-@deffn {Scheme Procedure} xfce-desktop-service
-Return a service that adds the @code{xfce} package to the system profile,
-and extends polkit with the ability for @code{thunar} to manipulate the
-file system as root from within a user session, after the user has
-authenticated with the administrator's password.
-@end deffn
-Because the GNOME and XFCE desktop services pull in so many packages,
-the default @code{%desktop-services} variable doesn't include either of
-them by default. To add GNOME or XFCE, just @code{cons} them onto
-@code{%desktop-services} in the @code{services} field of your
-@code{operating-system}:
+Available @code{cups-configuration} fields are:
-@example
-(use-modules (gnu))
-(use-service-modules desktop)
-(operating-system
- ...
- ;; cons* adds items to the list given as its last argument.
- (services (cons* (gnome-desktop-service)
- (xfce-desktop-service)
- %desktop-services))
- ...)
-@end example
+@deftypevr {@code{cups-configuration} parameter} package cups
+The CUPS package.
+@end deftypevr
-These desktop environments will then be available as options in the
-graphical login window.
+@deftypevr {@code{cups-configuration} parameter} package-list extensions
+Drivers and other extensions to the CUPS package.
+@end deftypevr
-The actual service definitions included in @code{%desktop-services} and
-provided by @code{(gnu services dbus)} and @code{(gnu services desktop)}
-are described below.
+@deftypevr {@code{cups-configuration} parameter} files-configuration files-configuration
+Configuration of where to write logs, what directories to use for print
+spools, and related privileged configuration parameters.
-@deffn {Scheme Procedure} dbus-service [#:dbus @var{dbus}] [#:services '()]
-Return a service that runs the ``system bus'', using @var{dbus}, with
-support for @var{services}.
+Available @code{files-configuration} fields are:
-@uref{http://dbus.freedesktop.org/, D-Bus} is an inter-process communication
-facility. Its system bus is used to allow system services to communicate
-and to be notified of system-wide events.
+@deftypevr {@code{files-configuration} parameter} log-location access-log
+Defines the access log filename. Specifying a blank filename disables
+access log generation. The value @code{stderr} causes log entries to be
+sent to the standard error file when the scheduler is running in the
+foreground, or to the system log daemon when run in the background. The
+value @code{syslog} causes log entries to be sent to the system log
+daemon. The server name may be included in filenames using the string
+@code{%s}, as in @code{/var/log/cups/%s-access_log}.
-@var{services} must be a list of packages that provide an
-@file{etc/dbus-1/system.d} directory containing additional D-Bus configuration
-and policy files. For example, to allow avahi-daemon to use the system bus,
-@var{services} must be equal to @code{(list avahi)}.
-@end deffn
+Defaults to @samp{"/var/log/cups/access_log"}.
+@end deftypevr
-@deffn {Scheme Procedure} elogind-service [#:config @var{config}]
-Return a service that runs the @code{elogind} login and
-seat management daemon. @uref{https://github.com/andywingo/elogind,
-Elogind} exposes a D-Bus interface that can be used to know which users
-are logged in, know what kind of sessions they have open, suspend the
-system, inhibit system suspend, reboot the system, and other tasks.
+@deftypevr {@code{files-configuration} parameter} file-name cache-dir
+Where CUPS should cache data.
-Elogind handles most system-level power events for a computer, for
-example suspending the system when a lid is closed, or shutting it down
-when the power button is pressed.
+Defaults to @samp{"/var/cache/cups"}.
+@end deftypevr
-The @var{config} keyword argument specifies the configuration for
-elogind, and should be the result of an @code{(elogind-configuration
-(@var{parameter} @var{value})...)} invocation. Available parameters and
-their default values are:
+@deftypevr {@code{files-configuration} parameter} string config-file-perm
+Specifies the permissions for all configuration files that the scheduler
+writes.
+
+Note that the permissions for the printers.conf file are currently
+masked to only allow access from the scheduler user (typically root).
+This is done because printer device URIs sometimes contain sensitive
+authentication information that should not be generally known on the
+system. There is no way to disable this security feature.
+
+Defaults to @samp{"0640"}.
+@end deftypevr
+
+@deftypevr {@code{files-configuration} parameter} log-location error-log
+Defines the error log filename. Specifying a blank filename disables
+access log generation. The value @code{stderr} causes log entries to be
+sent to the standard error file when the scheduler is running in the
+foreground, or to the system log daemon when run in the background. The
+value @code{syslog} causes log entries to be sent to the system log
+daemon. The server name may be included in filenames using the string
+@code{%s}, as in @code{/var/log/cups/%s-error_log}.
+
+Defaults to @samp{"/var/log/cups/error_log"}.
+@end deftypevr
+
+@deftypevr {@code{files-configuration} parameter} string fatal-errors
+Specifies which errors are fatal, causing the scheduler to exit. The
+kind strings are:
@table @code
-@item kill-user-processes?
-@code{#f}
-@item kill-only-users
-@code{()}
-@item kill-exclude-users
-@code{("root")}
-@item inhibit-delay-max-seconds
-@code{5}
-@item handle-power-key
-@code{poweroff}
-@item handle-suspend-key
-@code{suspend}
-@item handle-hibernate-key
+@item none
+No errors are fatal.
+
+@item all
+All of the errors below are fatal.
+
+@item browse
+Browsing initialization errors are fatal, for example failed connections
+to the DNS-SD daemon.
+
+@item config
+Configuration file syntax errors are fatal.
+
+@item listen
+Listen or Port errors are fatal, except for IPv6 failures on the
+loopback or @code{any} addresses.
+
+@item log
+Log file creation or write errors are fatal.
+
+@item permissions
+Bad startup file permissions are fatal, for example shared TLS
+certificate and key files with world-read permissions.
+@end table
+
+Defaults to @samp{"all -browse"}.
+@end deftypevr
+
+@deftypevr {@code{files-configuration} parameter} boolean file-device?
+Specifies whether the file pseudo-device can be used for new printer
+queues. The URI @uref{file:///dev/null} is always allowed.
+
+Defaults to @samp{#f}.
+@end deftypevr
+
+@deftypevr {@code{files-configuration} parameter} string group
+Specifies the group name or ID that will be used when executing external
+programs.
+
+Defaults to @samp{"lp"}.
+@end deftypevr
+
+@deftypevr {@code{files-configuration} parameter} string log-file-perm
+Specifies the permissions for all log files that the scheduler writes.
+
+Defaults to @samp{"0644"}.
+@end deftypevr
+
+@deftypevr {@code{files-configuration} parameter} log-location page-log
+Defines the page log filename. Specifying a blank filename disables
+access log generation. The value @code{stderr} causes log entries to be
+sent to the standard error file when the scheduler is running in the
+foreground, or to the system log daemon when run in the background. The
+value @code{syslog} causes log entries to be sent to the system log
+daemon. The server name may be included in filenames using the string
+@code{%s}, as in @code{/var/log/cups/%s-page_log}.
+
+Defaults to @samp{"/var/log/cups/page_log"}.
+@end deftypevr
+
+@deftypevr {@code{files-configuration} parameter} string remote-root
+Specifies the username that is associated with unauthenticated accesses
+by clients claiming to be the root user. The default is @code{remroot}.
+
+Defaults to @samp{"remroot"}.
+@end deftypevr
+
+@deftypevr {@code{files-configuration} parameter} file-name request-root
+Specifies the directory that contains print jobs and other HTTP request
+data.
+
+Defaults to @samp{"/var/spool/cups"}.
+@end deftypevr
+
+@deftypevr {@code{files-configuration} parameter} sandboxing sandboxing
+Specifies the level of security sandboxing that is applied to print
+filters, backends, and other child processes of the scheduler; either
+@code{relaxed} or @code{strict}. This directive is currently only
+used/supported on macOS.
+
+Defaults to @samp{strict}.
+@end deftypevr
+
+@deftypevr {@code{files-configuration} parameter} file-name server-keychain
+Specifies the location of TLS certificates and private keys. CUPS will
+look for public and private keys in this directory: a @code{.crt} files
+for PEM-encoded certificates and corresponding @code{.key} files for
+PEM-encoded private keys.
+
+Defaults to @samp{"/etc/cups/ssl"}.
+@end deftypevr
+
+@deftypevr {@code{files-configuration} parameter} file-name server-root
+Specifies the directory containing the server configuration files.
+
+Defaults to @samp{"/etc/cups"}.
+@end deftypevr
+
+@deftypevr {@code{files-configuration} parameter} boolean sync-on-close?
+Specifies whether the scheduler calls fsync(2) after writing
+configuration or state files.
+
+Defaults to @samp{#f}.
+@end deftypevr
+
+@deftypevr {@code{files-configuration} parameter} space-separated-string-list system-group
+Specifies the group(s) to use for @code{@@SYSTEM} group authentication.
+@end deftypevr
+
+@deftypevr {@code{files-configuration} parameter} file-name temp-dir
+Specifies the directory where temporary files are stored.
+
+Defaults to @samp{"/var/spool/cups/tmp"}.
+@end deftypevr
+
+@deftypevr {@code{files-configuration} parameter} string user
+Specifies the user name or ID that is used when running external
+programs.
+
+Defaults to @samp{"lp"}.
+@end deftypevr
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} access-log-level access-log-level
+Specifies the logging level for the AccessLog file. The @code{config}
+level logs when printers and classes are added, deleted, or modified and
+when configuration files are accessed or updated. The @code{actions}
+level logs when print jobs are submitted, held, released, modified, or
+canceled, and any of the conditions for @code{config}. The @code{all}
+level logs all requests.
+
+Defaults to @samp{actions}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} boolean auto-purge-jobs?
+Specifies whether to purge job history data automatically when it is no
+longer required for quotas.
+
+Defaults to @samp{#f}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} browse-local-protocols browse-local-protocols
+Specifies which protocols to use for local printer sharing.
+
+Defaults to @samp{dnssd}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} boolean browse-web-if?
+Specifies whether the CUPS web interface is advertised.
+
+Defaults to @samp{#f}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} boolean browsing?
+Specifies whether shared printers are advertised.
+
+Defaults to @samp{#f}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} string classification
+Specifies the security classification of the server. Any valid banner
+name can be used, including "classified", "confidential", "secret",
+"topsecret", and "unclassified", or the banner can be omitted to disable
+secure printing functions.
+
+Defaults to @samp{""}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} boolean classify-override?
+Specifies whether users may override the classification (cover page) of
+individual print jobs using the @code{job-sheets} option.
+
+Defaults to @samp{#f}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} default-auth-type default-auth-type
+Specifies the default type of authentication to use.
+
+Defaults to @samp{Basic}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} default-encryption default-encryption
+Specifies whether encryption will be used for authenticated requests.
+
+Defaults to @samp{Required}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} string default-language
+Specifies the default language to use for text and web content.
+
+Defaults to @samp{"en"}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} string default-paper-size
+Specifies the default paper size for new print queues. @samp{"Auto"}
+uses a locale-specific default, while @samp{"None"} specifies there is
+no default paper size. Specific size names are typically
+@samp{"Letter"} or @samp{"A4"}.
+
+Defaults to @samp{"Auto"}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} string default-policy
+Specifies the default access policy to use.
+
+Defaults to @samp{"default"}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} boolean default-shared?
+Specifies whether local printers are shared by default.
+
+Defaults to @samp{#t}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer dirty-clean-interval
+Specifies the delay for updating of configuration and state files, in
+seconds. A value of 0 causes the update to happen as soon as possible,
+typically within a few milliseconds.
+
+Defaults to @samp{30}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} error-policy error-policy
+Specifies what to do when an error occurs. Possible values are
+@code{abort-job}, which will discard the failed print job;
+@code{retry-job}, which will retry the job at a later time;
+@code{retry-this-job}, which retries the failed job immediately; and
+@code{stop-printer}, which stops the printer.
+
+Defaults to @samp{stop-printer}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer filter-limit
+Specifies the maximum cost of filters that are run concurrently, which
+can be used to minimize disk, memory, and CPU resource problems. A
+limit of 0 disables filter limiting. An average print to a
+non-PostScript printer needs a filter limit of about 200. A PostScript
+printer needs about half that (100). Setting the limit below these
+thresholds will effectively limit the scheduler to printing a single job
+at any time.
+
+Defaults to @samp{0}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer filter-nice
+Specifies the scheduling priority of filters that are run to print a
+job. The nice value ranges from 0, the highest priority, to 19, the
+lowest priority.
+
+Defaults to @samp{0}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} host-name-lookups host-name-lookups
+Specifies whether to do reverse lookups on connecting clients. The
+@code{double} setting causes @code{cupsd} to verify that the hostname
+resolved from the address matches one of the addresses returned for that
+hostname. Double lookups also prevent clients with unregistered
+addresses from connecting to your server. Only set this option to
+@code{#t} or @code{double} if absolutely required.
+
+Defaults to @samp{#f}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer job-kill-delay
+Specifies the number of seconds to wait before killing the filters and
+backend associated with a canceled or held job.
+
+Defaults to @samp{30}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer job-retry-interval
+Specifies the interval between retries of jobs in seconds. This is
+typically used for fax queues but can also be used with normal print
+queues whose error policy is @code{retry-job} or
+@code{retry-current-job}.
+
+Defaults to @samp{30}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer job-retry-limit
+Specifies the number of retries that are done for jobs. This is
+typically used for fax queues but can also be used with normal print
+queues whose error policy is @code{retry-job} or
+@code{retry-current-job}.
+
+Defaults to @samp{5}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} boolean keep-alive?
+Specifies whether to support HTTP keep-alive connections.
+
+Defaults to @samp{#t}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer keep-alive-timeout
+Specifies how long an idle client connection remains open, in seconds.
+
+Defaults to @samp{30}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer limit-request-body
+Specifies the maximum size of print files, IPP requests, and HTML form
+data. A limit of 0 disables the limit check.
+
+Defaults to @samp{0}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} multiline-string-list listen
+Listens on the specified interfaces for connections. Valid values are
+of the form @var{address}:@var{port}, where @var{address} is either an
+IPv6 address enclosed in brackets, an IPv4 address, or @code{*} to
+indicate all addresses. Values can also be file names of local UNIX
+domain sockets. The Listen directive is similar to the Port directive
+but allows you to restrict access to specific interfaces or networks.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer listen-back-log
+Specifies the number of pending connections that will be allowed. This
+normally only affects very busy servers that have reached the MaxClients
+limit, but can also be triggered by large numbers of simultaneous
+connections. When the limit is reached, the operating system will
+refuse additional connections until the scheduler can accept the pending
+ones.
+
+Defaults to @samp{128}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} location-access-control-list location-access-controls
+Specifies a set of additional access controls.
+
+Available @code{location-access-controls} fields are:
+
+@deftypevr {@code{location-access-controls} parameter} file-name path
+Specifies the URI path to which the access control applies.
+@end deftypevr
+
+@deftypevr {@code{location-access-controls} parameter} access-control-list access-controls
+Access controls for all access to this path, in the same format as the
+@code{access-controls} of @code{operation-access-control}.
+
+Defaults to @samp{()}.
+@end deftypevr
+
+@deftypevr {@code{location-access-controls} parameter} method-access-control-list method-access-controls
+Access controls for method-specific access to this path.
+
+Defaults to @samp{()}.
+
+Available @code{method-access-controls} fields are:
+
+@deftypevr {@code{method-access-controls} parameter} boolean reverse?
+If @code{#t}, apply access controls to all methods except the listed
+methods. Otherwise apply to only the listed methods.
+
+Defaults to @samp{#f}.
+@end deftypevr
+
+@deftypevr {@code{method-access-controls} parameter} method-list methods
+Methods to which this access control applies.
+
+Defaults to @samp{()}.
+@end deftypevr
+
+@deftypevr {@code{method-access-controls} parameter} access-control-list access-controls
+Access control directives, as a list of strings. Each string should be
+one directive, such as "Order allow,deny".
+
+Defaults to @samp{()}.
+@end deftypevr
+@end deftypevr
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer log-debug-history
+Specifies the number of debugging messages that are retained for logging
+if an error occurs in a print job. Debug messages are logged regardless
+of the LogLevel setting.
+
+Defaults to @samp{100}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} log-level log-level
+Specifies the level of logging for the ErrorLog file. The value
+@code{none} stops all logging while @code{debug2} logs everything.
+
+Defaults to @samp{info}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} log-time-format log-time-format
+Specifies the format of the date and time in the log files. The value
+@code{standard} logs whole seconds while @code{usecs} logs microseconds.
+
+Defaults to @samp{standard}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-clients
+Specifies the maximum number of simultaneous clients that are allowed by
+the scheduler.
+
+Defaults to @samp{100}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-clients-per-host
+Specifies the maximum number of simultaneous clients that are allowed
+from a single address.
+
+Defaults to @samp{100}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-copies
+Specifies the maximum number of copies that a user can print of each
+job.
+
+Defaults to @samp{9999}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-hold-time
+Specifies the maximum time a job may remain in the @code{indefinite}
+hold state before it is canceled. A value of 0 disables cancellation of
+held jobs.
+
+Defaults to @samp{0}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs
+Specifies the maximum number of simultaneous jobs that are allowed. Set
+to 0 to allow an unlimited number of jobs.
+
+Defaults to @samp{500}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs-per-printer
+Specifies the maximum number of simultaneous jobs that are allowed per
+printer. A value of 0 allows up to MaxJobs jobs per printer.
+
+Defaults to @samp{0}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs-per-user
+Specifies the maximum number of simultaneous jobs that are allowed per
+user. A value of 0 allows up to MaxJobs jobs per user.
+
+Defaults to @samp{0}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-job-time
+Specifies the maximum time a job may take to print before it is
+canceled, in seconds. Set to 0 to disable cancellation of "stuck" jobs.
+
+Defaults to @samp{10800}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-log-size
+Specifies the maximum size of the log files before they are rotated, in
+bytes. The value 0 disables log rotation.
+
+Defaults to @samp{1048576}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer multiple-operation-timeout
+Specifies the maximum amount of time to allow between files in a
+multiple file print job, in seconds.
+
+Defaults to @samp{300}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} string page-log-format
+Specifies the format of PageLog lines. Sequences beginning with percent
+(@samp{%}) characters are replaced with the corresponding information,
+while all other characters are copied literally. The following percent
+sequences are recognized:
+
+@table @samp
+@item %%
+insert a single percent character
+
+@item %@{name@}
+insert the value of the specified IPP attribute
+
+@item %C
+insert the number of copies for the current page
+
+@item %P
+insert the current page number
+
+@item %T
+insert the current date and time in common log format
+
+@item %j
+insert the job ID
+
+@item %p
+insert the printer name
+
+@item %u
+insert the username
+@end table
+
+A value of the empty string disables page logging. The string @code{%p
+%u %j %T %P %C %@{job-billing@} %@{job-originating-host-name@}
+%@{job-name@} %@{media@} %@{sides@}} creates a page log with the
+standard items.
+
+Defaults to @samp{""}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} environment-variables environment-variables
+Passes the specified environment variable(s) to child processes; a list
+of strings.
+
+Defaults to @samp{()}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} policy-configuration-list policies
+Specifies named access control policies.
+
+Available @code{policy-configuration} fields are:
+
+@deftypevr {@code{policy-configuration} parameter} string name
+Name of the policy.
+@end deftypevr
+
+@deftypevr {@code{policy-configuration} parameter} string job-private-access
+Specifies an access list for a job's private values. @code{@@ACL} maps
+to the printer's requesting-user-name-allowed or
+requesting-user-name-denied values. @code{@@OWNER} maps to the job's
+owner. @code{@@SYSTEM} maps to the groups listed for the
+@code{system-group} field of the @code{files-config} configuration,
+which is reified into the @code{cups-files.conf(5)} file. Other
+possible elements of the access list include specific user names, and
+@code{@@@var{group}} to indicate members of a specific group. The
+access list may also be simply @code{all} or @code{default}.
+
+Defaults to @samp{"@@OWNER @@SYSTEM"}.
+@end deftypevr
+
+@deftypevr {@code{policy-configuration} parameter} string job-private-values
+Specifies the list of job values to make private, or @code{all},
+@code{default}, or @code{none}.
+
+Defaults to @samp{"job-name job-originating-host-name
+job-originating-user-name phone"}.
+@end deftypevr
+
+@deftypevr {@code{policy-configuration} parameter} string subscription-private-access
+Specifies an access list for a subscription's private values.
+@code{@@ACL} maps to the printer's requesting-user-name-allowed or
+requesting-user-name-denied values. @code{@@OWNER} maps to the job's
+owner. @code{@@SYSTEM} maps to the groups listed for the
+@code{system-group} field of the @code{files-config} configuration,
+which is reified into the @code{cups-files.conf(5)} file. Other
+possible elements of the access list include specific user names, and
+@code{@@@var{group}} to indicate members of a specific group. The
+access list may also be simply @code{all} or @code{default}.
+
+Defaults to @samp{"@@OWNER @@SYSTEM"}.
+@end deftypevr
+
+@deftypevr {@code{policy-configuration} parameter} string subscription-private-values
+Specifies the list of job values to make private, or @code{all},
+@code{default}, or @code{none}.
+
+Defaults to @samp{"notify-events notify-pull-method notify-recipient-uri
+notify-subscriber-user-name notify-user-data"}.
+@end deftypevr
+
+@deftypevr {@code{policy-configuration} parameter} operation-access-control-list access-controls
+Access control by IPP operation.
+
+Defaults to @samp{()}.
+@end deftypevr
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} boolean-or-non-negative-integer preserve-job-files
+Specifies whether job files (documents) are preserved after a job is
+printed. If a numeric value is specified, job files are preserved for
+the indicated number of seconds after printing. Otherwise a boolean
+value applies indefinitely.
+
+Defaults to @samp{86400}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} boolean-or-non-negative-integer preserve-job-history
+Specifies whether the job history is preserved after a job is printed.
+If a numeric value is specified, the job history is preserved for the
+indicated number of seconds after printing. If @code{#t}, the job
+history is preserved until the MaxJobs limit is reached.
+
+Defaults to @samp{#t}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer reload-timeout
+Specifies the amount of time to wait for job completion before
+restarting the scheduler.
+
+Defaults to @samp{30}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} string rip-cache
+Specifies the maximum amount of memory to use when converting documents
+into bitmaps for a printer.
+
+Defaults to @samp{"128m"}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} string server-admin
+Specifies the email address of the server administrator.
+
+Defaults to @samp{"root@@localhost.localdomain"}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} host-name-list-or-* server-alias
+The ServerAlias directive is used for HTTP Host header validation when
+clients connect to the scheduler from external interfaces. Using the
+special name @code{*} can expose your system to known browser-based DNS
+rebinding attacks, even when accessing sites through a firewall. If the
+auto-discovery of alternate names does not work, we recommend listing
+each alternate name with a ServerAlias directive instead of using
+@code{*}.
+
+Defaults to @samp{*}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} string server-name
+Specifies the fully-qualified host name of the server.
+
+Defaults to @samp{"localhost"}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} server-tokens server-tokens
+Specifies what information is included in the Server header of HTTP
+responses. @code{None} disables the Server header. @code{ProductOnly}
+reports @code{CUPS}. @code{Major} reports @code{CUPS 2}. @code{Minor}
+reports @code{CUPS 2.0}. @code{Minimal} reports @code{CUPS 2.0.0}.
+@code{OS} reports @code{CUPS 2.0.0 (@var{uname})} where @var{uname} is
+the output of the @code{uname} command. @code{Full} reports @code{CUPS
+2.0.0 (@var{uname}) IPP/2.0}.
+
+Defaults to @samp{Minimal}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} string set-env
+Set the specified environment variable to be passed to child processes.
+
+Defaults to @samp{"variable value"}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} multiline-string-list ssl-listen
+Listens on the specified interfaces for encrypted connections. Valid
+values are of the form @var{address}:@var{port}, where @var{address} is
+either an IPv6 address enclosed in brackets, an IPv4 address, or
+@code{*} to indicate all addresses.
+
+Defaults to @samp{()}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} ssl-options ssl-options
+Sets encryption options. By default, CUPS only supports encryption
+using TLS v1.0 or higher using known secure cipher suites. The
+@code{AllowRC4} option enables the 128-bit RC4 cipher suites, which are
+required for some older clients that do not implement newer ones. The
+@code{AllowSSL3} option enables SSL v3.0, which is required for some
+older clients that do not support TLS v1.0.
+
+Defaults to @samp{()}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} boolean strict-conformance?
+Specifies whether the scheduler requires clients to strictly adhere to
+the IPP specifications.
+
+Defaults to @samp{#f}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer timeout
+Specifies the HTTP request timeout, in seconds.
+
+Defaults to @samp{300}.
+
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} boolean web-interface?
+Specifies whether the web interface is enabled.
+
+Defaults to @samp{#f}.
+@end deftypevr
+
+At this point you're probably thinking ``oh dear, Guix manual, I like
+you but you can stop already with the configuration options''. Indeed.
+However, one more point: it could be that you have an existing
+@code{cupsd.conf} that you want to use. In that case, you can pass an
+@code{opaque-cups-configuration} as the configuration of a
+@code{cups-service-type}.
+
+Available @code{opaque-cups-configuration} fields are:
+
+@deftypevr {@code{opaque-cups-configuration} parameter} package cups
+The CUPS package.
+@end deftypevr
+
+@deftypevr {@code{opaque-cups-configuration} parameter} string cupsd.conf
+The contents of the @code{cupsd.conf}, as a string.
+@end deftypevr
+
+@deftypevr {@code{opaque-cups-configuration} parameter} string cups-files.conf
+The contents of the @code{cups-files.conf} file, as a string.
+@end deftypevr
+
+For example, if your @code{cupsd.conf} and @code{cups-files.conf} are in
+strings of the same name, you could instantiate a CUPS service like
+this:
+
+@example
+(service cups-service-type
+ (opaque-cups-configuration
+ (cupsd.conf cupsd.conf)
+ (cups-files.conf cups-files.conf)))
+@end example
+
+
+@node Desktop Services
+@subsubsection Desktop Services
+
+The @code{(gnu services desktop)} module provides services that are
+usually useful in the context of a ``desktop'' setup---that is, on a
+machine running a graphical display server, possibly with graphical user
+interfaces, etc. It also defines services that provide specific desktop
+environments like GNOME and XFCE.
+
+To simplify things, the module defines a variable containing the set of
+services that users typically expect on a machine with a graphical
+environment and networking:
+
+@defvr {Scheme Variable} %desktop-services
+This is a list of services that builds upon @var{%base-services} and
+adds or adjusts services for a typical ``desktop'' setup.
+
+In particular, it adds a graphical login manager (@pxref{X Window,
+@code{slim-service}}), screen lockers,
+a network management tool (@pxref{Networking
+Services, @code{wicd-service}}), energy and color management services,
+the @code{elogind} login and seat manager, the Polkit privilege service,
+the GeoClue location service, an NTP client (@pxref{Networking
+Services}), the Avahi daemon, and has the name service switch service
+configured to be able to use @code{nss-mdns} (@pxref{Name Service
+Switch, mDNS}).
+@end defvr
+
+The @var{%desktop-services} variable can be used as the @code{services}
+field of an @code{operating-system} declaration (@pxref{operating-system
+Reference, @code{services}}).
+
+Additionally, the @code{gnome-desktop-service} and
+@code{xfce-desktop-service} procedures can add GNOME and/or XFCE to a
+system. To ``add GNOME'' means that system-level services like the
+backlight adjustment helpers and the power management utilities are
+added to the system, extending @code{polkit} and @code{dbus}
+appropriately, allowing GNOME to operate with elevated privileges on a
+limited number of special-purpose system interfaces. Additionally,
+adding a service made by @code{gnome-desktop-service} adds the GNOME
+metapackage to the system profile. Likewise, adding the XFCE service
+not only adds the @code{xfce} metapackage to the system profile, but it
+also gives the Thunar file manager the ability to open a ``root-mode''
+file management window, if the user authenticates using the
+administrator's password via the standard polkit graphical interface.
+
+@deffn {Scheme Procedure} gnome-desktop-service
+Return a service that adds the @code{gnome} package to the system
+profile, and extends polkit with the actions from
+@code{gnome-settings-daemon}.
+@end deffn
+
+@deffn {Scheme Procedure} xfce-desktop-service
+Return a service that adds the @code{xfce} package to the system profile,
+and extends polkit with the ability for @code{thunar} to manipulate the
+file system as root from within a user session, after the user has
+authenticated with the administrator's password.
+@end deffn
+
+Because the GNOME and XFCE desktop services pull in so many packages,
+the default @code{%desktop-services} variable doesn't include either of
+them by default. To add GNOME or XFCE, just @code{cons} them onto
+@code{%desktop-services} in the @code{services} field of your
+@code{operating-system}:
+
+@example
+(use-modules (gnu))
+(use-service-modules desktop)
+(operating-system
+ ...
+ ;; cons* adds items to the list given as its last argument.
+ (services (cons* (gnome-desktop-service)
+ (xfce-desktop-service)
+ %desktop-services))
+ ...)
+@end example
+
+These desktop environments will then be available as options in the
+graphical login window.
+
+The actual service definitions included in @code{%desktop-services} and
+provided by @code{(gnu services dbus)} and @code{(gnu services desktop)}
+are described below.
+
+@deffn {Scheme Procedure} dbus-service [#:dbus @var{dbus}] [#:services '()]
+Return a service that runs the ``system bus'', using @var{dbus}, with
+support for @var{services}.
+
+@uref{http://dbus.freedesktop.org/, D-Bus} is an inter-process communication
+facility. Its system bus is used to allow system services to communicate
+and to be notified of system-wide events.
+
+@var{services} must be a list of packages that provide an
+@file{etc/dbus-1/system.d} directory containing additional D-Bus configuration
+and policy files. For example, to allow avahi-daemon to use the system bus,
+@var{services} must be equal to @code{(list avahi)}.
+@end deffn
+
+@deffn {Scheme Procedure} elogind-service [#:config @var{config}]
+Return a service that runs the @code{elogind} login and
+seat management daemon. @uref{https://github.com/andywingo/elogind,
+Elogind} exposes a D-Bus interface that can be used to know which users
+are logged in, know what kind of sessions they have open, suspend the
+system, inhibit system suspend, reboot the system, and other tasks.
+
+Elogind handles most system-level power events for a computer, for
+example suspending the system when a lid is closed, or shutting it down
+when the power button is pressed.
+
+The @var{config} keyword argument specifies the configuration for
+elogind, and should be the result of an @code{(elogind-configuration
+(@var{parameter} @var{value})...)} invocation. Available parameters and
+their default values are:
+
+@table @code
+@item kill-user-processes?
+@code{#f}
+@item kill-only-users
+@code{()}
+@item kill-exclude-users
+@code{("root")}
+@item inhibit-delay-max-seconds
+@code{5}
+@item handle-power-key
+@code{poweroff}
+@item handle-suspend-key
+@code{suspend}
+@item handle-hibernate-key
@code{hibernate}
@item handle-lid-switch
@code{suspend}
@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} boolean mail-full-filesystem-access?
-Allow full filesystem access to clients. There's no access checks
+Allow full file system access to clients. There's no access checks
other than what the operating system does for the active UID/GID. It
works with both maildir and mboxes, allowing you to prefix mailboxes
names with e.g. /path/ or ~user/.
@deftypevr {@code{dovecot-configuration} parameter} boolean mmap-disable?
Don't use mmap() at all. This is required if you store indexes to
-shared filesystems (NFS or clustered filesystem).
+shared file systems (NFS or clustered file system).
Defaults to @samp{#f}.
@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} boolean mdbox-preallocate-space?
When creating new mdbox files, immediately preallocate their size to
@samp{mdbox-rotate-size}. This setting currently works only in Linux
-with some filesystems (ext4, xfs).
+with some file systems (ext4, xfs).
Defaults to @samp{#f}.
@end deftypevr
@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-fs
-Filesystem backend to use for saving attachments:
+File system backend to use for saving attachments:
@table @code
@item posix
No SiS done by Dovecot (but this might help FS's own deduplication)
@deftypevr {@code{dovecot-configuration} parameter} string postmaster-address
Address to use when sending rejection mails.
-Default is postmaster@@<your domain>. %d expands to recipient domain.
-Defaults to @samp{""}.
+%d expands to recipient domain.
+Defaults to @samp{"postmaster@@%d"}.
@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string hostname
@deffn {Scheme Procedure} nginx-service [#:nginx nginx] @
[#:log-directory ``/var/log/nginx''] @
[#:run-directory ``/var/run/nginx''] @
+ [#:vhost-list (list (nginx-vhost-configuration))] @
[#:config-file]
Return a service that runs @var{nginx}, the nginx web server.
arguments should match what is in @var{config-file} to ensure that the
directories are created when the service is activated.
+As an alternative to using a @var{config-file}, @var{vhost-list} can be
+used to specify the list of @dfn{virtual hosts} required on the host. For
+this to work, use the default value for @var{config-file}.
+
@end deffn
-@node Various Services
-@subsubsection Various Services
+@deftp {Data Type} nginx-vhost-configuration
+Data type representing the configuration of an nginx virtual host.
+This type has the following parameters:
+
+@table @asis
+@item @code{http-port} (default: @code{80})
+Nginx will listen for HTTP connection on this port. Set it at @code{#f} if
+nginx should not listen for HTTP (non secure) connection for this
+@dfn{virtual host}.
+
+@item @code{https-port} (default: @code{443})
+Nginx will listen for HTTPS connection on this port. Set it at @code{#f} if
+nginx should not listen for HTTPS (secure) connection for this @dfn{virtual host}.
+
+Note that nginx can listen for HTTP and HTTPS connections in the same
+@dfn{virtual host}.
+
+@item @code{server-name} (default: @code{(list 'default)})
+A list of server names this vhost represents. @code{'default} represents the
+default vhost for connections matching no other vhost.
+
+@item @code{root} (default: @code{"/srv/http"})
+Root of the website nginx will serve.
+
+@item @code{index} (default: @code{(list "index.html")})
+Index files to look for when clients ask for a directory. If it cannot be found,
+Nginx will send the list of files in the directory.
+
+@item @code{ssl-certificate} (default: @code{"/etc/nginx/cert.pem"})
+Where to find the certificate for secure connections. Set it to @code{#f} if
+you don't have a certificate or you don't want to use HTTPS.
+
+@item @code{ssl-certificate-key} (default: @code{"/etc/nginx/key.pem"})
+Where to find the private key for secure connections. Set it to @code{#f} if
+you don't have a key or you don't want to use HTTPS.
+
+@item @code{server-tokens?} (default: @code{#f})
+Whether the server should add its configuration to response.
+@end table
+@end deftp
+
+@node Network File System
+@subsubsection Network File System
+@cindex NFS
+
+The @code{(gnu services nfs)} module provides the following services,
+which are most commonly used in relation to mounting or exporting
+directory trees as @dfn{network file systems} (NFS).
@subsubheading RPC Bind Service
@cindex rpcbind
-The @code{(gnu services nfs)} module provides the following:
+The RPC Bind service provides a facility to map program numbers into
+universal addresses.
+Many NFS related services use this facility. Hence it is automatically
+started when a dependent service starts.
@defvr {Scheme Variable} rpcbind-service-type
A service type for the RPC portmapper daemon.
@end table
@end deftp
+
+@subsubheading Pipefs Pseudo File System
+@cindex pipefs
+@cindex rpc_pipefs
+
+The pipefs file system is used to transfer NFS related data
+between the kernel and user space programs.
+
+@defvr {Scheme Variable} pipefs-service-type
+A service type for the pipefs pseudo file system.
+@end defvr
+
+@deftp {Data Type} pipefs-configuration
+Data type representing the configuration of the pipefs pseudo file system service.
+This type has the following parameters:
+@table @asis
+@item @code{mount-point} (default: @code{"/var/lib/nfs/rpc_pipefs"})
+The directory to which the file system is to be attached.
+@end table
+@end deftp
+
+
+@subsubheading GSS Daemon Service
+@cindex GSSD
+@cindex GSS
+@cindex global security system
+
+The @dfn{global security system} (GSS) daemon provides strong security for RPC
+based protocols.
+Before exchanging RPC requests an RPC client must establish a security
+context. Typically this is done using the Kerberos command @command{kinit}
+or automatically at login time using PAM services.
+
+@defvr {Scheme Variable} gss-service-type
+A service type for the Global Security System (GSS) daemon.
+@end defvr
+
+@deftp {Data Type} gss-configuration
+Data type representing the configuration of the GSS daemon service.
+This type has the following parameters:
+@table @asis
+@item @code{nfs-utils} (default: @code{nfs-utils})
+The package in which the @command{rpc.gssd} command is to be found.
+
+@item @code{pipefs-directory} (default: @code{"/var/lib/nfs/rpc_pipefs"})
+The directory where the pipefs file system is mounted.
+
+@end table
+@end deftp
+
+
+@subsubheading IDMAP Daemon Service
+@cindex idmapd
+@cindex name mapper
+
+The idmap daemon service provides mapping between user IDs and user names.
+Typically it is required in order to access file systems mounted via NFSv4.
+
+@defvr {Scheme Variable} idmap-service-type
+A service type for the Identity Mapper (IDMAP) daemon.
+@end defvr
+
+@deftp {Data Type} idmap-configuration
+Data type representing the configuration of the IDMAP daemon service.
+This type has the following parameters:
+@table @asis
+@item @code{nfs-utils} (default: @code{nfs-utils})
+The package in which the @command{rpc.idmapd} command is to be found.
+
+@item @code{pipefs-directory} (default: @code{"/var/lib/nfs/rpc_pipefs"})
+The directory where the pipefs file system is mounted.
+
+@item @code{domain} (default: @code{#f})
+The local NFSv4 domain name.
+This must be a string or @code{#f}.
+If it is @code{#f} then the daemon will use the host's fully qualified domain name.
+
+@end table
+@end deftp
+
+
+@node Miscellaneous Services
+@subsubsection Miscellaneous Services
+
+
@cindex lirc
@subsubheading Lirc Service
@end deftp
+@cindex dual boot
+@cindex boot menu
Should you want to list additional boot menu entries @i{via} the
@code{menu-entries} field above, you will need to create them with the
-@code{menu-entry} form:
+@code{menu-entry} form. For example, imagine you want to be able to
+boot another distro (hard to imagine!), you can define a menu entry
+along these lines:
+
+@example
+(menu-entry
+ (label "The Other Distro")
+ (linux "/boot/old/vmlinux-2.6.32")
+ (linux-arguments '("root=/dev/sda2"))
+ (initrd "/boot/old/initrd"))
+@end example
+
+Details below.
@deftp {Data Type} menu-entry
The type of an entry in the GRUB boot menu.
The label to show in the menu---e.g., @code{"GNU"}.
@item @code{linux}
-The Linux kernel to boot.
+The Linux kernel image to boot, for example:
+
+@example
+(file-append linux-libre "/bzImage")
+@end example
@item @code{linux-arguments} (default: @code{()})
The list of extra Linux kernel command-line arguments---e.g.,
Return true if @var{obj} is a service extension.
@end deffn
+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 @code{simple-service} procedure
+provides a shorthand for this.
+
+@deffn {Scheme Procedure} simple-service @var{name} @var{target} @var{value}
+Return a service that extends @var{target} with @var{value}. This works
+by creating a singleton service type @var{name}, of which the returned
+service is an instance.
+
+For example, this extends mcron (@pxref{Scheduled Job Execution}) with
+an additional job:
+
+@example
+(simple-service 'my-mcron-job mcron-service-type
+ #~(job '(next-hour (3)) "guix gc -F 2G"))
+@end example
+@end deffn
+
At the core of the service abstraction lies the @code{fold-services}
procedure, which is responsible for ``compiling'' a list of services
down to a single directory that contains everything needed to boot and
recursive: when an indirect dependency requires grafting, then grafting
``propagates'' up to the package that the user is installing.
-Currently, the graft and the package it replaces (@var{bash-fixed} and
-@var{bash} in the example above) must have the exact same @code{name}
-and @code{version} fields. This restriction mostly comes from the fact
-that grafting works by patching files, including binary files, directly.
+Currently, the length of the name and version of the graft and that of
+the package it replaces (@var{bash-fixed} and @var{bash} in the example
+above) must be equal. This restriction mostly comes from the fact that
+grafting works by patching files, including binary files, directly.
Other restrictions may apply: for instance, when adding a graft to a
package providing a shared library, the original shared library and its
replacement must have the same @code{SONAME} and be binary-compatible.
described above.
+@subsubsection Specifying Dependencies
+@cindex inputs, for Python packages
+
+Dependency information for Python packages is usually available in the
+package source tree, with varying degrees of accuracy: in the
+@file{setup.py} file, in @file{requirements.txt}, or in @file{tox.ini}.
+
+Your mission, when writing a recipe for a Python package, is to map
+these dependencies to the appropriate type of ``input'' (@pxref{package
+Reference, inputs}). Although the @code{pypi} importer normally does a
+good job (@pxref{Invoking guix import}), you may want to check the
+following check list to determine which dependency goes where.
+
+@itemize
+
+@item
+Python dependencies required at run time go into
+@code{propagated-inputs}. They are typically defined with the
+@code{install_requires} keyword in @file{setup.py}, or in the
+@file{requirements.txt} file.
+
+@item
+Python packages required only at build time---e.g., those listed with
+the @code{setup_requires} keyword in @file{setup.py}---or only for
+testing---e.g., those in @code{tests_require}---go into
+@code{native-inputs}. The rationale is that (1) they do not need to be
+propagated because they are not needed at run time, and (2) in a
+cross-compilation context, it's the ``native'' input that we'd want.
+
+Examples are @code{setuptools}, which is usually needed only at build
+time, or the @code{pytest}, @code{mock}, and @code{nose} test
+frameworks. Of course if any of these packages is also required at
+run-time, it needs to go to @code{propagated-inputs}.
+
+@item
+Anything that does not fall in the previous categories goes to
+@code{inputs}, for example programs or C libraries required for building
+Python packages containing C extensions.
+
+@item
+If a Python package has optional dependencies (@code{extras_require}),
+it is up to you to decide whether to add them or not, based on their
+usefulness/overhead ratio (@pxref{Submitting Patches, @command{guix
+size}}).
+
+@end itemize
+
+
@node Perl Modules
@subsection Perl Modules
HCoop / jackhill / guix / guix.git / blobdiff