.nh
.TH LTSP-IMAGE 8 "2023-08-19" "LTSP 23.02-1+deb12u1" "LTSP Manual"
.SH NAME
.PP
\fBltsp image\fP - generate a squashfs image from an image source

.SH SYNOPSIS
.PP
\fBltsp\fP [\fIltsp-options\fP] \fBimage\fP [\fB-b\fP \fIbackup\fP] [\fB-c\fP \fIcleanup\fP] [\fB-i\fP \fIionice\fP] [\fB-k\fP \fIkernel-initrd\fP] [\fB-m\fP \fImksquashfs-params\fP] [\fB-r\fP \fIrevert\fP] [\fIimage\fP] ...

.SH DESCRIPTION
.PP
Compress a virtual machine image or chroot directory into a squashfs image,
to be used as the network root filesystem of LTSP clients. It's used in
similar fashion to live CDs, i.e. all clients will boot from this single read
only image and then use SSHFS or NFS to mount /home/username from the server.

.SH OPTIONS
.PP
See the \fBltsp(8)\fP man page for \fIltsp-options\fP\&.

.TP
\fB-b\fP, \fB--backup\fP=\fI0|1\fP
Backup /srv/ltsp/images/\fIimage\fP\&.img to \fIimage\fP\&.img.old. Defaults to 1.

.TP
\fB-c\fP, \fB--cleanup\fP=\fI0|1\fP
Create a writeable overlay on top of the image source and temporarily
remove user accounts and sensitive data before calling mksquashfs.
Defaults to 1.

.TP
\fB-i\fP, \fB--ionice\fP=\fIcmdline\fP
Set a prefix command to run mksquashfs with a lower priority, or specify
"" to disable it completely. Defaults to \fB\fCnice ionice -c3\fR\&.

.TP
\fB-k\fP, \fB--kernel-initrd\fP=\fIglob-regex\fP
Pass this parameter to the \fB\fCltsp kernel\fR call after the squashfs creation.
See ltsp-kernel(8) for more information.

.TP
\fB-m\fP, \fB--mksquashfs-params\fP=\fI"params"\fP
Pass \fI$params\fP to the mksquashfs call unquoted; so \fIparams\fP shouldn't
contain spaces. See mksquashfs(1) for more information.

.TP
\fB-r\fP, \fB--revert\fP[=\fI0|1\fP]
Move /srv/ltsp/images/\fIimage\fP\&.img.old to \fIimage\fP\&.img and call
\fB\fCltsp kernel image\fR\&. Useful when the clients won't boot with the new image.

.SH IMAGE TYPES
.PP
There are three "image" types in LTSP, in the following locations. The
/srv/ltsp path can be configured using \fB\fCltsp --base-dir=\fR:

.TP
\fB/srv/ltsp/\fIimg_name\fP\&.img\fP
Source images are placed directly under /srv/ltsp and usually are symlinks
to virtual machine raw disk files. They're only used by \fB\fCltsp image\fR\&.

.TP
\fB/srv/ltsp/\fIimg_name\fP\fP
Chroot directories can be used both as sources for \fB\fCltsp image\fR and as
NFS root exports for the clients.

.TP
\fB/srv/ltsp/images/\fIimg_name\fP\&.img\fP
Exported images (usually squashfs) are placed under the images directory and
the clients can netboot from them.

.PP
Images can be specified as simple names like \fB\fCltsp image img_name\fR, in which
case the aforementioned locations are searched, or as or full paths like
\fB\fCltsp image ~/VMs/vm.img\fR\&.

.PP
The supported image types result in the following three methods to use LTSP.
You may use either one of the methods or even all of them at the same time.

.SH CHROOTLESS
.PP
Chrootless LTSP, previously called "ltsp-pnp", is the recommended way to
maintain LTSP \fBif\fP its restrictions are acceptable.
In this mode, the server operating system itself is exported into a squashfs
file and used for netbooting all the clients. You, the sysadmin, would use
the typical GUI tools to manage the server, like software centers or update
managers. Then whenever necessary, you'd run:

.PP
.RS

.nf
ltsp image /
.fi
.RE

.PP
This creates or updates /srv/ltsp/images/x86_64.img (the arch name comes from
\fB\fCuname -m\fR). Then, all the clients should be able to boot from x86_64.img
and have a desktop environment identical to the server.

.PP
The big advantage of the 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.

.PP
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.

.PP
If for some reason you prefer a different name to \fB\fCuname -m\fR, you may create
a symlink:

.PP
.RS

.nf
ln -s / ~/amd64
.fi
.RE

.PP
\&...and run \fB\fCltsp image ~/amd64\fR instead.

.SH VM IMAGES
.PP
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:

.PP
.RS

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

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

.PP
.RS

.nf
ltsp image debian
.fi
.RE

.PP
It's also possible to omit the symlink by running:

.PP
.RS

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

.PP
\&...but then the image name shown in the iPXE boot menu would be
"debian-flat", which isn't pretty.

.PP
In summary, you may symlink raw VM disks in /srv/ltsp/img_name.img, and
\fB\fCltsp image img_name\fR 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 \fB\fCltsp image\fR, 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!

.SH CHROOTS
.PP
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 \fB\fCltsp-build-client\fR LTSPv5 tool no longer
exists. LTSP users are invited to create appropriate documentation in the
community wiki
\[la]https://github.com/ltsp/ltsp/wiki/chroots\[ra]\&.
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

.PP
.RS

.nf
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"
.fi
.RE

.SH EXAMPLES
.PP
Use the server installation as a template to generate a client image
(chrootless, previously called ltsp-pnp):

.PP
.RS

.nf
ltsp image /
.fi
.RE

.PP
Inform \fB\fCltsp image\fR that a chrootless installation uses separate /boot and
/opt partitions:

.PP
.RS

.nf
ltsp image /,,/boot,subdir=boot,,/opt,subdir=opt
.fi
.RE

.PP
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:

.PP
.RS

.nf
ltsp image --ionice="" x86_64
.fi
.RE

.PP
Specify an absolute path to a virtual machine image:

.PP
.RS

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

.PP
Revert to the the previous version of the "chrootless" image:

.PP
.RS

.nf
ltsp image -r /
.fi
.RE

.SH COPYRIGHT
.PP
Copyright 2019-2022 the LTSP team, see AUTHORS.

.SH SEE ALSO
.PP
\fBltsp\fP(8), \fBltsp.conf\fP(5), \fBltsp-dnsmasq\fP(8), ,
\fBltsp-info\fP(8), \fBltsp-initrd\fP(8), \fBltsp-ipxe\fP(8), \fBltsp-kernel\fP(8),
\fBltsp-nfs\fP(8), \fBltsp-remoteapps\fP(8)

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