AMI Configuration Guide

IMPORTANT - TO OVERRIDE PROPERTIES

Overview

Create a config/local.properties file and place each property to override on its own line in the format property.name=value

Step By Step

For amione, browse to the 3forge > amione > config directory and create a new, empty local.properties file. For amicenter, amirelay and amiweb browse to the config directory.

Hint

You can copy the default.properties to local.properties to get started with good default values.

Why we do this

So that even if you download and update a new version of AMI One, this file will not be overwritten (we will never include a local.properties file in the zip)

Sample local.properties

#My local.properties located under config directory

#Note, lines starting with pounds are comments

#Override the http port to standard port

http.port=80

#Override the location of the access.txt file

users.access.file=/home/myname/access.txt

Common Properties (AMI One, AMI Center, AMI Relay, AMI Web)

• f1.terminate.file: if supplied, then a file at specified location will be created. If an external process moves / copies to a file of the same name, but with a ".kill" suffix the process will exit.
• f1.threadpool.default.size: property name associated with the number of threads in the default thread pools.
• f1.threadpool.aggressive: if true will use an "aggressive" thread pool. This pool will wake up faster, but uses more CPU while idle.
• f1.conf.dir: directory to where the configuration files are located, default is config.
• f1.conf.filename: name of the configuration file loaded at start up, default is root.properties.
• f1.timezone: default time zone.
• f1.locale: default locale.
• f1.logs.dir: the root directory for where log files will be deposited.
• f1.plugins.dir: directory of where plugins are located.
• f1.resources.dir: directory of where additional resources will be placed.
• ami.components: a comma delimited list of which components to load. The components include relay, center and web. The default for AmiOne is all three: relay,center,web.

Relay Configuration Properties (AMI One, AMI Relay)

Relay General Properties (AMI One, AMI Relay)

• ami.relay.id: Sets the unique name of the relay. This is used to distinguish relays on the front end (when there are multiple relays connected to a single center).  Each relay should have a unique id
• ami.port: Sets the port that applications connect to on the Relay's host machine. The default port is 3289. See AMI Realtime API
• ami.port.bindaddr: Optional. Specifies the network interface that the ami.port server port be bound to
• ami.port.whitelist: Provide either a list of permitted hostname patterns or plugin for blocking/granting access based on foreign network address. Syntax is either file:<file_containing_a_hostname_patterns_per_line> or text:<comma_delimited_list_of_hostname_patterns> or plugin:<class_name_implementing_com.f1.ami.amicommon.AmiServerSocketEntitlementsPlugin>
• ami.log.messages: If set to true, all messages sent into and out of ami relay to/from other applications will be logged to a file
• ami.send.cr: If set to true, by default the relay will send a CR back on each response, in addition to a new line
• ami.center.host: Sets the hostname of the primary instance of ami center
• ami.center.backup.port: Optionally, sets the port of the backup instance of ami center
• ami.center.backup.host: Optionally, sets the hostname of the backup instance of ami center.
• ami.ssl.port: Optionally, sets the secure port that ami center is listening on.
• ami.ssl.backup.port: Optionally, sets the secure port that the backup ami center is listening on.
• ami.center.ssl.keystore.file: The path to the key store file, generated using java's keytool.
• ami.center.ssl.keystore.password: The password associated with the key store file
• ami.relay.guaranteed.messaging.enabled: If true, the relay will use a store and forward journal to record messages to disk prior to an ACK message being sent to the originating client.  The journal can also be used to deliver messages to late-subscribing Ami Centers. Default is false.
• ami.relay.persist.dir: Where to store the recovery journal files, if ami.relay.guaranteed.messaging.enabled is set to true. Default is ./persist
• ami.centers: A comma delimited list of centers' host:port to connect to. You can optionally prefix host:port with an alias in the form alias=host:port, in which case the alias will be used to reference the center within the relay.routes file. If an alias is not provided, then the alias is the host:port. Ex: ami.centers=myprimary=localhost:3270,other=some.host.com:3270
• ami.relay.routes.file: a file containing routing tables used for controlling which real-time streaming messages are sent to which center(s). Default is data/relay.routes  See relay.routes file for details. Note, if a file is not found, a placeholder file with instructions will be created there.

Relay.routes File

The relay can be connected to any number of centers (see ami.centers property). By default, as messages sent from an external source into a relay they are forwarded to all centers. By adding rules to the relay.routes file (see ami.relay.routes.file) you can control which centers are receiving messages based on any parameters within a message and/or the structure of the message itself. Each line within the file is an isolated rule. Changes to this file will take effect immediately.

Each line in the relay routes file is an isolated rule, with the following format:

ROUTE_NAME;PRIORITY;MESSAGE_TYPES;OBJECT_TYPES;PARAM_TYPES;EXPRESSION;ROUTE_LIST;SUCCESS_ACTION;FAIL_ACTION;SKIP_ACTION

Parameter	Description
ROUTE_NAME	Unique name of rule
PRIORITY	Higher priority rules execute first. Lower numbers have higher priority, with 0 being the highest priority. Ties are determined using alphabetical route name
MESSAGE_TYPES	Comma delimited list of messages types, only O (object), D (delete), C (Command) and S (Status) are supported, * - all types
OBJECT_TYPES	Comma delimited list of types to evaluate by this rule. Blank - skip rule, * - all types
PARAM_TYPES	Comma delimited list of param types for the rule in the format: Name Type [nonull]
EXPRESSION	Expression to evaluate, must return boolean, true return value indicates rule succeeded
ROUTE_LIST	Comma delimited list of centers to send message to. Blank - no centers, * - all servers
ON_TRUE	Action if Expression returns true: BREAK - stop evaluating rules, blank or CONTINUE - continue evaluating next rule
ON_FALSE	Action if Expression returns false or null: BREAK - stop evaluating rules, blank or CONTINUE - Continue evaluating next rule

