Configuration Support
Arcan uses an in-memory or on-disk database as a key-value store for keeping track of permitted programs to execute, appl specific configuration and engine platform specific configuration. This database can be controlled and queried with the use of the included arcan_db tool. There is also an optional FUSE based tool that provide an opt-in mechanism for scripts to expose their runtime configuration as a mountable filesystem, arcan_cfgfs.
An early design criteria is that scripts shouldn't be allowed to define arbitrary execution of other programs by default, it has to be explicitly permitted on a case to case basis. That also holds true for external connections via the ARCAN_CONNPATH environment, and the value to which it is set, the connection point - which pairs script specific policy with individual clients or group of clients.
The preferred mechanism for hooking up clients is actually 'launch targets', which can operate in the common 'internal launch' mode or the slightly more rare 'external launch' mode. The scripts have access to functions that enumerate targets and so on. This is preferred as the process is spawned and controlled from the main arcan instance, keeping the chain of trust intact and inheriting the connection primitives needed to transfer data. It is thus not possible for an external client to invisibly 'proxy' and listen in on another client's execution, and scripts have knowledge about which clients come from where.
A target has a name, a set of optional script- specific tags, a binary format, a set of 0 to many environment variables and one or many configurations. The basic target is added like this:
arcan_db add_target name -tag1 -tag2 -tagN binary_format arg1 arg2 argN
The current set of binary formats are 'BIN', 'EXTERNAL' and 'RETRO' - with reserved ones being 'SHELL', 'LWA' and 'WAYLAND'. A binary format defines how the execution of a target is to be set up, if there needs to be a loader of some sort. 'BIN' is simply any old binary that knows how to communicate using the SHMIF API.
As a slightly dumb example, you can see:
arcan_db add_target terminal BIN afsrv_terminal
arcan_db add_config terminal default
which would execute the builtin terminal emulator without any arguments. It's a dumb example because the terminal has a special path for being launched anyway. Anyhow, note the add_config command. A target can't be executed on its own, there need to be at least one configuration, which defines additional arguments and environment variables to be attached to the ones defined by the target. The main reason for this is to let the scripts have an easier time to keep track of individual runtime options.
The optional -tag attributes are primarily for indexing, to further let scripts set specific roles for indexing or searching. Though they are tied to a specific scripts and hence need to be paired to whatever is in the corresponding documentation, normal ones are -external, -autorun, -service.
As for the binary formats, 'EXTERNAL' is a special version of 'BIN' and requires that the scripts also specify that they want the launch of the target to be in 'LAUNCH_EXTERNAL' mode (usually paired with a tag that is set to -external). This mode forces the engine to stop everything and release all resources that can be reliably rebuilt, hand over execution to the target and wait for it to finish. It is thus intended for low resource settings, like handing over from a boot- "splash/config/display manager" script to a 'WM', for embedded like 'launchers' and for safer mobile 'suspend/resume' like control. When waking up from an external setup, video layers etc. are rebuilt, which activates special paths to reset device input state trackers and scanning display connectors and so on for devices or monitors being added or lost.
As an example, say that we have a 'suspend' tool that can put the system in hibernation mode or more.
arcan_db add_target suspend -external /usr/sbin/zzz
arcan_db add_config sleep -S
If the script would perform something like target_launch("suspend", "sleep", LAUNCH_EXTERNAL) the resolved execution path would become /usr/sbin/zzz -S.
'RETRO' is a binary format that uses the afsrv_game loader, which understands the libretro format, and can load "cores". Similarly, (though still unfinished), 'LWA' is for nested arcan applications and 'Wayland' for the arcan-wayland loader.
Each set of scripts gets its own key-value store. For instance, to see all the live configuration that durden tracks, you can use:
arcan_db show_appl durden
and the tool would output the settings that are stored. Although the preferred option is that the scripts provide interactive mechanisms for changing options, this support is provided here as a means of recovering if something should go wrong, allow distributions and packagers options to provide other defaults, to allow you to have multiple sets of options to switch out - or to use for snapshotted tracking and sharing of configuration.
The name 'arcan' is reserved for platform specific configuration. Running arcan without any arguments should show a list of accepted keys. This can be used to hard-code or override decisions, like to block certain devices or to specify priority when it comes to output displays and resolutions. For example:
arcan_db add_appl_kv arcan video_device=/dev/dri/card4 would force the first GPU to be considered to be at the specific /dev/dri/card4 path. This helps integrating with distribution or init system specific setups where paths might change between boots - while cutting down on environment variable abuse.
This tool is a fuse driver that has to be built separately. It requires a socket and a set of scripts that implement a simple text based format for exposing a filesystem like tree of config options, actions and values. For durden the feature can be activated by going to global/settings/system/control and define the name of a socket.
By then using:
arcan_cfgfs --control /path/to/durden/ipc/control /my/mount/path you get a mount that can be used for both exploration and feature discovery, and for scriptable automation - reusing familiar command line tools.