Running the UAS¶

The UAS will run applications that have been written by the user. These applications will be written in the same language that the UAS is written in, in this case the language is Python. Currently, the UAS is available for various versions of Python 3.

The UAS will find the applications in a directory called Applications which is directly below the UAS’s operating directory.

If you installed the UAS package using the Linux ZIP file:: To run the UAS, open a console in the UAS_Launcher directory and type python launch_uas.pyc (Alternatively, you can run it as a daemon by typing python launch_uas.pyc --daemon)
If you installed the UAS package using the Windows EXE file:: Under normal circumstances a UAS Windows service will have been automatically installed and started. If you wish to have manual control over this service, see the How do I manually control the Windows services section in the troubleshooting guide.

UAS configuration¶

At startup, the UAS will attempt to read a configuration file called config.cfg in a subdirectory called config. An example of the configuration file is given below:

# UAS configuration options.
uas_name:UAS           # a name for this instance of the UAS, displayed on cloud.aculab.com
log_level:trace        # for UAS_Launcher.log and UAS_Channels.log
log_root:./Logs        # where log files are written
log_size_m:10.0        # Mbytes size of log files
log_files:10           # number of log files before rotation
num_apps:400           # number of concurrent applications allowed on this UAS
num_apps_lower:300     # the lower limit at which backoff is ended if it is active
app_responder:on       # if this is on, the UAS will respond to application requests
app_limiter:on         # if this is on, the UAS will activate backoff if the application limit is reached
avg_window:5           # for connection metrics, the window length of the rolling average
monitor:38001          # management console connection port number
prospath:./prosody     # path to prosody module

If you installed the zip, it is also possible to provide options on the command line. These options will override the options read from the configuration file.

UAS command line options and defaults:

-h --help
Default False, if set will print help

-u --uas_name
Default ‘UAS’, using the default will cause the UAS to use the hostname

-l --log_level
Default ‘trace’, the log level, options are ‘debug’, ‘trace’, ‘info’, ‘report’, ‘warning’, ‘error’

-r --log_root
Default ‘./log’, where log files are written

-s --log_size_m
Default 10.0, maximum size of log files in megabytes

-f --log_files
Default 10, maximum number of log files before rotation

-n --num_apps
Default 400, maximum number of concurrent applications allowed on this UAS

-o --num_apps_lower
Default 300, The lower limit at which backoff is ended if it is active

-a --app_responder
Default ‘on’, If this is on, the UAS will respond to application requests

-b --app_limiter
Default ‘on’ If this is on, the UAS will activate backoff if the application limit is reached

-w --avg_window
Default 5, for connection metrics, the window length of the rolling average

-m --monitor
Default 38001, UAS management console connection port number

-p --prospath
Default ‘./prosody’, path to the prosody module

uas_name: If a name is given to the UAS it will transmit this name to cloud.aculab.com so that it is displayed on the home page. This allows the user to distinguish between UAS’s. If this option is left at the default value, the UAS will get the machine’s hostname and transmit that instead.

log_level: The log levels available are ‘debug’, ‘trace’, ‘info’, ‘report’, ‘warning’ and ‘error’. It is recommended to use debug level during the development phase. The log level can be changed at run time on the management console’s logs page.

log_root: This is the directory to which the UAS writes its log files.

log_size_m: The maximum size of a log file in megabytes, provided as a floating point value, before the file rolls over.

log_files: The maximum number of log files to create before discarding the oldest one. The files are numbered from 1 to (default) 10, where 10 is the oldest file. The current log file (the one that is being written) has no number.

num_apps: The maximum number of concurrent applications that the UAS can run. When this number is reached, the UAS will send a special message to cloud.aculab.com to say that it cannot receive any more application requests. This is called the backoff message. This limit can be modified at run time on the management console settings page.

num_apps_lower: The lower limit at which the UAS will resume accepting applications if backoff has been activated. This limit can be modified at run time on the management console settings page.

