# Gazetteer

This is a short gazetteer of some of the places in the filesystem. It is not a comprehensive map, nor a standard. For a map see the `hier` manual page. Many of the things here are dictated by compatibility with other systems.

## Runtime directories

`/run`

  This is the system-wide runtime directory. From the point of view of service and system management, the following points are important:

  - It is a memory file system, that is mounted early in the bootstrap process by the `system-manager` program. Thus its contents can potentially live from early bootstrap to shutdown, but do not live across system restarts, or powering the system down.

  - It is owned by the superuser, and only the superuser has the access to create/delete files and subdirectories in it. This is not an equivalent to `/tmp`. Other users do not have create/delete access, not even POSIX restricted write access.

  - System-wide services that run as dedicated users can have subdirectories immediately below it. The subdirectories are usually set up and torn down by the `start` and `stop` programs in their service directories. They are usually owned by the dedicated user account for the service, or the superuser, and named after the service.

  - This is not a data storage area. This primarily contains control and status files for services (including FIFOs and sockets), shared memory, and things that are effectively shared memory (such as the display buffers for user-space virtual terminals).

  Files to be found here include:

  `/run/utx.active`
    the part of the BSD login database that records currently-logged in users since the last bootstrap, created by the `utx` service
  `/run/utmp`
    the part of the Linux login database that records currently-logged in users since the last bootstrap, created by the `utx` service running `login-update-utmpx`
  `/run/machine-id`
    the machine ID, usually a simple duplicate of `/etc/machine-id`
  `/run/dmesg.boot`
    a dump of the early kernel log for the current bootstrap, saved by the `dmesg` service and redundant with the log of the `klogd` service
  `/run/log`
    the universally writable socket that the `local-syslog-read` service listens on
  `/run/logpriv`
    the superuser-only writable socket that the `local-priv-syslog-read` service listens on
  `/run/motd.dynamic`
    part of the "dynamically created" Message Of The Day, created by the `motd-dynamic` service
  `/run/ld-elf.so.hints`
    the hints database for the dynamic link-loader, created by the `ldconfig` service
`/run/service-manager`

  The runtime area for the system-wide `service-manager` instance, spawned by the system manager or run by some other system. This contains:

  `/run/service-manager/control`
    the conventional communications socket for the system-wide service manager, only accessible to the superuser and (if the system-wide Desktop Bus broker is running) the `messagebus` user
`/run/system-manager`

  The runtime area for the `system-manager`, on a fully-nosh-managed system.

`/run/system-manager/log`

  A log directory that holds the log output of the system-manager, the system-wide service manager, and any `system-control` commands spawned to enact system state changes. It is the `system-manager` that sets this up and spawns the logger dæmon that writes to it. If the system-wide service manager is run some other way, this log might be somewhere else.

`/run/service-bundles`

  Ephemeral service bundles for nonce services and targets whose definitions are not intended to last across system restarts. This has the same substructure as `/etc/service-bundles/` with the addition of `/run/service-bundles/early-supervise`.

`/run/service-bundles/early-supervise`

  This contains `supervise/` directories for service bundles that live on `/etc` but that need to be run when the root volume is mounted read-only.

`/run/user`

  The container for all per-user runtime directories. This is owned by the superuser, with only the superuser having access to create/delete files and subdirectories in it.

  For safety, this should be a mount point of a subordinate memory filesystem, configured via `/etc/fstab` and converted to a `/var/local/service-bundles/services/mount@-run-user` service bundle. Otherwise, users can fill up the main `/run` filesystem and cause problems and mischief. An alternative strategy (the existence of which is why `/run/user` is not mounted as standard by the system manager) is for each individual user's runtime directory to be such a memory filesystem instead, insulating users even from one another.

`/run/user/jim`

  The container for the per-user runtime directories belonging to user `jim`. This is owned by `jim`, with `jim` having full access to it. Files to be found here include:

  `/run/user/jim/bus`
    the conventional socket for `jim`'s per-user Desktop Bus broker, managed by the `user-dbus@jim` service

    The Desktop Bus people claim that the Desktop Bus "address" `unix:runtime=yes` points to this socket, and can be used as the value of the `DBUS_SESSION_BUS_ADDRESS` environment variable. In reality, at the time of writing (2016) no stable/release version of Debian, FreeBSD, or OpenBSD contains a Desktop Bus broker or library that defaults to this address or even understands this address syntax. One has to use the address `unix:path=/run/user/${USER}/bus` instead.

