Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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)

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>

home | help