Tailoring the configuration file

In the WLab directory within webapps, there should be a conf directory. This contains two XML files, application-properties.xml and strings.xml. The former is the main configuration file, which must be edited to suit your environment.

This file is divided into sections:

• General application parameters
• Hyper-V server parameters
• Data access parameters
• Authentication/directory server parameters
• Auto-suspension parameters

Apart from the latter section, the configuration sections all follow a similar pattern. As an example, the below is the default authentication section:

<bean id="authenticationAccess" class="org.paulneve.wlab.authentication.AuthenticationAccessLdapImpl">
	<property name="ldapServer" value="192.168.1.7"/>
	<property name="ldapPort" value="389"/>
	<property name="adMode" value="true"/>
	<property name="adDomain" value="demoserver.local"/>
</bean>

THE ONLY PARTS YOU SHOULD CHANGE ARE THE VALUES. Modifying any other part of the file will prevent WLab from starting up. So, for example, you could modify the line

<property name="ldapServer" value="192.168.1.7"/>

to

<property name="ldapServer" value="ldap.myuniversity.ac.uk"/>

but modifying any of the surrounding XML, or any values in the name="..." attributes will cause problems.

Note that any changes to application-properties.xml require a restart of Tomcat before they take effect. We also recommend you back up your application-properties.xml. When upgrading to a new version of WLab, your version of the file will be replaced with the default. If you have no backup, you will have to redo all your changes.

Compulsory configuration settings

These settings are those that almost always MUST be changed before WLab will run in your environment. Following a fresh install, you must configure these before going any further.

General application parameters

• defaultVncPassword
  When you come to configure the virtual machines for your tutors to clone, you will need to install VNC (see Dealing with WLab virtual machines). You should standardise on a single VNC password across all WLab VMs, and this parameter should contain this standard password.
  
  
• adminLogin
  This should be set to the login name of a user on your directory/domain who will have responsibility for administrating the WLab system. This user can then log into WLab and create additional tutors. If they wish, they can specify that such additional tutors are themselves superusers (which means they too can create tutors).
  
  
• maxConcurrentVMs
  This value indicates how many VMs can be run at the same time before WLab will prevent students from starting any more. In most cases, the default value of 5 will be too low and should be changed.
  
  The value comes directly from the virtualisation backend, and thus includes any VMs that may have been started manually i.e. outside of the WLab system. If, for example, there will always be 5 VMs running on your virtualisation server regardless of anything WLab might start, you should take such “permanent” VMs into account.

Hyper-V server parameters

• username / password
  This should be set to a user who has administrative access on the Hyper-V server, i.e. can stop/start/create/delete VMs. This MUST be in the form domain\username. The password parameter should be set to this user’s password.
  
  
• serverName
  This should be set to the IP address or domain name of the Hyper-V server.
  
  
• diskPath
  This should be directory where the Hyper-V server stores its virtual hard disks. Note that this is relative to the Hyper-V server! Also note, ALL, REPEAT, ALL VMs USED IN WLAB WILL AND *MUST* HAVE THEIR HARD DISKS LOCATED IN THE ROOT OF THIS FOLDER, INCLUDING BACKEND VMs. Any backend VMs that do not have their hard disks in this folder will NOT clone correctly.
  
  
• octet1 / octet2 / octet3
  These three values should be set according to the IP subnet where the virtual machines will be found. If your configuration was as the example IP addresses given in System Requirements, the default values of 192, 168 and 1 would be appropriate. When the system attempts to locate a VM, it will search the entire class C range for it.

Data access parameters

• dataAccess
  This should be set to a fully-enumerated directory where WLab can store its data files. An example might be /usr/share/WLabDataFiles. This should be read/writeable by the Tomcat process. Note that this is relative to the WLab server. If the directory does not exist WLab will attempt to create it. If in this event WLab cannot create it, an error will occur.

Authentication access parameters

• ldapServer / ldapPort
  Set the IP or domain address and port number of the LDAP directory server here. Note that this does not have to be on the same subnet as the VMs and other servers used by WLab as long as the Tomcat server can establish a connection to this address.
  
  
• ldapConnectionString
  Set the LDAP connection string here. This will be used to perform a directory search on the LDAP server, so as to ascertain whether or not the user name entered is a valid user. It must contain the placeholder *USER* - the user name entered will be inserted into the connection string at this point. An example value for this setting might be:
  
  uid=*USER*,cn=users,DC=myuniversity,DC=ac,DC=uk
  
  This setting is ignored if you are using Microsoft Active Directory, and adMode is set to true (see below).
  
  
• ssl
  Set to true if your LDAP server/port combination is SSL, false if plain text. You should also consult Using SSL with LDAP, especially if your SSL certificate is self-signed.
  
  
• adMode Set this value to true if you are connecting to Microsoft Active Directory. If this is true, ldapConnectionString is not used.
  
  
• adDomain Set this value to the Active Directory domain name. This should be fully specified, e.g. myuniversity.ac.uk rather than just myuniversity. Ignored if adMode is false.

Optional configuration settings

General application parameters

• port
  If you will run VNC on non-standard ports within your virtual machines, you can specify an alternative port number here.
  
  
• autoSuspendPeriod
  If a student overruns their allocated runtime, their VMs will be suspended and they are prevented from starting new VMs for this period of time (specified in minutes).
  
  
• defaultStudentConcurrentVMs
  Specifies how many VMs a student can run at the same time. Note that this can be overridden on a per-student basis by tutors.
  
  
• defaultStudentMaxBookings
  Students can book time on the system during which they will be guaranteed an uninterrupted runtime slot. These bookings last one hour. The value in this parameter value specifies how many such bookings a student may make in advance. This can be overridden on a per-student basis by tutors.
  
  
• defaultStudentMaxRuntime This specifies how long a student may run their VMs for before the student will automatically suspend them (so as to prevent a student from “hogging” the system). The value is in minutes, and can be overridden by tutors on a per-student basis.

Auto suspension parameter

This configuration section is formatted slightly differently to the others:

<bean id="vmSuspender" class="org.paulneve.wlab.utilities.VmSuspender" autowire="byName">
<constructor-arg type="int"><value>10</value></constructor-arg>
</bean>

Only the number between the <value> tags should ever be altered. The value specifies in seconds how often the system will poll for overrunning virtual machines. Increasingly this value reduces server load, but might result in less accuracy. You should increase the value proportionally as the number of likely concurrent VMs increases – a rule of thumb is to make this value double the maximum number of concurrent VMs.