`/run/user/:1001`

  A symbolic link to the per-user runtime directory for user ID 1001, such as `jim`.

  Note: The POSIX rules for account names (and indeed the structure of the account database itself on most systems) prohibit the occurrence of colon in an account name, whereas they permit digit characters. Thus we are ensured that no numeric user ID will ever clash with a valid account name.

`/run/user/jim/service-manager`

  The runtime area for `jim`'s per-user `service-manager` instance, spawned by `jim`'s per-user manager or run by some other system. This contains:

  `/run/user/jim/service-manager/control`
    the conventional communications socket for `jim`'s per-user service manager, managed by the `user-services@jim` service
`/run/user/jim/per-user-manager`

  The runtime area for `jim`'s `per-user-manager`. This contains:

  `/run/user/jim/per-user-manager/control`
    the conventional communications socket for `jim`'s per-user manager, only accessible to `jim`
`/run/user/jim/per-user-manager/log`

  A log directory that holds the log output of `jim`'s per-user manager, `jim`'s per-user service manager, and any `system-control` commands spawned to enact user management state changes. It is `jim`'s `per-user-manager` that sets this up and spawns the logger dæmon that writes to it. If `jim`'s per-user service manager is run some other way, this log might be somewhere else.

`/run/dev`

  The container for all runtime user-space devices, such as user-space virtual terminals. This is owned by the superuser, with only the superuser having access to create/delete files and subdirectories in it. User-space virtual terminals are subdirectories, such as:

  `/run/dev/head0`
    the virtual terminal intended for head #0 with a CJK input method layered on top, produced by the `console-input-method@head0` service
  `/run/dev/head0mux`
    the multiplex virtual terminal intended for head #0, produced by the `console-multiplexor@head0` service
  `/run/dev/vc1`
    the virtual terminal produced by the `terminal-emulator@vc1` service to whose TTY side the `ttylogin@vc1-tty` service attaches
  `/run/dev/vc2`
    the virtual terminal produced by the `terminal-emulator@vc2` service to whose TTY side the `ttylogin@vc2-tty` service attaches
  `/run/dev/vc3`
    the virtual terminal produced by the `terminal-emulator@vc3` service to whose TTY side the `ttylogin@vc3-tty` service attaches

  See `console-terminal-emulator` for the contents of these directories. Virtual terminal directories and their contents are owned by user `daemon` and with group `tty`. The terminal emulator services run as this user. (The TTY login services start running as the superuser, obviously.)

`/run/dbus`

  The runtime area for the system-wide Desktop Bus broker. This contains:

  `/run/dbus/system_bus_socket`
    the conventional communications socket for the system-wide Desktop Bus broker

## System directories

`/etc`

  Miscellany. This directly contains files such as:

  `/etc/machine-id`
    the machine ID, set up by the `machine-id` service (which runs `setup-machine-id` and `erase-machine-id`)
  `/etc/hostid`
    an ID, set up by the `machine-id` service (as above): the machine ID, in an alternative form to `/etc/machine-id`, on BSD systems; the 8-character host ID on GNU C library systems
  `/etc/default/rc.conf`
    a set of variable=value assignments incorporated by the external formats import subsystem into an amalgamated `rc.conf` file
  `/etc/rc.conf`
    a set of variable=value assignments incorporated by the external formats import subsystem into an amalgamated `rc.conf` file
  `/etc/rc.conf.local`
    a set of variable=value assignments incorporated by the external formats import subsystem into an amalgamated `rc.conf` file
  `/etc/fstab`
    a database table used by the external formats import subsystem to generate mount, swap, dump, and filesystem check service bundles
  `/etc/ttys`
    a database table used by `system-control`'s `preset` subcommand and the external formats import subsystem to configure TTY login service bundles
  `/etc/vconsole.conf`
    a set of variable=value assignments converted into `rc.conf` settings by amalgamation
  `/etc/network/interfaces`
    a Debian-style configuration file converted into `rc.conf` settings by amalgamation
  `/etc/hostname`
    the hostname converted into a `rc.conf` setting by amalgamation
  `/etc/hostname.interface`
    an OpenBSD configuration file converted into `rc.conf` settings by amalgamation
