lserv3: floating license server using a Webots dongle for
multiple concurrent executions of Webots on an limited
number of computers.

version 3.0.10 (May 11th, 2009)

OVERVIEW

lserv3 is a floating license server allowing to run Webots
concurrently on several machines defined by their IP
addresses (or their names). Hence Webots is not tied to
a predefined number of machines but can be run on an
unlimited number of computers. However, the license
server takes care that the number of computers running
Webots simultaneously doesn't exceed the maximum allowed
by the license file.

lserv3 should be installed on a server machine, i.e., a
computer that is on when users are supposed to run
Webots.

Currently, lserv3 runs on Linux (glibc2.3), Mac OS X 10.4
and Windows (XP, 2003 and Vista) operating systems.
It allows Webots execution on Linux, Windows and Mac OS X
machines.

You need a Webots dongle to be able to use lserv3.
You should have obtained this dongle from your Webots
reseller. This dongle should be connected to one of the
USB port of the machine running lserv3.

CLIENT CONFIGURATION:

Each client machine must have Webots installed locally.
An extra file named license.srv should lie in the
resources directory of each local installation of Webots.
This file should contain the a single text line with the
name or IP address of the machine on which the license
server is running. This name should be followed by ":",
the port on which the license server is listening,
another ":" and the type of license requested.

Examples:

128.192.23.1:10024:PRO

or

pc4.cyberbotics.com:10025:EDU

Please check which type of license (PRO, EDU or both) your
license server is expected to provide and ensure that this
matches with the information set in your license.srv file.
If your license server provides only EDU licenses, your
license.srv file should refer to EDU. If your license
server provide only PRO licenses, your license.srv file
should refer to PRO. Finally, if your license server
provides both EDU and PRO licenses, you may choose to set
either EDU or PRO in your license.srv file.

SERVER CONFIGURATION:

The server has a configuration file called machine.lst
which contains the list of authorized clients machines
defined by their names or IP addresses and possibly a
network mask. Hence, each line of that file defines a
machine, or a group of machines. Optionally, a license type
can be added to restrict the usage of a specific license
type on the machine(s). This file should either lie in the
current directory or be passed as an argument to the lserv3
using the "-m" command line option.

   Example:

   pc2.cyberbotics.com
   home.myuni.edu:PRO
   129.130.12.0/255.255.255.0

   The first line allows the computer identified as
   pc2.cyberbotics.com to run any license of Webots.
   
   The second line allows the specified computer to run
   only Webots PRO (excluding Webots EDU).
   
   The last line allows any machine with an IP matching
   129.130.12.* machine to run any license of Webots.

   You will have to create and update this file to allow
   more or less machines to be able to use the licenses
   you own.

When lauching the server, you may have to specify a number
of extra command line options. Under Linux, the "-d"
command line option allows you to launch lserv3 as a
system daemon.

Type "lserv3 -h" to get the list of all possible options.

Example:

# lserv3

launches the server, using machine.lst in the current
directory.

# lserv3 -m /path/to/machine.lst

uses machine.lst files as specified with the -m command
line options (replace "/path/to" by the actual path to the
file).

# lserv3 -m /path/to/machine.lst -d > /path/to/lserv3_log.txt 2> /path/to/lserv3_error.txt

Launch lserv3 as a daemon (Linux only) and log the messages
and the errors in two different files.

# lserv3 -h
 
lserv3 version 3.0.5: Webots license server, copyright 2008 Cyberbotics Ltd.

Usage: lserv3 [-d] [-h] [-m machine_file] [-p port] [-s]

 -d: run as a daemon process (you may want to use the -s
     option or redirect the standard output to a logfile)
     [this is option is not available under Windows]
 -h: display this message and exit
 -m machine_file: use the specified machine.lst file
 -p port: use the specified port instead of 10024
 -s: silent mode, nothing is written to the standard output


CHECKING THE STATUS OF LSERV3 ON THE WEB

