LTSP-IMAGE(8)

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

💖 LTSP-IMAGE(8) — the LTSP Manual, but make it make sense 💖

okay bestie, gather round, because this one is ltsp image from the LTSP Manual (yes, that's the LTSP-IMAGE(8) page, hi, welcome) and it is lowkey the main character of the whole netboot situation. no cap. let's go 🦋

✨ NAME ✨

ltsp image — generate a squashfs image from an image source

🌸 SYNOPSIS 🌸

ltsp [ltsp-options] image [-b backup] [-c cleanup] [-i ionice] [-k
kernel-initrd] [-m mksquashfs-params] [-r revert] [image] ...

💅 DESCRIPTION 💅

So basically: you take a virtual machine image or a chroot directory and you squash it — literally, into a squashfs image — and that becomes the network root filesystem for your LTSP clients. it's giving live CD energy, fr fr: all the clients boot off this one single read only image, and then they use SSHFS or NFS to mount /home/username from the server. iconic behaviour honestly.

🎀 OPTIONS 🎀

first things first: go read the ltsp(8) man page for ltsp-options, bestie, that's where the shared stuff lives 💖

  • -b, --backup=0|1 — backs up /srv/ltsp/images/image.img to image.img.old. defaults to 1. so yeah, you get a safety net by default, we love that for you 🫶
  • -c, --cleanup=0|1 — creates a writeable overlay on top of the image source and temporarily yeets the user accounts and sensitive data before calling mksquashfs. defaults to 1. this is the "please don't ship my secrets to the clients" button and it is on by default for a reason 🔥
  • -i, --ionice=cmdline — set a prefix command so mksquashfs runs at a lower priority, or pass "" to disable it completely. defaults to nice ionice -c3. so it doesn't eat your whole server alive while it's squashing, we stan a considerate queen 💅
  • -k, --kernel-initrd=glob-regex — passes this parameter to the ltsp kernel call after the squashfs creation. more deets in ltsp-kernel(8), go look 👀
  • -m, --mksquashfs-params="params" — passes $params to the mksquashfs call unquoted; so like, params shouldn't contain spaces, okay? see mksquashfs(1) for the full menu 🌈
  • -r, --revert[=0|1] — moves /srv/ltsp/images/image.img.old to image.img and calls ltsp kernel image. extremely useful when the clients just won't boot with the new image and you're sitting there like 😭. the undo button. use it.

🧚 IMAGE TYPES 🧚

there are three "image" types in LTSP, and they live in the following locations. heads up: the /srv/ltsp path can be configured with ltsp --base-dir=: ✨

  • /srv/ltsp/img_name.img — source images, sitting directly under /srv/ltsp, and usually they're symlinks to virtual machine raw disk files. these are only used by ltsp image.
  • /srv/ltsp/img_name — chroot directories. these can be used BOTH as sources for ltsp image and as NFS root exports for the clients. multitasking queen 👑
  • /srv/ltsp/images/img_name.img — exported images (usually squashfs), placed under the images directory, and these are the ones clients can netboot from 🥳

you can specify images as simple names like ltsp image img_name, in which case those locations above get searched, or as full paths like ltsp image ~/VMs/vm.img. your call, bestie.

the supported image types give you the following three methods of using LTSP. you may use either one of them, or honestly, all of them at the same time. no rules 💜

🌈 CHROOTLESS 🌈

Chrootless LTSP, previously called ltsp-pnp, is the recommended way to maintain LTSP — if its restrictions are acceptable to you. in this mode, the server operating system itself gets exported into a squashfs file and used to netboot all the clients. you, the sysadmin (yes you, main character), would use the typical GUI tools to manage the server, like software centers or update managers. then whenever necessary, you'd run:

ltsp image /

this creates or updates /srv/ltsp/images/x86_64.img (the arch name comes from uname -m). and then — boom — all the clients should be able to boot from x86_64.img and have a desktop environment identical to the server. slay.

the big advantage of chrootless mode is simplicity: there are no virtual machines or chroots involved. you'd maintain the server like any "home desktop PC", and have all clients be exact replicas, which is as simple as it gets. it's giving effortless 🦋

the disadvantages are that the clients need to have the same architecture as the server (e.g. all x86_64), and that the server can't be a "full blown server" with LDAP and Apache and a lot of other services, without taking care to disable those services on the clients with the MASK_SYSTEM_SERVICES parameter of ltsp.conf. note that MASK_SYSTEM_SERVICES already includes Apache and MySQL and a few other popular services that we don't want in LTSP clients, so it's not a problem if you install Apache on the LTSP server. phew 😮‍💨

if for some reason you prefer a different name to uname -m, you may create a symlink:

ln -s / ~/amd64

...and run ltsp image ~/amd64 instead. easy 💅

🦋 VM IMAGES 🦋

if the chrootless case doesn't fit you, you may use VirtualBox, virt-manager, KVM, VMWare and similar tools to maintain one or more template images for the clients. as an example, let's suppose you create a VM in VirtualBox and call it "debian". at the disk creation dialog, select "VMDK" type and "Fixed size", not "Dynamically allocated". proceed with installing Debian on it. in the partitioning step, make sure that the whole operating system goes in the first partition, without extra partitions for /boot etc. BIOS/MBR is easier, while if you have to use GPT/UEFI, put the EFI partition second. when you're done, close VirtualBox and symlink the VM disk so that LTSP finds it more easily:

ln -rs ~/VirtualBox\ VMs/debian/debian-flat.vmdk /srv/ltsp/debian.img

to export this image to the clients, after the initial creation or after updates etc, you'd run:

ltsp image debian

it's also possible to omit the symlink by running:

ltsp image ~/VirtualBox\ VMs/debian/debian-flat.vmdk

...but then the image name shown in the iPXE boot menu would be "debian-flat", which isn't pretty. 🙈 we're not doing that to ourselves.

in summary: you may symlink raw VM disks in /srv/ltsp/img_name.img, and ltsp image img_name will allow LTSP clients to netboot from them. please also see the DIRECT IMAGES section of ltsp-kernel(8) for an advanced method of allowing clients to netboot directly from a VM or .iso image without even running ltsp image, and the ADVANCED IMAGE SOURCES section of ltsp-ipxe(8) for extreme cases like telling the LTSP clients to boot from an .iso image inside a local disk partition! wild, i know 😳

⭐ CHROOTS ⭐

chroot directories in /srv/ltsp/img_name are properly supported as image sources by LTSP, but their creation and maintenance are left to external tools like debootstrap, lxc etc. the ltsp-build-client LTSPv5 tool no longer exists — rip bozo 💀. LTSP users are invited to create appropriate documentation in the community wiki ⟨https://github.com/ltsp/ltsp/wiki/chroots⟩. as a small example, you can use kvm to netboot a chroot and maintain it if you NFS-export /srv/ltsp/img_name in rw mode for your server IP, and then run

kvm -m 512 -kernel img_name/vmlinuz -initrd img_name/initrd.img \
    -append "rw root=/dev/nfs nfsroot=192.168.67.1:/srv/ltsp/img_name"

💜 EXAMPLES 💜

use the server installation as a template to generate a client image (chrootless, previously called ltsp-pnp):

ltsp image /

inform ltsp image that a chrootless installation uses separate /boot and /opt partitions:

ltsp image /,,/boot,subdir=boot,,/opt,subdir=opt

compress the /srv/ltsp/x86_64 chroot or the /srv/ltsp/x86_64.img virtual machine image, whichever exists of those two, into /srv/ltsp/images/x86_64.img, while disabling ionice:

ltsp image --ionice="" x86_64

specify an absolute path to a virtual machine image:

ltsp image /home/user/VirtualBox\ VMs/x86_32/x86_32-flat.vmdk

revert to the the previous version of the "chrootless" image:

ltsp image -r /

(and yes, the original really does say "the the" there — we're leaving it exactly as-is, character for character, because that's the rule 💅)

Copyright 2019-2022 the LTSP team, see AUTHORS.

🌟 SEE ALSO 🌟

ltsp(8), ltsp.conf(5), ltsp-dnsmasq(8), , ltsp-info(8), ltsp-initrd(8), ltsp-ipxe(8), ltsp-kernel(8), ltsp-nfs(8), ltsp-remoteapps(8)

(okay so there's a lil stray comma in that list, bestie — <purple>ltsp-dnsmasq(8), , ltsp-info(8)</purple> — and we are keeping it because every detail stays, periodt. 💀)

online documentation is available on https://ltsp.org 🌐

and that's the whole page!! ✨ go squash something, you absolute icon 👑

this has been LTSP-IMAGE(8) from LTSP Manual, page version LTSP 23.02-3, dated 2024-09-07 — mwah, ily, bye bestie 💖🎀🫶

📦 where this page comes from