It is not easy to find guides for FreeBSD. In this guide, I explain with a near step by step how to:
- install a KDE5 or GENOME 3 GUI in a jail
- remote control the jail using either VNC or the X11 forwarding
- install VNC as a service started on jail boot
- properly setup a secure SSH connection, SSH tunnel and X11 forwarding through SSH
- install a few graphical applications like mkvtoolnix-gui, qbittorrent, sakura, dolphin
My fist need was to remux a few videos directly on TrueNAS instead of doing it from a Windows machine through SMB, loosing both bandwidth and ZFS/ECC checksum during file operations.
There is no images, feel free to ask questions
I also did not go in the basics like adding users or explaining vncserver command options. There are a lot of guides for that.
- install a KDE5 or GENOME 3 GUI in a jail
- remote control the jail using either VNC or the X11 forwarding
- install VNC as a service started on jail boot
- properly setup a secure SSH connection, SSH tunnel and X11 forwarding through SSH
- install a few graphical applications like mkvtoolnix-gui, qbittorrent, sakura, dolphin
My fist need was to remux a few videos directly on TrueNAS instead of doing it from a Windows machine through SMB, loosing both bandwidth and ZFS/ECC checksum during file operations.
There is no images, feel free to ask questions
I also did not go in the basics like adding users or explaining vncserver command options. There are a lot of guides for that.
Code:
##########################################################
# Setup a jail with VNC and GUI <xgui>
##########################################################
# I assume a working jail with network access is setup, we name it "xgui"
# Create a user to which we will login using teh remote session
# I assume in this guide the user "admin"
# Ensure you create a password for your user, because KDE and GNOME won't accept an empty password at the login prompt !
# For security reasons, set also a password for user root
# Only add the mountpoints you need in ro, and some temp smb directories in rw, again for security reasons
# Login to the jail
root@truenas:~ #
iocage start xgui
iocage console xgui
# First update packages
root@xgui:~ #
pkg update
# ******************************
# Install X Window: xorg
#*******************************
# This is the X Window System used to provide a graphical environment in BSD
# It is needed for all BSD desktops which are based on Xorg (KDE, XFCE, Gnome)
pkg install xorg
# ******************************
# Install TigerVNC
# ******************************
# This is by far the most maintained VNC client
pkg install tigervnc-server
# Run VNC for the first time to setup config files
# - First login as the user under which we will start VNC sessions so that the config files
# are created under the user home directory, and not root home directory
# I will assume a user called admin was created
su - admin
admin@xgui:~ $
vncserver
# - enter the password, skip a view only password unless needed
# - to change password:
rm ~/.vnc/passwd
vncpasswd
# Exit vncserver
vncserver -kill :1
# Check the xstartup file vnc created:
# - by default, TigerVNC will start twm GUI and will start a small graphical terminal, xterm
# - no edits should be needed to test an xterm session with twm
cat ~/.vnc/xstartup
[xstartup][default] {
#!/bin/sh
unset SESSION_MANAGER
unset DBUS_SESSION_BUS_ADDRESS
OS=`uname -s`
if [ $OS = 'Linux' ]; then
case "$WINDOWMANAGER" in
*gnome*)
if [ -e /etc/SuSE-release ]; then
PATH=$PATH:/opt/gnome/bin
export PATH
fi
;;
esac
fi
if [ -x /etc/X11/xinit/xinitrc ]; then
exec /etc/X11/xinit/xinitrc
fi
if [ -f /etc/X11/xinit/xinitrc ]; then
exec sh /etc/X11/xinit/xinitrc
fi
[ -r $HOME/.Xresources ] && xrdb $HOME/.Xresources
xsetroot -solid grey
xterm -geometry 80x24+10+10 -ls -title "$VNCDESKTOP Desktop" &
twm &
} [xstartup][default]
# Test an xterm VNC remote session
vncserver :1 -localhost no
# - Connect to the VNC server from Windows RealVNC VNC Viewer
JAIL_IP:5901
# - We should see the xterm console
# Edit xstartup file to support kde, xfce and gnome
admin@xgui:~ $
nano ~/.vnc/xstartup
[xstartup][Final] {
#!/bin/sh
# Options: gnome, xfce, kde
desktop="kde"
# xsetroot: is a program that allows you to tailor the appearance of the background ("root")
# window on a workstation display running X (xorg). Any X dialog will have that look
unset SESSION_MANAGER
unset DBUS_SESSION_BUS_ADDRESS
OS=$(uname -s)
if [ "$OS" = 'Linux' ]; then
case "$WINDOWMANAGER" in
*gnome*)
if [ -e /etc/SuSE-release ]; then
PATH=$PATH:/opt/gnome/bin
export PATH
fi
;;
esac
fi
if [ -x /etc/X11/xinit/xinitrc ]; then
exec /etc/X11/xinit/xinitrc
fi
if [ -f /etc/X11/xinit/xinitrc ]; then
exec sh /etc/X11/xinit/xinitrc
fi
# Start and bind to desktop
if [ "$desktop" = "gnome3" ]; then
# Start Gnome 3 Desktop
[ -r "$HOME/.Xresources" ] && xrdb "$HOME/.Xresources"
vncconfig -iconic &
dbus-launch --exit-with-session gnome-session &
elif [ "$desktop" = "xfce" ]; then
# Start xfce GUI
[ -r "$HOME/.Xresources" ] && xrdb "$HOME/.Xresources"
xsetroot -solid grey
startxfce4 &
elif [ "$desktop" = "kde" ]; then
# Start KDE Plasama
[ -r "$HOME/.Xresources" ] && xrdb "$HOME/.Xresources"
xsetroot -solid grey
startplasma-x11 &
else
# Start default xterm with twm
[ -r "$HOME/.Xresources" ] && xrdb "$HOME/.Xresources"
xsetroot -solid grey
xterm -geometry 80x24+10+10 -ls -title "$VNCDESKTOP Desktop" &
twm &
fi
} [xstartup][Final]
# ******************************
# Install KDE:
# ******************************
# KDE is probably the most supported desktop environment for FreeBSD
# https://community.kde.org/FreeBSD/Setup/Ports
# First, install SDDM display manager, needed for KDE (equivalent of GDM for gnome)
# The display manager offers a graphical login page and sessions manager
root@xgui:~ #
pkg install sddm
# Install kde desktop:
# - Full package
pkg install kde5
# - Minimal package (our choice)
pkg install plasma5-plasma
# - Base apps only
pkg install kde-baseapps
# Set KDE and needed services to launch on start by adding these lines at end of /etc/rc.conf
# Note: We can safely disable the line kde5_enable because our system is headless
# The KDE desktop will be started by vncserver when launched
# - moused_enable: [NO MORE NEEDED] mouse support in xorg
# - hald_enable: [NO MORE NEEDED] HAL kernel layer for graphics support in xorg
# - dbus_enable: kernel messaging system, needed for proper working of KDE
# - sddm_enable: the SDDM display manager to display a login session
# - kde5_enable: we start the desktop manually with VNC
nano /etc/rc.conf
# Enable KDE services on start
#kde5_enable="YES"
#moused_enable="YES"
dbus_enable="YES"
#hald_enable="YES"
sddm_enable="YES"
# - Or enable the services just by running
sysrc dbus_enable="YES" && service dbus start
sysrc sddm_enable="YES" && service sddm start
# Mount /proc because it is needed by kde (even if it seems to work without it !)
# Note: the above /etc/rc.conf services must be enabled before adding /proc to fstab
root@truenas:~ #
iocage stop xgui
cd /mnt/dataset/iocage/jails/xgui
nano fstab
# /proc needs to be mounted for kde
proc /proc procfs rw 0 0
# Fix file name support in UTF-8
# KDE by default, doesn't display UTF-8 file names
# It doesn't read the config in /etc/login.conf or ~/.login_conf
# French chars in file names "é, à..." will not be properly handled in apps
# To Fix this:
iocage console xgui
# - login as the user running VNC and thus starting KDE
su - admin
# - create this startup file for KDE
admin@xgui:~ $
nano .config/plasma-workspace/env/locale.sh
[locale.sh] {
#!/bin/sh
export LANG=en_US.UTF-8
export MM_CHARSET=UTF-8
} [locale.sh]
# - restart the jail or the VNC session
# - file names with special characters should be properly handled now
# Add double click support to select items
# KDE GUI / System settings / Workspace / Workspace Behavior / General Behavior
# - Clicking files and folders: Selects them
# Configure xstartup for kde
nano .vnc/xstartup
# paste above file contents
# ******************************
# [OPTIONAL] Install gnome3
# ******************************
# Also needs xorg we previously installed
# This is probably the least supported desktop environment for FreeBSD
#
# There are two flavours, gnome3 and gnome3-lite
# The Lite edition only includes the minimal components to get a working GNOME 3 Desktop.
# The user then has to install preferred applications like editor, web browser or e-mail client.
# If you wish to install the full desktop after having installed gnome3-lite, look below
#
# Note: Both flavours will automatically install gnome-desktop and gdm dependencies
# - gdm: the display manager for the login page and session manager
# - gnome-desktop: the graphical desktop
#
# BUG: currently, there is an old bug still present. The login graphical page does not accept
# password through a VNC connection. It is reported to be a refresh issue
# - We install the lite version (gdm, gnome-desktop and xorg are automatically installed as gnome3-lite dependencies)
#pkg install gnome3-lite gnome-desktop gdm
pkg install gnome3-lite
# - Alternatively, install full gnome3 with all apps (gdm, gnome-desktop and xorg are automatically installed as gnome3 dependencies)
#pkg install gnome3 gnome-desktop gdm
pkg install gnome3
# - To migrate from the lite to the full version:
pkg delete gnome3-lite
pkg install gnome3
# Set gnome3 and needed services to launch on start by adding these lines at end of /etc/rc.conf
# Note: We can safely disable the line gnome_enable because our system is headless
# The gnome3 desktop will be started by vncserver when launched
nano /etc/rc.conf
# Enable Gnome services on start
#gnome_enable="YES"
moused_enable="YES"
dbus_enable="YES"
hald_enable="YES"
gdm_enable="YES"
# Mount /proc because it is needed by gnome3 (even if it seems to work without it !)
# Note: the above /etc/rc.conf services must be enabled before adding /proc to fstab
root@truenas:~ #
iocage stop xgui
cd /mnt/dataset/iocage/jails/xgui
nano fstab
# /proc needs to be mounted for gnome3
proc /proc procfs rw 0 0
# Reboot the jail from main TrueNAS host
root@truenas:~ #
iocage start xgui
# Login to jail
iocage console xgui
# Configure xstartup for gnome3
nano .vnc/xstartup
# paste above file contents
# *********************************************
# VNC Server setup: Manual or using SSH Tunnel
# *********************************************
#
# Manually start vncserver for the user admin using our installed desktop
# -localhost no: allow connecting remotely, we will disable it later
su - admin
vncserver :5 -depth 24 -geometry 1920x1080 -localhost no
# Test we can properly connect using VNC Viewer
JAIL_IP:5905
# If ok, stop the VNC server
vncserver -kill :5
# Enable SSH tunnel to secure VNC connection
# - First we setup the SSH service on the jail
root@xgui:~ #
sudo nano /etc/ssh/sshd_config
Port 15850
PermitRootLogin no
AuthenticationMethods "publickey,password"
PubkeyAuthentication yes
AuthorizedKeysFile .ssh/authorized_keys
PasswordAuthentication yes
PermitEmptyPasswords no
ChallengeResponseAuthentication no
UsePAM no
# Enable this for the SSH tunnel
AllowTcpForwarding yes
# - Enable sshd daemon on boot, and start it
sysrc sshd_enable="YES"
service sshd start
# - Create the private/public key pair for user admin
# When prompted, you must set a passphrase for openssl to generate the private key
openssl genrsa -aes256 -out privatekey.pem 4096
# - Extract public key from the private key and put it in /admin/.ssh directory
# + We first create and properly set permissions on the directory and public key file
su - admin
admin@xgui:~ $
mkdir .ssh
chmod 700 .ssh
#chown admin:smb_admin .ssh
touch .ssh/authorized_keys
chmod 600 .ssh/authorized_keys
#chown admin:smb_admin .ssh/authorized_keys
# + Extract the public key at the location set in sshd_config (authorized_keys)
exit
root@xgui:~ #
ssh-keygen -y -f privatekey.pem >/home/admin/.ssh/authorized_keys
# Restart sshd service
service sshd restart
# Setup Bitvise Client for SSH access to xgui server
# - in bitvise, create a new profile
# - Host: IP of xgui server: JAIL_IP
# - Port: 15850
# - Client key manager / Import
# - Select the privatekey.pem file previously created by openssl
# - Passphrase: enter the passphrase we set for the private during creation
# - add a comment to easily identify the key: "PC for admin@xgui Jail"
# - Client key manager / Select the imported key / Change passphrase
# - Remove the passphrase by entering old one, and leaving New fields empty
# Bitvise cannot save the passphrase and we must remove it to avoid having a prompt for the passphrase each time
# - For security, export a backup of the private key, with a passphrase
# - Username: admin
# - Initial method: publickey+password
# - Client key: Profile (select key profile we setup in "Client key manager")
# - Passphrase: greyed if we did not set one or we removed the passphrase
# + it is the certificate passphrase we decided to remove once the key is imported in Bitvise
# - Store encrypted password in profile: checked
# + User password will be saved, in an encrypted format, in Bitvise profile
# - Password: enter the password for user "admin"
# - Enable password over kbdi fallback: unchecked
# + Else, we will get the prompt for user password even if we saved it
# - Elevation: default
# - Options tab: select which programs to open on start: none since we will be using it for the VNC tunnel
# Test the SSH access and manually open terminal
# Setup SSH tunnel for VNC access to xgui server using Bitvise Client
# VNC is an unencrypted protocol and the server as we previously setup with "-localhost no"
# will listen on all interfaces. Any remote client can connect to the server.
# The password, being non-encrypted, can be easily sniffed on the local network
# The workaround is:
# - Setup an SSH tunnel on the client that will listen to local client interface 127.0.0.1
# - Set VNC Server to only accept connections and listen on the 127.0.0.1 interface (localhost of the server)
# - In VNC Client: we set destination IP to the client localhost interface rather than to the IP of the remote VNC Server
# - The SSH client running the tunnel will forward the connection on the local client port to the remote server
# The connection will use SSH and be forwarded to localhost:remote_port of the server
#
# Steps for Bitvise: we setup C2S (Client to Server) SSH port forwarding
# - Bitvise GUI / xgui Jail SSH profile / C2S Tab
# + Add
# + Enabled: check
# + Listen Interface: 127.0.0.1 (or localhost)
# + List. Port: 5905
# + Destination Host: localhost
# It is important that Destination Host is set to localhost
# It is the target VNC Server listening interface that we will set to localhost
# + Dest. Port: 5905
# + Comment: TigerVNC #5
# + SSH Login to the server in Bitvise
# - VNC Viewer / Edit VNC Connection
# + VNC Server: localhost:5905
# instead of the JAIL_IP:5905
# - Test the VNC connection and if it is ok, we can proceed to next step
# - Restrict VNC Server to listen only on localhost, that is, it will accept only connections from a local user
# and not from any other interface
admin@xgui:~ $
vncserver :5 -depth 24 -geometry 1920x1080 -localhost yes
# *********************************************
# Start VNC server as a service, on jail boot
# *********************************************
#
# We will use display #5 (port 5905) and user admin
# First, create the service daemon file
root@xgui:~ #
nano /usr/local/etc/rc.d/vncserver
[vncserver] {
#!/bin/sh
# Download this file
# cd /usr/local/etc/rc.d && fetch --no-verify-peer https://gist.githubusercontent.com/PhilZ-cwm6/bdc85494725bd1c1443b4db0f7f306e4/raw/64f22491e41b04398c69a80773aaa042f5ed0d64/vncserver
#
# Make the file executable with:
# /usr/local/etc/rc.d/vncserver (chmod +x)
#
# add to /etc/rc.conf
# vncserver_enable="YES"
#
# Edit below variables for the VNC server options
# PROVIDE: vncserver
# REQUIRE: NETWORKING SERVERS DAEMON ldconfig resolv
#
. /etc/rc.subr
name=vncserver
rcvar=vncserver_enable
VNCSERVER=/usr/local/bin/vncserver
load_rc_config $name
start_cmd="vncserver_start"
stop_cmd="vncserver_stop"
restart_cmd="vncserver_restart"
: ${vncserver_user="admin"}
: ${vncserver_enable="NO"}
: ${vncserver_display="5"}
: ${vncserver_depth="24"}
: ${vncserver_geometry="1920x1080"}
#: ${vncserver_localhost="no"}
: ${vncserver_localhost="yes"}
vncserver_start()
{
CMD="$VNCSERVER :${vncserver_display} -depth ${vncserver_depth} -geometry ${vncserver_geometry} -localhost ${vncserver_localhost}"
su -l ${vncserver_user} -c "${CMD}"
}
vncserver_stop()
{
CMD="$VNCSERVER -kill :${vncserver_display}"
su -l ${vncserver_user} -c "${CMD}"
}
vncserver_restart()
{
host=$(hostname -s)
[ -f "/home/${vncserver_user}/.vnc/${host}:${vncserver_display}.pid" ] && run_rc_command stop
run_rc_command start
}
run_rc_command "$1"
} [vncserver]
# Set the service script as executable
chmod +x /usr/local/etc/rc.d/vncserver
# Test the service
# This should start the service on display :5 and under user admin
root@xgui:~ #
service vncserver onestart
service vncserver onestop
service vncserver onerestart
# Enable the vncserver servcie on boot
sysrc vncserver_enable="YES"
# - Alternatively, add this line to /etc/rc.conf
vncserver_enable="YES"
# Restart the jail, we should be able to connect using VNC Viewer and Bitvise SSH tunnel
# *********************************************
# Take a snapshot of our configured jail
# *********************************************
# Commands to take, restore and delete a jail snapshot:
iocage snapshot xgui -n "manual-2022-01-27_17-38-vnc-tunnel-service"
Snapshot: dataset/iocage/jails/xgui@manual-2022-01-27_17-38-vnc-tunnel-service created.
iocage rollback -n "manual-2022-01-27_17-38-vnc-tunnel-service" xgui
iocage snapremove -n "manual-2022-01-27_17-38-vnc-tunnel-service" xgui
# *********************************************
# Install Sakura terminal
# *********************************************
pkg install sakura
New packages to be INSTALLED:
sakura: 3.8.4
vte3: 0.64.2_1
# Configure Sakura useful hot keys
# Sakura uses hotkeys with Accelerator+Key
# Accelerator is a combination of keys defined as:
- Shift key: 1
- Scroll lock key: 2
- Ctrl key: 4
- Alt key: 8
- Windows key: 64
# Below config changes will do:
# - Increase font size to 14 pt
# - Ctrl+T: new TAB
# - Ctrl+W: delete current TAB
# - Ctrl+Right/Left: change TAB
# - Ctrl+Minus/Plus: font size
su - admin
nano ~/.config/sakura/sakura.conf
font=Ubuntu Mono,monospace 14
add_tab_accelerator=4
del_tab_accelerator=4
switch_tab_accelerator=4
add_tab_key=T
del_tab_key=W
prev_tab_key=Left
next_tab_key=Right
increase_font_size_key=plus
decrease_font_size_key=minus
font_size_accelerator=4
# *********************************************
# Install mkvtoolnix / dolphin file manager...
# *********************************************
# These are all X Window apps, so they need either xorg or the X11 forwarding to run
# In X Org mode, we can start them directly from KDE Desktop in VNC
# MKVToolnix (X Win)
pkg install mkvtoolnix
mkvtoolnix-gui
# File manager (X Win)
pkg install dolphin
dolphin
# qBittorrent (X Win)
# - Note: There is a package flavour "qBittorrent-nox" for No X11 that can run as a service without X11 needed
# The "qBittorrent-nox" version can be accessed by enabling its web UI in conf files
# - The quarterly repo contains an outdated version 4.3.9
pkg install qbittorrent
Updating FreeBSD repository catalogue...
FreeBSD repository is up to date.
All repositories are up to date.
The following 2 package(s) will be affected (of 0 checked):
New packages to be INSTALLED:
libtorrent-rasterbar: 1.2.14,1
qbittorrent: 4.3.9
Proceed with this action? [y/N]: n
# - We switch to latest repo, but better in a clone and different jail
cp /etc/pkg/FreeBSD.conf /usr/local/etc/pkg/repos/FreeBSD.conf
nano /usr/local/etc/pkg/repos/FreeBSD.conf
FreeBSD: {
url: "pkg+http://pkg.FreeBSD.org/${ABI}/latest",
mirror_type: "srv",
signature_type: "fingerprints",
fingerprints: "/usr/share/keys/pkg",
enabled: yes
}
# - If pkg install gives unrecoverable errors, run
#pkg update -f
# - Get the latest qbittorrent and its missing library for offline install
pkg fetch -o ./ qbittorrent libtorrent-rasterbar
# - In xgui, jail, install the downloaded packages
pkg add qbittorrent-4.4.0.pkg libtorrent-rasterbar-1.2.14,1.pkg
qbittorrent
##########################################################
# Run remote graphical apps using Remote X11 Access
##########################################################
# Another way to run graphical apps in a FreeBSD jail remotely controlled from Window is using
# remote X11 access with X11Forwarding in SSH.
# Unlike VNC, the X Server rendering the graphics is not run locally (xorg) but on the remote machine
# That's why, the remote machine is often called the server, because it runs the X Window Server
# In Windows, the X Window servers are "Xming" and the most updated opensource "VcXsrv"
# Other Linux X Window servers can be used with Windows for Linux Subsystem, or Cygwin
# However, many X apps are designed on the assumption that the X Window server is running locally (xorg in FreeBSD)
# They can have a heavy anti-aliasing and other effects not properly suitable on a slow LAN
# A few important differences and limitations in X11:
# - VNC exports a whole session, desktop and all,
# while "ssh -X" will run a single program and show its windows on your workstation.
# - VNC server exports a session that survives even when you disconnect your screen,
# and you can reconnect to it later with all the windows open etc.
# This is not possible with an ssh X tunnel, since when your X server dies, the windows go away.
# - With ssh X, the remote machine must stay awake to proceed the remote app tasks.
# VNC will keep the remote Server independent while running the app, just like Windows RDP
# First, we install xauth and a sample X terminal to test:
pkg install xauth xterm
# And setting SSH server like above + add below entries to allow X11 Forwarding
sudo nano /etc/ssh/sshd_config
#AllowAgentForwarding yes
AllowTcpForwarding yes
#GatewayPorts no
X11Forwarding yes
X11DisplayOffset 10
# Only listen on localhost address:
X11UseLocalhost yes
#PermitTTY yes
# If you get the error: X11 forwarding request failed on channel 0
# Or have connection issues, try "X11UseLocalhost no" to allow listening on ALL interfaces (less secure)
X11UseLocalhost no
# Disable listening on IPv6 interface:
AddressFamily inet
# In jail, edit the hosts file [OPTIONAL]
# Use the IP and hostname of the jail. When you ssh in with X11 forwarding,
# it will try to resolve the machine's hostname. This tells it to use the IP address of the jail.
nano /etc/hosts
JAIL_IP xgui
# Install "VcXsrv X Window Server" on the Windows machine that will control the GUI apps remotely
# It will be the X Window Server
# The Client running the app, will send the GUI coordinates to the X Window Remote server
# The X Server is responsible of rendering the graphics on the remote machine where the user is sitting
# - Start XLauncher (VcXsrv X Window Server)
# - Select display settings: Multiple windows
# - Display number: 10
# This is the display selected by default in sshd_config "X11DisplayOffset"
# - Click Next
# - Select how to start clients: Start no client
# - Click Next
# - Extra settings: Disable access control
# Enable X11 forwarding on the SSH client (Bitvise, puTTy) on the Windows Machine
# - In Bitvise: after setting a proper SSH connection like above
# + Terminal tab
# + X11 Forwarding: checked
# + Display: 127.0.0.1:10.0
# - In Linux/Unix:
# + edit the client ~/.ssh/config file with these lines:
ForwardAgent yes
ForwardX11 yes
# + start ssh session with
ssh -v -X user@host
# Test an xterm graphical terminal by running from SSH client:
# You should get a new X11 terminal window in your Window machine
echo $DISPLAY
xgui:10.0
xterm
Last edited:
