guix.texi

@example
(service prosody-service-type
         (prosody-configuration
          (modules-enabled (cons "groups" %default-modules-enabled))
          (int-components
           (list
            (int-component-configuration
             (hostname "conference.example.net")
             (plugin "muc")
             (mod-muc (mod-muc-configuration)))))
          (virtualhosts
           (list
            (virtualhost-configuration
             (domain "example.net"))))))
@end example

See below for details about @code{prosody-configuration}.

@end deffn

By default, Prosody does not need much configuration.  Only one
@code{virtualhosts} field is needed: it specifies the domain you wish
Prosody to serve.

Prosodyctl will help you generate X.509 certificates and keys:

@example
prosodyctl cert request example.net
@end example

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.  Types starting with @code{maybe-} denote parameters that won't
show up in @code{prosody.cfg.lua} when their value is @code{'disabled}.

There is also a way to specify the configuration as a string, if you
have an old @code{prosody.cfg.lua} file that you want to port over from
some other system; see the end for more details.

@c The following documentation was initially generated by
@c (generate-documentation) in (gnu services messaging).  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 Prosody updates.

Available @code{prosody-configuration} fields are:

@deftypevr {@code{prosody-configuration} parameter} package prosody
The Prosody package.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} file-name data-path
Location of the Prosody data storage directory.  See
@url{http://prosody.im/doc/configure}.
Defaults to @samp{"/var/lib/prosody"}.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} file-name-list plugin-paths
Additional plugin directories.  They are searched in all the specified
paths in order.  See @url{http://prosody.im/doc/plugins_directory}.
Defaults to @samp{()}.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} string-list admins
This is a list of accounts that are admins for the server.  Note that you
must create the accounts separately.  See @url{http://prosody.im/doc/admins} and
@url{http://prosody.im/doc/creating_accounts}.
Example: @code{(admins '("user1@@example.com" "user2@@example.net"))}
Defaults to @samp{()}.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} boolean use-libevent?
Enable use of libevent for better performance under high load.  See
@url{http://prosody.im/doc/libevent}.
Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} module-list modules-enabled
This is the list of modules Prosody will load on startup.  It looks for
@code{mod_modulename.lua} in the plugins folder, so make sure that exists too.
Documentation on modules can be found at: @url{http://prosody.im/doc/modules}.
Defaults to @samp{%default-modules-enabled}.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} string-list modules-disabled
@samp{"offline"}, @samp{"c2s"} and @samp{"s2s"} are auto-loaded, but
should you want to disable them then add them to this list.
Defaults to @samp{()}.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} file-name groups-file
Path to a text file where the shared groups are defined.  If this path is
empty then @samp{mod_groups} does nothing.  See
@url{http://prosody.im/doc/modules/mod_groups}.
Defaults to @samp{"/var/lib/prosody/sharedgroups.txt"}.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} boolean allow-registration?
Disable account creation by default, for security.  See
@url{http://prosody.im/doc/creating_accounts}.
Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} maybe-ssl-configuration ssl
These are the SSL/TLS-related settings.  Most of them are disabled so to
use Prosody's defaults.  If you do not completely understand these options, do
not add them to your config, it is easy to lower the security of your server
using them.  See @url{http://prosody.im/doc/advanced_ssl_config}.

Available @code{ssl-configuration} fields are:

@deftypevr {@code{ssl-configuration} parameter} maybe-string protocol
This determines what handshake to use.
@end deftypevr

@deftypevr {@code{ssl-configuration} parameter} file-name key
Path to your private key file, relative to @code{/etc/prosody}.
Defaults to @samp{"/etc/prosody/certs/key.pem"}.
@end deftypevr

@deftypevr {@code{ssl-configuration} parameter} file-name certificate
Path to your certificate file, relative to @code{/etc/prosody}.
Defaults to @samp{"/etc/prosody/certs/cert.pem"}.
@end deftypevr

@deftypevr {@code{ssl-configuration} parameter} file-name capath
Path to directory containing root certificates that you wish Prosody to
trust when verifying the certificates of remote servers.
Defaults to @samp{"/etc/ssl/certs"}.
@end deftypevr

@deftypevr {@code{ssl-configuration} parameter} maybe-file-name cafile
Path to a file containing root certificates that you wish Prosody to trust.
Similar to @code{capath} but with all certificates concatenated together.
@end deftypevr

@deftypevr {@code{ssl-configuration} parameter} maybe-string-list verify
A list of verification options (these mostly map to OpenSSL's
@code{set_verify()} flags).
@end deftypevr

@deftypevr {@code{ssl-configuration} parameter} maybe-string-list options
A list of general options relating to SSL/TLS.  These map to OpenSSL's
@code{set_options()}.  For a full list of options available in LuaSec, see the
LuaSec source.
@end deftypevr

@deftypevr {@code{ssl-configuration} parameter} maybe-non-negative-integer depth
How long a chain of certificate authorities to check when looking for a
trusted root certificate.
@end deftypevr

@deftypevr {@code{ssl-configuration} parameter} maybe-string ciphers
An OpenSSL cipher string.  This selects what ciphers Prosody will offer to
clients, and in what order.
@end deftypevr

@deftypevr {@code{ssl-configuration} parameter} maybe-file-name dhparam
A path to a file containing parameters for Diffie-Hellman key exchange.  You
can create such a file with:
@code{openssl dhparam -out /etc/prosody/certs/dh-2048.pem 2048}
@end deftypevr

@deftypevr {@code{ssl-configuration} parameter} maybe-string curve
Curve for Elliptic curve Diffie-Hellman. Prosody's default is
@samp{"secp384r1"}.
@end deftypevr

@deftypevr {@code{ssl-configuration} parameter} maybe-string-list verifyext
A list of "extra" verification options.
@end deftypevr

@deftypevr {@code{ssl-configuration} parameter} maybe-string password
Password for encrypted private keys.
@end deftypevr

@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} boolean c2s-require-encryption?
Whether to force all client-to-server connections to be encrypted or not.
See @url{http://prosody.im/doc/modules/mod_tls}.
Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} boolean s2s-require-encryption?
Whether to force all server-to-server connections to be encrypted or not.
See @url{http://prosody.im/doc/modules/mod_tls}.
Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} boolean s2s-secure-auth?
Whether to require encryption and certificate authentication.  This
provides ideal security, but requires servers you communicate with to support
encryption AND present valid, trusted certificates.  See
@url{http://prosody.im/doc/s2s#security}.
Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} string-list s2s-insecure-domains
Many servers don't support encryption or have invalid or self-signed
certificates.  You can list domains here that will not be required to
authenticate using certificates.  They will be authenticated using DNS.  See
@url{http://prosody.im/doc/s2s#security}.
Defaults to @samp{()}.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} string-list s2s-secure-domains
Even if you leave @code{s2s-secure-auth?} disabled, you can still require
valid certificates for some domains by specifying a list here.  See
@url{http://prosody.im/doc/s2s#security}.
Defaults to @samp{()}.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} string authentication
Select the authentication backend to use.  The default provider stores
passwords in plaintext and uses Prosody's configured data storage to store the
authentication data.  If you do not trust your server please see
@url{http://prosody.im/doc/modules/mod_auth_internal_hashed} for information
about using the hashed backend.  See also
@url{http://prosody.im/doc/authentication}
Defaults to @samp{"internal_plain"}.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} maybe-string log
Set logging options.  Advanced logging configuration is not yet supported
by the GuixSD Prosody Service.  See @url{http://prosody.im/doc/logging}.
Defaults to @samp{"*syslog"}.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} file-name pidfile
File to write pid in.  See @url{http://prosody.im/doc/modules/mod_posix}.
Defaults to @samp{"/var/run/prosody/prosody.pid"}.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} virtualhost-configuration-list virtualhosts
A host in Prosody is a domain on which user accounts can be created.  For
example if you want your users to have addresses like
@samp{"john.smith@@example.com"} then you need to add a host
@samp{"example.com"}.  All options in this list will apply only to this host.

Note: the name "virtual" host is used in configuration to avoid confusion with
the actual physical host that Prosody is installed on.  A single Prosody
instance can serve many domains, each one defined as a VirtualHost entry in
Prosody's configuration.  Conversely a server that hosts a single domain would
have just one VirtualHost entry.

See @url{http://prosody.im/doc/configure#virtual_host_settings}.

Available @code{virtualhost-configuration} fields are:

all these @code{prosody-configuration} fields: @code{admins}, @code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled}, @code{groups-file}, @code{allow-registration?}, @code{ssl}, @code{c2s-require-encryption?}, @code{s2s-require-encryption?}, @code{s2s-secure-auth?}, @code{s2s-insecure-domains}, @code{s2s-secure-domains}, @code{authentication}, @code{log}, plus:
@deftypevr {@code{virtualhost-configuration} parameter} string domain
Domain you wish Prosody to serve.
@end deftypevr

@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} int-component-configuration-list int-components
Components are extra services on a server which are available to clients,
usually on a subdomain of the main server (such as
@samp{"mycomponent.example.com"}).  Example components might be chatroom
servers, user directories, or gateways to other protocols.

Internal components are implemented with Prosody-specific plugins.  To add an
internal component, you simply fill the hostname field, and the plugin you wish
to use for the component.

See @url{http://prosody.im/doc/components}.
Defaults to @samp{()}.

Available @code{int-component-configuration} fields are:

all these @code{prosody-configuration} fields: @code{admins}, @code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled}, @code{groups-file}, @code{allow-registration?}, @code{ssl}, @code{c2s-require-encryption?}, @code{s2s-require-encryption?}, @code{s2s-secure-auth?}, @code{s2s-insecure-domains}, @code{s2s-secure-domains}, @code{authentication}, @code{log}, plus:
@deftypevr {@code{int-component-configuration} parameter} string hostname
Hostname of the component.
@end deftypevr

@deftypevr {@code{int-component-configuration} parameter} string plugin
Plugin you wish to use for the component.
@end deftypevr

@deftypevr {@code{int-component-configuration} parameter} maybe-mod-muc-configuration mod-muc
Multi-user chat (MUC) is Prosody's module for allowing you to create
hosted chatrooms/conferences for XMPP users.

General information on setting up and using multi-user chatrooms can be found
in the "Chatrooms" documentation (@url{http://prosody.im/doc/chatrooms}),
which you should read if you are new to XMPP chatrooms.

See also @url{http://prosody.im/doc/modules/mod_muc}.

Available @code{mod-muc-configuration} fields are:

@deftypevr {@code{mod-muc-configuration} parameter} string name
The name to return in service discovery responses.
Defaults to @samp{"Prosody Chatrooms"}.
@end deftypevr

@deftypevr {@code{mod-muc-configuration} parameter} string-or-boolean restrict-room-creation
If @samp{#t}, this will only allow admins to create new chatrooms.
Otherwise anyone can create a room.  The value @samp{"local"} restricts room
creation to users on the service's parent domain.  E.g. @samp{user@@example.com}
can create rooms on @samp{rooms.example.com}.  The value @samp{"admin"}
restricts to service administrators only.
Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{mod-muc-configuration} parameter} non-negative-integer max-history-messages
Maximum number of history messages that will be sent to the member that has
just joined the room.
Defaults to @samp{20}.
@end deftypevr

@end deftypevr

@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} ext-component-configuration-list ext-components
External components use XEP-0114, which most standalone components
support.  To add an external component, you simply fill the hostname field.  See
@url{http://prosody.im/doc/components}.
Defaults to @samp{()}.

Available @code{ext-component-configuration} fields are:

all these @code{prosody-configuration} fields: @code{admins}, @code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled}, @code{groups-file}, @code{allow-registration?}, @code{ssl}, @code{c2s-require-encryption?}, @code{s2s-require-encryption?}, @code{s2s-secure-auth?}, @code{s2s-insecure-domains}, @code{s2s-secure-domains}, @code{authentication}, @code{log}, plus:
@deftypevr {@code{ext-component-configuration} parameter} string component-secret
Password which the component will use to log in.
@end deftypevr

@deftypevr {@code{ext-component-configuration} parameter} string hostname
Hostname of the component.
@end deftypevr

@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} non-negative-integer-list component-ports
Port(s) Prosody listens on for component connections.
@end deftypevr

@deftypevr {@code{prosody-configuration} parameter} string component-interface
Interface Prosody listens on for component connections.
Defaults to @samp{"127.0.0.1"}.
@end deftypevr

It could be that you just want to get a @code{prosody.cfg.lua}
up and running.  In that case, you can pass an
@code{opaque-prosody-configuration} record as the value of
@code{prosody-service-type}.  As its name indicates, an opaque configuration
does not have easy reflective capabilities.
Available @code{opaque-prosody-configuration} fields are:

@deftypevr {@code{opaque-prosody-configuration} parameter} package prosody
The prosody package.
@end deftypevr

@deftypevr {@code{opaque-prosody-configuration} parameter} string prosody.cfg.lua
The contents of the @code{prosody.cfg.lua} to use.
@end deftypevr

For example, if your @code{prosody.cfg.lua} is just the empty
string, you could instantiate a prosody service like this:

@example
(service prosody-service-type
         (opaque-prosody-configuration
          (prosody.cfg.lua "")))
@end example

@node Kerberos Services
@subsubsection Kerberos Services
@cindex Kerberos

The @code{(gnu services kerberos)} module provides services relating to
the authentication protocol @dfn{Kerberos}.

@subsubheading Krb5 Service

Programs using a Kerberos client library normally
expect a configuration file in @file{/etc/krb5.conf}.
This service generates such a file from a definition provided in the
operating system declaration.
It does not cause any daemon to be started.

No ``keytab'' files are provided by this service---you must explicitly create them.
This service is known to work with the MIT client library, @code{mit-krb5}.
Other implementations have not been tested.

@defvr {Scheme Variable} krb5-service-type
A service type for Kerberos 5 clients.
@end defvr

@noindent
Here is an example of its use:
@lisp
(service krb5-service-type
         (krb5-configuration
          (default-realm "EXAMPLE.COM")
          (allow-weak-crypto? #t)
          (realms (list
                   (krb5-realm
                    (name "EXAMPLE.COM")
                    (admin-server "groucho.example.com")
                    (kdc "karl.example.com"))
                   (krb5-realm
                    (name "ARGRX.EDU")
                    (admin-server "kerb-admin.argrx.edu")
                    (kdc "keys.argrx.edu"))))))
@end lisp

@noindent
This example provides a Kerberos@tie{}5 client configuration which:
@itemize
@item Recognizes two realms, @i{viz:} ``EXAMPLE.COM'' and ``ARGRX.EDU'', both
of which have distinct administration servers and key distribution centers;
@item Will default to the realm ``EXAMPLE.COM'' if the realm is not explicitly
specified by clients;
@item Accepts services which only support encryption types known to be weak.
@end itemize

The @code{krb5-realm} and @code{krb5-configuration} types have many fields.
Only the most commonly used ones are described here.
For a full list, and more detailed explanation of each, see the MIT
@uref{http://web.mit.edu/kerberos/krb5-devel/doc/admin/conf_files/krb5_conf.html,,krb5.conf}
documentation.


@deftp {Data Type} krb5-realm
@cindex realm, kerberos
@table @asis
@item @code{name}
This field is a string identifying the name of the realm.
A common convention is to use the fully qualified DNS name of your organization,
converted to upper case.

@item @code{admin-server}
This field is a string identifying the host where the administration server is
running.

@item @code{kdc}
This field is a string identifying the key distribution center
for the realm.
@end table
@end deftp

@deftp {Data Type} krb5-configuration

@table @asis
@item @code{allow-weak-crypto?} (default: @code{#f})
If this flag is @code{#t} then services which only offer encryption algorithms
known to be weak will be accepted.

@item @code{default-realm} (default: @code{#f})
This field should be a string identifying the default Kerberos
realm for the client.
You should set this field to the name of your Kerberos realm.
If this value is @code{#f}
then a realm must be specified with every Kerberos principal when invoking programs
such as @command{kinit}.

@item @code{realms}
This should be a non-empty list of @code{krb5-realm} objects, which clients may
access.
Normally, one of them will have a @code{name} field matching the @code{default-realm}
field.
@end table
@end deftp


@subsubheading PAM krb5 Service
@cindex pam-krb5

The @code{pam-krb5} service allows for login authentication and password
management via Kerberos.
You will need this service if you want PAM enabled applications to authenticate
users using Kerberos.

@defvr {Scheme Variable} pam-krb5-service-type
A service type for the Kerberos 5 PAM module.
@end defvr

@deftp {Data Type} pam-krb5-configuration
Data type representing the configuration of the Kerberos 5 PAM module
This type has the following parameters:
@table @asis
@item @code{pam-krb5} (default: @code{pam-krb5})
The pam-krb5 package to use.

@item @code{minimum-uid} (default: @code{1000})
The smallest user ID for which Kerberos authentications should be attempted.
Local accounts with lower values will silently fail to authenticate.
@end table
@end deftp


@node Web Services
@subsubsection Web Services

@cindex web
@cindex www
@cindex HTTP
The @code{(gnu services web)} module provides the following service:

@deffn {Scheme Procedure} nginx-service [#:nginx nginx] @
       [#:log-directory ``/var/log/nginx''] @
       [#:run-directory ``/var/run/nginx''] @
       [#:server-list '()] @
       [#:upstream-list '()] @
       [#:config-file @code{#f}]

Return a service that runs @var{nginx}, the nginx web server.

The nginx daemon loads its runtime configuration from @var{config-file}.
Log files are written to @var{log-directory} and temporary runtime data
files are written to @var{run-directory}.  For proper operation, these
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{server-list} can be
used to specify the list of @dfn{server blocks} required on the host and
@var{upstream-list} can be used to specify a list of @dfn{upstream
blocks} to configure.  For this to work, use the default value for
@var{config-file}.

At startup, @command{nginx} has not yet read its configuration file, so it
uses a default file to log error messages.  If it fails to load its
configuration file, that is where error messages are logged.  After the
configuration file is loaded, the default error log file changes as per
configuration.  In our case, startup error messages can be found in
@file{/var/run/nginx/logs/error.log}, and after configuration in
@file{/var/log/nginx/error.log}.  The second location can be changed with the
@var{log-directory} configuration option.

@end deffn

@deffn {Scheme Variable} nginx-service-type
This is type for the nginx web server.

This service can be extended to add server blocks in addition to the
default one, as in this example:

@example
(simple-service 'my-extra-server nginx-service-type
                (list (nginx-server-configuration
                        (https-port #f)
                        (root "/srv/http/extra-website"))))
@end example
@end deffn

@deftp {Data Type} nginx-server-configuration
Data type representing the configuration of an nginx server block.
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{server block}.

@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{server block}.

Note that nginx can listen for HTTP and HTTPS connections in the same
@dfn{server block}.

@item @code{server-name} (default: @code{(list 'default)})
A list of server names this server represents. @code{'default} represents the
default server for connections matching no other server.

@item @code{root} (default: @code{"/srv/http"})
Root of the website nginx will serve.

@item @code{locations} (default: @code{'()})
A list of @dfn{nginx-location-configuration} or
@dfn{nginx-named-location-configuration} records to use within this
server block.

@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

@deftp {Data Type} nginx-upstream-configuration
Data type representing the configuration of an nginx @code{upstream}
block.  This type has the following parameters:

@table @asis
@item @code{name}
Name for this group of servers.

@item @code{servers}
Specify the addresses of the servers in the group.  The address can be
specified as a IP address (e.g. @samp{127.0.0.1}), domain name
(e.g. @samp{backend1.example.com}) or a path to a UNIX socket using the
prefix @samp{unix:}.  For addresses using an IP address or domain name,
the default port is 80, and a different port can be specified
explicitly.

@end table
@end deftp

@deftp {Data Type} nginx-location-configuration
Data type representing the configuration of an nginx @code{location}
block.  This type has the following parameters:

@table @asis
@item @code{uri}
URI which this location block matches.

@anchor{nginx-location-configuration body}
@item @code{body}
Body of the location block, specified as a string. This can contain many
configuration directives.  For example, to pass requests to a upstream
server group defined using an @code{nginx-upstream-configuration} block,
the following directive would be specified in the body @samp{proxy_pass
http://upstream-name;}.

@end table
@end deftp

@deftp {Data Type} nginx-named-location-configuration
Data type representing the configuration of an nginx named location
block.  Named location blocks are used for request redirection, and not
used for regular request processing.  This type has the following
parameters:

@table @asis
@item @code{name}
Name to identify this location block.

@item @code{body}
@xref{nginx-location-configuration body}, as the body for named location
blocks can be used in a similar way to the
@code{nginx-location-configuration body}.  One restriction is that the
body of a named location block cannot contain location blocks.

@end table
@end deftp


@node DNS Services
@subsubsection DNS Services
@cindex DNS (domain name system)
@cindex domain name system (DNS)

The @code{(gnu services dns)} module provides services related to the
@dfn{domain name system} (DNS).  It provides a server service for hosting
an @emph{authoritative} DNS server for multiple zones, slave or master.
This service uses @uref{https://www.knot-dns.cz/, Knot DNS}.

An example configuration of an authoritative server for two zones, one master
and one slave, is:

@lisp
(define-zone-entries example.org.zone
;; Name TTL Class Type Data
  ("@@"  ""  "IN"  "A"  "127.0.0.1")
  ("@@"  ""  "IN"  "NS" "ns")
  ("ns" ""  "IN"  "A"  "127.0.0.1"))

(define master-zone
  (knot-zone-configuration
    (domain "example.org")
    (zone (zone-file
            (origin "example.org")
            (entries example.org.zone)))))

(define slave-zone
  (knot-zone-configuration
    (domain "plop.org")
    (dnssec-policy "default")
    (master (list "plop-master"))))

(define plop-master
  (knot-remote-configuration
    (id "plop-master")
    (address (list "208.76.58.171"))))

(operating-system
  ;; ...
  (services (cons* (service knot-service-type
                     (knot-confifguration
                       (remotes (list plop-master))
                       (zones (list master-zone slave-zone))))
                   ;; ...
                   %base-services)))
@end lisp

@deffn {Scheme Variable} knot-service-type
This is the type for the Knot DNS server.

Knot DNS is an authoritative DNS server, meaning that it can serve multiple
zones, that is to say domain names you would buy from a registrar.  This server
is not a resolver, meaning that it can only resolve names for which it is
authoritative.  This server can be configured to serve zones as a master server
or a slave server as a per-zone basis.  Slave zones will get their data from
masters, and will serve it as an authoritative server.  From the point of view
of a resolver, there is no difference between master and slave.

The following data types are used to configure the Knot DNS server:
@end deffn

@deftp {Data Type} knot-key-configuration
Data type representing a key.
This type has the following parameters:

@table @asis
@item @code{id} (default: @code{""})
An identifier for other configuration fields to refer to this key. IDs must
be unique and must not be empty.

@item @code{algorithm} (default: @code{#f})
The algorithm to use.  Choose between @code{#f}, @code{'hmac-md5},
@code{'hmac-sha1}, @code{'hmac-sha224}, @code{'hmac-sha256}, @code{'hmac-sha384}
and @code{'hmac-sha512}.

@item @code{secret} (default: @code{""})
The secret key itself.

@end table
@end deftp

@deftp {Data Type} knot-acl-configuration
Data type representing an Access Control List (ACL) configuration.
This type has the following parameters:

@table @asis
@item @code{id} (default: @code{""})
An identifier for ether configuration fields to refer to this key. IDs must be
unique and must not be empty.

@item @code{address} (default: @code{'()})
An ordered list of IP addresses, network subnets, or network ranges represented
with strings.  The query must match one of them.  Empty value means that
address match is not required.

@item @code{key} (default: @code{'()})
An ordered list of references to keys represented with strings.  The string
must match a key ID defined in a @code{knot-key-configuration}.  No key means
that a key is not require to match that ACL.

@item @code{action} (default: @code{'()})
An ordered list of actions that are permitted or forbidden by this ACL.  Possible
values are lists of zero or more elements from @code{'transfer}, @code{'notify}
and @code{'update}.

@item @code{deny?} (default: @code{#f})
When true, the ACL defines restrictions.  Listed actions are forbidden.  When
false, listed actions are allowed.

@end table
@end deftp

@deftp {Data Type} zone-entry
Data type represnting a record entry in a zone file.
This type has the following parameters:

@table @asis
@item @code{name} (default: @code{"@@"})
The name of the record.  @code{"@@"} refers to the origin of the zone.  Names
are relative to the origin of the zone.  For example, in the @code{example.org}
zone, @code{"ns.example.org"} actually refers to @code{ns.example.org.example.org}.
Names ending with a dot are absolute, which means that @code{"ns.example.org."}
refers to @code{ns.example.org}.

@item @code{ttl} (default: @code{""})
The Time-To-Live (TTL) of this record.  If not set, the default TTL is used.

@item @code{class} (default: @code{"IN"})
The class of the record.  Knot currently supports only @code{"IN"} and
partially @code{"CH"}.

@item @code{type} (default: @code{"A"})
The type of the record.  Common types include A (IPv4 address), AAAA (IPv6
address), NS (Name Server) and MX (Mail eXchange).  Many other types are
defined.

@item @code{data} (default: @code{""})
The data contained in the record.  For instance an IP address associated with
an A record, or a domain name associated with an NS record.  Remember that
domain names are relative to the origin unless they end with a dot.

@end table
@end deftp

@deftp {Data Type} zone-file
Data type representing the content of a zone file.
This type has the following parameters:

@table @asis
@item @code{entries} (default: @code{'()})
The list of entries.  The SOA record is taken care of, so you don't need to
put it in the list of entries.  This list should probably contain an entry
for your primary authoritative DNS server.  Other than using a list of entries
directly, you can use @code{define-zone-entries} to define a object containing
the list of entries more easily, that you can later pass to the @code{entries}
field of the @code{zone-file}.

@item @code{origin} (default: @code{""})
The name of your zone.  This parameter cannot be empty.

@item @code{ns} (default: @code{"ns"})
The domain of your primary authoritative DNS server.  The name is relative to
the origin, unless it ends with a dot.  It is mandatory that this primary
DNS server corresponds to an NS record in the zone and that it is associated
to an IP address in the list of entries.

@item @code{mail} (default: @code{"hostmaster"})
An email address people can contact you at, as the owner of the zone.  This
is translated as @code{<mail>@@<origin>}.

@item @code{serial} (default: @code{1})
The serial number of the zone.  As this is used to keep track of changes by
both slaves and resolvers, it is mandatory that it @emph{never} decreases.
Always increment it when you make a change in your zone.

@item @code{refresh} (default: @code{"2d"})
The frequency at which slaves will do a zone transfer.  This value can be
a number of seconds or a number of some unit between:
@itemize
@item m: minute
@item h: hour
@item d: day
@item w: week
@end itemize

@item @code{retry} (default: @code{"15m"})
The period after which a slave will retry to contact its master when it fails
to do so a first time.

@item @code{expiry} (default: @code{"2w"})
Default TTL of records.  Existing records are considered correct for at most
this amount of time.  After this period, resolvers will invalidate their cache
and check again that it still exists.

@item @code{nx} (default: @code{"1h"})
Default TTL of inexistant records.  This delay is usually short because you want
your new domains to reach everyone quickly.

@end table
@end deftp

@deftp {Data Type} knot-remote-configuration
Data type representing a remote configuration.
This type has the following parameters:

@table @asis
@item @code{id} (default: @code{""})
An identifier for other configuration fields to refer to this remote. IDs must
be unique and must not be empty.

@item @code{address} (default: @code{'()})
An ordered list of destination IP addresses.  Addresses are tried in sequence.
An optional port can be given with the @@ separator.  For instance:
@code{(list "1.2.3.4" "2.3.4.5@@53")}.  Default port is 53.

@item @code{via} (default: @code{'()})
An ordered list of source IP addresses.  An empty list will have Knot choose
an appropriate source IP.  An optional port can be given with the @@ separator.
The default is to choose at random.

@item @code{key} (default: @code{#f})
A reference to a key, that is a string containing the identifier of a key
defined in a @code{knot-key-configuration} field.

@end table
@end deftp

@deftp {Data Type} knot-keystore-configuration
Data type representing a keystore to hold dnssec keys.
This type has the following parameters:

@table @asis
@item @code{id} (default: @code{""})
The id of the keystore.  It must not be empty.

@item @code{backend} (default: @code{'pem})
The backend to store the keys in.  Can be @code{'pem} or @code{'pkcs11}.

@item @code{config} (default: @code{"/var/lib/knot/keys/keys"})
The configuration string of the backend.  An example for the PKCS#11 is:
@code{"pkcs11:token=knot;pin-value=1234 /gnu/store/.../lib/pkcs11/libsofthsm2.so"}.
For the pem backend, the string reprensents a path in the filesystem.

@end table
@end deftp

@deftp {Data Type} knot-policy-configuration
Data type representing a dnssec policy.  Knot DNS is able to automatically
sign your zones.  It can either generate and manage your keys automatically or
use keys that you generate.

Dnssec is usually implemented using two keys: a Key Signing Key (KSK) that is
used to sign the second, and a Zone Signing Key (ZSK) that is used to sign the
zone.  In order to be trusted, the KSK needs to be present in the parent zone
(usually a top-level domain).  If your registrar supports dnssec, you will
have to send them your KSK's hash so they can add a DS record in their zone.
This is not automated and need to be done each time you change your KSK.

The policy also defines the lifetime of keys.  Usually, ZSK can be changed
easily and use weaker cryptographic functions (they use lower parameters) in
order to sign records quickly, so they are changed often.  The KSK however
requires manual interaction with the registrar, so they are changed less often
and use stronger parameters because they sign only one record.

This type has the following parameters:

@table @asis
@item @code{id} (default: @code{""})
The id of the policy.  It must not be empty.

@item @code{keystore} (default: @code{"default"})
A reference to a keystore, that is a string containing the identifier of a
keystore defined in a @code{knot-keystore-configuration} field.  The
@code{"default"} identifier means the default keystore (a kasp database that
was setup by this service).

@item @code{manual?} (default: @code{#f})
Whether the key management is manual or automatic.

@item @code{single-type-signing?} (default: @code{#f})
When @code{#t}, use the Single-Type Signing Scheme.

@item @code{algorithm} (default: @code{"ecdsap256sha256"})
An algorithm of signing keys and issued signatures.

@item @code{ksk-size} (default: @code{256})
The length of the KSK.  Note that this value is correct for the default
algorithm, but would be unsecure for other algorithms.

@item @code{zsk-size} (default: @code{256})
The length of the ZSK.  Note that this value is correct for the default
algorithm, but would be unsecure for other algorithms.

@item @code{dnskey-ttl} (default: @code{'default})
The TTL value for DNSKEY records added into zone apex.  The special
@code{'default} value means same as the zone SOA TTL.

@item @code{zsk-lifetime} (default: @code{"30d"})
The period between ZSK publication and the next rollover initiation.

@item @code{propagation-delay} (default: @code{"1d"})
An extra delay added for each key rollover step.  This value should be high
enough to cover propagation of data from the master server to all slaves.

@item @code{rrsig-lifetime} (default: @code{"14d"})
A validity period of newly issued signatures.

@item @code{rrsig-refresh} (default: @code{"7d"})
A period how long before a signature expiration the signature will be refreshed.

@item @code{nsec3?} (default: @code{#f})
When @code{#t}, NSEC3 will be used instead of NSEC.

@item @code{nsec3-iterations} (default: @code{5})
The number of additional times the hashing is performed.

@item @code{nsec3-salt-length} (default: @code{8})
The length of a salt field in octets, which is appended to the original owner
name before hashing.

@item @code{nsec3-salt-lifetime} (default: @code{"30d"})
The validity period of newly issued salt field.

@end table
@end deftp

@deftp {Data Type} knot-zone-configuration
Data type representing a zone served by Knot.
This type has the following parameters:

@table @asis
@item @code{domain} (default: @code{""})
The domain served by this configuration.  It must not be empty.

@item @code{file} (default: @code{""})
The file where this zone is saved.  This parameter is ignored by master zones.
Empty means default location that depends on the domain name.

@item @code{zone} (default: @code{(zone-file)})
The content of the zone file.  This parameter is ignored by slave zones.  It
must contain a zone-file record.