Table Of Contents

Previous topic

ashttpd.conf

Next topic

The Reef Datamodel

Runtime Settings

Runtime Configuration Mechanism

Abilisoft applications have a set of configuration settings that coerce their runtime behaviour. Every setting has a “built-in” default value that can be overridden in the following ways:

  • By specifying a new setting value in the $AS_HOME/etc/application-name.conf file (where {application-name} is the name of the application e.g. asagent, up or ashttpd)
  • By setting an environment variable.
  • By passing in a command line argument when executing the application.

Settings are adhered to in priority order (1 being highest priority):

  1. Setting specified by command line argument
  2. Setting specified in an environment variable
  3. Setting specified in the ashttpd.conf file
  4. Built-in default setting

For example, an environment variable setting will override the built-in default but not an alternative setting value passed in as a command line argument. This provides a versatile and flexible configuration mechanism that suits most environments.

On UNIX platforms all settings are described in the installed man pages. All setting names follow an intuitive format, for example:

log_filecount Configuration file setting name
--log_filecount Command line parameter
AS_LOG_FILECOUNT Environment variable

ashttpd Configuration File

By default ashttpd reads its runtime configuration from the $AS_HOME/etc/ashttpd.conf file. However if the name setting is used then the file read will be $AS_HOME/etc/name.conf.

The syntax of the configuration file is fairly simple. Any lines starting with the “#” or “;” character are regarded as comments and ignored. The file is divided up into sections, each section begins with the section name enclosed in square brackets. Keys-value pairs are placed below, separated by the “=” character, e.g. for a section named settings:

[settings]
key1 = value1
key2 = value2

Currently ALL settings live in one section called settings, no other section names are used.

SETTING TYPES

BoolSetting

Boolean settings are very simple true/false settings. They accept true, t, yes, y, on and 1 as true, and false, f, no, n, off and 0 as false. In both cases any mixture of upper and lower case letters is allowed.

ByteSetting

This setting is used when you need to specify a file size or something similar. It accepts just an integer number which is interpredted as the number of bytes. But common suffixes can be used too.

Binary suffixes
Binary suffixes represent numbers as powers of 2. This uses the International Electrotechnical Commision’s notation that avoids confusion with the ISO notation. They are: KiB (2^10), MiB (2^20), GiB (2^30) and TiB (2^40).
SI suffixes
SI suffixes represent numbers as powers of 10. They are commonly known, although sometimes in relaction to computers mistakenly used for powers of two. Here they are used in their real meaning: kB (10^3), MB (10^6), GB (10^9), TB (10^12).

IntSetting

Unless a minimum and/or maximum is set any integer value is valid. The setting documentation should mention the possible restriction.

IpSetting

This specifies an IP address. It must be either an IPv4 address in dotted quad notation, an IPv6 address or a hostname which can be resolved. To specify a wildcard address leave this blank.

LogLevelSetting

This specifies how verbose a log target must be. Levels can be either a string or a numerical value between 0 and 100 (inclusive). Known strings with their numerical equivalent are: DEBUG (10), INFO (20), WARN (30), WARNING (30), ERROR (40), CRITICAL (50). Using 0 will get you all logging, using 100 will get you no log messages.

PathSetting

When setting a path, environment variables will be expanded and the resulting path will be made absolute. Since you normally don’t really have control over the current directory of the processes it is recommended that the fully expanded path will be an absolute path already.

Note that the ~ character is not expanded.

PeriodSetting

A period is represented as a string: days:hours:minutes:seconds. Any part may be left blank, leading blank parts may be omitted. E.g. legal values are: 200, :::200, 2:30, :2:30. This being 200 seconds for the first two and 2 minutes 30 seconds in the second.

SocketSetting

This specifies a socket address. The format is <address_type>:<address> where <address_type> is one of UNIX, TCP, UDP.

For a UNIX socket (always of SOCK_STREAM type) <address> is an absolute pathname, for a TCP or UDP socket <address> is made up of <ip_address>:<port> where <ip_address> is in the normal quad-dotted notation.

StringSetting

Unless there is a setting specific restriction for a string setting it can be set to any value. Be aware however that if a specific string setting does restrict the value it is probably also case sensitive.

If interprets special values is True, the following will be replaced with their respective values:

!HOST!:Replaced with the hostname of the server we are running on.
!IP!:Replaced with the IPv4 address of the server we are running on.
!APPID!:Replaced with the name of the application, for example asagent, up or ashttpd.
!NAME!:Replaced with the name given by the Name setting.

If expands environment variables is True, environment variables in the string are expanded. On UNIX the Bourne shell syntax is expected e.g:

$AS_HOME

On Windows the %variable-name% syntax is expected e.g:

%AS_HOME%

SETTINGS

daemonise

Run the application as a daemon

  • type: BoolSetting
  • setting: daemonise
  • default: True
  • parameter: –daemonise
  • environment variable: AS_DAEMONISE
  • MSI property: DAEMONISE
  • legacy name: Daemonise
  • legacy section: general
  • legacy parameter: –daemonise
  • legacy environment variable: AS_DAEMONISE

Normally on UNIX servers Abilisoft products run as daemons. However when you are debugging it can be useful to keep the server in the foreground with its file descriptors attached to the console. Setting this to false will inhibit daemonisation.

loglevel

The log level to use

  • type: LogLevelSetting
  • setting: loglevel
  • default: INFO
  • parameter: –loglevel
  • environment variable: AS_LOGLEVEL
  • MSI property: LOGLEVEL
  • legacy name: LogLevel
  • legacy section: logging
  • legacy parameter: –loglevel
  • legacy environment variable: AS_LOGLEVEL

The log level determines how detailed the logging output in the log files and console is. Values can be either a known string or an integer value between 0 and 100 (inclusive). Recognised string values with their numerical equivalents are: DEBUG (10), INFO (20), WARNING (30), ERROR (40) and CRITICAL (50).

name

Name of the application

  • type: StringSetting
  • setting: name
  • default: !APPID!
  • parameter: –name
  • environment variable: AS_NAME
  • MSI property: NAME
  • legacy name: Name
  • legacy section: general
  • legacy parameter: –name
  • legacy environment variable: AS_NAME
  • interprets special values: True
  • expands environment variables: False

Trying to run multiple instances of an Abilisoft product on a single server can sometimes cause a problem. Using this setting you can override the default application name. This influences defaults for the configuration file, log file, CORBA name and PID file. This is useful if you want to run more than one instance of an Abilisoft application on the same host (e.g. multiple agents).

cfg_backend

Configuration backend to use

  • type: StringSetting
  • setting: cfg_backend
  • default: DEFAULT
  • parameter: –cfg_backend
  • environment variable: AS_CFG_BACKEND
  • MSI property: CFG_BACKEND
  • legacy name: ConfigBackend
  • legacy section: config
  • legacy parameter: –config_backend
  • legacy environment variable: AS_CONFIG_BACKEND
  • interprets special values: False
  • expands environment variables: False

This defines which configuration backend should be used. Unless specified on the command line the default INI backend is used in any case, but this can be set to some other backend wich will then be loaded in addition to the INI backend. The latter backend will have priority over the INI one.

The DEFAULT backend will use INI on UNIX systems and WINREG on Windows.

cfg_inifile

Configuration file for the INI backend

  • type: StringSetting
  • setting: cfg_inifile
  • default: !NAME!.conf
  • parameter: –cfg_inifile
  • environment variable: AS_CFG_INIFILE
  • MSI property: CFG_INIFILE
  • legacy name: ConfigIni
  • legacy section: config
  • legacy parameter: –config
  • legacy environment variable: AS_CONFIG_FILE
  • interprets special values: True
  • expands environment variables: False

This specifies which configuration file the INI backend should read the configuration from.

The default is overwritten by all applications so for example asagent modifies this value to asagent.conf.

httpd_addr

IP address for server to listen on

  • type: IpSetting
  • setting: httpd_addr
  • default: ''
  • parameter: –httpd_addr
  • environment variable: AS_HTTPD_ADDR
  • MSI property: HTTPD_ADDR

Specifies the interface the application server should listen on. By default ‘’ (empty string) is used which means the server will listen on the configured port on all interfaces.

httpd_amfdebug

Enable amf DEBUG logging

  • type: BoolSetting
  • setting: httpd_amfdebug
  • default: False
  • parameter: –httpd_amfdebug
  • environment variable: AS_HTTPD_AMFDEBUG
  • MSI property: HTTPD_AMFDEBUG

Django AMF gateway logging is quite verbose and so is not included in the DEBUG logging by default. However if you need to see detailed AMF log information from app gateways then configure this setting to True and gateway log messages will also appear in the application log. Note that overall, the visibility of AMF gateway logs is still controlled by the loglevel setting.

httpd_djangodebug