Starting at the highest priority rule (lowest number), if the MESSAGE_TYPES and OBJECT_TYPES and PARAM_TYPES match the message, then the fields defined in the PARAM_TYPES are extracted from the message and passed into the EXPRESSION. If the expression returns true then the message is sent to all centers in the ROUTE_LIST. The ON_TRUE, ON_FALSE determine what to do next respective to the outcome.

Notes:

• Lines starting with a pound (#) are considered comments and skipped
• A particular message will only be sent to a particular center at most once, regardless of how many rules it matches

Example

#For NewOrder and Cancel messages with a symbol, route based on symbol. For all other messages router to all centers

RULE0;0;O,D;NewOrder,Cancel;Symbol String nonull;symbol < "F";Center0;BREAK;

RULE1;1;O,D;NewOrder,Cancel;Symbol String nonull;symbol < "Q";Center1;BREAK;

RULE2;2;O,D;NewOrder,Cancel;Symbol String nonull;true;Center2,Center3;BREAK;

RULE3;3;*;*;;true;*;BREAK;

Example messages:

O|T="NewOrder"|Symbol="AAPL"    <== will be sent Center0

O|T="NewOrder"|Symbol="IBM"    <== will be sent Center1

O|T="NewOrder"|Symbol="ZVZZT"    <== will be sent to both Center2,Center3

Center Configuration Properties (AMI One, AMI Center)

Center General Properties

• ami.naming.service: The password associated with the key store file
• ami.center.port: Sets the port of the primary instance of ami center
• ami.center.port.bindaddr: Optional. Specifies the network interface that the ami.center.port server port will be bound to
• ami.port.whitelist: Provide either a list of permitted hostname patterns or plugin for blocking/granting access based on foreign network address. Syntax is either file:<file_containing_a_hostname_patterns_per_line> or text:<comma_delimited_list_of_hostname_patterns> or plugin:<class_name_implementing_com.f1.ami.amicommon.AmiServerSocketEntitlementsPlugin>
• ami.aes.key.file: The aes key file used for encrypting / descrypting secure columns
• ami.aes.key.strength: Key strength, ex: 128
• idfountain.path: The path that is used persist files for managing auto-incrementing ids (amiid)
• idfountain.batchsize: (advanced)  The number of IDs AMI should generate per visit to the physical store.  Larger numbers mean less frequent visits to the file system but result in larger potential id-gaps on restart. Default is 1000000
• ami.unknown.realtime.table.behavior: Defines the behavior when real-time data is streamed into AMI but the type (T="...") values is undefined in the realtime database schema. The default is LEGACY.  Permissible values are:  IGNORE - drop records and don’t log anything, LOG_ERROR - drop records and log a warning, LEGACY - insert as a legacy record, CREATE_TABLE - Automatically create a new PUBLIC table with the correct columns corresponding to the record's fields and values.
• ami.center.publish.changes.period.millis - How often AMI Center publishes batched data changes out to consumers such as AmiWeb. Default is 500 milliseconds
• ami.log.query.max.chars - By default all queries, along with the username and duration are logged to the server log file. This property controls the max length of a query to get logged before truncating.  If set to 0 then the contents of the query are not logged. If -1 then nothing is logged
• ami.center.log.stats.period.millis - How often stats are written to the AmiOne.amilog (or AmiCenter.amilog) file
• ami.resources.monitor.period.millis - How often the resources directory is scanned for new/updated files. Default is 5,000 milliseconds. See ami.resources.dir
• ami.resources.dir - Where resources, such as images and audio files, are stored. These resources are accessed from the front end via Dashboard > Resource manager

Realtime Database Plugins (AMI one, AMI Center)

• ami.object.nobroadcast: Used to stop a type of message or data from broadcasting to AMI Web. This is used for increasing the performance of AMI Web when a type of data does not need to be pushed in real time to the front end and can be used as a "hard filter".  Should be a comma (,) delimited list of types (T=) of messages to suppress. See "AMI backend API" manual for details on specifying types on messages
• ami.object.indexes: Force indexes on the internal in memory database. The syntax is a comma delimited list of type.field pairs. Ex: account.fname,order.order_id
• ami.persist.dir: Directory where the center should store persistent data. This is any data that needs to persist after AMI center is shut down and restarted
• ami.datasource.plugins: A comma delimited list of java classes that implement the com.f1.ami.amicommon.AmiDatasourcePlugin interface. See plugin documentation for details
• ami.db.procedure.plugins: A comma delimited list of java classes that implement the com.f1.ami.center.procs. AmiStoredProcFactory interface. See plugin documentation for details
• ami.db.trigger.plugins: A comma delimited list of java classes that implement the com.f1.ami.center.triggers. AmiTriggerFactory interface. See plugin documentation for details
• ami.db.persister.plugins: A comma delimited list of java classes that implement the com.f1.ami.center.table.persist. AmiTablePersisterFactory interface. See plugin documentation for details
• ami.db.timer.plugins: A comma delimited list of java classes that implement the com.f1.ami.amicommon.AmiFactoryPlugin. AmiTimerFactory interface. See plugin documentation for details
• ami.db.dialect.plugins: Comma delimted list of classes implementing the com.f1.ami.center.dialectsAmiDbDialectPlugin interface.  Dialect plugins are used to adapt specific dialects (such as Tableau's mysql queries) into AMIDB's dialect