x11docker options overview

x11docker: Run GUI applications and desktop environments in docker.

Usage:
To run a docker image with new X server:
  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 a new empty X server:
  x11docker [OPTIONS] --xonly

Optional features:
  * Hardware acceleration for OpenGL
  * Pulseaudio and ALSA sound
  * Clipboard sharing
  * Printer access
  * Webcam access
  * Persistent home folders
  * Wayland support
  * Language locale creation
  * Init system in container (systemd, SysVinit, OpenRC, runit, tini)
  * DBus in container
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: --user=root --cap-default

Dependencies on host:
  Depending on chosen options, x11docker needs some packages to be installed.
  It will check for them on startup and show messages if some are missing.
  List of possibly needed packages:
   * most recommended to allow security and convenience:
       X servers: Xephyr xpra nxagent (on Windows: VcXsrv or Xwin)
       X tools:   xauth xrandr xhost xinit
   * advanced GPU support:
       Desktop mode:  weston Xwayland
       Seamless mode: weston Xwayland xpra xdotool
   * less important:
       xclip xdpyinfo xdg-utils pulseaudio
   * least important:
       unzip wget xfishtank kwin_wayland Xvfb
       xserver-xorg-legacy xserver-xorg-video-dummy

Dependencies in image:
  Doesn't have dependencies inside of docker images, except for options:
   --gpu:  OpenGL packages, often already installed as package dependencies.
   --pulseaudio: sound with pulseaudio needs pulseaudio on host and in image.
   --lang: localedef to create missing language locales.
   --dbus, --dbus-system, --hostdbus: needs dbus in image.
   --systemd, --runit,--openrc, --sysvinit: init systems need to be installed.

Options:
     --help            display this message and exit.
 -e, --exe             execute host application on new X server (no docker).
     --xonly           only create empty X server.

Basic settings: (especially influencing auto choosing X server)
 -d, --desktop         Indicate desktop environment in image.
 -g, --gpu             Hardware accelerated OpenGL rendering. Shares files in
                       /dev/dri. Works best with open source drivers installed
                       on host and OpenGL/Mesa in image.
                       For closed source nvidia drivers regard terminal output.
                       Degrades container isolation. Container access to GPU.
 -w, --wm COMMAND      Host window manager to use for single applications in
                       nested X server options like --xephyr.
                       To autodetect a host wm, use --wm=auto or short: -wm
                       To set default autodetected window manager:
                           update-alternatives --config x-window-manager

Shared folders:
 -m, --home            Share a host folder ~/.local/share/x11docker/imagename
                       as home folder in container to store persistent data.
                       ~/.local/share/x11docker has a softlink to ~/x11docker
     --homedir DIR     Specify custom host folder DIR for option --home.
     --homebasedir DIR Custom base folder for option --home.
                       (Compare --cachebasedir below).
     --sharedir DIR    Share host folder (or file) DIR. DIR:ro sets read-only. 

Clipboard, sound, printer, language:
 -c, --clipboard       Share clipboard between X servers (works best with xpra.
                       Most other X servers need xclip to be installed).
 -p, --pulseaudio [=MODE]  Sound with pulseaudio. Degrades isolation.
                       Needs 'pulseaudio' on host and in image.
                       Optional arg MODE can be 'socket' (default) or 'tcp'.
     --alsa [=CARDNAME]   Sound with ALSA. Shares devices in /dev/snd. You can
                       define a desired sound card with CARDNAME.
                       Get a list of available sound cards with: aplay -l
                       Degrades isolation, container access to sound hardware.
     --lang LOCALE     Language setting: search for utf8 LOCALE in image and
                       create it if missing. Needs package 'locale' im image.
                       LOCALE can be e.g. ru, en, de, zh_CN, cz, fr, fr_BE.
                       Same as host: --lang=$LANG.
     --printer         Share host printers through CUPS server.
     --webcam          Share host webcam device files.

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
     --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 '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.
     --sharessh        Share SSH agent authentication socket from host.
     --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.
     --showpid1        Echo host PID of container PID 1 on stdout.
     --stdin           Forward stdin of x11docker to image command.
     --workdir DIR     Set working directory DIR.

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.
                       Needs 'xpra' on host. For faster startup see --nxagent.
 -y, --xephyr          Nested X server for --desktop mode. Without --desktop,
                       a host window manager will be provided (option --wm).
                       (Needs 'Xephyr' or 'Xnest').
 -n, --nxagent         Nested X server supporting seamless and --desktop mode.
                       Faster than --xpra and more flexible than --xephyr, but
                       some compositing applications have issues.
                       (Needs 'nxagent', best since nxagent version 3.5.99).
 -A, --xpra-xwayland   Like --xpra, but supports option --gpu.
                       (Needs 'xpra', 'Xwayland', 'weston' and 'xdotool').
 -Y, --weston-xwayland Desktop mode like --xephyr, but supports option --gpu.
                       Runs from console, within X and within Wayland.
                       (Needs 'weston' and 'Xwayland'.)
 -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 by the way with option --clipboard.
 -x, --xorg            Core Xorg server. Runs ootb from console.
                       Switch tty with <CTRL><ALT><F1>....<F12>.
                       To run from within X, edit '/etc/X11/Xwrapper.conf' and
                       replace line:        allowed_users=console
                       with lines           allowed_users=anybody
                                            needs_root_rights=yes
                       Debian 9 and Ubuntu 16.04: Install xserver-xorg-legacy.

