All Projects → mviereck → X11docker

mviereck / X11docker

Licence: mit
Run GUI applications and desktops in docker and podman containers. Focus on security.

Programming Languages

shell
77523 projects
TeX
3793 projects

Projects that are alternatives of or similar to X11docker

Wxwidgets
wxWidgets is a free and open source cross-platform C++ framework for writing advanced GUI applications using native controls.
Stars: ✭ 3,994 (+5.19%)
Mutual labels:  gui, desktop, x11
Libagar
Cross-Platform GUI Toolkit (stable)
Stars: ✭ 212 (-94.42%)
Mutual labels:  gui, x11, xorg
X11vnc
a VNC server for real X displays
Stars: ✭ 272 (-92.84%)
Mutual labels:  wayland, x11, vnc
Green Recorder
A simple screen recorder for Linux desktop. Supports Wayland & Xorg
Stars: ✭ 594 (-84.36%)
Mutual labels:  wayland, desktop, xorg
Xsuspender
👀 💻 💤 🔋 Save battery by auto-suspending unfocused X11 applications.
Stars: ✭ 53 (-98.6%)
Mutual labels:  desktop, x11, xorg
Docker X11 Bridge
Simple Xpra X11 bridge to enable GUI with any docker image
Stars: ✭ 143 (-96.23%)
Mutual labels:  ssh, gui, x11
X11vnc Desktop
Docker image for Ubuntu with X11 and VNC
Stars: ✭ 57 (-98.5%)
Mutual labels:  x11, vnc, html5
Wallutils
🌆 Utilities for handling monitors, resolutions, wallpapers and timed wallpapers
Stars: ✭ 145 (-96.18%)
Mutual labels:  wayland, x11, xorg
Chamferwm
A tiling X11 window manager with Vulkan compositor.
Stars: ✭ 200 (-94.73%)
Mutual labels:  x11, xorg
Glmark2
glmark2 is an OpenGL 2.0 and ES 2.0 benchmark
Stars: ✭ 199 (-94.76%)
Mutual labels:  wayland, x11
Browsh
A fully-modern text-based browser, rendering to TTY and browsers
Stars: ✭ 14,058 (+270.24%)
Mutual labels:  ssh, vnc
Indicator Sound Switcher
Sound input/output selector indicator for Linux
Stars: ✭ 243 (-93.6%)
Mutual labels:  sound, pulseaudio
Glimmer
DSL Framework consisting of a DSL Engine and a Data-Binding Library used in Glimmer DSL for SWT (JRuby Desktop Development GUI Framework), Glimmer DSL for Opal (Pure Ruby Web GUI), Glimmer DSL for XML (& HTML), Glimmer DSL for CSS, and Glimmer DSL for Tk (MRI Ruby Desktop Development GUI Library)
Stars: ✭ 186 (-95.1%)
Mutual labels:  gui, desktop
Xf86 Input Wacom
X.Org driver for Wacom devices
Stars: ✭ 201 (-94.71%)
Mutual labels:  x11, xorg
Phantomstyle
Cross-platform QStyle for traditionalists
Stars: ✭ 179 (-95.29%)
Mutual labels:  gui, desktop
Brutedum
BruteDum - Brute Force attacks SSH, FTP, Telnet, PostgreSQL, RDP, VNC with Hydra, Medusa and Ncrack
Stars: ✭ 212 (-94.42%)
Mutual labels:  ssh, vnc
Sara
Originally a fork of catwm, now an offspring of dwm with a streamlined featureset, plus some bspwm.
Stars: ✭ 179 (-95.29%)
Mutual labels:  x11, xorg
Kime
Korean IME
Stars: ✭ 208 (-94.52%)
Mutual labels:  wayland, x11
X11 Packages
Packages using the X Window System.
Stars: ✭ 213 (-94.39%)
Mutual labels:  gui, x11
Lagrange
A Beautiful Gemini Client
Stars: ✭ 238 (-93.73%)
Mutual labels:  gui, desktop

x11docker: x11docker logo Run GUI applications in Docker

Avoid X security leaks and enhance container security

DOI

Introduction

x11docker allows to run graphical desktop applications (and entire desktops) in Linux containers.

