hesutils.conf

# HESIOD UTILITIES CONFIGURATION FILE
# ===================================
#
# Refer to the Hesutils documentation for further information.
#
# ==============================================================================
#
# This file is part of Hesutils <https://gitlab.com/jflf/hesutils>
# Hesutils Copyright (c) 2019-2021 JFLF
#
# Hesutils is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# Hesutils is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with Hesutils. If not, see <https://www.gnu.org/licenses/>.
#
# ==============================================================================



# Hesiod namespace configuration
# ------------------------------------------------------------------------------

# Left-hand side and right-hand side domain components used in Hesiod lookups.
#
# - LHS can be empty, RHS must be defined.
# - Neither can contain spaces or non-printable characters (they must be
#   lexically valid domain components).
# - For compatibility reasons both must include a leading dot.
# - /etc/hesiod.conf on the client machines must contain the same LHS and RHS.
#
# Note that the top-level component (the rightmost part of the RHS, after the
# last dot) must NOT be ".local", as this is the domain component used for mDNS
# queries (Bonjour, Avahi, etc).
#
# As a configuration example, this is the configuration needed to query the
# original Hesiod name server from the Athena project at MIT:
#   LHS=.ns
#   RHS=.athena.mit.edu
#
# Default values:       LHS=
#                       RHS=.hesiod
#
# The default values work well for a local system without a domain.
#
LHS=
RHS=.hesiod



# User and group configuration
# ------------------------------------------------------------------------------

# Minimum and maximum UID values for Hesiod user accounts?
#
# Default values:       UIDMIN=5000
#                       UIDMAX=5999
#
UIDMIN=5000
UIDMAX=5999

# Minimum and maximum GID values for Hesiod groups?
#
# Default values:       GIDMIN=${UIDMIN}
#                       GIDMAX=${UIDMAX}
#
GIDMIN=${UIDMIN}
GIDMAX=${UIDMAX}



# Generated records
# ------------------------------------------------------------------------------

# Trim the passwd GECOS field?
#
# Trimming the GECOS fields (not exporting them through Hesiod) makes the user
# and uid records a bit shorter.
#
# Default value:        TRIMGECOS=1
#
TRIMGECOS=1

# Include the full member list in group and gid records?
#
# Including the full user list (of Hesiod users only) in the group records makes
# getent group on the clients behave like on a local machine, returning the full
# list of members of that group. That may be required by some applications.
#
# Depending on the number of members, those lists can grow to very large sizes,
# requiring multiple TXT strings and potentially reaching the maximum size of a
# DNS answer (65535 bytes). Therefore it's only practical on sites where no
# group contains a very large number of users.
#
# Default value:        FULLMEMBERLIST=0
#
FULLMEMBERLIST=0

# Generate non-standard GRPLIST records?
#
# The GNU libc's Hesiod NSS module redefined the key and content of GRPLIST
# records. In the original documentation, <groupname>.grplist is a list of sub-
# groups, and <groupname> is a group of groups. In nss_hesiod's implementation,
# <username>.grplist is the list of groups of which <username> is a member.
# See the Hesutils documentation for more details.
#
# Obtaining a membership list is very useful on modern Linux systems. There is
# no way of getting that information out of standard Hesiod records only, and
# some client-side software might not function properly without it. For that
# reason hesgen will write out the user variant of GRPLIST records by default.
#
# On the other hand this is not standard and it might not be supported by any
# other Hesiod client code (or confuse the living daylights out of them). If
# needed, this parameter disables writing out GRPLIST records.
#
# NOTE: As groups-of-groups do not exist in standard system files, hesgen cannot
#       generate the group variant of GRPLIST records.
#
# Default value:        USERGRPLIST=1
#
USERGRPLIST=1

# Use UID and GID in records instead of user and group names?
#
# GROUP and GRPLIST records contain lists of users and groups. By default the
# full names are included. Those take up more space than UIDs and GIDs, which
# can be a problem in large sites or setups with large group memberships or
# numerous secondary groups per user. In those cases, it may be preferable to
# use IDs instead of names.
#
# Default value:        NAMELISTS=1
#
NAMELISTS=1


# Home directory transformation mechanisms
# ------------------------------------------------------------------------------

# NOTE: The entire topic of home directories and FILSYS records is complex!
#       Please see the Hesutils documentation for details and examples.


# Mechanism #1: sed commands

# Expressions passed as parameter to sed to modify the home directories.
# Leave empty or commented out to skip those step.
#
# HOMESEDEXPORT transforms the passwd path into the export path.
# HOMESEDMOUNT transforms the passwd path into the mount path.
#
# HOMESEDEXPORT is only used for FILSYS records.
#
# Examples:
# Passwd path:          /home/myuser
# Export path:          /export/home/myuser
# Mount path:           /mnt/nfs/home/myuser
# HOMESEDEXPORT:        's:^:/export:'
# HOMESEDMOUNT:         's:^:/mnt/nfs:'
#
# Default values:       HOMESEDEXPORT=  [empty]
#                       HOMESEDMOUNT=  [empty]
#
HOMESEDEXPORT=
HOMESEDMOUNT=

