Name

set-dynamic-hostname — set the dynamic hostname from the statically configured hostname

Synopsis

set-dynamic-hostname [--force]

Description

set-dynamic-hostname sets the dynamic hostname from the statically configured hostname. It is designed to be run as part of system or container/jail initialization.

The dynamic hostname is the hostname that is returned from the gethostname(2) library function, which may vary during the system's lifetime as the machine is (for example) granted DHCP leases. On operating systems such as FreeBSD, OpenBSD, and Linux, the dynamic hostname is the same as the nodename that is returned by the the uname(2) library function (although the POSIX standard does not in fact require this).

The statically configured hostname is the value of the hostname environment variable that the set-dynamic-hostname program is started with. Normally, set-dynamic-hostname will be chain-loaded from something like envdir(1) reading hostname out of an environment directory or read-conf(1) reading it from a file such as /etc/rc.conf.

If that environment variable is missing, set-dynamic-hostname looks (on operating systems that support it) to the kernel environment variable dhcp.host-name, which is the host name contained in the DHCP lease obtained by a PXE boot loader. If that fails, it sets the dynamic hostname to "localhost".

Unless the [--force] option is used, set-dynamic-hostname will not attempt to set the dynamic hostname if it has already been set to something. Thus setting the dynamic hostname for a container/jail can be done by simply setting it as the jail is created. Any later execution of set-dynamic-hostname within the jail, as part of its startup process, will not override that.

No restrictions are placed upon hostnames by set-dynamic-hostname, nor by most operating systems, except length restrictions. However, for best results, administrators should obey the rules set out in RFC 1123 § 2.1, which limit hostnames to:

  • the characters AZ, az, 09, ., and - (preferring lowercase, since RFC 1123 Host Names are not case sensitive) with the first character not being either . or - and the last character not being .

  • a maximum of 63 characters (hostnames here being the initial label(s) of an RFC 1123 Host Name)

For clarity, observe that a RFC 1123 Host Name comprises two parts:

  • the dynamic hostname, as set by this command, comprising the initial one or more labels (usually only the first label); and

  • the domain name, as returned by the getdomainname(2) library function (and on Linux the uname(2) library function), comprising the remaining labels.

Author

Jonathan de Boyne Pollard