Software can be installed in a deployable image with a rudimentary Linux system inside. This can help to run or deploy software that is difficult to install on several systems due to dependency issues. It is possible to run outdated versions or latest development versions side by side. Files to work on can be shared between host and container.

x11docker wiki provides some how-to's for basic setups without x11docker.

Supported systems

x11docker runs on Linux and (with some setup and limitations) on MS Windows. x11docker does not run on macOS except in a Linux VM.

Features

  • Focus on security:
    • Avoids X security leaks by running additional X servers.
    • Restricts container capabilities to bare minimum.
    • Container user is same as host user to avoid root in container.
  • Low dependencies:
    • No obliging dependencies on host beside X and one of docker, podman or nerdctl. Recommended: nxagent and Xephyr.
    • No dependencies inside of images except for some optional features.
  • Several optional features like GPU, sound, webcam and printer support.
  • Remote access with SSH, VNC or HTML5 possible.
  • Easy to use. Examples:
    • x11docker x11docker/fvwm xterm
    • x11docker --desktop --size 320x240 x11docker/lxde (needs nested X server Xephyr)

retro terminal cathode LXDE in xpra

Table of contents

GUI for x11docker

x11docker-gui is an optional graphical frontend for x11docker. It runs from console, too.

  • x11docker-gui needs package kaptain. If your distribution misses it, look at kaptain repository.
  • If kaptain is not installed on your system, x11docker-gui uses image x11docker/kaptain.

x11docker-gui screenshot

Terminal usage

Just type x11docker IMAGENAME [COMMAND].

  • Get an overview of options with x11docker --help.
    • For desktop environments in image add option -d, --desktop.
    • To run without X at all use option -t, --tty.
    • Get an interactive TTY with option -i, --interactive.
    • See generated container backend command (and further infos) with option --debug.
  • If startup fails, look at chapter Troubleshooting.

General syntax:

To run a container on a new X server:
  x11docker IMAGE
  x11docker [OPTIONS] IMAGE [COMMAND]
  x11docker [OPTIONS] -- IMAGE [COMMAND [ARG1 ARG2 ...]]
  x11docker [OPTIONS] -- 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

RUN_OPTIONS are just added to the docker|podman|nerdctl run command without a serious check by x11docker.

Options

Description of some commonly used feature options.

Choice of X servers and Wayland compositors

If no X server option is specified, x11docker automatically chooses one depending on installed dependencies and on given or missing options --desktop, --gpu and --wayland. Most recommended are nxagent and Xephyr.

Desktop or seamless mode

x11docker assumes that you want to run a single application in seamless mode, i.e. a single window on your regular desktop. If you want to run a desktop environment in image, add option --desktop.

  • Seamless mode is supported with options --nxagent and --xpra. As a fallback insecure option --hostdisplay is possible.
  • Desktop mode with --desktop is supported with all X server options except --hostdisplay. If available, x11docker prefers --xephyr and --nxagent.
  • Special case: Single applications with a window manager (option --wm).
    • If neither nxagent nor xpra are installed, but x11docker finds a desktop capable X server like Xephyr, it avoids insecure option --hostdisplay and runs Xephyr with a window manager.

Shared folders, volumes and HOME in container

Changes in a running container system will be lost, the created container will be discarded. For persistent data storage you can share host directories or volumes:

  • Option -m, --home creates a host directory in ~/.local/share/x11docker/IMAGENAME that is shared with the container and mounted as its HOME directory. Files in container home and user configuration changes will persist. x11docker creates a softlink from ~/.local/share/x11docker to ~/x11docker.
    • You can specify another host directory for container HOME with --home=DIR.
    • You can specify a volume for container HOME with --home=VOLUME.
  • Option --share PATH mounts a host file or folder at the same location in container.
    • You can also specify a volume with --share VOLUME.
    • --share PATH:ro restricts to read-only access.
    • Device files in /dev are supported, too.
  • Special cases for $HOME:
    • --home=$HOME will use your host home as container home. Discouraged, use with care.
    • --share $HOME will symlink your host home as a subfolder of container home.

Note that x11docker copies files from /etc/skel in container to HOME if HOME is empty. That allows to provide predefined user configurations in the image.

GPU hardware acceleration