`/etc/service-bundles`

  Service bundles, split into services and targets.

`/etc/service-bundles/services`

  Service bundles that need to be accessible when only the root volume is mounted. These are usually sysinit services, with their `supervise/` subdirectories symbolically linked to subdirectories in `/run/service-bundles/early-supervise`.

`/etc/service-bundles/targets`

  Service bundles for all targets. These are usually sysinit services, with their `supervise/` subdirectories symbolically linked to subdirectories in `/run/service-bundles/early-supervise`.

`/etc/system-control`

  A control area.

`/etc/system-control/convert`

  The external formats import subsystem. This comprises, amongst other things:

  `/etc/system-control/convert/*.do`
    the redo scripts that drive the import process
  `/etc/system-control/convert/all.do`
    the redo script that is the top level of the whole import process
  `/etc/system-control/convert/rc.conf`
    a generated amalgamation of all `rc.conf` configuration files and several other external sources of configuration information. Do not symbolically link any of the `rc.conf` configuration files to this! It is generated from them in the first place. This can be conveniently used with `read-conf` when one needs to access configuration settings from these files.
  `/etc/system-control/convert/host.conf`
    a host.conf file generated from `/etc/nsswitch.conf` which one can symbolically link to `/etc/host.conf`
  `/etc/system-control/convert/kbdmaps/*`
    keyboard maps for `console-fb-realizer`, symbolically linked into the `service/kbdmaps` subdirectory of any keyboard device user-space virtual terminal realizer services
  `/etc/system-control/convert/swap_capsctrl.kbd`
    a keyboard map snippet that is overlaid on top of others in order to produce `.capsctrl` variants
  `/etc/system-control/convert/modelm_capsctrl.kbd`
    a keyboard map snippet that is overlaid on top of others in order to produce non-`.capsctrl` variants
  `/etc/system-control/convert/soft_backspace.kbd`
    a keyboard map snippet that is overlaid on top of others in order to ensure that the `backspace ⌫` key is soft-switchable by the terminal emulator
  `/etc/system-control/convert/soft_delete.kbd`
    a keyboard map snippet that is overlaid on top of others in order to ensure that the `delete ⌦` key is soft-switchable by the terminal emulator
  `/etc/system-control/convert/soft_enter.kbd`
    a keyboard map snippet that is overlaid on top of others in order to ensure that the `enter` key is soft-switchable by the terminal emulator
  `/etc/system-control/convert/soft_escape.kbd`
    a keyboard map snippet that is overlaid on top of others in order to ensure that the `escape ⎋` key is soft-switchable by the terminal emulator
  `/etc/system-control/convert/soft_return.kbd`
    a keyboard map snippet that is overlaid on top of others in order to ensure that the `return ⮠` key is not hardwired
  `/etc/system-control/convert/soft_tab.kbd`
    a keyboard map snippet that is overlaid on top of others in order to ensure that the `tab ⇥` key is not hardwired
  `/etc/system-control/convert/default_to_br.kbd`
    a keyboard map snippet that is overlaid on top of U.S. International in order to produce ABNT2 standard layout, in the event that there are no `/usr/share/vt/keymaps/` keyboard maps
  `/etc/system-control/convert/default_to_de.kbd`
    a keyboard map snippet that is overlaid on top of U.S. International in order to produce DIN standard layout, in the event that there are no `/usr/share/vt/keymaps/` keyboard maps
  `/etc/system-control/convert/jp_to_jp.104.kbd`
    a keyboard map snippet that is overlaid on top of `/usr/share/vt/keymaps/jp.kbd` in order to fix a bug that maps 2 keys to the same thing and effectively wastes 1 key
  `/etc/system-control/convert/default_to_uk.kbd`
    a keyboard map snippet that is overlaid on top of U.S. International in order to produce U.K. International, in the event that there are no `/usr/share/vt/keymaps/` keyboard maps
  `/etc/system-control/convert/jp_to_jp.104.kbd`
    a keyboard map snippet that is overlaid on top of `/usr/share/vt/keymaps/jp.kbd` in order to fix a bug that maps 2 keys to the same thing and effectively wastes 1 key
  `/etc/system-control/convert/jp_to_jp.109.kbd`
    a keyboard map snippet that is overlaid on top of `/usr/share/vt/keymaps/jp.kbd` in order to fix a bug that prevents FEP input methods from working
  `/etc/system-control/convert/*.service`
  `/etc/system-control/convert/*.target`
    service and target source files used for compiling service and target service bundles, for various import-generated system-wide and per-user services and targets
  `/etc/system-control/convert/dbus/*.service`
    service source files used for compiling service bundles for system-wide Desktop Bus services, generated from the system-wide Desktop Bus service definitions in `/usr/share/dbus-1/system-services`
  `/etc/system-control/convert/per-user/*.do`
    the redo scripts that drive per-user external configuration import, linked into each user's `~jim/.config/system-control/convert`
  `/etc/system-control/convert/per-user/dbus/*.service`
    service source files used for compiling service bundles for per-user (a.k.a. "session") Desktop Bus services, generated from the per-user Desktop Bus service definitions in `/usr/share/dbus-1/services` and linked into each user's `~jim/.config/system-control/convert`
