x11docker options overview

x11docker: Run GUI applications and desktop environments in Docker containers.

Usage:
To run a Docker container on a new X server:
  x11docker IMAGE
  x11docker [OPTIONS] IMAGE [COMMAND]
  x11docker [OPTIONS] -- IMAGE [COMMAND [ARG1 ARG2 ...]]
  x11docker [OPTIONS] -- DOCKER_RUN_OPTIONS -- IMAGE [COMMAND [ARG1 ARG2 ...]]
To run a host application on a new X server:
  x11docker [OPTIONS] --exe COMMAND
  x11docker [OPTIONS] --exe -- COMMAND [ARG1 ARG2 ...]
To run only an empty new X server:
  x11docker [OPTIONS] --xonly
  
x11docker always runs a fresh container from image and discards it afterwards.

Optional features:
  * GPU hardware accelerated graphics
  * Sound with pulseaudio or ALSA
  * Clipboard sharing
  * Printer access
  * Webcam access
  * Persistent home folder
  * Wayland support
  * Language locale creation
  * Several init systems in container
  * DBus in container
  * Support of different container runtimes
Focus on security:
  * Avoids X security leaks using additional X servers.
  * Container user is same as host user to avoid root in container.
  * Restricts container capabilities to bare minimum.
  
Note that some applications might behave different than with a regular
'docker run' command due to security restrictions set by x11docker.
Unrestricted container setup is possible with --cap-default and/or --user=root

Dependencies on host:
  For core functionality x11docker only needs bash, docker and an X server.
  Depending on chosen options x11docker might need some additional tools.
  It checks for them on startup and shows messages if some are missing.
  Core list of recommended tools:
   * Recommended to allow security and convenience:
       X servers: Xephyr xpra nxagent
       X tools:   xauth xclip xrandr xhost xinit
   * Advanced GPU support: weston Xwayland xpra xdotool
  See also: https://github.com/mviereck/x11docker/wiki/Dependencies

Dependencies in image:
  No dependencies in image except for a few feature options. Most important:
   --gpu:  OpenGL/MESA packages, collected often in 'mesa-utils' package.
   --pulseaudio: Needs pulseaudio on host and pulseaudio client libs in image.
   --printer: Needs cups on host and cups client libs in image.
  See also: https://github.com/mviereck/x11docker/wiki/Dependencies
  
   
Options: (short options do not accept arguments)
     --help            Display this message and exit.
 -e, --exe             Execute host application instead of docker command.
     --xonly           Only create empty X server.

Basic settings: (especially influencing automatical choice of X server)
 -d, --desktop         Indicate desktop environment in image.
 -g, --gpu             GPU access for hardware accelerated OpenGL rendering. 
                       Works best with open source drivers on host and in image.
                       For closed source nvidia drivers regard terminal output.
 -w, --wm [=ARG]       Provide a window manager to container applications.
                       If available, image x11docker/openbox will be used.
                       Otherwise x11docker looks for a host window manager.
                       Possible ARG:
                         host: Enforce autodetection of a host window manager.
                         COMMAND: COMMAND can be a desired host window manager.
                         IMAGE: IMAGE can be a local docker image with a WM.
                         none: Run without a window manager. Same as --desktop.

Shared folders:
 -m, --home [=DIR]     Share a host folder as home folder in container to store
                       persistent data. Uses ~/.local/share/x11docker/IMAGENAME.
                       Optionally specify another host folder DIR.
                       ( ~/.local/share/x11docker has a softlink to ~/x11docker.
                        Use --homebasedir to change the base storage folder.)
     --share PATH      Share host file or folder PATH. Read-only with PATH:ro
                       Device files in /dev can be shared, too.

Host integration:
 -c, --clipboard       Share clipboard. Graphical clips with --xpra only.
 -p, --pulseaudio [=MODE]  Sound with pulseaudio. Needs 'pulseaudio' on host
                       and in image. Optional arg MODE can be 'socket' or 'tcp'.
     --alsa [=CARDNAME]   Sound with ALSA. You can define a desired sound card
                       with CARDNAME. List of available sound cards: aplay -l
 -l, --lang [=LOCALE]  Set language variable LANG=LOCALE in container.
                       Without LOCALE host variable --lang=$LANG is used.
                       If LOCALE is missing in image, x11docker generates it
                       with 'localedef' in container (needs 'locales' package).
                       LOCALE can be e.g. ru, en, de, zh_CN, cz, fr, fr_BE.
 -P, --printer [=MODE] Share host printers through CUPS server.
                       Optional MODE can be 'socket' or 'tcp'. Default: socket
     --sharessh        Share SSH agent authentication socket from host.
     --webcam          Share host webcam device files.

