ALS Logo

Altiva Licence Server

 Previous Topic Next Topic Altiva Software

 

ALS Configuration

The configuration file "Als.cfg" controls some aspects of the behaviour of the server. It is a plain ASCII text file which can be viewed and edited in any text editor, such as Windows Notepad. The file format is very simple, and consist of simple "key = value" pairs. Comments are preceded by a hash sign '#' (also known as a pound sign or octothorpe in US English).  The configuration file does not normally need to be edited, and should usually be left as-is for most environments. It is read at startup-time for the service, so any changes in the configuration file will only go into effect after the service is restarted. The following details are covered in this section:

  1. Configuration Variables Available
  2. The Configuration File
  3. Configuration Variables in Detail

Light bulb

 Note that in ALS v5 the configuration file was redesigned. Configuration files from v4 and earlier should not be used with ALS v5 and higher.

 

 

Configuration Variables Available

The settings for the configuration file are defined below:

  1. LICENCE_SERVER_PORT_NUM
  2. HTTP_SERVER_PORT_NUM
  3. HTTP_SERVER_ENABLED
  4. TIMEOUT_SECS
  5. ALIVE_RECONNECT_ENABLED
  6. COMPUTER_NAME_ENABLED
  7. ANY_DEPT_ENABLED
  8. VERSION_5_PROTOCOL_ENABLED
  9. DEBUG_LEVEL_NUM
  10. DEBUG_RETENTION_DAYS
  11. MAX_CONNECTIONS_PER_LICENCE
  12. SUPPORT_IP_V4
  13. SUPPORT_IP_V6

 

 

The Configuration File

A default configuration file is shown below.

##########################################################
# Altiva Licensing Server Configuration File             #
#                                                        #
# Last modified by Piers Porter                          #
# Altiva Software, Inc.                                  #
# 21st March 2016                                        #
#                                                        #
##########################################################

#
# This variable defines the port number of the licence server.
# ALS will use this port to communicate licence requests with the client machines.
# This only needs to be changed if it conflicts with an existing port.
#
LICENCE_SERVER_PORT_NUM = 1999


#
# This variable defines the port number of the ALS HTTP server.
# ALS will use this port to display logging files in HTML format to client machines.
# This only needs to be changed if it conflicts with an existing port. 
# It is ignored if the HTTP server is disabled via the setting HTTP_SERVER_ENABLED = 0.
#
HTTP_SERVER_PORT_NUM = 1998

#
# This setting defines whether the HTTP logging is enabled. 
# HTTP logging allows remote clients to view the status of the ALS log files by browsing to the machine running ALS.
# For example: http://myserver:1998
#
HTTP_SERVER_ENABLED = 1

#
# Maximum time allowed between heartbeats before a licence is freed back into the pool (in seconds).
# This setting is used to adjust the time allowed for lost connections to be freed.
# A lost connection typically happens when a computer is put in sleep mode, the client application exits unexpectedly, 
# a network connection is lost, or the client IP address unexpectedly changes.
# The client will send regular heartbeats to the server. If no heartbeats are received after the given number of seconds, 
# then the licence is relinquished automatically.
# The default time of 1800 seconds means 30 minutes between the heartbeat being received and the licence becoming relinquished to the pool.
#
TIMEOUT_SECS = 10

#
# Automatically allocate a new licence if an existing connection to the server is lost.
# This will automatically allocate a new licence from the pool for a client machine whose licence has already been freed. 
# This usually happens when a DHCP controller allocates a new IP address to a client that already has a licence checked out from the pool,
# or a formerly lost network connection is re-established.
#
ALIVE_RECONNECT_ENABLED = 1


#
# Use DNS/WINS lookup for computer name?
# This may slow the server down if the client is on a different workgroup / domain to the server.
# Disabling COMPUTER_NAME_ENABLED will report the computer name as "Unknown" in all log files
# and instead only display the IP address in IPv4 dotted-quad format.
#
# COMPUTER_NAME_ENABLED = 1; Lookup is enabled
# COMPUTER_NAME_ENABLED = 0; Lookup is disabled
#
COMPUTER_NAME_ENABLED = 0

