TODO ( Aktuell nur partiell maschinell übersetzt mittels deepl; manuelle Überarbeitung vermutlich erforderlich ;) )

Satellite Server Manual


The satellite server is available in the form of a virtual machine (VM). Currently, virtual machines are delivered in OVF format.

System requirements: see Appendix, "System requirements".
Announcements about updates: Please subscribe to our mailing list to be informed about news.


The current version of the satellite server can be downloaded at

An update may already be available for the last OVF image. Just compare the version number. For information about updating your satellite server, see Updating your satellite server.

virtualization environment

Running the satellite server requires one of the following virtualization solutions:


The OVF format can be imported directly under VMPlayer and VMWare Workstation. For use with ESX, the vmdks are delivered as “preallocated ESX-Type Type 4” by default. For space-saving use with VMPlayer or VMWare workstations, they can be converted to a suitable format using the ESX conversion tool1) or the vmware disk manager2). “Bridged” is recommended as the network type.


The delivered OVF version can be used directly under VirtualBox 3).

Microsoft HyperV

For use with Microsoft HyperV, the OVF format may have to be imported or converted beforehand using the “Microsoft Virtual Machine Converter” 4)).

Surrounding Infrastructure

DHCP-Server / PXE

A DHCP server should be present in the local network. To boot the clients, the local DHCP server must deliver the IP address of the satellite (option next-server or 66) and the file to be loaded pxelinux. 0 (option bootfile or 67). Since a DHCP server is usually already present in the infrastructure, the satellite server itself does not contain a DHCP server by default.

File server (NFS / CIFS / SMB)

The satellite server offers the option of a local NFS server, but it is necessarily quite limited in space. It is therefore advantageous to specify an external NFS or SMB (CIFS) server. NFS requires an NFSv3 share that can be read by the satellite server and read by the clients. The It is also possible to use NFSv4 if the sec=sys option is used5). For SMB/CIFS, it is recommended to create one export on the file server with read/write permission for the satellite server and another with read permission for the clients.


LDAP and AD can be used to authenticate the workstations. Wizards are available for AD and LDAP in the web interface. In addition, the bwIDM service can be used to allow external members of other institutions to sign-in.

Other authentication mechanisms such as NIS can be accessed via a generic module.

Authentication of the client computers

User-specific authentication, e. g. via Active Directory or LDAP within virtual machines, is possible in principle, but is explicitly not planned to keep images standardizable and interchangeable. All necessary authentication is performed by the base system.

Authentication of other services

Please note that for later logon to the satellite server using the bwLehrpool-Suite, a bwIDM access should be registered. This can be done conveniently via the network page

Should your location not be able to participate in the bwIDM identity management service, the bwLehrpool team can set up locally managed accesses for you. However, please use bwIDM if possible.

Required licenses

VMware licensing is required to use the VMware-based virtualization system of the workstations. For appropriate licensing (e. g.“vmware academic license”) it is recommended to contact VMWare.

License server

The use of license server dependent programs should take place within a working environment (virt. machine, image) in which the required license server dependent programs are installed with suitable configuration so that they can access the license server directly.

Proxy server

Proxy servers (direct access / SOCKS4/5) can be used with and without authentication and configured via a wizard of the web interface.

equipment and operation

The delivered image of the satellite server has already been preconfigured as far as possible. Various local passwords are re-created and applied the first time the system is started using the “First Boot” script. However, some local data still needs to be provided. This information is automatically requested with the first root login via the so-called “First Login” script. The further server configuration is done via web-based admin interface.

The "First Boot" script

The “First Boot” script runs automatically the first time the system is started. It generates new ssh keys, starts certain services, generates some internally used passwords (MySQL accesses) and enters them into certain configuration files.

MySQL root password

The MySQL root password created by the First Boot script is stored in the /root/mysqlpass file.

The "First Login" script

The satellite server will be delivered with the default root password “aendermichsofort”. The following points refer to the configuration options queried by the “First Boot” script.