app_responder: An on/off switch for accepting new application requests from cloud.aculab.com. If this is off, the UAS will refuse all further application requests. Applications that are already running will continue to run. This setting can be modified at run time on the management console settings page.

app_limiter: An on/off switch for the backoff mechanism. If this is off, the UAS will never tell the connection to stop sending new application requests, even if the num_apps limit has been reached. The app_responder switch will override this setting, if it is off no new application requests will be accepted even if app_limiter is off.

avg_window: The UAS gathers some simple statistics on the responsiveness of the connections. The responsiveness is measured as the round trip time in seconds taken for a message between the UAS and cloud.aculab.com. Recorded are the maximum, minimum and average response times. The average is calculated over a short window of recorded times. The default is 5 samples. These statistics may be viewed on the UAS management console’s Clouds page or retrieved using the UAS monitor.

monitor: This is the port number on which the UAS will listen for connections from the management console. This number has to be the same as the one set in the management console’s configuration file.

prospath: This is the path to the prosody module. The prosody module is the API library that the UAS uses to communicate with cloud.aculab.com.

If the configuration file is missing and no command line options are given, the command line defaults are used.

Once the UAS is running, type ‘quit’ in the console to terminate it.

On Linux the UAS can be run as a daemon, add --daemon to the command line options.

When running as a daemon, typing python launch_uas.pyc --dstop on the command line will cause the UAS to terminate gracefully. Alternatively, --drestart will restart it.

On some Linux distributions the default stack size per thread is eight megabytes. If the UAS is going to run hundreds of applications the amount of memory used can quickly become too large and the UAS will become sluggish. It is therefore important to reduce the stack size per thread. This can be done using the ulimit command, e.g.:

ulimit -s 256

to set the stack size per thread to 256 kilobytes. This will affect the current terminal only. Please read up on ulimit if you want to make the setting global and permanent on your system.

On Linux it is also important to ensure that enough file descriptors are available for the number of threads that need to be started. The default number of file descriptors on your Linux distribution might not be sufficient. You can increase the file descriptors value using the ulimit command, e.g.:

ulimit -n 10240

It is possible to run more than one instance of the UAS as a daemon on a single machine. However, each UAS must have a unique monitor port number. This is set in the configuration file.

Guidance on updating a UAS on a live system¶

Updating an application on the UAS is a simple matter of installing the new version of the application via the management console. This can be done even when there are several live calls. Existing calls will continue to use the old version while new calls will be picked up by the freshly installed version. However, if you are replacing the entire UAS, please read the following.

This section is for guidance only and you may well have your own procedures for upgrades. However, it’d be useful for you to read this for information. We suggest that you upgrade your development UAS first and, once happy with the result, upgrade your production UASs one-by-one.

Procedure for upgrading a live UAS, if you have installed the zip.

Extract the new UAS zip file into a fresh directory.
Copy the content of the original UAS’s Applications directory to the same directory for the new UAS, or see 8) below.
If you want to preserve any configuration changes you have made to the UAS or Management Console, copy their configuration files across to the same directory for the new UAS and Management Console. The configuration files can be found in the two config directories.
On the UAS Management Console browser, click Settings then click the green button by “Accept application requests is on” to stop accepting new application requests, the wording changes to “Accept application requests is off” and the button turns red. Note that this is a persistent change which writes to your configuration file.
Click Applications and wait for the numbers of Running applications to drop to 0. If you have another UAS running, all applications are now being handled by that UAS.
Quit the UAS Management Console and quit the UAS itself.
Change into the fresh directory, run the UAS Management Console and the UAS itself.
If you didn’t copy the Applications across manually (see 2) above), click Applications then add the required applications and common files.
Click Connections and add any missing connections using your credentials.
Click Settings and check that the settings are correct.
Once the connections become active, the UAS will be handling applications. If you detect problems, click Settings then click the green button to stop accepting new application requests. Then address the issues and click the same button again to start accepting requests.
Repeat the same procedure for any other UASs that require upgrading.