#
# Department licensing options. This is only relevant if the licence file on the server has the "DEPT=" command.
#
# ANY_DEPT_ENABLED = 0 : This means that a client can only check out a licence for its own department
# ANY_DEPT_ENABLED = 1 : This means that a client can check out a licence from any department, but it will try to fetch with its own first.
#
ANY_DEPT_ENABLED = 0

#
# This option allows new ALS V5 licence functionality to be unlocked between server and client.
# This should only be enabled if all clients support the new client/server protocol, which was enabled in CADconform for MicroStation v8.00.21 in April 2016.
# If there are any client machines running an earlier version of CADconform, then this option should be disabled.
#
VERSION_5_PROTOCOL_ENABLED = 0

#
# Debug level option.
# Modifying this variable changes the amount of information stored in the debug log file.
# If there is a problem with the Altiva Licence Server, change this variable to the highest level and restart the ALS service.
# This will provide more information in the log file to assist in diagnosing networking, firewall and licence pool problems.
#
# DEBUG_LEVEL_NUM = 0 : Minimal data logged. Only basic start/stop information and critical errors are logged.
# DEBUG_LEVEL_NUM = 1 : Moderate information on service activities and problems are logged. (Default setting)
# DEBUG_LEVEL_NUM = 2 : More service information is logged, including moderate warnings and routine service operations.
# DEBUG_LEVEL_NUM = 3 : Verbose debug messages information logged. All service information is reported. Use this to troubleshoot only, as it may impact performance.
#
DEBUG_LEVEL_NUM = 3


#
# Debug log file retention time.
# This defines how old inactive debugs file are allowed to get before they are deleted automatically.
# Note that this only affects previous log files and not the current log file. If the computer or service has a
# longer uptime than this definition below, then there is no limit on how old the current debug log file can get.
# Older debug logs can be useful for tracing problems with the service. If no such problems occur then this
# setting can be safely ignored.
#
# Note that the default is 4 weeks (28 days)
#
DEBUG_RETENTION_DAYS = 2

#
# Maximum connections per unique licence/client.
# If this is set higher than 1, then each client can request multiple connections for the same product from the same 
# machine, if it runs multiple instances of the requested product. In this case, the licence is only freed to the pool 
# when the number of active connections reaches zero.
# In ALS v5.0.01 and earlier, there was no limit on the number of simultaneous connections each licence could have.
# In ALS v5.0.02 and higher, this is set to 1 by default, meaning that each licence can only be connected to one client 
# at a time.
#
MAX_CONNECTIONS_PER_LICENCE = 1

#
# Allows support for IPv4.
# This should normally be set to "1" unless your network is configured to be IPv6 only. For example, some VPNs such
# as Microsoft DirectAccess do not support IPv4 for name resolution. Disabling IPv4 may give a slight increase in
# connectivity if this is disabled as it means an IPv4 connection will never be attempted. If set to "1" then IPv4
# will be allowed, however IPv6 will usually be attempted first if allowed.
#
SUPPORT_IP_V4 = 1

#
# Allows support for IPv6.
# This should normally be set to "1" unless your network is configured to be IPv4 only. Older network hardware may not 
# fully support IPv6. Disabling IPv6 may give a slight increase in connectivity if this option is disabled as it means 
# an IPv6 connection will never be attempted. If set to "1" then IPv6 will usually be attempted first.
#
SUPPORT_IP_V6 = 1

Configuration Variables in Detail


Below are more details on what settings are available and how each one works:

LICENCE_SERVER_PORT_NUM

This integer value represents the port number to use for communication on the server. It must also match the port number set in the client side licence file (see also: "Licence Files"). It is set to "1999" by default, but can generally be set to any number as required. Port numbers below 100 should generally be avoided as this may interfere with ports reserved for other system applications.


HTTP_SERVER_PORT_NUM

This integer value represents the port number to use for HTTP communication between the server and the client. This is used by the client to view the ALS status in a web browser. It is set to "1998" by default, but can generally be set to any number as required. Port numbers below 100 should generally be avoided as this may interfere with ports reserved for other system applications.


HTTP_SERVER_ENABLED

This option enables ("1") or disables ("0") the HTTP Server. The HTTP Server allows logging information to be displayed to clients in a web browser using the server name and HTTP port in the URL. For example: http://licserver01:1998.