lserv3 includes a simple web interface allowing the users
to check the current status of the license server,
including the list of currently connected clients. If
lserv3 runs on port 10024 of pc1.cyberbotics.com, the web
interface can be reached at the following URL:
http://pc1.cyberbotics.com:10024
This web page is also available from the Help menu of
Webots clients under the label "License server status...".


SETTING UP LSERV3 AS A SYSTEM DAEMON ON REDHAT LINUX

In order to ensure to have lserv3 always up and running
even after the server machine has shut down and
restarted, it might be useful to set it as a system
daemon. In order to proceed, copy the two files
mentionned in the appendix A of this document to the
following locations on a standard RedHat distribution:

/etc/init.d/lserv3
/etc/sysconf/lserv3.conf

These files were graciously provided by Paul Blaer from
Columbia University. They might not do all the necessary
checking to be sure that lserv3 started properly, but in
most cases it will work without any problem. Please note
that lserv3 is not the binary version of the license
server, but a daemon script provided in the appendix A of
this document.

Once those files are copied, you should be able to start
lserv3 as root the following way:

# service lserv3 start

and stop it with:

# service lserv3 stop


SETTING UP LSERV3 AS A SYSTEM DAEMON ON DEBIAN LINUX

An example file on how to setup lserv3 as a system daemon
on Debian Linux v3 (Woody) was provided by Peter Hanapppe
(from Sony CSL, Paris). The files should be installed as
follows:

/etc/lserv3/lserv3.conf (provided in the appendix B of this document)
/etc/lserv3/machine.lst
/etc/init.d/lserv3 (provided in the appendix B of this document)
/usr/sbin/lserv3 (lserv3 binary provided from Cyberbotics's web site)
/etc/rc*.d/*lserv3 (soft links to /etc/init.d/lserv3)

SETTING UP LSERV3 AS A WINDOWS SERVICE ON WINDOWS XP OR VISTA

1. Create a folder named "lserv3" in the Webots directory,
   like C:\Program Files\Webots\lserv3\

2. Copy the following files into this lserv3 folder:
   lserv3.exe
   matrix32.dll
   instsrv.exe
   srvany.exe
   machine.lst

3. Open a DOS console. Under Vista you must open it in administrator
   mode: click on the Windows Start menu, select "Start search" and
   type cmd, right click on the cmd icon appearing under "Programs"
   and select "Run as administrator". Once the DOS console pops up,
   execute the following commands:

   > cd "C:\Program Files\Webots\lserv3"

   Check that lserv3.exe works properly: plug-in the USB dongle
   and type:

   > lserv3.exe

   You may need to allow your firewall to let lserv3.exe use
   the specified port (usually 10024). Once lserv3.exe works, press
   Ctrl-C to quit lserv3 and continue with:

   > instsrv.exe lserv3 "C:\Program Files\Webots\lserv3\srvany.exe"
   > regedit

4. In regedit, open the following key:
   HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\lserv3
   Right click on it and create a new key named "Parameters".
   Right click on this new Parameters key and create 3 new strings:
   Application
   AppDirectory
   AppParameters
   Set their value to the following strings:
   Application   = "C:\Program Files\Webots\lserv3\lserv3.exe"
   AppDirectory  = "C:\Program Files\Webots\lserv3"
   AppParameters = "-s" (you may want to use other options here, like -p <port>)
   Quit regedit

5. From the administrator DOS console, start the service by typing:
   > sc.exe start lserv3
   Alternatively you may also use the graphical user interface to
   start the lserv3 service (in the Windows Control Panel, select
   System and Maintenance, Administrative Tools, Services)

6. Check that lserv3.exe is up and running by opening
   http://localhost:10024 in your web browser.
   

TROUBLE SHOOTING

General

If you have a local firewall, please check the firewall
settings to allow for TCP/IP traffic on the lserv3 port
(usually 10024).

Linux

If the server complains that with a message like: "Error:
cannot bind port 10024". Check that the port is not any
more in use:

# /usr/sbin/lsof | grep 10024

You can also check that no other instance of lserv3 is
currently running:

# ps aux | grep lserv3

If so, kill it with:

# killall lserv3

Check that the port has been freed with lsof | grep 10024
and relaunch lserv3. It might necessary to wait for a few
seconds that the system actually releases the port.


APPENDIX A: RedHat Linux files

/etc/init.d/lserv3

8<--- (cut here) -------------------
#!/bin/bash
#
# chkconfig: 2345 85 15
# description: Runs the lserv3 license server for Webots on RedHat Linux.
# processname: lserv3
# pidfile: /var/run/lserv3.pid
# config: /etc/sysconfig/lserv3.conf

# source function library
. /etc/init.d/functions
[ -e /etc/sysconfig/lserv3.conf ] && . /etc/sysconfig/lserv3.conf

RETVAL=0

start() {
        echo -n $"Starting Webots license server: "
        daemon /usr/bin/lserv3 -m $MACHINES -d
        
        RETVAL=$?
        echo
}

stop() {
        echo -n $"Shutting down Webots license server: "
        killproc lserv3
        RETVAL=$?

        echo
}

case "$1" in
  start)
        start
        ;;
  stop)
        stop
        ;;
  restart|reload)
        stop
        start
        RETVAL=$?
        ;;
  condrestart)
        stop
        start
        RETVAL=$?
        ;;
  status)
        status lserv3
        RETVAL=$?
        ;;
  *)
        echo $"Usage: $0 {start|stop|restart|condrestart|status}"
        exit 1
esac

exit $RETVAL

8<--- (cut here) -------------------


/etc/sysconf/lserv3.conf

8<--- (cut here) -------------------
# Webots license server configuration file for RedHat Linux

# Location of machine list:
MACHINES=/usr/share/lserv3/machine.lst
8<--- (cut here) -------------------


APPENDIX B: Debian Linux v3 (Woody) files

/etc/init.d/lserv3

8<--- (cut here) -------------------
#!/bin/sh
# Runs the lserv3 license server for Webots on Debian Linux v3 (Woody)

PATH=/bin:/usr/bin:/sbin:/usr/sbin
DAEMON=/usr/sbin/lserv3
PIDFILE=/var/run/lserv3.pid

test -x $DAEMON && . /etc/lserv3/lserv3.conf || exit 0

# Arguments to lserv3
#
ARGS="-m $MACHINES"

case "$1" in
  start)
    echo -n "Starting Webots license server: lserv3"
    if start-stop-daemon --quiet --stop --signal 0 --pidfile $PIDFILE --name lserv3
    then
      echo " already running."
      exit
    fi
    /sbin/start-stop-daemon --start --background -m --pidfile $PIDFILE --quiet --exec $DAEMON -- $ARGS
    echo "."
    ;;
  stop)
    echo -n "Stopping Webots license server: lserv3"
    if start-stop-daemon --quiet --stop --signal 0 --pidfile $PIDFILE --name lserv3
    then
      PID=`cat $PIDFILE`
      start-stop-daemon --quiet --stop --exec $DAEMON --pidfile $PIDFILE --name lserv3
      # Now we wait for it to die
      while kill -0 $PID 2>/dev/null; do sleep 1; done
      echo "."
    else
      echo " not running.";
    fi
    ;;
  force-reload|restart)
    $0 stop
    $0 start
    ;;
  *)
    echo "Usage: /etc/init.d/lserv3 {start|stop|restart|force-reload}"
    exit 1
esac

exit 0

8<--- (cut here) -------------------


/etc/lserv3/lserv3.conf

8<--- (cut here) -------------------
# Webots license server configuration for Debian Linux v3 (Woody)

# Location of machine list:
MACHINES=/etc/lserv3/machine.lst
8<--- (cut here) -------------------