Administration of Virtual Machines and Events

To make the administration of virtual machines and events in bwLehrpool easier, we provide a java program, the bwLehrpool-Suite. This software makes it possible to download and upload virutal machines, create events, set permissions and more.

The bwLehrpool-Suite (sometimes referred to simply as Suite or Instructors' Module (Dozentenmodul)) is a bwLehrpool internal client application for the creation of virtual machines for study and coursework. With the help of the Suite it is possible to download ready-to-use templates, which you can then adapt locally for your purposes. The Suite is then used to upload these personalized VMs to the bwLehrpool Server, create a new event and link the VM to it. Additionally, permissions can be set to allow selected or all users to use the VM.

As opposed to other systems, the use of the bwLehrpool computer pools are not centered on individual VMs, but on Events. So let's explain quickly what we mean when we refer to Events in this context. After successfully logging on, you will find yourself at the Start windows of the bwLehrpool-Suite. From here you can sqitch to a list of either the available VMs or events. You can always return to this screen by selecting the [Ansicht] (View) from the menu.

Within bwLehrpool, the terms Virtual Machine (VM), Image and “Abbild” are used interchangeably. An Image is the virtual HDD for the course environment. Usually this refers to a file with the extension “.vmdk”. This file contains the installed operating system (OS), as well as any other software the creator installed. Additionally there may be further files containing metadata that is required by VMWare Player for the execution of the VMs (recognizable via the extensions “.vmx”, “.vmxf”, or “.nvram”). Therefore, a virtual machine exists of the image and the associated Metadata.

When we talk about Events, we are talking about metadata (descriptive information). This metadata contains, e.g., the display name and the period of validity of your course environment. Events are entries that students using computers in the pool rooms can choose to start using the vmChooser program. Events are only visible in the pool rooms during the time period defined in the Event. Multiple Events can be defined containing the same virtual machine. An Event can therefore in the bwLehrpool context be said to describe a lecture or exam.

bwLehrpool-Suite: Workflow diagram (principally speaking, first create a virtual machine, then link an event to it).

The bwLehrpool-Suite was tested under the operating systems Linux (div. distributions), Windows (7, 8, 8.1, 10) and Apple OS/X. To run the bwLehrpool-Suite, you need the Java Runtime Environment. If you want to download and customize virtual machines locally, you will also need VMWare Player or VMWare Workstation. A link to recommended versions of the VMWare Player can be found inside bwLehrpool-Suite under the menu item „Über“ (About).

The latest version of the bwLehrpool-Suite can be downloaded here.

Before using bwLehrpool-Suite the first time, you must register for the bwLehrpool service Registration (via bwIDM). We would be pleased if you took part in the state-wide sharing of virtual machines; After registering you can start the bwLehrpool-Suite. When you are asked what you want to use for authentication, choose „Authentifizierung über bwIDM“. Under „Identity Provider“ select your institution and enter your normal university credentials. Then click on „Login“.

bwLehrpool-Suite: Login window

If your institution is running more than one satellite server, after you log in you will see a second chooser window. Then you will arrive at the start window for bwLehrpool-Suite. From here you can go directly to the list of available virtual machines or events. You can return to this screen at any time by selecting [Ansicht] from the menu.

bwLehrpool-Suite: Selection Screen (Virtual Machines and Events)

• You can use the [Sitzung] (Session) menu item to configure your program settings, log off or exit the Suite.

bwLehrpool-Suite: Menu bar

• You can return to the Start page or switch between viewing the list of virtual machines or events by choosing [Ansicht] from the menu.
• Within the [Über] menu are the following options: Clicking [Virtualisierer] will take you to a site where you can download the VMWare Player. [Nutzervereinbarung] will show you the details of the user agreement and clicking on [Software-Aktualisierung] will check to see if there is a newer version of the program available. Existence of newer versions of bwLehrpool-Suite will also be indicated on the lower window edge when the program is running.
• In the upper right of the program window you can see the current memory usage of the bwLehrpool-Suite, as well as the amount of storage space remaining on the satellite server. If the satellite server runs out of disk space, it will not be possible to upload a new virtual machine.

bwLehrpool-Suite: User Settings

This menu item can be used to set user settings for use by the bwLehrpool-Suite, such as E-Mail notification.

• E-Mail notification is activated by default. You will be informed of important information regarding your virtual machines and events. These could be actions like the upcoming automatic deletion of a VM or the approaching end date of an event. If you do not want to receive email notifications you can disable this option. Please be aware, though, that if you do this you will not be informed when changes are being made to your VMs or Events!

• Under specific circumstances the proxy settings of the host computer can cause a delay to the start of the bwLehrpool-Suite. If no proxy is needed in your network, you can turn off this option by setting „Keinen Proxy verwenden“.

• If the upload of a VM to the satellite server isn't using the full potential of your network connection, you can increase the number of connections per transfer (Verbindungen pro Transfer). Be aware, though - setting the number of connections too high can have a negative effect.

Whenever possible, use a previously existing tempate from the bwLehrpool-System as a starting point when you are creating a new VM for a course. This will save you not only the initial installation of the operating system, but also the effort of having to adapt a generic install to the needs of the bwLehrpool environment (e.g., automatic monitor resolution detection, deactivation of unused services, etc). The creation of a completely new VM and the settings required for bwLehrpool is not currently covered in this wiki. For further information refer to the article Erstellen neuer Virtueller Maschinen (currently available only in German).

bwLehrpool-Suite: Overview Virtual Machines

If you want to download a pre-existing VM (e.g. a template), switch to „Übersicht Virtuelle Maschinen“ (Overview of Virtual Machines). You can scan through this list or filter on selected criteria.

Once you have decided on a VM, click on the “Download” button in the ribbon at the bottom, or right click on the VM and choose “Download”. When the download starts a loading bar will open at the bottom of the display so that you can monitor the progress. When the download is complete you can open the directory containing the file directly or close the progress bar.

Use VMWare Player to open, start and edit the VM as desired.

When you are done editing your VM and ready to upload it, return to „Übersicht Virtueller Maschinen“ (Overview of Virtual Machines) and click on „Neue VM“. An assistant will walk you through the necessary steps. Give your VM a meaningful name ¹⁾ and add a description so that other users and especially the administrators of the bwLehrpool service understand the intended use of the VM. Finally, you will have the chance to set the permissions for your VM.

bwLehrpool-Suite: Permissions for other users

In the example to the right, the user „Christian Rößler“ has the same permissions as the creator of the VM. He can create an event attached to this VM, edit the name or description, and delete the VM. The Admin check box also lets him change the permissions of other users (compare this with the user „Jonathan Bauer“ who does not have Admin rights). The user „Simon Rettberg“ can only link or download the VM, he can't edit it. All other users of the system can only download the VM.

Click on „Fertigstellen“ to start the upload. You can then shut the window and continue to work with the Suite - your upload will continue in the background.

If you want to update a VM that is already in bwLehrpool, you don't need to start with a completely new VM. You have the possibility of providing an updated version.

To upload a new version of an existing VM, go to the detail view of your VM either via double-click or choose the “Bearbeiten” menu item for the detail view of the existing VM. Then choose „Neue VM-Version hochladen“. The advantage of this is that all events that are linked to this VM will then reference the current/updated version. ²⁾. Older versions of the VM will continue to be saved for a period of a few days on the satellite server, before they are automatically deleted and the storage space recovered. You can immediately delete a version by right-clicking on its entry in the detail view and choosing „Löschen“.

To edit the metadata of an existing VM, double click on its entry in the list or choose „Detailansicht“ (Detail View) in the lower ribbon. Depending on the permissions of the selected VM you can change the name, the description or the type of the OS. You may also be able to change the permissions or the owner of the VM itself.

Click on the displayed username to send an email to the owner of the VM.

Select the desired VM from the list of virtual machines and click on “Löschen” (Delete) in the lower ribbon. This will delete all existing versions of the selected VM. If there is an event linked to this VM, it will be deactivated. Deactivated events can be linked to new/different VMs and reactivated.

When you upload a VM, in addition to the virtual HDD ('vmdk'), the associated configuration file ('vmx') will also be saved in two parts - the metadata saved on the server side doesn't contain all the values that are in the file on your local computer. For example, the size of the RAM or the number of the processors for the specific bwLehrpool-Client the VM will run on aren't yet known and so reasonable values cannot be entered into the configuration file. This is handled automatically by beLehrpool when the VM is started in a PC pool. That is why there is no point in saving these or values at the server level.

If you want to know which parts of the vmx are saved on the satellite server or if you want to edit these yourself, you can open the detail window for your VM. Right click on the current version of the VM and choose 'VM-Konfiguration'. Via the user interface you can adjust the values, such as for example the hardware version via a simple drop down menu. If you want to change further settings, click on 'Expertenmodus'.

bwLehrpool-Suite: General Settings for Events

Before your virtual machine can be booted in the PC pool, you must create an event. Change to the list of events and then choose „Neue Veranstaltung“ (New Event) from the lower ribbon ³⁾. An assistant will walk you through the following steps.

Give your event a meaningful name and description. The name you give your event will be visible in the vmChooser in the PC pools. Event names and descriptions will also be scanned for the search functionality of the vmChooser.

An event is available for a specified time. Therefore you must give your event a start and end time. The start time can be in the future, if you don't want the event to be available immediately.

Then, you can choose which VM should be started when your event is selected. If you want to accept the default responses with respect to additional options, permissions and room selections, you can click directly on „Fertigstellen“ (Publish); otherwise, to continue, click „Weiter“ (Continue).

bwLehrpool-Suite: Limitations (network, external drives, e-exams

• The option „Immer auf aktuellste Imageversion updaten“ (Always update to the latest image version) means that this event will always been linked to the newest version of your chosen VM. If you deactivate this option, the event will always include the original version of the VM. If you upload an updated version (e.g., containing security patches or other fixes), your event will continue to reference the old version. Please note that outdated versions are automatically deleted after a period of days. Then you will have to manually link your event to a different VM or to the newly updated version⁴⁾ or your event will be automatically deactivated.
• You can temporarily deactivate your event by deselecting the „Vorlesung ist aktiv“ (Event is active) check box. Then your event will no longer be displayed in the vmChooser.
• If your event is intended for use as an e-exam, set the check mark next to „Veranstaltung ist eine Prüfung“ (Event is an exam). This will ensure that the event does not appear as a normal event, but rather only in the specific rooms that are set to the special Exam Mode by a bwLehrpool Admin.
• „Netzwerk-/Internetzugriff zulassen“ (Allow network/internet access): Set a check here if your event should have internet access and remove it if not.
  • „Ausnahmen“ (Exceptions): If you have enabled network/internet access, you can register specific blocks here; if you disabled access, you can register specific allowances. These are defined on a socket basis (Host and Port). Take special note of the tips in the pop-up window when you click on “Ausnahmen” (Exceptions).
• „Speichermedien zulassen“ (Allow portable data carriers): Set a check mark if your event should allow access to CDROMs, DVDs or USB storage devices. Remove the check mark to disable access.

Under the options „Berechtigungen festlegen“ (Set permissions) and „Raumauswahl“ (Room selection) please compare the descriptions of the subitems Permissions und Room Selection.

To edit an event after configuration choose your event from the list and then click on „Bearbeiten“ (Edit), or simply double click the event. In the newly opened sub window you will have tabs „Übersicht“ (Overview), „Allgemein“ (General), „Beschränkungen“ (Constraints), „Raumauswahl“ (Room selection), „Startskript“ (Start script) and „Berechtigungen“ (Permissions).

Of course, changing any of these settings will be dependent on your user having the appropriate permissions.

bwLehrpool-Suite: Event Overview

The overview displays the following settings for the selected event:

• Owner,
• Creation Date,
• Name of the person making the changes,
• Date of the last change,
• Name of the VM that will be started in this event,
• Start date of the event,
• End date (Expiration date) of the event and
• Number of calls to the event.

The start date can be in the future, if the event should only be available during a specific period. If a name is shown in blue type and in your OS a default mail client is defined, you can send that person an email by clicking on their name.

bwLehrpool-Suite: General Settings

The fundamental details describing an event can be found under „Allgemein“ (General). Fields with white backgrounds can be edited directly; the button “Speichern” (Save) is initially greyed out but will be activated when the program detects a change.

• Name: The name of the event as it will appear in vmChooser, the bwLehrpool user interface used to select a VM to boot in the PC pools. Please use a meaningful, but succinct name. The name you use will be searchable via the search function in vmChooser.
• Beschreibung (Description): Edit the description here. This field is much bigger than the name of the event so you can use complete sentences and/or multiple keywords. This field will also be searchable using the search functionality of the vmChooser. For that reason your search may match on terms that are not contained in the event name.
• ID: The ID of an event is for internal purposes and cannot be changed. This ID will not generally affect your use of the system.
• Besitzer (Owner): If you are the owner of an event (or a satellite server admin), you can assign a new owner to an event. If your system has a default standard mail client defined you can send an email to the person by clicking on their name when it appears in blue type.
• Verknüpfte (Linked) VM: Clicking on „Ändern“ (Edit) opens a list of the VM that are available to you. To change the VM, select the VM of your choice and then click „Übernehmen“ (Accept).
• VM Version: If the check box next to „Immer aktuellste Version verwenden“ (Always use latest version) is not set and you have uploaded multiple versions of your VM, you can choose previous versions of the VM. This is an easy option to return to a previous version, if, for example, during your course you discover that the latest version of the VM is not meeting your demands. Normally we do recommend that you select the option „Immer aktuellste Version verwenden“ so that any changes you make to the VM such as updates are automatically used for your event.
• Start date / End date: You can choose custom start and end dates for the visibility and use of your event. An event is only presented in the vmChooser as an option if the current date falls in the range listed and so it is very easy to change the visibility of your event or limit it to a specific time frame. The start date can be in the future (and then the event will not be available until the listed date.)
• Veranstaltung aktiv (Event Active): An event will only be presented in the vmChooser if this choice is selected. If you want to hide an event you can do it simply by clicking this option.

bwLehrpool-Suite: Limitations

• „Netzwerk-/Internetzugriff zulassen“ (Allow network/Internet access): Select this option if you want to allow network or Internet access from this Event. Attention: If you deny network access then e.g. network drives will also be blocked, unless you specifically allow them in „Ausnahmen“ (Exceptions). In the network rules entering a port number of 0 will allow all ports from the specified host. Please read and follow the hints given in the new window that opens!
  • When access is allowed: Exceptions entered here will block access on the individual sockets (a socket is a host address and port number).
  • When access is blocked: Exceptions entered here will allow access on the individual sockets (a socket is a host address and port number).

• „Externe Speichermedien zulassen“ (Allow external media): Clicking here allows the attachment of removable media such as USB sticks, CDROMs or DVDs.

• „Prüfungsmodus“ (Exam mode): This box regulates whether the event is seen as an E-Exam by the system. Please note that if you select this box your event will only be visible and able to run in those pool rooms that your local bwLehrpool Administrator has designated as supporting secure exam mode!

Attention: If you set an event into exam mode make sure that the examination pool room has not been excluded from the rooms the event is available in! (see FAQ/bwEklausuren (E-Exams)).

bwLehrpool-Suite: Room Selection

Room selection enables you to more finely specify the availability of an event. The setting is optional - if nothing is checked your event will appear alphabetically in the list on every pool PC. There are two different ways of specifying availability of your event - you can choose specific rooms where it should be prioritized („Veranstaltung mit höherer Priorität in den ausgewählten Räumen anzeigen“) and in the vmChooser it will be in the subsection at the top of the list, or you can limit the visibility of your event to specific rooms („Veranstaltung ausschließlich in den ausgewählten Räumen anzeigen“). The check box next to rooms lets you then choose the rooms to which the above-describing setting applies. When you choose a building every room below it will automatically selected - you do not need to click on every room unless you want to take a special action (see Example: below and picture for more details).

Example: In the picture to the right the building „Rechenzentrum“ (Computer Center) was chosen; all the rooms hierarchically below it (from „Lehrstuhl/1.OG“ to „Poolraum -114“) were automatically marked. Additionally, in the “UB Stadtmitte” (University Library) the individual rooms „Pool OG2“ and „Pool OG4“ were selected and the option „Veranstaltung mit höherer Priorität in den ausgewählten Räumen anzeigen“ (show this event with higher priority in the following rooms) was chosen. This event will therefore appear in the first subsection of the vmChooser in all the PC pools in the Computer Center and two PC pools in the Library, and in all other PC pools it will appear in the alphabetical listing.

bwLehrpool-Suite: Startskript

This option enables the insertion of a script which is to be automatically executed when a VM (more specifically, the VM that is started in this Event) starts. The text of the script should be entered into the text box and the proper file extension chosen from the “Dateinamenserweiterung” dropdown (.sh for Linux- or Unix-based VMs or .bat for Windows). The correct file extension is especially important for Windows.

Please note the following when using a start script:

• A shebang line is required on Linux- or Unix-based VMs (see example to the right). The executable bit will be set by the system.
• The script length should not exceed ~100KB due to space limits when starting the VM.

And especially:

• You are responsible for the creation of any start script and the bwLehrpool team will only under certain limited circumstances be able to support you with issues.

Note: This mechanism requires Minilinux version >=13. To check for availability ask your local bwLehrpool administrator (or test for yourself).

bwLehrpool-Suite: Nutzerrechte

To protect your event's settings, you can granularly set permissions. Permissions are applied on a per-person basis - if you want to grant permission to someone, click on „Benutzer hinzufügen“ (Add User) and double click on users in the list. The double click adds the person, you do not need to click on „Hinzufügen“ (Add). Only people who have already registered to use bwLehrpool-Suite appear in the list; if you can't find the person to whom you would like to grant rights, ask them to register via the bwLehrpool-Suite.

Once you have chosen all the names from the list, you can assign each different permissions. The categories for the permissions are „Bearbeiten“ (Edit) und „Admin“. Edit permission allows a person to change the metadata assigned to the event, such as Name, Description, Start and End Date and Linked VM. „Admin“ permission allows all this, plus the ability to delete the event. Clicking on the „Benutzer“ button over the list of names will reverse the alphabetical sorting of the list; the buttons „Bearbeiten“ and „Admin“ sort by Edit and Admin rights, respectively.

To remove all permissions granted to a user, select the user and click on „Benutzer entfernen“ (or press the “Delete” key on your keyboard) and they will be removed from the list.

Please also note the two options at the bottom of the tab under „Andere Nutzer“ (Other users). These check boxes will grant Edit or Admin rights to all registered bwLehrpool-Suite users and caution should be used when enabling these!

Example: In the example to the right the user Jonathan Bauer has Admin and Edit rights whereas Steffen Ritter and Simon Rettberg only have Edit rights. Other users have no rights to make changes to this event.

If you would like to delete an event, choose it from the list of events and click the „Löschen“ button at the bottom of the screen.

Please see also FAQ.