plucky (5) ltsp.conf.5.gz

Provided by: ltsp_23.02-3_all bug

NAME

       ltsp.conf - client configuration file for LTSP

SYNOPSIS

       The  LTSP  client  configuration  file  is  placed at /etc/ltsp/ltsp.conf and it loosely follows the .ini
       format. It is able to control various settings of the LTSP  server  and  clients.  After  each  ltsp.conf
       modification,  the  ltsp  initrd command needs to be run so that it's included in the additional ltsp.img
       initrd that is sent when the clients boot.

CREATION

       To create an initial ltsp.conf, run the following command:

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

       The optional -g sudo parameter allows users in the sudo group to edit ltsp.conf  with  any  editor  (e.g.
       gedit) without running sudo.

SYNTAX

       Open  and  view the /etc/ltsp/ltsp.conf file that you just created, so that it's easier to understand its
       syntax.

       The configuration file is separated into sections:

              • The special [server] section is evaluated only by the ltsp server.

              • The special [common] section is evaluated by both the server and ltsp clients.

              • In the special [clients] section, parameters for all clients can  be  defined.   Most  ltsp.conf
                parameters should be placed there.

              • MAC address, IP address, or hostname sections can be used to apply settings to specific clients.
                Those support globs, for example [192.168.67.*].

              • It's also possible to group parameters into named sections like [crt_monitor]  in  the  example,
                and reference them from other sections with the INCLUDE= parameter.

              • Advanced  users  may also use [applet/host] sections, for example [initrd-bottom/library*] would
                be evaluated by the ltsp initrd-bottom applet only for clients that have a hostname that  starts
                with "library".

       The  ltsp.conf  configuration file is internally transformed into a shell script, so all the shell syntax
       rules apply, except for the sections headers which are transformed into functions.

       This means that you must not use spaces around the "=" sign, and that you may write  comments  using  the
       "#" character.

       The  ltsp  initrd command does a quick syntax check by running sh -n /etc/ltsp/ltsp.conf and aborts if it
       detects syntax errors.

PARAMETERS

       The following parameters are currently defined; an example is given in each case.

       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  shouldn't  be
              included     in     the     generated     image.     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.

       CRONTAB_x="30 15   * * *   root    poweroff"
              Add a line in crontab. The example powers off the clients at 15:30.

       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.

       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.

       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.

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

       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 ⟨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

       To specify a hostname and a user to autologin in a client:

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

       The password above is "pass01" in base64 encoding. To calculate it, the  base64  command  was  run  in  a
       terminal:

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

       If  some clients need a custom xorg.conf file, create it in e.g.  /etc/ltsp/xorg-nvidia.conf, and put the
       following in ltsp.conf to dynamically symlink it for those clients at boot:

       [pc01]
       INCLUDE=nvidia

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

       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.

       [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

       Copyright 2019-2022 the LTSP team, see AUTHORS.

SEE ALSO

       ltsp(8),  ltsp-dnsmasq(8),  ltsp-image(8),  ltsp-info(8),  ltsp-initrd(8),  ltsp-ipxe(8), ltsp-kernel(8),
       ltsp-nfs(8), ltsp-remoteapps(8)

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