diff --git a/docs/index.rst b/docs/index.rst index acad18cd66bf8f54b8129fd0b0e53aa600410dd0..24a6b325680403d411da41ae1d6abf0b7ca09737 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -226,25 +226,35 @@ Installed under `instance-add-post.d`, `instance-rename-post.d`, Currently it supports dynamic updates against a BIND server or secure Microsoft DNS (Active Directory) by using the `nsupdate` -command (found in `dnsutils` debian package). +command (found in `dnsutils` debian package). The method to be used +is defined in AUTHENTICATION_METHOD setting. The available methods +are: -On both cases, to enable it, the admin must set the SERVER (the IP of + - plain (nsupdate) + - bind9 (nsupdate -k) + - kerberos (nsupdate -g) + +For backwards compatibility we assume `bind9` if the above setting is missing. +To disable DDNS updates unset the AUTHENTICATION_METHOD variable +in `/etc/defaults/snf-network`. + +If DDNS updates are enabled, the admin must set the SERVER (the IP of the DNS server) and FZONE (the domain of the instances) variables found in `/etc/default/snf-network`. Please note that currenlty only one domain is supported for the instances. -In case of BIND (e.g `DDNS <https://wiki.debian.org/DDNS>`_), +In case of ``bind9`` method (e.g `DDNS <https://wiki.debian.org/DDNS>`_), the KEYFILE variable in `/etc/default/snf-network` must point to -the .private file created by dnssec-keygen. +the `.private` file created by ``dnssec-keygen``. -To authenticate against an AD controller using Kerberos, snf-network -uses the -g option of nsupdate (GSS-TSIG mode). Prior to that, it uses -"k5start -H" to ensure there is a happy ticket (stored under -/var/lib/snf-network; see KERBEROS_TICKET default option). In case the -ticket is invalid, it will use a keytab containing the password and it -will try to obtain a ticket automatically (password-less). The keytab -with the corresponding service principal must already exist and both -should be mentioned in the settings. +In case of ``kerberos`` method (e.g. against Active Directory), +snf-network uses the -g option of nsupdate (GSS-TSIG mode). Prior to that, +it uses "k5start -H" to ensure there is a happy ticket (see +KERBEROS_TICKET default option). In case the ticket is invalid, it will +use a keytab containing the password and try obtain a ticket +automatically (password-less). The keytab with the corresponding service +principal must already exist and both should be mentioned in the +settings. To add a valid keytab one can use: @@ -427,10 +437,26 @@ one of them. <setups>`) - ``RUNLOCKED_OPTS`` options for runlocked helper script used as a wrapper for ebtables - - ``SERVER`` the IP/FQDN of the name server - - ``FZONE`` the domain that the VMs will reside in + - ``AUTHENTICATION_METHOD`` is the method to be used for dynamic DNS + updates. The valid methods are: plain (nsupdate), bind9 (nsupdate + -k), kerberos (nsupdate -g). To disable DDNS updates just unset this + setting. + - ``SERVER`` the IP/FQDN of the name server (required for dynamic DNS + updates) + - ``FZONE`` the domain that the VMs will reside in (required for + dynamic DNS updates) - ``KEYFILE`` path to file used with -k option of nsupdate - ``TTL`` defines the duration in seconds that a DNS record may be cached + (defaults to 300) + - ``KERBEROS_PRINCIPAL`` is the kerberos principal (required for + kerberos authentication) + - ``KERBEROS_KEYTAB`` is the kerberos keytab (defaults to + /etc/krb5.keytab) + - ``KERBEROS_KSTART_ARGS`` are the options to pass to kstart (default + to "-H 1 -l 1h") + - ``KERBEROS_TICKET`` is the path to keep the ticket obtained by kstart + (defaults to /var/lib/snf-network/snf-network-kerberos.tkt) + .. toctree::