Configuration

Crazy Ivan can be configured from one or more sources:

  • Environment Variables
  • Command Line Arguments
  • Consul KV Store
  • Vault KV Store
  • Properties File

The application gives priority to the values retrieved in the above order. This means that an environment variable setting will override any other setting.

Command Line arguments and Properties File keys are lower case, and separated by periods (ie. ‘section.key=’). Environment Variables, Vault, and Consul keys are all upper case, and are separated by underscores (ie. ‘SECTION_KEY=’).

All arguments are prefixed with the application name and profile name (ie. ‘section.key’ becomes ‘ivan.prod.section.key’). The profile name can be changed by providing the command line argument ‘profile’:

./crazy_ivan profile=dev

You can store multiple profiles in your configuration sources, and then specify which one to use on startup of each instance.

Cluster Name

The ‘cluster’ option on the command line or in a properties file, or the ‘AOSSL_CLUSTER_NAME’ environment variable, will set the name of the cluster. A cluster is a grouping of Crazy Ivan instances, which have been assigned particular scenes to manage. Each Crazy Ivan instance is designed to manage a set number of scenes, and this allows for highly optimized streaming of object updates.

The cluster name will affect both how Crazy Ivan registers with Consul, if provided, as well as the names of cluster-specific security properties.

Vault

Vault Address - Starts Crazy Ivan against a Vault instance. Specified by a collection of arguments:

  • vault (Environment Variable VAULT) - the address of the vault instance
vault=http://localhost:8200
  • vault.cert (Environment Variable VAULT_CERT) - the location of the SSL certificate

to use when communicating with Vault. You may also leave this blank to enable SSL encryption without providing a client certificate.

vault.cert=
  • vault.authtype (Environment Variable VAULT_AUTHTYPE) - the authentication type

used by Vault, currently supported options are ‘APPROLE’ and ‘BASIC’

vault.authtype=BASIC
  • vault.un (Environment Variable VAULT_UN) - The Username/Role Id for

authenticating with Vault

vault.un=test
  • vault.pw (Environment Variable VAULT_PW) - The Password/Secret Id for

authenticating with Vault

vault.pw=test

In addition, the Vault UN and PW can be loaded from files on disk, ‘vault_un.txt’ and ‘vault_pw.txt’. This is the recommended method to set authentication info in CI/CD processes within an application container.

Secure Properties

Secure Properties can be loaded from a properties file for development purposes, but in a Production scenario should always be loaded from a Vault instance. Once Crazy Ivan is connected to a Vault instance, the following properties can be loaded:

  • CONSUL_SSL_CERT - The SSL Certificate to use when communicating with Consul
  • CONSUL_ACL_TOKEN - The ACL Token to use when communicating with Consul
  • NEO4J_AUTH_UN - The Username to authenticate with discovered Neo4j instances
  • NEO4J_AUTH_PW - The Password to authenticate with discovered Neo4j instances
  • {cluster-name}_TRANSACTION_SECURITY_AUTH_USER - The username which will authenticate with Crazy Ivan over HTTP(s)
  • {cluster-name}_TRANSACTION_SECURITY_AUTH_PASSWORD - The password which will authenticate with Crazy Ivan over HTTP(s)
  • {cluster-name}_TRANSACTION_SECURITY_HASH_PASSWORD - The password for the hashing algorithm used to hash the password prior to storage.
  • {cluster-name}_EVENT_SECURITY_OUT_AES_KEY - The key for the AES-256 encryption used for sending UDP messages.
  • {cluster-name}_EVENT_SECURITY_OUT_AES_SALT - The salt used for the AES-256 encryption used for sending UDP messages.
  • {cluster-name}_EVENT_SECURITY_IN_AES_KEY - The key for the AES-256 encryption used for receiving UDP messages.
  • {cluster-name}_EVENT_SECURITY_IN_AES_SALT - The salt used for the AES-256 encryption used for receiving UDP messages.

Secure properties can be loaded from any configuration source, but when loaded from Vault they should be present at the default path (‘secret/’) in the v2 KV Store.

Consul

Consul Address - Starts Crazy Ivan against a Consul instance. Specified by either the consul command line argument or the AOSSL_CONSUL_ADDRESS environment variable.

./crazy_ivan consul=http://127.0.0.1:8500

We may also include the arguments:

  • consul.cert (Environment Variable AOSSL_CONSUL_SSL_CERT) - The location of the

SSL Certificate to use when communicating with Consul. You may also leave this blank to enable SSL encryption without providing a client certificate.

consul.cert=
  • consul.token (Environment Variable AOSSL_CONSUL_ACL_TOKEN) - The ACL Token to use when communicating with Consul

This will enable property retrieval from Consul KV Store & registering with Consul on start up.

The Consul ACL Token can alternatively be generated from the Consul Secret Store in Vault.

  • consul.token.role - The role configured in Vault to use to generate the Consul ACL Token.
consul.token.role=consul-role

Properties File

Properties File - Starts Crazy Ivan against a Properties File. Specified by either the props command line argument or the AOSSL_PROPS_FILE environment variable. For example:

./crazy_ivan props=app.properties

If no properties file is specified, Crazy Ivan will look for one named app.properties in both the current working folder, and in /etc/ivan/.

The consul address can also be specified within the properties file, with the key consul.

HTTPS Setup

SSL Context Configuration is performed on startup, if enabled. If the following properties are set, then SSL Certs for Crazy Ivan can be generated dynamically from Vault:

  • transaction.security.ssl.ca.vault.active - ‘true’ or ‘false’
transaction.security.ssl.ca.vault.active=true
  • transaction.security.ssl.ca.vault.role_name - the name of the role to use to generate the SSL Cert
transaction.security.ssl.ca.vault.role_name=test-role
  • transaction.security.ssl.ca.vault.common_name - The Common-Name to use on the Certificate
transaction.security.ssl.ca.vault.common_name=local

Otherwise, SSL Certificate Generation can be configured from a file in the current working directory called ‘ssl.properties’.

HTTPS must be enabled with the following parameter:

  • transaction.security.ssl.enabled - ‘true’ or ‘false’
transaction.security.ssl.enabled=true

Neo4j Connection

  • Neo4j - A full connection string may be supplied here.
neo4j=neo4j://username:password@localhost:7687

In Production Scenarios it is recommended to use Neo4j Discovery. If it is set to true, then Crazy Ivan will use Consul to find a Neo4j instance, and will dynamically find new instances when it encounters many consecutive failures. This is controlled by the property:

  • neo4j.discover - ‘true’ or ‘false’.
neo4j.discover=true

When enabled, you will want to utilize the secure properties ‘NEO4J_AUTH_UN’ and ‘NEO4J_AUTH_PW’ in Vault, in order to store the authorization info for Neo4j securely.

Other Values

There are a number of other options that Crazy Ivan can be provided on startup. Below is an overview of the remaining properties:

  • Log File - Path on disk to write logs to
log.file=ivan.log
  • Log Level - Debug, Info, Warning, Error
log.level=Debug
  • HTTP host to register with Consul
http.host=127.0.0.1
  • HTTP Port
http.port=8766
  • UDP Port
udp.port=8764
  • Enable Event (UDP) Encryption
event.security.aes.enabled=false
  • Transaction ID’s active or inactive. If active, Crazy Ivan will ensure a Transaction Id is stamped on each message.
transaction.id.stamp=True
  • Format for transactions (HTTP traffic). Currently only json is supported.
transaction.format=json
  • Method for streaming events. Currently only udp is supported.
event.stream.method=udp
  • Format for streaming events. Currently only json is supported
event.format=json

Go Home