X2Go - everywhere@home

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== X2Go-ThinClientEditon-Live (TCE-Live, formerly known as TCE-NG) ======
<columns 75% ->

<note tip>If you are looking for installation instructions for the classic, NFS-filesystem-based X2Go-ThinClient, please go [[wiki:advanced:tce:install|here]]
</note>

</columns>

===== History, Rationale, Outlook =====

During the time of Debian Wheezy being Debian's stable release, we started developing a new ThinClientEdition then called TCE-Next Generation, or TCE-NG for short - one that is based on Debian-Live and thus does no longer rely on NFS (though NFS can still be used to deploy the image - but we do not recommend that approach).  Instead, the entire image is loaded into the RAM of the ThinClient machine.  To avoid confusion, and because it has since left the "NG" state, we now call it TCE-Live.

The disadvantage is that your ThinClient now needs at least 512 MB to 1 GB of RAM (see below).  Working with 256 MB is possible when you use local storage instead of netbooting (don't use the ''toram'' parameter, either), but not really recommended.

However, the huge advantage is that there no longer is a need for any high-availibility setup concerning NFS (nor HTTP/HTTPS/FTP).  If you follow our advice of loading the entire image into the ThinClient's RAM, or using local storage,  all you need is an HTTP (HTTPS optional for later stages) or FTP server with a dedicated IP, if you want to use netbooting.  It is also possible to deploy the image to the ThinClient's local storage, if present, and have it update in the background.

Besides, making changes to/updating the classic, NFS-based TCE (henceforth referred to as TCE-Classic) with the entire filesystem, not just its compressed image, spread out over the NFS share was rather finicky - with the current TCE-Live, you build and deploy a new image every time you make a change, and you can test it on a single client without interrupting your production environment.  The //local storage// feature can also be used to create a portable version of both X2Go-TCE and X2GoClient for Windows, sharing the same configuration, on CD/DVD/USB media.

We've also received reports that TCE-Classic wouldn't work with Jessie, or at least it was very hard to get it to work.
Our TCE-Live works just fine with Jessie, Stretch, and Buster as well.
 
===== ThinClient prerequisites for all TCE-Live variants =====
  * At least 1 GB of RAM //unless// you use non-NTFS local storage, in that case, 512MB or even 256MB might work - but would you really want to use a Client that has 4 Megabytes of free RAM (our test result with 256 MB RAM total) and no swapspace?
  * For clients with less than 1 GB of RAM and no local storage, you could also use ''httpfs='' or ''ftpfs='' instead of ''fetch='', or ''netboot=nfs nfsroot=ip-of-your-server-here:/path/to/x2go-tce-filesystem.squashfs'' when netbooting, but this will make you dependent on an uninterrupted network connection again
  * At least an i586-compatible CPU
  * Capability to boot via PXE //or// sufficient local storage (expect 250-450 MB, depending on what you decide to include)
  * A graphics card and input devices (Keyboard, Mouse/Trackball/Touchpad/Trackpoint/Touchscreen, ...) that are supported by the stock Debian X Server
===== Build system prerequisites for all variants =====
  * You need a Debian Buster system to build the image. (Other distributions based on Debian might work, but this is untested.)
  * We suggest using a 64-Bit system, however, it is possible to use a 32-Bit system if you don't want to build a 64-Bit ThinClient image.
  * We suggest leaving at least 4 GB of free disk space so the build won't abort due to insufficient disk space while packages are downloaded, unpacked and copied around.
  * Make sure your package list is up to date by running: <code>sudo apt-get update </code>
  * Install the required package(s) by running: <code>sudo apt-get install genisoimage git-core live-build live-config-doc live-manual-html live-boot-doc lsb-release netcat-traditional</code>
  * If you want to speed up subsequent builds, install the recommended package(s) by running: <code>sudo apt-get install apt-cacher-ng</code>
  * If you want to be prepared to be able to cross-build across different architectures (e.g. building an ARM image on an Intel/AMD build host) - a feature coming soon - install the optional package(s) by running: <code>sudo apt-get install qemu-user-static binfmt-support squashfs-tools -y && update-binfmts --enable qemu-aarch64</code>

===== Building your own X2Go-TCE Image =====
==== Configuring the Build ====
Change to a directory where you want to save your builds, and save the following file as x2go-tce-config:
<code>
# NOTE: This file gets sourced by the actual buildscript - so place it in the same directory as the buildscript or adjust the path in the buildscript.

# simple check for apt-cacher-ng being active - if
# we have a successful connect on port 3142, assume
# it's apt-cacher-ng and use it
#
if nc -z 127.0.0.1 3142 ; then 
    # bad idea with apt-cacher-ng, but will work with e.g. squid
    # export https_proxy=http://127.0.0.1:3128/ 
    # export http_proxy=http://127.0.0.1:3128/
    # export ftp_proxy=http://127.0.0.1:3128/

    export LB_APT_FTP_PROXY=http://127.0.0.1:3142/
    export LB_APT_HTTP_PROXY=http://127.0.0.1:3142/
fi

# set these to true to save source files
#export LB_SOURCE="true"
#export LBX2GO_GETSRC="true"

# Select ONE of the following git reposities
# this one loosely corresponds to "stable"
#export LBX2GO_CONFIG='https://gitlab.x2go.org/x2go/live-build-x2go.git::feature/openbox-magic-pixel-workaround-buster'
#export LBX2GO_CONFIG='https://gitlab.x2go.org/x2go/live-build-x2go.git::feature/mate-minidesktop-buster'
export LBX2GO_CONFIG='https://gitlab.x2go.org/x2go/live-build-x2go.git::feature/openbox-magic-pixel-workaround-bullseye'
#export LBX2GO_CONFIG='https://gitlab.x2go.org/x2go/live-build-x2go.git::feature/mate-minidesktop-bullseye'
#export LBX2GO_CONFIG='https://github.com/bauritcs/live-build-x2go.git::feature/openbox-magic-pixel-workaround-bookworm'
#export LBX2GO_CONFIG='https://github.com/bauritcs/live-build-x2go.git::feature/mate-minidesktop-bookworm'
# NOTES: 1) https://github.com/bauritcs loosely corresponds to "heuler"
#        2) Minidesktop builds are work in progress and not production-ready. Cont(r)act us if you need them; feel free to submit patches.
#        3) Add "-stretch" to the end of the LBX2GO_CONFIG string to create a stretch build,
#           add "-buster" to the end of the LBX2GO_CONFIG string to create a buster build,
#           add "-bullseye" to the end of the LBX2GO_CONFIG string to create a bullseye build
#           add "-bookworm" to the end of the LBX2GO_CONFIG string to create a bookworm build (will be in gitlab repo $SOON - use github.com/bauritcs for now)

# Select ONE of the following LBX2GO_ARCH lines and comment out the others
# (feel free to use long or short options)
# for 64-Bit builds, use:
export LBX2GO_ARCH='-a amd64 -k amd64'
# 32-Bit, larger memory footprint, but faster performance on i686 and newer
#export LBX2GO_ARCH='-a i386 -k 686-pae'
# 32-Bit, smallest memory footprint - not available on buster
# export LBX2GO_ARCH='--architectures i386 --linux-flavours 586'
# For ARM (Raspberry Pi):
#export LBX2GO_ARCH='-a arm64'
#export LBX2GO_ARCH_MODEL='Pi4' # you can also set this to 'Pi3'. Note that there must not be any whitespace between 'Pi' and the digit.

# If you want to use the stock ISO image as created by this script, add your boot parameters here
# export LBX2GO_BOOTAPPEND_LIVE="boot=live components noswap lang=de vconsole.keymap=de keyboard-layouts=de locales=de_DE.UTF-8 silent quiet pubkey=http://x2go/x2go-tce/config/authorized_keys sessionsurl=http://x2go/x2go-tce/config/sessions toram"
export LBX2GO_BOOTAPPEND_LIVE="boot=live components noswap lang=de vconsole.keymap=de keyboard-layouts=de locales=de_DE.UTF-8 silent quiet sessionsurl=https://your_server_here/config/sessions pubkey=https://your_server_here/config/authorized_keys toram "

if echo -e "$LBX2GO_CONFIG" | grep -q "openbox"; then
	LBX2GO_BOOTAPPEND_LIVE+="fastpo "
	export LBX2GO_BOOTAPPEND_LIVE
elif echo -e "$LBX2GO_CONFIG" | grep -q "minidesktop"; then
	LBX2GO_BOOTAPPEND_LIVE+='timezone=Europe/Berlin noautologin ' # if you use nottyautologin instead of noautologin, an autologin will be set for the account "user", which conflicts our setting for the account "x2gothinclient"
	export LBX2GO_BOOTAPPEND_LIVE
fi

# detect if the selected git repo is meant to build a buster, stretch or jessie image
if [ -z "${LBX2GO_CONFIG##*-stretch}" ] ; then
    export LBX2GO_DEBVERSION="stretch"
    export LBX2GO_BOOTAPPEND_LIVE+=" net.ifnames=0 biosdevname=0"
elif [ -z "${LBX2GO_CONFIG##*-buster-heuler}" ] ; then
    export LBX2GO_DEBVERSION="buster"
    export LBX2GO_BOOTAPPEND_LIVE+=" net.ifnames=0 biosdevname=0"
elif [ -z "${LBX2GO_CONFIG##*-buster-heuler-bpo}" ] ; then
    export LBX2GO_DEBVERSION="buster"
    export LBX2GO_BOOTAPPEND_LIVE+=" net.ifnames=0 biosdevname=0"
elif [ -z "${LBX2GO_CONFIG##*-buster}" ] ; then
    export LBX2GO_DEBVERSION="buster"
    export LBX2GO_BOOTAPPEND_LIVE+=" net.ifnames=0 biosdevname=0"
elif [ -z "${LBX2GO_CONFIG##*-bullseye}" ] ; then
    export LBX2GO_DEBVERSION="bullseye"
    export LBX2GO_BOOTAPPEND_LIVE+=" net.ifnames=0 biosdevname=0"
elif [ -z "${LBX2GO_CONFIG##*-bookworm}" ] ; then
    export LBX2GO_DEBVERSION="bookworm"
    export LBX2GO_BOOTAPPEND_LIVE+=" net.ifnames=0 biosdevname=0"
    export LBX2GO_ARCHIVE_AREAS="non-free-firmware "
else
    export LBX2GO_DEBVERSION="jessie"
fi

# newer versions of live-build use the plural form of this parameter
if $(LANG=C lb config --help | grep -q bootloaders) ; then
    export LBX2GO_BOOTLOADERPARAMNAME="--bootloaders"
else
    export LBX2GO_BOOTLOADERPARAMNAME="--bootloader"
fi

# set boot loader type - leave this unchanged unless you really know what you're doing
if echo $LBX2GO_ARCH | awk '{print $2}' | grep -q "arm" ; then
    # This is part of our experimental ARM support
    LBX2GO_BOOTLOADERPARAMNAME=" "
    LBX2GO_BOOTLOADER=" "
else
    export LBX2GO_BOOTLOADER="syslinux"
fi

# These options are meant to reduce the image size.
# Feel free to adapt them after consulting "man lb_config"
# FIXME export LBX2GO_SPACE='--apt-indices none
export LBX2GO_SPACE='--apt-indices false
                     --apt-recommends false
                     --cache false
                     --checksums none
                     --firmware-binary false
                     --memtest none
                     --win32-loader false'

# fixing some peculiarities for Ubuntu here
if $(lsb_release -i | grep -i ubuntu -q ) ; then
        [ -f /usr/lib/live/build/binary_rootfs ] || ln -s /usr/lib/live/build/lb_binary_rootfs /usr/lib/live/build/binary_rootfs
        export LBX2GO_MIRROR="  -m http://deb.debian.org/debian
                                --mirror-chroot-security http://security.debian.org/debian/
                                --mirror-binary-security http://security.debian.org/debian/
                                --parent-mirror-chroot-security http://security.debian.org/debian/
                                --parent-mirror-binary-security http://security.debian.org/debian/"
else
        export LBX2GO_UPDATES="--updates true"
fi

# These are default values that should not require tuning
export LBX2GO_DEFAULTS="--backports true
                        --firmware-chroot true
                        --initsystem sysvinit
                        --security true
                        $LBX2GO_UPDATES
                        $LBX2GO_MIRROR
                        $LBX2GO_BOOTLOADERPARAMNAME $LBX2GO_BOOTLOADER
                        --distribution $LBX2GO_DEBVERSION"

# This is part of our experimental ARM support
if echo $LBX2GO_ARCH | grep -q 'arm' && ! dpkg --print-architecture | grep -q 'arm' ; then
    export LBX2GO_DEFAULTS+=" --bootstrap-qemu-arch arm64 \
                              --bootstrap-qemu-static /usr/bin/qemu-aarch64-static \
                              --apt-options \"--yes -oAPT::Default-Release=${LBX2GO_DEBVERSION} -oAPT::Immediate-Configure=false\" "
fi

# This is part of our experimental ARM support
# This makes sure the resulting disk image is at least 1GB in size, even though our build currently requires way less.
# It's unlikely that anyone will need to boot from a smaller partition; but if we let live-build pick the minimum size automatically,
# we will not have enough space left to copy the firmware blobs into the right location.
if echo $LBX2GO_ARCH | grep -q 'arm' ; then
    export LBX2GO_DEFAULTS+=" --binary-filesystem fat32 \
                              --hdd-size 1024"
fi

export LBX2GO_ARCHIVE_AREAS="main contrib non-free $LBX2GO_ARCHIVE_AREAS"

# This is for minidesktop builds and currently only adds firefox-esr language packs
# export LBX2GO_LANG='de'

# This is to optimize squashfs size, based on a suggestion by intrigeri from the TAILS team
# note that this will permanently change /usr/lib/live/build/binary_rootfs
#
#
if dpkg --print-architecture | grep -q 'arm' || echo $LBX2GO_ARCH | grep -q 'arm' ; then
	# on arm, these parameters must not be used; if they're there, we need to reinstall the package to undo our patch
	if grep -q -- '-Xbcj x86 -b 1024K -Xdict-size 1024K' /usr/lib/live/build/binary_rootfs; then
		apt install --reinstall live-build
	fi
	# feel free to experiment with these options, but be prepared for subtle breakage 
	#export MKSQUASHFS_OPTIONS=' -Xbcj arm '
	#export MKSQUASHFS_OPTIONS=' -b 1024K -Xdict-size 1024K '
	#export MKSQUASHFS_OPTIONS=' -Xbcj arm -b 1024K -Xdict-size 1024K '
	export MKSQUASHFS_OPTIONS=''
else
	export MKSQUASHFS_OPTIONS=' -Xbcj x86 -b 1024K -Xdict-size 1024K '
fi

# This removes documentation, locales and man pages
# You can safely enable this if you intend to run X2GoClient in fullscreen mode all the time, or when building the ssh-only rescue image.
# For all other uses of the TCE-Live image creator (i.e. Minidesktop), your results may vary ... use at your own risk.
export LBX2GO_TCE_SHRINK="true"

# This patches the squashfs file into the initrd. Only parsed when image type "netboot" is set.
# Will require boot parameter live-media=/ instead of fetch=...
# Both TFTP client and TFTP server must support file transfers >32MB for this to work, if you want to deploy this initrd via TFTP, 
# so e.g. atftpd will not work - tftpd-hpa, however, seems to have no problem with larger files.
# When using iPXE, you can use http instead of TFTP.
# This is especially helpful if you want to netboot via http and cannot use the server's IP, but must specify a DNS name - as "fetch=..." only understands IPs.
#export LBX2GO_NOSQUASHFS="true"

# Select ONE of the following LBX2GO_IMAGETYPE lines and comment out the others
# to create an iso image:
#export LBX2GO_IMAGETYPE='iso'
# to create an iso image that can also be dd'ed to USB media:
export LBX2GO_IMAGETYPE='iso-hybrid'
# to create a netboot-image:
#export LBX2GO_IMAGETYPE='netboot'
# /!\ the options below are NOT RECOMMENDED unless you use live-build from Debian Buster /!\
# (Debian 10) or newer to create an image that can be written to a hard disk (for older 
# live-build versions, this always results in a "build failed" message, even though the build
# might have worked - use live-build from Buster or newer and things will work):
#export LBX2GO_IMAGETYPE='hdd'
## This might be required for hdd builds, especially for (u)efi
#export LBX2GO_BOOTLOADER="syslinux grub-pc grub-efi"
# to create a tar file only (seems to be broken in older live-build versions - Buster works):
#export LBX2GO_IMAGETYPE='tar'

# This is part of our experimental ARM support
if echo "$LBX2GO_ARCH" | grep -q "arm" ; then
	# enforce hdd image for arm at the moment (might need to support netboot later on too)
	if ! [ "$LBX2GO_IMAGETYPE" = "hdd" ] ; then
	        echo "WARNING: Replacing selected image type with 'hdd'.  That's all we currently support on ARM."
		export LBX2GO_IMAGETYPE="hdd"
	fi
fi

if [ "$LBX2GO_IMAGETYPE" = "netboot" ]; then
        export LBX2GO_DEFAULTS+=" $LBX2GO_BOOTLOADER"
fi
</code>

==== Live-Patching the Build ====
To add patches that aren't part of any package yet, you can use the directory ./patch/ for patches that should be added to all versions, and ./patch-minidesktop/ for patches that should only be added to the MATE-MiniDesktop Edition.

You will need to create a directory structure like <code>./patch/includes.chroot/etc/</code> to create/overwrite a file in <code>/etc/</code> within the live environment.

e.g. to override <code>/etc/x2go/x2gothinclient-minidesktop_start</code> with a custom version, run <code>mkdir -p ./patch-minidesktop/includes.chroot/etc/x2go/</code> and save the following file as <code>./patch-minidesktop/includes.chroot/etc/x2go/x2gothinclient-minidesktop_start</code>
<code>
#!/bin/bash

# Copyright (C) 2010-2024 by X2Go project, https://wiki.x2go.org
#       Oleksandr Shneyder <o.shneyder@phoca-gmbh.de>
#       Moritz 'Morty' Struebe <Moritz.Struebe@informatik.uni-erlangen.de>
#       Mike Gabriel <mike.gabriel@das-netzwerkteam.de>
#       Stefan Baur <X2Go-ML-1@baur-itcs.de>
#
# X2Go is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# X2Go is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the
# Free Software Foundation, Inc.,
# 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.

# make sure pulseaudio can be reached via TCP from the X2Go Server side...
if ! /usr/bin/pactl list modules | grep -A1 'module-native-protocol-tcp' | grep -q 'auth-ip-acl=127.0.0.1;::1' ; then
        /usr/bin/pactl 'load-module' 'module-native-protocol-tcp' 'auth-ip-acl=127.0.0.1;::1'
fi

# make sure we don't start before sessions and settings files exist - avoids race conditions
while ! [ -e ~x2gothinclient/.x2goclient/sessions ] ; do
        sleep 1;
done

while ! [ -e ~x2gothinclient/.x2goclient/settings ]; do
        sleep 1
done

[ -s /etc/x2go/x2gothinclient_bg.svg ] && X2GO_BG='--background="/etc/x2go/x2gothinclient_bg.svg'
[ -s /etc/x2go/x2gothinclient_branding.svg ] && X2GO_BRAND='--branding="/etc/x2go/x2gothinclient_branding.svg'


/usr/lib/x2go/x2goclient --no-menu \
                         $X2GO_BG \
                         $X2GO_BRAND \
                         --kbd-type=auto \
                         --set-kbd=1 \
                         --tray-icon \
                         --read-exports-from=~/export \
                         --no-session-edit \
                         --add-to-known-hosts \
                         &

</code>
==== Starting the Build ====
In the directory where you want to save your builds, save the following file as x2go-tce-build, and run it (e.g. via //sudo bash ./x2go-tce-build//):
<code>
#!/bin/bash

# read (source) the config file
. ./x2go-tce-config

# Create Timestamp
LBX2GO_TIMESTAMP=$(date +"%Y%m%d%H%M%S")

# Log all output to a logfile in /tmp
exec > >(tee "/tmp/$LBX2GO_TIMESTAMP.log") 2>&1

# Set Directory name
LBX2GO_TCEDIR="./live-build-x2go-${LBX2GO_TIMESTAMP}-${LBX2GO_IMAGETYPE}-$(echo $LBX2GO_ARCH | awk '{print $2}')-${LBX2GO_CONFIG##*/}"

if [ -z "$LBX2GO_ARCH" ] ||
	( echo "$LBX2GO_ARCH" | grep -q "arm" && [ -z "$LBX2GO_ARCH_MODEL" ] ) || 
   [ -z "$LBX2GO_SPACE" ] ||
   [ -z "$LBX2GO_CONFIG" ] ||
   [ -z "$LBX2GO_DEFAULTS" ] ||
   [ -z "$LBX2GO_DEBVERSION" ] ||
   [ -z "$LBX2GO_IMAGETYPE" ] ||
   [ -z "$LBX2GO_TIMESTAMP" ] ||
   [ -z "$LBX2GO_BOOTLOADERPARAMNAME" ] ||
   [ -z "$LBX2GO_BOOTLOADER" ] ||
   [ -z "$LBX2GO_ARCHIVE_AREAS" ]; then
    echo -e "One or more of the following variables is unset:"
    echo -e "LBX2GO_ARCH: '${LBX2GO_ARCH}'"
    echo "$LBX2GO_ARCH" | grep -q "arm" && echo -e "LBX2GO_ARCH_MODEL: '${LBX2GO_ARCH_MODEL}'"
    echo -e "LBX2GO_SPACE: '${LBX2GO_SPACE}'"
    echo -e "LBX2GO_DEFAULTS: '${LBX2GO_DEFAULTS}'"
    echo -e "LBX2GO_DEBVERSION: '${LBX2GO_DEBVERSION}'"
    echo -e "LBX2GO_CONFIG: '${LBX2GO_CONFIG}'"
    echo -e "LBX2GO_IMAGETYPE: '${LBX2GO_IMAGETYPE}'"
    echo -e "LBX2GO_TIMESTAMP: '${LBX2GO_TIMESTAMP}'"
    echo -e "LBX2GO_BOOTLOADERPARAMNAME: '${LBX2GO_BOOTLOADERPARAMNAME}'"
    echo -e "LBX2GO_BOOTLOADER: '${LBX2GO_BOOTLOADER}'"
    echo -e "LBX2GO_ARCHIVE_AREAS: '${LBX2GO_ARCHIVE_AREAS}'"
    echo -e "Please visit http://wiki.x2go.org/doku.php/doc:howto:tce"
    echo -e "and read up on the general prerequisites for X2Go-TCE"
else
    # This will create a timestamped subdirectory for the build
    mkdir -p $LBX2GO_TCEDIR
    cd $LBX2GO_TCEDIR

    X2GO_LBCONFIG_STRING=$(cat <<X2GOLBCONFIGSTRING
    lb config $LBX2GO_ARCH $LBX2GO_SPACE $LBX2GO_DEFAULTS \
       --config $LBX2GO_CONFIG --binary-images $LBX2GO_IMAGETYPE \
       --archive-areas "$LBX2GO_ARCHIVE_AREAS" \
       --bootappend-live "$LBX2GO_BOOTAPPEND_LIVE"
X2GOLBCONFIGSTRING
)
    # Our previous way of doing this had issues with newlines and multiple blanks. So we're now doing a bit
    # of sanitizing, then we eval the variable.
    X2GO_LBCONFIG_STRING=$(echo "$X2GO_LBCONFIG_STRING" | tr '\n' ' ' | tr -s ' ')
    eval "$X2GO_LBCONFIG_STRING"

    # This will copy any patches we have prepared
    if [ -d "../patch" ] ; then
        cp -a ../patch/* config/
    fi

    # This will copy any patches we have prepared for minidesktop
    if [ -d "../patch-minidesktop" ] && (echo "$LBX2GO_CONFIG" | grep -q minidesktop) ; then
        cp -a ../patch-minidesktop/* config/
    fi

    # This checks if a bootloader directory is present (e.g. because of a custom splash.svg)
    # and adds all other files that might be missing (live-build won't add them automatically
    # if the directory already exists)
    if [ -d config/bootloaders ] ; then
        rsync -aPH --ignore-existing --exclude="splash.svg" /usr/share/live/build/bootloaders/* config/bootloaders
    fi
    # When enabled, this silences the audible beep at syslinux/isolinux/pxelinux/extlinux startup.
    # Note that this is an accessibility feature for blind users, so use with care.
    sed -e "s/$(echo -e "\07")//g" -i config/bootloaders/*/menu.cfg

    # This enables an i386-only package in the sources.list file when an i386 build is requested
    if echo $LBX2GO_ARCH | grep -q -i "i386" ; then
        sed -i -e 's/# for i386 only #//' config/package-lists/desktop.list.chroot
    fi

    # This is part of our experimental ARM support
    # It adds required arm64-only packages when an arm64 build is requested
    if echo $LBX2GO_ARCH | grep -q "arm" ; then

	# bullseye and newer do not need this
    	if [ "${LBX2GO_DEBVERSION}" = "buster" ]; then 
		# firmware for wifi 
		echo "firmware-brcm80211/buster-backports" >>config/package-lists/raspi.list.chroot
	fi

	if [ "$LBX2GO_ARCH_MODEL" = "Pi3" ] ; then
		# modules required for Raspberry Pi 3 LAN
		echo "crc16" >> config/includes.chroot/etc/initramfs-tools/modules
		echo "mii" >> config/includes.chroot/etc/initramfs-tools/modules
		echo "smsc95xx" >> config/includes.chroot/etc/initramfs-tools/modules
		echo "usbcore" >> config/includes.chroot/etc/initramfs-tools/modules
		echo "usbnet" >> config/includes.chroot/etc/initramfs-tools/modules
		echo "fake-hwclock" >>config/package-lists/raspi.list.chroot
		echo "usbutils" >>config/package-lists/raspi.list.chroot

		# firmware for basic raspi functions - required for boot on Pi3
		echo "raspi3-firmware/buster" >>config/package-lists/raspi.list.chroot
		# standard linux kernel - for Pi3
		echo "linux-image-arm64/buster" >>config/package-lists/raspi.list.chroot

	elif [ "$LBX2GO_ARCH_MODEL" = "Pi4" ] ; then
		# bullseye and newer do not need this
		if [ "${LBX2GO_DEBVERSION}" = "buster" ]; then
			# firmware for basic raspi functions - required for boot on Pi4
			echo "raspi3-firmware/buster-backports" >>config/package-lists/raspi.list.chroot
			echo "raspi-firmware/buster-backports" >>config/package-lists/raspi.list.chroot

			# newer linux kernel - required for pi4/pi400
			echo "linux-image-arm64/buster-backports" >>config/package-lists/raspi.list.chroot
		fi
	else
		echo "WARNING: ARM Platform selected, but unknown model: '$LBX2GO_ARCH_MODEL'. Assuming no additional packages/patches are required."
	fi
    fi
 

    # This is for minidesktop builds only
    if [ -f config/package-lists/firefox-langpacks.list.chroot ]; then
            if [ -n "$LBX2GO_LANG" ]; then
                    for LBX2GO_SINGLE_LANG in $(echo "$LBX2GO_LANG" | tr ';' ' '); do
                            echo "LANG: '$LBX2GO_SINGLE_LANG'"
                            sed -i -e 's/#firefox-esr-l10n-'$LBX2GO_SINGLE_LANG'$/firefox-esr-l10n-'$LBX2GO_SINGLE_LANG'/' config/package-lists/firefox-langpacks.list.chroot
                    done
            else
                    rm config/package-lists/firefox-langpacks.list.chroot
            fi
    fi
    if [ "$LBX2GO_TCE_SHRINK" = "true" ] ; then
        echo '#!/bin/sh' >./config/hooks/0112-remove-folders.hook.chroot
        echo 'set -e' >>./config/hooks/0112-remove-folders.hook.chroot
        echo '# Remove folders' >>./config/hooks/0112-remove-folders.hook.chroot
        echo 'rm -rf ./usr/share/doc/*' >>./config/hooks/0112-remove-folders.hook.chroot
        echo 'rm -rf ./usr/share/locale/*' >>./config/hooks/0112-remove-folders.hook.chroot
        echo 'rm -rf ./usr/share/man/*' >>./config/hooks/0112-remove-folders.hook.chroot
        [ "$LBX2GO_IMAGETYPE" != "netboot" ] && echo 'rm -rf ./var/lib/apt/lists/*' >>./config/hooks/0112-remove-folders.hook.chroot
        chmod 755 ./config/hooks/0112-remove-folders.hook.chroot
    fi

    if [ -n "$LB_APT_HTTP_PROXY" ] || [ -n "$LB_APT_FTP_PROXY" ]; then
        echo "NOTICE: apt proxy variable(s) is/are set."
        echo "NOTICE: Trying to use the proxy for all downloads."
        echo "NOTICE: If this fails, look for #SETPROXY in the $0 source."
        # Here, we should have reached a point where it is safe to point all proxy variables
        # at the apt-cacher-ng proxy.  If you're seeing errors during your build that hint
        # at files not being downloaded, disable these three entries.
        export https_proxy=$LB_APT_HTTP_PROXY
	export http_proxy=$LB_APT_HTTP_PROXY
        export ftp_proxy=$LB_APT_FTP_PROXY
    fi

    # This is part of our experimental ARM support
    # It is used when building for the ARM architecture (on Intel/AMD hardware and on ARM).
    # It makes some necessary changes, and also tries to speed up squashfs creation when it 
    # detects a crossbuild environment.
    if echo $LBX2GO_ARCH | grep -q 'arm'; then

        # This command removes all references to fuseext, freerdp-nightly, and x2gothinclient from the
        # package list files.  Currently needed as there are no ARM packages for any of these.
        echo "WARNING: Removing all references to fuseext,freerdp-nightly and x2gothinclient from the build."
        sed -e 's/^.*fuseext.*$//g' -e 's/^.*freerdp-nightly.*$//g' -e 's/^.*x2gothinclient.*$//g' -i ./config/package-lists/*

	# This command removes the X2Go repository from the directory where additional
        # archives are stored.  Currently needed as the X2Go repository offers no arm64 
        # packages, but Debian Buster does - so that's what we're falling back to.
        echo "WARNING: Removing all references to the X2Go repository from the build."
        rm ./config/archives/*x2go*

	# The following is a hack to reduce squashfs creation time in a crossbuild environment.
	# We're replacing mksquashfs in the changeroot with a wrapper script that drops the 
	# original mksquashfs call into a file.

	if (uname -m | grep -q 'i.86' || uname -m | grep -q 'x86_64' || uname -m | grep -q 'ppc64') ; then
                echo "INFO: using host-architecture mksquashfs from outside instead of the target-architecture one inside chroot."
		# We need to do this as a background task, waiting for the mksquashfs executable to
		# appear in the changeroot; as the changeroot will only be created later on, once
		# lb build is called.
			
		# The other background task waits until the command file has been created, then
		# it applies some necessary patches to it, and starts the mksquashfs command natively
		# on the build host, rather than in the changeroot environment.
		# This is because in the changeroot, we'd be running the ARM mksquashfs in a qemu
		# software emulation of the ARM architecture, while on the host, we can use all the
		# native, raw CPU power and cores available to us.

		# To make sure we don't have any lingering processes in the background, we're passing
		# our own PID along to the background tasks, and tell them to terminate if our PID
		# disappears while they're still in their waiting/looping state.

		MASTERPID=$$

		# Replace mksquashfs in chroot with script
		# (script will undo this upon completion)
		(
		    # wait until the chroot has been populated or until our parent process dies
		    while ! [ -x ./chroot/usr/bin/mksquashfs ]; do
			ps $MASTERPID >/dev/null || exit 1
			sleep 1
		    done
		    # make sure we don't overwrite the real executable if it has already been
		    # moved out of the way
		    if ! [ -x ./chroot/usr/bin/mksquashfs.real ]; then
			cp ./chroot/usr/bin/mksquashfs ./chroot/usr/bin/mksquashfs.real
		    fi
		   echo '#!/bin/bash' >./chroot/usr/bin/mksquashfs
		   # log the name we've been called with and all parameters into this file
		   echo 'echo "$0 $@" >/tmp/filesystem.squashfs.temp' >>./chroot/usr/bin/mksquashfs
		   # once the native mksquashfs is complete, we will remove this file
		   echo 'while [ -f /tmp/filesystem.squashfs.temp ]; do' >>./chroot/usr/bin/mksquashfs
		   echo '        sleep 1' >>./chroot/usr/bin/mksquashfs
		   echo 'done' >>./chroot/usr/bin/mksquashfs
		   # so let's wait until it has been removed before deleting ourselves ...
		   echo 'rm /usr/bin/mksquashfs' >>./chroot/usr/bin/mksquashfs
		   # ... and moving the real executable back into its place
		   echo 'mv /usr/bin/mksquashfs.real /usr/bin/mksquashfs' >>./chroot/usr/bin/mksquashfs
		   chmod 755 ./chroot/usr/bin/mksquashfs
		) &

		# start the native mksquashfs after patching the parameters
		(
		    # wait until the trigger file has been created or until our parent process dies
		    while ! [ -f ./chroot/tmp/filesystem.squashfs.temp ]; do
			ps $MASTERPID >/dev/null || exit 1
			sleep 1
		    done
		    # using any of the available filters (x86, arm, armthumb) for the 
		    # -Xbcj command results in an unusable squashfs on arm, so we drop the 
		    # parameter completely if it's there.
		    # also, all absolute paths (detected by beginning with " /") need to be
		    # prefixed with "./chroot" so the mksquashfs outside the chroot knows where
		    # to look for the corresponding paths/files.
		    sed -e 's/ -Xbcj x86/ /g' -e 's# /# ./chroot/#g' -i \
			./chroot/tmp/filesystem.squashfs.temp
		    #needs switch from e.g. /bin/mksquashfs to $(which mksquashfs)
		    sed -e "s#^.*mksquashfs#$(which mksquashfs)#g" -i \
			./chroot/tmp/filesystem.squashfs.temp
		    # if the mksquashfs command was missing, add it
		    grep -q mksquashfs ./chroot/tmp/filesystem.squashfs.temp || \
			sed -e "s#^ #$(which mksquashfs) #g" -i \
			./chroot/tmp/filesystem.squashfs.temp
		    # now let's make this executable
		    chmod 755 ./chroot/tmp/filesystem.squashfs.temp

		    # we also need to add some more excludes because they shouldn't end up
		    # in the squashfs - no idea why we don't need them while inside the chroot ...
		    echo 'proc/*' >>./chroot/excludes
		    echo 'sys/*' >>./chroot/excludes
		    echo 'dev/pts/*' >>/.chroot.excludes
		    # now let's execute the script and, if it terminates without an error,
		    # we'll move the newly created squashfs into the chroot where the chrooted
		    # mksquashfs command would have created it; if that worked as well, we'll
		    # remove the script file so our dummy mksquashfs inside the chroot knows
		    # it's time to terminate itself.
		    ./chroot/tmp/filesystem.squashfs.temp && \
		    mv ./filesystem.squashfs ./chroot/ && \
		    rm ./chroot/tmp/filesystem.squashfs.temp
		) &
	fi
    fi

    if lb build ; then
        echo -e "Build is done: '$LBX2GO_TCEDIR'"
        ln $(realpath ./chroot/vmlinuz) ./x2go-tce-vmlinuz
        ln $(realpath ./chroot/initrd.img) ./x2go-tce-initrd.img
        ln ./binary/live/filesystem.squashfs ./x2go-tce-filesystem.squashfs

        if [ "$LBX2GO_IMAGETYPE" = "hdd" ] ; then
                ln ./live-image-$(echo $LBX2GO_ARCH | awk '{print $2}').img \
                   ./x2go-tce-live-image-$(echo $LBX2GO_ARCH | awk '{print $2}').img
        fi

        # This is part of our experimental ARM support
        if [ "$LBX2GO_IMAGETYPE" = "hdd" ] && echo $LBX2GO_ARCH | grep -q "arm" ; then
		# after the build, let's determine the name of our image file ...
		IMAGEFILE="./x2go-tce-live-image-$(echo $LBX2GO_ARCH | awk '{print $2}').img"

		# ... and change the partition type to reflect the file system actually in use for partition 1
		# ("b" is FAT32)
		sfdisk --part-type $IMAGEFILE 1 b

		# next, we need to patch two things inside the image, so we need to set up a loop device for it.
		FREELOOP=$(losetup -f) # note that this could become a TOCTOU issue if more than 1 process tries to use loop devices

		# as the image is a full disk image containing a partition, we need to jump to the position where the first partition starts
		losetup -o 1048576 $FREELOOP $IMAGEFILE

		# now let's mount it
		mkdir -p ./tempmount
		mount $FREELOOP ./tempmount

		# purge this dir, so we have enough space; we'll return to fill it later
		rm ./tempmount/live/*

		# first, we copy the contents of the boot/firmware/ folder to the root directory, because that is where these files are needed
		# see if inplace helps against out of space errors
		rsync -aP --inplace ./chroot/boot/firmware/* ./tempmount

		mkdir -p ./tempmount/live/
		rsync -aP ./binary/live/*.squashfs ./tempmount/live/

		# next, we replace the "root=" parameter with the parameters needed for live-booting
		sed -e 's#root=/dev/mmcblk0p2 #'"$LBX2GO_BOOTAPPEND_LIVE"' #' -i ./tempmount/cmdline.txt

		# here comes the cleanup part
		sync
		umount $FREELOOP
		losetup -d $FREELOOP
		rmdir ./tempmount
	fi

        if [ "$LBX2GO_IMAGETYPE" = "netboot" ] ; then
            if [ "$LBX2GO_NOSQUASHFS" = "true" ] ; then
                (cd binary; echo live$'\n'live/filesystem.squashfs |cpio -o -H newc | gzip --fast) >./x2go-tce-filesystem.cpio.gz
                cat ./x2go-tce-initrd.img ./x2go-tce-filesystem.cpio.gz >./x2go-tce-initrd-with-fs.img || exit 1
                rm ./x2go-tce-filesystem.cpio.gz
                # keeping these doesn't hurt, but feel free to rm them as well
                # rm ./x2go-tce-filesystem.squashfs ./x2go-tce-initrd.img
            fi
        fi
        if [ "$LBX2GO_IMAGETYPE" = "iso" ] || [ "$LBX2GO_IMAGETYPE" = "iso-hybrid" ] ; then
            genisoimage -o ./x2go-tce-squashfs-only.iso -R -J -graft-points live/filesystem.squashfs=./x2go-tce-filesystem.squashfs
            if [ -e ./live-image-$(echo $LBX2GO_ARCH | awk '{print $2}').hybrid.iso ] ; then
                    ln ./live-image-$(echo $LBX2GO_ARCH | awk '{print $2}').hybrid.iso \
                       ./original-x2go-tce-live-image-$(echo $LBX2GO_ARCH | awk '{print $2}').hybrid.iso
            elif [ -e ./live-image-$(echo $LBX2GO_ARCH | awk '{print $2}').iso ] ; then
                    ln ./live-image-$(echo $LBX2GO_ARCH | awk '{print $2}').iso \
                       ./original-x2go-tce-live-image-$(echo $LBX2GO_ARCH | awk '{print $2}').iso
            fi
            mv ./x2go-tce-filesystem.squashfs ./original-x2go-tce-filesystem.squashfs
        fi
        # create timestamp file
        stat -c %Y ./config/includes.chroot/lib >./x2go-tce-timestamp
        touch -m -d @$(cat x2go-tce-timestamp) x2go-tce-timestamp
        if [ "$LBX2GO_GETSRC" = "true" ] ; then
                if lb source debian ;
                then
                        echo -e "Source files have been downloaded: '$LBX2GO_TCEDIR'"
                else
                        echo -e "Source download failed: '$LBX2GO_TCEDIR'"
                fi
        else
                lb clean
                rm -rf ./cache
        fi
    else
        echo -e "Build failed: '$LBX2GO_TCEDIR'"
        if [ "$LBX2GO_IMAGETYPE" = "hdd" ] ; then
                echo "Looks like you tried to build an hdd image."
                echo "Older (pre-Debian-Buster) releases of live-build show a harmless error during"
                echo "the build, that can be safely ignored - but will still get you a 'Build failed'"
                echo "message in turn. So if you're running an older Debian release, you might want to"
                echo "look at the content of your build directory - maybe your build was successful"
                echo "after all, and this script was merely unable to detect it (computers are dumb)."
        fi
    fi
    cd ..
fi


</code>
===== Netbooting =====

==== Prerequisites ====
  * You need an existing DHCP/PXE/TFTP setup with the usual pxelinux.0/pxelinux.cfg boot and configuration files, and a directory where kernel and initrd can be stored.  This is not covered here, though we might add a separate howto for that some time later on.
    * Note that whoever manages to spoof this server name can deploy rogue images to your ThinClients.  If this is a serious issue for you, consider using local storage media and the autoupdater instead.
    * It **might** be possible to already use HTTPS in this early stage when using iPXE.  This is untested and requires building your own iPXE image. see http://ipxe.org/crypto for details. Alternatively, use ipxe.lkrn (from [[http://boot.ipxe.org/ipxe.lkrn]]) and pxelinux.0 in combination with scripted ipxe commands in the pxelinux.cfg.
  * You will also need an HTTP/HTTPS/FTP server with a dedicated IP (no name-based virtual hosts) for the squashfs image. - **Note:** set LBX2GO_NOSQUASHFS=true and use iPXE (e.g. with ipxe.lkrn + pxelinux.0) if you cannot use an IP for your host. Another option (untested) is explained [[https://blog.jacekk.info/2016/01/debian-live-webboot-dns/|here]]
    * This image cannot be deployed via TFTP as it is too large - some TFTP servers (atftpd in particular) refuse to serve files lager than 32MB, and some TFTP clients have problems with that as well.
    * Also, even if you have a TFTP server/client combination that handles files larger than 32 MB, it will still be waaaay slower than the HTTP/FTP transfer.
    * Note that whoever manages to spoof this server name can deploy rogue images to your ThinClients.  If this is a serious issue for you, consider using local storage media and the autoupdater instead.
    * It **might** be possible to use HTTPS with the ''fetch='' command.  This is untested.
  * Once your setup fulfills all the requirements listed above, go ahead and build the image using the scripts listed in [[doc:howto:tce#configuring_the_build|Configuring the Build]] - make sure to choose ''export LBX2GO_IMAGETYPE='netboot''' (this should be the default)

==== Setting up your own netbootable X2Go-TCE environment ====

=== Adding the X2Go-TCE files to your Boot and Web Server(s) ===

This is assuming you already have an existing, working PXE/TFTP and HTTP (with optional HTTPS) or FTP server setup.

Once you see the message "Build is done:", go to the directory mentioned there, and copy x2go-tce-vmlinuz and x2go-tce-initrd.img to a suitable subdirectory under your TFTP root.

We suggest using ./x2go-tce.

<note tip>To verify that both your installation in general and the newly copied files are reachable via TFTP, use a TFTP client - we suggest atftp - and perform these steps:
<code> cd $(mktemp -d)
 atftp your-tftp-server-ip-here
 tftp> get pxelinux.cfg/default
 tftp> get x2go-tce/x2go-tce-vmlinuz 
 tftp> get x2go-tce/x2go-tce-initrd.img 
 tftp> quit
</code>
</note>

Next, copy x2go-tce-filesystem.squashfs from the directory mentioned after "Build is done:"  to a suitable subdirectory under your HTTP, HTTPS, or FTP root.

We suggest using ./x2go-tce.

<note tip>To verify that both your installation in general and the newly copied file are reachable via HTTP, HTTPS, or FTP, use an HTTP/HTTPS/FTP client - we suggest wget - and perform these steps:
<code> cd $(mktemp -d)
wget -Y off http://your-http-server-ip-here/
wget -Y off http://your-http-server-ip-here/x2go-tce/x2go-tce-filesystem.squashfs
</code>
In case of an FTP URL, replace http with ftp in the example above. Same goes for https when trying to get that to work.

**Note that you MUST use an IP address. X2Go-TCE WILL NOT WORK with a DNS name, even though this test here will accept IPs and DNS names alike. The only exception is when a template actually spells out that you should input a DNS name.**
</note>

=== Adding the configuration files to your Boot Server ===
Again, this is assuming you already have an existing, working PXE/TFTP server setup.
  * change to the pxelinux.cfg directory in your tftproot.
  * create a file x2go-tce there, using the template below and adjusting it to your needs
  * read section [[doc:howto:tce#boot_parameters_for_x2go-tce|Boot Parameters for X2Go-TCE]] to find out what changes to make and what to put where it says FURTHER-OPTIONS-GO-HERE
<file - x2go-tce>
DEFAULT x2go-tce
PROMPT 0
MENU TITLE Linux Boot Menu
MENU COLOR TITLE 1 #ffffff #000000 std
MENU COLOR SEL 0 #ffffff #444444 std
MENU COLOR TABMSG 0 #999933 #000000 std
MENU COLOR UNSEL 0 #aaaaaa

LABEL x2go-tce
TIMEOUT 50
MENU LABEL X2Go-TCE
KERNEL x2go-tce/vmlinuz
APPEND initrd=x2go-tce/initrd.img boot=live components noswap aufs rd.luks=0 rd.lvm=0 rd.md=0 rd.dm=0 kernel.sysrq=1 keep_bootcon sysrq_always_enabled rd.driver.pre=loop rd.noverifyssl rd.skipfsck rd.live.overlay.check rd.live.overlay.reset rd.live.ram log_buf_len=1M quickreboot consoleblank=0 kernel.sysrq=1 keep_bootcon sysrq_always_enabled rootwait=120 silent quiet splash lang=de vconsole.keymap=de keyboard-layouts=de locales=de_DE.UTF-8 hostname=localhost noroot nouser fetch=http://your-http-server-ip-here/x2go-tce/x2go-tce-filesystem.squashfs FURTHER-OPTIONS-GO-HERE

</file>

=== Required unless using the X2Go Session Broker: Adding the x2go-tce.sessions session configuration file to your HTTP or FTP Server ===
Again, this is assuming you already have an existing, working HTTP or FTP server setup.
  * run X2GoClient on any computer you like, and configure a session the same way it should appear on the ThinClient
 <note tip>when using a Windows client, run x2goclient.exe --portable, or it will store the session information in the registry, rather than in a "sessions" file.</note>

  * locate the "sessions" file you just created - it should be at ~/.x2goclient/sessions
  * copy it to x2go-tce.sessions
  * using an editor of your choice, edit x2go-tce.sessions so it contains only the sessions you want to appear on the ThinClient, and none that might have been created earlier.
  * log on to your HTTP or FTP server and change to the x2go-tce directory in your webroot/ftproot.
  * copy the x2go-tce.sessions file with your desired configuration to this directory.

=== Optional: Adding the x2go-tce.authorized_keys keyfile to your HTTP or FTP Server ===
Again, this is assuming you already have an existing, working HTTP or FTP server setup.
  * locate your current authorized_keys file - it should be at ~/.ssh/authorized_keys
  * copy it to x2go-tce.authorized_keys
  * using an editor of your choice, edit x2go-tce.authorized_keys so it contains only the keys you want to appear on the ThinClient, and none that might have been created for a different purpose.
  * log on to your HTTP or FTP server and change to the x2go-tce directory in your webroot/ftproot.
  * copy the x2go-tce.authorized_keys file with your desired configuration to this directory.
  * make sure the file is chmodded 644, not 600


=== Optional: Adding the x2go-tce.xorg.conf file to your HTTP or FTP Server ===
Again, this is assuming you already have an existing, working HTTP or FTP server setup.
  * copy the xorg.conf file from the working system to x2go-tce.xorg.conf - actually, to something that lets you tell which hardware it is made for, like x2go-tce-P4-whitebox-with-crappy-VGA.xorg.conf
  * log on to your HTTP or FTP server and change to the x2go-tce directory in your webroot/ftproot.
  * copy the x2go-tce.xorg.conf file (or whatever you named it) with your desired configuration to this directory.

==== Final Steps to boot a ThinClient ====
=== To boot your first X2Go-TCE ThinClient ===
Again, this is assuming you already have an existing, working PXE/TFTP server setup in place.
  * Determine the MAC address of your ThinClient. In the following example, we will assume it is ''AA-BB-CC-DD-EE-FF''.
  * Change to the pxelinux.cfg directory in your tftproot.
  * create a symlink with the name ''01-AA-BB-CC-DD-EE-FF'' (note the extra "01-" at the beginning) pointing to x2go-tce.
  * After that, your ThinClient should boot the X2Go-TCE image.

=== To make the X2Go-TCE image the default and only boot image ===
  * Change to the pxelinux.cfg directory in your tftproot.
  * run ''ls -lah default''
  * Make a note where this symlink points to, if it is a symlink.
  * If it is not a symlink, but a regular file, rename it e.g. to ''default-before-x2go-tce''
  * create a new symlink named ''default'' that points to ''x2go-tce''

=== To create several configurations to accommodate varying hardware/use cases, but all booting the same basic image ===
  * Change to the pxelinux.cfg directory in your tftproot.
  * copy the file x2go-tce to an appropriate name, like x2go-tce-debug or x2go-tce-P4-whitebox-with-crappy-VGA
  * you can create as many such configuration files as you want, and edit them according to the use case
  * to make a particular client boot a particular configuration, 
    * Determine the MAC address of your ThinClient. In the following example, we will assume it is ''AA-BB-CC-DD-EE-FF''.
    * create a symlink with the name ''01-AA-BB-CC-DD-EE-FF'' (note the extra "01-" at the beginning) pointing to x2go-tce-whatever-name-you-chose.
    * After that, your ThinClient should boot the X2Go-TCE image.
    * Note that it is possible to use partial matching, so a symlink starting with "01-AA-BB-CC" would match all ThinClients with a MAC address starting with "AA-BB-CC" and so on.
    * For further matching options (IP-based, for example), please consult the pxeboot documentation. In short, it should be possible (i.e. untested by us), but it a) requires you to assign static DHCP IPs and b) you need to translate the IP to its hexadecimal value and use that value as the symlink name, so e.g. 192.168.0.1 becomes C0A80001 -> x2go-tce.

===== Booting from local storage media ===== 
This section explains how to create images for local storage media.

Basically, proceed as shown for netboot above, but set LBX2GO_IMAGETYPE to ''iso-hybrid'' (recommended) or ''iso''. 
Do **not** select hdd or tar - even though we are creating a local storage media installation.

  - On your local storage media, create the following folders: ''/boot/X2Go-live1'', ''/boot/X2Go-live2'', ''/boot/X2Go-live-download''.
  - If you have serious space constraints, you can limit yourself to ''/boot/X2Go-live1'', but you will be unable to use the autoupdater then.
  - Copy ''./x2go-tce-vmlinuz'', ''./x2go-tce-initrd.img'', and ''./x2go-tce-squashfs-only.iso'' to ''/boot/X2Go-live1/'' (and to ''/boot/X2Go-live2/'', if present).

==== Installing a boot loader ==== 
The next step is to install a boot loader.  Currently, there are three choices, GRUB-legacy, syslinux, and GRUB4DOS.
  * Use GRUB-legacy for ext* file systems.
  * Use syslinux when installing on FAT* file systems.  Should work with ext* file systems as well (using extlinux), if you don't want GRUB-legacy. 
  * Use GRUB4DOS when dealing with an NTFS file system (say, you're trying to turn an existing Windows XP installation into a ThinClient).
  * read section [[doc:howto:tce#boot_parameters_for_x2go-tce|Boot Parameters for X2Go-TCE]]  to find out what changes to make and what to put where it says FURTHER-OPTIONS-GO-HERE

<note important>
Note that GRUB-legacy (and possibly GRUB4DOS as well) has a limit of 256 characters for /proc/cmdline.
Current syslinux implementations double that value to 512 characters.
So if you're seeing issues like X2Go-TCE hanging at boot when it comes to downloading config files, or certain parameters being ignored, when you specify a lot of and/or long parameters, you can either go ahead and shorten file names and paths (e.g. use "vml" instead of "x2go-tce-vmlinuz" and "<nowiki>http://host/</nowiki>" instead of "<nowiki>http://host.example.com/</nowiki>", or switch to a different bootloader.

</note>

=== Installing GRUB-legacy ===
    * mount /dev/targetpartition to (mountpath)
    * create a folder ''(mountpath)/boot/grub'' 
    * install grub-legacy into it:
      * ''apt-get -y install grub-legacy'' # note this will remove grub2 from your system if it is installed, but will not cause any change to your boot sequence 
      * ''grub-install --recheck --root-directory=(mountpath) /dev/targetdevice'' # entire device, not partition
      * check, and, if required, edit the contents of ''(mountpath)/boot/grub/device.map''
      * if you had to make changes, re-run ''grub-install --root-directory=(mountpath) /dev/targetdevice'' # entire device, not partition
      * optional: ''apt-get -y install grub2'' # reinstall grub2 if that is what you were using before
      * create a boot loader configuration file using the following template:
<file - menu.lst>
# sample grub-legacy menu.lst for booting X2Go-TCE from local media
# Depending on your setup, this goes either into C:\menu.lst or C:\boot\grub\menu.lst, or /boot/grub/menu.lst.
# C:\menu.lst is recommended for NTFS, /boot/grub/menu.lst for ext*. 
# Make sure you do not have menu.lst files at both locations.

default 0

timeout         5
color cyan/blue white/blue
# This says "password" in md5
password --md5 $1$v4.0xYdG$32uzkKsup9c1RsHZlzfQs1

title           X2Go-live1
find            /boot/X2Go-live1/x2go-tce-vmlinuz
root
kernel          /boot/X2Go-live1/x2go-tce-vmlinuz boot=live components noswap aufs rd.luks=0 rd.lvm=0 rd.md=0 rd.dm=0 kernel.sysrq=1 keep_bootcon sysrq_always_enabled rd.driver.pre=loop rd.noverifyssl rd.skipfsck rd.live.overlay.check rd.live.overlay.reset rd.live.ram log_buf_len=1M quickreboot consoleblank=0 kernel.sysrq=1 keep_bootcon sysrq_always_enabled rootwait=120 lang=de vconsole.keymap=de keyboard-layouts=de locales=de_DE.UTF-8 hostname=localhost noroot nouser silent quiet splash findiso=/boot/X2Go-live1/x2go-tce-squashfs-only.iso FURTHER-OPTIONS-GO-HERE
initrd          /boot/X2Go-live1/x2go-tce-initrd.img

title           X2Go-live2
find            /boot/X2Go-live2/x2go-tce-vmlinuz
root
kernel          /boot/X2Go-live2/x2go-tce-vmlinuz boot=live components noswap aufs rd.luks=0 rd.lvm=0 rd.md=0 rd.dm=0 kernel.sysrq=1 keep_bootcon sysrq_always_enabled rd.driver.pre=loop rd.noverifyssl rd.skipfsck rd.live.overlay.check rd.live.overlay.reset rd.live.ram log_buf_len=1M quickreboot consoleblank=0 kernel.sysrq=1 keep_bootcon sysrq_always_enabled rootwait=120 lang=de vconsole.keymap=de keyboard-layouts=de locales=de_DE.UTF-8 hostname=localhost noroot nouser silent quiet splash findiso=/boot/X2Go-live2/x2go-tce-squashfs-only.iso FURTHER-OPTIONS-GO-HERE
initrd          /boot/X2Go-live2/x2go-tce-initrd.img

</file>

=== Installing syslinux ===

    * install syslinux and mbr: ''apt-get install -y syslinux mbr''
    * run ''syslinux --install /dev/targetpartition'' # if that fails or media won't boot, try ''syslinux -s --install /dev/targetpartition''
    * note that you have to mark /dev/targetpartition as "active" in the partition table. You can do that e.g. by calling ''sfdisk -A number-of-target-partition /dev/targetdevice''
    * if your system doesn't boot like that, it might be due to an empty Master Boot Record.  You can use ''install-mbr /dev/targetdisk'' to fix this.
    * for syslinux, use these three files as templates:
<file - syslinux.cfg>
menu title X2Go-TCE
# This says "password" in md5
menu master passwd $1$v4.0xYdG$32uzkKsup9c1RsHZlzfQs1
UI menu.c32
default X2Go-live1
prompt 0
timeout 50
include X2Go-live1.cfg
include X2Go-live2.cfg
</file>

<file - X2Go-live1.cfg>
label X2Go-live1
        menu label X2Go-Live^1
        menu default
        linux /boot/X2Go-live1/x2go-tce-vmlinuz
        initrd /boot/X2Go-live1/x2go-tce-initrd.img
        append boot=live components noswap aufs rd.luks=0 rd.lvm=0 rd.md=0 rd.dm=0 kernel.sysrq=1 keep_bootcon sysrq_always_enabled rd.driver.pre=loop rd.noverifyssl rd.skipfsck rd.live.overlay.check rd.live.overlay.reset rd.live.ram log_buf_len=1M quickreboot consoleblank=0 kernel.sysrq=1 keep_bootcon sysrq_always_enabled rootwait=120 lang=de vconsole.keymap=de keyboard-layouts=de locales=de_DE.UTF-8 hostname=localhost noroot nouser silent quiet splash findiso=/boot/X2Go-live1/x2go-tce-squashfs-only.iso FURTHER-OPTIONS-GO-HERE
</file>
<file - X2Go-live2.cfg>
label X2Go-live2
        menu label X2Go-Live^2
        menu default
        linux /boot/X2Go-live2/x2go-tce-vmlinuz
        initrd /boot/X2Go-live2/x2go-tce-initrd.img
        append boot=live components noswap aufs rd.luks=0 rd.lvm=0 rd.md=0 rd.dm=0 kernel.sysrq=1 keep_bootcon sysrq_always_enabled rd.driver.pre=loop rd.noverifyssl rd.skipfsck rd.live.overlay.check rd.live.overlay.reset rd.live.ram log_buf_len=1M quickreboot consoleblank=0 kernel.sysrq=1 keep_bootcon sysrq_always_enabled rootwait=120 lang=de vconsole.keymap=de keyboard-layouts=de locales=de_DE.UTF-8 hostname=localhost noroot nouser silent quiet splash findiso=/boot/X2Go-live2/x2go-tce-squashfs-only.iso FURTHER-OPTIONS-GO-HERE
</file>

=== Installing GRUB4DOS ===

Installing GRUB4DOS allows you to keep the original Windows bootloader installed.  The method below also allows you to write-mount the NTFS file system and thus to deploy updates using the autoupdater.
This is done by chainloading GRUB4DOS from the native Microsoft Windows Bootloader

  * download https://sourceforge.net/projects/grub4dos/files/GRUB4DOS/grub4dos%200.4.4/grub4dos-0.4.4.zip and unzip the contents to a temporary directory
  * copy GRLDR and GRLDR.mbr from the GRUB4DOS temporary directory into C:\
  * make the appropriate changes to activate the changes:
    * Note: These steps all require Administrator privileges.
    * For Windows XP, you need to edit ''C:\boot.ini''
      - ''attrib -r -h -s C:\boot.ini'' 
      - Edit ''C:\boot.ini'' and add an entry ''C:\grldr="Start ThinClient"'' somewhere below the section ''[operating systems]''
      - To make booting in ThinClient mode the default, in section ''[boot loader]'', change the line starting with ''default'' to ''default=C:\grldr''
      - ''attrib +r +h +s C:\boot.ini'' 
    * For Windows Vista and newer, run this script:
<file - insertgrub.cmd>
@echo off
setlocal
set BCDEDIT=%SYSTEM%\bcdedit.exe
if not exist %BCDEDIT% exit 1
for /f "tokens=3" %%A in ('%BCDEDIT% /create /d "PXE boot" /application bootsector') do set guid=%%A
%BCDEDIT% /set %guid% device partition=%SystemDrive%
%BCDEDIT% /set %guid% path \grldr.mbr

REM you can use /addfirst instead, if you want
%BCDEDIT% /displayorder %guid% /addlast

REM this sets a 5 second timeout until the default entry is booted
REM feel free to adjust to your needs, but NEVER set it to 0 or 1
REM in combination with using /default below unless you don't ever
REM intend to boot back into Windows again.
%BCDEDIT% /timeout 5

REM "bootsequence" means only the single, next reboot will default to this
%BCDEDIT% /bootsequence %guid% /addfirst

REM alternatively, you can uncomment this and make the ThinClient 
REM boot option the default boot option
REM %BCDEDIT% /default %guid%

endlocal

</file>

  * create the boot loader configuration file(s):
    * you can use the template for GRUB-Legacy from above, but in that case, you cannot use the autoupdate feature, as the boot partition will be locked in read-only mode.
    * to be able to use the autoupdater, use the template below
    * you must replace the xxx'es in the ''ntfs-uuid='' parameter with the Volume Serial Number listed in the output of ''vol c:'' (Windows command) or with the UUID from the output of ''blkid /dev/targetpartition'' 
    * 
<file - menu.lst>
# sample grub-legacy menu.lst for booting X2Go-TCE from NTFS-formatted local media
# Depending on your setup, this goes either into C:\menu.lst or C:\boot\grub\menu.lst.
# C:\menu.lst is recommended. 
# Make sure you do not have menu.lst files at both locations.

default 0

timeout         5
color cyan/blue white/blue
# This says "password" in md5
password --md5 $1$v4.0xYdG$32uzkKsup9c1RsHZlzfQs1

title           X2Go-live1
find            /boot/X2Go-live1/x2go-tce-vmlinuz
root
kernel          /boot/X2Go-live1/x2go-tce-vmlinuz boot=live components noswap aufs rd.luks=0 rd.lvm=0 rd.md=0 rd.dm=0 kernel.sysrq=1 keep_bootcon sysrq_always_enabled rd.driver.pre=loop rd.noverifyssl rd.skipfsck rd.live.overlay.check rd.live.overlay.reset rd.live.ram log_buf_len=1M quickreboot consoleblank=0 kernel.sysrq=1 keep_bootcon sysrq_always_enabled rootwait=120 lang=de vconsole.keymap=de keyboard-layouts=de locales=de_DE.UTF-8 hostname=localhost noroot nouser silent quiet splash findiso=/boot/X2Go-live1/x2go-tce-squashfs-only.iso toram ntfs-uuid=xxxxxxxxxxxxx FURTHER-OPTIONS-GO-HERE
initrd          /boot/X2Go-live1/x2go-tce-initrd.img

title           X2Go-live2
find            /boot/X2Go-live2/x2go-tce-vmlinuz
root
kernel          /boot/X2Go-live2/x2go-tce-vmlinuz boot=live components noswap aufs rd.luks=0 rd.lvm=0 rd.md=0 rd.dm=0 kernel.sysrq=1 keep_bootcon sysrq_always_enabled rd.driver.pre=loop rd.noverifyssl rd.skipfsck rd.live.overlay.check rd.live.overlay.reset rd.live.ram log_buf_len=1M quickreboot consoleblank=0 kernel.sysrq=1 keep_bootcon sysrq_always_enabled rootwait=120 lang=de vconsole.keymap=de keyboard-layouts=de locales=de_DE.UTF-8 hostname=localhost noroot nouser silent quiet splash findiso=/boot/X2Go-live2/x2go-tce-squashfs-only.iso toram ntfs-uuid=xxxxxxxxxxxxx FURTHER-OPTIONS-GO-HERE
initrd          /boot/X2Go-live2/x2go-tce-initrd.img

</file>

===== Booting from CD/DVD/USB =====

  - set the variables as shown in [[doc:howto:tce#configuring_the_build|Configuring the Build]]
  - after that, continue with ''export LBX2GO_IMAGETYPE="iso-hybrid"'' (recommended) or ''export LBX2GO_IMAGETYPE="iso"''. 
  - see [[doc:howto:tce#boot_parameters_for_x2go-tce|Boot Parameters for X2Go-TCE]] for a description of possible options, make your choices, add them where it says FURTHER-OPTIONS-GO-HERE and follow up with <code>
export LBX2GO_DEFAULTS+=" --bootappend-live boot=live components noswap aufs rd.luks=0 rd.lvm=0 rd.md=0 rd.dm=0 kernel.sysrq=1 keep_bootcon sysrq_always_enabled rd.driver.pre=loop rd.noverifyssl rd.skipfsck rd.live.overlay.check rd.live.overlay.reset rd.live.ram log_buf_len=1M quickreboot consoleblank=0 kernel.sysrq=1 keep_bootcon sysrq_always_enabled rootwait=120 silent quiet splash lang=de vconsole.keymap=de keyboard-layouts=de locales=de_DE.UTF-8 hostname=localhost noroot nouser live-media-path=live FURTHER-OPTIONS-GO-HERE
</code>
  - after that, you can [[doc:howto:tce#starting_the_build|Start the Build]].
  - if you actually intend to write the image to CD/DVD or USB media, the only file you need is located at ''./original-x2go-tce-live-image-i386.hybrid.iso'' after running the build script.
  - if the image fails to boot, check the file system - there should be a folder ''live'' containing a file ''filesystem.squashfs''. Adjust the value of ''live-media-path='' accordingly.
==== Burning to CD/DVD ====
Use ''xorriso -as cdrecord -v dev=/dev/your-writer-device -dao ./original-x2go-tce-live-image-i386.hybrid.iso'' or whatever cd burning software you like.  See https://wiki.debian.org/BurnCd for some additional suggestions.

==== Writing to USB media ====
When using iso-hybrid, this file can be dd'ed straight to USB media, no need to unpack, format, fiddle with a boot loader, etc.

So just do ''dd if=./original-x2go-tce-live-image-i386.hybrid.iso of=/dev/targetdevice'' and wait until it finishes.

Also, when using iso-hybrid and USB media, there are a few "cheats" to reclaim unused space on the USB media, and to turn it into a solution that allows you to run X2GoClient in portable mode on Windows, and boot it as X2Go-TCE, with a shared configuration file. 


===== Persistent SSH Host Keys =====
As there is no simple way to have individual, persistent SSH Host Keys per ThinClient, and sharing secret host keys across machines is a bad idea, too, the default behavior is to generate a new key pair upon boot. If you need to SSH into ThinClients often, this may soon become annoying.
Therefore, X2Go-TCE-Live comes with a script that, during the boot process, will scan for USB media and fixed disk media (with fixed disk media taking precedence, unlike the ''copysecring'' boot parameter that copies SSH //Client// Private Keys when set) for a directory ''config/sshdkeys''. The volume must be labeled ''X2GO-TCE-LIVE'' and may use any supported file system, though write support is required if you want to store the keys from within X2Go-TCE-Live. If you're booting from fixed disk media/internal flash, you may put the folder directly in the root directory of your boot drive - just don't forget to change the volume label to the "magic value" ''X2GO-TCE-LIVE''. If the directory exists, but is empty, all current SSH Host Keys will be copied into it (missing ones will be generated on the fly). Any SSH Host Keys found in the ''config/sshdkeys'' directory will be copied into ''/etc/ssh/'' (in the ramdisk), with proper permissions and ownerships for sshd, and sshd will be told to reload its config if required.

===== Boot Parameters for X2Go-TCE =====
<note important>**These are always required for security reasons, unless you are working on a debug image:**
  * ''noroot'' - do not allow the local user account on the ThinClient (named "user") to become root, e.g. using sudo **Always set this unless you are debugging an image and need to log in locally!**
  * ''nouser'' - do not allow the local user account on the ThinClient (named "user") to log in at the console or remotely (using password "live") **Always set this unless you are debugging an image and need to log in locally!**
</note>

==== Options already present in the templates that you may/should change to your needs ====
  * options ending in ''=de'' and ''=de_DE.UTF-8'' should be set to match your desired country/locale setting

<note tip>To have different hostnames for each thin client:
  * assign DNS names for your thin clients
  * set your DHCP server to reply to "request host-name" requests from dhclient
  * use ''hostname=localhost'' as shown above.

If you remove ''hostname=localhost'' entirely, all thin clients will share the hostname ''debian'', which is the Debian-Live default host name.  Similarly, if you set ''hostname=someothervalue'', all thin clients booting this configuration will share the hostname ''someothervalue''.
</note>

==== What options are available under FURTHER-OPTIONS-GO-HERE? ====
  * Where it says FURTHER-OPTIONS-GO-HERE, you can (must!) add one or more of the options explained below. All options are separated from the next option using a single blank (space bar), just like the options before that placeholder. **DO NOT** use newlines. All "APPEND" options must be on **one and the same** line.
  * Options containing "tftp|rsync|https|http|ftp://your-http-server-ip-here" should be replaced with the proper HTTP, HTTPS, FTP, or, where mentioned as an alternative, TFTP or rsync URL for your server. HTTPS is always preferred for security reasons. Be sure to use only the IP, not a DNS name.
  * Options containing "tftp|rsync|https|http|ftp://your-http-server-ip-or-dns-here" should be replaced with the proper HTTP, HTTPS, FTP, or, where mentioned as an alternative, TFTP or rsync URL for your server. HTTPS is always preferred for security reasons. IP or DNS name may be used.

=== These two are mutually exclusive, i.e. never put both of them in the same config ===
  * ''broker-url=ssh:<nowiki>//</nowiki>your-broker-address-here'' - this allows you to specify an X2Go Session Broker instead of a sessions file (not limited to an ssh-based broker, works with an http-based broker as well)
  * ''sessionsurl=https|http|ftp://your-http-server-ip-or-dns-here/x2go-tce/x2go-tce.sessions'' - use this to specify a sessions file. You need this unless you are using a session broker. See below for how to add this file to your HTTP, HTTPS, or FTP server.  **Attention: Whoever manages to spoof the server name can inject rogue session config files into your ThinClients.**  To mitigate this risk, use HTTPS, where the attacker would have to spoof both server name and matching certificate.

=== These are entirely optional ===
  * ''audioout=list'' / ''audioout="alsa_card.something|output:something"'' - use this to list all available audio outputs / select a particular audio output. Note that when selecting one, the parameter consists of two values (as displayed in the output on /dev/tty8 when specifying ''list'') that need to be separated with a ''|'', and the set of the two values needs to be enclosed in double quotes. Do //not// enclose each value in double quotes separately! Correct example: ''audioout="alsa_card.pci-0000_00_1b.0|output:hdmi-stereo"''
  * ''bg=https|http|ftp://your-http-server-ip-or-dns-here/x2go-tce/x2go-tce-bg.svg'' - use this to specify an SVG file to "brand" your X2Go-TCE with. It will replace the blue background theme of the login screen. See below for how to add this file to your HTTP, HTTPS, or FTP server.  **Attention: Whoever manages to spoof the server name can inject rogue images into your ThinClients.** To mitigate this risk, use HTTPS, where the attacker would have to spoof both server name and matching certificate.
  * ''blank=n|n:n:n'' - Will disable (''blank=0'') or set screensaver timeout. Use ''blank=n:n:n'' to set DPMS Standby/Suspend/Off values. Standby value equals screensaver timeout value. All values are given in seconds.
  * ''blankdpmsfix'' - This forces the TFT to black for a few seconds during the X startup phase, then forces it back on again.  This fixes an occasional "black screen" issue that occurs with some flaky client/TFT hardware combinations when using DisplayPort connectors, and could otherwise only be remediated by manually turning the TFT off and back on again. (feature available via github repo, soon via x2go repo too)
  * ''branding=https|http|ftp://your-http-server-ip-or-dns-here/x2go-tce/x2go-tce-branding.svg'' - use this to specify an SVG file to "brand" your X2Go-TCE with. It will replace the seal icon in the lower left of the login screen. See below for how to add this file to your HTTP, HTTPS, or FTP server.  **Attention: Whoever manages to spoof the server name can inject rogue images into your ThinClients.**  To mitigate this risk, use HTTPS, where the attacker would have to spoof both server name and matching certificate.
  * ''copysecring'' - this will scan for USB media and fixed disk media (with USB media taking precedence) at boot for one or more of the following directories: ''config/ssh'', 'ssh', ''.ssh''. The volume must be labeled ''X2GO-TCE-LIVE'' or ''PORTABLEAPP'' and may use any supported file system. Any SSH Secret Keys found there will be copied into ''/home/user/.ssh'' (in the ramdisk), with proper permissions and ownerships for the default user account. This may come in handy when you are using SSH Secret Keys on USB media, but need to log in and out of sessions often, and don't want to leave the USB media plugged in all the time/don't want to have to re-insert it before each session startup. **Attention: This poses a security risk when other people are using your ThinClient afterwards (as they will have access to your keys).**  To mitigate this risk,be sure to power-cycle the ThinClient once you are done. You //should// specify this parameter when booting X2Go-TCE-Live from portable media when you want to use SSH Secret Keys, to make sure your secret key on the FAT/NTFS partition is available. But as stated above, be sure to power-cycle the machine once you're done.
  * ''earlyblankdpmsfix'' - This forces the TFT do black for a few seconds during the initial boot phase (right after the squashfs was downloaded), then forces it back on again.  This fixes an occasional "black screen" issue that occurs with some flaky client/TFT hardware combinations when using DisplayPort connectors, and could otherwise only be remediated by manually turning the TFT off and back on again. Earlyblankdpmsfix can also be called as ''earlyblankdpmsfix=nnnn'', where ''nnnn'' is the blanking time in milliseconds (so, ''earlyblankdpmsfix=1500'' equals 1.5 seconds). (feature available via github repo, soon via x2go repo too)
  * ''homepageurl="URL1[|URL2|URLn]"'' - this is only available in MiniDesktop mode. It allows you to specify one or more web pages that show up on Browser start/when clicking the "Home" icon. URLs need to be separated with a ''|'', and the set of URLs needs to be enclosed in double quotes. Do //not// enclose each URL in double quotes separately! Correct example: ''homepageurl="https://www.google.de|https://wiki.x2go.org"''
  * ''initrdblankdpmsfix'' is the same as ''earlyblankdpmsfix'', only that it activates in the initial ramdisk already. Like ''earlyblankdpmsfix'', it can also be called as ''initrdblankdpmsfix=nnnn''.  This parameter is useful if you are affected by the //black screen at boot// issue, and you are not combining squashfs and initrd into one file when netbooting. (feature available via github repo, soon via x2go repo too)
  * ''ldap=ldap.example.com:389:cn=cngoeshere,dc=example,dc=com'' - this allows you to specify an LDAP server to connect to - note that this is not needed for LDAP-based authentication, only when you intend to store entire session profiles in LDAP. You should really consider using the X2Go Session Broker instead.
  * ''ldap1=ldap-backupserver-1.example.com:389'' - this allows you to specify the first of up to two LDAP backup servers when using LDAP authentication
  * ''ldap2=ldap-backupserver-2.example.com:389'' - this allows you to specify the second of up to two LDAP backup servers when using LDAP authentication 
  * ''nodpms'' - Will not touch DPMS settings at all (by default, ''blank=0'' does both ''xset s off'' and ''xset -dpms''). Use this along with ''blank=n'' if you do want to blank the screen, but your screen is confused by DPMS settings.
  * ''nomagicpixel=1'' or ''nomagicpixel=2'' - you should set ''nomagicpixel=1'' while the "magic pixel" (clicking in the upper right corner of the screen will minimize a fullscreen session) is still active in thinclient mode (this feature is expected to be disabled at some point in the future). ''nomagicpixel=1'' will disable the window manager when exactly 3 windows are detected (that's the usual situation when a fullscreen session is active). It will re-enable openbox whenever more or less than 3 windows are detected. If this fails for you, you can try ''nomagicpixel=2'', which will try to trigger on the window-minimize command and restore it to fullscreen (this will cause a short screen flickering effect). Note that ''nomagicpixel=2'' will make your ThinClient unusable when trying to run the actual X2Go-TCE client as a virtual machine guest (the //X2GoServer// you connect to may be a VM guest, no problems there). To live with the magic pixel bug, simply do not add this option at all.
  * ''ntp="server1 server2 ... servern"'' - this allows you to specify your own NTP server.  If this parameter is not used, time will be synced with standard Debian NTP servers.  To disable NTP syncing entirely, use ''ntp=false'' (feature available via github repo, soon via x2go repo too)
  * ''pavol=[n:]volume%[|[n:]volume% ...]'' - Allows you to set default volume levels for one or more audio output devices. ''pavol=50%'' will set the default audio output device (#0) to 50%. ''pavol=1:99%'' will set audio output device #1 to 99%. ''pavol="0:50%|1:99%"'' will set audio output device #0 to 50%, and audio output device #1 to 99%. Note that this opion only makes sense in MATE-MiniDesktop mode, as regular TCE sessions get their volume levels restored from the host they connect to. (''pavol'' feature available via github repo, soon via x2go repo too).
  * ''pubkey=tftp|http|https|ftp://your-http-server-ip-or-dns-here/x2go-tce/x2go-tce.authorized_keys'' - Allows you to add an ssh public key file to the ThinClient, so your administrators can log in remotely using SSH. Note that this file needs to be chmodded 644, not 600, on the web server.  **Attention: Whoever manages to spoof this server name will have root access to your ThinClients.** Using HTTPS will mitigate this - an attacker would not only have to spoof the server name, but also the matching certificate.
  *  ''session=sessionname'' - use this to specify a session by name that should be pre-selected on startup. The name must be listed in the sessions file and may only contain characters from the following charset: //a-zA-Z0-9.:/ _-// (We suggest naming the default session ''default'' and using ''session=default''.) When using a session name with blanks, please enclose the sessionname in either single or double quotes, like so: ''session="session name"'' / ''session='session name'''
  * ''tcedebug'' - this switches X2GoClient into debug mode and will also lead to increased logging to /var/log/x2goclient and to tty9
  * ''tcpprint'' - Will allow you to use local LPT/USB printers like "dumb" network printers (listening to port 9100 and above). Requires MAC->IP mapping in DHCP server (and optionally, DNS->IP mapping), or static IPs - else your print jobs will end up on random devices. This setup is preferred over the X2GoClient's built-in printing for locally attached printers if X2GoServer and ThinClients are on the same network. It is not recommended when your X2Go connection goes across the internet or when the ThinClient is actually a laptop roaming between different networks. **Attention: When used without ''tcpprintonlyfrom'' (see below), this means anyone that can reach your thin client via e.g. ping can also send print jobs to it!**  
  * ''tcpprintonlyfrom=x.x.x.x'' - Will allow you to specify which IP address may connect to Port 9100 and above for printing to a locally attached LPT/USB printer. This should be the IP of your CUPS server or whatever print server system you use.  Understands the same syntax as ''xinetd'''s ''only_from''. 
  * ''throttle=n|n:n:n:n:n'' - Will throttle down- and upload speed (''throttle=n'') or set throttling limits as follows: download:upload:smoothingtime:smoothinglength:latency. Defaults for up- and download are 10 (KiloBytes/s), 3.0 (seconds, using decimals is permitted) smoothingtime, 20 (KiloBytes), 0 (ms). for a detailed description of these parameters, see "man trickle". You can use the first 1, 2, 3, 4 or all 5 parameters. To set down- and/or upload speed to unlimited, use the letter "u" instead of a numeric value.
  * ''timezone=TIMEZONE'' - can be used to define a timezone other than UTC, e.g. 'Europe/Berlin'. This especially makes sense for MATE-MiniDesktop, but is nice to have in regular TCE-Live as well, because the timestamp of the log messages will show the local time instead of UTC. This is a standard parameter of live-boot, and not specific to X2Go.
  * ''windowwidth=[n-nnn]'' - this is only available in MiniDesktop mode. It allows you to set the width of the X2GoClient login window (which gets moved and resized to the right side of your screen during session startup) to any value between 0 and 100. Note that widths smaller than 30 are not recommended and may cause further resizing once the session starts.
  * ''x3270servers="host[:port][|host[:port]...]"'' - this is only available in MiniDesktop mode. It allows you to specify one or more hosts (with optional ports) for x3270 terminal emulation sessions that will be created as desktop shortcuts on the thinclient. For a default 3270 connection, the port is 23 (telnet) and does not need to be specified. For an SSL-encrypted connection (recommended), the port is 992. Hosts may be IP addresses or DNS names, and need to be separated with a ''|''. (feature available via github repo, soon via x2go repo too)
  * ''x5250servers="host[:port][|host[:port]...]"'' - this is only available in MiniDesktop mode. It allows you to specify one or more hosts (with optional ports) for x5250 terminal emulation sessions that will be created as desktop shortcuts on the thinclient. For a default 5250 connection, the port is 23 (telnet) and does not need to be specified. For an SSL-encrypted connection (recommended), the port is 992. Hosts may be IP addresses or DNS names, and need to be separated with a ''|''. Note that x5250 support is currently not part of the standard image available via git, as there is no x5250 executable in Debian. You can try using x3270 instead, most modern IBM i (System i, iSeries, AS/400) systems support 3270-type connections as well. If you need native 5250 support, say, with a commercial, closed-source 5250 terminal emulator, please leave a message on the X2Go-User Mailing List and we'll tell you if and how you can integrate that into your build. (feature available via github repo, soon via x2go repo too)
  * ''xinerama=left-of|right-of|above|below|same-as'' - Allows you to specify how multiple screens are handled (same-as clones the primary screen to all secondary screens, the other commands will cascade and thus expand the screen). Note that the current implementation will enforce "same-as" if it detects a touch screen driver (wacom) and no other pointing device. This is so you won't get stuck being unable to log off, for example, due to your touch device being limited to one screen.
  * ''xorg-driver=DRIVERNAME'' - will skip graphics driver autodetection and force the specified driver instead. This is a standard parameter of live-boot, and not specific to X2Go.
  * ''xorg-resolution=HRESxVRES'' - will force the horizontal resolution to HRES and the vertical resolution to VRES, e.g. ''xorg-resolution=1280x1024'', useful if autodetection for the correct screen size fails, but you do get as far as seeing the X2Go GUI. This is a standard parameter of live-boot, and not specific to X2Go.
  * ''xorgconfurl=tftp|http|https|ftp://your-http-server-ip-or-dns-here/x2go-tce/x2go-tce.xorg.conf'' - when a client outright refuses to boot into the graphical X2Go login screen, but gets stuck at the console or a black screen instead, yet you can get the GUI to work using a regular Linux on the same hardware, you can disable the X Server's autodetection and force it to use the xorg.conf specified here.  Note that you should use a more descriptive name for the file, as described below. **Attention: Whoever manages to spoof the server name can inject rogue xorg config files into your ThinClients.**  To mitigate this risk, use HTTPS, where the attacker would have to spoof both server name and matching certificate.
  * ''xroot=[0xaabbcc|URI1[|URI2|...]]'' - can be used to set a local desktop background image or color (in hex format, with leading 0x, not leading #). On the main screen, this is only visible during startup, while additional screens will display whatever is set for them when there is no active session. The background also becomes visible for a short moment when the optional local screensaver activates or deactivates. Specifying more than one image will cause the first image to show up on the first screen, the second image on the second screen, and so on (feature available via github repo, soon via x2go repo too).
  * ''xrootmode=center|fill|scale|tile'' can be used to determine how the local desktop background image(s) should be positioned. If the parameter has been set, but something is wrong, it will default to a //grey mesh// background. (feature available via github repo, soon via x2go repo too). (feature available via github repo, soon via x2go repo too)
  * ''xsaveridletime=n'' - this value determines how long the screen should have been idle before the local slideshow screensaver sets in (value given in seconds). We recommend using 60 seconds less than for the server-sided, locking screensaver. (feature available via github repo, soon via x2go repo too)
  * ''xsaverimages=[URI1[|URI2|...]]'' - if you want a local, non-locking slideshow screensaver, you can specify image URLs here. These Images will be downloaded once, at boot. That way, one can display a slideshow without having to push the images across the network every time. Especially for slow links, this is the recommended way of running a slideshow screensaver. For security, combine this with a locking screensaver on the server with only one slide or a black background. (feature available via github repo, soon via x2go repo too)
  * ''xsaverimgtime=n'' - this determines how long each slide of the local, non-locking screensaver will be shown. (feature available via github repo, soon via x2go repo too)
=== These are only intended to be used with TCE images stored on local media ===
  * ''bwlimit=nnn'' - Will allow you to specify a bandwidth limit (valid values: 1-100) in percent for the backgrounded update task.
  * ''ntfs-uuid='' - Will be required for updating images stored on NTFS filesystems. Full UUID as shown under /dev/disk/by-uuid/ is preferred, but can work with the volume serial number shown in the output of "vol c:" as well.
  * ''updatesleep=nnnnn'' - Will allow you to specify the upper limit (in seconds) of the update timer's randomizer.  Allowed range for upper limit: 240-32767. Will default to 900 if unset or set to an out-of-range value. Lower limit is fixed at 120 seconds.
  * ''updateurl=rsync|https|http|ftp://your-http-server-ip-or-dns-here/path-to-update-files'' - Will allow you to update an image in the background when using local storage instead of PXE. Download task will start at a randomized interval to avoid unintentional dDOSing of the update server/network infrastructure. The updater will even work when using NTFS for local storage, but only if the //toram// boot option is used. Regardless of NTFS or not, the updater requires three directories: ''/boot/X2Go-live1, /boot/X2Go-live2, /boot/X2Go-live-download''. **Attention: Whoever manages to spoof the server name can deploy rogue images to your ThinClients.**  Even though it is slower, using an HTTPS web server is the safer way of doing this. Be sure that your web server delivers a last-modified header for all files. 

===== Client Branding/Theming using SVGs =====
It is possible to make X2Go-TCE-Live match your Corporate Design/Corporate Identity, using the "background" and "branding" parameters.
This is actually a feature of X2GoClient itself, so it will also work on //fat client// installations, and even on Windows and macOS.

{{:wiki:advanced:x2goclientdefaultbranding.png?400|Before ...}} {{:wiki:advanced:x2goclientbranding.png?400| ... and after.}}

You can find a more detailed explanation in the [[wiki:advanced:branding-theming|corresponding X2Go Wiki page]].
===== Querying X2Go-TCE version info ===== 
images built using the https://github.com/LinuxHaus/live-build-x2go::feature/openbox repository/branch after 2017-07-27 10:50 UTC will create a file ''/var/run/x2go-timestamps''.

A command like <code>ssh -A root@ThinClientIPorDNS 'cat /var/run/x2go-tce-timestamps'</code>

will return a result like
<code>
--- BEGIN TIMESTAMPS ---
1501164001;X2Go-live1;X
1501160716;X2Go-live2;
---- END TIMESTAMPS ----
</code>
Which you can parse using grep, awk, and/or perl, for example.

The first field is the version number, the second field is the name of the instance, the third field, if set, indicates that this is the running instance.

"Tell me the version number of the currently running instance" could thus be queried like:
<code>ssh -A root@ThinClientIPorDNS 'cat /var/run/x2go-tce-timestamps' | awk -F ';' '$3 == "X" { print $1 }'</code>

This value can then be compared to the output of <code>curl http(s)://YourUpdateServerIPorDNS/path/to/image/x2go-tce-timestamp</code>

-> If the number the curl command returns is higher than the one returned by the ssh command, the ThinClient is running an older version of X2Go-TCE and should be marked as requiring an update in whatever monitoring software you use. 

-> This feature doesn't really make sense when you're netbooting, so it is only enabled when an ''updateurl='' boot parameter is present - for local installations and writable portable media, it will help you keep track of update rollout status.

<note>Note that you will have to provide an SSH public key using the ''pubkey='' boot parameter for this to work.</note>

===== Troubleshooting a booted X2Go-TCE image ===== 

==== You can see the X2Go login screen, but the screen size (resolution) is wrong ====
Determine the correct resolution for your screen and set boot parameter ''xorg-resolution=HRESxVRES'' accordingly, e.g. to ''xorg-resolution=1280x1024''


==== The screen is entirely black (though you might notice an illuminated backlight in case of a TFT) ====

If the screen is entirely black, try pressing [Ctrl]+[Alt]+[F1] and see if that takes you to the text login screen.

==== You can see a text login screen with grey/white, green, and possibly red letters against a black background ====

If you end up at the text login, this means the X Server's autodetection failed.  There's not much you can do from inside X2Go-TCE at this point.  Make a note of the MAC address (the GREEN text), shut down the ThinClient and try to boot a different Linux distribution on it.  Try, for example, KNOPPIX Live Linux, other Distribution's Live Images (a recent Fedora or Arch, maybe?).

If you can get X running in one of these, proceed as follows:

In the running Linux where you have a working X Server on that particular hardware:
  * change to a command shell
  * try to run ''<nowiki>Xorg :$(($(ps -C Xorg -o args= | awk ' $2 ~ /^:[0-9]/ { print $2 }' | tr -d ':' | sort -n)+1)) -configure</nowiki>''
  * if that fails, stop the currently running X server, then run ''Xorg -configure''
  * this should output ~/xorg.conf.new, which could then be saved somewhere else (LAN share, USB media, ...).
  * once saved, shut down the ThinClient again.

Next steps:
  * rename the saved xorg.conf.new to x2go-tce.xorg.conf.name-of-your-stubborn-hardware and place it in the x2go-tce directory of the tftp|http|https|ftp server you use to deploy your images.
  * When using netbooting, do the following on your PXE/TFTP Server
    * create a separate configuration file "name-of-your-stubborn-hardware" for this hardware, based on the default file, 
    * create a symlink matching "01-", followed by the first three out of the six bytes of your hardware address, each separated by "-" (say, 01-AA-BB-CC when the full MAC was shown as AA:BB:CC:DD:EE:FF), that points to the file "name-of-your-stubborn-hardware".
  * In your boot configuration file (either "name-of-your-stubborn-hardware", when using netbooting, or menu.lst, when using local or USB storage media and grub-legacy, or X2Go-live1.cfg/X2Go-live2.cfg, when using local or USB storage media and syslinux), add the boot parameter ''xorgconfurl=tftp|http|https|ftp://your-http-server-ip-here/x2go-tce/x2go-tce.xorg.conf.name-of-your-stubborn-hardware''

==== The session itself works fine, but Audio is not working ====

First, check that the audio isn't simply muted (some cards/setups do this by default). Run ''pavucontrol'' inside the X2Go session. Check the settings on the tabs //Output Devices// and //Configuration//.  If that is the case, you probably need to create a script on the server that raises the volume/toggles the mute setting upon user login.

If that doesn't help, please boot with additional boot parameter ''audioout=list'' and look at the output on /dev/tty8 (Hit Ctrl+Alt+F8) - it will give you a list of available audio output devices.  This list also gets written to ''/tmp/audiolog'' on the ThinClient.

You might have to pick a different one from the list, by using boot parameter ''audioout='' with a particular card/output value, like: ''audioout=“alsa_card.pci-0000_00_1b.0|output:hdmi-stereo”'' (you need to copy the proper value from the list generated on your particular thinclient).

If you need different settings for different manufacturers, you can try to tell them apart by MAC address and set separate pxe boot configuration files for them.

===== Support Tools available in X2Go-TCE =====

==== Remote Access to the ThinClient's local display (before any connection is made) ==== 
X2Go-TCE comes with x11vnc installed.
If you want to see what's on the ThinClient's X11 screen, before a server connection has been established, proceed as follows:
  * On Linux/macOS/Unix:
    - spawn a VNC listening //client//, like so: ''xvncviewer -listen 5500''
    - run ''ssh -R 5500:localhost:5500 root@thinclient 'x11vnc -display :0 -rfbport 0 -coe localhost'''
  * On Windows:
    - Start a VNC listening //client//, for example ''vncclient.exe -listen 5500''
    - Start PuTTY, connect to root@thinclient
    - Select Connections/SSH/Tunnels in PuTTY
    - Enter Source Port 5500, Destination localhost:5500, Remote, Auto, and, very important, hit **Add** //before// you hit **Apply**, or your changes will **not** be saved
    - run ''x11vnc -display :0 -rfbport 0 -coe localhost'' in the PuTTY window
To see what a user is doing once a connection has been established, connect to the X2GoServer yourself and use X2Go's built-in Desktop Sharing (session shadowing). Install package ''x2godesktopsharing'' on the server, if you haven't done so already - this will deliver way better performance. See below for more.

==== Remote Access to the ThinClient's running X2Go Session ==== 
Please see the [[doc:usage:desktop-sharing|Desktop Sharing (session shadowing)]] HowTo for details.

==== Determining the ThinClient's IP and/or MAC when there is no network connection ==== 

When you are unable to connect to the ThinClient, you might want to ascertain its MAC and/or IP address(es), to make sure you and the user you are trying to support are talking about the same machine.  Tell the user to press [Ctrl]+[Alt]+[F1] and to read out
  * the GREEN text if you want to know the MAC address(es)
  * the RED text if you want to know the IP address(es) - if there is no red text, it means that the client was unable to acquire a DHCP lease.  Check cabling.
To return to the login screen, have the user press [Ctrl]+[Alt]+[F7] ([Alt]+[F7] should work, too), or, once you've successfully logged in over the network, issue the ''chvt 7'' command.


==== Checking the ThinClient's local printer setup (when using the ''tcpprint'' boot parameter) ====
There are several ways to check whether a ThinClient has detected any local printers:

  * Assuming you have remote access to the ThinClient, run ''ls -lah /etc/xinetd.d/jetdirect*'' and examine the files listed there.
  * When connected remotely, you can also look at the messages printed during the local printer setup phase, by running ''cat /dev/vcs9'' (you might have to pipe it through ''less'' to see the entire screen).
  * If you do not have remote access, tell the user to press [Ctrl]+[Alt]+[F9] and to read out what's on the screen.  To return to the login screen, have the user press [Ctrl]+[Alt]+[F7] ([Alt]+[F7] should work, too), or, once you've successfully logged in over the network, issue the ''chvt 7'' command.

==== Checking the ThinClient's update status (when using local storage) ====
There are several ways to check a ThinClient's update status:

  * Assuming you have remote access to the ThinClient, look at the messages printed during the update phase, by running ''cat /dev/vcs10'' (you might have to pipe it through ''less'' to see the entire screen) when connected remotely
  * If you do not have remote access, tell the user to press [Ctrl]+[Alt]+[F10] and to read out what's on the screen, preferably starting with the bottom line and continuing upward.  To return to the login screen, have the user press [Ctrl]+[Alt]+[F7] ([Alt]+[F7] should work, too), or, once you've successfully logged in over the network, issue the ''chvt 7'' command.

--------------------------------------------------------
===== List of open ToDos/FIXMEs for this page ===== 

FIXME This page is missing a section/subpage that explains how to use the content of the tar file located in the build directory **if no PXE/TFTP/HTTP server is present** yet.

Basically, debian-live/live/filesystem.squashfs becomes (webroot)/x2go-tce/x2go-tce-filesystem.squashfs and everything from tftpboot/ goes into the TFTP root directory. After that, one should proceed as described above regarding creation of files and symlinks.

Sample contents of live-image-i386.netboot.tar:
<code>
drwxr-xr-x root/root         0 2016-12-15 23:46 debian-live/
drwxr-xr-x root/root         0 2016-12-15 23:54 debian-live/live/
-rw-r--r-- root/root 271536128 2016-12-15 23:50 debian-live/live/filesystem.squashfs
-rw-r--r-- root/root     11579 2016-12-15 23:52 debian-live/live/filesystem.packages
-rw-r--r-- root/root        74 2016-12-15 23:52 debian-live/live/filesystem.packages-remove
drwxr-xr-x root/root         0 2016-12-15 23:54 tftpboot/
drwxr-xr-x root/root         0 2016-12-15 23:54 tftpboot/live/
-rw-r--r-- root/root  31942749 2016-12-15 23:52 tftpboot/live/initrd.img
-rw-r--r-- root/root   2831760 2016-12-15 23:52 tftpboot/live/vmlinuz
drwxr-xr-x root/root         0 2015-04-28 14:01 tftpboot/pxelinux.cfg/
-rw-r--r-- root/root        57 2014-10-25 14:21 tftpboot/pxelinux.cfg/default
-rw-r--r-- root/root       351 2016-12-15 23:54 tftpboot/live.cfg
-rw-r--r-- root/root    116624 2015-08-19 15:17 tftpboot/ldlinux.c32
-rw-r--r-- root/root       270 2016-12-15 23:54 tftpboot/menu.cfg
-rw-r--r-- root/root     26188 2015-08-19 15:17 tftpboot/vesamenu.c32
-rw-r--r-- root/root       268 2016-12-15 23:54 tftpboot/install.cfg
-rw-r--r-- root/root       508 2016-12-15 23:54 tftpboot/stdmenu.cfg
-rw-r--r-- root/root     34739 2016-12-15 23:54 tftpboot/splash.png
-rw-r--r-- root/root     23480 2015-08-19 15:17 tftpboot/libutil.c32
-rw-r--r-- root/root       153 2016-12-15 23:54 tftpboot/advanced.cfg
-rw-r--r-- root/root    182552 2015-08-19 15:17 tftpboot/libcom32.c32
-rw-r--r-- root/root     42988 2015-08-19 15:17 tftpboot/pxelinux.0
-rw-r--r-- root/root    164096 2015-08-19 15:17 tftpboot/hdt.c32
</code>

FIXME This page is missing a section/subpage that explains how to speed up the netboot process using iPXE.

Basically:
<code>
apt-get install ipxe
cd /your-tftp-root
mkdir -p {bios,uefi}
ln -s /usr/lib/ipxe/undionly.kpxe ./bios/
ln -s /boot/ipxe.efi ./uefi/
FQDN=DNS-name-of-your-server-here
IP_OF_FQDN=`dig $FQDN +short`
cat <<EOF>x2go-tce-ipxe
#!ipxe
dhcp
kernel http://$FQDN/x2go-tce-vmlinuz EVERYTHING-FROM-THE-LINE-STARTING-WITH-APPEND-IN-THE-X2GO-TCE-SAMPLE-FILE-ABOVE
initrd http://$FQDN/x2go-tce-initrd.img
boot
EOF
</code>

After that, create a symlink/symlinks that point(s) from "default" or a part of the MAC or the entire MAC, or the UUID, or the hex-encoded IP to x2go-tce-ipxe.

Then **add** this to your dhcpd.conf
<code>
   if substring ( option vendor-class-identifier , 19,1 ) = "0" {
           filename "bios/undionly.kpxe";
   }
   else if substring ( option vendor-class-identifier , 19,1 ) = "7" {
           filename "uefi/ipxe.efi";
   }
   else {  
           log (info, concat ( "Unhandled vendor class Arch: ", substring ( option vendor-class-identifier , 19,1 )));
   }
   if exists user-class and option user-class = "iPXE" {
	set hwmac = concat (
	suffix (concat ("0", binary-to-ascii (16, 8, "", substring(hardware,1,1))),2), ":",
	suffix (concat ("0", binary-to-ascii (16, 8, "", substring(hardware,2,1))),2), ":",
	suffix (concat ("0", binary-to-ascii (16, 8, "", substring(hardware,3,1))),2), ":",
	suffix (concat ("0", binary-to-ascii (16, 8, "", substring(hardware,4,1))),2), ":",
	suffix (concat ("0", binary-to-ascii (16, 8, "", substring(hardware,5,1))),2), ":",
	suffix (concat ("0", binary-to-ascii (16, 8, "", substring(hardware,6,1))),2)
	);

      filename = concat( "http://DNS-name-of-your-server-here/", hwmac );
   }
</code>

FIXME Document how to add second partition to USB media after dd'ing the iso-hybrid image, and how to add X2GoClient-Portable to it.

  * The catch is that on USB media, Windows (except for Windows 10 Creators Update and newer) will only see the partition with the partition number 1, even if there is more than 1 partition.
  * However, it doesn't care whether the partition bearing the number 1 is actually the first partition.  It will happily display the contents of the second partition as long as it bears the number 1.
  * So, one has to change the partition number of the dd'ed image to 2, then create a new partition in the remaining space and assign it the number 1 and a partition type of FAT (NTFS *might* work, but is untested.)
  * After that, partition "number 1" - actually the second partition on the USB media - can be formatted.
  * Once formatted, one can install X2GoClient for Windows on it, and add a short batch script or similar to run it in portable mode (''x2goclient.exe --portable --session-conf=sessions'').
  * Stefan has written a script to automate this as good as possible, but it is still too fragile to release (fixed paths, many assumptions, no error checking = potential for serious breakage including data loss).

FIXME Document that using ''updateurl'' along with an ''rsync:<nowiki>//</nowiki>FQDN/x2go-tce'' URL is the most efficient way to deploy updates.  Note that the syntax is ''rsync:<nowiki>//</nowiki>FQDN/x2go-tce'', NOT ''rsync:<nowiki>//</nowiki>FQDN::x2go-tce''.
  * On a stock Debian system with rsync installed, this needs ''RSYNC_ENABLE=true'' in ''/etc/default/rsync'' as well as an additional configuration file:

<file - /etc/rsyncd.conf>
lock file = /var/run/rsync.lock
log file = /var/log/rsyncd.log
pid file = /var/run/rsyncd.pid

[x2go-tce]
    path = /var/www/x2go-tce
    # change this to the path where you intend to keep the images
    comment = X2Go TCE files
    uid = root
    gid = root
    read only = yes
    list = yes
    hosts allow = 192.168.0.0/255.255.0.0
    # change this to your local subnet(s)
</file>
  * after you have prepared all this, execute ''service rsync start''
  * Note that whoever manages to spoof the server name can deploy rogue images to your ThinClients.  Even though it is slower, using an HTTPS web server is the safer way of doing this. Be sure that your web server delivers a last-modified header for all files.  In future, support for rsyncd via stunnel might be added, if the rsync project does not add native SSL support to rsyncd before that.

FIXME Some of the optional steps above could be moved to a separate subpage to reduce clutter.

FIXME The steps for the build process could probably streamlined into an x2go-tcebuilder.deb Debian package

Ideas:
  * instead of the "exports" stuff, use a config file e.g. under /etc/x2go/x2go-tcebuilder/config and source its contents
  * instead of copy-pasting the build commands, turn most of it into a script as /usr/bin/x2go-tcebuilder or something (the remaining config parts in the copy-paste block would have to be moved into the config file)
  * our config would be used as suggestion by linking to it; a user could create their own by replacing the link with a regular file (similar to how /etc/x2go/applications works)
  * our additional live-scripts would be shipped inside the package and similar to how apache does it with sites-available and sites-active - not pulling in content from git each time
    * /etc/x2go/x2go-tcebuilder/scripts-active (dir with symlinks to all active scripts)
    * /etc/x2go/x2go-tcebuilder/scripts-available (dir with symlinks to our templates and with regular user-created files)
    * /usr/share/x2go-tcebuilder/template-scripts (scripts we ship, with a big fat header that they should not be changed, but copied)
  * store the results somewhere under /var/lib/x2go-tcebuilder/ or whatever the proper place according to FHS and Debian would be
  * turning it into a package would mean we could add dependencies as well, so the manual apt-get install would not be neccessary
  * additional scripts could be added that work "automagically" if there's no PXE/TFTP/HTTP/FTP server yet - maybe in a separate package x2go-tce-setup-aids.deb which then has dependencies on atftpd and apache|lighttpd, ...

FIXME autodetection for SSH Private Keys might need some more bells and whistles.
  * how about a script that patches the sessions file to enable autologin for all sessions when keys have been found?
  * 2800-x2go-thinclientconfig needs to be changed so it uses the keyfile(s) when in broker mode (''--broker-ssh-key'')
  * Situation: We have a working automounter, and ''copysecring'' will copy all keys found to the live-user's homedir under .ssh:
    * If a session is set to "Try auto login (via SSH Agent or default SSH key)" and NO keyfile is set, then X2GoClient will try **all** secret keys in .ssh. Showing a password prompt if a key is password-protected is handled by X2GoClient, so needs no extra work.
    * To specify a keyfile, either:
      * use ''~/.ssh/keyfilename'' as path and use ''copysecring'', or
      * do not use ''copysecring'' and use ''/media/vendor_model_name/sdxn/path/to/keyfile'' (or ''/media/vendor_model_name/partlabel/path/to/keyfile'', if you assigned a partition label - which is recommended for this use case) as keyfile path/name

FIXME Parsing the output of e.g. <code>udevadm info --query path /dev/sdb
/devices/pci0000:00/0000:00:14.0/usb1/1-1/1-1:1.0/host2/target2:0:0/2:0:0:0/block/sdb
cat /sys/devices/pci0000:00/0000:00:14.0/usb1/1-1/serial</code> allows to determine the serial number of a USB device. Those SHOULD be unique, but sadly, they aren't (and sometimes, they are missing entirely). Therefore, a USB serial number can't be used for authentication, but it could be used for "weak" identification - so it could be used to set a default user name or a default session, or to download a particular sessions file.
Authentification and "hard" identification could be implemented using OpenPGP cards, ''scdaemon'' and a script based on ''/usr/share/doc/scdaemon/examples/scd-event''. For Status ''NOCARD'', suspend the session (kill x2goclient or send a signal that means "suspend", if available, or maybe sighup nxproxy), for status ''USABLE'', run ''gpg --card-status 2>&1 | awk '$1=="Serial" && $2=="number" {print $4}''' to determine the card's serial number, then act based on that (pull new sessions file or set default user, for example, and restart x2goclient).

FIXME Automount script currently expects a LUKS password in ''/etc/keys/keystick.key'' when it believes it has found an encrypted partition on USB media. This is a problem in general, as it should be trivial to sniff out this password using a rogue client. Such a password file would have to be saved as ''./patch/includes.chroot/etc/keys/keystick.key'' (with the proper restrictive permissions) before starting the build. Adding a boot parameter instead of hardcoding it would allow for dynamic password files (by specifying an URI that points to a CGI script, for example - you could output a different password depending on the source IP range, thus locking media to a particular department, if your departments have different IP ranges), but on the other hand, would make it even easier to sniff out the password. It would only really make sense for Netboot installations, and also not for a MiniDesktop in any way, because you have to block the user from accessing the TCE's local environment/files. And you also have to make sure that people cannot boot rogue clients.  This means a DHCP setup that is locked to known MAC addresses, and physically blocking access to the ThinClient and its network wiring - because the MAC is displayed during boot, and thus trivial to clone.

FIXME ''x2gocdmanager'' is currently not part of the image, but should become part of it. While optical media are on their way out, they still exist and thus we should support them. However, the script is hardcoded for X2Go-TCE-NFS and needs to be adapted to work with both TCEs.

FIXME ''pinentry-x2go'' and ''x2gosmartcardrules'' probably need further investigation to make smartcard authentication work.

FIXME Even though we set the hostname to ''localhost'' using the corresponding boot parameter, as recommended by Debian, changing the name via DHCP does not work for all image flavours. One way to fix this might be http://blog.schlomo.schapiro.org/2013/11/setting-hostname-from-dhcp-in-debian.html

FIXME When building a stretch TCE you need to add kernel parameters ''net.ifnames=0 biosdevname=0'' to the image's kernel parameters, else you will receive error messages about the hostname script being unable to find eth0. For a jessie TCE, it is not required. This could be fixed for iso-hybrid and netboot in the buildscript, but it will only work if people are using the image 1:1 - as soon as they start using syslinux or grub manually (as actually recommended by us), they need to add these parameters themselves.

FIXME ''bg='', ''branding='', ''broker-url='', ''ldap='', ''ldap1='', ''ldap2='', ''session='', ''throttle='', are currently unsupported in MiniDesktop-Mode. This could be changed, given enough tuits. Probably the easiest way would be to have ''/lib/live/config/2900-x2go-thinclientconfig'' exist in the MiniDesktop branches as well, make it aware of which environment it is running in (TCE/TCE-MMD), and have it patch the appropriate files.

FIXME <del>''2200-xserver-xorg-getxorgconf''</del> all scripts accepting URLs in boot parameters should be taught to understand ''file:<nowiki>///</nowiki>'' URLs. Such files can be included in the image by placing them in the ''./patch/includes.chroot/'' directory (in a suitable subdirectory) and referencing them from there.

FIXME it would be cool if most of the TCE-specific boot parameters could be placed into a file that in turn can be specified as a boot parameter, to reduce clutter and boot parameter length. This could be aCGI script, even, thus making it possible to distribute different configs depending on the source IP of the ThinClient, rather than the MAC Address. Said file would then have to be sourced by the scripts, after they have extracted everything from /proc/cmdline. This will make adding the feature easier, by simply deciding that parameters from this file take precendence over boot parameters. One might argue that boot parameters should take precedence over the config file, but this sounds way more complicated to implement.

FIXME A smaller image size can be achieved by removing the following packages from the squashfs: ''libxapian30 libpcsclite1 libdbus-glib-1-2 libfuse2 libpipeline1 libusb-1.0-0 libxv1 xnest xserver-xephyr rdesktop freerdp-x11 traceroute screen net-tools less ntfs-3g fuse locales cifs-utils xterm libgssglue1 libntfs-3g871 libtalloc2 libtcl8.6 libtk8.6 libutempter0 libvncclient1 libvncserver1 libwbclient0 libxcb-xf86dri0 libxcb-xv0 samba-common tcl tcl8.6 tk tk8.6 xbitmaps nfs-common rpcbind atmel-firmware bluez-firmware dahdi-firmware-nonfree hdmi2usb-fx2-firmware iso-codes ixo-usb-jtag libc-l10n libnfsidmap2 libtirpc1 firmware* x11vnc* libfreerdp* libwinpr* libapparmor1 systemd apt-utils libapt-inst2.0 acpi-support-base* acpid* acpi-support* pm-utils* powermgmt-base* gnupg gnupg-agent whiptail vim* vim-common* vim-tiny* xxd* xinetd libcroco3* libcurl3* libexif12* libgdk-pixbuf2.0-0* libgdk-pixbuf2.0-common* libgif7* libid3tag0* libimlib2* libnghttp2-14* libobrender32v5* libobt2v5* libpango-1.0-0* libpangocairo-1.0-0* libpangoft2-1.0-0* libpangoxft-1.0-0* librsvg2-2* librtmp1* libssh2-1* libstartup-notification0* libxft2* libxss1* vim-runtime* xprintidle feh xdotool openbox rsync   xserver-xorg-input-wacom* xserver-xorg-video-all* xserver-xorg-video-amdgpu* xserver-xorg-video-ati* xserver-xorg-video-nouveau* xserver-xorg-video-qxl* xserver-xorg-video-radeon* xserver-xorg-video-vmware* libdrm-amdgpu1* libdrm-nouveau2* libdrm-radeon1* libllvm3.9* libsensors4* libxatracker2*'' 
 - check if this could be turned into a build parameter. Note that this makes only sense for a netboot image that uses X2Go sessions only, and no NTFS media (neither fixed disk nor USB). Also, this causes an X startup failure during boot that needs to be worked around (by touching /home/user/.xsession).
Here's a script to do all of this automatically (needs to be run as root in the builddir:
<file - stripimage.sh>
#!/bin/bash -e
if [ $UID -ne 0 ] ; then
	echo "Must be root."
	exit 1
fi
unsquashfs x2go-tce-filesystem.squashfs
mount --bind /proc squashfs-root/proc
chroot squashfs-root apt purge -y acpi-support-base acpid acpi-support pm-utils powermgmt-base gnupg gnupg-agent whiptail vim vim-common vim-tiny xxd xinetd \
                                  libcroco3 libcurl3 libexif12 libgdk-pixbuf2.0-0 libgdk-pixbuf2.0-common libgif7 libid3tag0 libimlib2 libnghttp2-14 \
                                  libobrender32v5 libobt2v5 libpango-1.0-0 libpangocairo-1.0-0 libpangoft2-1.0-0 libpangoxft-1.0-0 librsvg2-2 librtmp1 \
                                  libssh2-1 libstartup-notification0 libxft2 libxss1 vim-runtime rsync xserver-xorg-input-wacom xserver-xorg-video-all \
                                  xserver-xorg-video-amdgpu xserver-xorg-video-ati xserver-xorg-video-nouveau xserver-xorg-video-qxl \
                                  xserver-xorg-video-radeon xserver-xorg-video-vmware libdrm-amdgpu1 libdrm-nouveau2 libdrm-radeon1 libllvm3.9 libsensors4 \
                                  libxatracker2 xprintidle feh xdotool openbox libxapian30 libpipeline1 libnpth0 libksba8 libseccomp2 libsqlite3-0 libxdo3 \
                                  libnewt0.52 libslang2 keyutils libassuan0 libdatrie1 libevent-2.0-5 libthai-data libthai0 \
                                  pinentry-curses trickle libxapian30 libpcsclite1 libdbus-glib-1-2 libfuse2 libpipeline1 libusb-1.0-0 libxv1 xnest \
                                  xserver-xephyr rdesktop freerdp-x11 traceroute screen net-tools less ntfs-3g fuse locales cifs-utils xterm libgssglue1 \
                                  libntfs-3g871 libtalloc2 libtcl8.6 libtk8.6 libutempter0 libvncclient1 libvncserver1 libwbclient0 libxcb-xf86dri0 \
                                  libxcb-xv0 samba-common tcl tcl8.6 tk tk8.6 xbitmaps nfs-common rpcbind atmel-firmware bluez-firmware \
                                  dahdi-firmware-nonfree hdmi2usb-fx2-firmware iso-codes ixo-usb-jtag libc-l10n libnfsidmap2 libtirpc1 x11vnc x11vnc-data \
                                  libapparmor1 systemd apt-utils libapt-inst2.0 libfreerdp-cache1.1 libfreerdp-client1.1 libfreerdp-codec1.1 \
                                  libfreerdp-common1.1.0 libfreerdp-core1.1 libfreerdp-crypto1.1 libfreerdp-gdi1.1 libfreerdp-locale1.1 \
                                  libfreerdp-primitives1.1 libfreerdp-rail1.1 libfreerdp-utils1.1 libwinpr-crt0.1 libwinpr-crypto0.1 libwinpr-dsparse0.1 \
                                  libwinpr-environment0.1 libwinpr-file0.1 libwinpr-handle0.1 libwinpr-heap0.1 libwinpr-input0.1 libwinpr-interlocked0.1 \
                                  libwinpr-library0.1 libwinpr-path0.1 libwinpr-pool0.1 libwinpr-registry0.1 libwinpr-rpc0.1 libwinpr-sspi0.1 \
                                  libwinpr-synch0.1 libwinpr-sysinfo0.1 libwinpr-thread0.1 libwinpr-utils0.1 firmware-amd-graphics firmware-atheros \
                                  firmware-bnx2 firmware-bnx2x firmware-brcm80211 firmware-cavium firmware-crystalhd firmware-intel-sound \
                                  firmware-intelwimax firmware-ipw2x00 firmware-ivtv firmware-iwlwifi firmware-libertas firmware-linux firmware-linux-free \
                                  firmware-linux-nonfree firmware-misc-nonfree firmware-myricom firmware-netxen firmware-qlogic firmware-realtek \
                                  firmware-samsung firmware-siano firmware-ti-connectivity firmware-zd1211
chroot squashfs-root dpkg -P apt tasksel tasksel-data
rm squashfs-root/etc/X11/Xsession.d/60x11-openbox-start squashfs-root/etc/X11/Xsession.d/60x11-spawn-configure-slideshow-screensaver
(cd squashfs-root/usr/bin/ ; ln -sf ../../bin/false xsetwacom)
mkdir -p squashfs-root/home/user
touch squashfs-root/home/user/.xsession
umount squashfs-root/proc
if ! grep '^eval $THROTTLINGCOMMAND' squashfs-root/etc/X11/Xsession.d/61x11-start-x2goclient | grep -q -- ' --thinclient ' ; then
        sed -i -e 's#eval \$THROTTLINGCOMMAND x2goclient#eval \$THROTTLINGCOMMAND x2goclient --thinclient#g' \
            squashfs-root/etc/X11/Xsession.d/61x11-start-x2goclient
fi
if [ -f binary/live/filesystem.squashfs ] ; then
        mv binary/live/filesystem.squashfs binary/live/filesystem.squashfs.old
fi
mkdir -p binary/live
mksquashfs squashfs-root binary/live/filesystem.squashfs -comp xz -Xbcj x86 -b 1024K -Xdict-size 1024K -noappend
rm -rf squashfs-root
ln -f binary/live/filesystem.squashfs x2go-tce-filesystem-stripped.squashfs
(cd binary; echo live$'\n'live/filesystem.squashfs |cpio -o -H newc | gzip --fast) >./tce-filesystem-stripped.cpio.gz
cat ./x2go-tce-initrd.img ./tce-filesystem-stripped.cpio.gz >./x2go-tce-initrd-with-fs-stripped.img
rm ./tce-filesystem-stripped.cpio.gz
</file>

FIXME for MATE-MiniDesktop, it might make sense to teach the image how to do LDAP auth (preferably with LDAPS or LDAP+TLS) and use lightdm without the auto-login. That way, a local screensaver //with// locking functionality (prompting for the actual user's LDAP password) should be possible - and LDAP credential passthrough to X2GoClient should work, too (though that might require kerberos in addition to LDAP,we'll see).

FIXME Scripts triggered by if-up should check if a new download is really necessary.

===== List of closed ToDos/FIXMEs for this page ===== 
  * Feature request: In TCE (not MMD), use <code>
while ! (grep "^/dev/" /etc/mtab | grep -q rw ) ; do # rw-mounted physical devices detected
	echo s >/proc/sysrq-trigger # sync all
	echo u >/proc/sysrq-trigger # remount all (physdevs) ro
done
echo o >/proc/sysrq-trigger # force fast shutdown/poweroff
</code> for faster poweroff when boot parameter ''fastpo'' is set

  * ''audioout='', ''blank='', ''*blankdpmsfix'', ''nodpms'', ''xinerama='', are currently unsupported in MiniDesktop-Mode, but this is being worked on, by outsourcing them into scripts under ''/etc/X11/Xsession.d/'' (currently, they reside in ''/lib/live/config/2900-x2go-thinclientconfig'' - which doesn't exist in the MiniDesktop branches - and from there, they get written to ''~/.xsession'' - fixed in github repo, soon in x2go repo
  * It would be nice to have a boot parameter ''xroot=[0xaabbcc|URI1[|URI2|...]]'' for the desktop background image/color, and a boot parameter ''xrootmode=center|fill|scale|tile'' to determine how the image(s) should be positioned (if the parameter has been set, but something is wrong, it should default to the "grey mesh" background) - fixed in github repo, soon in x2go repo
  * It would also be nice to have boot parameters ''xsaverimages=[URI1[|URI2|...]]'', ''xsaveridletime=n'', ''xsaverimgtime=n'', for a local, non-locking slideshow screensaver (if no images are specified/downloaded by the time it activates, it should just blank the screen). That way, one could display a slideshow without having to push the images across the network every time  - fixed in github repo, soon in x2go repo
  * Boot parameters ''blankdpmsfix'' and ''earlyblankdpmsfix'' still leave the screen blank for too long, when used in netboot mode (especially over slow links). Two ways to solve this are to either use local storage, or to use the initrd with the squashfs merged into it.  A third, new option would be a boot parameter ''initrdblankdpmsfix'', where the un-blanking code of ''earlyblankdpmsfix'' is applied in the initrd already - fixed in github repo, soon in x2go repo
  * There might be a race condition between the scripts handling the sshd keyfile and the ssh private key file copy task (/config ...), causing one to umount the fixed disk before the other is done reading/copying. What's weird is that there already is code that is supposed to keep this from happening, but it doesn't. - fixed in github repo, soon in x2go repo
  * Setting the time via NTP will fail if the TC can't establish a connection to an NTP server via the internet. It would make sense to allow specifying an internal NTP server via a boot parameter. - fixed in github repo, soon in x2go repo
  * ''copysecring'' currently does not work in MiniDesktop-Mode, as it copies the keys to the wrong user's homedir. - fixed in github repo, soon in x2go repo
  * copying ssh private keys seems to fail in MiniDesktop-Mode - possibly because of the priming/pruning/cleanup action performed on the homedirectory by the minidesktop init scripts? -  should already be fixed in github repo, soon in x2go repo 
  * Automount script expansion is in the works. Will fully support VFAT, NTFS, hfs, hpfs, will offer read-only support for ext* via fuseext2 (that way, file ownership/permissions are ignored). - fixed.
  * ''homepageurl='' (only available in MiniDesktop-Mode) is currently undocumented. Supports multiple URLs separated with pipes. - fixed
  * Maybe we should add symlinks to the mount points created by the automounter: Currently, we create ''/media/vendor_model_name/sdxn'' as a mount point. The idea is to allow the user to find their portable device using the vendor/model name description. However, this is unusable for scripting, as the ''//x//'' in ''sdxn'' may change any time. We should replace ''//sdx//'' with ''//partition//'' (or have corresponding symlinks created), but what should we do for //superfloppies// that only have ''sdx'' with no partition number? We could mount them as ''/media/vendor_model_name/partition/'' or directly at ''/media/vendor_model_name/''. Also, symlinks using labels and uuids, similar to ''/dev/by-*'' would be handy for scripting. Another problem: when replacing ''sdx'', what will happen when a user inserts two media with the same vendor/model name at the same time? Blindly replacing the string would make one of them inaccessible due to overwriting the symlink(s). We'd have to start checking active mounts and enumerate them like ''/media/vendor_model_name/1/partitionn'' or ''/media/vendor_model_name-1/partitionn''. - fixed. When a label is detected, a symlink is now created under ''/media/vendor_model_name/label'' that points to ''/media/vendor_model_name/partitionn''.
  * ''nomagicpixel='' is unsupported in MiniDesktop-Mode and will be unsupported there forever, as it doesn't make sense for MiniDesktop-Mode (there is a task bar available, so a session that has been minimized accidentally can be re-selected by the users themselves). - unfixable.
  * volume control applet for MiniDesktop mode has been added  - fixed in github repo, soon in x2go repo (to save/restore volume control settings, using the "persistence" feature of live-build is probably the better way to go)
<note>The live-config "builtin" command ''live-config.nottyautologin'' does not do the same as our ''nouser'' command. ''live-config.nottyautologin'' means "there's a login prompt, but you just need to enter username ''user'' and password ''live'' to login" - this is not what we want.  We need a solution to entirely block user logons.
</note>
X2Go - everywhere@home

User Tools

Site Tools

Page Tools
