nsd.conf

package: nsd

title: nsd.conf(5)

summary: NSD configuration file

text:
# nsd.conf(5)

## NAME
nsd.conf - NSD configuration file

## SYNOPSIS
nsd.conf

## DESCRIPTION
This file is used to configure nsd(8). It specifies options for the nsd server, zone files, primaries and secondaries.

The file format has attributes and values. Some attributes have attributes inside them. The notation is:

attribute: value

Comments start with # and last to the end of line. Empty lines are ignored, as is whitespace at the beginning of a line. Quotes must be used for values with spaces in them, eg. "file name.zone".

## EXAMPLE
An example of a short nsd.conf file is below.

```
# Example nsd.conf file for example.com.
# This is a comment.

server:
	server-count: 1 # use this number of cpu cores
	username: _nsd
	zonelistfile: /var/db/nsd/zone.list
	logfile: /var/log/nsd.log
	pidfile: /var/run/nsd.pid
	xfrdfile: /var/lib/nsd/xfrd.state

zone:
	name: example.com
	zonefile: /etc/nsd/example.com.zone

zone:
	# this server is the primary and 192.0.2.1 is the secondary.
	name: primaryzone.com
	zonefile: /etc/nsd/primaryzone.com.zone
	notify: 192.0.2.1 NOKEY
	provide-xfr: 192.0.2.1 NOKEY

zone:
	# this server is the secondary and 192.0.2.2 is the primary.
	name: secondaryzone.com
	zonefile: /etc/nsd/secondaryzone.com.zone
	allow-notify: 192.0.2.2 NOKEY
	request-xfr: 192.0.2.2 NOKEY
```

Then, use kill -HUP to reload changes from primary zone files. And use kill -TERM to stop the server.

## FILE FORMAT
There must be whitespace between keywords. Attribute keywords end with a colon ':'. An attribute is followed by its containing attributes, or a value.

At the top level, only server:, verify:, key:, pattern:, zone:, tls-auth:, and remote-control: are allowed. These are followed by their attributes or a new top-level keyword. The zone: attribute is followed by zone options. The server: attribute is followed by global options for the NSD server. The verify: attribute is used to control zone verification. A key: attribute is used to define keys for authentication. The pattern: attribute is followed by the zone options for zones that use the pattern. A tls-auth: attribute is used to define authentication attributes for TLS connections used for XFR-over-TLS.

Files can be included using the include: directive. It can appear anywhere, and takes a single filename as an argument. Processing continues as if the text from the included file were copied into the config file at that point. If a chroot is used, an absolute filename is needed (with the chroot prepended), so that the include can be parsed before and after application of the chroot (and the knowledge of what that chroot is). You can use '*' to include a wildcard match of files, eg. "foo/nsd.d/*.conf". Also '?', '{}', '[]', and '~' work, see glob(7). If no files match the pattern, this is not an error.

### Server Options
The global options (if not overridden from the NSD command-line) are taken from the server: clause. There may only be one server: clause.

ip-address: <ip4 or ip6 or interface-name>[@port] [servers] [bindtodevice] [setfib]

NSD will bind to the listed ip-address. Can be given multiple times to bind multiple ip-addresses. Optionally, a port number can be given. If none are given NSD listens to the wildcard interface. Same as command-line option -a. To limit which NSD server(s) listen on the given interface, specify one or more servers separated by whitespace after <ip>[@port]. The NSD server has number 1 to server-count processes to serve queries. This specifies the server processes by number that handle the ip-address. Ranges can be used as a shorthand to specify multiple consecutive servers. By default every server will listen and handle traffic for this.

If an interface name is used instead of ip4 or ip6, the list of IP addresses associated with that interface is picked up and used at server start.

For servers with multiple IP addresses that can be used to send traffic to the internet, list them one by one, or the source address of replies could be wrong. This is because if the udp socket associates a source address of 0.0.0.0 then the kernel picks an ip-address with which to send to the internet, and it picks the wrong one. Typically needed for anycast instances. Use ip-transparent to be able to list addresses that turn on later (typical for certain load-balancing).

The bindtodevice option looks for the device for the address, and then uses SO_BINDTODEVICE to bind the socket to the device. This is used as a performance optimisation. And it allows the network socket to connect directly to the network device. This speeds up the network stack processing. The socket only processes packets received from that interface.

The setfib option uses the SO_SETFIB socket option so that the fib from getaddrinfo for the address is set on the socket. This associates the FIB, the routing table, from the interface for the socket. That bypasses the routing selection for traffic. It is used as a performance optimisation.

interface: <ip4 or ip6 or interface-name>[@port] [servers] [bindtodevice] [setfib]

Same as ip-address (for ease of compatibility with unbound.conf).

ip-transparent: <yes or no>

Allows NSD to bind to non local addresses. This is useful to have NSD listen to IP addresses that are not (yet) added to the network interface, so that it can answer immediately when the address is added. Default is no.

ip-freebind: <yes or no>

Set the IP_FREEBIND option to bind to nonlocal addresses and interfaces that are down. Similar to ip-transparent. Default is no.

reuseport: <yes or no>

Use the SO_REUSEPORT socket option, and create file descriptors for every server in the server-count. This improves performance of the network stack. Only really useful if you also configure a server-count higher than 1 (such as, equal to the number of cpus). The default is no. It works on Linux, but does not work on FreeBSD, and likely does not work on other systems.

send-buffer-size: <number>

Set the send buffer size for query-servicing sockets. Set to 0 to use the default settings. It needs some space to be able to deal with packets that wait for local address resolution, from like ARP and NDP discovery, before they are sent out, hence it is elevated above the system default by default. The default is 4194304 bytes (4m).

receive-buffer-size: <number>

Set the receive buffer size for query-servicing sockets. Set to 0 to use the default settings. The default is 1048576 bytes (1m).

debug-mode: <yes or no>

Turns on debugging mode for nsd, does not fork a daemon process. Default is no. Same as command-line option -d. If set to yes it does not fork and stays in the foreground, which can be helpful for command-line debugging, but is also used by certain server supervisor processes to ascertain that the server is running.

do-ip4: <yes or no>

If yes, NSD listens to IPv4 connections. Default yes.

do-ip6: <yes or no>

If yes, NSD listens to IPv6 connections. Default yes.

database: <filename>

This option is ignored by NSD versions 4.8.0 and newer, because the database feature has been removed.

zonelistfile: <filename>

By default /var/db/nsd/zone.list is used. The specified file is used to store the dynamically added list of zones. The list is written to by NSD to add and delete zones. It is a text file with a zone-name and pattern-name on each line. This file is used for the nsd-control addzone and delzone commands.

identity: <string>

Returns the specified identity when asked for CH TXT ID.SERVER. Default is the name as returned by gethostname(3). Same as command-line option -i. See hide-identity to set the server to not respond to such queries.

version: <string>

Returns the specified version string when asked for CH TXT version.server, and version.bind queries. Default is the compiled package version. See hide-version to set the server to not respond to such queries.

nsid: <string>

Add the specified nsid to the EDNS section of the answer when queried with an NSID EDNS enabled packet. As a sequence of hex characters or with ascii_ prefix and then an ascii string. Same as command-line option -I.

logfile: <filename>

Log messages to the logfile. The default is to log to stderr and syslog (with facility LOG_DAEMON). Same as command-line option -l.

log-only-syslog: <yes or no>

Log messages only to syslog. Useful with systemd so that print to stderr does not cause duplicate log strings in journald. Before syslog has been opened, the server uses stderr. Stderr is also used if syslog is not available. Default is no.

server-count: <number>

Start this many NSD servers. Default is 1. Same as command-line option -N.

cpu-affinity: <number> <number> ...

Overall CPU affinity for NSD server(s). Default is no affinity.

server-N-cpu-affinity: <number>

Bind NSD server specified by N to a specific core. Default is to have affinity set to every core specified in cpu-affinity. This setting only takes effect if cpu-affinity is enabled.

xfrd-cpu-affinity: <number>

Bind xfrd to a specific core. Default is to have affinity set to every core specified in cpu-affinity. This setting only takes effect if cpu-affinity is enabled.

tcp-count: <number>

The maximum number of concurrent, active TCP connections by each server. Default is 100. Same as command-line option -n. That is the number of requests from clients to this server.

tcp-reject-overflow: <yes or no>

If set to yes, TCP connections made beyond the maximum set by tcp-count will be dropped immediately (accepted and closed). Default is no.

tcp-query-count: <number>

The maximum number of queries served on a single TCP connection. Default is 0, meaning there is no maximum.

tcp-timeout: <number>

Overrides the default TCP timeout. This also affects zone transfers over TCP. The default is 120 seconds.

tcp-mss: <number>

Maximum segment size (MSS) of TCP socket on which the server responds to queries. Value lower than common MSS on Ethernet (1220 for example) will address path MTU problem. Note that not all platform supports socket option to set MSS (TCP_MAXSEG). Default is system default MSS determined by interface MTU and negotiation between server and client.

outgoing-tcp-mss: <number>

Maximum segment size (MSS) of TCP socket for outgoing XFR request to other nameservers. Value lower than common MSS on Ethernet (1220 for example) will address path MTU problem. Note that not all platform supports socket option to set MSS (TCP_MAXSEG). Default is system default MSS determined by interface MTU and negotiation between NSD and other servers.

tcp-listen-queue: <number>

Set the TCP backlog for listening sockets. This allows more pending connections with their connection established waiting for TCP service. Higher is better for more connections coming in at the same time. High values also protect more against flooding and some side-channel issues. Default is -1 on BSDs and Linux, and 256 on other systems. The -1 selects the largest value allowed.

xfrd-tcp-max: <number>

Number of sockets for xfrd to use for outgoing zone transfers. Default 128. Increase it to allow more zone transfer sockets, like to 256. That is for zone transfers requested by this server from other servers. To save memory, this can be lowered, set it lower together with some other settings to have reduced memory footprint for NSD. xfrd-tcp-max: 32 and xfrd-tcp-pipeline: 128 and rrl-size: 1000 This reduces memory footprint, other memory usage is caused mainly by the server-count setting, the number of server processes, and the tcp-count setting, which keeps buffers per server process, and by the size of the zone data.

