aboutsummaryrefslogtreecommitdiff
path: root/doc/guix.texi
diff options
context:
space:
mode:
authorJulien Lepiller <julien@lepiller.eu>2017-05-01 21:41:45 +0200
committerJulien Lepiller <julien@lepiller.eu>2017-05-27 10:40:24 +0200
commitba69e8f7ce21a81bdd5b99fdb1cc64492443e15c (patch)
treeb6618a9991114560765101b92f7f4f1f0e3755c1 /doc/guix.texi
parentd771ba62f8b23cf71ad82b3423da36416e8a1e8d (diff)
downloadguix-ba69e8f7ce21a81bdd5b99fdb1cc64492443e15c.tar
guix-ba69e8f7ce21a81bdd5b99fdb1cc64492443e15c.tar.gz
gnu: Add knot-service-type.
* gnu/services/dns.scm: New file. * gnu/local.mk (GNU_SYSTEM_MODULES): Add it. * doc/guix.texi (DNS Services): New subsubsection.
Diffstat (limited to 'doc/guix.texi')
-rw-r--r--doc/guix.texi410
1 files changed, 410 insertions, 0 deletions
diff --git a/doc/guix.texi b/doc/guix.texi
index aa8b705be6..0d389261a2 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -218,6 +218,7 @@ Services
* Messaging Services:: Messaging services.
* Kerberos Services:: Kerberos services.
* Web Services:: Web servers.
+* DNS Services:: DNS daemons.
* VPN Services:: VPN daemons.
* Network File System:: NFS related services.
* Continuous Integration:: The Cuirass service.
@@ -8737,6 +8738,7 @@ declaration.
* Messaging Services:: Messaging services.
* Kerberos Services:: Kerberos services.
* Web Services:: Web servers.
+* DNS Services:: DNS daemons.
* VPN Services:: VPN daemons.
* Network File System:: NFS related services.
* Continuous Integration:: The Cuirass service.
@@ -13520,6 +13522,414 @@ Whether the server should add its configuration to response.
@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.
+
+@item @code{master} (default: @code{'()})
+A list of master remotes. When empty, this zone is a master. When set, this
+zone is a slave. This is a list of remotes identifiers.
+
+@item @code{ddns-master} (default: @code{#f})
+The main master. When empty, it defaults to the first master in the list of
+masters.
+
+@item @code{notify} (default: @code{'()})
+A list of slave remote identifiers.
+
+@item @code{acl} (default: @code{'()})
+A list of acl identifiers.
+
+@item @code{semantic-checks?} (default: @code{#f})
+When set, this adds more semantic checks to the zone.
+
+@item @code{disable-any?} (default: @code{#f})
+When set, this forbids queries of the ANY type.
+
+@item @code{zonefile-sync} (default: @code{0})
+The delay between a modification in memory and on disk. 0 means immediate
+synchronization.
+
+@item @code{serial-policy} (default: @code{'increment})
+A policy between @code{'increment} and @code{'unixtime}.
+
+@end table
+@end deftp
+
+@deftp {Data Type} knot-configuration
+Data type representing the Knot configuration.
+This type has the following parameters:
+
+@table @asis
+@item @code{knot} (default: @code{knot})
+The Knot package.
+
+@item @code{run-directory} (default: @code{"/var/run/knot"})
+The run directory. This directory will be used for pid file and sockets.
+
+@item @code{listen-v4} (default: @code{"0.0.0.0"})
+An ip address on which to listen.
+
+@item @code{listen-v6} (default: @code{"::"})
+An ip address on which to listen.
+
+@item @code{listen-port} (default: @code{53})
+A port on which to listen.
+
+@item @code{keys} (default: @code{'()})
+The list of knot-key-configuration used by this configuration.
+
+@item @code{acls} (default: @code{'()})
+The list of knot-acl-configuration used by this configuration.
+
+@item @code{remotes} (default: @code{'()})
+The list of knot-remote-configuration used by this configuration.
+
+@item @code{zones} (default: @code{'()})
+The list of knot-zone-configuration used by this configuration.
+
+@end table
+@end deftp
+
@node VPN Services
@subsubsection VPN Services
@cindex VPN (virtual private network)