login-banner 1 user commands nosh
login-banner chain-load utility for printing login banners
`login-banner` --utmp-filename filename template-filename next-prog

## Description

`login-banner` is a chain-loading utility that prints a system banner to its standard output, and then (if successful) chain loads to next-prog with the execvp 3 library function. Normally, the next-prog will be (or will eventually chain-load) login 1, which prints the login prompt(s) after the banner.

next-prog may contain its own command line options, which `login-banner` will ignore.

`login-banner` makes no alteration to process state.

With various pieces of system information to hand it displays the contents of template-filename to its standard output. The file is displayed as-is, with the exception that a backslash character begins a two-character escape sequence.

### Escape sequences

The following escape sequences are defined:

`\\`

  A single backslash.

`\d`

  The current date in the local timezone of the process.

`\h`

  The "hostname", by default the dynamic hostname obtained from the gethostname 2 library function. See set-dynamic-hostname 1 for how this is set. `login-banner` allows the value held by the kernel to be overridden by the value of a `HOSTNAME` environment variable (the same convention as machineenv 1).

`\L`

  The "location" name, from the `/etc/machine-info` file, if available. This defaults to an empty string.

`\l`

  The "line", i.e. the pathname of the controlling TTY name relative to `/dev`, from the ttyname 3 library function (applied to standard input). `login-banner` allows the value held by the kernel to be overridden by the value of a `TTY` environment variable (the same convention as vc-get-terminal 1 or pty-allocate 1, or an equivalent getty 1 program that sets that variable, and usually the case in TTY login services which chain to `login-banner` via these).

`\m`

  The "machine" name, from the uname 2 library function. On FreeBSD, the C library allows the value held by the kernel to be overridden by the value of a `UNAME_m` environment variable.

`\N`

  The "pretty" "node" name, from the `/etc/machine-info` file, if available. This defaults to the same as `\n`.

`\n`

  The "node" name, from the uname 2 library function. See set-dynamic-hostname 1 for how this is set and why in practice it is identical to, and redundant with, the "hostname" from the expansion of `\h`.

  Despite the claim in its documentation, on FreeBSD the C library does not allow the value held by the kernel to be overridden by the value of a `UNAME_n` environment variable.
`\O`

  The "DNS domain name", derived from the "hostname" by taking it to be (the human-readable form of) a DNS domain name and stripping its first "label". `login-banner` allows the value held by the kernel to be overridden by the value of a `LOCALDOMAIN` environment variable (a common DNS client library convention).

  See set-dynamic-hostname 1 for the bewildering and (self-)contradictory range of ways in which various programs derive the DNS domain name from the hostname.
`\o`

  The "NIS domain" name, from the getdomainname 2 library function. See set-dynamic-hostname 1 for how this is set. `login-banner` allows the value held by the kernel to be overridden by the value of a `DOMAINNAME` environment variable (the same convention as machineenv 1).

`\p`

  The "deployment" name, from the `/etc/machine-info` file, if available. This defaults to an empty string.

`\r`

  The "release" name, from the uname 2 library function. On FreeBSD, the C library allows the value held by the kernel to be overridden by the value of a `UNAME_r` environment variable.

`\S`

  The "pretty" "system" name, from the `/etc/os-release` file, if available. This defaults to the same as `\s`.

`\s`

  The "system" name, from the uname 2 library function. On FreeBSD, the C library allows the value held by the kernel to be overridden by the value of a `UNAME_s` environment variable.

`\t`

  The current time in the local timezone of the process.

`\U`

  The number of users logged on, followed by a space and the string "users" (or "user" if the number is exactly one). See `\u` for how this information is obtained.

`\u`

  The number of users logged on.

  `login-banner` derives information about the number of users logged on from the `utmp` file. The location of the `utmp` file is derived at compile time from a system header when the utility is built from source. To override it at runtime, use the --utmp-filename option.

`\v`

  The "version" name, from the uname 2 library function. On FreeBSD, the C library allows the value held by the kernel to be overridden by the value of a `UNAME_v` environment variable.

`\z`

  The local timezone of the process.

All other escape sequences are reserved for future expansion.

## Security

The program requires permission to read `utmp` and the template file.

## Compatibility

The functionality is a rough superset of that for "issue" files provided by other tools that implement the old and superseded "getty" tool:

- Wietse Venema's agetty 1 only understands `\d`, `\l`, `\m`, `\n`, `\o`, `\r`, `\S`, `\s`, `\t`, `\U`, `\u`, and `\v` in the same way. It has `\4`, `\6`, `\b`, and `\e` which are not in `login-banner`.

- Felix von Leiner's fgetty 1, Florian La Roche's mingetty 1, and Nikola Vladov's ngetty 1 only understand `\d`, `\l`, `\m`, `\n`, `\o`, `\r`, `\s`, `\t`, `\U`, `\u`, and `\v`.

- Gert Doering's mgetty 1 only understands `\m` and `\s` in the same way. It has `\d`, `\l`, `\r`, `\t`, `\u`, and `\v` but in upper case rather than lower case. And it has `\C`, `\I`, `\N`, `\P`, `\S`, and `\Y` which are not in `login-banner`, being aliases for other escape sequences, specific to remote serial terminals and dial-up, or U.S.-specific old style date+time formats.

## Example

`login-banner` doesn't really care if its standard output is not a virtual console, or even a terminal or a character device at all. It can be used to display login banners to arbitrary destinations, even to sockets and to files. (Although one must ensure that it always inherits a `TTY` environment variable in such cases, so that the `\l` escape sequence expands to the appropriate thing, and not to the name of some irrelevant controlling terminal.)

The following nosh 1 script is (roughly) equivalent to what in.telnetd 1 does, except that it doesn't handle the TELNET protocol negotiation or the various debugging options.

    #!/bin/nosh
    pty-allocate
    pty-run
    setsid
    open-controlling-terminal
    login-banner /etc/issue.net
    login

This is the sh 1 equivalent:

    #!/bin/sh -e
    exec \
    pty-allocate \
    pty-run \
    open-controlling-terminal \
    login-banner /etc/issue.net \
    login

## Author

Jonathan de Boyne Pollard