QF-Test - The License Server Manual

QF-Test - The License Server Manual
QF-Test - The License Server Manual
Version 4.1.4
Gregor Schmid
Quality First Software GmbH1
c 2014-2017 Quality First Software GmbH
Copyright May 31, 2017
1 http://www.qfs.de
i
Contents
1 Quickstart
1
2 License server installation
4
2.1
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4
2.2
License files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4
3 QF-Test startup options for running or administrating the license server
3.1
3.2
6
Call syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6
3.1.1
Server side operations . . . . . . . . . . . . . . . . . . . . . . . .
6
3.1.2
Client side operations . . . . . . . . . . . . . . . . . . . . . . . .
7
Command line arguments . . . . . . . . . . . . . . . . . . . . . . . . . .
8
3.2.1
Arguments for the starter script . . . . . . . . . . . . . . . . . . .
9
3.2.2
Arguments for the Java VM . . . . . . . . . . . . . . . . . . . . .
9
3.2.3
Arguments for QF-Test . . . . . . . . . . . . . . . . . . . . . . . .
9
4 Interactive license server administration
12
4.1
Opening the administration window . . . . . . . . . . . . . . . . . . . . . 12
4.2
Components of the administration window . . . . . . . . . . . . . . . . . 13
4.3
4.2.1
Menu ’File’ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.2.2
Menu ’View’ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.2.3
Menu ’Extras’ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.2.4
Update every ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.2.5
’Update’ button . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.2.6
Individual license data . . . . . . . . . . . . . . . . . . . . . . . . 14
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
CONTENTS
4.4
ii
4.3.1
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.3.2
Individual license usage . . . . . . . . . . . . . . . . . . . . . . . 16
Update license server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
A Release notes
21
A.1
Version 4.1.0 - October 6 2016 . . . . . . . . . . . . . . . . . . . . . . . . 21
A.2
Version 4.1.1 - November 23 2016 . . . . . . . . . . . . . . . . . . . . . . 21
A.3
Version 4.1.2 - January 13 2017 . . . . . . . . . . . . . . . . . . . . . . . 21
A.4
Version 4.1.3 - March 29 2017 . . . . . . . . . . . . . . . . . . . . . . . . 21
B Third party software
22
iii
List of Figures
4.1
Login dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4.2
Administration window . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.3
Current license usage with ’Show engines’ activated . . . . . . . . . . . . 15
4.4
Update dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.5
Update dialog with new license
4.6
License update confirmation . . . . . . . . . . . . . . . . . . . . . . . . . 19
. . . . . . . . . . . . . . . . . . . . . . . 19
Chapter 1
Quickstart
This chapter provides short explanations and examples for quickly setting up a typical
QF-Test license server. The next two explain the usage of the command line interface
in more detail and can be used as a reference.
The last chapter shows you how to administer the license server via the graphical user
interface.
Inform Quality First Software GmbH about server data for license generation
Define a dedicated host for the license server and a dedicated port on that
machine for this service. Provide this information to Quality First Software GmbH
for setting up the license files and make sure that firewalls are configured so that
client machines can reach the host under the given name or IP address at the
(4)
given port (section 2.2 ).
Install QF-Test
Unpack the QF-Test archive (.tar.gz or .zip) in a convenient location or run the
QF-Test Installer (.exe) on Windows. The directory named qftest is called
QF-Test’s root directory.
It contains a version-specific directory named
qftest-x.y.z. QF-Test needs write access to its root directory to store
version-independent files there. When upgrading to a newer version, install to the
(4)
same place in order to reuse those files (section 2.1 ).
License files
Save the server and client license files named license.server and license,
provided by Quality First Software GmbH, to QF-Test’s root directory (section
(4)
2.2 ).
Set the license server’s password
Quickstart
2
The default password for the QF-Test license server is secret. It is a good idea
to change it before starting the license server for the first time by defining a
password for the license server administrator named admin and setting the
administrator password by executing
qftest -batch(9) -licenseserver(10)
-licenseserver.setpwd <user>=<password>(11)
for <user> admin.
You can always run QF-Test directly from its bin directory by specifying the full
path instead of just qftest.
Start the license server
Then you can then run the license server via
qftest -batch(9) -licenseserver(10)
Distribute the client license
Provide the client license file called license to QF-Test users that should get
their license from the license server. The file should be saved in QF-Test’s root
directory on the client.
Measure license usage
Current license usage can be monitored on the server machine or any client
machine with a QF-Test installation and the client license. Either start the license
(12)
server admin GUI described in chapter 4 with
qftest -licenseserver.admin(10)
and login as user admin with the password you defined or dump the current license use to stdout with one of the following commands:
qftest -batch(9) [-licenseserver.password <password>(10)]
-licenseserver.dump(10)
qftest -batch(9) [-licenseserver.password <password>(10)]
-licenseserver.dumptotal(10)
Save the license server’s password
(10)
You can omit specifying -licenseserver.password <password> in the
above commands by logging in once via the admin GUI and checking ”Remember
password” or by saving the administrator password for client side use via
qftest -batch(9) -licenseserver.setpwd <user>=<password>(11)
Quickstart
Stop the license server
To stop the license server, either kill its process or run
qftest -batch(9) -licenseserver.shutdown(11)
3
Chapter 2
License server installation
2.1
Note
Prerequisites
Please always run the QF-Test license server with Java 8 or at least Java 7. The serverside SSL code in Java 6 and older is not stable and can cause occasional connection
errors under load.
The QF-Test license server functionality is currently part of the main QF-Test installation and not available as a separate package. Thus the installation is identical to the
installation of QF-Test itself, documented in the QF-Test manual, chapter 1.
It is possible, but not strictly necessary, to run the license server under a dedicated user
account. For security reasons the ”root” or ”Administrator” accounts should not be used.
2.2
License files
Besides the usual information about numbers and kinds of licenses and GUI engines,
two additional parameters are required for server and client licenses: The hostname or
IP address of the license server and a dedicated port number reserved for the license
server on this host. These must be provided to QFS for creating the server and client
license files, and the server will be limited to running on the specified host and port.
The QF-Test license server requires a special server license that should be saved under
the name ”license.server” in the ”qftest” root directory of the license server installation.
This license cannot be used on any other machine.
A matching client license is needed to administrate the server. The client license is similar to a normal QF-Test license and should also be installed in QF-Test’s root directory
and named ”license”.
2.2.
License files
5
QF-Test instances that need to get their license from the server should use the client
license in place of their normal license. One of the great advantages of the license
server is that the client license is constant and does not need to be updated when the
QF-Test version changes or additional instances are added to the license.
It is always possible to use a specific license via the command line argument
(10)
-license <file> .
Chapter 3
QF-Test startup options for running or
administrating the license server
Windows
The program qftest.exe is a Windows GUI application. When started from a command shell, it will not wait for QF-Test to terminate but return immediately and you won’t
see any output from QF-Test in the console window. For running the QF-Test license
server as a Windows service or autostart program this is fine. For running the license
server from a Windows command shell you may prefer to utilize the qftestc.exe console application. It waits for QF-Test to terminate and output will be displayed in the
console window. Apart from that, everything said about qftest.exe in this chapter
holds true for qftestc.exe too.
3.1
Call syntax
3.1.1
Server side operations
The following commands apply to the license server. They must be run on the license
server machine and require a server license.
Starting the license server
The license server is started as follows:
qftest -batch(9) [-dbg(9)] [-java <executable>(9)]
[-noconsole(9)] [-J<java-argument>]*
[-license <file>(10)] [-licenseserver.logfile <file>(10)]
[-licenseserver.verbose <level>(11)] [-options <file>(11)]
-licenseserver(10)
3.1.
Call syntax
7
Setting the administrator password for the license server
To set the administrator password for the license server on the server side, use
the following syntax for <user> admin:
qftest -batch(9) [-dbg(9)] [-java <executable>(9)]
[-noconsole(9)] [-J<java-argument>]*
[-license <file>(10)] [-licenseserver.logfile <file>(10)]
[-licenseserver.verbose <level>(11)] [-options <file>(11)]
-licenseserver(10) -licenseserver.setpwd <user>=<password>(11)
3.1.2
Client side operations
The following commands can be executed with QF-Test on either the license server
machine or a client machine. They require a client license matching the server.
Stopping the license server
To cleanly shut down the license server, use the following syntax:
qftest -batch(9) [-dbg(9)] [-java <executable>(9)]
[-noconsole(9)] [-J<java-argument>]* [-license <file>(10)]
[-options <file>(11)] [-licenseserver.password <password>(10)]
-licenseserver.shutdown(11)
Saving the user’s password for the license server
By running this command once, the administrator password will be
saved for the current user so that the command line argument
(10)
-licenseserver.password <password> can be omitted in future calls:
qftest -batch(9) [-dbg(9)] [-java <executable>(9)]
[-noconsole(9)] [-J<java-argument>]*
[-license <file>(10)] [-options <file>(11)]
-licenseserver.setpwd <user>=<password>(11)
Currently the only username supported is admin.
Getting detailed information about the current license usage
You can get a list of all currently used licenses with the following command:
qftest -batch(9) [-dbg(9)] [-java <executable>(9)]
[-noconsole(9)] [-J<java-argument>]* [-license <file>(10)]
[-options <file>(11)] [-licenseserver.password <password>(10)]
-licenseserver.dump(10)
3.2.
Command line arguments
8
The result is printed to standard output in comma-separated-values (CSV) format
including a header line.
Getting summary information about the current license usage
You can get a summary of the currently used licenses with the following
command:
qftest -batch(9) [-dbg(9)] [-java <executable>(9)]
[-noconsole(9)] [-J<java-argument>]* [-license <file>(10)]
[-options <file>(11)] [-licenseserver.password <password>(10)]
-licenseserver.dumptotal(10)
The result is printed to standard output in comma-separated-values (CSV) format
including a header line. The lines of data show the current license usage, the
remaining unused licenses and the total available licenses.
Getting summary information about peak license usage
The QF-Test license server internally tracks peak usage. You can get the values
with the following command:
qftest -batch(9) [-dbg(9)] [-java <executable>(9)]
[-noconsole(9)] [-J<java-argument>]* [-license <file>(10)]
[-options <file>(11)] [-licenseserver.password <password>(10)]
[-licenseserver.verbose <level>(11)]
-licenseserver.dumppeak(10)
The result is printed to standard output.
If the log level
(11)
-licenseserver.verbose <level> is VERBOSE or higher, the time at
which the peak was reached is printed. If it is DETAIL, the individual leases
causing the peak are listed as well.
Interactive license server administration
This command launches a dedicated license server administration GUI for
interactive use. You can also open this window from an interactive QF-Test
instance via the menu Extras→Administrate license server .
qftest [-dbg(9)] [-java <executable>(9)] [-J<java-argument>]*
[-license <file>(10)] [-options <file>(11)]
-licenseserver.admin(10)
3.2
Command line arguments
Command line arguments for QF-Test fall in three categories.
3.2.
Command line arguments
3.2.1
9
Arguments for the starter script
These arguments are evaluated directly by the qftest shell script or executable and
override settings determined during installation. Under Unix these settings are stored
in the file launcher.cfg in QF-Test’s root directory, under Windows they are stored in
the registry.
-batch
Run QF-Test in batch mode. This is a required argument for the license server.
-dbg
Turn on debugging output for the starter script. The same effect is achieved by
setting the environment variable QFTEST_DEBUG to a non-empty value. On
Windows this causes QF-Test to open a console window to display the output that
(9)
would otherwise be invisible unless the argument -noconsole is also given.
-java <executable>
The Java executable used to run QF-Test. The default is java on Unix and
javaw.exe on Windows, unless a different value was set during installation.
-noconsole (Windows only)
On Windows this argument suppresses the console window that would otherwise
(9)
be opened in case -dbg is specified.
3.2.2
Arguments for the Java VM
You can pass arguments to the Java VM through the starter script by prepending them
with -J, e.g. -J-Duser.language=en to set a system property.
3.2.3
Arguments for QF-Test
The rest of the arguments are handled by QF-Test itself when it is executed by the
Java virtual machine. These arguments can also be placed in a file using the syntax
<name>=<value> for arguments with parameters or <name>=true or <name>=false
to turn a simple argument on or off. By default this file is called qftest.options, located in the bin directory of QF-Test and used only for internal logging purposes. If you
change anything in this file, you can move it to QF-Test’s root directory so your changes
3.2.
Command line arguments
10
(11)
will still apply after upgrading. Alternatively you can use the -options <file> argument to specify a different file. Arguments given on the command line override arguments from an option file except for those which can be given multiple times. In the
latter case the arguments are merged.
-license <file>
Set the location of the license file.
-licenseserver
Start QF-Test in license server mode.
-licenseserver.admin
Open the license server administration GUI.
-licenseserver.dump
Print detailed information about the currently used licenses.
-licenseserver.dumptotal
Print summary information about the currently used licenses.
-licenseserver.dumppeak
Print information about peak license usage. If the log level defined with
(11)
-licenseserver.verbose <level> is DETAIL, also print the individual
leases that caused the peak usage.
-licenseserver.logfile <file>
Write log messages to the specified file.
The default log file is
licenseserver.log in the directory log under QF-Test’s root directory. To
suppress logging, use the argument with an empty value in the form
-licenseserver.logfile=.
-licenseserver.password <password>
The password for connecting to the license server as the user admin.
Can be omitted if the password was previously saved for the current
user during interactive use or via the command line argument
(11)
-licenseserver.setpwd <user>=<password> .
3.2.
Command line arguments
11
-licenseserver.setpwd <user>=<password>
Set a password for license server administration. Currently only one user named
admin is supported. When run in license server mode, i.e. in combination with
(10)
-licenseserver
the command changes the password for the license
serverwsd. In client mode it saves the password for the current user so that no
login is required when opening the license server administration window and no
(10)
password must be specified via -licenseserver.password <password>
when performing client-side batch operations.
-licenseserver.shutdown
Cleanly shut down the license server.
-licenseserver.verbose <level>
Set the log level for the license server.
On the server side it
determines how much detail is written to the log file specified with
(10)
-licenseserver.logfile <file> . On the client side it determines how
(10)
much detail to print for commands like -licenseserver.dumppeak .
Supported values are numbers form 0 to 4 or the respective constants NOTHING,
ERRORS, TERSE, VERBOSE, DETAIL. The default value is TERSE.
-nomessagewindow
In case of a fatal error in batch mode QF-Test prints an error message to the
console and for improved visibility also brings up an error dialog for about 30
seconds. That dialog can be suppressed with the help of this argument.
-options <file>
Override the location of the file used to specify additional command line
arguments. This argument can be given more than once to use several sources
of command line arguments.
-version
Print version information and exit.
Chapter 4
Interactive license server
administration
4.1
Opening the administration window
You can open the administration window in one of the two ways:
Start via command line
qftest -licenseserver.admin(10)
Start via QF-Test client
You can start the GUI admininstration at a client that gets its license from the
license server via the menu item Extras→License server administration... .
When the login dialog appears you can enter the user name (currently ’admin’ only)
and the password. Additionally you can check the box whether the password should be
saved so that the login dialog will not appear again next time.
Figure 4.1: Login dialog
4.2.
Components of the administration window
13
The administration windows consists of a menu bar, an overview and a table showing
the individual current or peak license usage. You can configure the GUI to show a status
line as well.
Figure 4.2: Administration window
4.2
Components of the administration window
4.2.1
Menu ’File’
Menu item ’Close window’
Closes the administration window.
4.2.2
Menu ’View’
Menu item ’Show status line’
You can activate or deactivate the menu item by clicking it. When it is ticked, i.e.
activated, you will see an additional line for status information at the bottom part
of the window.
4.2.
Components of the administration window
14
Menu item ’Update’
View→Update requests the current license usage from the license server and
updates the display. Alternatively you could press the
button.
Menu item ’Show engines’
You can activate or deactivate the menu item by clicking it.
When
View→Show engines is not ticked, i.e. deactivated, only the sums of the
developer and runtime licenses are displayed.
When View→Show engines is ticked, the licenses shown in the overview and
individual licenses tables are also listed per engine. This comes in handy when you
have a server license valid for different numbers of licenses for the different types
(15)
of engines. The image Current license usage with ’Show engines’ activated at
(15)
the beginning of the chapter Tables shows an example.
4.2.3
Menu ’Extras’
Menu item ’Update server license’
You can update the server license currently in use via this menu item. The update
(17)
process is described in detail in section 4.4 .
4.2.4
Update every ...
In the drop down list you can specify the interval (from 5 sec to 5 min) for requesting
license usage data from the license server and an update of the display.
4.2.5
’Update’ button
requests the current license usage from the license server and updates the
display.
4.2.6
Individual license data
(16)
Above the table Individual license usage you will find a drop down list, where you can
choose which data the table should display.
4.3.
Tables
15
Current usage
Data showing the license usage of the individual QF-Test clients currently started.
Peak usage (development)
Data showing the license usage of the individual clients at the time of maximum
use of developer licenses since the license server was started last.
Peak usage (runtime)
Data showing the license usage of the individual clients at the time of maximus
use of runtime licenses since the license server was started last.
4.3
Tables
Figure 4.3: Current license usage with ’Show engines’ activated
4.3.
Tables
4.3.1
16
Overview
In use
Number of licenses of the respective type (development/runtime) currently in use
by QF-Test clients.
Available
This table row shows the number of development and runtime licenses currently
available, including engine information if the menu option is set accordingly.
The image above shows an example with two developer licenses, one of which is
assigned to a QF-Test client making use of all the engines availabe and the other
to a QF-Test client using all engines except Java FX. The license structure of the
example allows only one instance of QF-Test to work with a Java FX engine. The
license structure for the runtime licenses is the same. However, the two runtime
licenses are used by a daemon running two QF-Test instances using only the web
engine.
Total
This table row shows the total number of development and runtime licenses
available. When the menu option is set accordingly it also show the respective
numbers for the single engines.
Peak usage (development)
Total license usage at the time of maximum usage of development licenses since
the last restart of the license server.
Peak (runtime)
Total license usage at the time of maximum usage of runtime licenses since the
last restart of the license server.
4.3.2
Individual license usage
You can specify the kind of individual license data shown by selecting the respective op(14)
tion from the drop-down list Individual license data above the table. The table columns
provide the following information:
Development / Runtime
4.4.
Update license server
17
The number of used development, respectively runtime licenses used by each
connected QF-Test client.
User
The name of the user running the QF-Test client.
Host
The name of the host on which the QF-Test client was started.
IP Address
The client’s IP address.
Started
The time when the QF-Test Client was started.
AWT / JavaFX / SWT / Web
Number of development licenses used for the respective engine by the QF-Test
client.
You can show / hide these columns via the menu item View→Show engines .
AWT/Rt / JavaFX/Rt / SWT/Rt / Web/Rt
Number of runtime licenses used for the respective engine by the QF-Test client.
You can show / hide these columns via the menu item View→Show engines .
4.4
Update license server
The server license can be updated interactively via the administration window. This is
done by selecting Extras→Update server license . The following dialog appears:
4.4.
Update license server
18
Figure 4.4: Update dialog
The top part of the dialog shows the server license currently in use.
In the bottom text field you can either paste the text of the license provided by Quality
First Software GmbH or enter it automatically by selecting the license (update) file via
the ”Select file” button.
4.4.
Update license server
19
Figure 4.5: Update dialog with new license
When the license data has been entered into the bottom text field you can press the
”Update” button. A message will come up informing you that the license update was
successful.
The license server is updated while it is running. It does not have to be restarted for the
new license to become active. QF-Test clients already connected are not affected by
the license update. Newly started clients will run with the updated license.
Figure 4.6: License update confirmation
The old license file gets backed up with the ending ’.old’ before the update is
4.4.
Update license server
20
performed. The new license data are written to the current license file specified via
(10)
-license <file> .
After the update the license update file provided by Quality First Software GmbH is no
longer needed.
21
Appendix A
Release notes
A.1
Version 4.1.0 - October 6 2016
First official version.
A.2
Version 4.1.1 - November 23 2016
Version number adapted to match latest QF-Test version.
A.3
Version 4.1.2 - January 13 2017
Version number adapted to match latest QF-Test version.
A.4
Version 4.1.3 - March 29 2017
Version number adapted to match latest QF-Test version.
22
Appendix B
Third party software
QF-Test license server makes use of the following software:
Bean Scripting Framework (BSF)
c 1999 International Business Machines Corporation.
Copyright See the license doc/licenses/bsf
URL: http://www.alphaworks.ibm.com/tech/bsf
Cryptix library
c 1995, 1996, 1997, 1998, 1999, 2000 The Cryptix Foundation
Copyright Limited. All rights reserved.
See the license doc/licenses/cryptix
URL: http://www.cryptix.org
GNU regex
c 1998-2001 Wes Biggs.
Copyright Distributed under the GNU Lesser General Public License (see
doc/licenses/LGPL).
Source code included in misc/gnu_src.jar
URL:
http://nlp.stanford.edu/nlp/javadoc/gnu-regexp-docs/index.html
Java Runtime Environment
Distributed under the Oracle Binary Code License Agreement for the Java SE
Platform Products and JavaFX (see doc/licenses/oracle-jre).
URL:
http://www.oracle.com/technetwork/java/javase/overview/index.html
Third party software
23
JGoodies Looks
c 2001-2005 JGoodies Karsten Lentzsch. All rights reserved.
Copyright See the license doc/licenses/jgoodies-looks
URL: http://www.jgoodies.com
JIDE Common Layer
c 2002 - 2009 JIDE Software, Inc, all rights reserved.
Copyright Distributed under the GNU General Public License (see doc/licenses/GPL)
with Classpath Exception (see doc/licenses/Classpath).
URL: http://www.jidesoft.com/products/oss.htm
Netty
c 2009 Red Hat, Inc.
Copyright Distributed
under
the
Apache
doc/licenses/apache-2.0).
URL: http://netty.io
Licence,
Version
2.0
(see
Version
2.0
(see
TrueZIP Virtual File System API
c 2005-2007 Schlichtherle IT Services.
Copyright Distributed
under
the
Apache
Licence,
doc/licenses/apache-2.0).
URL: http://truezip.dev.java.net
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertising