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.
/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
utx
service/run/utmp
utx
service running login-update-utmpx
/run/machine-id
/etc/machine-id
/run/dmesg.boot
dmesg
service and redundant with the log of the klogd
service/run/log
local-syslog-read
service listens on/run/logpriv
local-priv-syslog-read
service listens on/run/motd.dynamic
motd-dynamic
service/run/ld-elf.so.hints
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
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/sv/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
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
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
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
console-input-method@head0
service/run/dev/head0mux
console-multiplexor@head0
service/run/dev/vc1
terminal-emulator@vc1
service to whose TTY side the ttylogin@vc1-tty
service attaches/run/dev/vc2
terminal-emulator@vc2
service to whose TTY side the ttylogin@vc2-tty
service attaches/run/dev/vc3
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
/etc
Miscellany. This directly contains files such as:
/etc/machine-id
machine-id
service (which runs setup-machine-id
and erase-machine-id
)/etc/hostid
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
rc.conf
file/etc/rc.conf
rc.conf
file/etc/rc.conf.local
rc.conf
file/etc/fstab
/etc/ttys
system-control
's preset
subcommand and the external formats import subsystem to configure TTY login service bundles/etc/vconsole.conf
rc.conf
settings by amalgamation/etc/network/interfaces
rc.conf
settings by amalgamation/etc/hostname
rc.conf
setting by amalgamation/etc/hostname.interface
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
/etc/system-control/convert/all.do
/etc/system-control/convert/rc.conf
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
/etc/nsswitch.conf
which one can symbolically link to /etc/host.conf
/etc/system-control/convert/kbdmaps/*
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
.capsctrl
variants/etc/system-control/convert/soft_backspace.kbd
backspace ⌫
key is soft-switchable by the terminal emulator/etc/system-control/convert/soft_delete.kbd
delete ⌦
key is soft-switchable by the terminal emulator/etc/system-control/convert/soft_enter.kbd
enter
key is soft-switchable by the terminal emulator/etc/system-control/convert/soft_return.kbd
return ⮠
key is not hardwired/etc/system-control/convert/default_to_de.kbd
/usr/share/vt/keymaps/
keyboard maps/etc/system-control/convert/jp_to_jp.104.kbd
/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
/usr/share/vt/keymaps/
keyboard maps/etc/system-control/convert/jp_to_jp.104.kbd
/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
/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
/etc/system-control/convert/dbus/*.service
/usr/share/dbus-1/system-services
/etc/system-control/convert/per-user/*.do
~jim/.config/system-control/convert
/etc/system-control/convert/per-user/dbus/*.service
/usr/share/dbus-1/services
and linked into each user's ~jim/.config/system-control/convert
/etc/system-control/presets
/usr/share/system-control/presets
/usr/local/etc/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:
/etc/system-control/presets
/usr/share/system-control/presets
/usr/local/etc/system-control/presets
/etc/systemd/system-preset
/lib/systemd/system-preset
/usr/lib/systemd/system-preset
/usr/local/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.
/etc/systemd/user-preset
/lib/systemd/user-preset
/usr/lib/systemd/user-preset
/usr/local/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.
/usr/local/etc/cin-data-tables
Data tables for input methods.
/usr/local/etc/cin-data-tables/hiragana
/usr/local/etc/cin-data-tables/katakana
/usr/local/etc/cin-data-tables/romaji-x11
/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
/usr/local/etc/dbus-1/system.conf
by reference/var/service-bundles/services/console-fb-realizer@*/service/fonts/*.fnt
console-fb-realizer
/var/local/sv
Administrator-supplied service bundles and service bundles generated by the external formats import subsystem. Various files of interest are:
/var/local/sv/user-dbus@jim/service/per-user.conf
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
.
~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
~jim/.local/share/dbus-1/services/org.a11y.Bus.service
~jim/.local/share/dbus-1/services/org.gnome.Terminal.service
~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
~jim/.local/share/mpd/playlists
~jim/.local/share/mpd/sticker.sql
~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.