LTSP.CONF(5)

📦
version 23.02 · 6 versions
, in debian trixie, ubuntu questing

💖 LTSP.CONF — the client config file for LTSP, bestie 💖

okay so you wanna know about ltsp.conf? that's the client configuration file for LTSP, and it's lowkey the main character of your whole LTSP setup. it lives in section 5 of the manual, so pull up a chair, grab a strawberry 🍓, and let's get into it.

✨ NAME ✨

ltsp.conf — the client configuration file for LTSP. that's it, that's the name, and she serves. 💅

🌸 SYNOPSIS 🌸

so the LTSP client configuration file goes at /etc/ltsp/ltsp.conf, and it loosely follows the .ini format — like, it's giving .ini energy but it's not gonna be weird about it. it's the file that controls a whole bunch of settings for the LTSP server AND the clients. very versatile, very iconic. 👑

and here's the thing you cannot forget, bestie: after every single time you edit ltsp.conf, you have to run the ltsp initrd command. why?? because your changes need to get baked into the additional ltsp.img initrd that gets sent out when the clients boot. no ltsp initrd, no new config, and you'll be sitting there like "why is nothing working 😭" — it's because you skipped the step. periodt.

🎀 CREATION 🎀

to create an initial ltsp.conf, run this:

install -m 0660 -g sudo /usr/share/ltsp/common/ltsp/ltsp.conf /etc/ltsp/ltsp.conf

the -g sudo parameter is optional, but it's lowkey a slay: it lets users in the sudo group edit ltsp.conf with literally any editor they want (like gedit) without having to run sudo first. no more sudo-ing into a text editor at 2am, we love convenience. 🫶

🦋 SYNTAX 🦋

first move: open up that /etc/ltsp/ltsp.conf file you just created and actually look at it. fr fr, it makes the syntax so much easier to understand when you can see it with your own eyes. 👀

the config file is split up into sections, and each one has a whole different vibe:

  • the special [server] section is evaluated only by the ltsp server. server-only business, the clients don't even look at it. 💅
  • the special [common] section is evaluated by both the server and the ltsp clients. sharing is caring. ✨
  • in the special [clients] section, you can define parameters for all clients. most ltsp.conf parameters should go right here — this is the main character section, the one you'll be living in. 👑
  • MAC address, IP address, or hostname sections let you apply settings to specific clients. and they support globs!! so you can do stuff like [192.168.67.*] and target a whole range. obsessed. 🌈
  • you can also group parameters into named sections — like [crt_monitor] in the example — and then reference them from other sections using the INCLUDE= parameter. it's giving modular, it's giving organized, it's giving reuse. 🧚
  • and for the advanced girlies: you can use [applet/host] sections too. for example, [initrd-bottom/library*] would be evaluated by the ltsp initrd-bottom applet only for clients that have a hostname starting with library. iykyk. 🔥

now here's the tea ☕ — internally, the ltsp.conf file gets transformed into a shell script. so like, all the shell syntax rules apply?? except the section headers, which get transformed into functions instead. it's a whole glow-up.

which means two very important things:

  • you must not use spaces around the = sign. KEY=value, not KEY = value. i know, i know, but that's the rule. 💀
  • you can write comments using the # character. go off, document your config. 📝
and one more lil safety net: the ltsp initrd command does a quick syntax check by running sh -n /etc/ltsp/ltsp.conf, and it will abort if it detects syntax errors. so if you typo something, she'll catch it before your clients ever boot. thank u queen. 🙏

✨ PARAMETERS ✨

okay bestie this is the big one 💖 here are all the parameters that are currently defined, and I'm gonna hand you an example for each one because that's just how we do. no cap.

  • ADD_IMAGE_EXCLUDES="/etc/ltsp/add-image.excludes"
  • OMIT_IMAGE_EXCLUDES="home/*"

