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 http://files.bwlp.ks.uni-freiburg.de/satellit/bwlehrpool-server-3.0-ovf.tgz.

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.

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 tool¹⁾ or the vmware disk manager²⁾. “Bridged” is recommended as the network type.

The delivered OVF version can be used directly under VirtualBox ³⁾.

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

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.

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 used⁵⁾. 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.

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.

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 https://bwlp-masterserver.ruf.uni-freiburg.de/webif/.

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.

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.

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 servers (direct access / SOCKS4/5) can be used with and without authentication and configured via a wizard of the web interface.

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

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

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.

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.

The MAC address of the satellite server can be set or generated based on the VM settings of the virtualizer used⁶⁾. 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 bwLehrpoool@hs-offenburg.de to activate your server.

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.

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.

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.

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

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.

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.

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.

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.

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.

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

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

Information on this: exam_mode.

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.

Please refer to chapter ”Select system_configuration“.

Please refer to chapter ”missing_files_of_minilinux-installion“.

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

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

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.

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 ⁷⁾. * Master Password: This password is required when set to edit a boot menu entry by pressing the Tab key.

* 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
KERNEL http://1.2.3.4/kernel
INITRD http://1.2.3.4/initramfs-stage31
APPEND custom=option
IPAPPEND 3

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

Please compare chapter ”storage_location_virtual_machines“.

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 ⁸⁾. * 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.

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.

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

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

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

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.

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.

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

Ohne weitere Angaben	Filter, Beispiel printergui-validate	Filter mit „not“

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 Support⁹⁾, New Devices, and Processors sections.

Client-Statistiken Überblick	Client-Statistiken Beispiel: Defekte Sektoren

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

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

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 2.3.5.1,”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 2.3.3.3.1, “Virtual Machine Location”) without changing the settings. After such a forced mount, the status display should correctly indicate the VM memory usage.

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.

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.

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.

A ready-made base system is available (vmware image, not preallocated, root password “aendermichsofort”)¹¹⁾. 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 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:/ /git.openslx.org/bwlp/setup-scripts.git.

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, bwlehrpool@hs-offenburg.de.