password input

First, you will be prompted for the new root password to be set. For obvious reasons it is recommended to set your own password. This should be of sufficient complexity, possibly contain numbers and special characters and should not be derived from common words.

network configuration

The MAC address of the satellite server can be set or generated based on the VM settings of the virtualizer used6). Network configuration allows you to choose between DHCP-based and static IP configuration. No entry or [Return] keeps the existing IP configuration. Entering 's' leads to static IP configuration; you will be asked to enter IP address, gateway, netmask, domain, search domain, primary and secondary DNS and host name.

The network configuration can also be invoked later by entering 'netsetup'.

The satellite server must be able to access the central master server at the University of Freiburg in order to be able to update the required metadata and the MiniLinux basic system. Conversely, only authorized server installations receive the required data. Therefore, please register the IP address of your satellite server at to activate your server.

The admin interface

The admin interface can be accessed via http://[IP address or server name] or https://[IP address or server name]. It requires Javascript and cookies.

Registration of an administrator account

The admin interface will report at first startup that no administrator access has been registered and offers the possibility of registration. By pressing the “Registration” button, an authorized user can be created for administration. To do this, please enter the desired user ID, password and full name of the user who is authorized to administrate; the entry of a telephone number and e-mail address assigned to this user is optional. After successful registration of the admin user the button “Register” is deactivated.

Attention: For security reasons it is recommended to register the admin user directly after installation of the satellite server and to limit the accessibility of the admin interface to the local network.


Please observe any warnings that may have been given. Click on the corresponding note to go to the appropriate configuration or log page or initiate the appropriate action directly. * DB update: Executes any necessary schema or relationship update. Please always run the DB update first if there are several warnings. * Warning: General warning. Clicking leads to the server log. * Setup incomplete: A necessary configuration step was not executed. Click on it, open the start page or go directly - if known - to the missing configuration step. See also the chapter on initial configuration below.

initial configuration

Both a warning message “Setup incomplete” appears in the upper part of the window and a list of missing configuration items on the start page (“openSLX Admin”). The missing configuration items are usually at the first start: * “No virtual machine location has been defined yet”, * Important files of the MiniLinux installation are missing, * “No system configuration has been selected yet”.

Note: For how to import a saved configuration, see chapter “Sichern und Wiederherstellen der Konfiguration”.

virtual machine storage location

Please indicate here what kind of integration of storage space for the Virtual Machines is desired. You can use one of the following options: * Internal “: The satellite server uses the local directory /srv/openslx/nfs and provides an NFS server. Please note, however, that a single average size virtual image already occupies approx. 20 GB and that the satellite server does not have sufficient space when delivered. In order to use this feature, both the vmdk and root file system must be enlarged. * NFS: Please enter an NFS share that is writable for the IP/host name of the satellite server and readable by the workstations. For configuration examples, click on the question mark icon. * CIFS: Please enter the UNC path and, if applicable, the user ID and password for the read/write access of the satellite and the user ID and password for the read-only access of the teaching pool clients.

Missing files of the MiniLinux installation

No components of the bwLehrpool-MiniLinux to be delivered to the client PCs are available directly after a first installation of the satellite server.

These can be downloaded in the current version by clicking on “Update”. It is also recommended to check from time to time under [Settings], [bwLehrpool MiniLinux] if updates are available. To avoid the need to update the entire system, components can be upgraded individually after deployment.

Please note that the highest downloadable version does not always have to be the best one! If problems occur when booting workstations in low level system features, we recommend that you try a previous version. It can be a great help in troubleshooting when a previous version should work, but not a newer one.

select system configuration

Before you can create a system configuration, modules must have been created that can then be added to the system configuration.