Add or omit items to the ltsp image exclusion list 🫶 some files and directories genuinely shouldn't be included in the generated image, periodt. The initial list is defined in /usr/share/ltsp/server/image/image.excludes. It can be completely overridden by creating /etc/ltsp/image.excludes. ADD_IMAGE_EXCLUDES and OMIT_IMAGE_EXCLUDES can finetune the list by adding or removing lines to it. They can either be filenames or multiline text.

  • AUTOLOGIN="user01"
  • RELOGIN=0|1
  • GDM3_CONF="WaylandEnable=false"
  • LIGHTDM_CONF="greeter-hide-users=true"
  • SDDM_CONF="/etc/ltsp/sddm.conf"

Configure the display manager to log in this user automatically ✨ If SSHFS is used, the PASSWORDS_x parameter (see below 👀) must also be provided. AUTOLOGIN can be a simple username like "user01", or it can be a partial regular expression that transforms a hostname to a username. For example, AUTOLOGIN="pc/guest" means "automatically log in as guest01 in pc01, as guest02 in pc02 etc". Setting RELOGIN=0 will make AUTOLOGIN work only once. Finally, the *_CONF parameters can be either filenames or direct text, and provide a way to write additional content to the generated display manager configuration. the way that all works is lowkey iconic 💅

  • CRONTAB_x="30 15 * * * root poweroff"

Add a line in crontab. The example powers off the clients at 15:30. bye besties 😭

  • CUPS_SERVER="$SERVER"

Set the CUPS server in the client /etc/cups/client.conf. Defaults to $SERVER. You're supposed to also enable printer sharing on the server by running cupsctl _share_printers=1 or system-config-printer or by visiting http://localhost:631. Then all printers can be managed on the LTSP server. Other possible values are CUPS_SERVER="localhost", when a printer is connected to a client, or CUPS_SERVER="ignore", to skip CUPS server handling. 🖨️

  • DEBUG_LOG=0|1

Write warnings and error messages to /run/ltsp/debug.log. Defaults to 0.

  • DEBUG_SHELL=0|1

Launch a debug shell when errors are detected. Defaults to 0. very main character of it 🐛

  • DEFAULT_IMAGE="x86_64"
  • KERNEL_PARAMETERS="nomodeset noapic"
  • MENU_TIMEOUT="5000"

These parameters can be defined under [mac:address] sections in ltsp.conf, and they are used by ltsp ipxe to generate the iPXE menu. They control the default menu item, the additional kernel parameters and the menu timeout for each client. They can also be defined globally under [server]. 🌈

  • DISABLE_SESSION_SERVICES="evolution-addressbook-factory obex"
  • DISABLE_SYSTEM_SERVICES="anydesk teamviewerd"
  • KEEP_SESSION_SERVICES="at-spi-dbus-bus"
  • KEEP_SYSTEM_SERVICES="apparmor ssh"
  • MASK_SESSION_SERVICES="gnome-software-service update-notifier"
  • MASK_SYSTEM_SERVICES="apt-daily apt-daily-upgrade rsyslog"

Space separated lists of services to disable, permit or mask on LTSP clients 💅 They mostly correspond to systemctl disable/mask [--user] invocations. Setting these ltsp.conf parameters adds or omits items from the default lists that are defined in /usr/share/ltsp/client/init/56-services.sh. Disabled services can be started on demand by e.g. dbus or socket activation, while masked services need to be manually unmasked first 👑 Currently, MASK_SESSION_SERVICES also deletes the non-systemd user services from /etc/xdg/autostart.

  • DNS_SERVER="8.8.8.8 208.67.222.222"

Specify the DNS servers for the clients. 🌐

  • FSTAB_x="server:/home /home nfs defaults,nolock 0 0"

All parameters that start with FSTAB_ are sorted and then their values are written to /etc/fstab at the client init phase.

  • HOSTNAME="pc01"

Specify the client hostname. Defaults to "ltsp%{IP}". HOSTNAME may contain the %{IP} pseudovariable, which is a sequence number calculated from the client IP and the subnet mask, or the %{MAC} pseudovariable, which is the MAC address without the colons. 🏷️

  • HOSTS_x="192.168.67.10 nfs-server"

All parameters that start with HOSTS_ are sorted and then their values are written to /etc/hosts at the client init phase.

  • IMAGE_TO_RAM=0|1

Specifying this option under the [clients] section copies the rootfs image to RAM during boot. That makes clients less dependent on the server, but they must have sufficient memory to fit the image 😤 don't skip the RAM check bestie.

  • INCLUDE="other-section"

