Difference between revisions of "AMI Configuration Guide"

From 3forge Documentation
Jump to navigation Jump to search
Tag: visualeditor-switched
m (add custom variable via start script)
 
(296 intermediate revisions by 11 users not shown)
Line 1: Line 1:
= IMPORTANT - TO OVERRIDE PROPERTIES =
+
= GETTING STARTED =
 
'''Overview'''
 
'''Overview'''
  
Create a config/'''local.properties''' file and place each property to override on its own line in the format '''''property.name=value'''''
+
Browse to the 3forge > amione > config directory and create a new, empty '''local.properties''' file and place each property to override on its own line in the format '''''property.name=value'''''
  
'''Step By Step'''
+
Hint: You can copy the default.properties to local.properties to get started with good default values.
  
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.
+
You might ask, why doesn't AMI just come with a default local.propertiers? This is so that when you download and update to a new version of AMI this file will not be overwritten, hence maintaining your existing settings.
 
 
'''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'''
 
'''Sample local.properties'''
Line 20: Line 12:
 
<span style="font-family: courier new; color: green;">#My local.properties located under config directory</span>
 
<span style="font-family: courier new; color: green;">#My local.properties located under config directory</span>
  
<span style="font-family: courier new; color: green;">#Note, lines starting with pounds are comments</span>
+
<span style="font-family: courier new; color: green;">#Note, lines starting with pounds are comments (except for #INCLUDE)</span>
  
 
<span style="font-family: courier new; color: green;">#Override the http port to standard port</span>
 
<span style="font-family: courier new; color: green;">#Override the http port to standard port</span>
Line 28: Line 20:
 
<span style="font-family: courier new; color: green;">#Override the location of the access.txt file</span>
 
<span style="font-family: courier new; color: green;">#Override the location of the access.txt file</span>
  
<span style="font-family: courier new; color: green;">users.access.file=/</span><span style="font-family: courier new; color: blue;">home/myname/access.txt</span>
+
<span style="font-family: courier new; ">users.access.file=/</span><span style="font-family: courier new; color: blue;">home/myname/access.txt</span>
 +
 
 +
<span style="font-family: courier new; color: green;">#Process and include properties from a custom properties file</span>
 +
 
 +
<span style="font-family: courier new; color: green;">#INCLUDE </span><span style="font-family: courier new; color: blue;">home/env_specific.properties</span>
 +
 
 +
<span style="font-family: courier new; color: green;">#Define my own custom value</span>
 +
 
 +
<span style="font-family: courier new; ">my.custom.value=</span><span style="font-family: courier new; color: blue;">5</span>
 +
 
 +
<span style="font-family: courier new; color: green;">#Reference my custom value</span>
 +
 
 +
<span style="font-family: courier new; ">ami.frames.per.second=</span><span style="font-family: courier new; color: blue;">${my.custom.value}</span>
  
== Common Properties (AMI One, AMI Center, AMI Relay, AMI Web) ==
+
<span style="font-family: courier new; color: green;">#Append to an existing variable</span>
  
* <span style="font-family: courier new; color: blue;">f1.terminate.file</span>: 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.
+
<span style="font-family: courier new; ">ami.datasource.plugins=</span><span style="font-family: courier new; color: blue;">$${ami.datasource.plugins},com.my.Plugin</span>
* <span style="font-family: courier new; color: blue;">f1.threadpool.default.size</span>: property name associated with the number of threads in the default thread pools.
+
 
 +
<span style="font-family: courier new; color: green;">#Remove a specific property in any of AMI's prepackaged configuration (root.properties, speedlogger.properties, defaults.properties). </span>
 +
 
 +
<span style="font-family: courier new; color: red">#UNDEFINE </span> <span style="font-family: courier new; ">speedlogger.sink.FILE_SINK.maxFiles=10</span>
 +
 
 +
= Common Properties (Applies to Components: Center, Relay, Web, WebBalancer) =
 +
 
 +
* <span style="font-family: courier new; color: blue;">f1.terminate.file</span>: A small file will be created and monitored by AMI. If an external process moves / copies to a file of the same name, but with a ".kill" suffix the process will exit (this provides any easy way for an external script or job control process to cleanly shutdown AMI).
 +
* <span style="font-family: courier new; color: blue;">f1.threadpool.default.size</span>: The number of threads in the core thread pool (this does not include threads for http servicing or image processing).
 
* <span style="font-family: courier new; color: blue;">f1.threadpool.aggressive</span>: if true will use an "aggressive" thread pool. This pool will wake up faster, but uses more CPU while idle.
 
* <span style="font-family: courier new; color: blue;">f1.threadpool.aggressive</span>: if true will use an "aggressive" thread pool. This pool will wake up faster, but uses more CPU while idle.
 
* <span style="font-family: courier new; color: blue;">f1.conf.dir</span>: directory to where the configuration files are located, default is ''config''.
 
* <span style="font-family: courier new; color: blue;">f1.conf.dir</span>: directory to where the configuration files are located, default is ''config''.
 
* <span style="font-family: courier new; color: blue;">f1.conf.filename</span>: name of the configuration file loaded at start up, default is ''root.properties''.
 
* <span style="font-family: courier new; color: blue;">f1.conf.filename</span>: name of the configuration file loaded at start up, default is ''root.properties''.
* <span style="font-family: courier new; color: blue;">f1.timezone</span>: default time zone.
+
* <span style="font-family: courier new; color: blue;">f1.timezone</span>: set timezone for Java (note, this does not control default user or logger timezones)
 
* <span style="font-family: courier new; color: blue;">f1.locale</span>: default locale.
 
* <span style="font-family: courier new; color: blue;">f1.locale</span>: default locale.
 
* <span style="font-family: courier new; color: blue;">f1.logs.dir</span>: the root directory for where log files will be deposited.
 
* <span style="font-family: courier new; color: blue;">f1.logs.dir</span>: the root directory for where log files will be deposited.
* <span style="font-family: courier new; color: blue;">f1.plugins.dir</span>: directory of where plugins are located.
+
* <span style="font-family: courier new; color: blue;">f1.plugins.dir</span>: directory of where plugins will be loaded from.
 
* <span style="font-family: courier new; color: blue;">f1.resources.dir</span>: directory of where additional resources will be placed.
 
* <span style="font-family: courier new; color: blue;">f1.resources.dir</span>: directory of where additional resources will be placed.
* <span style="font-family: courier new; color: blue;">ami.components</span>: 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.
+
* <span style="font-family: courier new; color: blue;">ami.components</span>: a comma delimited list of which components to load, which can include an of: relay,center,web,webbalancer,webmanager. The default is the three components: relay,center,web.
 +
* <span style="font-family: courier new; color: blue;">ami.amilog.stats.period</span>: How often AMI should log general health statistics such as memory, user load, etc. which can be used for real-time/historical monitoring via the performance dashboard.  Default: ''15 SECONDS''.
 +
* <span style="font-family: courier new; color: blue;">ami.naming.service.resolvers</span>: Specify a comma delimited list of naming service plugin classes (implements com.f1.ami.amicommon.AmiNamingServiceResolver). These can be used to map logic service names to physical host/ports.
 +
* <span style="font-family: courier new; color: blue;">ami.content.security.policy</span>: The default content security policy is:<code>img-src 'self' <nowiki>https://*.mapbox.com data: w3.org/svg/2000; default-src https://*.mapbox.com 'self' 'unsafe-inline' 'unsafe-eval' blob:</nowiki></code>.For more information regarding Content Security Policy, please refer to the following link: '''[https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP Content Security Policy (CSP)]'''
 +
* <span style="font-family: courier new; color: blue;">ami.aes.key.file</span>: The aes key file used for encrypting / decrypting secure data (see strEncrypt/strDecrypt in amiscript for examples)
 +
* <span style="font-family: courier new; color: blue;">ami.aes.key.text</span>: The aes key used for encrypting / decrypting secure columns (instead of using ami.aes.key.file)
 +
* <span style="font-family: courier new; color: blue;">ami.aes.key.strength</span>: Key strength, ex: 128
  
= Relay Configuration Properties (AMI One, AMI Relay) =
+
= Java VM Properties (These should be included in the start.sh or AMI_One.vmoptions file) =
 +
The Java VM Properties can be configured in '''''AMI_One.vmoptions''''' (for windows) or '''''AMI_One_linux.vmoptions'''''(for linux), which are parsed in '''''start.sh'''''. Some of these properties control how messages are logged and how garbage collection is handled. Here are some concrete examples of Java VM Properties<br>
 +
* <span style="font-family: courier new; color: blue;">-Df1.global.procinfosink.file=./.f1proc.txt</span>:Controls where AMI will write proc information.  Note, this proc information includes uptime/downtime/process id/and processuid
 +
* <span style="font-family: courier new; color: blue;">-Df1.license.file=${HOME}/f1license.txt,f1license.txt,config/f1license.txt</span>:Comma delimited list of where the f1license.txt file(s) should be looked for
 +
* <span style="font-family: courier new; color: blue;">-Df1.license.property.file=config/local.properties</span>The file that contains a line in the format ''f1.license.file=xxxxx'' which points to the license file
 +
* <span style="font-family: courier new; color: blue;">-Dproperty.f1.conf.dir=config/</span>:Directory where the root.properties is located.
 +
* <span style="font-family: courier new; color: blue;">-Djava.util.logging.manager=com.f1.speedlogger.sun.SunSpeedLoggerLogManager</span>:Forces java to use the 3Forge logger
 +
* <span style="font-family: courier new; color: blue;">-Dlog4j.configuratorClass=com.f1.speedloggerLog4j.Log4jSpeedLoggerManager</span>:Forces other 3rd party plugins that were written for log4j to use 3Forge logger instead
 +
* <span style="font-family: courier new; color: blue;">-Dlog4j.configuration=com/f1/speedloggerLog4j/Log4jSpeedLoggerManager.class</span>:Forces other 3rd party plugins that were written for log4j to use 3Forge logger instead
 +
* <span style="font-family: courier new; color: blue;">-Dproperty.f1.properties.secret.key.files=/path/to/keyfile</span>:If specified, the ${CIPHER:xxxxxx} syntax within .properties files will be decoded using the file's key. (See tools.sh for creating a key).  comma delimit for multiple files
 +
* <span style="font-family: courier new; color: blue;">-Dproperty.f1.properties.decrypters=[DECRYPTERID]=com.package.DecrypterClass</span>:If specified, the ${CIPHER:[DECRYPTERID]:xxxxxx} syntax within .properties files will be decoded using class. (See com.f1.utils.encrypt.Decrypter Interface)  Comma delimit for multiple classes
 +
<br>
 +
Variables declared in the following way can be referenced in your local.properties file with ${}:
 +
 
 +
* <span style="font-family: courier new; color: blue;">-Dproperty.your.variable.name=value</span>
 +
 
 +
= Relay Configuration Properties (Applies to Components: Relay) =
 +
Note: To run the ami relay, include ''relay'' in the list of components found in the the ami.components property, ex: <span style="font-family: courier new; color: blue;">ami.components=relay</span>
  
 
== Relay General Properties (AMI One, AMI Relay) ==
 
== Relay General Properties (AMI One, AMI Relay) ==
  
 
* <span style="font-family: courier new; color: blue;">ami.relay.id</span>: 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
 
* <span style="font-family: courier new; color: blue;">ami.relay.id</span>: 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
* <span style="font-family: courier new; color: blue;">ami.port</span>: Sets the port that applications connect to on the Relay's host machine. The default port is 3289. See AMI Realtime API
+
* <span style="font-family: courier new; color: blue;">ami.port</span>: Sets the port that applications connect to on the Relay's host machine. The default port is 3289. See AMI Realtime API. When set to -1, the socket is not started and refuses any connections to the relay.
 
* <span style="font-family: courier new; color: blue;">ami.port.bindaddr</span>: Optional. Specifies the network interface that the ''ami.port'' server port be bound to
 
* <span style="font-family: courier new; color: blue;">ami.port.bindaddr</span>: Optional. Specifies the network interface that the ''ami.port'' server port be bound to
 +
* <span style="font-family: courier new; color: blue;">ami.port.keystore.file</span>: The path to the key store file, generated using java's keytool.
 +
* <span style="font-family: courier new; color: blue;">ami.port.keystore.password</span>: The password associated with the key store file.
 +
* <span style="font-family: courier new; color: blue;">ami.port.wait.for.center</span>: The duration to wait for center to start up
 
* <span style="font-family: courier new; color: blue;">ami.port.whitelist</span>: 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>
 
* <span style="font-family: courier new; color: blue;">ami.port.whitelist</span>: 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>
 +
* <span style="font-family: courier new; color: blue;">ami.datasource.plugins</span>: A comma delimited list of java classes that implement the com.f1.ami.amicommon.AmiDatasourcePlugin interface. See plugin documentation for details
 +
* <span style="font-family: courier new; color: blue;">ami.center.port</span>: Sets the port of the primary instance of ami center
 +
* <span style="font-family: courier new; color: blue;">ami.center.host</span>: Sets the hostname of the primary instance of ami center
 +
* <span style="font-family: courier new; color: blue;">ami.centers</span>: 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
 +
* <span style="font-family: courier new; color: blue;">ami.center.[name].keystore.file</span>: Supply if center is using ssl connection. The path to the key store file, generated using java's keytool. (Name is the center name as it appears in ami.centers property)
 +
* <span style="font-family: courier new; color: blue;">ami.center.[name].keystore.contents.base64</span>: Supply if center is using ssl connection. The contents of the keystore as a base64 (instead of supplying the file name) (Name is the center name as it appears in ami.centers property)
 +
* <span style="font-family: courier new; color: blue;">ami.center.[name].keystore.password</span>: Supply if center is using ssl connection. The password associated with the key store file (Name is the center name as it appears in ami.centers property)
 +
* <span style="font-family: courier new; color: blue;">ami.relay.persist.dir</span>: Where to store the recovery journal files, if ami.relay.guaranteed.messaging.enabled is set to true. Default is ./persist
 +
* <span style="font-family: courier new; color: blue;">ami.relay.guaranteed.messaging.enabled</span>: 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.
 +
 +
* <span style="font-family: courier new; color: blue;">ami.relay.routes.file</span>: 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| Relay Routes File]] for details. Note, if a file is not found, a placeholder file with instructions will be created there.
 
* <span style="font-family: courier new; color: blue;">ami.log.messages</span>: If set to true, all messages sent into and out of ami relay to/from other applications will be logged to a file
 
* <span style="font-family: courier new; color: blue;">ami.log.messages</span>: If set to true, all messages sent into and out of ami relay to/from other applications will be logged to a file
 +
 
* <span style="font-family: courier new; color: blue;">ami.send.cr</span>: If set to true, by default the relay will send a CR back on each response, in addition to a new line
 
* <span style="font-family: courier new; color: blue;">ami.send.cr</span>: If set to true, by default the relay will send a CR back on each response, in addition to a new line
* <span style="font-family: courier new; color: blue;">ami.center.host</span>: Sets the hostname of the primary instance of ami center
+
 