Hardware acceleration for OpenGL is possible with option -g, --gpu.

Clipboard

Clipboard sharing is possible with option -c, --clipboard.

  • Image clips are possible with --xpra and --hostdisplay.
  • Some X server options need package xclip on host.

Sound

Sound is possible with options -p, --pulseaudio and --alsa.

  • For pulseaudio sound with --pulseaudio you need pulseaudio on host and pulseaudio (at least the pulseaudio client libraries) in image. Compare wiki: feature dependencies.
  • For ALSA sound with --alsa you might need to specify a sound card with e.g. --alsa=Generic. Get a list of available sound cards with aplay -l.

Webcam

Webcams on host can be shared with option --webcam.

  • If webcam application in image fails, install --gpu dependencies in image. Compare wiki: feature dependencies.
  • guvcview needs --pulseaudio or --alsa.
  • cheese and gnome-ring need --init=systemd.

Printer

Printers on host can be provided to container with option --printer.

  • It needs cups on host, the default printer server for most linux distributions.
  • The container needs cups client libraries in image. Compare wiki: feature dependencies.

Language locales

x11docker provides option --lang for flexible language locale settings.

  • --lang without an argument sets LANG in container to same as on host. Same as --lang=$LANG
  • x11docker will check on container startup if the desired locale is already present in image and enable it.
  • If x11docker does not find the locale, it creates it on container startup. This needs some locale packages in image. Compare wiki: feature dependencies.
  • Examples: --lang=de for German, --lang=zh_CN for Chinese, --lang=ru for Russian, --lang=$LANG for your host locale.
  • For support of chinese, japanese and korean characters install a font like fonts-arphic-uming in image.
  • Keyboard input methods like fcitx-pinyin are possible with some container setup. Compare ticket #269.

Wayland

To run Wayland instead of an X server x11docker provides options --wayland, --weston, --kwin and --hostwayland. For further description loot at wiki: Description of Wayland options.

  • Option --wayland automatically sets up a Wayland environment. It regards option --desktop.
  • Options --weston and --kwin run Wayland compositors weston or kwin_wayland.
  • Option --hostwayland can run applications seamless on host Wayland desktops like Gnome 3, KDE 5 and Sway.
  • Example: xfce4-terminal on Wayland: x11docker --wayland x11docker/xfce xfce4-terminal

Init system

x11docker supports several init systems as PID 1 in container with option --init. Init in container solves the zombie reaping issue. As default x11docker uses tini in/usr/bin/docker-init. Also available are systemd, SysVinit, runit, OpenRC and s6-overlay. elogind is supported, too. Look at wiki: Init systems in Docker.

DBus

Some desktop environments and applications need a running DBus system daemon and/or DBus user session. DBus options need dbus in image.

  • use --dbus to run a DBus user session daemon.
  • A DBus system daemon will be started automatically with init systems systemd, openrc, runit and sysvinit (option --init).
    • It is also possible to run a DBus system daemon with --dbus=system without advanced init systems. However, this causes trouble in some cases and is not recommended in general.
  • use --hostdbus to connect to host DBus user session.
  • use --share /run/dbus/system_bus_socket to share host DBus system socket.

Container runtime

It is possible to run containers with different backends following the OCI runtime specification. Docker's default runtime is runc. You can specify another one with option --runtime=RUNTIME. Container runtimes known and supported by x11docker are:

  • runc: Docker default.
  • kata-runtime: Sets up a virtual machine with its own Linux kernel to run the container. kata aims to combine the security advantages of containers and virtual machines.
    • Some x11docker options are not possible with --runtime=kata-runtime. Most important: --hostdisplay, --gpu, --printer, --webcam and all Wayland related options.
  • nvidia: Specialized fork of runc to support nvidia/nvidia-docker images.
  • crun: Fast and lightweight alternative to runc with same functionality.
  • oci: Runtime reported in #205, no documentation found. Handled by x11docker like runc.

Using different runtimes is well tested for rootful Docker, but not for other backend setups.

Possible runtime configuration in /etc/docker/daemon.json:

{
  "default-runtime": "runc",
  "runtimes": {
    "kata-runtime": {
      "path": "/opt/kata/bin/kata-runtime",
      "runtimeArgs": [
        "--kata-config /opt/kata/share/defaults/kata-containers/configuration.toml"
      ]
    },
    "crun": {
      "path": "/usr/local/bin/crun",
      "runtimeArgs": []
    },
    "nvidia": {
      "path": "nvidia-container-runtime",
      "runtimeArgs": []
    }
  }
}

Backend docker, podman or nerdctl

x11docker supports container tools Docker, podman and nerdctl with option --backend=BACKEND in rootful and rootless mode.

  • By default x11docker tries to run docker. Alternatively set option --backend=podman or --backend=nerdctl.
  • Test status:
    • x11docker was developed with rootful docker, this is well tested.
    • Basically tested is podman, rootless and rootful.
    • Barely tested:
      • rootless docker
      • nerdctl in rootless and rootful mode.
    • Some fixes and adjustments for the less tested setups can be expected.
  • For rootless mode podman is recommended.
    • Only podman allows option --home in rootless mode yet.
    • Only podman provides useful file ownerships with option --share in rootless mode yet.
  • For rootful mode docker or podman are recommended.
  • To switch between rootless or rootful mode of podman and nerdctl just use (or leave) sudo or set (or leave) option --pw.
  • For rootless docker set environment variable DOCKER_HOST accordingly.

Security

Scope of x11docker is to run containerized GUI applications while preserving and improving container isolation. Core concept is:

  • Runs a second X server to avoid X security leaks.
    • This in opposite to widespread solutions that share host X socket of display :0, thus breaking container isolation, allowing keylogging and remote host control. (However, x11docker provides this with fallback option --hostdisplay).
    • Authentication is done with MIT-MAGIC-COOKIE, stored separate from file ~/.Xauthority.
  • Creates container user similar to host user to avoid root in container.
    • You can also specify another user with --user=USERNAME or a non-existing one with --user=UID:GID.
    • Disables possible root password and deletes entries in /etc/sudoers.
      • If you want root permissions in container, use option --sudouser that allows su and sudo with password x11docker. Alternatively you can run with --user=root.
    • If you want to use USER specified in image instead, set option --user=RETAIN. x11docker won't change container's /etc/passwd or /etc/sudoers in that case. Option --home won't be available.
  • Reduces container capabilities to bare minimum.
    • Sets run option --cap-drop=ALL to drop all capabilities. Most applications don't need them.
    • Sets run option --security-opt=no-new-privileges.
    • These restrictions can be disabled with x11docker option --cap-default or reduced with --sudouser, --user=root, --newprivileges.

That being said, the default docker capabilities and the seccomp/SELinux/apparmor profiles are set up well to protect the host system. Nonetheless, x11docker follows the principle of least privilege. Containers should not have capabilities or privileges that they don't need for their job.

Default runtimes like runc use Linux namespaces to isolate container applications, but share the kernel from host. If you are concerned about container access to host kernel, consider to use container runtime kata-runtime instead.

Weaknesses:

  • Possible SELinux restrictions are degraded for x11docker containers with run option --security-opt label=type:container_runtime_t to allow access to new X unix socket. A more restrictive solution is desirable. Compare: SELinux and Docker: allow access to X unix socket in /tmp/.X11-unix
  • A possible user namespace remapping setup is disabled to allow options --home and --share without file ownership issues.
    • This is less an issue because x11docker already avoids root in container.
    • Exception: User namespace remapping is not disabled for --user=RETAIN.
  • x11docker provides several different X server options. Each X server involved might have its individual vulnerabilities. x11docker only covers well-known X security leaks that result from X11 protocol design.

Options degrading container isolation

x11docker shows warning messages in terminal if chosen options degrade container isolation. Note that x11docker does not check custom DOCKER_RUN_OPTIONS.

Most important:

  • --hostdisplay shares host X socket of display :0 instead of running a second X server.
    • Danger of abuse is reduced providing so-called untrusted cookies, but do not rely on this.
    • If additionally using --gpu or --clipboard, option --hostipc and trusted cookies are enabled and no protection against X security leaks is left.
    • If you don't care about container isolation, x11docker --hostdisplay --gpu is an insecure but quite fast setup without any overhead.
  • --gpu allows access to GPU hardware. This can be abused to get window content from host (palinopsia bug) and makes GPU rootkits like keyloggers possible.
  • --pulseaudio and --alsa allow catching audio output and microphone input from host.

Rather special options reducing security, but not needed for regular use:

  • --sudouser and --user=root allow su and sudo with password x11dockerfor container user. If an application somehow breaks out of container, it can harm your host system. Allows many container capabilities that x11docker would drop otherwise.
  • --cap-default disables x11docker's container security hardening and falls back to default container capabilities as provided by the backends docker, podman or nerdctl. If an application somehow breaks out of container, it can harm your host system.
  • --init=systemd|sysvinit|openrc|runit allow some container capabilities that x11docker would drop otherwise. --init=systemd also shares access to /sys/fs/cgroup. Some processes will run as root in container. If a root process somehow breaks out of container, it can harm your host system. Allows many container capabilities that x11docker would drop otherwise.
  • --hostipc sets run option --ipc=host. Allows MIT-SHM / shared memory. Disables IPC namespacing.
  • --hostdbus allows communication over DBus with host applications.

Sandbox

Container isolation enhanced with x11docker allows to use containers as a sandbox that fairly well protects the host system from possibly malicious or buggy software. Though, no sandbox solution in the wild can provide a perfect secure protection, and Docker even with enhanced security settings from x11docker is no exception.

Using x11docker as a sandbox is not intended to run obviously evil software. Rather use it as:

  • Compatibility environment to run software that is hard or impossible to install on host due to dependency issues.
  • Development environment to collect libraries, compiler and so on to keep the host clean.
  • Development environment to mitigate damage caused by unexpected/buggy behaviour.
  • Security layer for software that may be malicious in worst case. Examples: Internet browser with enabled javascript, or wine with MS Windows applications.

x11docker already restricts process capabilities. You can additionally restrict access to CPU and RAM with option --limit. As default --limit restricts to 50% of available CPUs and 50% of currently free RAM. Another amount can be specified with --limit=FACTOR with a FACTOR greater than zero and less than or equal one.

For more custom fine tuning have a look at Docker documentation: Limit a container's resources.

NOTE: Internet access is allowed by default. You can disable internet access with --network=none.

WARNING: There is no restriction that can prevent the container from flooding the hard disk storing the container or in shared folders.

Security and feature check

To check container isolation and some feature options use image x11docker/check and try out with several options.

  • An insecure setup is x11docker --hostdisplay --gpu x11docker/check. It fairly well demonstrates common X security leaks.
  • Add options like --pulseaudio --alsa --webcam --clipboard --printer to check their functionality.

Installation

Note that x11docker is just a bash script without library dependencies. Basically it is just a wrapper for X servers and container backends docker, podman and nerdctl. To allow advanced usage of x11docker abilities have a look at chapter Dependencies.

Installation options

As root you can install, update and remove x11docker in system directories to be available system-wide:

  • x11docker --install : install x11docker and x11docker-gui from current directory. (Useful to install from an extracted zip file or a cloned git repository.)
  • x11docker --update : download and install latest release from github.
  • x11docker --update-master : download and install latest master version from github.
  • x11docker --remove : remove all files installed by x11docker.
    • Note: This does not remove ~/.local/share/x11docker where it stores persistent files of option --home.

What the installation does (just for information):

  • Copies scripts x11docker and x11docker-gui to /usr/bin.
  • Copies icon x11docker.png to /usr/share/icons.
  • Creates menu entry x11docker.desktop in /usr/share/applications.
  • Copies documentation README.md, CHANGELOG.md and LICENSE.txt to /usr/share/doc/x11docker.

Shortest way for first installation:

  • For systems using sudo:
    curl -fsSL https://raw.githubusercontent.com/mviereck/x11docker/master/x11docker | sudo bash -s -- --update
  • Directly as root:
    curl -fsSL https://raw.githubusercontent.com/mviereck/x11docker/master/x11docker | bash -s -- --update

Minimal installation

You can run x11docker from an arbitrary location with bash x11docker. For minimal system-wide installation make x11docker executable with chmod +x x11docker and move it to /usr/bin (or another location in PATH). Other files than script x11docker itself are not essential.

Installation on MS Windows