* Active Directory Authentication: Select “Add” if you want the client PC users of the training pool to log in via Active Directory and complete the form provided. Pay attention to the help text provided and don't forget to give the module a descriptive name (“title”). * LDAP Authentication: If you want to log in via LDAP, select “Add” and fill in the form provided. Don't forget to give your module a descriptive title. * Furnishing-specific logo: The furnishings-specific logo is displayed when the teaching pool clients are booted and in the login screen. It must be in svg vector graphics format. You can either upload an svg file directly, or specify a URL pointing to an svg graphic. * SSH daemon: With this module you can control if and how the sshd starts on the booted clients and which functions it provides. If you do not want to use sshd on the clients, you do not need to create such a module. You can specify whether logins with password or only by private key are allowed and on which port the sshd daemon has to listen. In the case of key-based authentication, the Web interface naturally expects the public key to be entered. * Add generic module: Using a module defined here, arbitrary files can be added to the basic Linux system of the clients. The directory structure given in an archive uploaded here will be extracted one by one into the booted Linux; a file contained in the archive at etc/example.conf will appear in the booted system under /etc/example.conf. This is the right place for location-specific settings. After uploading, the contents of the archive are displayed for control purposes. For more information, see Generic_module.

After creating the desired configuration modules, a system configuration can now be configured with “New configuration”. can be created. Select the desired configuration modules via radio button, assign a name to the corresponding configuration and press “Next”. You should now receive a message “the configuration has been created successfully”; below you can choose, whether you want to set this configuration as global configuration or (in case of a further configuration) further, i. e. back to the overview.

* Note: You can easily create multiple configurations for your room_configuration or simply for test purposes, and easily change them under [Settings], [Localization + Integration] by pressing “activate”. The symbols used are explained in the legend below; hovering the mouse pointer over a symbol provides brief instructions (“tool tip”).

The basic configuration is finished at this point. However, it is recommended that within the framework of the Extended configuration options, pay particular attention to the configuration_variables.

advanced configuration options

Invalid Link
Administrator interface startup screen

The web interface offers a variety of additional configuration options. Although these are not necessarily necessary in individual cases, they allow further adjustments of the system, enable messages to be sent to the teaching pool clients, allow sub-configurations for individual locations or computers, move rooms to check mode and much more.

You can also save the imported configuration here. It is highly recommended that you save after all types of configuration changes. How about - now?

Last but not least, sophisticated client logging is available.

vmChooser-News and Help

Under [Settings], [vmChooser News] you can set messages and a help page that appear in the client-side message or help window of the vmChooser (selection program of the work environments, i. e. courses containing virtual machines). Current messages can be entered without losing older messages. Older messages can be displayed again by pressing the “View” button. For formatting the message texts or help, highlighting and markups are available (accessible via the control bar above the text field). HTML code can be entered or edited directly.

* Note: If you want to display an older message again, click on “View” to display the older message, edit it if necessary and press “Save”.

The help text is entered in the same way.

rooms / places

For information on how to handle rooms and locations and the possibility of creating system configurations for individual computers and rooms, see here.

room planner

The spatial conditions of the pool rooms can be traced in the room planner. Further information can be found there.

check mode

Information on this: exam_mode.

bwLehrpool suite

This main menu item includes settings that affect the Behavior of the bwLehrpool-Suite, the program for editing virtual machines and lectures. A log of the bwLehrpool Suite actions is also available.

localization + integration

Please refer to chapter ”Select system_configuration“.

bwLehrpool-Minilinux - update

Please refer to chapter ”missing_files_of_minilinux-installion“.

configuration variables

Under[Settings], [Configuration variables], you can set the Client behavior influencing variables.

PXE boot

At this point, general settings of the PXE boot behavior can be made.

boot address of the server

From a selection of the IP addresses available to the server, you can select an address via which the server is to be addressed by the clients when booting. Normally, this selection is limited to a single IP address.

Please make sure that an IP address is marked as active (green button with check mark and label “Active”), even if only one IP address is listed in the list. To do this, click on the blue “Set” button behind the IP address in question.

boot menu

