Table of Contents
Configuration Files
...
Configuration options can be specified in a number of different ways. These take precedence in the following order:
Java System properties – set using the -D propertyName=value on the java command line / tomcat launch configuration
webapps/<phixflow>/WEB-INF/classes/local.properties – optional java properties file
webapps/<phixflow>/WEB-INF/classes/phixflow.properties – optional java properties file
Environment variables – using the environment form of the property name as described below
webapps/<phixflow>/WEB-INF/classes/context/server.properties – this contains the default values and should not be modified
Keystore Files
Optionally, secrets, such as database passwords, can be kept encrypted in external secret files. Refer to Configure a Keystore and Aliases for instructions on how to configure this before proceeding with the installation.
Environment Form of Property Names
As operating systems have stricter rules around valid characters in environment variable names, and prefer them to be in upper case, when using environment variables the property name should be converted as follows:
Replace dots (.) with underscores (_)
Remove any dashes (-)
Convert to uppercase
For example, “db.url” would be looked up as “DB_URL” when resolved from environment variables.
Guidelines and Advice for Configuration
The context/server.properties file should never be changed. This is replaced on upgrade.
For a multi-instance environment (e.g. DEV, QA and Prod) it is recommended that a common phixflow.properties file is used on all instances, containing configuration settings that are identical on all environments. The local.properties file is then used for local overrides, such as database url and passwords.
For single instance environments it is recommended to follow the same structure as with multi-instance environments, but just one of either the phixflow.properties or local.properties files can be used to have all the configuration in a single file.
Only properties that have differing values from the default settings in the server.properties should be configured. This makes it easier to review and manage the configuration and ensures that fixes and improvements to the default settings will be applied automatically.
In docker environments it may be beneficial to use environment variables rather than settings in the local.properties file. This allows the same container image to be started as multiple instances with different configurations.
Configuration Properties
| Note |
|---|
Java properties files use the backslash \ as an escape character. When configuring paths on Windows either use forward slashes (e.g. c:/apps/phixflow) or double backslashes (e.g. c:\\apps\\phixflow). Other properties can be referenced within a property value using the syntax ${property} |
...
| name | InstallTimeProperties |
|---|
Installation Specific Properties
These properties are required for installation to succeed and are populated in the database. After installation is complete the values are not used any further.
...
Property
...
Requires Configuration
...
Default Value
...
Explanation
...
install.customer_name
...
Always
...
<none>
...
The customer name as provided with your licence.
...
install.licence_key
...
Always
...
<none>
...
Licence key as provided with your licence.
...
install.user.password
...
Often
...
<autogenerated>
...
install.user.username
...
Often
...
admin
...
Username of the default administrator user created during installation.
...
install.user.email
...
Often
...
<none>
...
Table of Contents
| Table of Contents |
|---|
| minLevel | 1 |
|---|
| maxLevel | 6 |
|---|
| include | |
|---|
| outline | false |
|---|
| indent | |
|---|
| style | none |
|---|
| exclude | Table of Contents |
|---|
| type | list |
|---|
| class | |
|---|
| printable | true |
|---|
|
Configuration Files
| Excerpt |
|---|
|
Configuration options can be specified in a number of different ways. These take precedence in the following order: Java System properties – set using the -D propertyName=value on the java command line / tomcat launch configuration webapps/<phixflow>/WEB-INF/classes/local.properties – optional java properties file webapps/<phixflow>/WEB-INF/classes/phixflow.properties – optional java properties file Environment variables – using the environment form of the property name as described below webapps/<phixflow>/WEB-INF/classes/context/server.properties – this contains the default values and should not be modified
In other words a setting in phixflow.properties takes precedence over a setting for that same property in server.properties a setting in local.properties takes precedence over a setting for that same property in either or both server.properties or phixflow.properties
Keystore FilesOptionally, secrets, such as database passwords, can be kept encrypted in external secret files. Refer to Configure a Keystore and Aliases for instructions on how to configure this before proceeding with the installation. As operating systems have stricter rules around valid characters in environment variable names, and prefer them to be in upper case, when using environment variables the property name should be converted as follows: For example, “db.url” would be looked up as “DB_URL” when resolved from environment variables. Guidelines and Advice for ConfigurationThe context/server.properties file should never be changed. This is replaced on upgrade. For a multi-instance environment (e.g. DEV, QA and Prod) it is recommended that a common phixflow.properties file is used on all instances, containing configuration settings that are identical on all environments. The local.properties file is then used for local overrides, such as database url and passwords. For single instance environments it is recommended that you use only the local.properties file. Only properties that have differing values from the default settings in the server.properties should be configured. This makes it easier to review and manage the configuration and ensures that fixes and improvements to the default settings will be applied automatically. In docker environments it may be beneficial to use environment variables rather than settings in the local.properties file. This allows the same container image to be started as multiple instances with different configurations.
|
Configuration Properties
| Note |
|---|
Java properties files use the backslash \ as an escape character. When configuring paths on Windows either use forward slashes (e.g. c:/apps/phixflow) or double backslashes (e.g. c:\\apps\\phixflow). Other properties can be referenced within a property value using the syntax ${property} |
| Excerpt |
|---|
| name | InstallTimeProperties |
|---|
|
Installation Specific PropertiesThese properties are required for installation to succeed and are populated in the database. After installation is complete the values are not used any further. Database Connection ConfigurationThese are the basic settings to enable connection to the Phixflow database. Property | Requires Configuration | Default Value | Explanation |
|---|
db.url | Always | <none> | The jdbc url of the database including any required parameters.E.g. jdbc:mysql://localhost/phixflow?defaultFetchSize=2000&?allowPublicKeyRetrieval=truejdbc:oracle:thin:@//localhost:1521/pdb.localjdbc:sqlserver://;database=webtrunk;sendStringParametersAsUnicode=falseProperty | Requires Configuration | Default Value | Explanation |
|---|
install.customer_name | Always | <none> | The customer name as provided with your licence. | install.licence_key | Always | <none> | Licence key as provided with your licence. | install.user.password | Often | <autogenerated> | Initial password of the default administrator user created during installation. If no value is configured a password is autogenerated and written to the security.log file.
It is strongly recommended this is changed immediately after installation. | install.user.username | Often | admin | Username of the default administrator user created during installation. | install.user.email | Often | <none> | Email address of the default administrator user created during installation. Can be updated after installation in the User Details screen. | install.user.firstname | Often | admin | First name of the default administrator user created during installation. Can be updated after installation in the User Details screen. | install.user.lastname | Often | admin | Last name of the default administrator user created during installation. Can be updated after installation in the User Details screen. | install.data.base | Often | ${install.application_loc}/data | Base location for the default data directory paths. This will commonly be configured to be “/opt/phixflow/data” | install.userdata.firstnametemp | Often | admin | First name of the default administrator user created during installation. Can be updated after installation in the User Details screen. | install.user.lastname | Often | admin | Last name of the default administrator user created during installation. Can be updated after installation in the User Details screen.Occasionally | ${install.data.base}/temp | Populates an initial value in the System Configuration Temporary File Location | install.data.baseupload | OftenOccasionally | ${install.data.application_locbase}/dataBase location for the default data directory paths. This will commonly be configured to be “/opt/phixflow/data”upload | Populates an initial value in the System Configuration File Upload Directory | install.data.tempimport | Occasionally | ${install.data.base}/tempimport | Populates an initial value in the System Configuration Temporary Import File Location | install.data.uploadexport | Occasionally | ${install.data.base}/uploadexport | Populates an initial value in the System Configuration Export File Upload DirectoryLocation | install.data.importtemplate | Occasionally | ${install.data.base}/importtemplate | Populates an initial value in the System Configuration Import File Template Location | install.data.exportarchive | Occasionally | ${install.data.base}/exportarchive | Populates an initial value in the System Configuration Export File LocationArchive Directory | install.data.templaterestore | Occasionally | ${install.data.base}/templaterestore | Populates an initial value in the System Configuration Template LocationRestore Directory | install.data.archivedriver | Occasionally | ${install.data.base}/archivedriver | Populates an initial value in the System Configuration Archive Data Driver Directory | install.data.restoredownload | Occasionally | ${install.data.base}/restoredownload | Populates an initial value in the System Configuration Restore DirectoryDownload Location | install.data.driverplugin | Occasionally | ${install.data.base}/driverplugin | Populates an initial value in the System Configuration Data Driver DirectoryPlugin Location | install.data.downloadfile | Occasionally | ${install.data.base}/downloadfile | Populates an initial value in the System Configuration Download Location | install.data.plugin | Occasionally | ${install.data.base}/plugin | Populates an initial value in the System Configuration Plugin Location | install.data.file | Occasionally | ${install.data.base}/file | Populates an initial value in the System Configuration File Table Upload Location | install.application_loc | Rarely | <autodetected> | Base application install location, e.g. ZB example missing here | install.pepperKey | Rarely | <none> | Externally defined value for the pepperKey. If not specified and a pepper key isn’t configured in the keystore then a value is autogenerated. | install.phixflow_api_key | Rarely | <none> | Externally defined value for the PhixFlow API credential signing key. If not specified and the API key isn’t configured in the keystore then a value is autogenerated. |
|
| Excerpt |
|---|
|
File Table Upload Location | install.application_loc | Rarely | <autodetected> | Base application install location | install.pepperKey | Rarely | <none> | Externally defined value for the pepperKey. If not specified and a pepper key isn’t configured in the keystore then a value is autogenerated. | install.phixflow_api_key | Rarely | <none> | Externally defined value for the PhixFlow API credential signing key. If not specified and the API key isn’t configured in the keystore then a value is autogenerated. |
|
| Excerpt |
|---|
|
Database Connection ConfigurationThese are the basic settings to enable connection to the Phixflow database. Property | Requires Configuration | Default Value | Explanation |
|---|
db.url | Always | <none> | The jdbc url of the database including any required parameters. For more information on defining the database URL consult your Database Administrator.
Example URLs MySQL jdbc:mysql://localhost/phixflow?defaultFetchSize=2000&allowPublicKeyRetrieval=true
Note the allowPublicKeyRetrieval parameter may be required depending on your setup
Oracle jdbc:oracle:thin:@//localhost:1521/pdb.local
SQL Server jdbc:sqlserver://;database=webtrunk;sendStringParametersAsUnicode=false;encrypt=false
MS SQL Server JDBC driver version 12.6.1 onwards, defaults to using an encrypted connection which may require additional parameters to be added to the URL. If encryption is not required, add 'encrypt=false' to the URL. See https://learn.microsoft.com/en-us/sql/connect/jdbc/microsoft-jdbc-driver-for-sql-server?view=sql-server-ver16 | phixflow-database-user | Often | <none> | Default key name containing the database username. May This can also be stored in the keystore. | phixflow-database-password | Often | <none> | Default key name containing the database password. May This can also be stored in the keystore. |
|
...
| Excerpt |
|---|
|
Login - Saml ConfigurationPhixFlow supports multiple modes of supporting authentication users. Users can be authenticated either with local credentials, native active directory based credentials, or using SAML to authenticate with active directory or other services, such as Okta. Property | Requires Configuration | Default Value | Explanation |
|---|
login.saml.enabled=false | Often | false | Configures whether SAML login is enabled | login.saml.key= <none> | Often | <none> | Configures the identity provider's entity id . | login.saml.attribute.domain= <none> | Often | <none> | Configures the domain of the saml users. | login.saml.label=Single Sign In | Rarely | Single Sign In | The label to display | login.saml.attributeMap=authenticationOnly | Often | authenticationOnly | Configures the integration method. authenticationOnly - SAML used for authentication but PhixFlow manages user details and permissions. okta - configured to support Okta based authentication and details. userDetails - allows configuration of authentication and user details to be provided by saml. | login.saml.keystore.file | Often | classpath:keystore/samlKeystore.jks | Configures the location of the saml keystore | login.saml.keystore.password | Often | <none> | Configures the password to the saml keystore. | login.saml.keystore.key.password | Often | <none> | Configures the password to the secret in the saml keystore | login.saml.keystore.key.alias | Rarely | samlKey | Configures the alias of the secret stored in the saml keystore | login.saml.url.host | Often | localhost | Configures the externally resolvable hostname of the PhixFlow server. If behind a reverse proxy this will be the proxy’s hostname. | login.saml.url.port | Occasionally | 443 | Configures the port of the PhixFlow server, or that of the reverse proxy if it is being used. | login.saml.url.includePort | Rarely | false | Whether the port should be included in the generated url. | login.saml.url.path | Occasionally | /phixflow | Path that the webapp is installed under. If behind a reverse proxy this should be the path that the proxy forwardsthe path that the proxy forwards. Make sure that you do not precede the path with a /, i.e. it should be the name of the webapp only, as in the example. | login.saml.metadata.entityId | Rarely | https://${login.saml.url.host}/${login.saml.url.path} | The value that globally identifies the PhixFlow instance. | login.saml.metadata.entityBaseUrl | Rarely | https://${login.saml.url.host}/${login.saml.url.path} | The public facing URL of the PhixFlow instance. | login.saml.metadata.file | Often | file:/opt/phixflow/data/saml-metadata/idp-metadata.xml | Path to the Identity Provider Metadata file. | login.saml.metadata.trustCheck | Rarely | true | Whether to validate incoming signatures. | login.saml.attribute.username | Occasionally | nameid | Used with the authenticationOnly and userDetails attribute map to define the appropriate mapping from the incoming metadata. | login.saml.attribute.fullname | Occasionally | displayname | Used with the userDetails attribute map to define the appropriate mapping from the incoming metadata. | login.saml.attribute.firstname | Occasionally | givenname | Used with the userDetails attribute map to define the appropriate mapping from the incoming metadata. | login.saml.attribute.lastname | Occasionally | surname | Used with the userDetails attribute map to define the appropriate mapping from the incoming metadata. | login.saml.attribute.phonenumber | Occasionally | phonenumber | Used with the userDetails attribute map to define the appropriate mapping from the incoming metadata. | login.saml.attribute.company | Occasionally | company | Used with the userDetails attribute map to define the appropriate mapping from the incoming metadata. | login.saml.attribute.department | Occasionally | department | Used with the userDetails attribute map to define the appropriate mapping from the incoming metadata. | login.saml.attribute.email | Occasionally | email | Used with the userDetails attribute map to define the appropriate mapping from the incoming metadata. | login.saml.attribute.groups | Occasionally | group | Used with the userDetails attribute map to define the appropriate mapping from the incoming metadata. | login.saml.attribute.globalLogout | Occasionally | false | Used with the authenticationOnly and userDetails attribute map to determine whether logging out of PhixFlow should also trigger a logout of the identity provider. |
|
| Excerpt |
|---|
|
Login - Active Directory ConfigurationPhixFlow supports multiple modes of supporting authentication users. Users can be authenticated either with local credentials, native active directory based credentials, or using SAML to authenticate with active directory or other services, such as Okta. Property | Requires Configuration | Default Value | Explanation |
|---|
login.activeDirectory.enabled | Often | false | Whether Active Directory integration is enabledActive Directory integration is enabled. | login.activeDirectory.domain | Often | http://example.com | The domain being logged into | login.activeDirectory.url | Often | ldaps://ldap.example.com | Space separated list of domain LDAP servers. | login.activeDirectory.domaindn | Often | http://example.com | The domain being logged into. | login.activeDirectory.url | Often | ldaps://ldap.example.com | Space separated list of domain LDAP serversou=user accounts,dc=example,dc=com | If you have a large AD tree, searches may take some time, and this could lead to slow authentication for users. Therefore it is possible to specify a root DN (Distinguished name) at which PhixFlow will begin searching for the user. The Distinguished Name format is standard and further details can be found on the web. | login.activeDirectory.dntimeout | Rarely | Often | ou=user accounts,dc=example,dc=com | The root distinguished name to search under. | login.activeDirectory.timeout | Rarely | 5000 | Timeout for attempt to authenticate against each server5000 | You can specify a timeout. For each server specified, if the server does not respond within the limit specified by the timeout, it will try the next server. If the last server in the list times out, then the authentication will fail. The timeout is specified in milliseconds. | login.activeDirectory.authenticationOnly | Occasionally | falseWhether | only authentication is used from active directory, with user permissions and details being stored in PhixFlow.If this is true Active Directory is used for authentication when logging in, but not authorisation. This is a mixed user. The user must be configured in PhixFlow before logging in and user groups must be configured for the user. External groups will not be used to determine access rights. |
|
| Excerpt |
|---|
|
Logging Configurationvalid Where a level is required this can be one of level values: OFF, ERROR, WARN, INFO, DEBUG, TRACE, ALL
Property | Requires Configuration | Default Value | Explanation |
|---|
logging.file.directory | Occasionally | logs | The directory logs are written into, relative to the Tomcat root directory. | logging.file.phixflow.base | Occasionally | phixflow | Base name of the standard PhixFlow log file. | logging.file.security.base | Occasionally | security | Base name of the security log file. | logging.stdout.level | Occasionally | OFF | Used to control the minimum log message level permitted to be output to stdout.ZB is “stdout” a typo?standard output. | logging.root.level | Rarely | INFO | Configures the default minimum log level that can be generated. | logging.file.phixflow.main | Rarely | ${logging.file.directory}/${logging.file.phixflow.base}.log | Defines the path and name of the standard PhixFlow log file | logging.file.phixflow.archive | Rarely | ${logging.file.directory}/${logging.file.phixflow.base}.%d{yyyy-MM-dd}.log | Defines the path and name of archived standard PhixFlow log files. | logging.file.security.main | Rarely | ${logging.file.directory}/${logging.file.security.base}.log | Defines the path and name of the security log file. | logging.file.security.archive | Rarely | ${logging.file.directory}/${logging.file.security.base}.%d{yyyy-MM-dd}.log | Defines the path and name of archived security log files. | logging.file.phixflow.level | Rarely | ALL | Used to control the minimum log message level permitted to be output to standard log file. | logging.file.security.level | Rarely | ALL | Used to control the minimum log message level permitted to be output to security log file. |
|