xfrd-tcp-pipeline: <number>

Number of simultaneous outgoing zone transfers that are possible on the tcp sockets of xfrd. Max is 65536, default is 128. That is for zone transfers requested by this server from other servers.

ipv4-edns-size: <number>

Preferred EDNS buffer size for IPv4. Default 1232.

ipv6-edns-size: <number>

Preferred EDNS buffer size for IPv6. Default 1232.

pidfile: <filename>

Use the pid file instead of the platform specific default, usually "/var/run/nsd.pid". Same as command-line option -P. With "" there is no pidfile, for some startup management setups, where a pidfile is not useful to have. The default can be set at compile time, sometimes to "". Then the config option and commandline option can be used to specify that a pidfile is used, different from its compile time default value. The file is not chowned to the user from the username: option, for permission safety reasons. It remains owned to the user by which the server was started. The file may not be removed after the server is finished and quit, since permissions for the username may not make this possible.

port: <number>

Answer queries on the specified port. Default is 53. Same as command-line option -p.

statistics: <number>

If not present no statistics are dumped. Statistics are produced every number seconds. Same as command-line option -s.

chroot: <directory>

NSD will chroot on startup to the specified directory. Note that if elsewhere in the configuration you specify an absolute pathname to a file inside the chroot, you have to prepend the chroot path. That way, you can switch the chroot option on and off without having to modify anything else in the configuration. Set the value to "" (the empty string) to disable the chroot. By default "" is used. Same as command-line option -t.

username: <username>

After binding the socket, drop user privileges and assume the username. Can be username, id or id.gid. Same as command-line option -u.

zonesdir: <directory>

Change the working directory to the specified directory before accessing zone files. Also, NSD will access zonelistfile, logfile, pidfile, xfrdfile, xfrdir, server-key-file, server-cert-file, control-key-file and control-cert-file relative to this directory. Set the value to "" (the empty string) to disable the change of working directory. By default "/etc/nsd" is used.

difffile: <filename>

Ignored, for compatibility with NSD3 config files.

xfrdfile: <filename>

The soa timeout and zone transfer daemon in NSD will save its state to this file. State is read back after a restart. The state file can be deleted without too much harm, but timestamps of zones will be gone. If it is configured as "", the state file is not used, all secondary zones are checked for updates upon startup. For more details see the section on zone expiry behavior of NSD. Default is /var/lib/nsd/xfrd.state.

xfrdir: <directory>

The zone transfers are stored here before they are processed. A directory is created here that is removed when NSD exits. Default is /tmp.

xfrd-reload-timeout: <number>

If this value is -1, xfrd will not trigger a reload after a zone transfer. If positive xfrd will trigger a reload after a zone transfer, then it will wait for the number of seconds before it will trigger a new reload. Setting this value throttles the reloads to once per the number of seconds. The default is 1 second.

verbosity: <level>

This value specifies the verbosity level for (non-debug) logging. Default is 0. 1 gives more information about incoming notifies and zone transfers. 2 lists soft warnings that are encountered. 3 prints more information. Same as command-line option -V. Verbosity 0 will print warnings and errors, and other events that are important to keep NSD running.

Verbosity 1 prints additionally messages of interest. Successful notifies, successful incoming zone transfer (the zone is updated), failed incoming zone transfers or the inability to process zone updates.

Verbosity 2 prints additionally soft errors, like connection resets over TCP. And notify refusal, and axfr request refusals.

hide-version: <yes or no>

Prevent NSD from replying with the version string on CHAOS class queries. Default is no.

hide-identity: <yes or no>

Prevent NSD from replying with the identity string on CHAOS class queries. Default is no.

drop-updates: <yes or no>

If set to yes, drop received packets with the UPDATE opcode. Default is no.

use-systemd: <yes or no>

This option is deprecated and ignored. If compiled with libsystemd, NSD signals readiness to systemd and use of the option is not necessary.

log-time-ascii: <yes or no>

Log time in ascii, if "no" then in seconds epoch. Default is yes. This chooses the format when logging to file. The printout via syslog has a timestamp formatted by syslog.

log-time-iso: <yes or no>

Log time in ISO8601 format, if log-time-ascii: yes is also set. Default is no.

round-robin: <yes or no>

Enable round robin rotation of records in the answer. This changes the order of records in the answer and this may balance load across them. The default is no.

minimal-responses: <yes or no>

Enable minimal responses for smaller answers. This makes packets smaller. Extra data is only added for referrals, when it is really necessary. This is different from the --enable-minimal-responses configure time option, that reduces packets, but exactly to the fragmentation length, the nsd.conf option reduces packets as small as possible. The default is no.

confine-to-zone: <yes or no>

If set to yes, additional information will not be added to the response if the apex zone of the additional information does not match the apex zone of the initial query (E.G. CNAME resolution). Default is no.

refuse-any: <yes or no>

Refuse queries of type ANY. This is useful to stop query floods trying to get large responses. Note that rrl ratelimiting also has type ANY as a ratelimiting type. It sends truncation in response to UDP type ANY queries, and it allows TCP type ANY queries like normal. The default is no. With the option turned off, NSD behaves according to RFC 8482 4.1. It minimizes the response with one RRset. Popular and not large types, like A, AAAA and MX are preferred, and large types, like DNSKEY and RRSIG are picked with a lower preference than other types. This makes the response smaller.

reload-config: <yes or no>

Reload configuration file and update TSIG keys and zones on SIGHUP. Default is no.

zonefiles-check: <yes or no>

Make NSD check the mtime of zone files on start and sighup. If you disable it it starts faster (less disk activity in case of a lot of zones). The default is yes. The nsd-control reload command reloads zone files regardless of this option.

zonefiles-write: <seconds>

Write updated secondary zones to their zonefile every N seconds. If the zone or pattern's "zonefile" option is set to "" (empty string), no zonefile is written. The default is 3600 (1 hour).

rrl-size: <numbuckets>

This option gives the size of the hashtable. Default 1000000. More buckets use more memory, and reduce the chance of hash collisions.

rrl-ratelimit: <qps>

The max qps allowed (from one query source). Default is off (with a suggested 200 qps). If set to 0 then it is disabled (unlimited rate), also set the whitelist-ratelimit to 0 to disable ratelimit processing. If you set verbosity to 2 the blocked and unblocked subnets are logged. Blocked queries are blocked and some receive TCP fallback replies. Once the rate limit is reached, NSD begins dropping responses. However, one in every "rrl-slip" number of responses is allowed, with the TC bit set. If slip is set to 2, the returned response rate will be halved. If it's set to 3, the returned response rate will be one-third, and so on. If you set rrl-slip to 10, traffic is reduced to 1/10th. Ratelimit options rrl-ratelimit, rrl-size and rrl-whitelist-ratelimit are updated when nsd-control reconfig is done (also the zone-specific ratelimit options are updated). If not compiled in the option is ignored, the ratelimit can be on or off by default by compile time configuration.

rrl-slip: <numpackets>

This option controls the number of packets discarded before we send back a SLIP response (a response with "truncated" bit set to one). 0 disables the sending of SLIP packets, 1 means every query will get a SLIP response. Default is 2, cuts traffic in half and legit users have a fair chance to get a +TC response.

rrl-ipv4-prefix-length: <subnet>

IPv4 prefix length. Addresses are grouped by netblock. Default 24.

rrl-ipv6-prefix-length: <subnet>

IPv6 prefix length. Addresses are grouped by netblock. Default 64.

rrl-whitelist-ratelimit: <qps>

The max qps for query sorts for a source, which have been whitelisted. Default off (with a suggested 2000 qps). With the rrl-whitelist option you can set specific queries to receive this qps limit instead of the normal limit. With the value 0 the rate is unlimited.

answer-cookie: <yes or no>

Enable to answer to requests containing DNS Cookies as specified in RFC7873. Default is no. DNS Cookies increase transaction security and provide limited protection against denial-off-service amplification attacks. Server cookies will be created and included in responses. Server cookies are created based on the client cookie in the request, the current time, the client's IP address and a secret. When a client includes a valid server cookie in successive requests, the client will not be subjected to Request Rate Limiting (see rrl-ratelimit).

Servers in an anycast deployment need to be able to verify each other's server cookies. For this they need to share the secret used to construct and verify the cookies. These cookie secrets can be specified in the configuration files with the cookie-secret and cookie-staging-secret options.

If no cookie secrets are provided via configuration file, server cookie secrets can be added, dropped and activated with the nsd-control(8) tool. These secrets will be stored persistently in the cookie secret file for which the location can be specified with the cookie-secret-file option.

If no cookie secrets are provided via configuration file, and there is no or an empty cookie secret file, a random cookie secret is generated.

cookie-secret: <128 bit hex string>

The cookie secret with which server cookies are created and can be verified. If a cookie-secret is specified via configuration file, cookie secrets from the cookie secret file will be ignored.

cookie-staging-secret: <128 bit hex string>

A cookie secret with which server cookies can be verified, but will not be created. This is helpful in rolling cookie secrets in anycast setups. A cookie-staging-secret can only be configured when there is also a cookie-secret configured.

cookie-secret-file: <filename>

File from which the secrets are read used in DNS Cookie calculations. Secrets will only be read from this file if no cookie secrets are given in the configuration file via the cookie-secret and cookie-staging-secret options. Default is "/var/db/nsd/cookiesecrets.txt" In NSD version 4.10.1 and earlier, the default location of the cookie secret file was "/etc/nsd/nsd_cookiesecrets.txt". For migration purposes, cookie secrets will be read from that location if no value is given for the cookie-secret-file option and when the current default location ("/var/db/nsd/cookiesecrets.txt") does not exist.

The content of the cookie secret file must be manipulated with the add_cookie_secret, drop_cookie_secret and activate_cookie_secret commands to the nsd-control(8) tool. Please see that manpage how to perform a safe cookie secret rollover.

tls-service-key: <filename>

