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: