Configuration Reference

FusionAuth configuration is managed in a number of ways, depending on the item being configured. The majority of application level settings are managed in the UI or the APIs. Other items such as memory, ports, and other system configuration options are managed through a lookup process. This process uses environment variables, Java system properties, and the key value pairs in the fusionauth.properties file.

Lookup process

Available Since Version 1.19.0.

The lookup process was introduced in version 1.19.0 and allows any configuration option to be specified in one of three ways: environment variables, Java system properties, or in the fusionauth.properties configuration file. Here is the process for looking up configuration options (NOTE: that the name of the configuration options are listed below):

Check if an environment variable is defined with the configuration option name
Check if an environment variable is defined with the configuration option name translated by upper-casing it and replacing periods and dashes with underscores
Check if there is a Java system property with the configuration option name
Check if the configuration option is defined in the fusionauth.properties configuration file

To better illustrate how the lookup works, let’s take one of the common configuration options for FusionAuth and walk through each step. We’ll use database.url which defines the JDBC URL where the database is located. Here’s how the lookup will work:

Check for an environment variable named database.url
Check for an environment variable named DATABASE_URL
Check for a Java System property defined like this: -Ddatabase.url=foo
Check if there is a line in fusionauth.properties like this: database.url=foo

This lookup order is consistent for every configuration option listed below.

Configuration file

Assuming you installed in the default locations, the configuration file may be found in the following directory. If you have installed in an alternate location the path to this file will be different.

Linux and macOS

/usr/local/fusionauth/config/fusionauth.properties

Windows

\fusionauth\config\fusionauth.properties

Options

The following table contains all of the configuration options that FusionAuth uses. For your convenience, you may select the type of configuration you plan to use and the names will be updated to correspond to your preference.

Display configuration values in format:

database.connection-healthcheck-99percent-ms [Integer] defaults to 250

This ensures that the average time it takes FusionAuth to get a database connection from the connection pool does not go above the specified value. If this value is exceeded, then the /api/status API will return a non-200 status code. This usually means that the database is under heavy load or is having issues.

database.connection-timeout [Integer] defaults to 2,000

The number of milliseconds that FusionAuth will attempt to connect to the database before failing.

database.idle-timeout [Integer] defaults to 120,000

The number of milliseconds that FusionAuth will leave an idle database connection in its connection pool before recreating it.

database.max-lifetime [Integer] defaults to 240,000

The number of milliseconds that FusionAuth will allow a database connection to live before it is destroyed and recreated.

database.minimum-idle [Integer] defaults to unset

The minimum number of idle connections that FusionAuth will keep in the connection pool. This ensures that the pool always has that number of connections. By default, this is not set, so the connection pool will be a fixed size of the value of the maximum-pool-size configuration option.

database.maximum-pool-size [Integer] defaults to 10

The maximum number of database connections that FusionAuth will keep in the connection pool.

database.mysql.enforce-utf8mb4 [String] defaults to true

When set to true and using MySQL, a 4 byte UTF compatible character set configuration is enforced at startup.

If this validation is not desired or not it is not possible to modify your MySQL configuration to satisfy the validation, disable this check by setting this value to false. If this is false, any attempt to store a 4 byte unicode character will cause the INSERT or UPDATE request to fail. The initial MySQL UTF-8 implementation only supported up to characters up to 3 bytes in length; utf8mb4 extends this to 4 byte characters.

database.password [String]

The password that FusionAuth will use to connect to the database. If you are using Silent Mode or Setup Wizard, then this password might be used when the database.user is automatically created for you, depending on your database server and configuration options.

Keep in mind, that this password must be secure if you let FusionAuth create the database user for you.

database.root.password [String]

The password that FusionAuth will use to connect to the database server as part of Silent Mode or Setup Wizard if it cannot connect using the database.username and database.password values. This should be the password for a user that has superuser privileges to the database. For example, many PostgreSQL servers will provide you with a password for the postgres user. Similarly, MySQL servers sometimes leave the password blank for the mysql user.

This configuration option allows FusionAuth to create its own database and schema and also create the user specified by database.username with the password specified by database.password. This setting is useful for Docker and other containers where FusionAuth needs to bootstrap itself without any user interaction.

database.root.username [String]

The password that FusionAuth will use to connect to the database server as part of Silent Mode or Setup Wizard if it cannot connect using the database.username and database.password values. This should be the username that has superuser privileges to the database. For example, many PostgreSQL servers use the username of postgres for the superuser account. Similarly, MySQL servers often use the username mysql for the superuser account.

Deprecated names:

database.root.user

database.url [String]

The JDBC URL that FusionAuth can use to connect to the configured database.

Consider the examples below and review each part of the URL string as you may need to adjust it for your configuration.

jdbc:postgresql://db:5432/fusionauth

Database type: PostgreSQL
Database host: db
Database port: 5432
Database name: fusionauth

In the example above, notice we have specified the PostgreSQL jdbc type, a host of db, a port 5432 and a database name of fusionauth. The host is the service name of the database configuration, in this case it is named db.

jdbc:mysql://db:3306/fusionauth?serverTimezone=UTC

Database type: MySQL
Database host: db
Database port: 3306
Database name: fusionauth
Server timezone: UTC

In the example above, notice we have specified the MySQL jdbc type, a host of db, a port 3306, a database name of fusionauth, and the server timezone UTC.

If you are using MySQL, you must include the serverTimezone=UTC parameter in the URL. The ? character is the same as a standard URL parameter, so if you have additional parameters, you should only have a single ? and parameters should be separated by &.

You may also wish to connect to a remote database, in that case you will provide your own JDBC string URL specifying the remote database host and port.

database.username [String]

The database user that FusionAuth will use to connect to the database. If you are using Silent Mode or Setup Wizard, then this user might be automatically created for you, depending on your database server and configuration options. If this user is created as part of Silent Mode or Setup Wizard, it will also be the owner of the database and schema for FusionAuth.

Deprecated names:

database.user

fusionauth-app.additional-java-args [String]

Any additional arguments that you want to pass to the Java VM where this service will run.

Deprecated names:

fusionauth.additional-java-args

fusionauth-app.ajp.port [Integer] defaults to 9019

The port number that FusionAuth will use to accept AJP requests.

Deprecated names:

fusionauth-app.ajp-port

fusionauth-app.http.cookie-same-site-policy [String] Available since 1.16.0

The value to use in the Same-Site cookie attribute for cookies set by FusionAuth. Possible values are:

None
Lax
Strict

Deprecated names:

fusionauth.cookie.same.site.policy
fusionauth-app.cookie-same-site-policy
fusionauth-app.http.cookie.same-site-policy

fusionauth-app.http.max-header-size [Integer] Defaults to 10240 Available since 1.17.0

The maximum size of the HTTP header in bytes.

Deprecated names:

fusionauth.http.max.header-size
fusionauth-app.http-max-header-size

fusionauth-app.http.port [Integer] defaults to 9011

The port number that FusionAuth will use to accept HTTP requests.

Deprecated names:

fusionauth-app.http-port

fusionauth-app.https.port [Integer] defaults to 9013

The port number that FusionAuth will use to accept HTTPS requests.

Deprecated names:

fusionauth-app.https-port

fusionauth-app.kickstart.file [String]

The path to the FusionAuth Kickstart JSON file.

Deprecated environment variable names:

FUSIONAUTH_KICKSTART

fusionauth-app.management.port [Integer] defaults to 9010

The port number used for internal Tomcat administration.

Deprecated names:

fusionauth-app.management-port

fusionauth-app.memory [String] defaults to 512M

The amount of memory to allocate to Java VM where this service will run. Use the M or G suffix to denote megabytes and gigabytes respectively.

For example, 512M will allocate 512 Megabytes to the Java VM and 1G will allocate 1 gigabyte. This value must be an integer, for example use 1536M to allocate 1.5 gigabytes.

Deprecated names:

fusionauth.memory

fusionauth-app.reindex-batch-size [Integer] defaults to 1000

The number of users to process per batch for a reindex operation.

fusionauth-app.reindex-thread-count [Integer] defaults to 2

The number of threads to process batches of users on for a reindex operation.

fusionauth-app.runtime-mode [String] defaults to development Available since 1.16.0

The FusionAuth runtime mode. The runtime mode causes some features to be modified based upon this configuration.

The possible values are:

development
production

When in the development runtime mode, maintenance mode will interactively assist you configuring the database and connecting to Elasticsearch if configured. Once you move FusionAuth into production, it is recommended that you modify the runtime mode to production. When in production runtime mode maintenance mode will no longer be available to you which means you can be certain that your end users will not find themselves on the database upgrade panel during an Upgrade. When in production mode you will either need to leverage Silent Mode to automatically apply database migrations or you will need to apply the database migrations yourself (either by hand or via a script of some sort).

Deprecated names:

fusionauth.runtime-mode

fusionauth-app.silent-mode [Boolean] defaults to false Available since 1.19.0

Determines if FusionAuth should use Silent Mode during the startup process. Previous to version 1.19.0, Silent Mode was only available when the fusionauth-app.runtime-mode was development. This has been changed so that FusionAuth can now automatically apply database migrations during the startup process.

