Skip to content
Architecture > Configuration Guide

Common Properties

This document contains a list of configurable properties that apply to all the following components: Center, Relay, Web.

For other components, please see these pages:

  • Center (properties specific to the Center component)
  • Web (properties specific to the Web component)
  • Relay (properties specific to the Relay component)
  • WebBalancer and WebManager (properties for managing connections to 3forge Web)

General 3forge Properties

These properties configure basic runtime behavior of a 3forge application.

Note

Property default values that are prefixed with a # are optional or must be configured by the user before use.

ami.components

Default:
1
ami.components=relay,center,web
Description:
  • A comma-delimited list of which components to load
  • This can be any combination of:
    • the Relay
    • the Center
    • the Web
    • WebBalancer
    • WebManager
  • See this guide for more

f1.terminate.file

Default:
1
f1.terminate.file=config//../.amionemain.prc
Description:
  • A small file generated as part of the AMI package to enable clean shutdown of 3forge from an external process or script
  • If an external process moves/copies to a file of the same name, but with a .kill suffix, the process will exit

f1.threadpool.default.size

Default:
1
f1.threadpool.default.size=8
Description:
  • The number of threads in the core thread pool (this does not include threads for http servicing or image processing)

f1.threadpool.aggressive

Default:
1
f1.threadpool.aggressive=true
Description:
  • If true, will use an "aggressive" thread pool
  • This pool will wake up faster, but uses more CPU while idle

f1.conf.dir

Default:
1
f1.conf.dir=amione/config
Description:
  • Directory to where the configuration files are located

f1.conf.filename

Default:
1
f1.conf.filename=root.properties
Description:
  • Name of the configuration file loaded at startup
  • We do not recommend changing this

f1.timezone

Default:
1
f1.timezone=UTC
Description:
  • Set timezone for the JVM (this does not control default user or logger timezones)

f1.locale

Default:
1
f1.locale=default
Description:
  • Default locale, can be set either as <language> or <language>_<country>
  • Fields accept ISO 3166-1 alpha-2/alpha-3/full name
  • E.g:
    • <language>: EN/ENG/ENGLISH
    • <country>: US/USA/UNITED STATES

f1.logs.dir

Default:
1
f1.logs.dir=amione/log
Description:
  • The root directory for where log files will be deposited

f1.plugins.dir

Default:
1
f1.plugins.dir=amione/plugins
Description:
  • Directory of where plugins will be loaded from

f1.resources.dir

Default:
1
f1.resources.dir=amione/resources
Description:
  • Directory of where additional resources will be placed

ami.amilog.stats.period

Default:
1
ami.amilog.stats.period=15 SECONDS
Description:
  • How often 3forge should log general health statistics such as memory, user load, etc
  • Can be used for real-time/historical monitoring via the performance dashboard

ami.naming.service.resolvers

Default:
1
# ami.naming.service.resolvers=fully_qualified_classname_of_plugin
Description:
  • 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

Default:
1
ami.content.security.policy=img-src 'self' https://*.mapbox.com data: w3.org/svg/2000; default-src https://*.mapbox.com 'self' 'unsafe-inline' 'unsafe-eval' blob:
Description:
  • For more information regarding Content Security Policy, please refer to the this link

ami.aes.key.file

Default:
1
ami.aes.key.file=persist/amikey.aes
Description:
  • The aes key file used for encrypting/decrypting secure data (see strEncrypt()/strDecrypt() in the Center methods for examples)

ami.aes.key.text

Default:
1
# ami.aes.key.text=<aes_key>
Description:
  • The aes key used for encrypting/decrypting secure columns (instead of using ami.aes.key.file)

ami.aes.key.strength

Default:
1
ami.aes.key.strength=128
Description:
  • Key strength, e.g: 128

Log Properties

For debugging purposes, when 3forge launches, it generates a few log files. These are:

  1. AmiOne.log

    • The main log file
    • You should refer to this for any issues with your runtime

  2. AmiOne.amilog

    • A machine-readable log file
    • Contains information about memory usage, etc.

  3. AmiMessages.log

    • Tracks messages that are being sent to and from 3forge (real-time)

For more information on how to interpret log files, see this page.

Log Property Structure

There are a number of properties to configure the log files to your preference. The structure of each property is as follows:

1
speedlogger.<log_type>.<log_subtype>.<property>

Example

Consider the following property:
1
speedlogger.stream.=BASIC_APPENDER;FILE_SINK;INFO

This is a stream property, which determines how different log messages are streamed into the log file.

The flag INFO refers to the level of verbosity of the output in the log file, in this case "informative."

Where log files are stored, how many previous logs are kept on disk, and the verbosity of a log message can all be configured via the local.properties file.

Log Files and Directories

Note

If you want to change the location of the stderr, stdout, and gc.log files, you will need to manually edit the start.sh file in amione/scripts for each file type.

Properties with the prefix speedlogger.sink determine the file structure of 3forge logs. The default configuration for the basic log file looks like this: 

1
2
3
4
speedlogger.sink.FILE_SINK.type=file
speedlogger.sink.FILE_SINK.fileName=\${f1.logs.dir}/\${f1.logfilename}.log
speedlogger.sink.FILE_SINK.maxFiles=10
speedlogger.sink.FILE_SINK.maxFileSizeMb=1000

The FILE_SINK property refers to the file that logs are written to. The default directory for logs will be in the root directory of your installation in amione/log, and the default log file is AmiOne.

To change the FILE_SINK configuration to use a different directory or file name, you will need to change the following variables in your local.properties file, which will be referenced in other logging properties:

f1.logs.dir

Default:
1
f1.logs.dir=amione/log
Description:
  • Where the log files are stored
  • To change, set this property to f1.logs.dir=path/to/your/directory

f1.logfilename

Default:
1
f1.logfilename=AmiOne
Description:
  • Name of the log file where logs are stored
  • To change, set this property to f1.logfilename=<your_logfile_name>

To change the number of log files that are recorded, set the following properties:

speedlogger.sink.FILE_SINK.maxFiles

Default:
1
speedlogger.sink.FILE_SINK.maxFiles=10
Description:
  • Maximum number of session logs saved before overwriting and deleting
  • Sessions are numbered in ascending order (most recent to oldest)
  • To change, set this property to your desired value

speedlogger.sink.FILE_SINK.maxFileSizeMb

Default:
1
speedlogger.sink.FILE_SINK.maxFileSizeMb=1000
Description:
  • Maximum size of a log file in MB
  • To change, set this property to your desired value

Wherever FILE_SINK is called in a property will call back to these variables.

Each collection of log types will have their own similar configurable properties, the full list can be found below.

Log Message Appenders

The message appenders determine the content and style of a log message that is added to the log file.

For the basic files (AmiOne), a description of the appender properties are below.

speedlogger.appender.BASIC_APPENDER.pattern

Default:
1
speedlogger.appender.BASIC_APPENDER.pattern=%P %d{YMD-h:m:s.S z} [%t] %c::%M: %m %D%n
Description:
  • The pattern of the appender's log message
  • The default structure is:
    • %P: log level
    • %d{YMD-h:m:s.S z}: date (format and timezone)
    • [%t]: message origin type
    • %c::%M:: ID of internal AMI class::method call
    • %m: log message/description
    • %D%n: any additional details

speedlogger.appender.BASIC_APPENDER.type

Default:
1
speedlogger.appender.BASIC_APPENDER.type=BasicAppender
Description:
  • The implementation of SpeedLoggerAppender factory used
  • Use the existing BasicAppender class

speedlogger.appender.BASIC_APPENDER.timezone

Default:
1
speedlogger.appender.BASIC_APPENDER.timezone=EST5EDT
Description:
  • Timezone of an appender's log message
  • To change, set this value to any Java accepted timezone

speedlogger.stream.

Default:
1
speedlogger.stream.=BASIC_APPENDER;FILE_SINK;INFO
Description:
  • Properties of the basic logger (how a log message is actually streamed into the log file):
    1. Which appender (BASIC_APPENDER)
      • Pattern determined in speedlogger.appender.BASIC_APPENDER.pattern
    2. Which log file (FILE_SINK)
    3. Which log level (INFO)

