Skip to content

Engine Namespace

Jump to bottom
Bjorn Stahl edited this page Sep 19, 2017 · 2 revisions

This part of the design documentation covers the namespaces available.

For the sake of terminology, we use namespace here to cover an isolated grouping of names that are used to reference resources. In its most practical sense, it is used as a way of restricing where and how arcan and its various components are allowed to access and create files on the computer it is running on.

The following, rather intimidating figure, illustrates available namespaces and how they are mapped.

namespaces

The specific heuristics used to set the defaults are OS specific and related code can be found in platform/ os name /paths.c and, to a lesser extent, namespace.c. This is a rather legacy ridden feature from earlier versions where we only had a themepath (now RESOURCE_APPL) and resourcepath(now RESOURCE_APPL_SHARED).

To quickly describe the various namespaces and their intended role:

  • RESOURCE_APPL - The folder of the currently active appl and is treated as read-only. When an appl tries to load an image or a script file this is the first path that is searched.

  • RESOURCE_APPL_SHARED - Read-only folder with shared data like icons, images and support scripts.

  • RESOURCE_APPL_TEMP - By default, this is mapped to the same folder as the appl but is used in a read-write fashion. When an appl needs to update, create or delete images, text blocks or other data objects, this is the only place it is allowed to do so in. By default, this is mapped to the same path as RESOURCE_APPL but can be remapped to disallow self-modifying appl behavior.

  • RESOURCE_APPL_STATE - This namespace is read and write but restricted to the subset of features that involve frameserver state serialization. Some frameserver types permit saving and restoring state. State is an opaque data blob indiginous to a frameserver.

  • RESOURCE_SYS_APPLBASE - Folder from which new appls can be selected from, meaning that appls that explicitly call system_collapse in order to switch to another appl, references this namespace. It is also used to define RESOURCE_APPL during load time (RESOURCE_SYS_APPLBASE/applname)

  • RESOURCE_SYS_APPLSTORE - Similar to SYS_APPLBASE, but used for APPL_TEMP and is by default equal to SYS_APPLBASE. RESOURCE_APPL_TEMP is expanded as (RESOURCE_SYS_APPLBASE/applname)

  • RESOURCE_SYS_APPLSTATE - Similar to SYS_APPLBASE and SYS_APPLSTORE and is by default defined as APPL_SHARED/savestates (for legacy reasons).

  • RESOURCE_SYS_FONT - Fonts can be referenced and embedded as part format strings passed to the render_text function call. By default, this is set to APPL_SHARED/fonts (for legacy reasons) but in more sensitive settings one might want to redefine to a more controlled namespace due to the complexity involved in parsing and rendering fonts as a possible attack vector.

  • RESOURCE_SYS_BIN - Points to the base path and prefix of the active built-in frameservers, e.g. /usr/bin/arcan_frameserver. When an appl calls a function that implies spawning a frameserver, this is expanded along with possibly archetype (decode, encode etc.) and later executed.

  • RESOURCE_SYS_LIBS - Points to a folder where the set of allowed hijack libraries are present. This is used for launching targets that is defined as having interpositioned pre-loaded libs in the database.

  • RESOURCE_SYS_DEBUG - Points to a folder where log and debug files will be generated. By default, it is sert to APPL_SHARED/logs but one might want to point this elsewhere for monitoring, logging and debugging purposes.

There also exists a number of ways to redefine where these namespaces point. The engine will refuse to start if not all required namespaces are mapped in a valid way. If that happens, the engine will output a list of the current mapping, indicating which ones that are missing, to help debugging.

The more common way of setting the namespaces come from the command-line argument -t (which sets APPLBASE), -B (which sets SYS_BIN) and -p (which sets APPL_SHARED).

They can also be set via the database in the 'arcan' appl keyspace, e.g.

 arcan_db add_appl_kv arcan path_appl /tmp

with the possible keys being: path_appl, path_resource, path_state, path_applbase, path_applstore, path_statebase, path_font, path_bin, path_lib, path_log

For posix- related platforms, there is also the option to use environment variables to more finely define which namespaces points to where. These environment variables are (ENV(NAMESPACE) pattern):

ARCAN_APPLPATH(RESOURCE_APPL), ARCAN_RESOURCEPATH(RESOURCE_APPL_SHARED), ARCAN_APPLTEMPPATH(RESOURCE_APPL_TEMP), ARCAN_APPLBASEPATH(RESOURCE_SYS_APPLBASE), ARCAN_STATEBASEPATH(RESOURCE_SYS_APPLSTATE), ARCAN_APPLSTOREPATH(RESOURCE_SYS_APPLSTORE), ARCAN_FONTPATH(RESOURCE_SYS_FONT), ARCAN_BINPATH(RESOURCE_SYS_BIN), ARCAN_LIBPATH(RESOURCE_SYS_LIBS), ARCAN_LOGPATH(RESOURCE_SYS_DEBUG).

It is not permitted for the running appl to traverse outside namespace confinement, though this is platform implementation defined (some platforms do not currently provide traversal protection).

Clone this wiki locally