Logo / Docs

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):

  1. Check if an environment variable is defined with the configuration option name
  2. Check if an environment variable is defined with the configuration option name translated by upper-casing it and replacing periods and dashes with underscores
  3. Check if there is a Java system property with the configuration option name
  4. 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:

  1. Check for an environment variable named database.url
  2. Check for an environment variable named DATABASE_URL
  3. Check for a Java System property defined like this: -Ddatabase.url=foo
  4. 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-msIntegerDefaults 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-timeoutIntegerDefaults to 2,000

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

database.idle-timeoutIntegerDefaults to 120,000

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

database.max-lifetimeIntegerDefaults to 240,000

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

database.minimum-idleIntegerDefaults 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-sizeIntegerDefaults to 10

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

database.mysql.enforce-utf8mb4StringDefaults 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.passwordString

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.passwordString

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.usernameString

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.

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.

Deprecated names:
  • database.root.user
database.urlString

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.

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.usernameString

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-argsString
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.portIntegerDefaults to 9019DEPRECATED

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-policyStringAvailable since 1.16.0DEPRECATED

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.entity-search-index.nameStringDefaults to fusionauth_entityAvailable since 1.22.0

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

fusionauth-app.http-local.portIntegerDefaults to 9012Available 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-sizeIntegerDefaults to 10240Available since 1.17.0DEPRECATED

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 now 64k.
fusionauth-app.http.portIntegerDefaults to 9011

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

Deprecated names:
  • fusionauth-app.http-port
fusionauth-app.https.enabledBooleanDefaults to falseAvailable 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.portIntegerDefaults to 9013

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

Deprecated names:
  • fusionauth-app.https-port
fusionauth-app.https.certificate-fileStringAvailable 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-fileStringAvailable 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.certificateStringAvailable 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.properties

fusionauth-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-keyStringAvailable 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.properties

fusionauth-app.https.private-key=-----BEGIN PRIVATE KEY-----\n\
MIIYnyo8ePdRyOzBExOrJMfUpDnShAoGBAJKYYqYNdtbOsv2INOIxjcDlQa90tb\n\
<snip>
MV1fpQ==\n\
-----END PRIVATE KEY-----\n
fusionauth-app.http.read-timeoutIntegerDefaults to 20,000Available 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.fileString

The path to the FusionAuth Kickstart JSON file.

Deprecated environment variable names:
  • FUSIONAUTH_KICKSTART
fusionauth-app.local-metrics.enabledBooleanDefaults to falseAvailable since 1.46.0

Set to true to allow unauthenticated access to /api/prometheus/metrics and /api/status from localhost. This can be used to allow the scraping of health and metrics data by local collector agents without the need to provide an API key.

fusionauth-app.management.portIntegerDefaults to 9010DEPRECATED

The port number used for internal Tomcat administration.

Deprecated names:
  • fusionauth-app.management-port
Deprecated in version 1.37.0.
fusionauth-app.memoryStringDefaults 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-sizeIntegerDefaults to 1000

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

fusionauth-app.reindex-thread-countIntegerDefaults to 2

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

fusionauth-app.runtime-modeStringDefaults to developmentAvailable 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.search.default-refresh-intervalStringDefaults to 1sAvailable since 1.49.2

The default search index refresh_interval. Bulk operations (bulk user import and reindex) may temporarily relax this value for better performance and then set it back to this value. This value specifies the delay before updated User and Entity data are available to search requests. Must be a valid Elasticsearch Date/Time Interval Value, however setting this variable is not recommended.

fusionauth-app.silent-modeBooleanDefaults to trueAvailable 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.urlStringAvailable 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.nameStringDefaults to fusionauth_userAvailable since 1.22.0

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

fusionauth-search.additional-java-argsString
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-directoryString (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.hostsStringDefaults 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 as 192.168.1.42.

fusionauth-search.hosts=_local_,_site_

Deprecated names:
  • fusionauthsearch.hosts
fusionauth-search.http.portIntegerDefaults 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.memoryString (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.serversStringDefaults to localhost:9020DEPRECATED

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.portIntegerDefaults 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.hostStringAvailable since 1.31.0

The hostname of your HTTP proxy.

This option configures an egress HTTP proxy for any connections FusionAuth makes.

proxy.portIntegerAvailable since 1.31.0

The port number of your HTTP proxy. This value is required when setting proxy.host .

proxy.usernameStringAvailable since 1.31.0

The username used to authenticate. If your proxy does not require authentication you may omit this value.

proxy.passwordStringAvailable since 1.31.0

The password used to authenticate to your HTTP proxy. This value is required when setting proxy.username .

search.serversStringDefaults 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.snifferBooleanDefaults to falseAvailable 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.typeStringDefaults to databaseAvailable 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.