Warning

We do not recommend changing the pattern or type of appender used for each log message type.

If you require additional information, please reach out to us at support@3forge.com

Log Level Verbosity

To adjust the log level for a certain class of logs, replace the corresponding label (the flag at the end of the property) on a stream property with the label you require.

Code Full label
ALL All
FNE Fine
INF Info
WRN Warning
SVR Severe
OFF OFF

Where ALL gives the highest verbosity and OFF gives none.

Speedlogger Properties List

Below are the default configurations for each log type.

Basic

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# Define the log message pattern and timezone for basic log messages by configuring an appender: BASIC_APPENDER
speedlogger.appender.BASIC_APPENDER.pattern=%P %d{YMD-h:m:s.S z} [%t] %c::%M: %m %D%n
speedlogger.appender.BASIC_APPENDER.timezone=EST5EDT
speedlogger.appender.BASIC_APPENDER.type=BasicAppender 

# Configure the log file properties - directory, naming convention, number of files, size of files
speedlogger.sink.FILE_SINK.type=file
speedlogger.sink.FILE_SINK.fileName=${f1.logs.dir}/${f1.logfilename}.log
speedlogger.sink.FILE_SINK.maxFiles=10
speedlogger.sink.FILE_SINK.maxFileSizeMb=1000

# Set stream properties for general AMI log messages 
speedlogger.stream.=BASIC_APPENDER;FILE_SINK;INFO
speedlogger.stream.AMI=BASIC_APPENDER;FILE_SINK;OFF

AmiScript

1
2
3
4
5
6
7
8
# Define AmiScript log message pattern and timezone by configuring an appender: SIMPLE_APPENDER
speedlogger.appender.SIMPLE_APPENDER.pattern=%P %d{YMD-h:m:s.S z} [%t] %c: %m %D%n
speedlogger.appender.SIMPLE_APPENDER.timezone=EST5EDT
speedlogger.appender.SIMPLE_APPENDER.type=BasicAppender  

# Set stream properties for AmiScript log messages 
speedlogger.stream.AMISCRIPT.LOGINFO=SIMPLE_APPENDER;FILE_SINK;INF
speedlogger.stream.AMISCRIPT.LOGWARN=SIMPLE_APPENDER;FILE_SINK;WRN

Backend Messages

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
# Define backend log message pattern and timezone by configuring an appender: AMIMESSAGES_APPENDER
speedlogger.appender.AMIMESSAGES_APPENDER.pattern=%d{YMD-h:m:s.S z} %m%n
speedlogger.appender.AMIMESSAGES_APPENDER.timezone=EST5EDT
speedlogger.appender.AMIMESSAGES_APPENDER.type=BasicAppender 

# Configure the log file properties for AMI messages - directory, naming convention (we don't recommend changing this), number of files, size of files
speedlogger.sink.AMIMESSAGES_SINK.type=file
speedlogger.sink.AMIMESSAGES_SINK.fileName=${f1.logs.dir}/AmiMessages.log
speedlogger.sink.AMIMESSAGES_SINK.maxFiles=10
speedlogger.sink.AMIMESSAGES_SINK.maxFileSizeMb=1000 

# Set stream properties for AMI messages log messages
speedlogger.stream.AMI_MESSAGES=AMIMESSAGES_APPENDER;AMIMESSAGES_SINK;INFO

3forge Web Tracking

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
# Define the log message pattern and timezone for Web tracking messages by configuring the appender: AMITRACKER_APPENDER
speedlogger.appender.AMITRACKER_APPENDER.pattern=%d{YMD-h:m:s.S z} %m%n
speedlogger.appender.AMITRACKER_APPENDER.timezone=EST5EDT
speedlogger.appender.AMITRACKER_APPENDER.type=BasicAppender 

# Configure the log file properties for Web tracking - directory, naming convention (we don't recommend changing this), number of files, size of files
#speedlogger.sink.AMITRACKER_SINK.type=file
#speedlogger.sink.AMITRACKER_SINK.fileName=${f1.logs.dir}/AmiWebActivityTracker.log
#speedlogger.sink.AMITRACKER_SINK.maxFiles=10
#speedlogger.sink.AMITRACKER_SINK.maxFileSizeMb=1000 

