Skip to content

How to

Jump to bottom
accetto edited this page Oct 17, 2019 · 17 revisions

Updated: 2018-10-29

Table of content

How to create containers?

Created containers will run under the privileged root user by default.

The following container will listen on the host's TCP ports 25901 (VNC) and 26901 (noVNC):

docker run -d -p 25901:5901 -p 26901:6901 accetto/ubuntu-vnc-xfce

The following container wil create or re-use the local named volume my_Downloads mounted as /home/headless/Downloads. The container will be accessible through the same TCP ports as the one above:

docker run -d -p 25901:5901 -p 26901:6901 -v my_Downloads:/home/headless/Downloads accetto/ubuntu-vnc-xfce

or using the newer syntax with --mount flag:

docker run -d -p 25901:5901 -p 26901:6901 --mount source=my_Downloads,target=/home/headless/Downloads accetto/ubuntu-vnc-xfce

TOC

How to use headless containers?

There are two ways, how to use the created headless containers. Note that the default VNC user password is headless.

Over VNC

To be able to use the containers over VNC, a VNC Viewer is needed (e.g. TigerVNC or TightVNC).

The VNC Viewer should connect to the host running the container, pointing to the host's TCP port mapped to the container's TCP port 5901.

For example, if the container has been created on the host called mynas using the parameters described above, the VNC Viewer should connect to mynas:25901.

Over noVNC

To be able to use the containers over noVNC, an HTML5 capable web browser is needed. It actually means, that any current web browser can be used.

The browser should navigate to the host running the container, pointing to the host's TCP port mapped to the container's TCP port 6901.

However, since the version 1.2.0 the containers offer two noVNC clients. Additionally to the previously available lite client there is also the full client with more features. The connection URL differs slightly in both cases. To make it easier, a simple startup page is implemented.

If the container have been created on the host called mynas using the parameters described above, then the web browser should navigate to http://mynas:26901.

The startup page will show two hyperlinks pointing to the both noVNC clients:

  • http://mynas:26901/vnc_lite.html
  • http://mynas:26901/vnc.html

It's also possible to provide the password through the links:

  • http://mynas:26901/vnc_lite.html?password=headless
  • http://mynas:26901/vnc.html?password=headless

TOC

How to override VNC password?

The default VNC password is headless. To change it for a new container, simply provide its value through the environment variable VNC_PW:

docker run -d -P -e VNC_PW=newpassword accetto/ubuntu-vnc-xfce

It's also possible to change the default VNC password for a new image using the build argument VNC_PW.

TOC

How to override VNC resolution?

The default VNC resolution is set to 1024x768 pixels. To change it for a new container, simply provide the new value through the environment variable VNC_RESOLUTION:

docker run -d -P -e VNC_RESOLUTION=1360x768 accetto/ubuntu-vnc-xfce

TOC

How to override VNC user?

To run a new container under a non-root user 2017:2000, use the user parameter of the docker run command:

docker run -d -P --user 2017:2000 accetto/ubuntu-vnc-xfce

There will be some user limitations inside the container because the actual user account is not created this way. Depending on the use case, it could be seen as an advantage or a disadvantage.

Note that in this case the user must be specified numerically (as uid or uid:gid).

The root user on the other hand can be specified numerically or by its name (as 0, 0:0, root or root:root) and it will not be limited in any way:

docker run -d -P --user root accetto/ubuntu-vnc-xfce

Again, depending on the use case, running a container under the privileged root user could be seen as an advantage or a disadvantage. In any case, potential security risks should be carefully assessed.

TOC

How to override VNC blacklist parameters?

The VNC parameters BlacklistTimeout and BlacklistThreshold are configurable through the build arguments ARG_BLACKLIST_TIMEOUT/ARG_BLACKLIST_THRESHOLD and environment variables BLACKLIST_TIMEOUT/BLACKLIST_THRESHOLD. Their original default values have been:

BlacklistTimeout = 10
BlacklistThreshold = 5

However, since the version 1.1.3 they are set to the following values:

BlacklistTimeout = 0
BlacklistThreshold = 20

It effectively disables the built-in VNC blacklisting, mitigating the VNC connection problem "Too many security failures".

The original default values can be restored using the following command:

docker run -d -P -e BLACKLIST_TIMEOUT=10 -e BLACKLIST_THRESHOLD=5 accetto/ubuntu-vnc-xfce

TOC

How to run containers in foreground?

The image supports the following container start-up options: --wait (default), --skip, --debug (also --tail-log) and --help. Their description is provided by the image itself.

The following container will print out the help and then it'll remove itself:

docker run --rm accetto/ubuntu-vnc-xfce --help

Excerpt from the output, which describes the other options:

OPTIONS:
-w, --wait      (default) Keeps the UI and the vnc server up until SIGINT or SIGTERM are received.
                An optional command can be executed after the vnc starts up.
                example: docker run -d -P accetto/ubuntu-vnc-xfce
                example: docker run -it -P accetto/ubuntu-vnc-xfce /bin/bash

-s, --skip      Skips the vnc startup and just executes the provided command.
                example: docker run -it -P accetto/ubuntu-vnc-xfce --skip /bin/bash

-d, --debug     Executes the vnc startup and tails the vnc/noVNC logs.
                Any parameters after '--debug' are ignored. CTRL-C stops the container.
                example: docker run -it -P accetto/ubuntu-vnc-xfce --debug

-t, --tail-log  same as '--debug'

-h, --help      Prints out this help.
                example: docker run --rm accetto/ubuntu-vnc-xfce

It should be noticed, that the --debug start-up option does not show the command prompt even if the -it run arguments are provided. This is because the container is watching the incoming vnc/noVNC connections and prints out their logs in real time. However, it is easy to attach to the running container like in the following example.

In the first terminal window on the host computer, create a new container named foo:

docker run --name foo accetto/ubuntu-vnc-xfce --debug

In the second terminal window on the host computer, execute the shell inside the foo container:

docker exec -it foo /bin/bash

TOC

Clone this wiki locally