Special X server options:
 -t, --tty             TTY only. Do not provide any X or Wayland server.
     --kwin-xwayland   Like --weston-xwayland, but using kwin_wayland
                       (Needs 'kwin_wayland' and 'Xwayland').
 -X, --xwayland        Blanc Xwayland, needs a running Wayland compositor.
                       (Needs 'Xwayland' to be installed.)
     --xdummy          Invisible X server. (Needs Xorg's dummy video driver)
     --xvfb            Invisible X server. (Needs '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).
     --xwin            X server for Windows to run with Cygwin/X.
     --vcxsrv          X server for Windows to run with MSYS2, Cygwin or WSL.

Wayland without X:
 -W, --wayland         Automatically set up a Wayland environment.
                       Chooses one of following options and regards --desktop.
                       Sets some Wayland environment variables and runs
                       DBus system daemon (--dbus-system) in container.
 -T, --weston          Weston without X for pure Wayland applications.
                       Runs in X or from console. (Needs package weston.)
 -K, --kwin            KWin without X for pure Wayland applications.
                       Runs in X or from console. (Needs kwin_wayland.)
 -H, --hostwayland     Share host Wayland without X for pure Wayland apps.
                       (Needs already running Wayland compositor like Gnome 3.)
                       (Can be combined with --hostdisplay.)

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'
 -f, --fullscreen      Run Xephyr, nxagent or Weston in fullscreen mode.
     --size XxY        Screen size of new X server (e.g. 800x600).
     --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).
     --rotate N        Rotate display (--xorg, --weston and --weston-xwayland)
                       Allowed values: 0, 90, 180, 270, flipped, flipped-90,
                       flipped-180, flipped-270.  (flipped = mirrored)
     --dpi N           dpi value (dots per inch) to submit to clients.
                       Influences font size of some applications.
     --output-count N  Multiple outputs for Weston, KWin or Xephyr.
     --xfishtank       Show fish tank on new X server (needs 'xfishtank').

X and Wayland configuration:
     --xhost STR       Set "xhost STR" on new X server (see 'man xhost').
                       (Use with care. '--xhost +' allows access for everyone).
 -o, --no-xhost        Disable any access to host X server granted by xhost.
     --no-auth         Allow access to X for everyone. Security risk!
     --display N       Use display number N for new X server.
     --vt N            Use vt / tty N (affects --xorg, --xdummy, --xpra).
     --keymap LAYOUT   Set keyboard layout for new X server, e.g. de, us, ru.
                       For possible LAYOUT look at /usr/share/X11/xkb/symbols.
     --westonini FILE  Custom weston.ini for --weston and --weston-xwayland.

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 Additional group GROUP for container user.

Init system and DBus daemon:
     --tini            Default: init system tini (built-in of docker).
     --no-init         No init system in container. Image command is PID 1.
     --runit           Init system runit. Degrades container isolation.
                       Needs 'runit' installed in image. 'dbus' is recommended.
     --openrc          Init system OpenRC. Degrades container isolation a bit,
                       but needs less capabilities than --runit and --systemd.
                       Needs 'openrc' installed in image. 'dbus' recommended.
     --sysvinit        Init system SysVinit. Degrades container isolation a bit,
                       but needs less capabilities than  others.
                       Needs 'sysvinit' installed in image. 'dbus' recommended.
     --systemd         Init system systemd. Degrades container isolation.
                       For faster startup mask services that fail in container.
                       Needs 'systemd' installed in image.
                       Old systemd versions in image need --sys-admin, too.
     --sharecgroup     Share /sys/fs/cgroup. Allows elogind in container if
                       used with --dbus-system or init options.
 -b, --dbus            Run DBus user session daemon for image command.
     --dbus-system     Run DBus system daemon in container (includes --dbus).
                       Default for --wayland and for init options except --tini.
     --hostdbus        Connect to DBus session from host.

Container capabilities:
  Custom capabilities can be added with --cap-add=CAP after  --
     --cap-default     Allow default docker container capabilities and
                       disable container security hardening of x11docker.
     --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 --net=host, disables network
                       namespacing. Severe reduction of container isolation!
                       Shares host network stack.
     --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 without argument FACTOR is 0.5
     --sys-admin       Add capability SYS_ADMIN. Please avoid that.

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.
     --license         Show license of x11docker (MIT) and exit.
     --ps              Preserve container and cache files on exit.
     --cleanup         Clean up orphaned containers and cache files.

Verbosity options:
 -v, --verbose [=c]    Be verbose. Output of logfile on stderr.
                       Optional argument '=c' generates colored output. 
 -D, --debug           Debug mode: Show some debug output,
 -q, --quiet           Suppress x11docker terminal messages.

Installation options (need root permissions):
     --install         Install x11docker and x11docker-gui from current folder.
     --update          Download and install latest release from github.
     --update-master   Download and install latest master version from github.
     --remove          Remove x11docker from your system.

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