x11docker options overview

x11docker: Run GUI applications and desktop environments in docker.

Usage:
To run a docker image on a 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:
  * GPU hardware accelerated graphics
  * Sound with pulseaudio r ALSA
  * Clipboard sharing
  * Printer access
  * Webcam access
  * Persistent home folders
  * Wayland support
  * Language locale creation
  * Several init systems in container
  * DBus in container
  * Supports a set 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 needs some packages to be installed.
  It will check for them on startup and show messages if some are missing.
  Core list of recommended packages:
   * Recommended to allow security and convenience:
       X servers: Xephyr xpra nxagent
       X tools:   xauth xclip xrandr xhost xinit
       On MS Windows also install runx:  https://github.com/mviereck/runx
   * 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 packages, often already installed as package dependencies.
   --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:
     --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 [=ARG]       Provide a window manager for container applications
                       for nested X server options like --xephyr.
                       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            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).
     --share PATH      Share host file or folder PATH. Read-only with PATH:ro
                       Device files in /dev can be shared, too.

Clipboard, sound, printer, language:
 -c, --clipboard       Share clipboard between X servers.
 -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]  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 'locale' package).
                       LOCALE can be e.g. ru, en, de, zh_CN, cz, fr, fr_BE.
     --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 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.
     --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.
     --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.
 -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 by the way with option --clipboard.
 -x, --xorg            Core Xorg server. Runs ootb from console.
                       Switch tty with <CTRL><ALT><F1>....<F12>.

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
 -X, --xwayland        Blanc Xwayland, needs a running Wayland compositor.
     --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).
     --xwin            X server to run in Cygwin/X on MS Windows.

Wayland without X:
 -W, --wayland         Automatically set up a Wayland environment.
                       Chooses one of following options and regards --desktop.
                       Sets some Wayland environment variables.
 -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).
     --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)
     --xfishtank       Show fish tank on new X server.

X and Wayland special configuration:
     --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).

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 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, image command will be PID 1.
                       Special: systemd, sysvinit, runit, openrc, s6-overlay.
                       The special init systems include option --dbus-system.
     --sharecgroup     Share /sys/fs/cgroup. Allows elogind in container if
                       used with --dbus-system or special --init options.
     --dbus            Run DBus user session daemon for image command.
     --dbus-system     Run DBus system daemon in container (includes --dbus).
                       Rather use one of --init=systemd|openrc|sysvinit|runit
     --hostdbus        Connect to DBus user 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

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.
     --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.
                       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.

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