From f4e9afa52fdba59f82915ebf222ead48959d4985 Mon Sep 17 00:00:00 2001 From: mviereck Date: Wed, 14 Aug 2019 15:12:27 +0200 Subject: [PATCH] --help: update --- x11docker | 107 +++++++++++++++++++++++++----------------------------- 1 file changed, 49 insertions(+), 58 deletions(-) diff --git a/x11docker b/x11docker index 2d23a3e8..4fbe3ad2 100755 --- a/x11docker +++ b/x11docker @@ -21,10 +21,11 @@ esac usage() { # --help: show usage information echo " -x11docker: Run GUI applications and desktop environments in docker. +x11docker: Run GUI applications and desktop environments in Docker containers. Usage: -To run a docker image on a new X server: +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 ...]] @@ -33,6 +34,8 @@ To run a host application on a new X server: 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 @@ -40,12 +43,12 @@ Optional features: * Clipboard sharing * Printer access * Webcam access - * Persistent home folders + * Persistent home folder * Wayland support * Language locale creation * Several init systems in container * DBus in container - * Supports a set of different container runtimes + * 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. @@ -58,12 +61,11 @@ 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. + It checks them on startup and shows 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 @@ -75,22 +77,19 @@ Dependencies in image: See also: https://github.com/mviereck/x11docker/wiki/Dependencies -Options: (Note that short options do not accept arguments.) - --help display this message and exit. - -e, --exe execute host application on new X server (no docker). - --xonly only create empty X server. +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 Hardware accelerated OpenGL rendering. Shares files in - /dev/dri. Works best with open source drivers installed - on host and OpenGL/Mesa 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. - Degrades container isolation. Container access to GPU. - -w, --wm [=ARG] Provide a window manager to 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. + -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. @@ -103,23 +102,20 @@ Shared folders: ~/.local/share/x11docker has a softlink to ~/x11docker. Optionally specify another host folder DIR. --homebasedir DIR Custom base folder for option --home. - (Compare --cachebasedir below). + (Compare --cachebasedir below.) --share PATH Share host file or folder PATH. Read-only with PATH:ro Device files in /dev can be shared, too. -Host integration: 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. +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 'locale' package). + 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 @@ -174,7 +170,7 @@ X server options: -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. + Remove restrictions with option --clipboard. -x, --xorg Core Xorg server. Runs ootb from console. Switch tty with ..... @@ -201,7 +197,7 @@ Wayland without X: -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]. + --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. @@ -241,16 +237,16 @@ User settings: 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 +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, image command will be PID 1. - Special: systemd, sysvinit, runit, openrc, s6-overlay. + Others: systemd, sysvinit, runit, openrc, s6-overlay. --sharecgroup Share /sys/fs/cgroup. Allows elogind in container if - used with one of --init=systemd|openrc|runit|sysvinit + used with one of --init=openrc|runit|sysvinit --dbus Run DBus user session daemon for image command. - To also run a DBUS system daemon in container, + To also run a DBus system daemon in container, use one of --init=systemd|openrc|runit|sysvinit --hostdbus Connect to DBus user session from host. @@ -262,13 +258,12 @@ Container capabilities: 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 + --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 + --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 + Default for --limit without argument FACTOR: 0.5 Miscellaneous: --launcher Create application launcher on desktop and exit. @@ -277,11 +272,12 @@ Miscellaneous: --cachebasedir DIR Custom base folder for cache files. --license Show license of x11docker (MIT) and exit. --cleanup Clean up orphaned containers and cache files. + Terminates currently running x11docker containers, too. Verbosity options: -v, --verbose Be verbose. Output of x11docker.log on stderr. -V Be verbose with colored output. - -D, --debug Debug mode: Show some debug output. + -D, --debug Debug mode: Show some less verbose debug output. -q, --quiet Suppress x11docker terminal messages. Installation options (need root permissions): @@ -290,6 +286,7 @@ Installation options (need root permissions): --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. x11docker version: $Version Please report issues and get help at: https://github.com/mviereck/x11docker @@ -697,10 +694,8 @@ $(for Line in $Watchpidlist; do pspid $Line ; done)" saygoodbye "watchpidlist" } setonwatchpidlist() { # add PID $1 to watchpidlist() - #echo ${1:-} >&9 debugnote "Set pid ${1:-} on watchlist: ${2:-}" echo "${1:-}" >>$Watchpidfifo - storepid "${1:-pid}" "${2:-processname}" } watchmessagefifo() { # watch for messages out of container or dockerrc # message in fifo must end with :$Messagetype @@ -5405,7 +5400,7 @@ create_xtermrc() { # create xtermrc: script to prompt for password #### final startup routines waitfor_xserver() { # wait for X server to be ready local Zeit=$(date +%s) Count=0 Dauer=0 - local Compositorpid= Xinitpid= Xserverpid= + local Xinitpid= Xserverpid= Line= # wait for X server to be ready (sign is creation of $Cachefolder/Xready in xinitrc) debugnote "Waiting for X server $Xserver to be ready." @@ -5427,15 +5422,6 @@ $(tail $Compositorlogfile)")" done debugnote "$Xserver is ready" - # check and watch compositor - [ "$Compositorcommand" ] && { - Compositorpid=$(cat $Compositorpidfile) - checkpid $Compositorpid && setonwatchpidlist $Compositorpid compositor || error "Startup of compositor failed. - Last lines of compositor log: -$(tail $Compositorlogfile)" - storepid $Compositorpid compositor - } - # check and watch X server case $Xserver in --tty|--hostdisplay|--hostwayland|--weston|--kwin) ;; @@ -5607,19 +5593,24 @@ start_pulseaudiotcp() { # option --pulseaudio=tcp: load Pulseaudio TCP m return 0 } start_compositor() { # start Wayland compositor Weston or KWin - local Compositorkeyword= Dbuslaunch= + local Compositorkeyword Compositorpid - command -v dbus-launch >/dev/null && Dbuslaunch=dbus-launch case $Xserver in --weston|--weston-xwayland|--xpra-xwayland|--xdummy-xwayland) Compositorkeyword="weston-desktop-shell" ;; --kwin|--kwin-xwayland) Compositorkeyword="X-Server" ;; esac - unpriv "$Dbuslaunch $Compositorcommand >> $Compositorlogfile 2>&1 & echo \$! >>$Compositorpidfile" + + unpriv "$(command -v dbus-launch) $Compositorcommand >> $Compositorlogfile 2>&1 & echo \$! >>$Compositorpidfile" + waitforlogentry compositor $Compositorlogfile "$Compositorkeyword" || error "Startup of Wayland compositor failed. Can not run $Xserver. Last lines of compositor log: $(tail $Compositorlogfile)" + Compositorpid="$(cat $Compositorpidfile)" + storepid $Compositorpid compositor + setonwatchpidlist $Compositorpid compositor + case $Xserver in --xpra-xwayland|--xdummy-xwayland) # hide weston window unpriv "xdotool windowunmap 0x$(printf '%x\n' $(grep 'window id' $Compositorlogfile | rev | cut -d' ' -f1 | rev))" ;; @@ -7681,18 +7672,18 @@ todo() { # --xpra --desktop: redraw issues on resize # --xpra --desktop --xdummy: resize issues # --printer: regard CUPS_SERVER - # Don't need Compositorpidfile? + # CHECK: combination --hostdisplay --hostwayland [--wayland] # FIXME: --interactive does not work with --enforce-i # --env: check escapestring in cmd.sh - # improve speed of dockerrc and containerrootrc # CHECK --xpra-xwayland, --weston-xwayland: Xwayland does not fit Weston window size if parts of weston window are offscreen # --xpra on wayland (experimental): version check, py3 check # dependeny wiki: Cygwin packages # x11docker/check: palinopsia: check video RAM size with glxinfo + # CHECK: kata-runtime: x11docker/lxde needs --init=systemd, why? # BUG --runtime=kata-runtime --nxagent: ALT-GR works wrong. # FIXME: myrealpath(): If realpath is missing, the path argument is returned without resolving. # CHECK: Xwayland with X over IP