set-dynamic-hostname 1 user commands nosh
set-dynamic-hostname set the dynamic hostname from the statically configured hostname
`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.

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` itself, nor by most operating systems, except length restrictions.

### The dynamic hostname

The dynamic hostname is the hostname that is set with the sethostname 2 library function, which may vary during the system's lifetime as the machine is (for example) granted DHCP leases. It is conventionally accessible via the hostname 1 command, the `HOST` shell variable in the Z shell, and any programs that simply call the gethostname 2 library function themselves.

### The static hostname

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`. The nosh toolkit comes with a system service bundle that invokes the `set-dynamic-hostname` command, and whose `hostname` environment variable is converted, via a configuration import mechanism, from the `/etc/rc.conf` configuration file.

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.`, a fully-qualified DNS domain name.

For statically configured hostnames, it is recommended to follow the conventions laid out in the OpenBSD myname 5, the FreeBSD rc.conf 5, and the FreeBSD and OpenBSD hostname 7 manual pages. The modern convention, stated by these manual pages, is that this is a multiple-label, possibly also fully-qualified (i.e. with a trailing `.` character), DNS domain name in human-readable (not machine-readable as in the DNS protocol) form; and that it follow the lexical rules for such names (including disallowing all-numeric labels and being case-insensitive).

35 years after the invention of internationalized domain names, it is still not settled whether non-English hostnames should be encoded as Punycode or UTF-8. It is the author's recommendation to use UTF-8, because hostnames are human-readable strings presented by applications programs to their users, not on-the-wire Punycode-encoded DNS domain names.

## Standards

The Single Unix Specification requires that operating systems have three things:

- a "host" name, that is the name that is returned from the gethostname 2 library function.

- a "domain" name, that is the name that is returned from the getdomainname 2 library function.

- a "node" name, that is the name that is returned from the uname 2 library function.

The Single Unix Specification does not define any relationships amongst these three. What namespaces and qualifying domains encompass the "host" and "node" names is up to individual operating systems to define, and they need not bear any relation to the "domain" name.

Nor does it specify how any of these are set, nor that they are even variable during system runtime. It notes that in historical operating systems the "node" name was, indeed, hardwired into the code of the operating system at compile time.

Nor does it define any ways in which these are accessible from the shell or from utilities.

### Reality

In reality, FreeBSD, OpenBSD, and Linux-based operating systems present these different concepts to system administrators and users instead:

a dynamic "hostname"

  This is the "host" name that is returned from the gethostname 2 library function and set by the (non-standardized but universal) sethostname 2 library function. It is also the "node" name that is returned from the uname 2 library function; the two being guaranteed identical on these operating systems. It is conventionally accessible via the hostname 1 command, via the uname 1 command with the -n option, and as aforementioned.

a dynamic "NIS domain name"

  This is the "domain" name that is returned from the getdomainname 2 library function and set by the (non-standardized but universal) setdomainname 2 library function. It is conventionally accessible via the domainname 1 command. Peter Tobias's hostname also provides nisdomainname 1 and ypdomainname 1 commands.

  Despite this access overkill, it is rarely of practical use.

  Very old documentation calls this the "YP domain name", although the BSDs stopped using the name "Yellow Pages" for this in the 1980s.
a dynamic "DNS domain name"

  This is derived from the "hostname", somehow. FreeBSD and OpenBSD provide no command for accessing this. Peter Tobias's hostname provides the dnsdomainname 1 command, as well as various name-qualification options to its hostname 1 command.

  There is no consistency in how this happens, not even from subsystem to subsystem on a single operating system, nor even within a single toolkit (e.g. Peter Tobias's hostname). Some programs take the "hostname" and simply strip off a leading "label" by looking for the first `.` character. Some programs follow the more complex steps given in the FreeBSD and OpenBSD hostname 7 manual page; albeit that not all do, even on FreeBSD itself, with the `HOSTALIASES` environment variable not widely recognized and name qualification not following the rules set out on that page (which do not agree with how DNS client libraries from ISC's BIND and djbdns actually fully-qualify names). Peter Tobias's hostname documents a complex and bewildering set of rules for how its dnsdomainname 1 and its hostname 1 commands interact with their various command-line options when it comes to name qualification and deriving DNS domain names.

### History

RFC 1123 § 2.1 describes Host Names, limiting such Host Names to the characters `A`–`Z`, `a`–`z`, `0`–`9`, `.`, 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 `.` character.

An old convention was that the Host Name was the Single Unix Specification's "host" name qualified with its "domain" name. In practice, this would have only been true on operating systems where "Yellow Pages" was the primary name lookup mechanism. It is explicitly contradicted by modern practice (and indeed by RFC 1123), where the "hostname" is a DNS name, not a YP/NIS name. It and RFC 1123 are also explicitly contradicted by the FreeBSD and OpenBSD hostname 7 manual page which explains that "hostname"s are indeed allowed to end with a `.` character in the modern DNS-based world.

Peter Tobias's hostname does not mention RFC 1123, only RFC 1035, disallows a `-` as the last character as well, and silently removes whitespace; albeit that (as aforementioned) the operating systems that it runs on have no such restrictions themselves.

## Author

Jonathan de Boyne Pollard