Include another section in this section. 🪄

  • LOCAL_SWAP=0|1

Activate local swap partitions. Defaults to 1.

  • MULTISEAT=0|1
  • UDEV_SEAT_n_x="*/usb?/?-[2,4,6,8,10,12,14,16,18]/*"

MULTISEAT=1 tries to autodetect if an LTSP client has two graphics cards and to automatically split them along with the USB ports into two seats ✨ Optional lines like UDEV_SEAT_1_SOUND="*/sound/card1*" can be used to finetune the udev rules that will be generated and placed in a file named /etc/udev/rules.d/72-ltsp-seats.rules. it's giving split-screen energy 🎀

  • NAT=0|1

Only use this under the [server] section 👈 Normally, ltsp service runs when the server boots and detects if a server IP is 192.168.67.1, in which case it automatically enables IP forwarding for the clients to be able to access the Internet in dual NIC setups. But if there's a chance that the IP isn't set yet (e.g. disconnected network cable), setting NAT=1 enforces that.

  • OMIT_FUNCTIONS="pam_main mask_services_main"

A space separated list of function names that should be omitted. The functions specified here will not be executed when called. This option can be specified in any [section]. 🙈

  • PASSWORDS_x="teacher/cXdlcjEyMzQK [a-z][-0-9]*/MTIzNAo= guest[^:]*/"

A space separated list of regular expressions that match usernames, followed by slash and base64-encoded passwords. At boot, ltsp init writes those passwords for the matching users in /etc/shadow, so that then pamltsp can pass them to SSH/SSHFS. The end result is that those users are able to login either in the console or the display manager by just pressing [Enter] at the password prompt 😳 slay.

Passwords are base64-encoded to prevent over-the-shoulder spying and to avoid the need for escaping special characters. To encode a password in base64, run base64, type a single password, and then Ctrl+D.

In the example above, the teacher account will automatically use "qwer1234" as the password, the a1-01, b1-02 etc students will use "1234", and the guest01 etc accounts will be able to use an empty password without even authenticating against the server; in this case, SSHFS can't be used, /home should be local or NFS. 🔐

fr fr read that one twice, it's doing a LOT.
  • POST_APPLET_x="ln -s /etc/ltsp/xorg.conf /etc/X11/xorg.conf"

All parameters that start with POST_ and then have an ltsp client applet name are sorted and their values are executed after the main function of that applet. See the ltsp(8) man page for the available applets. The usual place to run client initialization commands that don't need to daemonize is POST_INIT_x.

  • PRE_APPLET_x="debug_shell"

All parameters that start with PRE_ and then have an ltsp client applet name are sorted and their values are executed before the main function of that applet. ⏱️

  • PWMERGE_SUR=, PWMERGE_SGR=, PWMERGE_DGR=, PWMERGE_DUR=

Normally, all the server users are listed on the client login screens and are permitted to log in. To exclude some of them, define one or more of those regular expressions. For more information, read /usr/share/ltsp/client/login/pwmerge. For example, if you name your clients pc01, pc02 etc, and your users a01, a02, b01, b02 etc, then the following line only shows/allows a01 and b01 to login to pc01:

PWMERGE_SUR=".*%{HOSTNAME#pc}"
  • REMOTEAPPS="users-admin mate-about-me"

Register the specified applications as remoteapps, so that they're executed on the LTSP server via ssh -X instead of on the clients. For more information, see ltsp-remoteapps(8). 🦋

  • RPI_IMAGE="raspios"