At this point, you can make adjustments to the appearance of the boot menu displayed on the client. * Standard boot behavior: Possible settings are “bwLehrpool” (default setting),”Local HDD“. (after the menu timeout has expired, boot from hard disk (see below) and “My own entry / custom”. * Display time of the menu: Defines the timeout of the menu display in seconds, i. e. after this time has elapsed, the entry specified in “Standard boot behaviour” is started. Entering a zero (“0”) does not represent a time-out 7). * Master Password: This password is required when set to edit a boot menu entry by pressing the Tab key.

Attention: Since this editing option allows manipulation of the client's boot process, a password should be set here!

* User-defined menu option: here you can enter your own menu code, which is then added to the PXE menu displayed on the client side. The format corresponds to the syslinux menu format. Any number of menu entries can be specified; for example, to refer to another PXE server. If you want to create an entry that should be started automatically after the timeout, this entry has to be labelled “custom” and the default boot behavior has to be set to “custom”.

Sample entry:

LABEL custom
MENU LABEL ^Custom menu boot entry
APPEND custom=option

After pressing “Create boot menu” a new boot menu is generated. This can take up to one minute.

VM location

Please compare chapter ”storage_location_virtual_machines“.

Web interface

This menu item deals with the configuration of the admin interface. The possible configurations here refer to the https configuration and the masking of passwords.

The server does not provide access via https directly after the initial configuration. The use of https is of course highly recommended!

* If a certificate is already provided for use, it can be inserted via the menu item “Own certificate” via clipboard. Please note that in this case, the certificate and key must be in base64-encoded x509 format (also known as “pem”). * Optionally, the certificate chain associated with the certificate (CA chain) can also be specified if the certificate has not been signed by one of the CAs contained in standard browsers. This file, which contains one or more blocks, must be in the same format as the certificates mentioned above. * If there is no own certificate, possibly even signed by a CA chain, the server can also generate its own self-signed certificate. In this case, this certificate must of course be accepted by the user the first time the admin interface is accessed via https 8). * If https has been configured, but it should no longer be used, a configured https can be deactivated via the menu item “Deactivate https”. With regard to the password settings, you can configure whether or not to mask password fields of the admin interface. If the interface is used in a secure environment, i. e. without third party insight, non-masking can increase comfort and reduce bothersome prescribers. By default, passwords are masked. Note: The password field of the login screen is excluded from this setting and is always masked.

Backing up and restoring the configuration

The options for backing up and restoring a configuration can be found under[Settings], [Backup/Restore]. A backup contains the database entries of the work environments and events, the configuration of the VM store and the MiniLinux configuration.

Attention: The contents of the VM store are not saved.
Save the configuration

A backup file in tgz format (tar with gz) can be downloaded by clicking on “Save”. It is recommended that you store these separately.

import of a configuration backup

If a secured configuration of a satellite server is available, it can be restored under the menu item Settings,”Backup/Restore“.

Attention: By importing a backup, the registered admin user is replaced by the admin user contained in the backup!

status messages / monitoring

All satellite server status messages can be accessed via the “Status” drop down menu.

server status, server reboot

The information given here is divided into the following areas:

* Storage space: Here you can find information on the percentage utilization rate of both the system partition of the satellite server and the storage location of the virtual machines used in each case. The VM location utilization display also applies to externally attached memory (nfs or smb/cifs). * Note: If you are using a dnbd3-based VM storage space solution, both displays may be identical. * Address configuration: Displays the IP addresses of the locally available interfaces, IP v4 and IP v6. * Services: Status display of the active services (currently only for LDAP-AD proxy). * System: Displays the uptime of the satellite server, the percentage CPU load (current load and average, number of logical CPUs), the RAM utilization (percentage usage, total in MiB, free in MiB) and the swap usage (percentage usage, total in MiB, free in MiB). * Maintenance: Here a server reboot can be triggered.

Furthermore, in the “Advanced / Debug” section of this site you will find logs of the dmsd service, the AD/LDAP proxy and the output of the “netstat -tulpn” and “ps auxf” commands.