`/usr/local/etc/system-control/presets`
`/etc/system-control/presets`
`/usr/local/share/system-control/presets`
`/usr/pkg/etc/system-control/presets`
`/usr/share/system-control/presets`

  Directories for nosh package only preset files that only `system-control`'s `preset` subcommand searches. Preset files that only have meaning for a nosh-managed system, or that are intended to modify and override systemd presets, go here. The (approximate) intention is the following split:

  `/usr/local/etc/system-control/presets`
    administrator-supplied presets
  `/etc/system-control/presets`
    administrator-supplied presets
  `/usr/local/share/system-control/presets`
    non-operating-system non-package-supplied presets
  `/usr/pkg/etc/system-control/presets`
    non-operating-system package-supplied presets
  `/usr/share/system-control/presets`
    operating-system-supplied presets
`/etc/systemd/system-preset`
`/usr/local/lib/systemd/system-preset` `/lib/systemd/system-preset`
`/usr/lib/systemd/system-preset`

  Directories for common preset files, for system-wide services, that `system-control`'s `preset` subcommand and systemd's `systemctl preset` both search. (Strictly speaking, this is an abuse of `lib`, which is for program object code libraries not text data files; the correct place for the systemd people to have chosen was `share`.)

`/usr/local/etc/system-control/user-presets`
`/etc/system-control/user-presets`
`/usr/local/share/system-control/user-presets`
`/usr/pkg/etc/system-control/user-presets`
`/usr/share/system-control/user-presets`

  Directories for nosh package only preset files, for per-user services, that only `system-control`'s `preset` subcommand searches. Preset files that only have meaning for a nosh-managed system, or that are intended to modify and override systemd presets, go here. The (approximate) intention is the following split:

  `/usr/local/etc/system-control/user-presets`
    administrator-supplied presets
  `/etc/system-control/user-presets`
    administrator-supplied presets
  `/usr/local/share/system-control/user-presets`
    non-operating-system non-package-supplied presets
  `/usr/pkg/etc/system-control/user-presets`
    non-operating-system package-supplied presets
  `/usr/share/system-control/user-presets`
    operating-system-supplied presets
`/etc/systemd/user-preset`
`/usr/local/lib/systemd/user-preset` `/lib/systemd/user-preset`
`/usr/lib/systemd/user-preset`

  Directories for common preset files, for per-user services, that `system-control`'s `preset` subcommand and systemd's `systemctl preset` both search. (Strictly speaking, this is an abuse of `lib`, which is for program object code libraries not text data files; the correct place for the systemd people to have chosen was `share`.)

`/usr/local/share/cin-data-tables`

  Data tables for input methods.

  `/usr/local/share/cin-data-tables/hiragana`
    conversion from ASCII to Hiragana using just Nihon-shiki and Kunrei-shiki
  `/usr/local/share/cin-data-tables/katakana`
    conversion from ASCII to Katakana and symbols using a grab-bag combination of Nihon-shiki, Kunrei-shiki, Hebon-shiki, Hyoojun-shiki, old ANSI and BS standards, and unofficial but common stuff
  `/usr/local/share/cin-data-tables/romaji-x11`
    conversion from ASCII to Romaji using a subset of the common X11 compose-key sequences, excluding anything already typeable with an ISO 9995 keyboard's common secondary group