# Set  stream properties for Web tracking log messages
speedlogger.stream.AMI_ACTIVITY_TRACKER=AMITRACKER_APPENDER;FILE_SINK;ALL

To save 3forge tracking logs to a separate file, remove the comment denotation (#) on lines 7-10.

3forge Statistics

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# Define the log message pattern and timezone for detailed machine-readable messages on memory usage and other statistics by configuring the appender: AMISTATS_APPENDER
speedlogger.appender.AMISTATS_APPENDER.pattern=%m%n
speedlogger.appender.AMISTATS_APPENDER.type=BasicAppender 

# Configure the log file properties for stat tracking - directory, naming convention, number of files, size of files
speedlogger.sink.AMISTATS_SINK.type=file
speedlogger.sink.AMISTATS_SINK.fileName=${f1.logs.dir}/${f1.logfilename}.amilog
speedlogger.sink.AMISTATS_SINK.maxFiles=10
speedlogger.sink.AMISTATS_SINK.maxFileSizeMb=1000 

# Set stream properties for statistics log messages
speedlogger.stream.AMI_STATS=AMISTATS_APPENDER;AMISTATS_SINK;ALL

Disable or Mute Messages

Any time you wish to mute certain messages from showing up in your AmiOne.log, you can use the following template:

  1. Determine the class of 3forge messages you wish to mute.

  2. Add the following line to your local.properties, replacing CLASSNAME with the the class you wish to mute: 

    1
    speedlogger.stream.CLASSNAME=BASIC_APPENDER;FILE_SINK;OFF

Example

Given a log output like this:
1
INF 20231108-13:32:25.009 EST5EDT [F1POOL-04] com.f1.ami.amicommon.centerclient.AmiCenterClientState::onUserSnapshotRequest: localhost:3341 (seqnum=721) User demo requested: [team] of which [team] will be requested from the the Center

The property would be: 

1
speedlogger.stream.com.f1.ami.amicommon.centerclient.AmiCenterClientState=BASIC_APPENDER;FILE_SINK;OFF

REST API Properties

AMI provides a REST server that can be used to query performance and other statistics of the application. More information can be found on here.

REST Endpoint Properties

These properties configure the AMI REST API endpoint addresses.

ami.rest.plugin.classes

Default:
1
ami.rest.plugin.classes=com.f1.ami.amicommon.rest.AmiRestPlugin_Version,com.f1.ami.amicommon.rest.AmiRestPlugin_Whoami,com.f1.ami.amicommon.rest.AmiRestPlugin_Whatsmyip,com.f1.ami.amicommon.rest.AmiRestPlugin_Stats,com.f1.ami.center.AmiRestPlugin_Query
Description:
  • List of classes that implement com.f1.ami.amicommon.rest.AmiRestPlugin

ami.rest.auth.plugin.class

Default:
1
ami.rest.auth.plugin.class=com.f1.ami.web.auth.AmiAuthenticatorFileBacked
Description:
  • Class for authentication

ami.rest.show.errors

Default:
1
ami.rest.show.errors=true
Description:
  • If there is an exception in the endpoint, list it in the REST response
  • Convenient for debugging, but less secure

ami.rest.show.endpoints

Default:
1
ami.rest.show.endpoints=true
Description:
  • Determines whether all endpoints should be shown when browsing to /3forge_rest
  • Convenient for debugging, but less secure

ami.rest.uses.web.port

Default:
1
ami.rest.uses.web.port=true
Description:
  • If true, uses the same port as the HTTP port (access via appending /3forge_rest to the HTTP address)
  • If false, you will need to manually configure the port using ami.rest.http.port

REST Server Host Properties

If you opt to host the REST server on a different port to the Web, you will need to configure at least the following property to host the REST server on the local machine: 

1
ami.rest.http.port=<port>

Otherwise, the minimum configuration for a HTTP connection is the following: 

1
2
3
ami.rest.http.port=<port>
ami.rest.http.port.bindaddr=<network_interface>
ami.rest.http.port.whitelist=<options>

The full list of configurable REST properties is listed below.

HTTP Connection to REST Server

ami.rest.http.port

Default:
1
# ami.rest.http.port=<port>
Description:
  • The HTTP port the REST server should use

ami.rest.http.port.bindaddr

Default:
1
# ami.rest.http.port.bindaddr=<network_interface>
Description:
  • Specifies the network interface that the REST server HTTP port will be bound to

ami.rest.http.port.whitelist

Default:
1
# ami.rest.http.port.whitelist=<options>
Description:
  • Provide either a list of permitted hostname patterns, or a plugin for blocking/granting access based on foreign network address
  • Syntax:
    1. file: file:<file_containing_a_hostname_patterns_per_line\>
    2. text: text:<newline_delimited_list_of_hostname_patterns>
    3. plugin: plugin:<class_name_implementing_com.f1.ami.amicommon.AmiServerSocketEntitlementsPlugin\>

HTTPS Connection to REST Server

ami.rest.https.port

Default:
1
# ami.rest.https.port=<port>
Description:
  • Specifies the HTTPS port the REST server should use for secure access

ami.rest.https.port.bindaddr

Default:
1
# ami.rest.https.port.bindaddr=<network_interface>
Description:
  • Specifies the network interface that the REST server HTTPS port will be bound to

ami.rest.https.port.whitelist

Default:
1
# ami.rest.https.port.whitelist=<options>
Description:
  • Provide either a list of permitted hostname patterns, or a plugin for blocking/granting access based on foreign network address
  • Syntax:
    1. file: file:<file_containing_a_hostname_patterns_per_line\>
    2. text: text:<newline_delimited_list_of_hostname_patterns>
    3. plugin: plugin:<class_name_implementing_com.f1.ami.amicommon.AmiServerSocketEntitlementsPlugin\>

ami.rest.https.keystore.contents.base64

Default:
1
# ami.rest.https.keystore.contents.base64=<base64_key>
Description:
  • If using an SSL connection, supply contents of a keystore as base64

ami.rest.https.keystore.file

Default:
1
# ami.rest.https.keystore.file=/path/to/keystore/created/by/java/keytool
Description:
  • Supply if using an SSL connection
  • Path to the keystore file (using Oracle keytool)

ami.rest.https.keystore.password

Default:
1
# ami.rest.https.keystore.password=keystore_password
Description:
  • Password associated to keystore file

Java Virtual Machine (JVM) Properties

3forge runs in the JVM which takes a set of Java options that configure its behavior and how the application is built.

The JVM properties are configured in a .vmoptions file located in the amione directory of the 3forge installation. Depending on the OS, this is either:

  • AMI_One.vmoptions (for Windows)
  • AMI_One_linux.vmoptions (for Linux)

These properties are then parsed in start.sh and used to launch AMI correctly.

Some of these properties control how messages are logged and how garbage collection is handled. Here are some examples of the JVM Properties:

Java Properties

1
-Djava.util.logging.manager=com.f1.speedlogger.sun.SunSpeedLoggerLogManager
  • Forces Java to use the 3forge logger 
1
2
-Dlog4j.configuratorClass=com.f1.speedloggerLog4j.Log4jSpeedLoggerManager
-Dlog4j.configuration=com/f1/speedloggerLog4j/Log4jSpeedLoggerManager.class
  • Forces other 3rd party plugins that were written for log4j to use 3forge logger instead

3forge Properties

1
-Df1.global.procinfosink.file=./.f1proc.txt
  • Controls where 3forge will write proc information on the application's uptime/downtime 
1
-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 
1
-Df1.license.property.file=config/local.properties
  • The file containing the f1.license.file property which points to the license file 
1
-Dproperty.f1.conf.dir=config/
  • Directory where the root.properties file is located 
1
-Dproperty.f1.properties.secret.key.files=/path/to/keyfile
  • Comma-delimited list of keyfiles for encrypting and decrypting .properties files
  • If specified, the ${CIPHER:xxxxxx} syntax within .properties files will be decoded using the keyfile's key
  • See this page on encrypting .properties files