* <span style="font-family: courier new; color: blue;">ami.center.backup.port</span>: Optionally, sets the port of the backup instance of ami center
+
== Relay.routes File ==
* <span style="font-family: courier new; color: blue;">ami.center.backup.host</span>: Optionally, sets the hostname of the backup instance of ami center.
+
The relay can be connected to any number of centers (see [[Relay Properties Ami One Ami Relay.htm#ami.centers|ami.centers property]]). By default, as messages are sent from an external source into a relay they are forwarded to all centers. By adding rules to the relay.routes file (see [[Relay Properties Ami One Ami Relay.htm#ami.relay.routes.file|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.
* <span style="font-family: courier new; color: blue;">ami.ssl.port</span>: Optionally, sets the secure port that ami center is listening on.
+
 
* <span style="font-family: courier new; color: blue;">ami.ssl.backup.port</span>: Optionally, sets the secure port that the backup ami center is listening on.
+
To support dynamic routing, changes to this file during runtime 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
 +
{| class="wikitable"
 +
!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'''
 +
 
 +
<nowiki>#</nowiki>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 (Applies to Components: Center) =
 +
 
 +
Note: To run the ami center, include ''center'' in the list of components found in the the ami.components property, ex: <span style="font-family: courier new; color: blue;">ami.components=center</span>
 +
 
 +
== Center General Properties ==
 +
 
 +
* <span style="font-family: courier new; color: blue;">ami.center.port</span>: Sets the port of the primary instance of ami center
 +
* <span style="font-family: courier new; color: blue;">ami.center.port.bindaddr</span>: Optional. Specifies the network interface that the ''ami.center.port'' server port will be bound to
 +
* <span style="font-family: courier new; color: blue;">ami.port.whitelist</span>: 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:<newline_delimited_list_of_hostname_patterns> or plugin:<class_name_implementing_com.f1.ami.amicommon.AmiServerSocketEntitlementsPlugin>
 +
* <span style="font-family: courier new; color: blue;">ami.center.ssl.port</span>: Optionally, sets the secure port that ami center is listening on.
 
* <span style="font-family: courier new; color: blue;">ami.center.ssl.keystore.file</span>: The path to the key store file, generated using java's keytool.
 
* <span style="font-family: courier new; color: blue;">ami.center.ssl.keystore.file</span>: The path to the key store file, generated using java's keytool.
 
* <span style="font-family: courier new; color: blue;">ami.center.ssl.keystore.password</span>: The password associated with the key store file
 
* <span style="font-family: courier new; color: blue;">ami.center.ssl.keystore.password</span>: The password associated with the key store file
* <span style="font-family: courier new; color: blue;">ami.relay.guaranteed.messaging.enabled</span>: 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.
+
* <span style="font-family: courier new; color: blue;">idfountain.path</span>: The path that is used persist files for managing auto-incrementing ids (amiid)
* <span style="font-family: courier new; color: blue;">ami.relay.persist.dir</span>: Where to store the recovery journal files, if ami.relay.guaranteed.messaging.enabled is set to true. Default is ./persist
+
* <span style="font-family: courier new; color: blue;">idfountain.batchsize</span>: (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
* <span style="font-family: courier new; color: blue;">ami.centers</span>: 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
+
* <span style="font-family: courier new; color: blue;">ami.db.auth.plugin.class</span>: Class name of custom authenticator which must implement com.f1.ami.web.auth.AmiAuthenticator interface and be deposited in the plugin directory. The plugin will be responsible for user authentication and configuration. See Ami Authenticator Plugin Manual for details.
* <span style="font-family: courier new; color: blue;">ami.relay.routes.file</span>: 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.htm|relay.routes file]] for details. Note, if a file is not found, a placeholder file with instructions will be created there.
+
 
 +
* <span style="font-family: courier new; color: blue;">ami.unknown.realtime.table.behavior</span>: 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.
 +
* <span style="font-family: courier new; color: blue;">ami.center.publish.changes.period.millis</span> - How often AMI Center publishes batched data changes out to consumers such as AmiWeb. Default is 500 milliseconds
 +
* <span style="font-family: courier new; color: blue;">ami.log.query.max.chars</span> - 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
 +
* <span style="font-family: courier new; color: blue;">ami.center.log.stats.period.millis</span> - How often stats are appended to the AmiOne.amilog file in milliseconds (default is 15 seconds)
 +
* <span style="font-family: courier new; color: blue;">ami.resources.monitor.period.millis</span> - How often the resources directory is scanned for new/updated files. Default is 5,000 milliseconds. See ami.resources.dir
 +
* <span style="font-family: courier new; color: blue;">ami.resources.dir</span> - 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 (Applies to Components: Center) ==
 +
 
 +
* <span style="font-family: courier new; color: blue;">ami.object.nobroadcast</span>: 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
 +
* <span style="font-family: courier new; color: blue;">ami.object.indexes</span>: 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''
 +
* <span style="font-family: courier new; color: blue;">ami.persist.dir</span>: Directory where the center should store persistent data. This is any data that needs to persist after AMI center is shut down and restarted
 +
* <span style="font-family: courier new; color: blue;">ami.datasource.plugins</span>: A comma delimited list of java classes that implement the ''com.f1.ami.amicommon.AmiDatasourcePlugin'' interface. See plugin documentation for details
 +
* <span style="font-family: courier new; color: blue;">ami.db.procedure.plugins</span>: A comma delimited list of java classes that implement the ''com.f1.ami.center.procs.'' ''AmiStoredProcFactory'' interface. See plugin documentation for details
 +
* <span style="font-family: courier new; color: blue;">ami.db.trigger.plugins</span>: A comma delimited list of java classes that implement the ''com.f1.ami.center.triggers.'' ''AmiTriggerFactory'' interface. See plugin documentation for details
 +
* <span style="font-family: courier new; color: blue;">ami.db.persister.plugins</span>: A comma delimited list of java classes that implement the ''com.f1.ami.center.table.persist.'' ''AmiTablePersisterFactory'' interface. See plugin documentation for details
 +
* <span style="font-family: courier new; color: blue;">ami.db.timer.plugins</span>: A comma delimited list of java classes that implement the ''com.f1.ami.amicommon.AmiFactoryPlugin.'' ''AmiTimerFactory'' interface. See plugin documentation for details
 +
* <span style="font-family: courier new; color: blue;">ami.db.dialect.plugins</span>: 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
 +
* <span style="font-family: courier new; color: blue;">ami.db.console.prompt</span>: takes in a string to customize AMI DB console prompt. E.g. -PROD -> AMIDB-PROD>
 +
 
 +
== Realtime Database Configuration Properties (Applies to Components: Center)==
 +
 
 +
* <span style="font-family: courier new; color: blue;">ami.datasource.timeout.millis</span>: Default amount of time, in milliseconds, AMI will wait for a datasource to respond to a query before timing out. Default is 60000 (one minute)
 +
* <span style="font-family: courier new; color: blue;">ami.datasource.concurrent.queries.per.user</span>: The max number of queries to a specific datasource from a specific user that can be invoked simultaneously.  Default is 5
 +
* <span style="font-family: courier new; color: blue;">ami.db.schema.config.files</span>: A comma delimited list of sql files to execute on startup
 +
* <span style="font-family: courier new; color: blue;">ami.db.schema.managed.file</span>: The file that contains the schema to execute on startup, as defined via the command line.  For example, if a user creates a new public table, this file will be updated to include the modified schema so that next time AMI is restarted the table still exists.
 +
* <span style="font-family: courier new; color: blue;">ami.db.table.default.refresh.period.millis</span>: The max delay for refreshing changes to the front end.  (See RefreshPeriodMs column in the __TABLE table)
 +
* <span style="font-family: courier new; color: blue;">ami.db.max.stack.size</span>: The max stack size for nesting triggers / procedure calls. Default is 4
 +
* <span style="font-family: courier new; color: blue;">ami.db.persist.dir</span>: For tables with persistence, the directory that the data is stored in.  (See PersistEngine in the USE options of the CREATE PUBLIC TABLE clause)
 +
* <span style="font-family: courier new; color: blue;">ami.db.persist.dir.system.tables</span>: The directory where the contents of system tables (ex: __TABLE, __COLUMN, ...)  are stored by default.
 +
* <span style="font-family: courier new; color: blue;">ami.db.persist.dir.system.table.[__''system_table_name'']</span>: The Directory where the contents of a specific system table is stored. Ex: ''ami.db.persist.dir.system.table.__DATASOURCE=/var/mydatasources''
 +
* <span style="font-family: courier new; color: blue;">ami.db.timer.logging.enabled</span>: Default is true, which says that each time a timer is fired a log line will be written to the log file.  In instances where timers are firing frequently, it is optimal to set this to false
 +
* <span style="font-family: courier new; color: blue;">ami.db.console.port</span>: The port for connecting via telnet command line interface. Default is 3290
 +
* <span style="font-family: courier new; color: blue;">ami.db.console.port.bindaddr</span>: Optional. Specifies the network interface that the ''ami.db.console.port.bindaddr'' server port will be bound to
 +
* <span style="font-family: courier new; color: blue;">ami.db.console.port.whitelist</span>: provide either a list, file 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>
 +
* <span style="font-family: courier new; color: blue;">ami.db.console.history.dir</span>: The directory that stores command line history
 +
* <span style="font-family: courier new; color: blue;">ami.db.console.history.max.lines</span>: Max number of lines to store, default is 10000
 +
* <span style="font-family: courier new; color: blue;">ami.db.jdbc.port</span>: The port for connecting to AMI via the AMI JDBC driver. Default is 3280
 +
* <span style="font-family: courier new; color: blue;">ami.db.jdbc.port.bindaddr</span>: Optional. Specifies the network interface that the ''ami.db.jdbc.port'' server port will be bound to
 +
* <span style="font-family: courier new; color: blue;">ami.db.jdbc.port.whitelist</span>: 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>
 +
* <span style="font-family: courier new; color: blue;">ami.jdbc.auth.plugin.class</span>: By default pointing to ${ami.db.auth.plugin.class}, which sets target database's JDBC endpoints
 +
* <span style="font-family: courier new; color: blue;">ami.db.anonymous.datasources.enabled</span>: should users be able to access undefined-datasources dynamically (via the USE DS_ADAPTER directive)
 +
* <span style="font-family: courier new; color: blue;">ami.db.disable.functions</span>: Comma delimited list of functions to disable, by default strDecrypt is disabled
 +
* <span style="font-family: courier new; color: blue;">ami.db.default.permissions</span>: When a user logs into the database and does not have an AMIDB_PERMISSIONS option associated with there account, what are the default permissions. Should be a comma delimited combination of READ, WRITE, ALTER, and EXECUTE. Blank means no permissions, default is all permissions( READ,WRITE,ALTER,EXECUTE)
 +
* <span style="font-family: courier new; color: blue;">amiscript.db.variable.''varname''</span>: Declare a readonly variable available in the AMI Center database.  The value should be wrapped in quotes for a string, or properly formatted to indicate the type. Note, you can see declared variables via SHOW VARS. Examples:
 +
** amiscript.db.variable.hello="world"  //declare a string named hello
 +
** amiscript.db.variable.num=123L  //declare a long named num.
 +
*  <span style="font-family: courier new; color: blue;">ami.db.onstartup.ondisk.defrag </span>: If true, then on startup the ONDISK columns for persisted tables will be defragmented meaning empty blocks, do to deletes/updates will be removed. If false, then defrag is skipped but empty blocks will attempt to be reused.  true is default
 +
 
 +
= Email Configuration Properties =
 +
 
 +
To send emails from you account via AMI, you will need to add the some of these properties to local.properties file:
 +
 
 +
* <span style="font-family: courier new; color: blue;">email.client.host</span>: The SMTP server to connect to. To connect to the Gmail SMTP server use host as smtp.gmail.com
 +
* <span style="font-family: courier new; color: blue;">email.client.port</span>: The SMTP server port to connect to. To connect to the Gmail SMTP server use port as 465.
 +
* <span style="font-family: courier new; color: blue;">email.client.username</span>: Username for the email account.
 +
* <span style="font-family: courier new; color: blue;">email.client.password</span>: Password for the email account.
 +
* <span style="font-family: courier new; color: blue;">email.client.authentication.enabled</span>: If true, attempts to authenticate the user. Defaults to true.
 +
* <span style="font-family: courier new; color: blue;">email.client.ssl.enabled</span>: If true, use SSL to connect and use the SSL port by default. Defaults to false for the SMTP protocol.
 +
* <span style="font-family: courier new; color: blue;">email.client.start.tls.enabled</span>: If true, enables the use of the STARTTLS command (if supported by the server) to switch the connection to a TLS-protected connection before issuing any login commands. If the server does not support STARTTLS, the connection continues without the use of TLS. Defaults to true.
 +
* <span style="font-family: courier new; color: blue;">email.client.retries.count</span>: Number of times it tries to reconnect to the SMTP server. If 0, it will not retry if connection fails. And, for example, if set to 2 it will retry 2 times (so 3 trys in total).
 +
* <span style="font-family: courier new; color: blue;">email.client.debug.enabled</span>: If true, AMI can debug email related information
 +
 
 +
= Web Configuration Properties (Applies to Components: Web) =
 +
Note: To run the ami web, include ''web'' in the list of components found in the the ami.components property, ex: <span style="font-family: courier new; color: blue;">ami.components=web</span>
 +
== License ==
 +
 
 +
* <span style="font-family: courier new; color: blue;">ami.license.file</span>: location of where to place/edit license file when using license wizard (under Help -> Enter/Update License). Default is ./f1license.txt
 +
* <span style="font-family: courier new; color: blue;">ami.web.disable.license.wizard</span>: Hide the Help -> Enter/Update License menu item, even when not in developer mode  
 +
* <span style="font-family: courier new; color: blue;">ami.web.license.auth.url</span>: the url for connecting to 3forge's server and generating license files (accessed from Help ->Enter/Update License -> Generate License Key). If blank, then the Generaet License Key button is not available and licenses must be manually generated via the website portal.
 +
* <span style="font-family: courier new; color: blue;">f1.license.warning.days</span>: The number of days prior to a valid license expiring that a warning message will start appearing on the login page. Default is 14 days.
 +
 
 +
== HTTP Connection & Session Options ==
 +
 
 +
* <span style="font-family: courier new; color: blue;">http.port</span>: sets the port that web browsers use to connect to AMI Web. The default port is 31313.
 +
* <span style="font-family: courier new; color: blue;">https.port</span>: sets the port that web browsers use to connect securely to AMI Web. The default port is 3333  https.keystore.file: the path to the key store file generated using java's keytool that will be used for secure web connections.
 +
* <span style="font-family: courier new; color: blue;">https.keystore.password</span>: the password associated with the key store file specified in the ''https.keystore.file'' property.
 +
* <span style="font-family: courier new; color: blue;">ami.web.http.connections.max</span>: the maximum number of concurrent http connections (for preventing DOS attacks). Default is ''100''
 +
* <span style="font-family: courier new; color: blue;">ami.web.http.connections.timeout.ms</span>: the number of milliseconds before an idle http connection is closed. Default is ''30000''
 +
* <span style="font-family: courier new; color: blue;">ami.session.check.period.seconds</span>: the number of seconds between which AMI checks and removes expired sessions (users that have closed their AMI tab/browser, or are disconnected w/o a valid logout).  Default is 60 seconds.
 +
* <span style="font-family: courier new; color: blue;">ami.session.timeout.seconds</span>: the number of seconds that must pass before a session is considered expired, causing the user to automatically be logged out. Default is 300 seconds.
 +
* <span style="font-family: courier new; color: blue;">ami.allow.site.framed</span>: allow the ami webpage to be framed inside an iframe. If false, then x-Frame-Options and SameSite options are included in header. Default is ''true''
 +
* <span style="font-family: courier new; color: blue;">http.port.bindaddr</span>: Optional. Specifies the network interface that the ''http.port'' server port will be bound to
 +
* <span style="font-family: courier new; color: blue;">https.port.bindaddr</span>: Optional. Specifies the network interface that the ''https.port'' server port will be bound to
 +
* <span style="font-family: courier new; color: blue;">ami.session.cookiename</span>: name of the cookie to store in the web browser for the sessionid. Default is F1SESSION. If multiple AMI instances are sharing a host then each must have a unique cookiename
 +
* <span style="font-family: courier new; color: blue;">http.port.whitelist</span>: 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:<New_line_delimited_list_of_hostname_patterns> or plugin:<class_name_implementing_com.f1.ami.amicommon.AmiServerSocketEntitlementsPlugin>
 +
* <span style="font-family: courier new; color: blue;">https.port.whitelist</span>: 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>
 +
* <span style="font-family: courier new; color: blue;">amiscript.variable.''varname''</span>: Declare a readonly variable available throughout the dashboard's amiscript.  The value should be wrapped in quotes for a string, or properly formatted to indicate the type. Note, you can see declared variables via Menu -> Dashboard -> Session Variables. Examples:
 +
** amiscript.variable.hello="world"  //declare a string named hello
 +
** amiscript.variable.num=123L  //declare a long named num.
 +
* <span style="font-family: courier new; color: blue;">users.access.file.encrypt.mode</span>''':''' ''off'' indicates the access.txt file is plain text.  ''password'' indicates that the password portion must be encrypted.  See strEncrypt(...) function for encrypting passwords. Default if ''off''. Can be set to '''password''' to turn encryption on.
 +
* <span style="font-family: courier new; color: blue;">ami.centers</span>: a comma delimted list of centers' host:port to connect to.  You can optionally prefix a 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 dashboard. If an alias is not provided, then the alias is the host:port.  Note, the first supplied URL is considered the primary center.Ex: ami.centers=myprimary=localhost:3270,other=some.host.com:3270
 +
* <span style="font-family: courier new; color: blue;">ami.center.[name].keystore.file</span>: Supply if center is using ssl connection. The path to the key store file, generated using java's keytool. (Name is the center name as it appears in ami.centers property)
 +
* <span style="font-family: courier new; color: blue;">ami.center.[name].keystore.contents.base64</span>: Supply if center is using ssl connection. The contents of the keystore as a base64 (instead of supplying the file name) (Name is the center name as it appears in ami.centers property)
 +
* <span style="font-family: courier new; color: blue;">ami.center.[name].keystore.password</span>: Supply if center is using ssl connection. The password associated with the key store file (Name is the center name as it appears in ami.centers property)
 +
* <span style="font-family: courier new; color: blue;">ami.web.http.slow.response.warn.ms</span>: Log a warning if a full round trip http request/response is greater than the specified duration in milliseconds.  Default is 5000
 +
* <span style="font-family: courier new; color: blue;">ami.web.show.wait.icon.after.duration</span>: the duration before displaying the loading / waiting icon. Default is ''2000 milliseconds''
 +
* <span style="font-family: courier new; color: blue;">ami.slow.amiscript.warn.ms</span>: Log a warning if an amiscript block can not be executed the specified duration in milliseconds. Default is 1000
 +
* <span style="font-family: courier new; color: blue;">ami.web.portal.dialog.header.title</span>: title on the portal dialog header (i.e. loading and error dialogs).
 +
 
 +
== Login Options ==
 +
 
 +
* <span style="font-family: courier new; color: blue;">ami.login.page.animated</span>: Boolean indicating if login page should display animated background. True by default, recommended to set to false if used on remote desktops.
 +
* <span style="font-family: courier new; color: blue;">ami.login.page.title</span>: the suffix to include in the login page web's title (appended to 3forge - )
 +
* <span style="font-family: courier new; color: blue;">ami.login.page.terms.and.conditions.file</span>: Optional file to include in the login page, requiring user to acknowledge the terms and conditions before logging in.
 +
* <span style="font-family: courier new; color: blue;">contact.email</span>: The email address for contacting support on a login issue, or to create a new account. Default is "support@3forge.com?subject=Ami Account Request"
 +
* <span style="font-family: courier new; color: blue;">ami.login.page.logo.file</span>: Path to file containing image for login in login screen. Image will be scaled to a pixel width and height of 350x200. It's suggested that the image should be exactly that size to avoid scaling artifacts.
 +
* <span style="font-family: courier new; color: blue;">web.title</span>: Change the title in the web browser tab
 +
* <span style="font-family: courier new; color: blue;">web.logged.out.url</span>: url to redirect to when logged out, default is / which directs to login page. (Hint: set to /loggedout.htm for a logged out page instead, useful for OAUTH)
 +
* <span style="font-family: courier new; color: blue;">web.favicon</span>: The icon to put in the tab
 +
* <span style="font-family: courier new; color: blue;">f1.license.warning.days</span>: Number of days to start displaying warning on login page before license expires
 +
* <span style="font-family: courier new; color: blue;">ami.web.splashscreen.info.html</span>: Information to show on the splashscreen (rendered as html)
 +
* <span style="font-family: courier new; color: blue;">ami.web.default.MAXSESSIONS</span>:Maximum number of sessions allowed per login of a user
 +
 
 +
== Developer Options ==
 +
 
 +
* <span style="font-family: courier new; color: blue;">ami.autosave.dir</span>: the directory where autosaved versions of the layout are saved. Default is ''data/autosave''
 +
* <span style="font-family: courier new; color: blue;">ami.autosave.count</span>: The minimum number of backup revisions of layouts that should be saved per user
 +
* <span style="font-family: courier new; color: blue;">ami.autosave.layout.frequency</span>: How often layouts will be automatically saved to the backup log file. Default is: ''15 MINUTES''
 +
* <span style="font-family: courier new; color: blue;">ami.messages.max.info</span>: Maximum number of debug/info messages to store for debugging purposes in edit mode.  Default is ''100''
 +
* <span style="font-family: courier new; color: blue;">ami.messages.max.warn</span>: Maximum number of warming messages to store for debugging purposes in edit mode.  Default is ''100''
 +
 
 +
== Plugins ==
 +
 
 +
* <span style="font-family: courier new; color: blue;">ami.web.auth.plugin.class</span>: Class name of custom authenticator which must implement ''com.f1.ami.web.auth.AmiAuthenticator'' interface and be deposited in the plugin directory. The plugin will be responsible for user authentication and configuration. See Ami Authenticator Plugin Manual for details.
 +
* <span style="font-family: courier new; color: blue;">ami.auth.namespace</span>: Optional namespace that will be passed into authenticator's authenticate(...) method
 +
* <span style="font-family: courier new; color: blue;">amiscript.custom.classes</span>: A comma delimited list of classes to include for acce''ss within ami script. See plugin doc''umentation for details.
 +
* <span style="font-family: courier new; color: blue;">ami.style.files</span>: Comma delimited list of files (wildcards supported) which cont''ain ami styles. (see menu -> dashboa''rd -> style manager)
 +
* <span style="font-family: courier new; color: blue;">ami.web.panels</span>: Comma delimited list of custom panel type configurations.
 +
*<span style="font-family: courier new; color: blue;">ami.auth.timeout.ms</span>: Amount of time, in milliseconds before AMI assumes the authentication plugin has timed out. Default is 5000 milliseconds
 +
* <span style="font-family: courier new; color: blue;">ami.web.data.filter.plugin.class</span>: Class name of custom Data Filter which must implement the ''com.f1.ami.web.datafilter. AmiWebDataFilterPlugin'' interface and be deposited in the plugin directory.  The plugin will be responsible for filtering out data that users shoud have and not have access to.  See Ami Data Data Filter Plugin manual For details
 +
* <span style="font-family: courier new; color: blue;">ami.guiservice.plugins</span>: A comma delimited list of class names implementing the com.f1.ami.web.AmiWebGuiServicePlugin interface. (See Gui Service Plugin for details)
 +
* <span style="font-family: courier new; color: blue;">ami.web.permitted.cors.origins</span>: control which origins are accepted in AMI Remote Procedure Calling (see RPC)
 +
 
 +
== Layout and User Files ==
 +
 
 +
* <span style="font-family: courier new; color: blue;">users.access.file</span>: Location of the "access.txt" file, see User Parameters section below.
 +
* <span style="font-family: courier new; color: blue;">users.path</span>: Directory containing the .ami_settings user files and the user preference files. Default is ''data/users''.
 +
* <span style="font-family: courier new; color: blue;">ami.shared.layouts.dir</span>: base directory of where shared layouts are stored (those layouts available to end non-dev users). Default is ''data/shared''
 +
* <span style="font-family: courier new; color: blue;">ami.cloud.dir</span>: base directory of the AMI Cloud. Layouts and user settings saved to the cloud will be stored in this directory.
 +
* <span style="font-family: courier new; color: blue;">ami.users.file</span>: file name of the users configuration file. See "Access Configuration File for Web" section for details.
 +
* <span style="font-family: courier new; color: blue;">ami.web.default.layout.shared</span>: ['''Deprecated''', use '''''ami.web.default.layout=SHARED:<layoutname>'''''] Name of the layout's file name. If Specified, then any users that login will be automatically assigned to the specified layout, and developer/admin mode will not be available.  See ami.shared.layouts.dir for where shared layouts are located.
 +
* <span style="font-family: courier new; color: blue;">ami.font.files</span>: A list of true type font files (.ttf) to load make available for use in dashboards. May include wild cards, ex: ''my/fonts/*.ttf''
 +
* <span style="font-family: courier new; color: blue;">ami.fonts.in.browser</span>: A list of font family names that are assumed to be available in the browser, meaning the ttf definitions will not be transferred to the browser even if a corresponding ttf file is specified (see ami.font.files). The default is: ''Arial,Courier,Georgia,Impact,Lucida,Times New Roman,Verdana''
 +
* <span style="font-family: courier new; color: blue;">ami.webmanager.host</span>: Optional location for where to access webmanager, used for remotely loading files. If not specified, local file system is used.
 +
* <span style="font-family: courier new; color: blue;">ami.webmanager.port</span>: Optional location for where to access webmanager, used for remotely loading files.
 +
* <span style="font-family: courier new; color: blue;">ami.web.default.LAYOUTS</span>: A comma-delimited list of layout names that are accessible for the users that are non-dev and non-admin.
 +
 
 +
===Default layout===
 +
The default layout is the layout to load when a particular user logs in. There are some properties that give a fine control on how the default layout is determined. The property with lower number of priority will be considered first.<br>
 +
If '''''ami.web.default.DEFAULT_LAYOUT''''' (with priority 0) is present, then all other properties with bigger priority values will be ignored.<br>
 +
* <span style="font-family: courier new; color: blue;">ami.web.default.DEFAULT_LAYOUT</span>: PRIORITY 0
 +
* <span style="font-family: courier new; color: blue;">ami.web.default.layout</span>: PRIORITY 1
 +
* <span style="font-family: courier new; color: blue;">The user's '''''ami_layout_shared ''''' in access.txt</span>: PRIORITY 2
 +
* <span style="font-family: courier new; color: blue;">ami.web.default.layout.shared</span>: PRIORITY 3 (This is deprecated, suggested to use '''''ami.web.default.layout=SHARED:<layoutname>''''' instead )
 +
** note that using <span style="font-family: courier new; color: blue;">ami.web.default.layout.shared</span> in conjunction with <span style="font-family: courier new; color: blue;">ami.shared.layouts.dir=path/to/dir </span> will load a specific layout to every user who logs in, regardless if they are present in access.txt or if you are using an authentication plugin.
 +
The properties above will apply for all users in ''access.txt''. If you want a finer control of default layouts for each individual user, you could put the <span style="font-family: courier new; color: blue;"><property></span> from the <span style="font-family: courier new; color: blue;">ami.web.default.<property></span> at the end of each user clause in '''''access.txt''''', as an example:<br>
 +
If there are two users: user1 and user2. We want to assign <span style="font-family: courier new; color: blue;">user1_defaultLayout.ami</span> to user1 as the default layout, and <span style="font-family: courier new; color: blue;">user2_defaultLayout.ami</span> for user2, then in access.txt:<br>
 +
<code>user1|123456|ISADMIN=true|ISDEV=true|DEFAULT_LAYOUT=user1_defaultLayout.ami<br>
 +
user2|123456|ISADMIN=true|ISDEV=true|DEFAULT_LAYOUT=user2_defaultLayout.ami
 +
</code>
 +
 
 +
===Deprecated===
 +
* <span style="font-family: courier new; color: gray;">ami.web.default.layout;</span>
 +
* <span style="font-family: courier new; color: gray;">ami.web.default.layout.shared;</span>  use <span style="font-family: courier new; color: blue;">ami.web.default.layout=SHARED:<layoutname></span>
 +
* <span style="font-family: courier new; color: gray;">ami.web.default.to.admin;</span>
 +
 
 +
== End User Behavior ==
 +
=== User Settings===
 +
All default user-specific settings can be configured programmatically using <span style="font-family: courier new; color: blue;">ami.default.user.<User Setting Name></span> in local.properties, as an example:<br>
 +
* <span style="font-family: courier new; color: blue;">ami.default.user.[property]</span>: Set default user settings e.g. set users' default timezone to UTC with <span style="font-family: courier new; color: blue;">ami.default.user.timeZone=UTC</span> (note timeZone uses a capital Z)
 +
Other properties include:<br>
 +
{| class="wikitable"
 +
!Property Name(key)
 +
!Property Value(value)
 +
!Supported Value
 +
!Example Usage
 +
|-
 +
|ami.default.user.dateFormat
 +
|String, format of date, by default is M/dd/yyyy
 +
|[yyyy/MM/dd, MM/dd/yy,...]
 +
|ami.default.user.dateFormat=yyyy/MM/dd
 +
|-
 +
|ami.default.user.timeFormat
 +
|String, format of date, by default is H:mm
 +
|[hh:mm a, h:mm, HH:mm, h:mm a], (if time is 13:30, then H:mm->3:30, h:mm->1:30 PM, HH:mm->13:30, hh:mm a->01:30 PM)
 +
|ami.default.user.timeFormat=HH:mm
 +
|-
 +
|ami.default.user.numberSeparator
 +
|String, determines on how the number should be separted, by default is 1,234,567,890.123
 +
|[1,234,567,890; 1,234,567,890.123;  1'234'567'890; 1234567890,123; ...]
 +
|ami.default.user.numberSeparator=1,234,567,890
 +
|-
 +
|ami.default.user.numberDecimalPrecision
 +
|Integer, number from 0-10, by default is 2
 +
|Integer number from 0-10
 +
|ami.default.user.numberDecimalPrecision=4
 +
|-
 +
|ami.default.user.sciNotDigitsLeft
 +
|Integer, number from 1-20, by default is 1
 +
|Integer number from 1-20,
 +
|ami.default.user.sciNotDigitsLeft=4
 +
|-
 +
|ami.default.user.sciNotDigitsLeft
 +
|Integer, number from 1-20, by default is 3
 +
|Integer number from 1-20,
 +
|ami.default.user.sciNotDigitsRight=5
 +
|-
 +
|ami.default.user.numberNegativeFormat
 +
|String, format of Negative Number. by default is sign, can take either sign or parenthesis
 +
|[sign,parentheses]
 +
|ami.default.user.numberNegativeFormat=parentheses
 +
|-
 +
|ami.default.user.spreadSheetFormatOption
 +
|String, spread sheet formating, by default is always, can take either always or never
 +
|[always,never]
 +
|ami.default.user.spreadSheetFormatOption=never
 +
|-
 +
|ami.default.user.autoApplyUserPrefs
 +
|String, whether or not automatically apply use preferances, by default is ask, can take always,never or ask
 +
|[always,never,ask]
 +
|ami.default.user.autoApplyUserPrefs=always
 +
|}
 +
 
 +
* <span style="font-family: courier new; color: blue;">ami.show.menu.option.datastatistics</span>: When to show the data statistics menu option'': always, never, dev, admin.'' (dev - only in dev or admin mode, admin - only in admin mode) default is ''always''
 +
* <span style="font-family: courier new; color: blue;">ami.show.menu.option.fullscreen</span>: When to show the full screen menu option'': always, never, dev, admin.'' (dev - only in dev or admin mode, admin - only in admin mode) default is ''always''
 +
* <span style="font-family: courier new; color: blue;">ami.frames.per.second</span>: the rate that the web browser is updated with new data. This is used to tune the performance of AMI and the user experience. We do not recommend a refresh rate of higher than 20 frames per second.
 +
* <span style="font-family: courier new; color: blue;">ami.web.default.cmd.timeout.ms</span>: the number of milliseconds to wait for a response when sending a command to the backend.  Default is ''30000''
 +
* <span style="font-family: courier new; color: blue;">ami.request.timeout.seconds</span>: the amount of time before a user will be prompted that their request could not be serviced. Default is 60 seconds.
 +
* <span style="font-family: courier new; color: blue;">ami.show.menu.option.datastatistics</span>: Determines which types of users can view data statistics (under Menu Bar -> Help -> Data Statistics) . Valid options are ''always'', ''never'', ''dev'' or ''admin''.   Default is ''always''
 +
* <span style="font-family: courier new; color: blue;">ami.show.menu.option.fullscreen</span>: Determines which types of users can set the browser to full screen (under Menu Bar -> Windows -> Full Screen) . Valid options are ''always'', ''never'', ''dev'' or ''admin''.   Default is ''always''
 +
* <span style="font-family: courier new; color: blue;">ami.web.default.to.admin</span>: by default is ''true'', which means that if there are no admin users registered (See Menu Bar -> Account -> Manage Users) then all users are considered admins. Setting to false means that users will be strictly assigned the role they are associated with.
 +
* <span style="font-family: courier new; color: blue;">ami.web.default.ISADMIN</span>: by default is ''false'', which means that if ISADMIN is not supplied in access.txt, what is the default value
 +
* <span style="font-family: courier new; color: blue;">ami.web.default.ISDEV</span>: by default is ''false'', which means that if ISDEV is not supplied in access.txt, what is the default value
 +
* <span style="font-family: courier new; color: blue;">general.error.message</span>: The generic error message displayed to users when an exception is not caught.  Default is: "Frontend encountered unhandled condition"
 +
* <span style="font-family: courier new; color: blue;">general.error.emailTo</span>: The email address to send error reports to when a user clicks to report an error. Default is: "[[Mailto:support@3forge.com|support@3forge.com]]"
 +
* <span style="font-family: courier new; color: blue;">general.error.emailSubject</span>: The default subject used to populate the error report email (see general.error.emailTo). Default is "Support Issue"
 +
* <span style="font-family: courier new; color: blue;">general.error.emailBody</span>: The introductory sentence in the error report email (see general.error.emailTo). Default is "Please find details below:"
 +
* <span style="font-family: courier new; color: blue;">ami.web.filter.dialog.max.options</span>: Maximum number of options to show in the table filter dialog
 +
 
 +
== Performance ==
 +
 
 +
* <span style="font-family: courier new; color: blue;">ami.web.precached.tables</span>: A comma delimited list of tables (aka types) to automatically cache real-time inside the webserver. Any types that a layout references that are not explicitly listed in this property will require a snapshot request from the Ami Center.
 +
* <span style="font-family: courier new; color: blue;">ami.chart.threading.suggestedPointsPerThread</span>: Determines the number of threads to use for a chart, based on the number of points to render. Default is 100000
 +
* <span style="font-family: courier new; color: blue;">ami.chart.threading.maxThreadsPerLayer</span>: Provides a ceiling on total threads that can be used. Default is 10
 +
* <span style="font-family: courier new; color: blue;">ami.chart.threading.threadPoolSize</span>: The total number of threads (across all users) to allocate for chart image processing. Default is 100
 +
* <span style="font-family: courier new; color: blue;">ami.chart.threading.antialiasCutoff</span>: The number of points before anti-aliasing should be turned off, so that rendering is faster for high density charts. Default is 100000
 +
* <span style="font-family: courier new; color: blue;">ami.chart.compressionLevel</span>: The PNG compression level for  the images  that are transferred to the front end where 0=off, 10=Full compression. Default is 2
 +
* <span style="font-family: courier new; color: blue;">ami.frames.per.second</span>:The number of times that the AMI application's display is refreshed in a single second. Default is 15fps
 +
 
 +
== SAML ==
 +
 
 +
* <span style="font-family: courier new; color: blue;">saml.identity.provider.url</span>: the url of the identity provider
 +
* <span style="font-family: courier new; color: blue;">saml.service.provider.url</span>: the full url or the service provider (this ami instance's url as known by the identify provider)
 +
* <span style="font-family: courier new; color: blue;">saml.entityid</span>: The issuer id provided in the samle request
 +
* <span style="font-family: courier new; color: blue;">saml.relay.state</span>: Optional, adds the RelayState param to the request
 +
* <span style="font-family: courier new; color: blue;">saml.plugin.class</span>:  The class that implements the com.f1.ami.web.AmiWebSamlPlugin interface. For non-customized versions use com.f1.ami.plugins.amisaml.AmiWebSamlPluginImpl
 +
* <span style="font-family: courier new; color: blue;">saml.username.field</span>: The field of the response to extract username from
 +
* <span style="font-family: courier new; color: blue;">saml.identity.provider.cert.file</span>: The file containing the certificate
 +
* <span style="font-family: courier new; color: blue;">saml.identity.provider.clock.skew.ms</span>: Amount of time (in milliseconds) that Identity provider timestamp and service provider timestamp can drift
 +
* <span style="font-family: courier new; color: blue;">saml.identity.provider.lifetime.ms</span>: Expriry time of IDP request (in milliseconds)
 +
* <span style="font-family: courier new; color: blue;">saml.debug</span>: set to true to have ami debug verbose saml related information
 +
 
 +
== OKTA (Oauth) ==
 +
 
 +
* <span style="font-family: courier new; color: blue;">sso.plugin.class</span>: The class the implements the AmiWebSSOPlugin. Use ''com.f1.amioktaauth.AmiOktaOauthPlugin''
 +
* <span style="font-family: courier new; color: blue;"> oauth.client.id</span>: Client Id of the application registered to authenticate via OKTA.
 +
* <span style="font-family: courier new; color: blue;"> oauth.client.secret</span>: Client secret of the application registered to authenticate via OKTA.
 +
* <span style="font-family: courier new; color: blue;"> oauth.redirect.uri</span>: The uri OKTA will use to redirect the user once authentication is complete. In this case it will be the uri of amiweb (http://localhost:33332/oktaAuthFinished/). Note that this uri must match with the one configured in OKTA account.
 +
* <span style="font-family: courier new; color: blue;"> oauth.server.domain</span>: The domain of the okta account (''https://something.okta.com'')
 +
* <span style="font-family: courier new; color: blue;"> oauth.scope</span>: Space delimited scopes indicating the types of resources AMI will be requesting from the resource server. Use ''openid profile email''
 +
* <span style="font-family: courier new; color: blue;">web.logged.out.url</span>: url to redirect to when logged out, default is / which directs to login page. (Hint: set to /loggedout.htm for a logged out page instead, useful for OAUTH)
 +
* <span style="font-family: courier new; color: blue;"> oauth.authorization.endpoint</span>: Okta authorization endpoint. Default value /oauth2/default/v1/authorize
 +
* <span style="font-family: courier new; color: blue;"> oauth.token.endpoint</span>: Okta token endpoint. Default value /oauth2/default/v1/token
 +
* <span style="font-family: courier new; color: blue;"> oauth.code.challenge.method</span>: Okta code challenge method. Default value S256
 +
* <span style="font-family: courier new; color: blue;"> oauth.oauth.digest.algo</span>: Java hashing algorithm used to verify the code challenge. Default value SHA-256 
 +
* <span style="font-family: courier new; color: blue;"> oauth.username.field</span>:  The field from Okta identity response to use as the AMI username. Default value email
 +
* <span style="font-family: courier new; color: blue;"> oauth.ami.isadmin.field</span>: The field from Okta identity response use to identity an AMI admin user (Recommended).
 +
* <span style="font-family: courier new; color: blue;"> oauth.ami.isadmin.values</span>: Comma delimited list of AMI admins. If the value of the isadmin field matches any of the values, the user gets AMI admin privileges. Otherwise the user will be in user mode.
 +
* <span style="font-family: courier new; color: blue;"> oauth.ami.isdev.field</span>: The field from Okta identity response use to identity an AMI dev user (Recommended).
 +
* <span style="font-family: courier new; color: blue;"> oauth.ami.isdev.values</span>: Comma delimited list of AMI devs.  If the value of the isdev field matches any of the values, the user gets AMI dev privileges. 
 +
* <span style="font-family: courier new; color: blue;"> oauth.debug</span>: For detailed logging. Default value false
 +
* <span style="font-family: courier new; color: blue;"> oauth.session.check.period.seconds</span>: Controls polling frequency for a refresh token and also the frequency of the reaper thread to check on the SSO session. Defaults to 60 seconds.
 +
 
 +
== LDAP ==
 +
 
 +
The LDAP plugin is available upon request. Please reach out via support@3forge.com
 +
 
 +
* <span style="font-family: courier new; color: blue;">ami.auth.plugin.class</span>=com.f1.ami.amildap.AmiAuthenticatorLDAP
 +
* <span style="font-family: courier new; color: blue;">ldap.address</span>= address of ldap server. Ex: ldap.example.com
 +
* <span style="font-family: courier new; color: blue;">ldap.port</span>=ldap port, default is 389
 +
* <span style="font-family: courier new; color: blue;">ldap.bindDN</span>=admin bind DN. Ex: cn=admin,dc=example,dc=com
 +
* <span style="font-family: courier new; color: blue;">ldap.baseDN</span>=base DN. Ex: ou=group,dc=example,dc=com
 +
* <span style="font-family: courier new; color: blue;">ldap.bindPW</span>=admin password
 +
* <span style="font-family: courier new; color: blue;">ldap.attributes</span>=Optional. Comma delimited attributes to search for in ldap (i.e. cn,givenName,sn,mail)
 +
* <span style="font-family: courier new; color: blue;">ldap.userAttributeName</span>=attribute to identify user object (i.e. sAMAccountName)
 +
* <span style="font-family: courier new; color: blue;">ldap.maxConnections</span>=Optional. Maximum number of connections (defaults to 10)
 +
* <span style="font-family: courier new; color: blue;">ldap.initialConnections</span>=Optional. Initial number of connections (defaults to 5)
 +
* <span style="font-family: courier new; color: blue;">ldap.useSSL</span>=Optional. Specifies that ssl should be used for all connections (defaults to false)
 +
* <span style="font-family: courier new; color: blue;">ldap.useStartTLS</span>=Optional. Specifies that the StartTLS protocol should be used, requires useSSL to be true
 +
* <span style="font-family: courier new; color: blue;">ldap.sslTrustStorePath</span>=Optional. Path to the truststore cert (for ssl)
 +
* <span style="font-family: courier new; color: blue;">ldap.sslTrustStorePin</span>=Optional. Pin for the truststore cert (for ssl)
 +
* <span style="font-family: courier new; color: blue;">ldap.sslTrustStoreFormat</span>=Optional. Format of the truststore cert (valid inputs are: all,pem. Defaults to JVM defaults otherwise)
 +
* <span style="font-family: courier new; color: blue;">ldap.sslValidateHostname</span>=Optional. Boolean indicating if the hostname should be validated. (Defaults to true)
 +
 
 +
== Style ==
 +
* <span style="font-family: courier new; color: blue;">web.loadingbar.styles</span>: this property takes in a list of key-value pairs. The keys are: '''dialogBgColor''', '''headerBgColor''', '''stripeColor1''', '''stripeColor2''', '''stripeColor3'''.
 +
Example usage: web.loadingbar.styles=dialogBgColor=#234567,headerBgColor=#123456,stripeColor1=#ff0000,stripeColor2=#ff00ff,stripeColor3=#f0f0f0
 +
 
 +
[[File:Loading bar properties.png]]
 +
 
 +
= WebBalancer Configuration Properties (Applies to Components: WebBalancer) =
 +
Note: To run the ami webbalancer, include ''webbalancer'' in the list of components found in the the ami.components property, ex: <span style="font-family: courier new; color: blue;">ami.components=webbalancer</span>
 +
==WebBalancer Routing Rules==
 +
*<span style="font-family: courier new; color: blue;">ami.webbalancer.routes.file</span>: File containing a list of routing rules for determining how incoming client ip addresses are routed to ami web server addresses. Routing Rules are one entry per line with descending priority. Each line is in the form client_ip_mask;target1,target2,target3;BREAK[or CONTINUE]
 +
*<span style="font-family: courier new; color: blue;">ami.webbalancer.sessions.file</span>: A file for persisting active session rounting, in case of web balancer restart.
 +
 
 +
==WebBalancer Check Frequencies==
 +
*<span style="font-family: courier new; color: blue;">ami.webbalancer.check.sessions.period</span>: How often to check for changes to routes file and stale sessions. Default: 5 SECONDS
 +
*<span style="font-family: courier new; color: blue;">ami.webbalancer.server.alive.check.period</span>: How often to test servers marked as DOWN, to see if they are alive. Default: 5 SECONDS
 +
*<span style="font-family: courier new; color: blue;">ami.webbalancer.server.test.url.period</span>: How often to ping servers marked as UP to ensure they are healthy. Default: 30 SECONDS
 +
*<span style="font-family: courier new; color: blue;">ami.webbalancer.server.test.url</span>: The URL to request from web server for HTTP OK status. Default is /portal/rsc/ami/normal.png
 +
*<span style="font-family: courier new; color: blue;">ami.webbalancer.session.timeout.period</span>: After what period of time is a session with zero connections considered stale. Default: 1 MINUTE
 +
 
 +
==WebBalancer Client HTTP Connectivity==
 +
*<span style="font-family: courier new; color: blue;">ami.webbalancer.http.port</span>: Optional, the http port to listen for insecure connections on. if not specified, http is not available. Default is 33330
 +
*<span style="font-family: courier new; color: blue;">ami.webbalancer.http.port.bindaddr</span>: Optional, Specifies the network interface that the ami.webbalancer.http.port port be bound to
 +
*<span style="font-family: courier new; color: blue;">ami.webbalancer.http.port.whitelist</span>: Optional. Controls access to the http port, 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
 +
*<span style="font-family: courier new; color: blue;">ami.webbalancer.https.port</span>: Optional, the https port to listen for secure connections. If not specified, https is not available.
 +
*<span style="font-family: courier new; color: blue;">ami.webbalancer.https.port.bindaddr</span>: Optional, Specifies the network interface that the ami.webbalancer.https.port port be bound to
 +
*<span style="font-family: courier new; color: blue;">ami.webbalancer.https.port.whitelist</span>: Optional. Controls access to the https port, 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
 +
*<span style="font-family: courier new; color: blue;">ami.webbalancer.https.keystore.file</span>: The path to the key store file, generated using java's keytool.
 +
*<span style="font-family: courier new; color: blue;">ami.webbalancer.https.keystore.password</span>: The password associated with the key store file.
 +
 
 +
==WebBalancer.routes==
 +
 
 +
'''Overview'''
 +
 
 +
This file (specified by ami.webbalancer.routes.file) should contain a list of rules, one rule per line.
 +
 
 +
'''Rule Format'''
 +
 
 +
CLIENT_MASK;SERVERS_LIST;ON_FAILURE    #comments
 +
 
 +
{| class="wikitable"
 +
|-
 +
! Parameter !!  Description
 +
|-
 +
| CLIENT_MASK || A pattern matching expression for client ip addresses, (*=wild)
 +
|-
 +
| SERVERS_LIST || a comma delimited list of [weighting*]protocol://host:port entries.  (Only http,https protocols supported, default is http)
 +
|-
 +
| ON_FAILURE ||  If all servers in SERVERS_LIST are down, either CONTINUE trying other rules or BREAK and return error to user. Default is BREAK
 +
|}
 +
 
 +
Each new client connection is passed through the webbalancer rules engine to determine which list of webservers are candidates for forwarding starting at the highest priority (first) rule.
 +
 
 +
If the client's ip address (as seen by the webbalancer) matches the CLIENT_MASK portion then a web server from the SERVERS_LIST option is chosen for forwarding, see selection strategy for details. The selected forwarding is "sticky for all subsequent connections from the same client ip address for the life of the session (see ami.webbalancer.session.timeout.period for determining when a session can expire).
 +
 
 +
'''Selection Strategy'''
 +
The servers from the SERVERS_LIST with an UP status (see ami.webbalancer.server.test.url property determining UP/DOWN status of a server) and the least number of active client sessions is chosen, based on the servers weighting. Ties broken via round-robin. All entries have a default weighting of one (1) but can be overridden by prefixing with a weighting and star (*). Servers with higher weightings will be assigned more users. For example, <span style="font-family: courier new; ">https://server1:33332,2*https://server2:33332,.5*server3:33332</span>. In this scenario, server 2 would get twice the number of users as server1.  Server 3 would get half the number of users as server 1.
 +
 
 +
Note: If a client address can not be matched to a rule the user will receive an error message.
 +
 
 +
'''Examples'''
 +
 
 +
<span style="font-family: courier new; ">192.168.1.1|192.168.1.2|192.168.1.3;https://server1:33332,https://server2:33332;    #send those 3 clients to either server1 or server2</span>
 +
 
 +
<span style="font-family: courier new; ">192.168.1.*;https://server3:33332;  #send all clients in the 192.168.1 address range to server3</span>
 +
 
 +
<span style="font-family: courier new; ">192.168.2.*;1*https://server6:33332;4*https://server7:33332;  #send all clients in the 192.168.2 address range to server6 or server7. 1/5th of users to server6 and 4/5ths to server7 </span>
 +
 
 +
<span style="font-family: courier new; "><nowiki>*</nowiki>;http://server4:33332,http://server5:33332;  #all others get sent to server4 or server5</span>
 +
 
 +
Default:
 +
 
 +
<span style="font-family: courier new; "><nowiki>*</nowiki>;http://localhost:33332;BREAK</span>
 +
 
 +
=WebManager Configuration Properties=
 +
 
 +
Note: To run the ami webmanager, include ''webmanager'' in the list of components found in the the ami.components property, ex: <span style="font-family: courier new; color: blue;">ami.components=webmanager</span>
 +
 
 +
*<span style="font-family: courier new; color: blue;">ami.webmanager.port</span>: The server port that the webmanager listens on for connections from ami web servers
 +
*<span style="font-family: courier new; color: blue;">ami.webmanager.port.bindaddr</span>: The server port to bind to
 +
*<span style="font-family: courier new; color: blue;">ami.webmanager.port.whitelist</span>: The whitelist used to control connections accepted on the port
 +
*<span style="font-family: courier new; color: blue;">ami.webmanager.mapping.pwd</span>: The working directory for file requests, default is java's path of working directory, typically under 3forge/amione.
 +
*<span style="font-family: courier new; color: blue;">ami.webmanager.mapping.roots</span>: A key=value comma delimited list of roots that web server file requests are mapped to. The key is a "logical name" and the value is the "actual location". Ex: /public=/opt/files,/=/ takes all file requests under /public and maps them to /opt/files, otherwise all files starting with / are mapped to /
 +
*<span style="font-family: courier new; color: blue;">ami.webmanager.mapping.strict</span>: If true, file requests requesting a parent directory (via ..) will be rejected.  Also, requests denoting home directory (~) will be directory. Default is true.  IMPORTANT SECURITY NOTE: Setting to false will allow remote access to all host files accesible by user process.
 +
 
 +
= Default Authentication Access File (Applies to Components: Web) =
 +
When an authentication plugin is not supplied a configurable "access" file is referenced by default. Note, this should only be used for testing and other non-production purposes due the lack of security, etc. This is where usernames, passwords, default layouts, and user parameters are defined. The access configuration files lives in the directory of the Web application and is named ''data/access.txt'' by default.  Each line should contain a single user's entry which is pipe (|) delimited. The first entry is the username, 2nd is the password, additional parameters are key=value.
 +
 
 +
'''Username:''' First Param, the username defined is what a user needs to login as.
 +
 
 +
'''Password:''' Second Param, this is the only place that passwords can be set for users.
 +
 
 +
'''key=value''': Additional parameters.  The following keys are supported:
 +
  '''ISDEV='''true/false - Determines if the user should have developer rights, aka should they have the green toggle button in the upper right corner
 +
  '''ISADMIN='''true/false - If ISDEV is set to false, then this has no effect. If ISDEV is set to true and ISADMIN is set to true, then dev user can shutdown AMI from the GUI via File -> Shutdown.
 +
  '''amiscript.variable.''varname'''''=value  - Defines a variable in the user session, with the type inferred. For example amiscript.variable.blah=123 creates a variable named blah of type int with the value 123.  Alternatively, amiscript.variable.blah="123" would create the variable as a string instead.
 +
  '''amivar.''varname''='''value  - Deprecated - defines a variable of type string in the user session prefixed with user<dot> For example amivar.blah=123 creates a variable inside user user's session named user.blah with the string value "123"
 +
  '''developer_ami_editor_keyboard'''=vi/default - For developer mode, should the editor use plain text or vi mode
 +
  '''ami_layout_shared'''=default layout to load (under the directory configured using the ami.shared.layouts.dir property)
 +
  '''ami_layout_current'''=Current layout
 +
  '''LAYOUTS'''=A comma delimited list of regular expressions for layouts that are available to this user. This is only applicable to CLOUD layouts.
 +
 
 +
 
 +
'''User Parameters:''' parameters can be assigned to a user. These parameters can then be used to modify the user's access to data and inputs.  
 +
 
 +
'''Example Configuration File'''
 +
 
 +
<span style="font-family: courier new; ">jdoe|jdoe123|ami_layout_shared=ACME.ami|amivar_group=ops</span>
 +
 
 +
<span style="font-family: courier new; ">csmith|password1234</span>
 +
 
 +
<span style="font-family: courier new; ">exampleusername|pass24|amivar_region=asia</span>
 +
 
 +
<span style="font-family: courier new; ">exampleusername|pass24|LAYOUTS=overview.ami, report.ami, *rfp.ami</span>
 +
 
 +
=Instructions: Encrypting values inside .properties files=
 +
 
 +
For this example, let's say you have the following property in your local.properties and you want to encode the password
 +
 
 +
''myurl=http://blah?pass=password123456&user=steve''
 +
 
 +
'''Step 1''': Under the scripts directory, use the tools.sh to create a 128-bit strength key (feel free to adjust the strength).
 +
 
 +
<span style="font-family: courier new; ">./tools.sh --aes_generate /opt/ami/secret.aes 128</span>
 +
 
 +
'''Step 2''': Add this option to your start.sh so that AMI knows where the secret key for decoding encrypted properties is located
 +
 
 +
<span style="font-family: courier new; ">-Dproperty.f1.properties.secret.key.files=/opt/ami/secret.aes</span>
 +
 
 +
'''Step 3''': Using the same tools.sh, Encode the password and copy the output text into your clipboard
 +
 
 +
<span style="font-family: courier new; ">./tools.sh -aes_encrypt /opt/ami/secret.aes password123456</span>
 +
 
 +
<span style="font-family: courier new; ">_fYjHz8Dr4o7XjZcOd1BhtKzV9U5MpZMpTyGlu-mpheL4qV-ZX-yUads </span>
 +
 
 +
'''Step 4''': Change your local.properties file to use the encrypted value instead, by enclosing with $''{CIPHER:  ...  }''
 +
 
 +
myurl=http://blah?pass=${CIPHER:_fYjHz8Dr4o7XjZcOd1BhtKzV9U5MpZMpTyGlu-mpheL4qV-ZX-yUads}&user=steve
 +
 
 +
'''Step 5''': Restart AMI
 +
 
 +
In the AmiOne.log you'll see that the value for the ''myurl'' property is substituted with  ***** for security purposes.
 +
 
 +
'''Two Notes'''
 +
 
 +
'''For additional passwords''': Skip steps 1 and 2
 +
 
 +
'''Tip''': you can also decrypt using tool.sh by running:
 +
 
 +
<span style="font-family: courier new; ">./tools.sh -aes_decrypt /opt/ami/secret.aes _fYjHz8Dr4o7XjZcOd1BhtKzV9U5MpZMpTyGlu-mpheL4qV-ZX-yUads
 +
password123456</span>
 +
 
 +
= Default File Structure - AMI =
 +
 
 +
Below is the standard file structure for a new install of ami after it has been run once.
 +
 
 +
<pre>
 +
ami
 +
├───README_AMIONE.txt
 +
├───uninstall.exe
 +
 +
├───.install4j
 +
│  └───...
 +
 +
├───jre  - - - - - - - - - - - - - - - - - - Location of the Java JRE used by AMI
 +
│  └───...
 +
 +
└───amione
 +
    ├───.amionemain.prc  - - - - - - - - - - Used by stop.sh to shutdown AMI
 +
    ├───.console_history.txt
 +
    ├───.f1proc.txt
 +
    ├───AMI_One.exe
 +
    ├───AMI_One.vmoptions  - - - - - - - - - Virtual machine options
 +
    ├───error.log  - - - - - - - - - - - - - Major error log
 +
    ├───output.log - - - - - - - - - - - - - Startup log
 +
    │
 +
    ├───config - - - - - - - - - - - - - - - Directory for storing properties, we recommend adding a local.properties file here, see the "AMI Configuration Guide" for more details
 +
    │  ├───root.properties  - - - - - - - - References load order of other properties files
 +
    │  ├───defaults.properties  - - - - - - Default properties
 +
    │  ├───build.properties - - - - - - - - Build version properties
 +
    │  └───speedlogger.properties - - - - - Logging properties
 +
    │
 +
    ├───data - - - - - - - - - - - - - - - - Stores developer/admin created files, such as routing tables.
 +
    │  ├───access.txt - - - - - - - - - - - Access file (will be overwritten if new installation is on top of old)
 +
    │  ├───managed_schema.amisql  - - - - - Schema file for AMIDB
 +
    │  ├───relay.routes - - - - - - - - - - List of relay route names
 +
    │  │
 +
    │  ├───autosave - - - - - - - - - - - - Directory for autosaves by user
 +
    │  │  ├───demo.cnt - - - - - - - - - - Current autosave number
 +
    │  │  ├───demo.cur - - - - - - - - - - Recent autosaves
 +
    │  │  ├───demo.old - - - - - - - - - - Older autosaves
 +
    │  │  └───...
 +
    │  │
 +
    │  ├───cloud  - - - - - - - - - - - - - Directory for layouts saved in the cloud
 +
    │  │  ├───my_layout.ami
 +
    │  │  └───...
 +
    │  │
 +
    │  ├───fonts  - - - - - - - - - - - - - Directory for fonts
 +
    │  │  ├───Arial.ttf
 +
    │  │  └───...
 +
    │  │
 +
    │  ├───idfountain - - - - - - - - - - - Directory for managing autoincrementing ids
 +
    │  │  └───...
 +
    │  │
 +
    │  ├───styles - - - - - - - - - - - - - Directory for readonly styles
 +
    │  │  ├───HALLOWEEN.amistyle.json
 +
    │  │  └───...
 +
    │  │
 +
    │  └───users  - - - - - - - - - - - - - Directory for user preferences
 +
    │          demo.ami_settings
 +
    │
 +
    ├───history
 +
    │  └───ami_console.history  - - - - - - AMI command line history
 +
    │
 +
    ├───lib  - - - - - - - - - - - - - - - - Directory for java libraries, including libraries for AMI web
 +
    │  └───...
 +
    │
 +
    ├───log  - - - - - - - - - - - - - - - - Files with numbered extensions e.g. 0001 are logs from past runs of ami; files without numbered extensions are the most recent logs
 +
    │  ├───AmiMessages.log  - - - - - - - - Log of all messages received by AMI
 +
    │  ├───AmiMessages.log.0001
 +
    │  ├───AmiOne.amilog  - - - - - - - - - Log of internal messages within AMI
 +
    │  ├───AmiOne.amilog.0001
 +
    │  ├───AmiOne.log - - - - - - - - - - - AMI console log
 +
    │  └───AmiOne.log.0001
 +
    │
 +
    ├───persist  - - - - - - - - - - - - - - Directory for AMI Generated files used for recovery (on restart).
 +
    │  ├───amikey.aes - - - - - - - - - - - Encryption key for user passwords, see "Encrypting passwords in access.txt" for more details
 +
    │  ├───__CENTER.dat - - - - - - - - - - Info on multiple centers
 +
    │  ├───__DATASOURCE.dat - - - - - - - - Info on datasources
 +
    │  └───__REPLICATION.dat  - - - - - - - Info on replication centers
 +
    │
 +
    ├───resources  - - - - - - - - - - - - - Directory for storing resources (ex images) to be used by the webserver
 +
    │
 +
    └───scripts  - - - - - - - - - - - - - - UNIX/DOS scripts for starting/stopping AMI
 +
        ├───start.sh
 +
        ├───stop.sh
 +
        ├───restart.sh
 +
        ├───tools.sh
 +
        ├───start.bat
 +
        ├───stop.bat
 +
        ├───restart.bat
 +
        └───tools.bat
 +
</pre>
 +
 
 +
= AMI Download File Naming Convention =
 +
 
 +
Windows: ami_windows-x64_[version]_[branch].exe
 +
 
 +
Mac: ami_macos_[version]_[branch].dmg
 +
 
 +
Unix: ami_unix_[version]_[branch].sh
 +
 
 +
Other (Tar gz): ami_unix_[version]_[branch].tar.gz

Latest revision as of 15:27, 14 March 2024

GETTING STARTED

Overview

Browse to the 3forge > amione > config directory and create a new, empty local.properties file and place each property to override on its own line in the format property.name=value

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

You might ask, why doesn't AMI just come with a default local.propertiers? This is so that when you download and update to a new version of AMI this file will not be overwritten, hence maintaining your existing settings.

Sample local.properties

#My local.properties located under config directory

#Note, lines starting with pounds are comments (except for #INCLUDE)

#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

#Process and include properties from a custom properties file

#INCLUDE home/env_specific.properties

#Define my own custom value

my.custom.value=5

#Reference my custom value

ami.frames.per.second=${my.custom.value}

#Append to an existing variable

ami.datasource.plugins=$${ami.datasource.plugins},com.my.Plugin

#Remove a specific property in any of AMI's prepackaged configuration (root.properties, speedlogger.properties, defaults.properties).

#UNDEFINE speedlogger.sink.FILE_SINK.maxFiles=10

Common Properties (Applies to Components: Center, Relay, Web, WebBalancer)

  • f1.terminate.file: A small file will be created and monitored by AMI. If an external process moves / copies to a file of the same name, but with a ".kill" suffix the process will exit (this provides any easy way for an external script or job control process to cleanly shutdown AMI).
  • f1.threadpool.default.size: The number of threads in the core thread pool (this does not include threads for http servicing or image processing).
  • 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: set timezone for Java (note, this does not control default user or logger timezones)
  • f1.locale: default locale.
  • f1.logs.dir: the root directory for where log files will be deposited.
  • f1.plugins.dir: directory of where plugins will be loaded from.
  • f1.resources.dir: directory of where additional resources will be placed.
  • ami.components: a comma delimited list of which components to load, which can include an of: relay,center,web,webbalancer,webmanager. The default is the three components: relay,center,web.
  • ami.amilog.stats.period: How often AMI should log general health statistics such as memory, user load, etc. which can be used for real-time/historical monitoring via the performance dashboard. Default: 15 SECONDS.
  • ami.naming.service.resolvers: Specify a comma delimited list of naming service plugin classes (implements com.f1.ami.amicommon.AmiNamingServiceResolver). These can be used to map logic service names to physical host/ports.
  • ami.content.security.policy: The default content security policy is:img-src 'self' https://*.mapbox.com data: w3.org/svg/2000; default-src https://*.mapbox.com 'self' 'unsafe-inline' 'unsafe-eval' blob:.For more information regarding Content Security Policy, please refer to the following link: Content Security Policy (CSP)
  • ami.aes.key.file: The aes key file used for encrypting / decrypting secure data (see strEncrypt/strDecrypt in amiscript for examples)
  • ami.aes.key.text: The aes key used for encrypting / decrypting secure columns (instead of using ami.aes.key.file)
  • ami.aes.key.strength: Key strength, ex: 128

Java VM Properties (These should be included in the start.sh or AMI_One.vmoptions file)

The Java VM Properties can be configured in AMI_One.vmoptions (for windows) or AMI_One_linux.vmoptions(for linux), which are parsed in start.sh. Some of these properties control how messages are logged and how garbage collection is handled. Here are some concrete examples of Java VM Properties

  • -Df1.global.procinfosink.file=./.f1proc.txt:Controls where AMI will write proc information. Note, this proc information includes uptime/downtime/process id/and processuid
  • -Df1.license.file=${HOME}/f1license.txt,f1license.txt,config/f1license.txt:Comma delimited list of where the f1license.txt file(s) should be looked for
  • -Df1.license.property.file=config/local.propertiesThe file that contains a line in the format f1.license.file=xxxxx which points to the license file
  • -Dproperty.f1.conf.dir=config/:Directory where the root.properties is located.
  • -Djava.util.logging.manager=com.f1.speedlogger.sun.SunSpeedLoggerLogManager:Forces java to use the 3Forge logger
  • -Dlog4j.configuratorClass=com.f1.speedloggerLog4j.Log4jSpeedLoggerManager:Forces other 3rd party plugins that were written for log4j to use 3Forge logger instead
  • -Dlog4j.configuration=com/f1/speedloggerLog4j/Log4jSpeedLoggerManager.class:Forces other 3rd party plugins that were written for log4j to use 3Forge logger instead
  • -Dproperty.f1.properties.secret.key.files=/path/to/keyfile:If specified, the ${CIPHER:xxxxxx} syntax within .properties files will be decoded using the file's key. (See tools.sh for creating a key). comma delimit for multiple files
  • -Dproperty.f1.properties.decrypters=[DECRYPTERID]=com.package.DecrypterClass:If specified, the ${CIPHER:[DECRYPTERID]:xxxxxx} syntax within .properties files will be decoded using class. (See com.f1.utils.encrypt.Decrypter Interface) Comma delimit for multiple classes


Variables declared in the following way can be referenced in your local.properties file with ${}:

  • -Dproperty.your.variable.name=value

Relay Configuration Properties (Applies to Components: Relay)

Note: To run the ami relay, include relay in the list of components found in the the ami.components property, ex: ami.components=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. When set to -1, the socket is not started and refuses any connections to the relay.
  • ami.port.bindaddr: Optional. Specifies the network interface that the ami.port server port be bound to
  • ami.port.keystore.file: The path to the key store file, generated using java's keytool.
  • ami.port.keystore.password: The password associated with the key store file.
  • ami.port.wait.for.center: The duration to wait for center to start up
  • 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.datasource.plugins: A comma delimited list of java classes that implement the com.f1.ami.amicommon.AmiDatasourcePlugin interface. See plugin documentation for details
  • ami.center.port: Sets the port of the primary instance of ami center
  • ami.center.host: Sets the hostname of the primary instance of ami center
  • 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.center.[name].keystore.file: Supply if center is using ssl connection. The path to the key store file, generated using java's keytool. (Name is the center name as it appears in ami.centers property)
  • ami.center.[name].keystore.contents.base64: Supply if center is using ssl connection. The contents of the keystore as a base64 (instead of supplying the file name) (Name is the center name as it appears in ami.centers property)
  • ami.center.[name].keystore.password: Supply if center is using ssl connection. The password associated with the key store file (Name is the center name as it appears in ami.centers property)
  • 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.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.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.
  • 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

Relay.routes File

The relay can be connected to any number of centers (see ami.centers property). By default, as messages are 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.

To support dynamic routing, changes to this file during runtime 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 (Applies to Components: Center)

Note: To run the ami center, include center in the list of components found in the the ami.components property, ex: ami.components=center

Center General Properties

  • 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:<newline_delimited_list_of_hostname_patterns> or plugin:<class_name_implementing_com.f1.ami.amicommon.AmiServerSocketEntitlementsPlugin>
  • ami.center.ssl.port: Optionally, sets the secure port that 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
  • 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.db.auth.plugin.class: Class name of custom authenticator which must implement com.f1.ami.web.auth.AmiAuthenticator interface and be deposited in the plugin directory. The plugin will be responsible for user authentication and configuration. See Ami Authenticator Plugin Manual for details.
  • 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 appended to the AmiOne.amilog file in milliseconds (default is 15 seconds)
  • 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 (Applies to Components: 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
  • ami.db.console.prompt: takes in a string to customize AMI DB console prompt. E.g. -PROD -> AMIDB-PROD>

Realtime Database Configuration Properties (Applies to Components: Center)

  • ami.datasource.timeout.millis: Default amount of time, in milliseconds, AMI will wait for a datasource to respond to a query before timing out. Default is 60000 (one minute)
  • ami.datasource.concurrent.queries.per.user: The max number of queries to a specific datasource from a specific user that can be invoked simultaneously.  Default is 5
  • ami.db.schema.config.files: A comma delimited list of sql files to execute on startup
  • ami.db.schema.managed.file: The file that contains the schema to execute on startup, as defined via the command line.  For example, if a user creates a new public table, this file will be updated to include the modified schema so that next time AMI is restarted the table still exists.
  • ami.db.table.default.refresh.period.millis: The max delay for refreshing changes to the front end.  (See RefreshPeriodMs column in the __TABLE table)
  • ami.db.max.stack.size: The max stack size for nesting triggers / procedure calls. Default is 4
  • ami.db.persist.dir: For tables with persistence, the directory that the data is stored in.  (See PersistEngine in the USE options of the CREATE PUBLIC TABLE clause)
  • ami.db.persist.dir.system.tables: The directory where the contents of system tables (ex: __TABLE, __COLUMN, ...)  are stored by default.
  • ami.db.persist.dir.system.table.[__system_table_name]: The Directory where the contents of a specific system table is stored. Ex: ami.db.persist.dir.system.table.__DATASOURCE=/var/mydatasources
  • ami.db.timer.logging.enabled: Default is true, which says that each time a timer is fired a log line will be written to the log file.  In instances where timers are firing frequently, it is optimal to set this to false
  • ami.db.console.port: The port for connecting via telnet command line interface. Default is 3290
  • ami.db.console.port.bindaddr: Optional. Specifies the network interface that the ami.db.console.port.bindaddr server port will be bound to
  • ami.db.console.port.whitelist: provide either a list, file 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.db.console.history.dir: The directory that stores command line history
  • ami.db.console.history.max.lines: Max number of lines to store, default is 10000
  • ami.db.jdbc.port: The port for connecting to AMI via the AMI JDBC driver. Default is 3280
  • ami.db.jdbc.port.bindaddr: Optional. Specifies the network interface that the ami.db.jdbc.port server port will be bound to
  • ami.db.jdbc.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.jdbc.auth.plugin.class: By default pointing to ${ami.db.auth.plugin.class}, which sets target database's JDBC endpoints
  • ami.db.anonymous.datasources.enabled: should users be able to access undefined-datasources dynamically (via the USE DS_ADAPTER directive)
  • ami.db.disable.functions: Comma delimited list of functions to disable, by default strDecrypt is disabled
  • ami.db.default.permissions: When a user logs into the database and does not have an AMIDB_PERMISSIONS option associated with there account, what are the default permissions. Should be a comma delimited combination of READ, WRITE, ALTER, and EXECUTE. Blank means no permissions, default is all permissions( READ,WRITE,ALTER,EXECUTE)
  • amiscript.db.variable.varname: Declare a readonly variable available in the AMI Center database.  The value should be wrapped in quotes for a string, or properly formatted to indicate the type. Note, you can see declared variables via SHOW VARS. Examples:
    • amiscript.db.variable.hello="world"  //declare a string named hello
    • amiscript.db.variable.num=123L  //declare a long named num.
  • ami.db.onstartup.ondisk.defrag : If true, then on startup the ONDISK columns for persisted tables will be defragmented meaning empty blocks, do to deletes/updates will be removed. If false, then defrag is skipped but empty blocks will attempt to be reused. true is default

Email Configuration Properties

To send emails from you account via AMI, you will need to add the some of these properties to local.properties file:

  • email.client.host: The SMTP server to connect to. To connect to the Gmail SMTP server use host as smtp.gmail.com
  • email.client.port: The SMTP server port to connect to. To connect to the Gmail SMTP server use port as 465.
  • email.client.username: Username for the email account.
  • email.client.password: Password for the email account.
  • email.client.authentication.enabled: If true, attempts to authenticate the user. Defaults to true.
  • email.client.ssl.enabled: If true, use SSL to connect and use the SSL port by default. Defaults to false for the SMTP protocol.
  • email.client.start.tls.enabled: If true, enables the use of the STARTTLS command (if supported by the server) to switch the connection to a TLS-protected connection before issuing any login commands. If the server does not support STARTTLS, the connection continues without the use of TLS. Defaults to true.
  • email.client.retries.count: Number of times it tries to reconnect to the SMTP server. If 0, it will not retry if connection fails. And, for example, if set to 2 it will retry 2 times (so 3 trys in total).
  • email.client.debug.enabled: If true, AMI can debug email related information

Web Configuration Properties (Applies to Components: Web)

Note: To run the ami web, include web in the list of components found in the the ami.components property, ex: ami.components=web

License

  • ami.license.file: location of where to place/edit license file when using license wizard (under Help -> Enter/Update License). Default is ./f1license.txt
  • ami.web.disable.license.wizard: Hide the Help -> Enter/Update License menu item, even when not in developer mode  
  • ami.web.license.auth.url: the url for connecting to 3forge's server and generating license files (accessed from Help ->Enter/Update License -> Generate License Key). If blank, then the Generaet License Key button is not available and licenses must be manually generated via the website portal.
  • f1.license.warning.days: The number of days prior to a valid license expiring that a warning message will start appearing on the login page. Default is 14 days.

HTTP Connection & Session Options

  • http.port: sets the port that web browsers use to connect to AMI Web. The default port is 31313.
  • https.port: sets the port that web browsers use to connect securely to AMI Web. The default port is 3333 https.keystore.file: the path to the key store file generated using java's keytool that will be used for secure web connections.
  • https.keystore.password: the password associated with the key store file specified in the https.keystore.file property.
  • ami.web.http.connections.max: the maximum number of concurrent http connections (for preventing DOS attacks). Default is 100
  • ami.web.http.connections.timeout.ms: the number of milliseconds before an idle http connection is closed. Default is 30000
  • ami.session.check.period.seconds: the number of seconds between which AMI checks and removes expired sessions (users that have closed their AMI tab/browser, or are disconnected w/o a valid logout).  Default is 60 seconds.
  • ami.session.timeout.seconds: the number of seconds that must pass before a session is considered expired, causing the user to automatically be logged out. Default is 300 seconds.
  • ami.allow.site.framed: allow the ami webpage to be framed inside an iframe. If false, then x-Frame-Options and SameSite options are included in header. Default is true
  • http.port.bindaddr: Optional. Specifies the network interface that the http.port server port will be bound to
  • https.port.bindaddr: Optional. Specifies the network interface that the https.port server port will be bound to
  • ami.session.cookiename: name of the cookie to store in the web browser for the sessionid. Default is F1SESSION. If multiple AMI instances are sharing a host then each must have a unique cookiename
  • http.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:<New_line_delimited_list_of_hostname_patterns> or plugin:<class_name_implementing_com.f1.ami.amicommon.AmiServerSocketEntitlementsPlugin>
  • https.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>
  • amiscript.variable.varname: Declare a readonly variable available throughout the dashboard's amiscript.  The value should be wrapped in quotes for a string, or properly formatted to indicate the type. Note, you can see declared variables via Menu -> Dashboard -> Session Variables. Examples:
    • amiscript.variable.hello="world"  //declare a string named hello
    • amiscript.variable.num=123L  //declare a long named num.
  • users.access.file.encrypt.mode: off indicates the access.txt file is plain text.  password indicates that the password portion must be encrypted.  See strEncrypt(...) function for encrypting passwords. Default if off. Can be set to password to turn encryption on.
  • ami.centers: a comma delimted list of centers' host:port to connect to.  You can optionally prefix a 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 dashboard. If an alias is not provided, then the alias is the host:port.  Note, the first supplied URL is considered the primary center.Ex: ami.centers=myprimary=localhost:3270,other=some.host.com:3270
  • ami.center.[name].keystore.file: Supply if center is using ssl connection. The path to the key store file, generated using java's keytool. (Name is the center name as it appears in ami.centers property)
  • ami.center.[name].keystore.contents.base64: Supply if center is using ssl connection. The contents of the keystore as a base64 (instead of supplying the file name) (Name is the center name as it appears in ami.centers property)
  • ami.center.[name].keystore.password: Supply if center is using ssl connection. The password associated with the key store file (Name is the center name as it appears in ami.centers property)
  • ami.web.http.slow.response.warn.ms: Log a warning if a full round trip http request/response is greater than the specified duration in milliseconds. Default is 5000
  • ami.web.show.wait.icon.after.duration: the duration before displaying the loading / waiting icon. Default is 2000 milliseconds
  • ami.slow.amiscript.warn.ms: Log a warning if an amiscript block can not be executed the specified duration in milliseconds. Default is 1000
  • ami.web.portal.dialog.header.title: title on the portal dialog header (i.e. loading and error dialogs).

Login Options

  • ami.login.page.animated: Boolean indicating if login page should display animated background. True by default, recommended to set to false if used on remote desktops.
  • ami.login.page.title: the suffix to include in the login page web's title (appended to 3forge - )
  • ami.login.page.terms.and.conditions.file: Optional file to include in the login page, requiring user to acknowledge the terms and conditions before logging in.
  • contact.email: The email address for contacting support on a login issue, or to create a new account. Default is "support@3forge.com?subject=Ami Account Request"
  • ami.login.page.logo.file: Path to file containing image for login in login screen. Image will be scaled to a pixel width and height of 350x200. It's suggested that the image should be exactly that size to avoid scaling artifacts.
  • web.title: Change the title in the web browser tab
  • web.logged.out.url: url to redirect to when logged out, default is / which directs to login page. (Hint: set to /loggedout.htm for a logged out page instead, useful for OAUTH)
  • web.favicon: The icon to put in the tab
  • f1.license.warning.days: Number of days to start displaying warning on login page before license expires
  • ami.web.splashscreen.info.html: Information to show on the splashscreen (rendered as html)
  • ami.web.default.MAXSESSIONS:Maximum number of sessions allowed per login of a user

Developer Options

  • ami.autosave.dir: the directory where autosaved versions of the layout are saved. Default is data/autosave
  • ami.autosave.count: The minimum number of backup revisions of layouts that should be saved per user
  • ami.autosave.layout.frequency: How often layouts will be automatically saved to the backup log file. Default is: 15 MINUTES
  • ami.messages.max.info: Maximum number of debug/info messages to store for debugging purposes in edit mode.  Default is 100
  • ami.messages.max.warn: Maximum number of warming messages to store for debugging purposes in edit mode.  Default is 100

Plugins

  • ami.web.auth.plugin.class: Class name of custom authenticator which must implement com.f1.ami.web.auth.AmiAuthenticator interface and be deposited in the plugin directory. The plugin will be responsible for user authentication and configuration. See Ami Authenticator Plugin Manual for details.
  • ami.auth.namespace: Optional namespace that will be passed into authenticator's authenticate(...) method
  • amiscript.custom.classes: A comma delimited list of classes to include for access within ami script. See plugin documentation for details.
  • ami.style.files: Comma delimited list of files (wildcards supported) which contain ami styles. (see menu -> dashboard -> style manager)
  • ami.web.panels: Comma delimited list of custom panel type configurations.
  • ami.auth.timeout.ms: Amount of time, in milliseconds before AMI assumes the authentication plugin has timed out. Default is 5000 milliseconds
  • ami.web.data.filter.plugin.class: Class name of custom Data Filter which must implement the com.f1.ami.web.datafilter. AmiWebDataFilterPlugin interface and be deposited in the plugin directory.  The plugin will be responsible for filtering out data that users shoud have and not have access to.  See Ami Data Data Filter Plugin manual For details
  • ami.guiservice.plugins: A comma delimited list of class names implementing the com.f1.ami.web.AmiWebGuiServicePlugin interface. (See Gui Service Plugin for details)
  • ami.web.permitted.cors.origins: control which origins are accepted in AMI Remote Procedure Calling (see RPC)

Layout and User Files

  • users.access.file: Location of the "access.txt" file, see User Parameters section below.
  • users.path: Directory containing the .ami_settings user files and the user preference files. Default is data/users.
  • ami.shared.layouts.dir: base directory of where shared layouts are stored (those layouts available to end non-dev users). Default is data/shared
  • ami.cloud.dir: base directory of the AMI Cloud. Layouts and user settings saved to the cloud will be stored in this directory.
  • ami.users.file: file name of the users configuration file. See "Access Configuration File for Web" section for details.
  • ami.web.default.layout.shared: [Deprecated, use ami.web.default.layout=SHARED:<layoutname>] Name of the layout's file name. If Specified, then any users that login will be automatically assigned to the specified layout, and developer/admin mode will not be available.  See ami.shared.layouts.dir for where shared layouts are located.
  • ami.font.files: A list of true type font files (.ttf) to load make available for use in dashboards. May include wild cards, ex: my/fonts/*.ttf
  • ami.fonts.in.browser: A list of font family names that are assumed to be available in the browser, meaning the ttf definitions will not be transferred to the browser even if a corresponding ttf file is specified (see ami.font.files). The default is: Arial,Courier,Georgia,Impact,Lucida,Times New Roman,Verdana
  • ami.webmanager.host: Optional location for where to access webmanager, used for remotely loading files. If not specified, local file system is used.
  • ami.webmanager.port: Optional location for where to access webmanager, used for remotely loading files.
  • ami.web.default.LAYOUTS: A comma-delimited list of layout names that are accessible for the users that are non-dev and non-admin.

Default layout

The default layout is the layout to load when a particular user logs in. There are some properties that give a fine control on how the default layout is determined. The property with lower number of priority will be considered first.
If ami.web.default.DEFAULT_LAYOUT (with priority 0) is present, then all other properties with bigger priority values will be ignored.

  • ami.web.default.DEFAULT_LAYOUT: PRIORITY 0
  • ami.web.default.layout: PRIORITY 1
  • The user's ami_layout_shared in access.txt: PRIORITY 2
  • ami.web.default.layout.shared: PRIORITY 3 (This is deprecated, suggested to use ami.web.default.layout=SHARED:<layoutname> instead )
    • note that using ami.web.default.layout.shared in conjunction with ami.shared.layouts.dir=path/to/dir will load a specific layout to every user who logs in, regardless if they are present in access.txt or if you are using an authentication plugin.

The properties above will apply for all users in access.txt. If you want a finer control of default layouts for each individual user, you could put the <property> from the ami.web.default.<property> at the end of each user clause in access.txt, as an example:
If there are two users: user1 and user2. We want to assign user1_defaultLayout.ami to user1 as the default layout, and user2_defaultLayout.ami for user2, then in access.txt:
user1|123456|ISADMIN=true|ISDEV=true|DEFAULT_LAYOUT=user1_defaultLayout.ami
user2|123456|ISADMIN=true|ISDEV=true|DEFAULT_LAYOUT=user2_defaultLayout.ami

Deprecated

  • ami.web.default.layout;
  • ami.web.default.layout.shared; use ami.web.default.layout=SHARED:<layoutname>
  • ami.web.default.to.admin;

End User Behavior

User Settings

All default user-specific settings can be configured programmatically using ami.default.user.<User Setting Name> in local.properties, as an example:

  • ami.default.user.[property]: Set default user settings e.g. set users' default timezone to UTC with ami.default.user.timeZone=UTC (note timeZone uses a capital Z)

Other properties include:

Property Name(key) Property Value(value) Supported Value Example Usage
ami.default.user.dateFormat String, format of date, by default is M/dd/yyyy [yyyy/MM/dd, MM/dd/yy,...] ami.default.user.dateFormat=yyyy/MM/dd
ami.default.user.timeFormat String, format of date, by default is H:mm [hh:mm a, h:mm, HH:mm, h:mm a], (if time is 13:30, then H:mm->3:30, h:mm->1:30 PM, HH:mm->13:30, hh:mm a->01:30 PM) ami.default.user.timeFormat=HH:mm
ami.default.user.numberSeparator String, determines on how the number should be separted, by default is 1,234,567,890.123 [1,234,567,890; 1,234,567,890.123; 1'234'567'890; 1234567890,123; ...] ami.default.user.numberSeparator=1,234,567,890
ami.default.user.numberDecimalPrecision Integer, number from 0-10, by default is 2 Integer number from 0-10 ami.default.user.numberDecimalPrecision=4
ami.default.user.sciNotDigitsLeft Integer, number from 1-20, by default is 1 Integer number from 1-20, ami.default.user.sciNotDigitsLeft=4
ami.default.user.sciNotDigitsLeft Integer, number from 1-20, by default is 3 Integer number from 1-20, ami.default.user.sciNotDigitsRight=5
ami.default.user.numberNegativeFormat String, format of Negative Number. by default is sign, can take either sign or parenthesis [sign,parentheses] ami.default.user.numberNegativeFormat=parentheses
ami.default.user.spreadSheetFormatOption String, spread sheet formating, by default is always, can take either always or never [always,never] ami.default.user.spreadSheetFormatOption=never
ami.default.user.autoApplyUserPrefs String, whether or not automatically apply use preferances, by default is ask, can take always,never or ask [always,never,ask] ami.default.user.autoApplyUserPrefs=always
  • ami.show.menu.option.datastatistics: When to show the data statistics menu option: always, never, dev, admin. (dev - only in dev or admin mode, admin - only in admin mode) default is always
  • ami.show.menu.option.fullscreen: When to show the full screen menu option: always, never, dev, admin. (dev - only in dev or admin mode, admin - only in admin mode) default is always
  • ami.frames.per.second: the rate that the web browser is updated with new data. This is used to tune the performance of AMI and the user experience. We do not recommend a refresh rate of higher than 20 frames per second.
  • ami.web.default.cmd.timeout.ms: the number of milliseconds to wait for a response when sending a command to the backend.  Default is 30000
  • ami.request.timeout.seconds: the amount of time before a user will be prompted that their request could not be serviced. Default is 60 seconds.
  • ami.show.menu.option.datastatistics: Determines which types of users can view data statistics (under Menu Bar -> Help -> Data Statistics) . Valid options are always, never, dev or admin.   Default is always
  • ami.show.menu.option.fullscreen: Determines which types of users can set the browser to full screen (under Menu Bar -> Windows -> Full Screen) . Valid options are always, never, dev or admin.   Default is always
  • ami.web.default.to.admin: by default is true, which means that if there are no admin users registered (See Menu Bar -> Account -> Manage Users) then all users are considered admins. Setting to false means that users will be strictly assigned the role they are associated with.
  • ami.web.default.ISADMIN: by default is false, which means that if ISADMIN is not supplied in access.txt, what is the default value
  • ami.web.default.ISDEV: by default is false, which means that if ISDEV is not supplied in access.txt, what is the default value
  • general.error.message: The generic error message displayed to users when an exception is not caught.  Default is: "Frontend encountered unhandled condition"
  • general.error.emailTo: The email address to send error reports to when a user clicks to report an error. Default is: "[[1]]"
  • general.error.emailSubject: The default subject used to populate the error report email (see general.error.emailTo). Default is "Support Issue"
  • general.error.emailBody: The introductory sentence in the error report email (see general.error.emailTo). Default is "Please find details below:"
  • ami.web.filter.dialog.max.options: Maximum number of options to show in the table filter dialog

Performance

  • ami.web.precached.tables: A comma delimited list of tables (aka types) to automatically cache real-time inside the webserver. Any types that a layout references that are not explicitly listed in this property will require a snapshot request from the Ami Center.
  • ami.chart.threading.suggestedPointsPerThread: Determines the number of threads to use for a chart, based on the number of points to render. Default is 100000
  • ami.chart.threading.maxThreadsPerLayer: Provides a ceiling on total threads that can be used. Default is 10
  • ami.chart.threading.threadPoolSize: The total number of threads (across all users) to allocate for chart image processing. Default is 100
  • ami.chart.threading.antialiasCutoff: The number of points before anti-aliasing should be turned off, so that rendering is faster for high density charts. Default is 100000
  • ami.chart.compressionLevel: The PNG compression level for  the images  that are transferred to the front end where 0=off, 10=Full compression. Default is 2
  • ami.frames.per.second:The number of times that the AMI application's display is refreshed in a single second. Default is 15fps

SAML

  • saml.identity.provider.url: the url of the identity provider
  • saml.service.provider.url: the full url or the service provider (this ami instance's url as known by the identify provider)
  • saml.entityid: The issuer id provided in the samle request
  • saml.relay.state: Optional, adds the RelayState param to the request
  • saml.plugin.class: The class that implements the com.f1.ami.web.AmiWebSamlPlugin interface. For non-customized versions use com.f1.ami.plugins.amisaml.AmiWebSamlPluginImpl
  • saml.username.field: The field of the response to extract username from
  • saml.identity.provider.cert.file: The file containing the certificate
  • saml.identity.provider.clock.skew.ms: Amount of time (in milliseconds) that Identity provider timestamp and service provider timestamp can drift
  • saml.identity.provider.lifetime.ms: Expriry time of IDP request (in milliseconds)
  • saml.debug: set to true to have ami debug verbose saml related information

OKTA (Oauth)

  • sso.plugin.class: The class the implements the AmiWebSSOPlugin. Use com.f1.amioktaauth.AmiOktaOauthPlugin
  • oauth.client.id: Client Id of the application registered to authenticate via OKTA.
  • oauth.client.secret: Client secret of the application registered to authenticate via OKTA.
  • oauth.redirect.uri: The uri OKTA will use to redirect the user once authentication is complete. In this case it will be the uri of amiweb (http://localhost:33332/oktaAuthFinished/). Note that this uri must match with the one configured in OKTA account.
  • oauth.server.domain: The domain of the okta account (https://something.okta.com)
  • oauth.scope: Space delimited scopes indicating the types of resources AMI will be requesting from the resource server. Use openid profile email
  • web.logged.out.url: url to redirect to when logged out, default is / which directs to login page. (Hint: set to /loggedout.htm for a logged out page instead, useful for OAUTH)
  • oauth.authorization.endpoint: Okta authorization endpoint. Default value /oauth2/default/v1/authorize
  • oauth.token.endpoint: Okta token endpoint. Default value /oauth2/default/v1/token
  • oauth.code.challenge.method: Okta code challenge method. Default value S256
  • oauth.oauth.digest.algo: Java hashing algorithm used to verify the code challenge. Default value SHA-256
  • oauth.username.field: The field from Okta identity response to use as the AMI username. Default value email
  • oauth.ami.isadmin.field: The field from Okta identity response use to identity an AMI admin user (Recommended).
  • oauth.ami.isadmin.values: Comma delimited list of AMI admins. If the value of the isadmin field matches any of the values, the user gets AMI admin privileges. Otherwise the user will be in user mode.
  • oauth.ami.isdev.field: The field from Okta identity response use to identity an AMI dev user (Recommended).
  • oauth.ami.isdev.values: Comma delimited list of AMI devs. If the value of the isdev field matches any of the values, the user gets AMI dev privileges.
  • oauth.debug: For detailed logging. Default value false
  • oauth.session.check.period.seconds: Controls polling frequency for a refresh token and also the frequency of the reaper thread to check on the SSO session. Defaults to 60 seconds.

LDAP

The LDAP plugin is available upon request. Please reach out via support@3forge.com

  • ami.auth.plugin.class=com.f1.ami.amildap.AmiAuthenticatorLDAP
  • ldap.address= address of ldap server. Ex: ldap.example.com
  • ldap.port=ldap port, default is 389
  • ldap.bindDN=admin bind DN. Ex: cn=admin,dc=example,dc=com
  • ldap.baseDN=base DN. Ex: ou=group,dc=example,dc=com
  • ldap.bindPW=admin password
  • ldap.attributes=Optional. Comma delimited attributes to search for in ldap (i.e. cn,givenName,sn,mail)
  • ldap.userAttributeName=attribute to identify user object (i.e. sAMAccountName)
  • ldap.maxConnections=Optional. Maximum number of connections (defaults to 10)
  • ldap.initialConnections=Optional. Initial number of connections (defaults to 5)
  • ldap.useSSL=Optional. Specifies that ssl should be used for all connections (defaults to false)
  • ldap.useStartTLS=Optional. Specifies that the StartTLS protocol should be used, requires useSSL to be true
  • ldap.sslTrustStorePath=Optional. Path to the truststore cert (for ssl)
  • ldap.sslTrustStorePin=Optional. Pin for the truststore cert (for ssl)
  • ldap.sslTrustStoreFormat=Optional. Format of the truststore cert (valid inputs are: all,pem. Defaults to JVM defaults otherwise)
  • ldap.sslValidateHostname=Optional. Boolean indicating if the hostname should be validated. (Defaults to true)

Style

  • web.loadingbar.styles: this property takes in a list of key-value pairs. The keys are: dialogBgColor, headerBgColor, stripeColor1, stripeColor2, stripeColor3.

Example usage: web.loadingbar.styles=dialogBgColor=#234567,headerBgColor=#123456,stripeColor1=#ff0000,stripeColor2=#ff00ff,stripeColor3=#f0f0f0

Loading bar properties.png

WebBalancer Configuration Properties (Applies to Components: WebBalancer)

Note: To run the ami webbalancer, include webbalancer in the list of components found in the the ami.components property, ex: ami.components=webbalancer

WebBalancer Routing Rules

  • ami.webbalancer.routes.file: File containing a list of routing rules for determining how incoming client ip addresses are routed to ami web server addresses. Routing Rules are one entry per line with descending priority. Each line is in the form client_ip_mask;target1,target2,target3;BREAK[or CONTINUE]
  • ami.webbalancer.sessions.file: A file for persisting active session rounting, in case of web balancer restart.

WebBalancer Check Frequencies

  • ami.webbalancer.check.sessions.period: How often to check for changes to routes file and stale sessions. Default: 5 SECONDS
  • ami.webbalancer.server.alive.check.period: How often to test servers marked as DOWN, to see if they are alive. Default: 5 SECONDS
  • ami.webbalancer.server.test.url.period: How often to ping servers marked as UP to ensure they are healthy. Default: 30 SECONDS
  • ami.webbalancer.server.test.url: The URL to request from web server for HTTP OK status. Default is /portal/rsc/ami/normal.png
  • ami.webbalancer.session.timeout.period: After what period of time is a session with zero connections considered stale. Default: 1 MINUTE

WebBalancer Client HTTP Connectivity

  • ami.webbalancer.http.port: Optional, the http port to listen for insecure connections on. if not specified, http is not available. Default is 33330
  • ami.webbalancer.http.port.bindaddr: Optional, Specifies the network interface that the ami.webbalancer.http.port port be bound to
  • ami.webbalancer.http.port.whitelist: Optional. Controls access to the http port, 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
  • ami.webbalancer.https.port: Optional, the https port to listen for secure connections. If not specified, https is not available.
  • ami.webbalancer.https.port.bindaddr: Optional, Specifies the network interface that the ami.webbalancer.https.port port be bound to
  • ami.webbalancer.https.port.whitelist: Optional. Controls access to the https port, 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
  • ami.webbalancer.https.keystore.file: The path to the key store file, generated using java's keytool.
  • ami.webbalancer.https.keystore.password: The password associated with the key store file.

WebBalancer.routes

Overview

This file (specified by ami.webbalancer.routes.file) should contain a list of rules, one rule per line.

Rule Format

CLIENT_MASK;SERVERS_LIST;ON_FAILURE #comments

Parameter Description
CLIENT_MASK A pattern matching expression for client ip addresses, (*=wild)
SERVERS_LIST a comma delimited list of [weighting*]protocol://host:port entries. (Only http,https protocols supported, default is http)
ON_FAILURE If all servers in SERVERS_LIST are down, either CONTINUE trying other rules or BREAK and return error to user. Default is BREAK

Each new client connection is passed through the webbalancer rules engine to determine which list of webservers are candidates for forwarding starting at the highest priority (first) rule.

If the client's ip address (as seen by the webbalancer) matches the CLIENT_MASK portion then a web server from the SERVERS_LIST option is chosen for forwarding, see selection strategy for details. The selected forwarding is "sticky for all subsequent connections from the same client ip address for the life of the session (see ami.webbalancer.session.timeout.period for determining when a session can expire).

Selection Strategy The servers from the SERVERS_LIST with an UP status (see ami.webbalancer.server.test.url property determining UP/DOWN status of a server) and the least number of active client sessions is chosen, based on the servers weighting. Ties broken via round-robin. All entries have a default weighting of one (1) but can be overridden by prefixing with a weighting and star (*). Servers with higher weightings will be assigned more users. For example, https://server1:33332,2*https://server2:33332,.5*server3:33332. In this scenario, server 2 would get twice the number of users as server1. Server 3 would get half the number of users as server 1.

Note: If a client address can not be matched to a rule the user will receive an error message.

Examples

192.168.1.1|192.168.1.2|192.168.1.3;https://server1:33332,https://server2:33332; #send those 3 clients to either server1 or server2

192.168.1.*;https://server3:33332; #send all clients in the 192.168.1 address range to server3

192.168.2.*;1*https://server6:33332;4*https://server7:33332; #send all clients in the 192.168.2 address range to server6 or server7. 1/5th of users to server6 and 4/5ths to server7

*;http://server4:33332,http://server5:33332; #all others get sent to server4 or server5

Default:

*;http://localhost:33332;BREAK

WebManager Configuration Properties

Note: To run the ami webmanager, include webmanager in the list of components found in the the ami.components property, ex: ami.components=webmanager

  • ami.webmanager.port: The server port that the webmanager listens on for connections from ami web servers
  • ami.webmanager.port.bindaddr: The server port to bind to
  • ami.webmanager.port.whitelist: The whitelist used to control connections accepted on the port
  • ami.webmanager.mapping.pwd: The working directory for file requests, default is java's path of working directory, typically under 3forge/amione.
  • ami.webmanager.mapping.roots: A key=value comma delimited list of roots that web server file requests are mapped to. The key is a "logical name" and the value is the "actual location". Ex: /public=/opt/files,/=/ takes all file requests under /public and maps them to /opt/files, otherwise all files starting with / are mapped to /
  • ami.webmanager.mapping.strict: If true, file requests requesting a parent directory (via ..) will be rejected. Also, requests denoting home directory (~) will be directory. Default is true. IMPORTANT SECURITY NOTE: Setting to false will allow remote access to all host files accesible by user process.

Default Authentication Access File (Applies to Components: Web)

When an authentication plugin is not supplied a configurable "access" file is referenced by default. Note, this should only be used for testing and other non-production purposes due the lack of security, etc. This is where usernames, passwords, default layouts, and user parameters are defined. The access configuration files lives in the directory of the Web application and is named data/access.txt by default.  Each line should contain a single user's entry which is pipe (|) delimited. The first entry is the username, 2nd is the password, additional parameters are key=value.

Username: First Param, the username defined is what a user needs to login as.

Password: Second Param, this is the only place that passwords can be set for users.

key=value: Additional parameters. The following keys are supported:

  ISDEV=true/false - Determines if the user should have developer rights, aka should they have the green toggle button in the upper right corner
  ISADMIN=true/false - If ISDEV is set to false, then this has no effect. If ISDEV is set to true and ISADMIN is set to true, then dev user can shutdown AMI from the GUI via File -> Shutdown.
  amiscript.variable.varname=value  - Defines a variable in the user session, with the type inferred. For example amiscript.variable.blah=123 creates a variable named blah of type int with the value 123.  Alternatively, amiscript.variable.blah="123" would create the variable as a string instead.
  amivar.varname=value  - Deprecated - defines a variable of type string in the user session prefixed with user<dot> For example amivar.blah=123 creates a variable inside user user's session named user.blah with the string value "123"
  developer_ami_editor_keyboard=vi/default - For developer mode, should the editor use plain text or vi mode
  ami_layout_shared=default layout to load (under the directory configured using the ami.shared.layouts.dir property)
  ami_layout_current=Current layout
  LAYOUTS=A comma delimited list of regular expressions for layouts that are available to this user. This is only applicable to CLOUD layouts.


User Parameters: parameters can be assigned to a user. These parameters can then be used to modify the user's access to data and inputs.  

Example Configuration File

jdoe|jdoe123|ami_layout_shared=ACME.ami|amivar_group=ops

csmith|password1234

exampleusername|pass24|amivar_region=asia

exampleusername|pass24|LAYOUTS=overview.ami, report.ami, *rfp.ami

Instructions: Encrypting values inside .properties files

For this example, let's say you have the following property in your local.properties and you want to encode the password

myurl=http://blah?pass=password123456&user=steve

Step 1: Under the scripts directory, use the tools.sh to create a 128-bit strength key (feel free to adjust the strength).

./tools.sh --aes_generate /opt/ami/secret.aes 128

Step 2: Add this option to your start.sh so that AMI knows where the secret key for decoding encrypted properties is located

-Dproperty.f1.properties.secret.key.files=/opt/ami/secret.aes

Step 3: Using the same tools.sh, Encode the password and copy the output text into your clipboard

./tools.sh -aes_encrypt /opt/ami/secret.aes password123456

_fYjHz8Dr4o7XjZcOd1BhtKzV9U5MpZMpTyGlu-mpheL4qV-ZX-yUads

Step 4: Change your local.properties file to use the encrypted value instead, by enclosing with ${CIPHER: ... }

myurl=http://blah?pass=${CIPHER:_fYjHz8Dr4o7XjZcOd1BhtKzV9U5MpZMpTyGlu-mpheL4qV-ZX-yUads}&user=steve

Step 5: Restart AMI

In the AmiOne.log you'll see that the value for the myurl property is substituted with ***** for security purposes.

Two Notes

For additional passwords: Skip steps 1 and 2

Tip: you can also decrypt using tool.sh by running:

./tools.sh -aes_decrypt /opt/ami/secret.aes _fYjHz8Dr4o7XjZcOd1BhtKzV9U5MpZMpTyGlu-mpheL4qV-ZX-yUads password123456

Default File Structure - AMI

Below is the standard file structure for a new install of ami after it has been run once.

ami
├───README_AMIONE.txt
├───uninstall.exe
│
├───.install4j
│   └───...
│
├───jre  - - - - - - - - - - - - - - - - - - Location of the Java JRE used by AMI
│   └───...
│
└───amione
    ├───.amionemain.prc  - - - - - - - - - - Used by stop.sh to shutdown AMI
    ├───.console_history.txt
    ├───.f1proc.txt
    ├───AMI_One.exe
    ├───AMI_One.vmoptions  - - - - - - - - - Virtual machine options
    ├───error.log  - - - - - - - - - - - - - Major error log
    ├───output.log - - - - - - - - - - - - - Startup log
    │
    ├───config - - - - - - - - - - - - - - - Directory for storing properties, we recommend adding a local.properties file here, see the "AMI Configuration Guide" for more details
    │   ├───root.properties  - - - - - - - - References load order of other properties files
    │   ├───defaults.properties  - - - - - - Default properties
    │   ├───build.properties - - - - - - - - Build version properties
    │   └───speedlogger.properties - - - - - Logging properties
    │
    ├───data - - - - - - - - - - - - - - - - Stores developer/admin created files, such as routing tables.
    │   ├───access.txt - - - - - - - - - - - Access file (will be overwritten if new installation is on top of old)
    │   ├───managed_schema.amisql  - - - - - Schema file for AMIDB
    │   ├───relay.routes - - - - - - - - - - List of relay route names
    │   │
    │   ├───autosave - - - - - - - - - - - - Directory for autosaves by user
    │   │   ├───demo.cnt - - - - - - - - - - Current autosave number
    │   │   ├───demo.cur - - - - - - - - - - Recent autosaves
    │   │   ├───demo.old - - - - - - - - - - Older autosaves
    │   │   └───...
    │   │
    │   ├───cloud  - - - - - - - - - - - - - Directory for layouts saved in the cloud
    │   │   ├───my_layout.ami
    │   │   └───...
    │   │
    │   ├───fonts  - - - - - - - - - - - - - Directory for fonts
    │   │   ├───Arial.ttf
    │   │   └───...
    │   │
    │   ├───idfountain - - - - - - - - - - - Directory for managing autoincrementing ids
    │   │   └───...
    │   │
    │   ├───styles - - - - - - - - - - - - - Directory for readonly styles
    │   │   ├───HALLOWEEN.amistyle.json
    │   │   └───...
    │   │
    │   └───users  - - - - - - - - - - - - - Directory for user preferences
    │           demo.ami_settings
    │
    ├───history
    │   └───ami_console.history  - - - - - - AMI command line history
    │
    ├───lib  - - - - - - - - - - - - - - - - Directory for java libraries, including libraries for AMI web
    │   └───...
    │
    ├───log  - - - - - - - - - - - - - - - - Files with numbered extensions e.g. 0001 are logs from past runs of ami; files without numbered extensions are the most recent logs
    │   ├───AmiMessages.log  - - - - - - - - Log of all messages received by AMI
    │   ├───AmiMessages.log.0001
    │   ├───AmiOne.amilog  - - - - - - - - - Log of internal messages within AMI
    │   ├───AmiOne.amilog.0001
    │   ├───AmiOne.log - - - - - - - - - - - AMI console log
    │   └───AmiOne.log.0001
    │
    ├───persist  - - - - - - - - - - - - - - Directory for AMI Generated files used for recovery (on restart).
    │   ├───amikey.aes - - - - - - - - - - - Encryption key for user passwords, see "Encrypting passwords in access.txt" for more details
    │   ├───__CENTER.dat - - - - - - - - - - Info on multiple centers
    │   ├───__DATASOURCE.dat - - - - - - - - Info on datasources
    │   └───__REPLICATION.dat  - - - - - - - Info on replication centers
    │
    ├───resources  - - - - - - - - - - - - - Directory for storing resources (ex images) to be used by the webserver
    │
    └───scripts  - - - - - - - - - - - - - - UNIX/DOS scripts for starting/stopping AMI
        ├───start.sh
        ├───stop.sh
        ├───restart.sh
        ├───tools.sh
        ├───start.bat
        ├───stop.bat
        ├───restart.bat
        └───tools.bat

AMI Download File Naming Convention

Windows: ami_windows-x64_[version]_[branch].exe

Mac: ami_macos_[version]_[branch].dmg

Unix: ami_unix_[version]_[branch].sh

Other (Tar gz): ami_unix_[version]_[branch].tar.gz