Enable Django DEBUG logging

  • type: BoolSetting
  • setting: httpd_djangodebug
  • default: False
  • parameter: –httpd_djangodebug
  • environment variable: AS_HTTPD_DJANGODEBUG
  • MSI property: HTTPD_DJANGODEBUG

Django runtime logging is capped at INFO level because at DEBUG level it is quite verbose. However if you need to see detailed Django log information, configure this setting to True and DEBUG messages from the Django runtime will also appear in the application log. Note that overall, the visibility of Django runtime logs is still controlled by the loglevel setting.

httpd_expose_tracebacks

Expose tracebacks of unhandled exceptions to client

  • type: BoolSetting
  • setting: httpd_expose_tracebacks
  • default: False
  • parameter: –httpd_expose_tracebacks
  • environment variable: AS_HTTPD_EXPOSE_TRACEBACKS
  • MSI property: HTTPD_EXPOSE_TRACEBACKS

None

httpd_ident

Server identity to use in response headers

  • type: StringSetting
  • setting: httpd_ident
  • default: ashttpd
  • parameter: –httpd_ident
  • environment variable: AS_HTTPD_IDENT
  • MSI property: HTTPD_IDENT
  • interprets special values: False
  • expands environment variables: False

The server identity used in the Server: header of HTTP responses.

httpd_log_socket_errors

Log premature client disconnect tracebacks

  • type: BoolSetting
  • setting: httpd_log_socket_errors
  • default: True
  • parameter: –httpd_log_socket_errors
  • environment variable: AS_HTTPD_LOG_SOCKET_ERRORS
  • MSI property: HTTPD_LOG_SOCKET_ERRORS

Turn off to not log premature client disconnect tracebacks.

httpd_logrequests

Include HTTP server log messages

  • type: BoolSetting
  • setting: httpd_logrequests
  • default: False
  • parameter: –httpd_logrequests
  • environment variable: AS_HTTPD_LOGREQUESTS
  • MSI property: HTTPD_LOGREQUESTS

The built in HTTP server hosting the application server will emit log messages to stdout and stderr. By default these are intercepted and discarded. Changing this setting to True will cause the log messages to be sent to the application log file.

httpd_port

Server Port

  • type: IntSetting
  • setting: httpd_port
  • default: 8080
  • parameter: –httpd_port
  • environment variable: AS_HTTPD_PORT
  • MSI property: HTTPD_PORT

Specifies the port that the application server will listen on.

httpd_url_scheme

The wsgi.url_scheme value to use

  • type: StringSetting
  • setting: httpd_url_scheme
  • default: http
  • parameter: –httpd_url_scheme
  • environment variable: AS_HTTPD_URL_SCHEME
  • MSI property: HTTPD_URL_SCHEME
  • interprets special values: False
  • expands environment variables: False

The URL scheme the application is externally exposed on. This is useful if a reverse proxy is terminating the SSL connection since it will allow the WSGI application to render URLs using the https scheme even when it is handeling http requests itself.

httpd_wsgiapp

The WSGI Application to serve

  • type: PathSetting
  • setting: httpd_wsgiapp
  • default: $AS_HOME/share/ashttpd/urlmapper.wsgi
  • parameter: –httpd_wsgiapp
  • environment variable: AS_HTTPD_WSGIAPP
  • MSI property: HTTPD_WSGIAPP

Specifies the client WSGI application that ashttpd will host. This can be any Web Server Gateway Interface (WSGI) compliant web application written in Python. The value must be the full path to the .wsgi file.

log_dir

Directory for logfiles

  • type: PathSetting
  • setting: log_dir
  • default: $AS_HOME/var/log
  • parameter: –log_dir
  • environment variable: AS_LOG_DIR
  • MSI property: LOG_DIR
  • legacy name: LogDir
  • legacy section: logging
  • legacy parameter: –log_dir
  • legacy environment variable: AS_LOGDIR

The directory to store the logfiles in. If you use environment variables in here they will be expanded.

log_filecount

Number of roll-over logfiles to keep

  • type: IntSetting
  • setting: log_filecount
  • default: 5
  • parameter: –log_filecount
  • environment variable: AS_LOG_FILECOUNT
  • MSI property: LOG_FILECOUNT
  • legacy name: BackupCount
  • legacy section: logging
  • legacy parameter: –logfile_backup_count
  • legacy environment variable: AS_LOGFILE_BACKUP_COUNT

When a log file reaches it’s maximum size (specified by log_maxfilesize) it is rolled over and renamed to foo.log.N where N is a number. The number of these rolled over log files to keep is specified here.

log_filename

Name for the log file

  • type: StringSetting
  • setting: log_filename
  • default: !NAME!
  • parameter: –log_filename
  • environment variable: AS_LOG_FILENAME
  • MSI property: LOG_FILENAME
  • legacy name: LogFileName
  • legacy section: logging
  • legacy parameter: –log_file_name
  • legacy environment variable: AS_LOGFILENAME
  • interprets special values: True
  • expands environment variables: False

The base filename of the logfile to use, i.e. the name given here will get .log appended to it. Specials values like !APPID! and !NAME! are allowed.

log_maxfilesize

Maximum size of a logfile before it gets rolled over

  • type: ByteSetting
  • setting: log_maxfilesize
  • default: 5MiB
  • parameter: –log_maxfilesize
  • environment variable: AS_LOG_MAXFILESIZE
  • MSI property: LOG_MAXFILESIZE
  • legacy name: MaxSize
  • legacy section: logging
  • legacy parameter: –max_logfile_size
  • legacy environment variable: AS_MAX_LOGFILE_SIZE

The maximum size a logfile is allowed to have, once this size is reached it is rolled over and a new one is started. The size can have common size suffixes like kB, MB, KiB, MiB, etc.

log_utc

Timestamp in logfiles are UTC

  • type: BoolSetting
  • setting: log_utc
  • default: True
  • parameter: –log_utc
  • environment variable: AS_LOG_UTC
  • MSI property: LOG_UTC
  • legacy name: LogTimeUTC
  • legacy section: logging
  • legacy parameter: –log_time_utc
  • legacy environment variable: AS_LOG_TIME_UTC

Timestamps used in the logfiles represent UTC time. By setting this to False they will represent local time.

tune_backlog

The backlog to use on the server socket

  • type: IntSetting
  • setting: tune_backlog
  • default: 1024
  • parameter: –tune_backlog
  • environment variable: AS_TUNE_BACKLOG
  • MSI property: TUNE_BACKLOG

The backlog on a server socket specifies how many client connections the kernel will queue up if the application can not immediately accept them. See the manpage of listen(2) for details.

tune_channel_timeout

Time after which a channel is considered inactive

  • type: PeriodSetting
  • setting: tune_channel_timeout
  • default: 120
  • parameter: –tune_channel_timeout
  • environment variable: AS_TUNE_CHANNEL_TIMEOUT
  • MSI property: TUNE_CHANNEL_TIMEOUT

Maximum seconds to leave an inactive connection open. An inactive channel is one which has not sent nor received data to the client.

tune_cleanup_interval

Interval for inactive channel cleanups

  • type: PeriodSetting
  • setting: tune_cleanup_interval
  • default: 30
  • parameter: –tune_cleanup_interval
  • environment variable: AS_TUNE_CLEANUP_INTERVAL
  • MSI property: TUNE_CLEANUP_INTERVAL

Minimum seconds between cleaning up inactive channels. An inactive channel is one which has not sent nor received data to the client.

tune_connection_limit

Max number of clients connected

  • type: IntSetting
  • setting: tune_connection_limit
  • default: 100
  • parameter: –tune_connection_limit
  • environment variable: AS_TUNE_CONNECTION_LIMIT
  • MSI property: TUNE_CONNECTION_LIMIT

Stop creating new channels if too many are already active. Each channel consumes at least one file descriptor and, depending on the input and output body sizes, potentially up to three, plus whatever file descriptors your application logic happens to open. The default is conservative, but you may need to increase the number of file descriptors available to the ashttpd process on most platforms in order to safely change it (see ulimit -a “open files” setting).

tune_inbuf_overflow

Maximum size of in-memory request, in bytes

  • type: IntSetting
  • setting: tune_inbuf_overflow
  • default: 524288
  • parameter: –tune_inbuf_overflow
  • environment variable: AS_TUNE_INBUF_OVERFLOW
  • MSI property: TUNE_INBUF_OVERFLOW

A temporary file will be created if the incoming request is larger then this value. This is a conservative default.

tune_max_request_body_size

Maximum number of bytes in request body

  • type: ByteSetting
  • setting: tune_max_request_body_size
  • default: 1048576
  • parameter: –tune_max_request_body_size
  • environment variable: AS_TUNE_MAX_REQUEST_BODY_SIZE
  • MSI property: TUNE_MAX_REQUEST_BODY_SIZE

None

tune_max_request_header_size