The HTTP Server
The ALS HTTP Server running in the Microsoft Edge browser


TIMEOUT_SECS

This value defines how long to wait (in seconds) before cleaning up lost connections. Each client application sends a "heartbeat" back to ALS to indicate that it is still running and continuing to use the licence. If the network connecting the client and the server goes down, or the client suddenly crashes or loses power, then the server needs to relinquish the licence that was being used, otherwise the pool of available licences may be exhausted by computers that are not actively using a licence. Therefore ALS will periodically relinquish a licence when a certain amount of time has past without ALS receiving a heartbeart from the client. Under normal operation a client will specifically send a message to ALS that it is no longer using a licence when the application exits, so the licence is freed immediately. The heartbeat time setting is only used when the client application did not exit gracefully, and thus it is not a common occurrence that the server needs to free licences manually through the heartbeat time. The default time for a freeing a licence after the heartbeat is lost is 1800 seconds (30 minutes). Generally the clients should always send a heartbeat at least twice as often as ALS frees licences with lost heartbeats. The client-side heartbeat can be set by the client application.

ALIVE_RECONNECT_ENABLED

This option will enable ("1") or disable ("0") the functionality to automatically re-request a new licence if an existing connection to the server is lost. If this is enabled, then ALS will automatically allocate a new licence from the pool for a client machine whose licence has already been freed. This is an usual event that may happen when the licence was freed erroneously. The more common causes of this might be:
  1. A formerly lost network connection is re-established, for example the ethernet cable was unplugged or the wireless connection was temporarily lost.
  2. A DHCP controller renews the server connection, allocating a new IP address to a client that already has a licence checked out from the pool under a different IP address.
  3. The ALS service was restarted, either manually or due to a reboot of the server.
  4. The client machine was rebooted unexpectedly, or an application crash occurred before the licence could be relinquished properly.

 

COMPUTER_NAME_ENABLED


This setting is used by for logging purposes only. It can be set to "0" to disable, or "1" to enable. If it is enabled, then the computer name will be displayed next to the IP address of each computer in the log file. This can be useful for seeing which computers are using licences regularly if the IP address is dynamic (and therefore not a useful unique identifier). The disadvantage of using this setting, is that if the client computer accessing ALS is part of a different workgroup or domain, then this can slow down the licence communication, or possibly cause ALS to time-out. If time-outs or noticeable lags occur regularly, COMPUTERNAME_LOOKUP should be disabled by setting the value to "0".
As of ALS v5, the computer name lookup should be much faster when allocating licences to client machines that also support the enhanced ALS v5 protocol. In CADconform for MicroStation, this will be version 8.00.21 and higher.


ANY_DEPT_ENABLED

This value controls behaviour of department licensing and can be set to "0" (disabled) or "1" (enabled). It is only used for licence files that have specifically been generated for a particular department. If it is enabled, then licence requests from a specific department will be attempted first, and then fall back to any available department. If it is disabled, then licences for a specific department can only be met with a free licence from a corresponding department. This functionality can be useful if you want to reserve some licences so they are always available for a specific department. Consider the example below:

Example scenario:
You have a pool of 10 licences of a product available for everyone, however you want to install it on about 10 machines, as the application is not used all the time by everyone. You want the licences to be available as a first in, first served basis. You also have 2 IT administrators, and they should always have access to the application as top priority, so they can resolve any issues with the application if needed. What you can do is request a licence file where you have 8 normal licences, and 2 licences reserved for the IT department. This licence file will then run on ALS. On the two IT computers, they have a client-side setting that specifically requests a licence reserved for the IT department.

Now assume that you have 8 normal clients running the application and one more normal user tries to check-out a licence.

Now assume that you purchase an extra 2 licences reserved for a new department named "Mapping". You have 8 normal clients running the application and one more normal user tries to check-out a licence.

Now assume that you have 2 IT administrators already running the application and one more IT administrator tries to check-out a licence.

Therefore the DEPARTMENTS_ALLOW_ANY setting only has bearing on whether department licences are available to clients that are not in that department.


VERSION_5_PROTOCOL_ENABLED