server log

From left to right, the server log contains an information icon, a timestamp, the name of the event, and possibly an icon to the right that provides additional information when printed. Hovering the mouse pointer over the information icon on the left provides information about the severity of the event (possible values:“info”,”warning“ and “error”). For a better overview, the “warning” and “error” messages are highlighted in color.

Note: Warning messages do not necessarily have to limit server operation, but they should be followed up. The “error” messages indicate serious problems that can seriously affect the operation of the satellite server.

client log

From left to right, the client log displays an information icon, a timestamp, the IP address of the respective client, the name of the event, and, if necessary, an icon to the right that displays additional information about the event when you click on it. .

Events can be filtered for a better overview. Filtering requires the input of an event ID. This event ID can be determined by hovering the mouse pointer (“mouse-over”) over the information icons on the left; a click on the information icon transfers the event ID directly to the filter line. However, an event ID can also be entered into the filter line via keyboard, in this case it must be acknowledged with Enter before pressing “Go”. Filtering by event IDs can be inverted by setting a checkmark at “not”.

You will quickly get a feel for the IDs appearing in your installation, if you set the “not” check mark, accept the IDs in order of their occurrence by clicking on the filter line and press “Go” in each case. You can transfer any number of IDs to the filter row.
Ohne weitere Angaben Filter, Beispiel printergui-validate Filter mit „not“

client statistics

Here you can find a lot of statistical information about clients served by the satellite server and currently being used. At the top of the screen is a brief summary of the system's known client computers, started clients and clients in use, possibly followed by a highlighted warning message, so hard disks with more than ten bad sectors have been seen. A history display below provides a brief overview of the last 24 hours.

Further statistics can be viewed at a glance from the Memory, Temporary Partition (s), 64bit Guest Support9), New Devices, and Processors sections.

All blue displayed expressions are provided with links to further statistics!
Client-Statistiken Überblick Client-Statistiken Beispiel: Defekte Sektoren



Minimal Empfohlen Optimal
CPUs 1 2 4
RAM 1 GB 2 GB 4 GB
Netzanbindung 100 MBit 1 GBit – 10 GBit 10 GBit


22 ssh global/lokal Wartungszugang
80 http lokal Admin-Schnittstelle
111 rcp lokal NFS-Mounts
443 https lokal Admin-Schnittstelle
2049 nfs lokal NFS-Server
3100+10) ldap lokal ldap-zu-AD-Proxy
9090 dozmod (thrift) global bwLehrpool-Suite
9091 dozmod (thrift), ssl global bwLehrpool-Suite, gesicherte Verbindung
9092 dozmod global bwLehrpool-Suite, Dateitransport
9093 dozmod global bwLehrpool-Suite, gesicherte Verbindung
Anmerkung: Wenn Dozierende von außerhalb des lokalen Netzes VMs hochladen bzw. Veranstaltungen verwalten sollen, müssen die Ports 9090 bis 9093 von außerhalb erreichbar sein.

Zusätzlich muss die Kommunikation mit dem zentralen Masterserver in Freiburg ermöglicht werden. Dazu müssen folgende Ports ausgehend freigegeben sein.

443 https global Masterserver
9090 dozmod (thrift) global bwLehrpool-Suite
9091 dozmod (thrift), ssl global bwLehrpool-Suite, gesicherte Verbindung
9092 dozmod global bwLehrpool-Suite, Dateitransport
9093 dozmod global bwLehrpool-Suite, gesicherte Verbindung

Konfiguration der Lehrpool-PCs

BIOS settings

* Activate the option “Intel Virtualization Technology (VT-x) and, if available, VT-d (Intel Virtualization Technology for Directed I/O) in the BIOS of the teaching pool computers (CMOS settings). 64bit virtual machines cannot be started if these options are not activated or not supported by the respective computer. * It is recommended to switch from UEFI to BIOS or legacy boot, because UEFI is currently not supported. Attention: This can lead to the possibility that local operating systems may have to be reinstalled or the bootloader used may have to be adapted.