X server options:
     --auto            Auto choose X server (default).
                       (Regards options --desktop, --gpu, --wayland and --wm).
 -a, --xpra            Nested X server supporting seamless and --desktop mode.
 -y, --xephyr          Nested X server for --desktop mode. Without --desktop,
                       a host window manager will be provided (option --wm).
 -n, --nxagent         Nested X server supporting seamless and --desktop mode.
                       Faster than --xpra and more flexible than --xephyr, but
                       some compositing applications have issues.
 -A, --xpra-xwayland   Like --xpra, but supports option --gpu.
 -Y, --weston-xwayland Desktop mode like --xephyr, but supports option --gpu.
                       Runs from console, within X and within Wayland.
 -h, --hostdisplay     Share host display :0. Quite bad container isolation!
                       Least overhead of all X server options.
                       Some apps may fail due to restricted untrusted cookies.
                       Remove restrictions with option --clipboard.
 -x, --xorg            Core Xorg server. Runs ootb from console.
                       Switch tty with <CTRL><ALT><F1>....<F12>.

Special X server options:
     --kwin-xwayland   Like --weston-xwayland, but using kwin_wayland
 -t, --tty             TTY only. Do not provide any X or Wayland server.
     --xdummy          Invisible X server using dummy video driver.
     --xvfb            Invisible X server using Xvfb.
                       --xdummy and --xvfb can be used for custom  VNC access.
                       Output of environment variables on stdout. (--showenv)
                       Along with option --gpu an invisible setup with Weston,
                       Xwayland and xdotool is used (instead of Xdummy or Xvfb).
 -X, --xwayland        Blanc Xwayland, needs a running Wayland compositor.
     --xwin            X server to run in Cygwin/X on MS Windows.

Wayland instead of X:
 -W, --wayland         Automatically set up a Wayland environment.
                       Chooses one of following options and regards --desktop.
 -T, --weston          Weston without X for pure Wayland applications.
                       Runs in X, in Wayland or from console.
 -K, --kwin            KWin without X for pure Wayland applications.
                       Runs in X, in Wayland or from console.
 -H, --hostwayland     Share host Wayland without X for pure Wayland apps.

X and Wayland appearance options:
     --border [=COLOR] Draw a colored border in windows from --xpra[-xwayland].
                       Optional COLOR can be e.g. 'orange' or '#F00'. Thickness
                       can be specified, too, e.g. 'red,3'. Default: 'blue,1'
     --dpi N           dpi value (dots per inch) to submit to clients.
                       Influences font size of some applications.
 -f, --fullscreen      Run in fullscreen mode.
     --scale N         Scale/zoom factor N for xpra, Xorg or Weston.
                       Allowed for --xpra, --xorg --xpra-xwayland: 0.25...8.0.
                       Allowed for --weston and --weston-xwayland: 1...9.
                       (Mismatching font sizes can be adjusted with --dpi).
                       Odd resolutions with --xorg might need --scale=1.
     --size XxY        Screen size of new X server (e.g. 800x600).
     --output-count N  Multiple virtual monitors for Weston, KWin or Xephyr.
     --rotate N        Rotate display (--xorg, --weston and --weston-xwayland)
                       Allowed values: 0, 90, 180, 270, flipped, flipped-90,
                       flipped-180, flipped-270.  (flipped means mirrored)
 -F, --xfishtank       Show fish tank on new X server.

X and Wayland special configuration:
     --clean-xhost     Disable xhost access policies on host display.
     --display N       Use display number N for new X server.
     --keymap LAYOUT   Set keyboard layout for new X server, e.g. de, us, ru.
                       For possible LAYOUT look at /usr/share/X11/xkb/symbols.
     --no-auth         Allow access to X for everyone. Security risk!
     --vt N            Use vt / tty N (regarded by --xorg only).
     --westonini FILE  Custom weston.ini for --weston and --weston-xwayland.
     --xhost STR       Set "xhost STR" on new X server (see 'man xhost').
                       (Use with care. '--xhost +' allows access for everyone).
     --xoverip         Connect to X over TCP network. For special setups only.
                       Only supported by a subset of X server options.
     --xtest [=yes|no] Enable or disable X extension XTEST. Default is yes for
                       --xpra, --xvfb and --xdummy, no for other X servers.
                       Needed to allow custom access with xpra. 

Special options:
     --env VAR=value   Set custom environment variable VAR=value
                       Special use case for user shell: '--env SHELL=/bin/sh'
 -i, --interactive     Run with an interactive tty to allow shell commands.
     --name NAME       Specify container name NAME.
     --no-internet     Disable internet access for container.
     --no-entrypoint   Disable ENTRYPOINT in image to allow other commands, too
     --enforce-i       Run x11docker in interactive bash mode to allow tty 
                       access. Can help to run weston-launch on special systems.
     --pull [=ask|yes|no|always]  Behaviour if image is missing on host.
                       ask: Ask in terminal, timeout after 60s (default).
                       yes: Allow docker pull (default for --pull).
                       no: Do not run or ask for 'docker pull'
                       always: Always run 'docker pull'. Download only if
                       newer image is available. Allows sort of auto-update.
     --pw FRONTEND     Choose frontend for password prompt. Possible FRONTEND:
                         su sudo gksu gksudo lxsu lxsudo kdesu kdesudo
                         pkexec beesu none
     --runfromhost CMD Run host command CMD on new X server (you may need & ).
     --runasroot CMD   Run command CMD as root in container on startup.
                       Caution: Runs with --privileged host access.
     --runtime RUNTIME Specify docker runtime. Known by x11docker:
                         runc:         Docker default runtime.
                         crun:         Fast replacement for runc written in C.
                         nvidia:       Runtime for nvidia/nvidia-docker images.
                         kata-runtime: Runtime using a qemu VM.
     --stdin           Forward stdin of x11docker to container command.
     --workdir DIR     Set working directory DIR.