# Mechanism #2: map file

# Map file containing per-user static homedir and FILSYS entries.
# Leave empty or commented out to skip that step.
#
# Syntax for passwd records only, whitespace-separated:
# <user name>  <home path>
#
# Syntax for passwd and FILSYS records, whitespace-separated:
# <user name>|*  AFS  <export path>  <mount options>  <mount path>
# <user name>|*  NFS  <export path>  <server>  <mount options>  <mount path>
# <user name>|*  <FS type>  <device>  <mount options>  <mount path>
#
# Empty lines and comments (#) are ignored.
#
# Default value:        FSMAPFILE=  [none]
#
FSMAPFILE=

# Mechanism #3: custom command

# Command to run to obtain per-user homedir and FILSYS entries.
# Leave empty or commented out to skip that step.
#
# Parameters passed to the command: all the individual fields of the passwd
# entry, in the same order as in the passwd entry.
#
# Output on stdout for passwd records only, whitespace-separated:
# <user name>  <home path>
#
# Output on stdout for passwd and FILSYS records, whitespace separated:
# <user name>|*  AFS  <export path>  <mount options>  <mount path>
# <user name>|*  NFS  <export path>  <server>  <mount options>  <mount path>
# <user name>|*  <FS type>  <device>  <mount options>  <mount path>
#
# Return codes:
# 0 for success, anything else for error.
#
# Default value:        FSCOMMAND=  [none]
#
FSCOMMAND=



# FILSYS record generation
# ------------------------------------------------------------------------------

# The Linux automounter supports Hesiod as a provider of filesystem maps. On the
# server, this takes the form of FILSYS TXT records. The client systems must be
# configured to use the automounter for home directories.

# Generate FILSYS records?
#
# This option controls the presence of FILSYS records in hesgen's output. The
# contents of those records is controlled by the home directory transformation
# mechanisms above, as well as the automatic FILSYS generation below.
#
# See the Hesutils documentation for more details.
#
# Default value:        FILSYS=0
#
FILSYS=0

# Generate automatic FILSYS records from the values of the following parameters
# (FSTYPE, NFSSERVER, FSDEVICE, FSMOUNTOPTS)?
#
# This is different from the FILSYS option above, which controls whether FILSYS
# records should be emitted at all. See the Hesutils documentation for details.
#
# Default value:        FILSYSAUTO=0
#
FILSYSAUTO=0

# Filesystem type or protocol to access the home directories.
#
# Traditional Hesiod supports only 2 types: AFS and NFS. Those two have special
# dedicated syntaxes. See the documentation text of FSMAPFILE above for the list
# of fields.
#
# Those two syntaxes are selected by setting FSTYPE to "AFS" resp. "NFS", lower
# or upper case. Any other value, including "nfs4", will be treated as the
# generic third syntax.
#
# The Linux automounter daemon supports many filesystem types. See the Hesutils
# documentation and autofs(5) for additional information.
#
# Default value:        FSTYPE=NFS
#
FSTYPE=NFS

# Name of the NFS server exporting the home directories.
#
# This can be an IP address or a hostname. The hostname must resolve from the
# client nodes, but not necessarily from the machine on which this script runs.
#
# This parameter is used only when FSTYPE=NFS.
#
# Default value:        NFSSERVER=$(hostname -f)  [FQDN of the local machine]
#
NFSSERVER=$(hostname -f)

# Filesystem device.
#
# For filesystems other than AFS or NFS, a device is required. This can be
# either a local block device, or the syntax for a specific network filesystem.
#
# This device string is exactly the same as the first field of an fstab entry.
#
# The device syntax for many network filesystems contains usually the IP address
# or the hostname of the file server. The hostname must resolve from the client
# nodes, but not necessarily from the machine on which this script runs.
#
# It also contains often a volume path or export path, usually (but not always)
# at the end. For example, the device syntax for a NFS mount in the fstab might
# look like this:
#   nfssrv:/export/home
#
# If the FSDEVICE string contains the characters '{}' (without the quotes),
# those will be replaced by the export path generated by the home directory
# transformation mechanisms. For example:
#   FSDEVICE='nfssrv:{}'
#
# See the Hesutils documentation for more details.
#
# This parameter is used only when FSTYPE is neither AFS nor NFS, in which case
# it is mandatory.
#
# Default value:        FSDEVICE=  [empty]
FSDEVICE=

# Filesystem mount options.
#
# This can be the single options "r" (read-only) or "w" (read-write) from the
# traditional FILSYS specifications, or any modern mount option string.
#
# Default value:        FSMOUNTOPTS="rw"
#
FSMOUNTOPTS="rw"



# DNS server options
# ------------------------------------------------------------------------------

# Select the Hesiod TXT record output format.
#
# Possible values:      "dnsmasq"
#                       "unbound"
#                       "bind"
#
# Default value:        OUTPUTFMT="dnsmasq"
#
OUTPUTFMT="dnsmasq"