x11docker can run natively on MS Windows electively in one of:

Further information at wiki: x11docker on MS Windows.

Deinstallation

You can remove x11docker with x11docker --remove. That will remove the files listed above. It will also remove ~/.cache/x11docker and stop all running x11docker containers. x11docker will not remove:

  • Files and folders for persistent data storage with option --home. These are:
    • ~/.local/share/x11docker where persistent data is stored.
    • Softlink ~/x11docker that points there.
  • Folders you might have created yourself for x11docker:
    • ~/.local/share/x11docker
    • ~/.config/x11docker

Dependencies

x11docker can run with standard system utilities without additional dependencies on host or in image.

  • As a core it only needs bash, an X server and one of docker, podman or nerdctl to run containers on X.
  • x11docker checks dependencies for chosen options on startup and shows terminal messages if some are missing.

For advanced usage of x11docker it is recommended to install some additional packages. The recommended base commands are: nxagent Xephyr weston Xwayland xdotool xauth xinit xclip xhost xrandr xdpyinfo. Some of them are probably already installed.

Some feature options have additional dependencies on host and/or in image. This affects especially options --gpu, --printer and --pulseaudio. Compare wiki: feature dependencies.

Troubleshooting

For troubleshooting run x11docker or x11docker-gui in a terminal. x11docker shows warnings if something is insecure, missing or going wrong. Also it shows notes if options don't work and fallbacks are used. It might give hints to fix some issues.

Core checks

1. Make sure your x11docker version is up to date with x11docker --update (latest release) or x11docker --update-master (latest beta).

2. Carefully read the regular x11docker messages. Often they already give a hint what to do.

  • Use option -D, --debug to see some internal messages.
  • Use option -v, --verbose to see full logfile output.
  • You can find the latest dispatched logfile at ~/.cache/x11docker/x11docker.log.

3. Try another X server option.

  • Some applications fail with fallback option --hostdisplay. Add --clipboard to disable some security restrictions of --hostdisplay.
  • If that does not help, install additional X servers. The most stable and reliable option is --xephyr.

Privilege checks

Some applications need more privileges or capabilities than x11docker provides by default. One attempt is to allow several privileges until the setup works. Than reduce privileges to find out which are needed indeed. (Note the -- in the following commands, do not miss them).

1. Adding privileges:

  • Try x11docker --cap-default IMAGENAME
  • Try x11docker --cap-default --hostipc --hostnet IMAGENAME
  • Try x11docker --cap-default --hostipc --hostnet --share /run/udev/data:ro -- --cap-add ALL --security-opt seccomp=unconfined --privileged -- IMAGENAME

2. Reducing privileges:

  • Drop options one by one in this order: --privileged --security-opt seccomp=unconfined --cap-add ALL --share /run/udev/data:ro --hostnet --hostipc --cap-default. Only leave options that are needed to keep the setup working.
  • Option --cap-default might already be enough. It allows default container capabilities as docker|podman|nerdctl would do on themself.
    • You can just stop debugging and reducing here if you like to.
    • You can try to reduce --cap-default. Partially remove additional options to find out which one(s) are needed:
      • First try x11docker --newprivileges -- IMAGENAME
      • Than try and reduce: x11docker --newprivileges -- --cap-add=SETPCAP --cap-add=MKNOD --cap-add=AUDIT_WRITE --cap-add=CHOWN --cap-add=NET_RAW --cap-add=DAC_OVERRIDE --cap-add=FOWNER --cap-add=FSETID --cap-add=KILL --cap-add=SETGID --cap-add=SETUID --cap-add=NET_BIND_SERVICE --cap-add=SYS_CHROOT --cap-add=SETFCAP -- IMAGENAME
  • --cap-add ALL should not be considered to be a solution.
    • Drop capabilities from following command to find the one(s) you need: x11docker --cap-default -- --cap-add=SYS_MODULE --cap-add=SYS_RAWIO --cap-add=SYS_PACCT --cap-add=SYS_ADMIN --cap-add=SYS_NICE --cap-add=SYS_RESOURCE --cap-add=SYS_TIME --cap-add=SYS_TTY_CONFIG --cap-add=AUDIT_CONTROL --cap-add=MAC_OVERRIDE --cap-add=MAC_ADMIN --cap-add=NET_ADMIN --cap-add=SYSLOG --cap-add=DAC_READ_SEARCH --cap-add=LINUX_IMMUTABLE --cap-add=NET_BROADCAST --cap-add=IPC_LOCK --cap-add=IPC_OWNER --cap-add=SYS_PTRACE --cap-add=SYS_BOOT --cap-add=LEASE --cap-add=WAKE_ALARM --cap-add=BLOCK_SUSPEND --cap-add=AUDIT_READ -- IMAGENAME
    • Many of these capabilities are rather dangerous and should not be allowed for a container. Especially to mention is SYS_ADMIN.
  • Option --privileged should not be considered to be a solution. Basically it allows arbitrary access to the host for container applications.
    • Likely you need to share a device file in /dev, e.g. something like --share /dev/vboxdrv.
  • --hostipc and --hostnet severely reduce container isolation. Better solutions are desirable.

