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 advanced visualization and analysis work in a wide range of applications e.g. game development, real-time streaming video, monitoring and surveillance, 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 context need to be rebuilt. Note that the behaviors of this option may vary radi- cally depending on video platform. Verify and Validate 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 configuration 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, --monitor- 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 inherited file descriptor number. -C, --monitor-ctrlilename or - Sets filename (use - for stdin) to work as a blocking control inter- face / watchdog that is triggered upon sending SIGUSR1 to the process. This can preempt script execution and is intended as an in- ternal developer facing channel for building better inspection and debugging tools. Refer to the source implementation for arcan_moni- tor.c for commands and processing. -p, --rpath path Change default searchpath for shared resources, see the namespaces section below for additional details. -B, --binpath path Specify the full path to the desired frameserver (e.g. /usr/bin/ar- can_frameserver) or to a prefix /path/to/prefix_ (decode, 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 sec- tion 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 argu- ments 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 applname 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 debuglevel is also exposed to scripts. This can be added multiple times for addi- tional effect. Debuglevels over 2 enabled engine features that change engine behavior and notably increases verbosity. -V, --version Print a version string to stdout and then terminate. This version 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 connec- tion point is generated and written to stdin. This is supposed 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 (as- suming it passes normal connection point validation). Unstable Arguments These are slated to be replaced with a more flexible display config- uration 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 features. -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 con- nected display resolution to match the specified canvas dimensions. -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 tuning 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 petnames 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 for- mat: 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 ex- ternal 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 resource. The way these are set up will vary depending on command-line arguments, operat- ing-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 developer perspective, please refer to the developer documentation on the wiki. This setup is rather complex in order to account for a large range of plat- forms and use-cases, with the most simple configuration being an applica- tion 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 con- fines 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 gen- eration. The most fine-grained control can be obtained by setting a number of envi- ronment 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 development 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 default, this is resolved to the same folder as the appl is - but can be un- mapped to prevent an appl from killing or modifying itself. 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 fall- back to RESOURCEPATH/fonts but can be set to some other system font directory for more fine-grained control (as font-parsing is complex and can be a source of vulnerabilities). ARCAN_BINPATH The default is to set this to /usr/bin/arcan_frameserver (or wher- ever the frameserver is installed, first searching ./ then /usr/lo- cal/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 referenced as RE- SOURCE_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/troubleshooting 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 ARCAN_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 inher- ently 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 (arche- types), 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 environment 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 dy- namically 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_recordtar- get(...). LIGHTWEIGHT (LWA) ARCAN Lightweight arcan is a specialized build of the engine that uses the frame- server 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 ap- plication framework, rendering engine and display server all rolled into one. The lwa build works just the same (although likely with fewer dependencies on external libraries) as the main version, except the ARCAN_CONNPATH envi- ronment need to be set to a connection point that the arcan instance ex- poses. HEADLESS ARCAN Headless arcan is a specialized build of the engine that performs all ren- dering 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 capabili- ties of the encode frameserver. By setting the video platform argument for ARCAN_VIDEO_ENCODE=encode_args, the output can be recorded or streamed, in- teractively 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 output, 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 dis- tributed 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 re- peated 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 argument 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 ex- ternal 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 database for the spe- cific 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_peri- odic=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 suffix 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 de- bugger to it. The delay can be configured through debugstall=val (default is 10) on the command- line. hook/alloc_debug This scripts intercepts all allocation functions and attaches a de- bug 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 input. 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 en- gine was built in Debug mode. A governing principle for user supplied scripts is that of Fail Often, Early and Hard. This means that API misuse, i.e. missing or wrong arguments will result in a crash and the related er- ror description will be provided (color-coded) to the standard 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 standard 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 con- tact and discussion, see the #arcan IRC channel on freenode. Save a snap- shot of core-dumps (in the case of engine issues) or the appropriate re- sources/logs entries. For some issues, a copy of the database used and a list of files (with permissions) in applpath and resourcepath may also be relevant. COPYRIGHT Copyright A(C) 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+15.1.quarterly>