Skip to content

Commit

Permalink
--help: update
Browse files Browse the repository at this point in the history
  • Loading branch information
@mviereck
mviereck committed Aug 14, 2019
1 parent 352d085 commit f4e9afa
Showing 1 changed file with 49 additions and 58 deletions.
107 changes: 49 additions & 58 deletions x11docker
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 ...]]
Expand All @@ -33,19 +34,21 @@ 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
* Sound with pulseaudio or ALSA
* 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.
Expand All @@ -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
Expand All @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -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 <CTRL><ALT><F1>....<F12>.
Expand All @@ -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.
Expand Down Expand Up @@ -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.
Expand All @@ -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.
Expand All @@ -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):
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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."
Expand All @@ -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) ;;
Expand Down Expand Up @@ -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))" ;;
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit f4e9afa

Please sign in to comment.