Configuration Reference
Overview
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.
/usr/local/fusionauth/config/fusionauth.properties
\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 isfalse
, any attempt to store a 4 byte unicode character will cause theINSERT
orUPDATE
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.This password must be secure (long, lots of different characters, high entropy, all the characteristics of a good password) 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
anddatabase.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 thepostgres
user. Similarly, MySQL servers sometimes leave the password blank for themysql
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 bydatabase.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
anddatabase.password
values. This should be the username that has superuser privileges to the database. For example, many PostgreSQL servers use the username ofpostgres
for the superuser account. Similarly, MySQL servers often use the usernamemysql
for the superuser account.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 bydatabase.password
. This setting is useful for Docker and other containers where FusionAuth needs to bootstrap itself without any user interaction.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 port5432
and a database name offusionauth
. The host is the service name of the database configuration, in this case it is nameddb
.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 port3306
, a database name offusionauth
, and the server timezoneUTC
.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.
Some MySQL services such as Microsoft Azure may require a specific version of TLS to connect successfully. At the time of writing this note, the MySQL connector will not attempt to utilize TLSv1.2 by default, so when connecting to a service that requires this version you will need to explicitly request this version of TLS on the connection string. For example, appending this
enabledTLSProtocols=TLSv1.2
to the connection string will allow you to successfully connect to an Azure managed MySQL database. See MySQL Connector : Connecting Securely UsingSSL for additional information. -
- 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
Deprecated -
The port number that FusionAuth will use to accept AJP requests.
Deprecated names:
-
fusionauth-app.ajp-port
Deprecated in version
1.37.0
. -
- fusionauth-app.http.cookie-same-site-policy [String] Available since 1.16.0 Deprecated
-
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
Deprecated in version
1.37.0
. -
- fusionauth-app.http-local.port [Integer] Defaults to
9012
Available since 1.36.0 -
The port number that FusionAuth will use to make HTTP requests to itself over localhost. This is port is only used by FusionAuth itself, when making an API call, or using any browser based connections to FusionAuth, please use the port configured by fusionauth-app.http.port.
- fusionauth-app.http.max-header-size [Integer] Defaults to
10240
Available since 1.17.0 Deprecated -
The maximum size of the HTTP header in bytes.
Deprecated names:
-
fusionauth.http.max.header-size
-
fusionauth-app.http-max-header-size
Deprecated in version
1.37.0
, the default value is now64k
. -
- 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.enabled [Boolean] defaults to
false
Available since 1.43.0 -
Set to true to enable the HTTPS server. When enabled, a certificate chain and private key set as either filenames or content as described below.
See fusionauth-app.https.certificate, fusionauth-app.https.certificate-file, fusionauth-app.https.private-key and fusionauth-app.https.private-key-file.
- 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.https.certificate-file [String] Available since 1.43.0
-
The fully-qualified filename containing the certificate chain of the HTTPS server, in PEM format. Ensure that this file contains the server certificate and all intermediate certificates up to, but not including, the root CA certificate.
- fusionauth-app.https.private-key-file [String] Available since 1.43.0
-
The fully-qualified filename containing the private key corresponding to the HTTPS server certificate, in PKCS#8 PEM format. Keys in this format are wrapped inside of a
-----BEGIN PRIVATE KEY-----
block. - fusionauth-app.https.certificate [String] Available since 1.43.0
-
The raw content of the certificate chain of the HTTPS server, in PEM format. Ensure that this contains the server certificate and all intermediate certificates up to, but not including, the root CA certificate.
Note, this property will take precedence over fusionauth-app.https.certificate-file if both values are set.
When specifying this in the
fusionauth.properties
file, ensure each line ends with an escaped newline character (\n
) and a continuation character (\
). For example:fusionauth.propertiesfusionauth-app.https.certificate=-----BEGIN CERTIFICATE-----\n\ MIIF0DCCA7igAwIBAgIIJ4oFgYxh2howDQYJKoZIhvcNAQELBQAwYTELMAkGA1UE\n\ <snip> Ma1apQ==\n\ -----END CERTIFICATE-----\n\ -----BEGIN CERTIFICATE-----\n\ <snip> -----END CERTIFICATE-----\n
- fusionauth-app.https.private-key [String] Available since 1.43.0
-
The raw PKCS#8 PEM-formatted private key content. Keys in this format are wrapped inside of a
-----BEGIN PRIVATE KEY-----
block.Note, this property will take precedence over fusionauth-app.https.private-key-file if both values are set.
When specifying this in the
fusionauth.properties
file, ensure each line ends with an escaped newline character (\n
) and a continuation character (\
). For example:fusionauth.propertiesfusionauth-app.https.private-key=-----BEGIN PRIVATE KEY-----\n\ MIIYnyo8ePdRyOzBExOrJMfUpDnShAoGBAJKYYqYNdtbOsv2INOIxj+cDlQa90tb\n\ <snip> MV1fpQ==\n\ -----END PRIVATE KEY-----\n
- fusionauth-app.http.read-timeout [Integer] defaults to
20,000
Available since 1.37.0 -
The HTTP read timeout in milliseconds that the server will wait to read data from an incoming request.
- 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
Deprecated -
The port number used for internal Tomcat administration.
Deprecated names:
-
fusionauth-app.management-port
Deprecated in version
1.37.0
. -
- fusionauth-app.memory [String] defaults to
512M
-
The amount of memory to allocate to Java VM where this service will run. Use the
M
orG
suffix to denote megabytes and gigabytes respectively.For example,
512M
will allocate 512 Megabytes to the Java VM and1G
will allocate 1 gigabyte. This value must be an integer, for example use1536M
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 toproduction
. When inproduction
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 inproduction
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
true
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 wasdevelopment
. 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 example127.0.0.1
-
_site_
- Any site-local addresses on the system, for example192.168.0.1
. -
_global_
- Any globally-scoped addresses on the system, for example8.8.8.8
.
The following is an example to bind to
localhost
as well as any site local addresses on the system such as192.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
orG
suffix to denote megabytes and gigabytes respectively.For example,
512M
will allocate 512 Megabytes to the Java VM and1G
will allocate 1 gigabyte. This value must be an integer, for example use1536M
to allocate 1.5 gigabytes.Deprecated names:
-
fusionauthsearch.memory
-
- fusionauth-search.servers [String] defaults to
localhost:9020
Deprecated -
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 on a 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.
Deprecated in version
1.16.0
. - 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
-
- proxy.host [String] Available since 1.31.0
-
The hostname of your HTTP proxy.
This option configures an egress HTTP proxy for any connections FusionAuth makes.
- proxy.port [Integer] Available since 1.31.0
-
The port number of your HTTP proxy. This value is required when setting proxy.host.
- proxy.username [String] Available since 1.31.0
-
The username used to authenticate. If your proxy does not require authentication you may omit this value.
- proxy.password [String] Available since 1.31.0
-
The password used to authenticate to your HTTP proxy. This value is required when setting proxy.username.
- 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
The following is an example of a configuration using basic auth for authentication with the search engine.
search.servers=https://user:password@search.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 tofalse
.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
-
Limits
Database configuration is limited to a single host. Using a valid JDBC URL with multiple hosts is not currently supported.
There’s a tracking issue to support more database configuration options.
The format of the database username has some limitations as well. In particular, the username cannot contain an @
symbol. Please review the tracking issue for more information.
Feedback
How helpful was this page?
See a problem?
File an issue in our docs repo
Have a question or comment to share?
Visit the FusionAuth community forum.