If enabled, the server provides TLS service on TCP sockets with the TLS service port number. The port number (853) is configured with tls-port. To turn it on, create an interface: option line in config with @port appended to the IP-address. This creates the extra socket on which the DNS over TLS service is provided. The file is the private key for the TLS session. The public certificate is in the tls-service-pem file. Default is "", turned off. Requires a restart (a reload is not enough) if changed, because the private key is read while root permissions are held and before chroot (if any).

tls-service-pem: <filename>

The public key certificate pem file for the tls service. Default is "", turned off.

tls-service-ocsp: <filename>

The ocsp pem file for the tls service, for OCSP stapling. Default is "", turned off. An external process prepares and updates the OCSP stapling data. Like this,

```
openssl ocsp -no_nonce \
	-respout /path/to/ocsp.pem \
	-CAfile /path/to/ca_and_any_intermediate.pem \
	-issuer /path/to/direct_issuer.pem \
	-cert /path/to/cert.pem \
	-url "$( openssl x509 -noout -ocsp_uri -in /path/to/cert.pem )"
```

tls-port: <number>

The port number on which to provide TCP TLS service, default is 853, only interfaces configured with that port number as @number get DNS over TLS service.

tls-auth-port: <number>

The port number on which to provide TCP TLS service to authenticated clients only. If you want to use mutual TLS authentication in Transfer over TLS (XoT) connections, this is where the primary server enables a dedicated port for this purpose. Certificates in tls-cert-bundle are used for verifying the authenticity of a client or a secondary server. Client (secondary) must enable tls-auth, configure client-cert and client-key and enable tls-auth in zone configuration in order to authenticate to a remote (primary) server.

tls-auth-xfr-only: <yes or no>

Allow zone transfers only on the tls-auth-port port and only to authenticated clients. This works globally for all zones. A provide-xfr access control list with tls-auth is also required to allow and verify a connection. Requests for zone transfers on other ports are refused.

tls-cert-bundle: <filename>

If null or "", the default verify locations are used. Set it to the certificate bundle file, for example "/etc/pki/tls/certs/ca-bundle.crt". These certificates are used for authenticating Transfer over TLS (XoT) connections.

proxy-protocol-port: <number>

The port number for proxy protocol service. If the statement is given multiple times, additional port numbers can be used for proxy protocol service. The interface definitions that use this port number expect PROXYv2 proxy protocol traffic, for UDP, TCP and for TLS service.

xdp-interface: <string>

The interface to use XDP with. This enables the use of AF_XDP sockets for UDP queries. Default is "", disabled. (EXPERIMENTAL) Considerations:

• If cpu-affinity is configured, please be aware of the cpu affinity of network device queues.

• The number of spawned servers depends on the number of combined rx/tx channels/queues of the selected interface. As many processes as there are combined channels on the specified interface will receive traffic via XDP. server-count will be increased if necessary. If server-count is higher, the excess processes will not use XDP.

• The PROXYv2 protocol, DNSTAP, and ratelimiting are currently not supported via XDP.

xdp-program-path: <string>

The eBPF XDP program to extract the XSKMAP from. Specify your own program here, if you want to use a custom XDP program. The default program shipped with NSD only redirects UDP (over Ethernet[+VLAN]+IPv4/6) traffic to port 53. When using your own XDP program, it needs to define a BPF_MAP_TYPE_XSKMAP named "xsks_map". This option needs to be set, even when NSD is configured not to load the specified XDP program (see xdp-program-load), to be able to determine the XSKMAP structure. In this case your XDP program needs to pin the above mentioned map in a bpffs (see xdp-bpffs-path).

Default is "/usr/share/nsd/xdp-dns-redirect_kern.o".

xdp-program-load: <yes or no>

Specify whether NSD should load the XDP program. If set to no, you need to load the XDP program yourself. Default is yes, if xdp-interface is set.

xdp-bpffs-path: <string>

The path to the bpffs to store/read the xsks_map pin. The default XDP program loaded by NSD doesn't need this option, it is only necessary if you load a program that pins its BPF map. If NSD is configured to load an XDP program that pins its map, NSD needs to have read/write/execute access to the specified bpffs to be able to create and later delete the map pin. If you load the XDP program yourself, NSD only needs read and write access to the pin file itself (but at least execute access to the parent directories). The default bpffs (/sys/fs/bpf) usually doesn't have the necessary permissions set for non-root users. You can either set the necessary permissions or mount your own bpffs.

Default is "/sys/fs/bpf".

xdp-force-copy: <yes or no>

Force the use of XDP_COPY mode instead of zero copy for AF_XDP sockets. This can help with drivers with broken AF_XDP support. Default is no.

metrics-enable: <yes or no>

Enable the prometheus metrics HTTP endpoint. It exposes the same statistics as the nsd-control stats_noreset command, but with metric names following the prometheus specification. (Requires libevent2) To generate metrics per zone (or more accurately, per zonestats group), specify the zonestats option on the desired zones. This will expose the zonestats metrics with the zonestats name as a label called "zone", for example with zonestats: examplezone:

```
	nsd_zonestats_queries_total{zone="examplezone"}
```

Beware, that when using nsd-control stats (instead of nsd-control stats_noreset), the statistics will be reset for the HTTP metrics endpoint as well.

metrics-interface: <ip4 or ip6 | interface name>

NSD will bind to the listed addresses or interfaces to serve the prometheus metrics. Can be given multiple times to bind multiple ip-addresses. Use 0.0.0.0 and ::0 to bind to the wildcard interface. If an interface name is used instead of ip4 or ip6, the list of IP addresses associated with that interface is picked up and used at server start.

Default is 127.0.0.1 and ::1.

metrics-port: <number>

The port number for the HTTP service. Default is 9100.

metrics-path: <string>

The HTTP path to expose the metrics at. Default is "/metrics".

### Remote Control
The remote-control: clause is used to set options for using the nsd-control(8) tool to give commands to the running NSD server. It is disabled by default, and listens for localhost by default. It uses TLS over TCP where the server and client authenticate to each other with self-signed certificates. The self-signed certificates can be generated with the nsd-control-setup tool. The key files are read by NSD before the chroot and before dropping user permissions, so they can be outside the chroot and readable by the superuser only.

control-enable: <yes or no>

Enable remote control, default is no.

control-interface: <ip4 or ip6 | interface name | absolute path>

NSD will bind to the listed addresses to service control requests (on TCP). Can be given multiple times to bind multiple ip-addresses. Use 0.0.0.0 and ::0 to service the wildcard interface. If none are given NSD listens to the localhost 127.0.0.1 and ::1 interfaces for control, if control is enabled with control-enable. If an interface name is used instead of ip4 or ip6, the list of IP addresses associated with that interface is picked up and used at server start.

With an absolute path, a unix local named pipe is used for control. The file is created with user and group that is configured and access bits are set to allow members of the group access. Further access can be controlled by setting permissions on the directory containing the control socket file. The key and cert files are not used when control is via the named pipe, because access control is via file and directory permission.

control-port: <number>

The port number for remote control service. 8952 by default.

server-key-file: <filename>

Path to the server private key, by default /etc/nsd/nsd_server.key. This file is generated by the nsd-control-setup utility. This file is used by the nsd server, but not by nsd-control.

server-cert-file: <filename>

Path to the server self signed certificate, by default /etc/nsd/nsd_server.pem. This file is generated by the nsd-control-setup utility. This file is used by the nsd server, and also by nsd-control.

control-key-file: <filename>

Path to the control client private key, by default /etc/nsd/nsd_control.key. This file is generated by the nsd-control-setup utility. This file is used by nsd-control.

control-cert-file: <filename>

Path to the control client certificate, by default /etc/nsd/nsd_control.pem. This certificate has to be signed with the server certificate. This file is generated by the nsd-control-setup utility. This file is used by nsd-control.

### Verifier options
The verify: clause is used to enable or disable zone verification, configure listen interfaces and control the global defaults.

enable: <yes or no>

Enable zone verification. Default is no.

port: <number>

The port to answer verifier queries on. Default is 5347.

ip-address:

Interfaces to bind for zone verification (default are the localhost interfaces, usually 127.0.0.1 and ::1). To bind to multiple IP addresses, list them one by one. Optionally, Socket options cannot be specified for verify ip-address

verify-zones: <yes or no>

Verify zones by default.

verifier: <command>

When an update is received for the zone (by IXFR or AXFR) this program will be run to assess the zone with the update. If the program exits with a status code of 0, the zone is considered good and will be served. Any other status code will designate the zone bad and the received update will be discarded. The zone will continue to be served but without the update. The following environment variables are available to verifiers:

VERIFY_ZONE

The domain name of the zone to be verified.

VERIFY_ZONE_ON_STDIN

When the zone can be read from standard input (stdin), this variable is set to "yes", otherwise it is set to "no".

VERIFY_IP_ADDRESSES

The first address on which the zones to be assessed will be served. If IPv6 is available an IPv6 address will be preferred over IPv4.

VERIFY_PORT

The port number for VERIFY_IP_ADDRESS.

VERIFY_IPV6_ADDRESS

The first IPv6 address on which the zones to be assessed will be served.

VERIFY_IPV6_PORT

The port number for VERIFY_IPV6_ADDRESS.

VERIFY_IPV4_ADDRESS

The first IPv4 address of which the zones to be assessed will be served.

VERIFY_IPV4_PORT

The port number for VERIFY_IPV4_ADDRESS.

verifier-count: <number>

Maximum number of verifiers to run concurrently. Default is 1.

verifier-feed-zone: <yes or no>

Feed the updated zone to the verifier over standard input (stdin).

verifier-timeout: <seconds>

The maximum number of seconds a verifier is allowed to run for assessing one zone. If the verifier takes longer, it will be terminated and the zone update will be discarded. The default is 0 seconds which means the verifier may take as long as it needs.

### Pattern Options
The pattern: clause is used to denote a set of options to apply to some zones. The same zone options as for a zone are allowed.

name: <string>

The name of the pattern. This is a (case sensitive) string. The pattern names that start with "_implicit_" are used internally for zones that have no pattern (they are defined in nsd.conf directly).