# Try to create a valid zone declaration snippet?
#
# Hesgen can write out the TXT records only, without any zone definition or
# other stanzas. This is useful if you want to integrate those records within a
# larger, more complex configuration file. But as some DNS servers require
# specific directives for a configuration file to be valid, hesgen's bare output
# isn't sufficient on its own.
#
# Enable this option to wrap the output in just enough zone decoration to create
# a valid standalone configuration snippet.
#
# The exact additions depend on the DNS server:
#   unbound:    basic zone declaration
#   bind:       master zone file directives
#
# Refer to the Hesutils documentation for details on how to use those snippets.
#
# WARNING: The added elements are the bare minimum to have the DNS servers treat
#          that data, in a separate file, as valid. They are emphatically not a
#          complete DNS server or zone configuration!
#
# This parameter has no effect with dnsmasq.
#
# Default value:        CREATEZONE=1
#
CREATEZONE=1

# Override the DNS server's TTL configuration?
#
# If set to a value, a TTL directive will be included in the generated records.
# If unset, the server's TTL value (default or as defined in the rest of the
# configuration) will apply.
#
# Setting the TTL to zero has the effect of disabling client-side record
# caching. This has a major performance impact on operations that do frequent
# user and group lookups, such as listing directory contents.
#
# NOTE: Dnsmasq doesn't support per-TXT-record TTL, so setting a value here will
#       affect all local answers (records, DHCP leases and /etc/hosts entries).
#
# The TTL value must specified in seconds only (e.g. 300 for 5 minutes).
#
# Default value:        TTL=  [empty]
#
TTL=

# Change the class of the Hesiod records?
#
# The default class for any record nowadays is IN. HS is considered deprecated,
# but as long as client-side support still exists nothing prevents you from
# declaring your Hesiod data in the HS class.
#
# This parameter takes one of two values: IN or HS. If set to either of those
# values, a class directive will be included in the generated records. If unset
# or empty, default class of the server or zone will apply implicitly.
#
# This parameter has no effect with dnsmasq.
#
# This parameter has no effect when OUTPUTFMT=unbound and CREATEZONE=1. Unbound
# local zones are always IN. See the Hesutils documentation for more details.
#
# Default value:        CLASS=  [empty]
#
CLASS=

# Include a Start Of Authority record in the generated data?
#
# The format of this option is a Bash list of all the fields of an SOA record.
# If the parameter is unset or empty, no SOA record is generated.
#
# The SOA fields must be provided by the user. For example:
#
#  SOA=( ns.icann.org.       # mname     primary name server for the zone
#        noc.dns.icann.org.  # rname     administrator's email address, @ -> .
#        2020080302          # serial    serial number
#        7200                # refresh   secondary sync refresh period
#        3600                # retry     secondary sync retry delay
#        1209600             # expire    secondary sync-give-up-and-stop delay
#        3600                # negative  negative caching TTL (ex-minimum)
#      )
#
# WARNING: The content of those fields is not validated.
#
# This parameter has no effect with dnsmasq.
#
# This parameter has no effect when CREATEZONE=0.
#
# This parameter is mandatory when OUTPUTFMT=bind and CREATEZONE=1. In that case
# hesgen will also create an NS record with the first item in the array as
# nameserver.
#
# Default value:        SOA=  [empty]
SOA=

# Prevent Hesiod lookups without a local TXT record (a.k.a. unknown users and
# groups) from being forwarded to the upstream DNS servers?
#
# This option should almost always be set to 1 (block forwarding). The only
# reason why you wouldn't want this is if you have layers of DNS forwarders
# serving each a local subset of a single Hesiod namespace. If this is the case,
# take a break, have a nice coffee or beer with good friends, listen to the wind
# in the leaves and the birds singing, breathe deeply until you're at peace, and
# then ponder the life choices that led you to that situation.
#
# This parameter has an effect with unbound only when CREATEZONE=1.
#
# This parameter has no effect with bind. See the Hesutils documentation for
# alternate ways to achieve the same result.
#
# Default value:        BLOCKUPSTREAM=1
#
BLOCKUPSTREAM=1

# Prevent Hesiod lookups from unconfigured clients from being forwarded to the
# hardcoded default DNS server?
#
# The Hesiod NSS module in old GNU libc libraries (<= 2.23, circa 2016)
# defaulted to using RHS=.Athena.MIT.EDU if not defined in /etc/hesiod.conf. Any
# Hesiod lookup from unconfigured clients (with an empty hesiod.conf) would thus
# be forwarded to the MIT DNS servers, if not blocked.
#
# There is no reason whatsoever for not blocking those lookups, except if you're
# the MIT IT team. Hi guys! This one's for you.
#
# This parameter has no effect with bind. See the Hesutils documentation for
# alternate ways to achieve the same result.
#
# Default value:        BLOCKATHENA=1
#
BLOCKATHENA=1