Maximum number of bytes of all request headers combined

  • type: ByteSetting
  • setting: tune_max_request_header_size
  • default: 262144
  • parameter: –tune_max_request_header_size
  • environment variable: AS_TUNE_MAX_REQUEST_HEADER_SIZE
  • MSI property: TUNE_MAX_REQUEST_HEADER_SIZE

None

tune_outbuf_overflow

Maximum size of in-memory responses, in bytes

  • type: IntSetting
  • setting: tune_outbuf_overflow
  • default: 1048576
  • parameter: –tune_outbuf_overflow
  • environment variable: AS_TUNE_OUTBUF_OVERFLOW
  • MSI property: TUNE_OUTBUF_OVERFLOW

A temporary file will be created if the pending output is larger than this value. This is a conservative default.

tune_recv_bytes

The number of bytes to pass to recv(2)

  • type: ByteSetting
  • setting: tune_recv_bytes
  • default: 8192
  • parameter: –tune_recv_bytes
  • environment variable: AS_TUNE_RECV_BYTES
  • MSI property: TUNE_RECV_BYTES

None

tune_send_bytes

The number of bytes to pass to send(2)

  • type: ByteSetting
  • setting: tune_send_bytes
  • default: 18000
  • parameter: –tune_send_bytes
  • environment variable: AS_TUNE_SEND_BYTES
  • MSI property: TUNE_SEND_BYTES

This is the number of bytes to send to send(2). Multiples of 9000 should avoid partly-filled TCP packets, but don’t set this larger than the TCP write buffer size. In Linux, /proc/sys/net/ipv4/tcp_wmem controls the minimum, default, and maximum sizes of TCP write buffers.

tune_threads

Number of threads the worker should be using

  • type: IntSetting
  • setting: tune_threads
  • default: 4
  • parameter: –tune_threads
  • environment variable: AS_TUNE_THREADS
  • MSI property: TUNE_THREADS

Each worker uses a number of threads to handle actual requests. In general the more the workers need to wait on I/O the more threads you can use. However worker threads are limited by the Python GIL so if you need to handle more requests you want to run multiple workers rather then change the number of threads in a worker.

Reef Configuration File

Reef is a WSGI application that is hosted by ashttpd and as such has its own runtime configuration settings file. Reef is composed of a set of “Django” applications (see https://djangoproject.com) and the file $AS_HOME/etc/reef.conf is used to override the Reef’s own runtime settings. An example is provided in the installation directory in $AS_HOME/share/doc/reef/examples/reef.conf.

Sections

The reef.conf is similar in structure to a normal configuration file however the content of particular sections can be more elaborate than the usual name, value pair syntax. Here is an example reef.conf file:

[django]
# Set the default client page size to 10 events
APP_EVENTSVC = {'PAGE_SIZE': 200}

# Define Admin email addresses.  This is a tuple that lists people
# who get code error notifications.  When a view raises an exception,
# Django will email these people with the full exception information.
# Each member of the tuple should be a tuple of (Full name, email address)
ADMINS = (('Amy Wong', 'awong@abilisoft.com'),
          ('Zapp Brannigan', 'zbrannigan@abilisoft.com'),
          ('Antonio Calculon', 'acalculon@abilisoft.com'),
         )

# Specify e-mail settings Reef will use when sending e-mails.
EMAIL_HOST = 'smtp.company.com'
EMAIL_PORT = 25
EMAIL_HOST_PASSWORD = 'secret'
EMAIL_HOST_USER = 'user@company.com'

[django.db:default]
# Configure the django database
ENGINE = django.db.backends.sqlite3
NAME = $AS_HOME/var/lib/reef/reef.db

Section: [django]

This section will override Reef’s defsult django settings. All values must be valid python expressions [1]. The main point to remember is that any string values defined must have quotes around them.

Footnotes

[1]Specifically, this is limited to whatever the Python ast module method ast.literal_eval() will accept.

In the example above we override:

  • The default event page size returned to the Reef client to 200 rows (instead of the default 100 rows)
  • Define the e-mail list for ‘admins’
  • Define the e-mail host information so that Reef can send e-mails when issues arise.

A full reference for available settings can be found at https://docs.djangoproject.com/en/1.4/ref/settings/. Note that not all settings will affect the runtime behaviour of Reef. Contact Abilisoft Support if you have any queries about a specific Reef runtime setting that does not work as you would expect.

Section [django.db:default]

This section allows one to configure the default database that Reef will use. The values are simple strings and are not processed as Python expressions. However environment variables may be used. Refer to the section on Configuring the Database for details and examples.