include-pattern: <pattern-name>

The options from the given pattern are included at this point in this pattern. The referenced pattern must be defined above this one.

<zone option>: <value>

The zone options such as zonefile, allow-query, allow-notify, request-xfr, allow-axfr-fallback, notify, notify-retry, provide-xfr, store-ixfr, ixfr-number, ixfr-size, create-ixfr, zonestats, outgoing-interface, verify-zone, verifier, verifier-feed-zone, verifier-timeout, catalog, and catalog-member-pattern can be given. They are applied to the patterns and zones that include this pattern.

### Zone Options
For every zone the options need to be specified in one zone: clause. The access control list elements can be given multiple times to add multiple servers. These elements need to be added explicitly.

For zones that are configured in the nsd.conf config file their settings are hardcoded (in an implicit pattern for themselves only) and they cannot be deleted via delzone, but remove them from the config file and repattern.

name: <string>

The name of the zone. This is the domain name of the apex of the zone. May end with a '.' (in FQDN notation). For example "example.com", "sub.example.net.". This attribute must be present in each zone.

zonefile: <filename>

The file containing the zone information. If this attribute is present it is used to read and write the zone contents. If the attribute is absent it prevents writing out of the zone. The string is processed so that one string can be used (in a pattern) for a lot of different zones. If the label or character does not exist the percent-character is replaced with a period for output (i.e. for the third character in a two letter domain name). The '/' slash character is escaped as "\047" when it is inside the '%s' string. Directories are created as necessary, when the directory is specified as part of the zonefile string. Useful for "%1/%2/%s.zone" or so.

%s is replaced with the zone name.

%1 is replaced with the first character of the zone name.

%2 is replaced with the second character of the zone name.

%3 is replaced with the third character of the zone name.

%z is replaced with the toplevel domain name of the zone.

%y is replaced with the next label under the toplevel domain.

%x is replaced with the next-next label under the toplevel domain.

allow-query: <ip-spec> <key-name | NOKEY | BLOCKED>

Access control list. When at least one allow-query option is specified, then the specified addresses in the allow-query options are allowed to query the server for the zone. Queries from unlisted or specifically BLOCKED addresses are discarded. If NOKEY is given no TSIG signature is required. BLOCKED supersedes other entries, other entries are scanned for a match in the order of the statements. Without allow-query options, queries are allowed from any IP address without TSIG key (which is the default). The ip-spec is either a plain IP address (IPv4 or IPv6), or can be a subnet of the form 1.2.3.4/24, or masked like 1.2.3.4&255.255.255.0 or a range of the form 1.2.3.4-1.2.3.25. Note the ip-spec ranges do not use spaces around the /, &, @ and - symbols.

allow-notify: <ip-spec> <key-name | NOKEY | BLOCKED>

Access control list. The listed (primary) address is allowed to send notifies to this (secondary) server via UDP or TCP. Notifies from unlisted or specifically BLOCKED addresses are discarded. If NOKEY is given no TSIG signature is required. BLOCKED supersedes other entries, other entries are scanned for a match in the order of the statements. The ip-spec is either a plain IP address (IPv4 or IPv6), or can be a subnet of the form 1.2.3.4/24, or masked like 1.2.3.4&255.255.255.0 or a range of the form 1.2.3.4-1.2.3.25. A port number can be added using a suffix of @number, for example 1.2.3.4@5300 or 1.2.3.4/24@5300 for port 5300. Note the ip-spec ranges do not use spaces around the /, &, @ and - symbols.

request-xfr: [AXFR|UDP] <ip-address> <key-name | NOKEY> [tls-auth-name]

Access control list. The listed address (the primary) is queried for AXFR/IXFR on update. A port number can be added using a suffix of @number, for example 1.2.3.4@5300. The specified key is used during AXFR/IXFR. If tls-auth-name is included, the specified tls-auth clause will be used to perform authenticated XFR-over-TLS. If the AXFR option is given, the server will not be contacted with IXFR queries but only AXFR requests will be made to the server. This allows an NSD secondary to have a primary server that runs NSD. If the AXFR option is left out then both IXFR and AXFR requests are made to the primary server.

If the UDP option is given, the secondary will use UDP to transmit the IXFR requests. You should deploy TSIG when allowing UDP transport, to authenticate notifies and zone transfers. Otherwise, NSD is more vulnerable for Kaminsky-style attacks. If the UDP option is left out then IXFR will be transmitted using TCP.

If a tls-auth-name is given then TLS (by default on port 853) will be used for all zone transfers for the zone. If authentication of the primary, based on the specified tls-auth authentication information, fails the XFR request will not be sent. Support for TLS 1.3 is required for XFR-over-TLS.

allow-axfr-fallback: <yes or no>

This option should be accompanied by request-xfr. It (dis)allows NSD (as secondary) to fallback to AXFR if the primary name server does not support IXFR. Default is yes.

size-limit-xfr: <number>

This option should be accompanied by request-xfr. It specifies XFR temporary file size limit. It can be used to stop very large zone retrieval, that could otherwise use up a lot of memory and disk space. If this option is 0, unlimited. Default value is 0.

notify: <ip-address> <key-name | NOKEY>

Access control list. The listed address (a secondary) is notified of updates to this zone via UDP. A port number can be added using a suffix of @number, for example 1.2.3.4@5300. The specified key is used to sign the notify. Only on secondary configurations will NSD be able to detect zone updates (as it gets notified itself, or refreshes after a time).

notify-retry: <number>

This option should be accompanied by notify. It sets the number of retries when sending notifies.

provide-xfr: <ip-spec> <key-name | NOKEY | BLOCKED> [tls-auth-name]

Access control list. The listed address (a secondary) is allowed to request XFR from this server. Zone data will be provided to the address. The specified key is used during XFR. For unlisted or BLOCKED addresses no data is provided and requests are discarded. BLOCKED supersedes other entries and other entries are scanned for a match in the order of the statements. The ip-spec is either a plain IP address (IPv4 or IPv6), or can be a subnet of the form 1.2.3.4/24, or masked like 1.2.3.4&255.255.255.0 or a range of the form 1.2.3.4-1.2.3.25. A port number can be added using a suffix of @number, for example 1.2.3.4@5300 or 1.2.3.4/24@5300 for port 5300. Note the ip-spec ranges do not use spaces around the /, &, @ and - symbols.

If a tls-auth-name is given then TLS authentication of the secondary will be performed for zone transfer requests for the zone. The remote end must connect to the tls-auth-port and must present a certificate with a SAN (Subject Alternative Name) DNS entry or CN (Common Name) entry equal to auth-domain-name of the defined tls-auth. The certificate validity is also verified with tls-cert-bundle. If authentication of the secondary, based on the specified tls-auth authentication information, fails the XFR zone transfer will be refused. If the connection is performed on the tls-port then no authentication will be performed and the transfer will not be refused. To enforce only authenticated zone transfers, tls-auth-xfr-only should also be enabled. Support for TLS 1.3 is required for XFR-over-TLS.

outgoing-interface: <ip-address>

Access control list. The listed address is used to request AXFR|IXFR (in case of a secondary) or used to send notifies (in case of a primary). The ip-address is a plain IP address (IPv4 or IPv6). A port number can be added using a suffix of @number, for example 1.2.3.4@5300.

store-ixfr: <yes or no>

If enabled, IXFR contents are stored and provided to the set of clients specified in the provide-xfr statement. Default is no. IXFR content is a smaller set of changes that differ between zone versions, whereas an AXFR contains the full contents of the zone.

ixfr-number: <number>

The number of IXFR versions to store for this zone, at most. Default is 5.

ixfr-size: <number>

The max storage to use for IXFR versions for this zone, in bytes. Default is 1048576. A value of 0 means unlimited. If you want to turn off IXFR storage, set the store-ixfr option to no. NSD does not elide IXFR contents from versions that add and remove the same data. It stores and transmits IXFRs as they were transmitted by the upstream server.

create-ixfr: <yes or no>

If enabled, IXFR data is created when a zonefile is read by the server. This requires store-ixfr to be set to yes, so that the IXFR contents are saved to disk. Default is off. If the server is not running, the nsd-checkzone -i option can be used to create an IXFR file. When an IXFR is created, the server spools a version of the zone to a temporary file, at the location where the ixfr files are stored. This creates IXFR data when the zone is read from file, but not when a zone is read by AXFR transfer from a server, because then the topmost server that originates the data is the one place where IXFR differences are computed and those differences are then transmitted verbatim to all the other servers.

max-refresh-time: <seconds>

Limit refresh time for secondary zones. This is the timer which checks to see if the zone has to be refetched when it expires. Normally the value from the SOA record is used, but this option restricts that value.

min-refresh-time: <seconds>

Limit refresh time for secondary zones.

max-retry-time: <seconds>

Limit retry time for secondary zones. This is the timer which retries after a failed fetch attempt for the zone. Normally the value from the SOA record is used, followed by an exponential backoff, but this option restricts that value.

min-retry-time: <seconds>

Limit retry time for secondary zones.

min-expire-time: <seconds or refresh+retry+1>

Limit expire time for secondary zones. The value can be expressed either by a number of seconds, or the string "refresh+retry+1". With the latter the expire time will be lower bound to the refresh plus the retry value from the SOA record, plus 1. The refresh and retry values will be subject to the bounds configured with max-refresh-time, min-refresh-time, max-retry-time and min-retry-time if given.

zonestats: <name>

When not compiled without zone-stats NSD can collect statistics per zone. This name gives the group where statistics are added to. The groups are output from nsd-control stats and stats_noreset. Default is "". You can use "%s" to use the name of the zone to track its statistics. If not compiled in, the option can be given but is ignored.

include-pattern: <pattern-name>

The options from the given pattern are included at this point. The referenced pattern must be defined above this zone.

rrl-whitelist: <rrltype>

