mirror of
https://github.com/systemd/systemd.git
synced 2026-08-09 01:20:53 +00:00
1ada9064e6
Lennart suggested to use a more uniform algorithm for
the picking of the hostname words that is not biased
for long words by just (predictably) randomly going over
the offsets until we land on a word boundary. This is a
very nice suggestion so this commit implements it with
a fallback to the "old" behavior if we do not find a
word boundary within a reasonable amount of attempts.
A small python script shows that 64 iterations plus
fallback is a good number:
```
$ python3 simulate-hostname-pick.py 64
hostname-wordlist/adverbs
words=261 p_accept=0.1119 avg_bytes/word=1/p=8.94
max_iterations=64, n_trials=1000000
fallback rate : 0.051000% (510/1_000_000)
mean seeks per word : 8.93
hostname-wordlist/adjectives
words=449 p_accept=0.1380 avg_bytes/word=1/p=7.24
max_iterations=64, n_trials=1000000
fallback rate : 0.007500% (75/1_000_000)
mean seeks per word : 7.25
hostname-wordlist/nouns
words=449 p_accept=0.1472 avg_bytes/word=1/p=6.79
max_iterations=64, n_trials=1000000
fallback rate : 0.002700% (27/1_000_000)
mean seeks per word : 6.79
```
Combined with the fallback to the previous method if
we can't find anything within the 64 attemps this seems
to be the best tradeoff and give us very good uniformity.
Hostname word lists
====================
These files provide the word lists for the "$" wildcard understood by
/etc/hostname (see hostname(5)). The "$" token is positional: the n-th "$" in a
template is replaced by a word from the list file named "n", i.e. the first "$"
uses the file "1", the second "2", and so on. A template such as:
$-$-$-???? -> wildly-happy-octopus-92a9
is expanded deterministically from the machine ID, so a given machine always
gets the same name.
The numbered files are shipped as symlinks to the semantic lists, so the same
words back both names:
1 -> adverbs
2 -> adjectives
3 -> nouns
This keeps the lookup flexible (a deployment can add a "4", "5", … or repoint
the symlinks) while the actual word lists keep meaningful names.
Files
-----
Each file is a plain list of words, one per line. Blank lines and lines starting
with "#" are treated as comments and skipped. Each word must be a valid single
hostname label (lowercase letters, digits, hyphens); invalid entries are skipped.
The file is used as-is from the highest-priority directory that provides it (/etc
-> /run -> /usr/local/lib -> /usr/lib); files are not merged across directories.
Search path (highest priority first):
/etc/systemd/hostname-wordlist/{1,2,3,...}
/run/systemd/hostname-wordlist/...
/usr/local/lib/systemd/hostname-wordlist/...
/usr/lib/systemd/hostname-wordlist/...
Caveats
-------
The word for each token is derived deterministically from the machine ID and
recomputed on every boot; it is not persisted. The position is folded into the
hash, so repeated "$" tokens stay independent even when they resolve to the same
list. Changing a word list may change the name a machine gets. If a referenced
list is missing the name is treated as invalid and the built-in fallback
hostname is used.
Words are picked uniformly without reading the whole list into memory: an offset
is chosen by hashing and accepted only when it lands on the start of a line
(otherwise another offset is tried), so a word's chance does not depend on its
own length or that of its neighbours.
Origin
------
These are the "small" word lists taken from the petname project
(https://github.com/dustinkirkland/petname), distributed under the Apache
License 2.0. Distributions are encouraged to ship larger lists (petname also
provides "medium" and "large") for a bigger name space.