fusionauth-app.url [String] Available since 1.4.0

The FusionAuth App URL that is used to communicate with other FusionAuth nodes. This value is defaulted if not specified to use a localhost address or a site local if available. Unless you have multiple FusionAuth nodes the generated value should always work. You may need to manually specify this value if you have multiple FusionAuth nodes and the only way the nodes can communicate is on a public network.

fusionauth-app.user-search-index.name [String] defaults to fusionauth_user Available since 1.22.0

The name of the Elasticsearch index that will be created by FusionAuth to index users.

fusionauth-search.additional-java-args [String]

Any additional arguments that you want to pass to the Java VM where this service will run.

Deprecated names:

fusionauthsearch.additional.java.args

fusionauth-search.data-directory [String (Path)]

The location on disk where FusionAuth Search will store its data. This value is defaulted if not specified and generally should not be modified.

Deprecated names:

fusionauthsearch.data.directory

fusionauth-search.hosts [String] defaults to _local_

This parameter indicates which address or network interfaces to bind during service startup. The default value will cause the service to bind any loopback address on the system such as 127.0.0.1.

This default value is sufficient for running FusionAuth and the Search Engine on the same server. If you run FusionAuth Search on a separate system than FusionAuth App you will need to modify this value. You may specify a single hostname or IP address or one of the special values in any combination.

Special values include:

_[networkInterface]_ - Addresses of a network interface, for example _en0_
_local_ - Any loopback address on the system, for example 127.0.0.1
_site_ - Any site-local addresses on the system, for example 192.168.0.1.
_global_ - Any globally-scoped addresses on the system, for example 8.8.8.8.

The following is an example to bind to localhost as well as any site local addresses on the system such at 192.168.1.42.

fusionauth-search.hosts=_local_,_site_

Deprecated names:

fusionauthsearch.hosts

fusionauth-search.http.port [Integer] defaults to 9021

The port number that the Search Engine will use to accept HTTP requests. This value is also utilized by FusionAuth to make HTTP requests to the FusionAuth Search.

Deprecated names:

fusionauth-search.http-port

fusionauth-search.memory [String (Memory)] defaults to 512M

The amount of memory to allocate to Java VM where this service will run. Use the M or G suffix to denote megabytes and gigabytes respectively.

For example, 512M will allocate 512 Megabytes to the Java VM and 1G will allocate 1 gigabyte. This value must be an integer, for example use 1536M to allocate 1.5 gigabytes.

Deprecated names:

fusionauthsearch.memory

fusionauth-search.servers [String] defaults to localhost:9020 No longer used as of 1.16.0

A comma separated list of stand-alone search engine servers that will be used by FusionAuth. The port specified on the server should be the Search Engine Transport port, not the HTTP port.

The following is an example of a configuration for two separate search engines, one running on localhost and the other is on remote system.

fusionauth-search.servers=localhost:9020,search2.example.com:9020

This configuration value is used by the FusionAuth Search and the FusionAuth App services. Even when running FusionAuth App without FusionAuth Search on the same server this configuration value will need to be provided.

fusionauth-search.transport.port [Integer] defaults to 9020

The port that the search engine will use for optimized TCP communications instead of HTTP communications. This port is used internally by the search engine to communicate between clustered nodes.

Deprecated names:

fusionauth-search.transport-port
fusionauthsearch.transport.port

search.servers [String] defaults to http://localhost:9021

A comma separated list of URLs that will be used by FusionAuth to connect to the search engine. The port specified on the URL should be the Search Engine HTTP port. (see fusionauth-search.http-port) It is not recommended to ever run the FusionAuth Search open to the public internet.

The following is an example of a configuration for two separate search engines, one running on localhost and the other is on a remote system.

search.servers=http://localhost:9021,http://search2.example.com:9021

Deprecated names:

fusionauth-app.search-servers

search.sniffer [Boolean] defaults to false Available since 1.19.8

Set to true if you want to use the Elasticsearch sniffer configuration. If you are using a managed Elasticsearch service, or running Elasticsearch inside of a container, you should leave this value set to false.

This configuration can be helpful to allow FusionAuth to use a single connection to localhost and then allow the Elasticsearch REST client to discover all other nodes in the Elasticsearch cluster.

search.type [String] defaults to database Available since 1.16.0

The search engine type. The possible values are:

database
elasticsearch

When configuring the search engine type to elasticsearch, you must configure the search.servers property as well.

Deprecated names:

fusionauth-app.search-engine-type
fusionauth.search.engine
fusionauth.search.engine.type