`/var/service-bundles`

  The main set of packaged service bundles for system-wide services. This is split into services and targets in the same way as `/etc/service-bundles`. But the `/var/service-bundles/targets` directory is simply a symbolic link to `/etc/service-bundles/targets`. Various files of interest are:

  `/var/service-bundles/services/dbus/service/system-wide.conf`
    the configuration file used by the system-wide Desktop Bus service, that incorporates `/usr/local/etc/dbus-1/system.conf` by reference
  `/var/service-bundles/services/console-fb-realizer@*/service/fonts/*.fnt`
    fonts for `console-fb-realizer`
  `/var/service-bundles/services/console-kvt-realizer@*/service/fonts/*.fnt`
    fonts for `console-kvt-realizer`
`/var/local/service-bundles/services`

  Administrator-supplied service bundles and service bundles generated by the external formats import subsystem. Various files of interest are:

  `/var/local/service-bundles/services/user-dbus@jim/service/per-user.conf`
    the configuration file used by `jim`'s per-user Desktop Bus service, that incorporates `/usr/local/etc/dbus-1/session.conf` by reference
`/var/log/sv`

  Log directories for individual system-wide services, one subdirectory per logging service. Individual log subdirectories are always owned by the superuser.

`/var/log/user`

  The container for all per-user logging directories. This is owned by the superuser, with only the superuser having access to create/delete files and subdirectories in it.

`/var/log/user/jim`

  Log directories for the individual per-user services run by user `jim`, one subdirectory per logging service. Everything is always owned by `jim`.

## User directories

`~jim/.config/system-control/presets`

  Presets for `jim`'s per-user services and targets. This has the same substructure as `/etc/system-control/presets/`.

`~jim/.config/system-control/convert`

  Per-user external configuration import for `jim`'s per-user services and targets. This has the same substructure as `/etc/system-control/convert/per-user/` and is initialized from it by the system-wide external configuration import.

`~jim/.config/service-bundles`

  Service bundles for `jim`'s per-user services and targets. This has the same substructure as `/etc/service-bundles/`.

`~jim/.config/service-bundles/common/env`

  Common environment for many of `jim`'s per-user services. This allows one to set environment variables like `DBUS_SESSION_BUS_ADDRESS` globally across all of said services.

`~jim/.config/service-bundles/services/mpd/service/mpd.conf`

  Where external configuration import sets up `jim`'s Music Player pointer file that locates its other parts. This is symbolically linked from `~jim/.config/mpd/mpd.conf` so that (unless changed) non-dæmon Music Players use the same configuration.

`~jim/.config/uschedule/`

  Where external configuration import sets up `jim`'s command and job area for Uwe Ohse's uschedule. This is symbolically linked from `~jim/.uschedule` for compatibility.

`~jim/.local/share/dbus-1/services`

  Where per-user external configuration import sets up override Desktop Bus server definitions. These overrides use the per-user service manager to start services that start the various Desktop Bus server programs, instead of the broker spawning them directly. They also work around a Desktop Bus broker code bug that requires `User=` even in per-user files like these, otherwise it does not run `dbus-daemon-launch-helper`. They include:

  `~jim/.local/share/dbus-1/services/org.kde.knotify.service`
    server definition for KDE's Notify Desktop Bus server
  `~jim/.local/share/dbus-1/services/org.a11y.Bus.service`
    server definition for the subordinate "accessibility" Desktop Bus server
  `~jim/.local/share/dbus-1/services/org.gnome.Terminal.service`
    server definition for GNOME Terminal's dæmon
`~jim/.local/share/mpd`

  Where external configuration import sets up `jim`'s Music Player service's data files and directories. These include:

  `~jim/.local/share/mpd/database`
    the player's database
  `~jim/.local/share/mpd/playlists`
    the player's play lists
  `~jim/.local/share/mpd/sticker.sql`
    the player's sticker database
`~jim/.cache/mpd/state`

  Where external configuration import sets up `jim`'s Music Player service's cached runtime player state.

`~jim/Music`

  Where external configuration import sets up `jim`'s Music Player service's shared (with other players) music files.