PXE/network should be set first in the boot sequence.


In principle, the bwLehrpool system can also be run on hard-disk-free computers with sufficient RAM. Nevertheless, it is recommended to create a partition for temporary storage. The following partition types are automatically recognized as. temp. memory and included:

* MBR partitions of ID 44 (hex), or * GPT partitions bearing the label “OpenSLX-ID44”.

* The recommended size of these partitions is 20-50 GB. * Optimum partition size: 50-70 GB or as large as the largest virtual image in use.

For more information on using temp. partitions, seehere; a brief overview of the client PC hardwarehere.


Known problems and their remedies are summed up here.

Work environment does not start (nfs)

It was reported that in very rare cases the nfs share was not mounted correctly after a restart of the satellite server. In this case, no client-side display of available work environments occurs after the user login.

Verification of the problem: The satellite's status page (see Chapter,”Server Status, Server Reboot”) does not show a VM memory load, but an error message such as “Error: Cannot mount VM location”.

Troubleshooting the problem: Under [Settings], [VM Storage Location]. (see section, “Virtual Machine Location”) without changing the settings. After such a forced mount, the status display should correctly indicate the VM memory usage.

Upload aborts at 0%

If the upload of a working environment via bwLehrpool-Suite terminates at 0% with error message, it is recommended to check the permissions of the directory /srv/openslx/nfs. This should be assigned to the owner dmsd and the group images in the rights (0)775.

file system enlargement

If the disk space provided to the satellite server is too small, you will find here a brief enlargement guide. Of course, this should mainly occur when storing virtual machines internally.

satellite server development version

If you want to set up your own satellite server, you can build a test version with the latest available sources. As a basis, you need a Debian 7.7 or 7.8 either physically or in the form of a virtual machine (virt. machine recommended). We consider approx. 5-6 GB of space for the system partition plus a swap partition to be sufficient (see appendix, chapter 3.1, System requirements). The use of a 64bit debian should be possible without any problems, but we have not tested it in individual cases.

Please note that we can of course provide more difficult help for home-made satellites than in the case of an image that we deliver and verify.

Prefabricated Debian base system

A ready-made base system is available (vmware image, not preallocated, root password “aendermichsofort”)11). Please note, however, that we do not guarantee the timeliness, usability or availability of this image in general - in case of doubt, you may prefer to create your own image.

The automatic build script

The automatic build script can be downloaded via git. Switch to a directory of your choice, since root privileges are required for building, the hierarchy under /root is recommended. Make sure git is installed and run the command git clone git:/ /

Start of the build script

After executing the git command, change to the created directory setup-scripts/satellit_installer, and execute the shell script satellit_installer with the option -version “Version string”. The specification of a version string is mandatory. Trigger a reboot at the end of the script and continue with Chapter 2, Setting Up and Operating the Satellite Server.


The bwLehrpool team (bwEKlausuren) is pleased about feedback, comments, criticism, bug reports and compliments not only concerning this manual.

Please contact the project team bwLehrpool / bwEKlausuren,

vmware-vdiskmanager ships with VMWare-Workstation. See; list of vmdk types
Depending on the environment, it may be necessary to create a group on the NFS server called “images” with numeric gid 12345 and a user “dmsd” with numeric uid 10001. The primary group of the user “dmsd” should be the group “images”
VMWare player and ESX offer the possibility to generate a MAC. This is also done if “machine has been copied” is specified at the first start of the image under VMPlayer/Workstation/ESX.
To be precise, there is then a timeout of approx. 10 years - to be exact
Delivers the familiar message “This connection is not trusted / I know the risk” in Firefox or its equivalent in Internet Explorer / Opera etc.
Whether 64-bit VMs are supported
Der erste ldadp (ldap-AD-Proxy) belegt 3100; eventuelle weitere belegen 3101, 3102 usw.