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.