3. Open a ticket to ask for possibilities how to optimize the privilege setup.

Other checks

1. Container user: By default x11docker sets up an unprivileged container user similar to your host user.

  • The image may have a USER specification and be designed for this user.
    • Check for a USER specification in image with docker inspect --format '{{.Config.User}}' IMAGENAME
    • You can enable this predefined user with --user=RETAIN
  • The container might need a root user. Try with --user=root. Note that this disables some x11docker restrictions for containers similar to --cap-default.

2. Init and DBus

  • A few applications need a DBus user daemon. Install dbus in image and try option --dbus.
  • A few applications need systemd and/or a running DBus system daemon. Install systemd in image and try option --init=systemd.

3. Architecture check of host OS and image

  • The image may not be built for the architecture of your host OS. (ie. Image is built for amd64 but your OS runs on arm, e.g. on a RaspBerry PI). With a mismatch the container will quit unexpectedly & x11docker may emit the error dockerrc(): Did not receive PID of PID1 in container.
    • You can check the image architecture with docker inspect --format {{.Architecture}} IMAGENAME.
    • You can check the host architecture with uname -m.
    • For further information and multi-arch setups look at wiki: Multi-arch setups with QEMU.

Contact

Feel free to open a ticket if you have a question or encounter an issue.

Issues

If reporting an issue:

  • Have a look at chapter Troubleshooting.
  • Most times it makes sense to store the --verbose output (or ~/.cache/x11docker/x11docker.log) at pastebin.com.

Contributing

If you want to contribute to x11docker, please open a ticket before creating a pull request. Often it is possible to accomplish desired tasks with already available options. Note that x11docker is considered to be stable and changes other than bug fixes are less likely to be merged. In general new features are not intended.

Support

Please open a ticket if you need support. Please note that x11docker is a non-commercial project maintained in free time. I'll help where I can, but there is no organisation behind x11docker that can provide large scale support.

Donation

If you like to make a donation: Thank you! :)

I don't take the money myself, but please spend some to Galsan Tschinag in Mongolia (Wikipedia). One of his great projects is the afforestation of Mongolia. A donation account in Germany is provided by Förderverein Mongolei e.V..

Förderverein Mongolei e.V.
IBAN DE7261290120 0394 3660 00
BIC GENODES1NUE
Volksbank Kirchheim-Nürtingen

I personally know some of the people behind this. I assure that they are trustworthy and have a great heart and soul and do a good thing.

Examples

Some x11docker image examples with desktop environments can be found on docker hub. A special one to check features and container isolation is x11docker/check.

Docker does not provide automated builds for free anymore, so the images are becoming outdated. Instead of pulling them, rather build them locally with x11docker option --build.

Some x11docker Dockerfiles are provided at https://github.com/mviereck?tab=repositories; look for repositories beginning with dockerfile-x11docker. You can build locally from these Dockerfiles with x11docker option --build. Example:

x11docker --build x11docker/fvwm

Single applications