Select this LTSP image to boot Raspberry Pis from. This symlinks all $BASE_DIR/$RPI_IMAGE/boot/* files directly under $TFTP_DIR when ltsp kernel $RPI_IMAGE is called. See the Raspberry Pi OS documentation page at https://ltsp.org/docs/installation/raspios for more information. 🍓

  • SEARCH_DOMAIN="ioa.sch.gr"

A search domain to add to resolv.conf and to /etc/hosts. Usually provided by DHCP.

  • SERVER="192.168.67.1"

The LTSP server is usually autodetected; it can be manually specified if there's need for it.

  • X_DRIVER="vesa"
  • X_HORIZSYNC="28.0-87.0"
  • X_MODELINE='"1024x768_85.00" 94.50 1024 1096 1200 1376 768 771 775 809 -hsync +vsync'
  • X_MODES='"1024x768" "800x600" "640x480"'
  • X_PREFERREDMODE="1024x768"
  • X_VERTREFRESH="43.0-87.0"
  • X_VIRTUAL="800 600"

If any of these parameters are set, the /usr/share/ltsp/client/init/xorg.conf template is installed to /etc/X11/xorg.conf, while applying the parameters. Read that template and consult xorg.conf(5) for more information. The most widely supported method to set a default resolution is X_MODES. If more parameters are required, create a custom xorg.conf as described in the EXAMPLES section. 🖥️✨

💖 EXAMPLES 💖 (the fun part, bestie)

okay so real talk, this is where it all clicks. let's go 🌈

🎀 autologin a specific client, no cap

say you want a client to have a hostname AND autologin a user, you literally just do this in a section keyed by its MAC address:

[3c:07:71:a2:02:e3]
HOSTNAME=pc01
AUTOLOGIN=user01
PASSWORDS_PC01="user01/cGFzczAxCg=="

and before you panic about that password — the password above is pass01 in base64 encoding, okay? it's giving encrypted but make it readable. to calculate it yourself, the base64 command was run in a terminal like this:

base64
pass01
<press Ctrl+D at this point>
cGFzczAxCg==

so yeah you literally just run base64, type your password, hit Ctrl+D, and the magic string falls out. slay ✨

🦋 custom xorg.conf for just some clients

if some clients need a custom xorg.conf file, create it in e.g. /etc/ltsp/xorg-nvidia.conf, and then put the following in ltsp.conf so it gets dynamically symlinked for those clients at boot:

[pc01]
INCLUDE=nvidia

[nvidia]
POST_INIT_LN_XORG="ln -sf ../ltsp/xorg-nvidia.conf /etc/X11/xorg.conf"

see what she did there?? INCLUDE pulls in the nvidia section only for pc01, and the POST_INIT_LN_XORG hook does the symlink at exactly the right moment. main character behavior fr fr 👑

👑 the big brain one: including raw code

since ltsp.conf is transformed into a shell script and sections into functions, it's possible to directly include code or to call sections at POST_APPLET_x hooks. yes, bestie, you're writing shell now. it's lowkey iconic.

[clients]
# Allow local root logins by setting a password hash for the root user.
# The hash contains $, making it hard to escape in POST_INIT_x="sed ...".
# So put sed in a section and call it at POST_INIT like this:
POST_INIT_SET_ROOT_HASH="section_set_root_hash"

# This is the hash of "qwer1234"; cat /etc/shadow to see your hash.
[set_root_hash]
sed 's|^root:[^:]*:|root:$6$VRfFL349App5$BfxBbLE.tYInJfeqyGTv2lbk6KOza3L2AMpQz7bMuCdb3ZsJacl9Nra7F/Zm7WZJbnK5kvK74Ik9WO2qGietM0:|' -i /etc/shadow

read those comments again though, they're doing a LOT of work. the hash contains $, which makes it genuinely hard to escape inside POST_INIT_x="sed ..." — so the move is: put the sed in its own section, then call that section at POST_INIT. the comment tells you that hash above is the hash of qwer1234, and that you can cat /etc/shadow to see your own hash. periodt. 💅

also heads up bestie, that sed -i is editing /etc/shadow for real. know what you're doing before you run it, k? 🫶

Copyright 2019-2022 the LTSP team, see AUTHORS.

(they said it, not me — go read the AUTHORS file, they deserve the credit 💜)

🌸 SEE ALSO 🌸

Online documentation is available on https://ltsp.org

go read the rest of the crew, they all ate 🔥

and that's the whole page, bestie!! 🎉 this manual page is from LTSP 23.02-3, dated 2024-09-07, and it's LTSP.CONF(5). you made it to the end, i'm so proud, now go configure some thin clients and be the main character of your own lab 💖✨🎀🦋

📦 where this page comes from