User settings:
     --sudouser        Allow su and sudo for container user. Use with care,
                       severe reduction of default x11docker security!
                         Password:  x11docker
     --user N          Create container user N (N=name or N=uid). Default:
                       same as host user. N can also be an unknown user id.
                       You can specify a group id with N being 'user:gid'.
                       Special case: --user=RETAIN keeps image user settings.
     --hostuser USER   Run X (and container user) as user USER. Default is
                       result of $(logname). (x11docker must run as root).
     --group-add GROUP Add container user to group GROUP.

Init system, elogind and DBus daemon:
     --init [=INITSYSTEM] Run an init system as PID 1 in container. Solves the
                       zombie reaping issue. INITSYSTEM can be:
                         tini: Default. Mostly present as docker-init on host.
                         none: No init system, container command will be PID 1.
                       Others: systemd, sysvinit, runit, openrc, s6-overlay.
     --sharecgroup     Share /sys/fs/cgroup. Allows elogind in container if
                       used with one of --init=openrc|runit|sysvinit
     --dbus [=system]  Run DBus user session daemon for container command.
                       With argument 'system' also run a DBus system daemon. 
                       (Rather use one of --init=systemd|openrc|runit|sysvinit
                        to run the DBus system daemon.)
     --hostdbus        Connect to DBus user session from host.

Container capabilities:
  In most setups x11docker sets --cap-drop=ALL --security-opt=no-new-privileges
  and shows warnings if doing otherwise.
  Custom capabilities can be added with --cap-add=CAP after  --
     --cap-default     Allow default docker container capabilities.
                       Includes --newprivileges=yes. Discouraged.
     --hostipc         Sets docker option --ipc=host. Disables IPC namespacing.
                       Severe reduction of container isolation! Shares
                       host interprocess communication and shared memory.
                       Allows MIT-SHM extension of X servers.
     --hostnet         Set docker run option --network=host. Disables network
                       namespacing. Severe reduction of container isolation!
     --limit [=FACTOR] Limit CPU and RAM usage of container to 
                       currently free RAM x FACTOR and available CPUs x FACTOR.
                       Allowed range is 0 < FACTOR <= 1. 
                       Default for --limit without argument FACTOR: 0.5
     --newprivileges [=yes|no|auto]  Set or unset docker run option 
                       --security-opt=no-new-privileges. Default with no
                       argument is 'yes'. Default for most cases is 'no'.

Miscellaneous:
     --launcher        Create application launcher on desktop and exit. 
                       You can move the created .desktop file to 
                       ~/.local/share/applications to get a menu entry.
     --cachebasedir DIR  Custom base folder for cache files.
     --homebasedir DIR   Custom base folder for option --home.
     --license         Show license of x11docker (MIT) and exit.
     --cleanup         Clean up orphaned containers and cache files.
                       Terminates currently running x11docker containers, too.
     
Output of parseable information on stdout:
  Get output with e.g.:  read id < <(x11docker --showid x11docker/check)
     --showenv         Echo new $DISPLAY, $XAUTHORITY and $WAYLAND_DISPLAY.
                       For custom access to new X server. Get environment with:
                         read xenv < <(x11docker --showenv [...])
     --showid          Echo container ID on stdout.
     --showinfofile    Echo path to internal x11docker info storage file.
     --showpid1        Echo host PID of container PID 1 on stdout.

Verbosity options:
 -v, --verbose         Be verbose. Output of x11docker.log on stderr.
 -V                    Be verbose with colored output. 
 -D, --debug           Debug mode: Show some less verbose debug output
                       and enable rigorous error control.
 -q, --quiet           Suppress x11docker terminal messages.

Installation options (need root permissions):
     --install         Install x11docker and x11docker-gui from current folder.
                       Useful to install from an extracted zip file.
     --update          Download and install latest release from github.
     --update-master   Download and install latest master version from github.
     --remove          Remove x11docker from your system.
                       Preserves ~/.local/share/x11docker from option --home.
                       
Exit codes:
  0:     Success
  64:    x11docker error
  130:   Terminated by ctrl-c
  other: Exit code of command in container

x11docker version: 6.5.0
Please report issues and get help at: https://github.com/mviereck/x11docker