This option allows new ALS Version 5 licence functionality to be unlocked between server and client. This should only be enabled if all clients support the new client/server protocol, which was enabled in CADconform for MicroStation v8.00.21 in April 2016.
If there are any client machines running an earlier version of CADconform or other products released before this date, then this option should be disabled. This option is off ("0") by default in v5.0 of ALS, but will probably be defaulted on ("1") in future versions.

DEBUG_LEVEL_NUM

The DEBUG_LEVEL is used to define how much debugging information is included in the log file. The higher the number, the more debugging information is logged. The lowest level is "0" and the highest level is "3". The default level is "1", which gives minimal debugging information. The disadvantage of higher levels is that it can create larger log files and possibly slightly slower operation, though this affect may be negligible on all but the slowest servers. The various levels of debugging are outlined below: See also the DEBUG_RETENTION_DAYS setting below.


DEBUG_RETENTION_DAYS


The DEBUG_RETENTION_DAYS setting defines how many days to keep legacy debug log files for. Every time the ALS service is restarted (either due to a manual restart or an automatic one after a server reboot), a new debug log is created. At this stage in starting up, the service will also automatically delete any existing debugging log files that are older than the current setting for DEBUG_RETENTION_DAYS. It is possible for a debug log to be much older than this setting if it is still in active use, so the age and size of the current debug log will also be a function of the current uptime of the server. The default is 21 days. If sporadic problem occur with the server that can not be traced in the current debug log, then you may wish to increase this size so that are longer audit history is available. The default is 4 weeks (i.e. DEBUG_RETENTION_DAYS = 28).

MAX_CONNECTIONS_PER_LICENCE

The setting MAX_CONNECTIONS_PER_LICENCE defines how many times each licence can be checked out to a unique client machine. It is set to 1 by default, meaning each machine can have only one connection at a time. This means that one machine drawing more then one licence by running multiple instances of a product, (either simulatenously or through a Virtual Machine), will be treated as one unique request. Closing the first instance when multiple connections have been requested will immediately free the licence back into the pool for other client machines to request. If this variable is set to a number higher than one, then each successive licence request counts as an additional connection. The licence is then only freed back into the pool when the number of active connections is reduced to zero. This variable was added in v5.00.03 of ALS. Previous versions of ALS had no upper limit on simultaneous connections, which may delay the relinquishing of the licence back into the pool until all connections were closed.

SUPPORT_IP_V4

This setting enables support for the TCP/IP v4 protocol. This allows connectivity via 32-bit dotted quad addresses, for example www.google.com has the IPv4 address "172.217.25.142".

This setting should normally be set to "1" unless your network is configured to be IPv6 only. For example, some VPNs such as Microsoft DirectAccess do not support IPv4 for name resolution. Disabling IPv4 support may cause licence communication to fail faster as it means an IPv4 connection will never be attempted. Generally IPv6 will usually be attempted first if enabled (see below).

Versions of ALS prior to v5.1.0 would always connect only via IPv4, so turning this option on and disabling IPv6 can be seen as running ALS in legacy mode, mimicking the functionality of v5.0.x and earlier.

 

SUPPORT_IP_V6

This setting enables support for the TCP/IP v6 protocol. This allows connectivity of 128-bit addresses via 8 groups of 4 hexadecimal addresses, for example www.google.com has the IPv6 address "2404:6800:4006:805::200E".  

This setting should normally be set to "1" unless your network is configured to be IPv4 only. This might be useful if using older network hardware that does not fully support IPv6. Disabling IPv6 may give a slight increase in connectivity if this option is disabled as it means an IPv6 connection will never be attempted.

If set to "1" then IPv6 will usually be attempted first before IPv4. If both IPv4 and IPv6 are enabled (the default setting), then ALS will attempt to create a dual socket on the licence and HTML port, allowing clients to connect using either IPv4 or IPv6. Note that a client that only supports IPv4 may still have its address mapped and transported via IPv6. For example, if a client attempts an IPv4 connection to ALS v5.1 with this setting enabled, then it may get mapped to an IPv6 address, which will look like the IPv4 address with the prefix "::ffff" (that is 80 bits of zeroes followed by 16 bits of ones, then the 32-bit IPv4 address).