FreeBSD Manual Pages
arcan(1) User manual arcan(1) NAME Arcan - Scriptable Multimedia Engine SYNOPSIS arcan [OPTIONS] applname [APPLARGS] DESCRIPTION Arcan is a portable and fast self-sufficient multimedia engine for ad- vanced visualization and analysis work in a wide range of applications e.g. game development, real-time streaming video, monitoring and sur- veillance, up to and including desktop compositors and window managers. OPTIONS -h, --help Show a brief summary of commands and usage. -w, --width pixels Set the desired active canvas width. Setting this value to zero will let the display driver chose based on connected displays. This can be overridden by the running appl. This value will be cached/fetched from the database. -h, --height pixels Set the desired active canvas height. Setting this value to zero will let the display driver chose based on connected displays. This can be overridden by the running appl. This value will be cached/fetched from the database. -m, --conservative Toggle conservative memory management profile. The engine will store just enough metadata to be able to reconstruct static data sources (e.g. most textures, fonts etc.) should the display con- text need to be rebuilt. Note that the behaviors of this option may vary radically depending on video platform. Verify and Vali- date heavily when using conservative mode. -W, --sync-strat strategy Specify the synchronization strategy that the display driver should use initially. These are dependent on the built-time con- figuration of the engine and are listed at the end of running arcan with the --help command-line argument. -M, --monitor rate Enable monitoring mode, every rate ticks, save a snapshot of the scripting engine state to a monitoring target (see -O, --moni- tor-out). If the rate is set to a negative value, only script errors will be written. -O, --monitor-out target Defines the monitoring data recipient, used in combination with -M, --monitor. Either specify LOG:filename or LOGFD:fdno for a file destination or for -C, --monitor-ctrl Sets STDIN to work as a blocking control interface / watchdog that is triggered upon sending SIGUSR1 to the process. This can preempt script execution and is intended as an internal devel- oper facing channel for building better inspection and debugging tools. Refer to the source implementation for arcan_monitor.c for commands and processing. -p, --rpath path Change default searchpath for shared resources, see the name- spaces section below for additional details. -B, --binpath path Specify the full path to the desired frameserver (e.g. /usr/bin/arcan_frameserver) or to a prefix /path/to/prefix_ (de- code, encode, game, terminal, remoting). -L, --libpath path Set the search path for native libraries (used e.g. by lua sys- tem_load). -t, --applpath path Change default searchpath for applications, see the namespaces section below for additional details. -T, --scriptpath path Change the default search path for builtin system scripts, see the namespaces section below for additional details. -H, --hook Specify a post-init (after running applname()) hook script that will be loaded and executed. The scripts are fetched from the system scripts namespace (-T, --scriptpath). Providing multiple -H arguments is allowed. See the hookscripts section below for additional details. -b, --fallback applname If the running application crashes due to scripting error or from misuse of the API, all running external or recoverable frameserver, connections will be transferred to applname. If ap- plname is set to the reserved value :self the same appl will be used without running a verifyload cycle. -d, --database dbname Specify a different database for use when launching external targets and as a key/value store for the running application, overriding the default of HOMEDIR/.arcan/arcan.sqlite. -g, --debug Increases debuglevel, more troubleshooting data will be sent to the standard error and standard output nodes. The active debu- glevel is also exposed to scripts. This can be added multiple times for additional effect. Debuglevels over 2 enabled engine features that change engine behavior and notably increases ver- bosity. -V, --version Print a version string to stdout and then terminate. This ver- sion string can be used to identify the build, including audio, video, input platforms and source code repository checkout id. -1, --pipe-stdout This is only usable from an arcan_lwa instance. A requested con- nection point is generated and written to stdin. This is sup- posed to be used with a normal arcan instance running piped with -0 and act as a generic mechanism for hooking up multiple arcan instances in a pipes-and-filters structure. -0, --pipe-stdin See the description for 'pipe-stdin'. Reads a single line from stdin and tries to open an external connection point with that name (assuming it passes normal connection point validation). Unstable Arguments These are slated to be replaced with a more flexible display configuration system and will be changed in coming versions. Users should therefore take precautions to make sure to notice when upgrading as not to break scripts that depend on these fea- tures. -S, --nosound Disable (silence) audio output. -s, --windowed Set borderless, windowed display mode. -f, --fullscreen Fullscreen switch, the display driver will attempt to force the connected display resolution to match the specified canvas di- mensions. -a, --multisamples samples Enable multisampling (MSAA), default: 4 samples. If MSAA setup fails, the engine will silently revert to regular sampling. There is also a range of possible environment variables for tun- ing options related to the various input platforms. These are printed when you start arcan with the --help argument and vary depending on how the engine was compiled. USER-NAMESPACES For dynamically exposing files and folders with user controlled pet- names and access restructions, the database and the 'arcan' appl key value store is used. This is mainly useful / intended for cases where Arcan is used as the system display server and desktop. The keys and values follows the format: key=ns_petname value=Label:permissions:path. As an example, exposing the user home directory on a POSIX system would be: arcan_db add_appl_kv arcan ns_home Home:rw:/home/me This is intended to be controlled / managed by dynamic tools, like an external drive or encrypted storage mounting daemon. NAMESPACES There is a large assortment of namespaces that the engine will search for when an appl requests read access to- or the creation of- a re- source. The way these are set up will vary depending on command-line arguments, operating-system specific scans, if applname was specified as a relative/absolute path and on a series of environment variables. For a more detailed explanation on how this works from an appl devel- oper perspective, please refer to the developer documentation on the wiki. This setup is rather complex in order to account for a large range of platforms and use-cases, with the most simple configuration being an application base folder (controlled with the -t command-line switch) and a shared resource folder (Controlled with the -p switch). The most important namespaces are the APPLBASE and the RESOURCEPATH. Appls can manipulate (create, open, read, write) the files within the confines of the APPLBASE/APPNAME. Traversal (../) outside this path will be blocked, but a user can explicitly map (symlink, bind-mounts or similar) other paths into this namespace and the engine will allow it. Scripts are treated as an overlay namespace where there is a priority order in the event of a collision. By default, scripts are treated in the order of APPLTEMP -> APPLBASE -> SCRIPTPATH. More paranoid builds will want to disable APPLTEMP to prevent the creation of a unpacker scripts / code generation. The most fine-grained control can be obtained by setting a number of environment variables: ARCAN_RESOURCEPATH Shared resources, as described above. ARCAN_SCRIPTPATH The system script namespace contains shared scripts that are part of the general Arcan package to promote optional re-use of higher level analysis like mouse gestures. The default search- path for this is would be the share/arcan/scripts install path, though you might want to override this for custom setups or de- velopment purposes. ARCAN_APPLTEMPPATH Used when there is a need to split the folder that an appl can use as a writable (delete, create, update) backing store. By de- fault, this is resolved to the same folder as the appl is - but can be unmapped to prevent an appl from killing or modifying it- self. ARCAN_APPLBASEPATH This path is used to search for appls but may be ignored for ab- solute paths specified on the command-line. ARCAN_APPLSTOREPATH The default setting is to allow the appl full access to its own folder, but this can be split into a separate store. This will then expand as ARCAN_APPLSTOREPATH/APPLNAME. ARCAN_STATEBASEPATH The default setting is to map this to RESOURCEPATH/savestates and will then be shared between all appls (which holds true whenever STATEBASE is set to a subdirectory of RESOURCEPATH). ARCAN_FONTPATH The default setting is to map this to the APPLPATH/fonts with fallback to RESOURCEPATH/fonts but can be set to some other sys- tem font directory for more fine-grained control (as font-pars- ing is complex and can be a source of vulnerabilities). ARCAN_BINPATH The default is to set this to /usr/bin/arcan_frameserver (or wherever the frameserver is installed, first searching ./ then /usr/local/bin then /usr/bin). ARCAN_LIBPATH This path specifies the directory where the appl is allowed to load libraries from using system_load. The namespace is refer- enced as RESOURCE_SYS_LIBS in the scripting documentation. ARCAN_LOGPATH Set to RESOURCEPATH/logs by default (if it exists) and is used for storing debugging, profiling and similar development/trou- bleshooting related data. This includes state dumps which may contain sensitive data. Some namespaces are also reset when an appl does an explicit switch, this behavior can be cancelled out by setting AR- CAN_XXXPIN for any namespaces that should explicitly be locked to some path. FRAMESERVERS A principal design decision behind Arcan is to split tasks that are in- herently prone to security and stability issues into separate processes that should be sandboxed to as large a degree as possible with the principle of least privilege in mind. These behave like 'normal' clients but are grouped into fixed roles (archetypes), like 'decode' is responsible for image parsing and so on. They are chainloaded by 'arcan_frameserver' into its respective role (afsrv_) based on a probe done at startup, a build-time mask and an en- vironment controlled mask. For instance, to block the 'terminal' role, set AFSRV_BLOCK_TERMINAL. It should be the active application (set of user-supplied scripts) that dynamically control the level of privilege, communication and data storage that such processes have access to. These are mainly an internal developer detail, some scripting functions transparently set them up - e.g. launch_decode(...) and define_record- target(...). LIGHTWEIGHT (LWA) ARCAN Lightweight arcan is a specialized build of the engine that uses the frameserver shared memory API as its audio/video display backend. This allows Arcan to run and control additional instances of itself, with the same or a different application, thus reusing the engine to fulfill the role of application framework, rendering engine and display server all rolled into one. The lwa build works just the same (although likely with fewer dependen- cies on external libraries) as the main version, except the ARCAN_CON- NPATH environment need to be set to a connection point that the arcan instance exposes. HEADLESS ARCAN Headless arcan is a specialized build of the engine that performs all rendering in memory, and normally do not try to output anything to the screen. It adds the option to use other software defined outputs via the capabilities of the encode frameserver. By setting the video plat- form argument for ARCAN_VIDEO_ENCODE=encode_args, the output can be recorded or streamed, interactively as well as non-interactively. See the afsrv_encode binary for the possible encoding options. A special detail with this build is that, since there is no strict out- put, the default virtual display dimensions have to be set explicitly via the -w and -h arguments. HOOK SCRIPTS There is a built-in set of more generic and re-usable scripts being distributed along with the engine. These are normally installed as a 'scripts' subdirectory in the shared set of files, though this path can be changed with the -T argument. A hookscript is enabled via the -H command line argument, which can be repeated to chain them together. Their arguments are extracted from the appl-arguments part of the command line in the key=value form. hook/shutdown.lua This hookscript sets a timer to whatever a shutdown=number argu- ment on the commandline provides, or the built-in default of 500 ticks. When the timer fires, an asynchronous shutdown request will be queued. This allows for easier automation and testing. hook/external_input.lua This hookscript opens up a connection point where you can attach external input drivers. The default connection point for the first hook script will be extio_1, this will increment for each instance of the script that is added to the command line. The extio prefix can be tuned by adding the ext_io key to the data- base for the specific appl being run, and only one input provider can be attached to the connection point at a time. hook/timed_dump.lua This script sets a timer to whatever dump_timer=number or dump_periodic=number on the command-line is set to. When the timer fires, it calls system_snapshot into 'timed_n.lua" or whatever dump_prefix is set to on the command-line. The _n suf- fix corresponds to the dump sequence if on a periodic timer. hook/debugstall.lua This scripts enables the frameserver debugstall (delay whenever a frameserver is launched) as a tool to make it easier to attach a debugger to it. The delay can be configured through de- bugstall=val (default is 10) on the command- line. hook/alloc_debug This scripts intercepts all allocation functions and attaches a debug traceback as the 'tag' property of the video object. This can then be used in system_snapshot and crash-dumps to figure out where a certain allocation came from. hook/touch_simulator.lua This script takes over mouse input and re-injects as touch in- put. Since it intercepts the input appl- handler, it is best used as a pre: hook rather than the default (post). DIAGNOSTICS There are a number of ways the engine can shut down, especially if the engine was built in Debug mode. A governing principle for user supplied scripts is that of Fail Often, Early and Hard. This means that API mis- use, i.e. missing or wrong arguments will result in a crash and the related error description will be provided (color-coded) to the stan- dard output, and that a state dump will be generated and stored in the namespace specified by ARCAN_LOGPATH. This state dump is a Lua parsable script that can be loaded either by a regular Lua interpreter. The environment variable ARCAN_FRAMESERVER_DEBUGSTALL can be set if you suspect that a frameserver is involved, or to blame, for an issue. This will print the process ID (pid) of the new frameserver process to stan- dard output, then sleep for the argument supplied number of seconds, to provide enough time to attach a debugger or tracing tool. There is also a way to trace the events that are passed between the main process and all the framesevers, and that is via the environment variable ARCAN_SHMIF_DEBUG=1. HOMEPAGE https://arcan-fe.com SEE-ALSO arcan_api_overview(3) arcan_lwa(1) arcan_frameserver(1) arcan_db(1) BUGS You can report bugs through the tracker on the github page. For normal contact and discussion, see the #arcan IRC channel on freenode. Save a snapshot of core-dumps (in the case of engine issues) or the appropri- ate resources/logs entries. For some issues, a copy of the database used and a list of files (with permissions) in applpath and resour- cepath may also be relevant. COPYRIGHT Copyright 2003-2020 Bjorn Stahl. License GPLv2+ or BSD depending on build configuration. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. AUTHOR Bjorn Stahl <contact at arcan-fe dot com> arcan November 2020 arcan(1)
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | USER-NAMESPACES | NAMESPACES | FRAMESERVERS | LIGHTWEIGHT (LWA) ARCAN | HEADLESS ARCAN | HOOK SCRIPTS | DIAGNOSTICS | HOMEPAGE | SEE-ALSO | BUGS | COPYRIGHT | AUTHOR
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=arcan&sektion=1&manpath=FreeBSD+Ports+14.3.quarterly>