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 two versions of Python, 2.6 and 2.7.
The UAS will find the applications in a directory called Applications which is directly below the UAS’s operating directory.
If you installed the zip, to run the UAS open a console in the UAS_Launcher directory and type python launch_uas.pyc.
If you installed the Windows MSI, under normal circumstances a UAS Windows service will have been automatically installed and started, however, the following options are available for manual control:
- UAS_Launcher install, to install the Windows service
- UAS_Launcher start, to start the Windows service
- UAS_Launcher stop, to stop the Windows service
- UAS_Launcher remove, to remove the Windows service
- UAS_Launcher debug, to run the UAS as a console application.
Similar manual control exists for the UAS Management Console.
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. Read more about this in the web services examples section.
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.
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.
Procedure for upgrading a live UAS if you have installed the Windows EXE.
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. Read more about this in the web services examples section.
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 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.
Application data records (ADR) provide a list of the applications that have run, along with a small amount of useful information.