Application x11docker command
Xfce4 Terminal x11docker x11docker/xfce xfce4-terminal
GLXgears with hardware acceleration x11docker --gpu x11docker/xfce glxgears
Kodi media center with hardware
acceleration, Pulseaudio sound
and shared Videos folder.
For setup look at ehough/docker-kodi.
x11docker --gpu --pulseaudio --share ~/Videos erichough/kodi.
XaoS fractal generator x11docker patricknw/xaos
Telegram messenger with persistent
HOME for configuration storage
x11docker --home xorilog/telegram
Firefox with shared Download folder. x11docker --share $HOME/Downloads -- --tmpfs /dev/shm -- jess/firefox
Tor browser x11docker jess/tor-browser
Chromium browser with restricted resource usage x11docker --limit -- jess/chromium --no-sandbox
VLC media player with shared Videos
folder and Pulseaudio sound
x11docker --pulseaudio --share=$HOME/Videos jess/vlc
GNU Octave Scientific Programming Language built for arm & arm64 x11docker aptman/dbhi:bionic-octave octave

Desktop environments

Desktop environment
(most based on Debian)
x11docker command
Cinnamon x11docker --desktop --gpu --init=systemd x11docker/cinnamon
deepin (website) (3D desktop from China) x11docker --desktop --gpu --init=systemd -- --cap-add=IPC_LOCK --security-opt seccomp=unconfined -- x11docker/deepin
Enlightenment (based on Void Linux) x11docker --desktop --gpu --runit x11docker/enlightenment
Fluxbox (based on Debian, 87 MB) x11docker --desktop x11docker/fluxbox
FVWM (based on Alpine, 22.5 MB) x11docker --desktop x11docker/fvwm
Gnome 3 x11docker --desktop --gpu --init=systemd x11docker/gnome
KDE Plasma x11docker --desktop --gpu --init=systemd x11docker/kde-plasma
KDE Plasma as nested Wayland compositor x11docker --gpu --init=systemd -- --cap-add SYS_RESOURCE -- x11docker/kde-plasma startplasmacompositor
Lumina (website) (based on Void Linux) x11docker --desktop x11docker/lumina
LiriOS (needs at least docker 18.06
or this xcb bugfix.) (based on Fedora)
x11docker --desktop --gpu lirios/unstable
LXDE x11docker --desktop x11docker/lxde
LXDE with wine and PlayOnLinux and
a persistent HOME folder to preserve
installed Windows applications,
and with Pulseaudio sound.
x11docker --desktop --home --pulseaudio x11docker/lxde-wine
LXQt x11docker --desktop x11docker/lxqt
Mate x11docker --desktop x11docker/mate
Trinity (website) (successor of KDE 3) x11docker --desktop x11docker/trinity
Xfce x11docker --desktop x11docker/xfce

Option --preset

For very long option combinations you might want to use option --preset FILENAME to have a command shortcut. FILENAME is a file in ~/.config/x11docker/preset containing some x11docker options.

  • Example multimedia: Create a file ~/.config/x11docker/preset/multimedia:
    --gpu
    --webcam
    --printer
    --pulseaudio
    --clipboard
    --share ~/Videos
    --share ~/Music
    
    Use it like: x11docker --preset=multimedia jess/vlc
  • Example deepin desktop: Instead of very long command
    x11docker --desktop --init=systemd -- --cap-add=IPC_LOCK --security-opt seccomp=unconfined -- x11docker/deepin
    
    you can create a file ~/.config/x11docker/preset/deepin containing the desired options:
    --desktop 
    --init=systemd
    -- 
    --cap-add=IPC_LOCK
    --security-opt seccomp=unconfined
    -- 
    x11docker/deepin
    
    Run with: x11docker --preset=deepin

Adjust images for your needs

For persistent changes of image system adjust Dockerfile and rebuild. To add custom applications to x11docker example images you can create a new Dockerfile based on them. Example:

# xfce desktop with VLC media player
FROM x11docker/xfce
RUN apt-get update && apt-get install -y vlc

Screenshots

More screenshots are stored in screenshot branch

x11docker --desktop x11docker/lxde-wine screenshot

x11docker --desktop x11docker/lxqt screenshot

x11docker --desktop --gpu --init=systemd -- --cap-add=IPC_LOCK --security-opt seccomp=unconfined -- x11docker/deepin screenshot

Note that the project description data, including the texts, logos, images, and/or trademarks, for each open source project belongs to its rightful owner. If you wish to add or remove any projects, please contact us at [email protected].