Procedure for upgrading a live UAS if you have installed the Windows EXE.

On the UAS Management Console browser, click Settings then click the green button by “Accept application requests is on” to stop accepting new application requests, the wording changes to “Accept application requests is off” and the button turns red. Note that this is a persistent change which writes to your configuration file.
Click Applications and wait for the numbers of Running applications to drop to 0. If you have another UAS running, all applications are now being handled by that UAS.
In Windows, go to Add or Remove Programs and uninstall the old UAS Python package.
Run the executable you downloaded and install the new UAS Python package.
On the UAS Management Console browser, click Applications then add the required applications and common files.
Click Settings and check that the settings are correct.
Click Connections and add any missing connections using your credentials.
Once the connections become active, the UAS will be handling applications. If you detect problems, click Settings then click the green button to stop accepting new application requests. Then address the issues and click the same button again to start accepting requests.
Repeat the same procedure for any other UASs that require upgrading.

The UAS connection model¶

A UAS can respond to application requests from more than one connection. Each UAS must be told the details of the specific connections on which to register. This registration uses the details of an existing user account on that connection. Without this information cloud.aculab.com cannot direct calls to be handled by the UAS.

The UAS maintains a list of connections to which it holds a connection. The information is stored in a machine-readable file called clouds.mcn in a UAS subdirectory called clouds.

The UAS gathers some simple statistics on the responsiveness of its connections. The responsiveness is measured as the round trip time in seconds taken for a message between the UAS and cloud.aculab.com. Recorded are the maximum, minimum and average response time. These statistics may be viewed on the UAS management console’s Clouds page or retrieved using the UAS monitor.

Following first-time installation on a platform the UAS should be automatically configured with details of the connections that it is going to make. Manual configuration of connections can be done via the Management Console’s Connections page.

The applications¶

The applications reside in a directory called Applications which is directly below the UAS’s operating directory. On startup, the UAS will import the applications. New versions of the applications can be uploaded to this directory using the UAS management console while the UAS is running.

Note: In order for the management console to upload new applications, it must have write permission in the UAS directory.

See the heading about writing UAS applications for more information.

The application data records¶

Application data records (ADR) provide a list of the applications that have run, along with a small amount of useful information.

Understanding application data records

The UAS monitor¶

The UAS monitor is a command line utility used to retrieve and display UAS statistics from the cloud. Once running, the statistics will be retrieved and displayed every 30 seconds.

The statistics represent the responsiveness of the UAS connections. The responsiveness is measured as the round trip time in seconds taken for a message between the UAS and Aculab Cloud. Presented are the Maximum, Minimum and Average time measured in seconds.

A guideline on interpreting the statistics is as follows:

Minimum: less than 1 is good, 1 to 2 is OK, more than 2 is bad.

Maximum: less than 5 is good, 5 to 10 OK, more than 10 is bad.

Average: less than 2 is good, 2 to 4 is OK, more than 4 is bad.

The information returned by the UAS is a JSON format object of the following:

[
    {
        "cloudid"   : "0-2-0",
        "minrespt"  : "0.02",
        "maxrespt"  : "0.15",
        "meanrespt" : "0.12"
    },
    {
        ...
    },
    ...
]

In Python terms this is a list of dictionaries, where each dictionary holds the statistics for a single cloud connection. There can be more than one connection per cloud region.

cloudid is the id of the cloud connection, for example 0-2-0 is the European cloud.

minrespt is the minimum response time recorded.

maxrespt is the maximum response time seen.

meanrespt is the average response time seen.

Usage¶

python uas_monitor [ip_addr] [port]

Optional Arguments¶

ip_addr

Your UAS IP address. The default is ‘localhost’.

port

Your UAS listening port. The default is 38001.