This option causes queries of this rrltype to be whitelisted, for this zone. They receive the whitelist-ratelimit. You can give multiple lines, each enables a new rrltype to be whitelisted for the zone. Default has none whitelisted. The rrltype is the query classification that the NSD RRL employs to make different types not interfere with one another. The types are logged in the loglines when a subnet is blocked (in verbosity 2). The RRL classification types are: nxdomain, error, referral, any, rrsig, wildcard, nodata, dnskey, positive, all.

multi-primary-check: <yes or no>

Default no. If enabled, checks all primaries for the last version. It uses the higher version of all the configured primaries. Useful if you have multiple primaries that have different version numbers served.

verify-zone: <yes or no>

Enable or disable verification for this zone. Default is value-zones configured in verify:.

verifier: <command>

Command to execute to assess this zone. Default is verifier configured in verify:.

verifier-feed-zone: <yes or no>

Feed updated zone to verifier over standard input. Default is verifier-feed-zone configured in verify:.

verifier-timeout: <seconds>

Number of seconds before verifier is forcefully terminated. Specify 0 (zero) to not use a specific timeout. Default is verifier-timeout from verify:.

catalog: <consumer or producer>

If set to consumer, catalog zone processing is enabled for the zone. Only a single zone may be configured as a catalog consumer zone. When more than one catalog consumer zone is configured, none of them will be processed. Member zones of the catalog will use the pattern specified by the group property, or if a group property is missing or invalid, the pattern specified by the catalog-member-pattern option is used. Group properties are valid if there is only a single value matching the name of a for member zones valid pattern. A zone with the option set to producer, can be used to produce a catalog zone. Member zones for catalog producer zones can be added with "nsd-control addzone <zone> <pattern>", where <pattern> has a catalog-producer-zone option pointing to a catalog producer zone. Members will get a group property with the pattern name as value. Catalog producer zones must be primary zones and may not have a request-xfr option. Catalog producer zones will not read content from zone files, but will reconstruct the zone on startup from the member zone entries in /var/db/nsd/zone.list, specified with the zonelistfile option.

The status of both catalog consumer and producer zones can be verified with nsd-control zonestatus. It will show the number of member zones and, if the catalog zone is invalid, the reason for it to be invalid is shown. nsd-control zonestatus will also show the entry of a catalog member zone in the catalog (consumer or producer) zone as catalog-member-id:.

A catalog zone can either be catalog consumer zone or a catalog producer zone but not both. Likewise, catalog member zones can be either a member of catalog consumer zone or a catalog producer zone but not both.

Catalog zones contain a list of zones that are served. Use allow-query: 0.0.0.0/0 BLOCKED and allow-query: ::0/0 BLOCKED in a catalog zone zone or pattern clause to prevent revealing the catalog. Also consider using transfers over TLS to further protect the catalog against eavesdroppers.

catalog-member-pattern: <pattern-name>

If this option is provided for a catalog consumer zone, members of that catalog that have a missing or an invalid group property will be added using pattern <pattern-name>.

catalog-producer-zone: <zone-name>

This option can only be used in a pattern. Adding a zone using "nsd-control addzone <zone> <pattern>" with a <pattern> containing this option, will cause a catalog member entry to be created in the catalog producer zone <zone-name>. <zone-name> must exist and must be a valid catalog producer zone.

### Key Declarations
The key: clause establishes a key for use in access control lists. It has the following attributes.

name: <string>

The key name. Used to refer to this key in the access control list. The key name has to be correct for tsig to work. This is because the key name is output on the wire.

algorithm: <string>

Authentication algorithm for this key. Such as hmac-md5, hmac-sha1, hmac-sha224, hmac-sha256, hmac-sha384 and hmac-sha512. Can also be abbreviated as 'sha1', 'sha256'. Default is sha256. Algorithms are only available when they were compiled in (available in the crypto library).

secret: <base64 blob>

The base64 encoded shared secret. It is possible to put the secret: declaration (and base64 blob) into a different file, and then to include: that file. In this way the key secret and the rest of the configuration file, which may have different security policies, can be split apart. The content of the secret is the agreed base64 secret content. To make it up, enter a password (its length must be a multiple of 4 characters, A-Za-z0-9), or use dev-random output through a base64 encode filter.

### TLS Auth Declarations
The tls-auth: clause establishes attributes to use when authenticating the far end of a TLS connection as well as to define credentials to authenticate to a remote server. It is used in access control lists for XFR-over-TLS. It has the following attributes.

name: <string>

The tls-auth name. Used to refer to this TLS authentication information in the access control list.

auth-domain-name: <string>

The authentication domain name as defined in RFC8310. Used to verify the certificate of the remote connecting server. When used by a primary server in provide-xfr it verifies the secondary. When used by a secondary server in request-xfr it verifies the primary.

client-cert: <file name of clientcert.pem>

If you want to use mutual TLS authentication, this is where the client certificates can be configured that NSD uses to connect to the upstream server to download the zone. The client public key pem cert file can be configured here. Also configure a private key with client-key.

client-key: <file name of clientkey.key>

If you want to use mutual TLS authentication, the private key file can be configured here for the client authentication.

client-key-pw: <string>

If the client-key file uses a password to decrypt the key before it can be used, then the password can be specified here as a string. It is possible to include other config files with the include: option, and this can be used to move that sensitive data to another file, if you wish.

### DNSTAP Logging Options
DNSTAP support, when compiled in, is enabled in the dnstap: section. This starts a collector process that writes the log information to the destination.

dnstap-enable: <yes or no>

If dnstap is enabled. Default no. If yes, it connects to the dnstap server and if any of the dnstap-log-..-messages options is enabled it sends logs for those messages to the server.

dnstap-socket-path: <file name>

Sets the unix socket file name for connecting to the server that is listening on that socket. Default is "/var/run/nsd-dnstap.sock".

dnstap-ip: <"" or addr[@port]>

If disabled with "", the socket path is used. With a value, like address or address@port, like "127.0.0.1@3333" TCP or TLS is used. Default is "".

dnstap-tls: <yes or no>

If enabled, TLS is used to the address specified in dnstap-ip. Otherwise, TCP is used. Default is yes.

dnstap-tls-server-name: <string>

The name for authenticating the upstream server. With "" disabled.

dnstap-tls-client-key-file: <file name>

The key file for client authentication, or "" disabled.

dnstap-tls-client-cert-file: <file name>

The cert file for client authentication, or "" disabled.

dnstap-send-identity: <yes or no>

If enabled, the server identity is included in the log messages. Default is no.

dnstap-send-version: <yes or no>

If enabled, the server version if included in the log messages. Default is no.

dnstap-identity: <string>

The identity to send with messages, if "" the hostname is used. Default is "".

dnstap-version: <string>

The version to send with messages, if "" the package version is used. Default is "".

dnstap-log-auth-query-messages: <yes or no>

Enable to log auth query messages. Default is no. These are client queries to NSD.

dnstap-log-auth-response-messages: <yes or no>

Enable to log auth response messages. Default is no. These are responses from NSD to clients.

## NSD CONFIGURATION FOR BIND9 HACKERS
BIND9 is a name server implementation with its own configuration file format, named.conf(5). BIND9 types zones as 'Primary' or 'Secondary'.

### Secondary zones
For a secondary zone, the primary servers are listed. The primary servers are queried for zone data, and are listened to for update notifications. In NSD these two properties need to be configured separately, by listing the primary address in allow-notify and request-xfr statements.

In BIND9 you only need to provide allow-notify elements for any extra sources of notifications (i.e. the operators), NSD needs to have allow-notify for both primaries and operators. BIND9 allows additional transfer sources, in NSD you list those as request-xfr.

Here is an example of a secondary zone in BIND9 syntax.

```
# Config file for example.org
options {
	dnssec-enable yes;
};

key tsig.example.org. {
	algorithm hmac-md5;
	secret "aaaaaabbbbbbccccccdddddd";
};

server 162.0.4.49 {
	keys { tsig.example.org. ; };
};

zone "example.org" {
	type secondary;
	file "secondary/example.org.signed";
	primaries { 162.0.4.49; };
};
```

For NSD, DNSSEC is enabled automatically for zones that are signed. The dnssec-enable statement in the options clause is not needed. In NSD keys are associated with an IP address in the access control list statement, therefore the server{} statement is not needed. Below is the same example in an NSD config file.

```
# Config file for example.org
key:
	name: tsig.example.org.
	algorithm: hmac-md5
	secret: "aaaaaabbbbbbccccccdddddd"

zone:
	name: "example.org"
	zonefile: "secondary/example.org.signed"
	# the primary is allowed to notify and will provide zone data.
	allow-notify: 162.0.4.49 NOKEY
	request-xfr: 162.0.4.49 tsig.example.org.
```

Notice that the primary is listed twice, once to allow it to send notifies to this secondary server and once to tell the secondary server where to look for updates zone data. More allow-notify and request-xfr lines can be added to specify more primaries.

It is possible to specify extra allow-notify lines for addresses that are also allowed to send notifications to this secondary server.

### Primary zones
For a primary zone in BIND9, the secondary servers are listed. These secondary servers are sent notifications of updated and are allowed to request transfer of the zone data. In NSD these two properties need to be configured separately.

Here is an example of a primary zone in BIND9 syntax.

```
zone "example.nl" {
	type primary;
	file "example.nl";
};
```

In NSD syntax this becomes:

```
zone:
	name: "example.nl"
	zonefile: "example.nl"
	# allow anybody to request xfr.
	provide-xfr: 0.0.0.0/0 NOKEY
	provide-xfr: ::0/0 NOKEY

# to list a secondary server you would in general give
# provide-xfr: 1.2.3.4 tsig-key.name.
# notify: 1.2.3.4 NOKEY
```

### Other
NSD is an authoritative only DNS server. This means that it is meant as a primary or secondary server for zones, providing DNS data to DNS resolvers and caches. BIND9 can function as an authoritative DNS server, the configuration options for that are compared with those for NSD in this section. However, BIND9 can also function as a resolver or cache. The configuration options that BIND9 has for the resolver or caching thus have no equivalents for NSD.

## FILES
/etc/nsd/nsd.conf

default NSD configuration file

