AMI Configuration Guide
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.
#My local.properties located under config directory
#Note, lines starting with pounds are comments (except for #INCLUDE)
#Override the http port to standard port
#Override the location of the access.txt file
#Process and include properties from a custom properties file
#Define my own custom value
#Reference my custom value
#Append to an existing variable
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: default time zone. For the web component, this will also apply for users that have not saved personalized default preferences
- 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. 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.
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
- ami.port.bindaddr: Optional. Specifies the network interface that the ami.port server port be bound to
- ami.port.whitelist: Provide either a list of permitted hostname patterns or plugin for blocking/granting access based on foreign network address. Syntax is either file:<file_containing_a_hostname_patterns_per_line> or text:<comma_delimited_list_of_hostname_patterns> or plugin:<class_name_implementing_com.f1.ami.amicommon.AmiServerSocketEntitlementsPlugin>
- ami.log.messages: If set to true, all messages sent into and out of ami relay to/from other applications will be logged to a file
- ami.send.cr: If set to true, by default the relay will send a CR back on each response, in addition to a new line
- ami.center.host: Sets the hostname of the primary instance of ami center
- ami.center.backup.port: Optionally, sets the port of the backup instance of ami center
- ami.center.backup.host: Optionally, sets the hostname of the backup instance of ami center.
- ami.ssl.port: Optionally, sets the secure port that ami center is listening on.
- ami.ssl.backup.port: Optionally, sets the secure port that the backup ami center is listening on.
- ami.relay.guaranteed.messaging.enabled: If true, the relay will use a store and forward journal to record messages to disk prior to an ACK message being sent to the originating client. The journal can also be used to deliver messages to late-subscribing Ami Centers. Default is false.
- ami.relay.persist.dir: Where to store the recovery journal files, if ami.relay.guaranteed.messaging.enabled is set to true. Default is ./persist
- ami.centers: A comma delimited list of centers' host:port to connect to. You can optionally prefix host:port with an alias in the form alias=host:port, in which case the alias will be used to reference the center within the relay.routes file. If an alias is not provided, then the alias is the host:port. Ex: ami.centers=myprimary=localhost:3270,other=some.host.com:3270
- ami.relay.routes.file: a file containing routing tables used for controlling which real-time streaming messages are sent to which center(s). Default is data/relay.routes See Relay Routes File for details. Note, if a file is not found, a placeholder file with instructions will be created there.
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||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.
- 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
#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;
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:<comma_delimited_list_of_hostname_patterns> or plugin:<class_name_implementing_com.f1.ami.amicommon.AmiServerSocketEntitlementsPlugin>
- ami.aes.key.file: The aes key file used for encrypting / descrypting secure columns
- ami.aes.key.strength: Key strength, ex: 128
- idfountain.path: The path that is used persist files for managing auto-incrementing ids (amiid)
- idfountain.batchsize: (advanced) The number of IDs AMI should generate per visit to the physical store. Larger numbers mean less frequent visits to the file system but result in larger potential id-gaps on restart. Default is 1000000
- ami.unknown.realtime.table.behavior: Defines the behavior when real-time data is streamed into AMI but the type (T="...") values is undefined in the realtime database schema. The default is LEGACY. Permissible values are: IGNORE - drop records and don’t log anything, LOG_ERROR - drop records and log a warning, LEGACY - insert as a legacy record, CREATE_TABLE - Automatically create a new PUBLIC table with the correct columns corresponding to the record's fields and values.
- ami.center.publish.changes.period.millis - How often AMI Center publishes batched data changes out to consumers such as AmiWeb. Default is 500 milliseconds
- ami.log.query.max.chars - By default all queries, along with the username and duration are logged to the server log file. This property controls the max length of a query to get logged before truncating. If set to 0 then the contents of the query are not logged. If -1 then nothing is logged
- ami.center.log.stats.period.millis - How often stats are written to the AmiOne.amilog (or AmiCenter.amilog) file
- ami.resources.monitor.period.millis - How often the resources directory is scanned for new/updated files. Default is 5,000 milliseconds. See ami.resources.dir
- ami.resources.dir - Where resources, such as images and audio files, are stored. These resources are accessed from the front end via Dashboard > Resource manager
- 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
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
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.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.
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
- 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.
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: how often to check for session times (users that have closed their browser or are disconnected w/o a valid logout). Default is 60 seconds.
- ami.session.timeout.seconds: the amount of time before a session is considered timed out 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:<comma_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
- 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.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.slow.amiscript.warn.ms: Log a warning if an amiscript block can not be executed the specified duration in milliseconds. Default is 1000
- 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 "firstname.lastname@example.org?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.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
- ami.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: File that contains user access rights for layouts, as administered by File -> Manage 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: 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.show.menu.option.datastatistics: When to show the data statistics menu option: always, never, dev, admin. (dev - only in dev or adming 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 adming 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.
- 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: "[]"
- 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
- 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
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. Defaault 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.
This file (specified by ami.webbalancer.routes.file) should contain a list of rules, one rule per line.
|CLIENT_MASK||A pattern matching expression for client ip addresses, (*=wild)|
|SERVERS_LIST||a comma delimited list of 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. With ties broken via round-robin.
Note: If a client address can not be matched to a rule the user will receive an error message.
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
*;http://server4:33332,http://server5:33332; #all others get sent to server4 or server5
Default Authentication Access File ((Applies to Components: Web)
When an authentication plugin is not supplied a configurable "access" file is referenced by default. 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 entry which is pipe (|) delimited containing the following in order:
Username: the username defined is what a user needs to login as.
Password: this is the only place that passwords can be set for users.
Default Layout: if a user is assigned a default layout, they will automatically be classified as a basic user without administrative or developer rights. When the user logs in, they will automatically see the default layout without the ability to modify it. The layout configuration must be exported from the dashboard view. Copy and paste this into a text file and save the file to the AMI Web directory. Call the layout using the name of this text file. See example below.
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
Default File Structure - AMI
3forge/amione/config/build.properties - build information
3forge/amione/config/default.properties - default properties
3forge/amione/config/root.properties - references load order of properties files
3forge/amione/config/speedlogger.properties - logging config
3forge/amione/lib/ - directory java libraries, including libraries for AMI web
3forge/amione/data/ - Stores developer/admin created files, such as routing tables.
3forge/amione/persist/ - Stores AMI Generated files used for recovery (on restart).
3forge/amione/scripts/start.sh - UNIX script for starting AMI
3forge/amione/scripts/stop.sh - UNIX script for stopping AMI
3forge/amione/scripts/start.bat - DOS script for starting AMI
3forge/amione/scripts/stop.bat - DOS script for stopping AMI
3forge/amione/scripts/restart.sh - UNIX script for restarting AMI
3forge/amione/data/access.txt - see default authentication access file section
3forge/amione/data/resources - place resources (ex images) used by web in this directory
3forge/amione/config/local.properties - create, and override properties here
AMI Download File Naming Convention
Other (Tar gz): ami_unix_[version]_[branch].tar.gz