## SEE ALSO
nsd(8), nsd-checkconf(8), nsd-checkzone(8), nsd-control(8)

## AUTHORS
NSD was written by a combined team from NLnet Labs and RIPE NCC. Please see the CREDITS file in the distribution for further details.

## BUGS
nsd.conf is parsed by a primitive parser. Error messages may not be to the point.


nslcd.conf

package: nss-ldapd

title: nslcd.conf(5)

text:
# nslcd.conf(5)

## NAME
nslcd.conf - configuration file for LDAP nameservice daemon

## DESCRIPTION
The nss-pam-ldapd package allows LDAP directory servers to be used as a primary source of name service information. (Name service information typically includes users, hosts, groups, and other such data historically stored in flat files or NIS.)

The file nslcd.conf contains the configuration information for running nslcd (see nslcd(8)). The file contains options, one on each line, defining the way NSS lookups and PAM actions are mapped to LDAP lookups.

## OPTIONS

### RUNTIME OPTIONS
threads NUM

Specifies the number of threads to start that can handle requests and perform LDAP queries. Each thread opens a separate connection to the LDAP server. The default is to start 5 threads.

uid UID

This specifies the user id with which the daemon should be run. This can be a numerical id or a symbolic value. If no uid is specified no attempt to change the user will be made. Note that you should use values that don't need LDAP to resolve.

gid GID

This specifies the group id with which the daemon should be run. This can be a numerical id or a symbolic value. If no gid is specified no attempt to change the group will be made. Note that you should use values that don't need LDAP to resolve.

log SCHEME [LEVEL]

This option controls the way logging is done. The SCHEME argument may either be none, syslog or an absolute file name. The LEVEL argument is optional and specifies the log level. The log level may be one of: crit, error, warning, notice, info or debug. The default log level is info. All messages with the specified loglevel or higher are logged. This option can be supplied multiple times. If this option is omitted syslog info is assumed.

### GENERAL CONNECTION OPTIONS
uri URI ...

Specifies the LDAP URI of the server to connect to. The URI scheme may be ldap, ldapi or ldaps, specifying LDAP over TCP, ICP or SSL respectively (if supported by the LDAP library). Alternatively, the value DNS may be used to try to lookup the server using DNS SRV records. By default the current domain is used but another domain can be queried by using the DNS:DOMAIN syntax. To convert SRV records for port 389 into an ldaps:// URI, DNSLDAPS can be used.

When using the ldapi scheme, %2f should be used to escape slashes (e.g. ldapi://%2fvar%2frun%2fslapd%2fldapi/), although most of the time this should not be needed.

This option may be specified multiple times and/or with more URIs on the line, separated by spaces. Normally, only the first server will be used with the following servers as fall-back (see bind_timelimit below).

If LDAP lookups are used for host name resolution, any host names should be specified as an IP address or name that can be resolved without using LDAP.

ldap_version VERSION

Specifies the version of the LDAP protocol to use. The default is to use the maximum version supported by the LDAP library.

binddn DN

Specifies the distinguished name with which to bind to the directory server for lookups. The default is to bind anonymously.

bindpw PASSWORD

Specifies the credentials with which to bind. This option is only applicable when used with binddn above. If you set this option you should consider changing the permissions of the nslcd.conf file to only grant access to the root user.

rootpwmoddn DN

Specifies the distinguished name to use when the root user tries to modify a user's password using the PAM module. Note that currently this DN needs to exist as a real entry in the LDAP directory.

rootpwmodpw PASSWORD

Specifies the credentials with which to bind if the root user tries to change a user's password. This option is only applicable when used with rootpwmoddn above. If this option is not specified the PAM module prompts the user for this password. If you set this option you should consider changing the permissions of the nslcd.conf file to only grant access to the root user.

### SASL AUTHENTICATION OPTIONS
sasl_mech MECHANISM

Specifies the SASL mechanism to be used when performing SASL authentication.

sasl_realm REALM

Specifies the SASL realm to be used when performing SASL authentication.

sasl_authcid AUTHCID

Specifies the authentication identity to be used when performing SASL authentication.

sasl_authzid AUTHZID

Specifies the authorization identity to be used when performing SASL authentication. Must be specified in one of the formats: dn:<distinguished name> or u:<username>.

sasl_secprops PROPERTIES

Specifies Cyrus SASL security properties. Allowed values are described in the ldap.conf(5) manual page.

sasl_canonicalize yes|no

Determines whether the LDAP server host name should be canonicalised. If this is set to yes the LDAP library will do a reverse host name lookup. By default, it is left up to the LDAP library whether this check is performed or not.

### KERBEROS AUTHENTICATION OPTIONS
krb5_ccname NAME

Set the name for the GSS-API Kerberos credentials cache.

### SEARCH/MAPPING OPTIONS
base [MAP] DN

Specifies the distinguished name (DN) to use as search base. This option may be supplied multiple times and all specified bases will be searched. A global search base may be specified or a MAP-specific one. If no MAP-specific search bases are defined the global ones are used.

If, instead of a DN, the value DOMAIN is specified, the host's DNS domain is used to construct a search base. A value of "" can be used to indicate an empty search base (quotes are not otherwise supported for base values and not all LDAP server configurations support this).

If this value is not defined an attempt is made to look it up in the configured LDAP server. If the LDAP server is unavailable during start-up nslcd will not start.

scope [MAP] sub[tree]|one[level]|base|children

Specifies the search scope (subtree, onelevel, base or children). The default scope is subtree; base scope is almost never useful for name service lookups; children scope is not supported on all servers.

deref never|searching|finding|always

Specifies the policy for dereferencing aliases. The default policy is to never dereference aliases.

referrals yes|no

Specifies whether automatic referral chasing should be enabled. The default behaviour is to chase referrals.

filter MAP FILTER

The FILTER is an LDAP search filter to use for a specific map. The default filter is a basic search on the objectClass for the map (e.g. (objectClass=posixAccount)).

map MAP ATTRIBUTE NEWATTRIBUTE

This option allows for custom attributes to be looked up instead of the default RFC 2307 attributes. The MAP may be one of the supported maps below. The ATTRIBUTE is the one as used in RFC 2307 (e.g. userPassword, ipProtocolNumber, macAddress, etc.). The NEWATTRIBUTE may be any attribute as it is available in the directory. If the NEWATTRIBUTE is presented in quotes (") it is treated as an expression which will be evaluated to build up the actual value used. See the section on attribute mapping expressions below for more details.

Only some attributes for group, passwd and shadow entries may be mapped with an expression (because other attributes may be used in search filters). For group entries only the userPassword attribute may be mapped with an expression. For passwd entries the following attributes may be mapped with an expression: userPassword, gidNumber, gecos, homeDirectory and loginShell. For shadow entries the following attributes may be mapped with an expression: userPassword, shadowLastChange, shadowMin, shadowMax, shadowWarning, shadowInactive, shadowExpire and shadowFlag.

The uidNumber and gidNumber attributes in the passwd and group maps may be mapped to the objectSid followed by the domain SID to derive numeric user and group ids from the SID (e.g. objectSid:S-1-5-21-3623811015-3361044348-30300820).

By default all userPassword attributes are mapped to the unmatchable password ("*") to avoid accidentally leaking password information.

### TIMING/RECONNECT OPTIONS
bind_timelimit SECONDS

Specifies the time limit (in seconds) to use when connecting to the directory server. This is distinct from the time limit specified in timelimit and affects the set-up of the connection only. Note that not all LDAP client libraries have support for setting the connection time out. The default bind_timelimit is 10 seconds.

timelimit SECONDS

Specifies the time limit (in seconds) to wait for a response from the LDAP server. A value of zero (0), which is the default, is to wait indefinitely for searches to be completed.

idle_timelimit SECONDS

Specifies the period of inactivity (in seconds) after which the connection to the LDAP server will be closed. The default is not to time out connections.

reconnect_sleeptime SECONDS

Specifies the number of seconds to sleep when connecting to all LDAP servers fails. By default 1 second is waited between the first failure and the first retry.

reconnect_retrytime SECONDS

Specifies the time after which the LDAP server is considered to be permanently unavailable. Once this time is reached retries will be done only once per this time period. The default value is 10 seconds.

Note that the reconnect logic as described above is the mechanism that is used between nslcd and the LDAP server. The mechanism between the NSS and PAM client libraries on one end and nslcd on the other is simpler with a fixed compiled-in time out of a 10 seconds for writing to nslcd and a time out of 60 seconds for reading answers. nslcd itself has a read time out of 0.5 seconds and a write time out of 60 seconds.

### SSL/TLS OPTIONS
ssl on|off|start_tls

Specifies whether to use SSL/TLS or not (the default is not to). If start_tls is specified then StartTLS is used rather than raw LDAP over SSL. Not all LDAP client libraries support both SSL, StartTLS and all related configuration options.

tls_reqcert never|allow|try|demand|hard

Specifies what checks to perform on a server-supplied certificate. The meaning of the values is described in the ldap.conf(5) manual page. At least one of tls_cacertdir and tls_cacertfile is required if peer verification is enabled.

tls_cacertdir PATH

Specifies the directory containing X.509 certificates for peer authentication. This parameter is ignored when using GnuTLS. On Debian OpenLDAP is linked against GnuTLS.

tls_cacertfile PATH

Specifies the path to the X.509 certificate for peer authentication.

tls_randfile PATH

Specifies the path to an entropy source. This parameter is ignored when using GnuTLS. On Debian OpenLDAP is linked against GnuTLS.

tls_ciphers CIPHERS

Specifies the ciphers to use for TLS. See your TLS implementation's documentation for further information.

tls_cert PATH

Specifies the path to the file containing the local certificate for client TLS authentication.

tls_key PATH

Specifies the path to the file containing the private key for client TLS authentication.

tls_reqsan never|allow|try|demand|hard

Specifies the way server Subject Alternative Name (SAN) is checked in the server-supplied certificate. The meaning of the values is described in the ldap.conf(5) manual page.

tls_crlcheck none|peer|all

Specifies if the Certificate Revocation List (CRL) of the CA should be used to verify if the server certificates have not been revoked. The meaning of the values is described in the ldap.conf(5) manual page.

tls_crlfile PATH

Specifies the path to the file containing a Certificate Revocation List to be used to verify if the server certificates. The meaning of the values is described in the ldap.conf(5) manual page.

### OTHER OPTIONS
pagesize NUMBER

Set this to a number greater than 0 to request paged results from the LDAP server in accordance with RFC2696. The default (0) is to not request paged results. This is useful for LDAP servers that contain a lot of entries (e.g. more than 500) and limit the number of entries that are returned with one request. For OpenLDAP servers you may need to set sizelimit size.prtotal=unlimited for allowing more entries to be returned over multiple pages.

nss_initgroups_ignoreusers user1,user2,...

This option prevents group membership lookups through LDAP for the specified users. This can be useful in case of unavailability of the LDAP server. This option may be specified multiple times. Alternatively, the value ALLLOCAL may be used. With that value nslcd builds a full list of non-LDAP users on startup.

nss_min_uid UID

This option ensures that LDAP users with a numeric user id lower than the specified value are ignored. Also requests for users with a lower user id are ignored.

nss_uid_offset NUMBER

This option specifies an offset that is added to all LDAP numeric user ids. This can be used to avoid user id collisions with local users or, when using objectSid attributes, for compatibility reasons. The value from the nss_min_uid option is evaluated after applying the offset.

nss_gid_offset NUMBER

This option specifies an offset that is added to all LDAP numeric group ids. This can be used to avoid user id collisions with local groups or, when using objectSid attributes, for compatibility reasons.

nss_nested_groups yes|no

If this option is set, the member attribute of a group may point to another group. Members of nested groups are also returned in the higher level group and parent groups are returned when finding groups for a specific user. The default is not to perform extra searches for nested groups.

nss_getgrent_skipmembers yes|no

If this option is set, the group member list is not retrieved when looking up groups. Lookups for finding which groups a user belongs to will remain functional so the user will likely still get the correct groups assigned on login. This can offer a speed-up on systems that have very large groups. It has the downside of returning inconsistent information about group membership which may confuse some applications. This option is not recommended for most configurations.

nss_disable_enumeration yes|no

If this option is set, functions which cause all user/group entries to be loaded (getpwent(), getgrent(), setspent()) from the directory will not succeed in doing so. Applications that depend on being able to sequentially read all users and/or groups may fail to operate correctly. This can dramatically reduce LDAP server load in situations where there are a great number of users and/or groups. This is typically used in situations where user/program access to enumerate the entire directory is undesirable, and changing the behavior of the user/program is not possible. This option is not recommended for most configurations.

validnames REGEX

This option can be used to specify how user and group names are verified within the system. This pattern is used to check all user and group names that are requested and returned from LDAP. The regular expression should be specified as a POSIX extended regular expression. The expression itself needs to be separated by slash (/) characters and the 'i' flag may be appended at the end to indicate that the match should be case-insensitive. The default value is /^[a-z0-9._@$()]([a-z0-9._@$() \\~-]*[a-z0-9._@$()~-])?$/i

ignorecase yes|no

This specifies whether or not to perform searches for group, netgroup, passwd, protocols, rpc, services and shadow maps using case-insensitive matching. Setting this to yes could open up the system to authorisation bypass vulnerabilities and introduce nscd cache poisoning vulnerabilities which allow denial of service. The default is to perform case-sensitive filtering of LDAP search results for the above maps.

pam_authc_ppolicy yes|no

This option specifies whether password policy controls are requested and handled from the LDAP server when performing user authentication. By default the controls are requested and handled if available.

pam_authc_search FILTER

By default nslcd performs an LDAP search with the user's credentials after BIND (authentication) to ensure that the BIND operation was successful. The default search is a simple check to see if the user's DN exists. A search filter can be specified that will be used instead. The same substitutions as with the pam_authz_search option will be performed and the search should at least return one entry.

The value BASE may be used to force the default search for the user DN.

The value NONE may be used to indicate that no search should be performed after BIND. Note that some LDAP servers do not always return a correct error code as a result of a failed BIND operation (e.g. when an empty password is supplied).

pam_authz_search FILTER

This option allows flexible fine tuning of the authorisation check that should be performed. The search filter specified is executed and if any entries match, access is granted, otherwise access is denied. The search filter can contain the following variable references: $username, $service, $ruser, $rhost, $tty, $hostname, $fqdn, $domain, $dn, and $uid. These references are substituted in the search filter using the same syntax as described in the section on attribute mapping expressions below.

For example, to check that the user has a proper authorizedService value if the attribute is present (this almost emulates the pam_check_service_attr option in PADL's pam_ldap):

```
(&(objectClass=posixAccount)(uid=$username)(|(authorizedService=$service)(!(authorizedService=*))))
```

The pam_check_host_attr option can be emulated with:

```
(&(objectClass=posixAccount)(uid=$username)(|(host=$hostname)(host=$fqdn)(host=\\*)))
```

This option may be specified multiple times and all specified searches should at least return one entry for access to be granted.

pam_password_prohibit_message "MESSAGE"

If this option is set password modification using pam_ldap will be denied and the specified message will be presented to the user instead. The message can be used to direct the user to an alternative means of changing their password.

reconnect_invalidate DB,DB,...

If this option is set, nslcd will try to flush the specified external caches on start-up and whenever a connection to the LDAP server is re-established after an error. DB can refer to one of the nsswitch maps, in which case nscd is contacted to flush its cache for the specified database. If DB is nfsidmap, nfsidmap is contacted to clear its cache.

Using this option ensures that external caches are cleared of incorrect information (typically the absence of users) that may be present due to unavailability of the LDAP server.

cache CACHE TIME [TIME]

Configure the time entries are kept in the specified internal cache. The first TIME value specifies the time to keep found entries in the cache. The second TIME value specifies to the time to remember that a particular entry was not found. If the second parameter is absent, it is assumed to be the same as the first.

Time values are specified as a number followed by an s for seconds, m for minutes, h for hours or d for days. Use 0 or off to disable the cache.

Currently, only the dn2uid cache is supported that is used to remember DN to username lookups that are used when the member attribute is used. The default time value for this cache is 15m.

## SUPPORTED MAPS
The following maps are supported. They are referenced as MAP in the options above.

alias[es]

Mail aliases. Note that most mail servers do not use the NSS interface for requesting mail aliases and parse /etc/aliases on their own.

ether[s]

Ethernet numbers (mac addresses).

group

Posix groups.

host[s]

Host names.

netgroup

Host and user groups used for access control.

network[s]

Network numbers.

passwd

Posix users.

protocol[s]

Protocol definitions (like in /etc/protocols).

rpc

Remote procedure call names and numbers.

service[s]

Network service names and numbers.

shadow

Shadow user password information.

## ATTRIBUTE MAPPING EXPRESSIONS
For some attributes a mapping expression may be used to construct the resulting value. This is currently only possible for attributes that do not need to be used in search filters. The expressions are a subset of the double quoted string expressions in the Bourne (POSIX) shell. Instead of variable substitution, attribute lookups are done on the current entry and the attribute value is substituted. The following expressions are supported:

${attr} (or $attr for short)

will substitute the value of the attribute

${attr:-word}

(use default) will substitute the value of the attribute or, if the attribute is not set or empty substitute the word

${attr:+word}

(use alternative) will substitute word if attribute is set, otherwise substitute the empty string

${attr:offset:length}

will substitute length characters (actually bytes) starting from position offset (which is counted starting at zero); the substituted string is truncated if it is too long; in particular, it can be of length zero (if length is zero or offset falls out of the original string)

${attr#word}

remove the shortest possible match of word from the left of the attribute value

${attr##word}

remove the longest possible match of word from the left of the attribute value (pynslcd only)

${attr%word}

remove the shortest possible match of word from the right of the attribute value (pynslcd only)

${attr%%word}

remove the longest possible match of word from the right of the attribute value (pynslcd only)

Only the # matching expression is supported in nslcd and only with the ? wildcard symbol. The pynslcd implementation supports full matching.

Quote ("), dollar ($) and backslash (\) characters should be escaped with a backslash (\).

The expressions are inspected to automatically fetch the appropriate attributes from LDAP. Some examples to demonstrate how these expressions may be used in attribute mapping:

"${shadowFlag:-0}"

use the shadowFlag attribute, using the value 0 as default

"${homeDirectory:-/home/$uid}"

use the uid attribute to build a homeDirectory value if that attribute is missing

"${isDisabled:+100}"

if the isDisabled attribute is set, return 100, otherwise leave value empty

"${userPassword#{crypt\}}"

strip the {crypt} prefix from the userPassword attribute, returning the raw hash value

## FILES
/etc/nslcd.conf

the main configuration file

/etc/nsswitch.conf

Name Service Switch configuration file

## SEE ALSO
nslcd(8), nsswitch.conf(5)

## AUTHOR
This manual was written by Arthur de Jong <arthur@arthurdejong.org> and is based on the nss_ldap(5) manual developed by PADL Software Pty Ltd.


title: nss_ldap(5)

summary: LDAP nameservice provider

text:
# nss_ldap(5)

## NAME
nss_ldap - LDAP nameservice provider

## DESCRIPTION
The nss_ldap module is a set of C library extensions which allows X.500 and LDAP directory servers to be used as a primary source of name service information. (Name service information typically includes users, hosts, groups, and other such data historically stored in flat files or NIS.)

Features of the PADL nss_ldap module include support for both the RFC 2307 and RFC 2307bis schema, a common implementation across multiple platforms, Kerberos and SSL security, configurable schema mapping, and configuration file compatibility with the pam_ldap(5) module.

Because LDAP is a hierarchical directory service, one can distribute the information in a manner which reflects organizational structure. This contrasts with the flat, single domain policy of NIS. LDAP has many of the advantages of NIS+ (security and scalability) without the complexity.

nss_ldap will work alongside existing NIS, NIS+, DNS and flat file name services. More importantly, because it builds as a shared library, it is not necessary to recompile any applications to take advantage of LDAP.

The present version of nss_ldap supports AIX 4.3.3 and above, FreeBSD 5.1, HP-UX 11i, Linux and Solaris 2.6 and above. Many vendors provide their own LDAP nameservice providers, often also called nss_ldap. This manual page applies to the PADL nss_ldap module only. If you are using a vendor provided module, consult the relevant documentation instead.

The features supported by the version of nss_ldap depend on which flags were enabled when the software was built. Most features are enabled in the configuration file, described below. (The location of the configuration file is configurable at compile time; the default path is /etc/ldap.conf.) Also, some features may be unavailable on certain operating systems or with certain LDAP libraries. For more information, consult your vendor.

## CONFIGURATION
nss_ldap stores its configuration in the ldap.conf file, the location of which is configurable at compile time. (It should be noted that some LDAP client libraries, such as OpenLDAP, also use a configuration file of the same name. nss_ldap supports many of the same configuration file options as OpenLDAP, but it adds several that are specific to the functionality it provides. Additionally, it is not guaranteed that nss_ldap will continue to match the configuration file semantics of OpenLDAP. You may wish to use different files.)

Configuration file options consist of a keyword followed by a space and any arguments. The following options are supported by both nss_ldap and the PADL pam_ldap module:

host <name:port ...>

Specifies the name(s) or IP address(es) of the LDAP server(s) to connect to. In the case that nss_ldap is used for host name resolution, each server should be specified as an IP address or name that can be resolved without using LDAP. Multiple servers may be specified, each separated by a space. The failover time depends on whether the LDAP client library supports configurable network or connect timeouts (see bind_timelimit below).

base <base>

Specifies the default base distinguished name (DN) to use for searches.

uri <ldap[is]://[name[:port]] ...>

For LDAP client libraries that support it, specifies the URI(s) of the LDAP server(s) to connect to. The URI scheme may be ldap, ldapi, or ldaps, specifying LDAP over TCP, IPC and SSL respectively. If applicable, a port number can be specified; the default port number for the selected protocol is used if omitted. This option takes precedence over the host option; it is not possible to combine the two.

ldap_version <version>

Specifies the version of the LDAP protocol to use. Presently version must be 2 or 3. The default is to use the maximum version supported by the client library.

binddn <binddn>

Specifies the distinguished name with which to bind to the directory server(s). This option is optional; the default is to bind anonymously.

bindpw <bindpw>

Specifies the cleartext credentials with which to bind. This option is only applicable when used with binddn above. The default is no credential (anonymous bind). When binding to the directory using SASL or other authentication mechanisms apart from simple binds, this option is not used.

rootbinddn <binddn>

This option has the same syntax and effect as the binddn option above, except it applies when the effective user ID is zero. If not specified, then the identity specified in binddn is used instead. Because the configuration file may be readable by many users, the root bind DN credentials are stored in the ldap.secret file instead. This file is usually in the same directory as the configuration file.

port <port>

Specifies the port to connect to; this option is used with the host option, and is ignored with the uri option.

scope <sub|one|base>

Specifies the search scope (subtree, one level or base object). The default scope is subtree; base scope is almost never useful for nameservice lookups.

deref <never|searching|finding|always>

Specifies the policy for dereferencing aliases. The default policy is to never dereference aliases.

timelimit <timelimit>

Specifies the time limit (in seconds) to use when performing searches. A value of zero (0), which is the default, is to wait indefinitely for searches to be completed.

bind_timelimit <timelimit>

Specifies the time limit (in seconds) to use when connecting to the directory server. This is distinct from the time limit specified in timelimit and affects the initial server connection only. (Server connections are otherwise cached.) Only some LDAP client libraries have the underlying functionality necessary to support this option. The default bind timelimit is 30 seconds.

referrals <yes|no>

Specifies whether automatic referral chasing should be enabled. The default behaviour is specified by the LDAP client library.

restart <yes|no>

Specifies whether the LDAP client library should restart the select(2) system call when interrupted. This feature is not supported by all client libraries.

logdir <directory>

Specifies the directory used for logging by the LDAP client library. This feature is not supported by all client libraries.

debug <level>

Specifies the debug level used for logging by the LDAP client library. This feature is not supported by all client libraries, and does not apply to the nss_ldap and pam_ldap modules themselves (debugging, if any, is configured separately and usually at compile time).

ssl <on|off|start_tls>

Specifies whether to use SSL/TLS or not (the default is not to). If start_tls is specified then StartTLS is used rather than raw LDAP over SSL. Not all LDAP client libraries support both SSL and StartTLS, and all related configuration options.

sslpath <cert7_path>

For the Netscape and Mozilla LDAP client libraries only, this specifies the path to the X.509 certificate database.

tls_checkpeer <yes|no>

Specifies whether to require and verify the server certificate or not, when using SSL/TLS with the OpenLDAP client library. The default is to use the default behaviour of the client library; for OpenLDAP 2.0 and earlier it is "no", for OpenLDAP 2.1 and later it is "yes". At least one of tls_cacertdir and tls_cacertfile is required if peer verification is enabled.

tls_cacertdir <certificate_dir>

Specifies the directory containing X.509 certificates for peer authentication.

tls_cacertfile <certificate_file>

Specifies the path to the X.509 certificate for peer authentication.

tls_randfile <entropy_file>

Specifies the path to an entropy source.

tls_ciphers <ciphers>

Specifies the ciphers to use for TLS. See your TLS implementation's documentation for further information.

tls_cert <certificate_file>

Specifies the path to the file containing the local certificate for client TLS authentication.

tls_key <key_file>

Specifies the path to the file containing the private key for client TLS authentication.

The following configuration options apply to nss_ldap only:

bind_policy <hard_open|hard_init|soft>

Specifies the policy to use for reconnecting to an unavailable LDAP server. The default is hard_open, which reconnects if opening the connection to the directory server failed. By contrast, hard_init reconnects if initializing the connection failed. Initializing may not actually contact the directory server, and it is possible that a malformed configuration file will trigger reconnection. If soft is specified, then nss_ldap will return immediately on server failure. All "hard" reconnect policies block with exponential backoff before retrying.

nss_connect_policy <persist|oneshot>

Determines whether nss_ldap persists connections. The default is for the connection to the LDAP server to remain open after the first request.

idle_timelimit <timelimit>

Specifies the time (in seconds) after which nss_ldap will close connections to the directory server. The default is not to time out connections.

sasl_authid <authid>

Specifies the authorization identity to be used when performing SASL authentication.

rootsasl_auth_id <authid>

Specifies the authorization identity to be used when performing SASL authentication as root (when the effective user ID is zero).

sasl_secprops <properties>

Specifies Cyrus SASL security properties. Allowed values are described in the ldap.conf(5) manual page.

rootuse_sasl <yes|no>

Specifies whether SASL authentication should be used when the effective user ID is zero.

krb5_ccname <PREFIX:args>

If nss_ldap is built with configurable GSS-API credentials cache name support, specifies the Kerberos credentials cache to use.

nss_paged_results <yes|no>

Enables support for paged results.

pagesize <pagesize>

When paged results are enabled (see above), specifies the number of entries to return in a single page. The default is 1000.

nss_base_<map> <basedn?scope?filter>

Specify the search base, scope and filter to be used for specific maps. (Note that map forms part of the configuration file keyword and is one of passwd, shadow, group, hosts, services, networks, protocols, rpc, ethers, netmasks, bootparams, aliases and netgroup.) The syntax of basedn and scope are the same as for the configuration file options of the same name, with the addition of being able to omit the trailing suffix of the base DN (in which case the global base DN will be appended instead). The filter is a search filter to be added to the default search filter for a specific map, such that the effective filter is the logical intersection of the two. The base DN, scope and filter are separated with literal question marks (?) as given above; this is for compatibility with the DUA configuration profile schema and the ldapprofile tool. This option may be specified multiple times.

nss_map_attribute <from_attribute> <to_attribute>

This option may be specified multiple times, and directs nss_ldap to use the attribute to_attribute instead of the RFC 2307 attribute from_attribute in all lookups. If nss_ldap was built without schema mapping support, then this option is ignored.

nss_map_objectclass <from_objectclass> <to_objectclass>

This option may be specified multiple times, and directs nss_ldap to use the object class to_objectclass instead of the RFC 2307 object class from_objectclass in all lookups. If nss_ldap was built without schema mapping support, then this option is ignored.

nss_default_attribute_value <attribute> <value>

Specifies the default value to use for entries that lack the specified attribute. This option may be specified multiple times, for different attributes. If nss_ldap was built without schema mapping support, then this option is ignored.

nss_override_attribute_value <attribute> <value>

Specifies a value to use for the specified attribute in preference to that contained in the actual entry. This option may be specified multiple times, for different attributes. If nss_ldap was built without schema mapping support, then this option is ignored.

nss_schema <rfc2307bis|rfc2307>

If the value of this option is rfc2307bis then support for the RFC2307bis schema (distinguished names in groups) will be enabled.

nss_initgroups <backlink>

This option directs the nss_ldap implementation of initgroups(3) to determine a user's group membership by reading the memberOf attribute of their directory entry (and of any nested groups), rather than querying on uniqueMember. This may provide increased performance with certain directory servers that have peculiar indexing configurations. If RFC2307bis support is disabled, then this option is ignored.

nss_initgroups_ignoreusers <user1,user2,...,userN>

This option directs the nss_ldap implementation of initgroups(3) to return NSS_STATUS_NOTFOUND if called with a listed users as its argument.

nss_getgrent_skipmembers <yes|no>

Specifies whether or not to populate the members list in the group structure for group lookups. If very large groups are present, enabling this option will greatly increase performance, at the cost of some lost functionality. You should verify no local applications rely on this information before enabling this on a production system.

nss_srv_domain <domain>

This option determines the DNS domain used for performing SRV lookups.

## AUTHOR
The nss_ldap module was developed by PADL Software Pty Ltd (www.padl.com).

## FILES
/etc/ldap.conf, /etc/ldap.secret, /etc/nsswitch.conf

## SEE ALSO
nsswitch.conf(5)