The Setup File

Template
Location
Setup field reference
Syntax

The setup file (edg-setup.properties) is the main EDG configuration file. It defines low-level configuration options such as data storage, workspace directory location and authentication method.

Higher-level options are set at runtime on the Server Administration Page.

Note

In TopBraid EDG Studio, the setup file is optional, and reasonable default values are assumed.

The file uses a simple fieldName = value syntax. See Syntax for details.

Template 

An example setup file that can serve as a template is included with the EDG server download.

It can also be downloaded from the EDG application after it has been started, by appending assets/edg-setup/edg-setup.properties to the URL where EDG has been deployed (often https://your-server/edg/, or http://localhost:8083/ for EDG Studio).

Location 

Before EDG installation, the setup file must be placed in a location that is readable by Tomcat.

EDG checks the Java system property edg.setup to locate the setup file. The value must be the full absolute path and filename.

System properties can be set in various ways. The recommended way is to append to Tomcat’s CATALINA_OPTS environment variable. See Configuring CATALINA_OPTS for more information.

Note

In TopBraid EDG Studio, the setup file location is given on the command line with the -s or --setup-file option. The path may be relative. For example:

./edg -s configuration2.properties

Setup field reference 

This section lists all available setup fields, grouped thematically.

General 

workspacePath

The location of the workspace, a directory that houses all the data for EDG. The directory must be persistent. Tomcat must have read and write access.

Syntax: Directory path
Default: -
Example: /var/lib/tomcat10/Workspace

licenseFile

The path to the TopQuadrant-provided product license file. EDG will not work without a valid license file.

If this field is specified in the setup file and the license file needs to to be updated later, then this must be done in the file system and a server restart is required.

If this field is not specified in the setup file, then EDG will ask for a license file to be uploaded when first running, and an administrator may later replace the license file through the Product Registration Admin Page.

Syntax: File path
Default: -
Example: ./edg-license.lic

Authentication 

endUserAuthMethod

Defines how users authenticate with EDG. See Authentication Overview for more information, and Authentication Methods for details on the available methods.

Note

The default setting cookie is intended for local development and testing. It should never be used on a server.

Syntax: One of form, basic, saml2, oidc, cookie
Default: cookie (cookie authentication)

apiAuthMethods

Defines additional authentication methods for API clients and other integrations that connect to EDG APIs. See Authentication Overview for more information, and Authentication Methods for details on the available methods.

Syntax: Comma-separated list of basic, oauth2
Default: -

authMethod (deprecated)

Enables one of the Tomcat-based authentication methods. Cannot be combined with endUserAuthMethod or apiAuthMethods.

Syntax: One of form, basic
Default: -

usersFile

The location and name of the users.yaml file which defines user accounts and security roles for some (non-SSO) authentication methods.

Syntax: File path
Default: ./users.yaml

ldapConfigFile

The location and name of the cofiguration file for LDAP Authentication. If this file exists, LDAP authentication will be used.

Syntax: File path
Default: ./ldap.yaml

saml2ConfigFile

The location and name of the cofiguration file for SAML Authentication.

Syntax: File path
Default: ./saml2.yaml

oidcConfigFile

The location and name of the cofiguration file for Authentication with OpenID Connect (OIDC).

Syntax: File path
Default: ./oidc.yaml

oauth2ConfigFile

The location and name of the cofiguration file for Authentication with OAuth 2.0.

Syntax: File path
Default: ./oauth2.yaml

authRealm

Sets the realm name for HTTP Basic Authentication. The option is provided for completeness and has little relevance in practice.

Default: TopBraid EDG

Authorization 

securityRoles
adminSecurityRoles
powerUserSecurityRoles
managerSecurityRoles
explorerSecurityRoles
serviceAccountSecurityRoles

These fields define security roles.

The securityRoles field defines one or more security roles without giving them any particular permission.

The other fields define security roles and also add them to a particular rights group.

Warning

Any EDG setup requires an administrator role. If no adminSecurityRoles are defined in the setup file, then ALL users will have administrator rights until an administrator role is manually selected (and the ANY_ROLE wildcard removed from AdministratorGroup) on the Rights Management Admin Page.

Note

Removing a previously defined security role from one of the xxxSecurityRoles fields is not sufficient to remove it from the application. It must also be manually removed on the Rights Management Admin Page.
Syntax: Comma-separated list of names (details)

Default: -
Example:
adminSecurityRoles = admin
powerUserSecurityRoles = poweruser
managerSecurityRoles = manager
explorerSecurityRoles = explorer
serviceAccountSecurityRoles = api
securityRoles = user

Lockout Feature 

lockoutFailureCount: Sets the number of consecutive failed login attempts allowed before an account will be temporarily locked. Setting this to a number less than 1 will disable the Lockout feature (not recommended). The default is 5.
lockoutDuration: Sets the length of time (in seconds) an account should be locked after too many failed attempts. The default is 300 (5 minutes).
lockoutCacheSize: EDG keeps track of (at most) this many accounts that have had login failures. The default is 1000.
lockoutCacheRemovalWarningDuration: If an account is removed from the cache due to the cache size limit being reached, a warning will be logged if the entry has been in the cache less than this many seconds. The default is 3600 (1 hour).

Secure Storage 

vaultType

Selects the type of Secure Storage. This is the storage for passwords and other credentials that administrators or users enter into EDG.

With LocalFile, secrets will be stored encrypted in a local file.
With Hashicorp, EDG integrates with Hashicorp Vault

See the following subsections for setup fields specific to each Secure Storage type.

Syntax: One of LocalFile or Hashicorp
Default: LocalFile

vault<...>

This special syntax adds an entry to the Secure Storage without going through the manual UI of the Password Management Admin Page.

Secrets manually entered in the UI take precedence over those provided with the vault<...> syntax.

Secure Storage entries consist of:

a resource (usually a URL),
an optional username,
an optional scope which identifies an asset collection that the secret is associated with,
and the secret itself (usually a password or other credential).

The characters : and = occurring in resource, username or scope must be escaped as \: and \=.

To avoid storing secrets in plain text in the setup file, see Reading values from files or environment variables.

Syntax:

vault<resource> = secret
vault<username><resource> = secret
vault<scope>/<username><resource> = secret

Example:

vault<edg><jdbc\:mysql\://db1.example.com/sc_staging> = 5J;5Jz68/1}D
vault<edg><jdbc\:mysql\://db1.example.com/sc_prod> = ${env:SC_PROD_DB_PASSWORD}

Secure Storage in local file 

Setup fields for vaultType = LocalFile. With this type of Secure Storage, passwords and other credentials are stored encrypted in a local file.

vaultPath

The path to the file where encrypted passwords and other credentials are stored. Tomcat must have read and write access.

If not specified, the vault file is stored inside the EDG webapp directory.

Syntax: File path
Default: -
Example: ./vault.properties

vaultPassword

A master password used to encrypt and decrypt the vault file.

Warning

It is strongly recommended to store this value in a secure location outside the setup file, such as environment variable, or a file on an encrypted volume. See Reading values from files or environment variables. EDG will log a warning if this value is stored in plain text.

Default: -

vaultEncryption

The encryption algorithm used for the vault file.

Syntax: A valid Java cipher algorithm names
Default: PBEWithHMACSHA512AndAES_256

Secure Storage in Hashicorp Vault 

Setup fields for vaultType = Hashicorp. With this type of Secure Storage, EDG integrates with Hashicorp Vault to store passwords and other credentials. See EDG Integration with Hashicorp Vault for more information.

hashicorpVaultURL

The location of the Hashicorp Vault server. Must start with https:// to be secure.

Syntax: URL
Default: -
Example: http://localhost:8200

hashicorpVaultDataPath

The data path used within Vault to store secrets for this EDG instance. It corresponds to a path from a policy configured in Vault.

Syntax: Vault path syntax
Default: -
Example: /kv/data/edg/secure-storage/

hashicorpVaultMetadataPath

The metadata path used to list secrets in the data path. It is usually the data path with data replaced by metadata. It corresponds to a path from a policy configured in Vault.

Syntax: Vault path syntax
Default: -
Example: /kv/metadata/edg/secure-storage/

hashicorpVaultAuthMethod

Selects how EDG autenticates with Hashicorp Vault. AppRole and TLS certificates are supported. Refer to the Hashicorp Vault documentation for details.

Syntax: AppRole or TLS
Default: AppRole

hashicorpVaultRoleId

For hashicorpVaultAuthMethod = AppRole: The role-id configured in Vault for EDG.

Syntax: Usually a UUID
Default: -

hashicorpVaultSecretId

The secret-id for the AppRole given in hashicorpVaultRoleId.

Warning

It is strongly recommended to store this value in a secure location outside the setup file, such as environment variable, or a file on an encrypted volume. See Reading values from files or environment variables. EDG will log a warning if this value is stored in plain text.

Syntax: Usually a UUID
Default: -

hashicorpVaultCertFile

For hashicorpVaultAuthMethod = TLS: A trusted certificate file that has been configured in Vault for EDG.

Syntax: File path
Default: -
Example: ./cert.pem

hashicorpVaultCertFile

For hashicorpVaultAuthMethod = TLS: The private key file for the trusted certificate.

Syntax: File path
Default: -
Example: ./key.pem

Data Platform 

Setup fields for TopBraid Data Platform, a high-availability solution for EDG servers.

databaseType

Selects the storage engine to use for EDG. See Database Type: Application data storage for more information.

The default engine (SharedTDB) requires no further setup.

Syntax: DataPlatform or SharedTDB
Default: SharedTDB

dpServerURL

URL of the Data Coordinator server for Data Platform.

Specifying this without setting databaseType to DataPlatform allows legacy setups where selected graphs are on Data Platform but the system graphs are not.

Syntax: URL
Default: -
Example: http://dc.example.com:1066/

isPrimaryNode

Exactly one node in a Data Platform cluster must have this set to true.

Syntax: true/false
Default: false

dpZone

Directory in the workspace where Data Platform keeps local state. Do not change this unless instructed by TopQuadrant Support.

Syntax: Directory path, relative to workspacePath
Default: Zone

Security hardening 

For added security, sensitive configuration settings such as passwords and other secrets should be stored in a secure location outside the setup file. See Reading values from files or environment variables. EDG will log a warning if these values are stored in plain text.

Also, the following security settings further lock down the sandbox around various features.

Warning

On production systems, these settings should be enabled unless a feature is required for customisations/integrations.

disableADSSQL

Disable ADS SQL features such as SQL.query()

Syntax: true/false
Default: false

disableADSHTTP

Disable ADS IO.http function

Syntax: true/false
Default: false

disableExternalFiles

Disable access to files outside of the workspace

Syntax: true/false
Default: false

disableProjectUpload

Disable upload of customization projects via the Upload Project Admin Page

Syntax: true/false
Default: false

disableSPARQLSERVICE

Disable the SERVICE keyword in SPARQL queries. The keyword allows sub-queries to external SPARQL endpoints.

Syntax: true/false
Default: false

disableSWPHTTP

Disable HTTP access from SWP scripts

Syntax: true/false
Default: false

disableCorpusUrlList

Disable the URL list corpus connector

Syntax: true/false
Default: false

disableRemoteData

Disable support for remote data sources

Syntax: true/false
Default: false

disableRemoteEditing

Disable editing of remote data sources. Only meaningful if disableRemoteData is not set to true.

Syntax: true/false
Default: false

Miscellaneous 

sessionTimeout

Session timeout in minutes. Users will have to log in again after this period of inactivity.

Syntax: Integer number
Default: 90

repositoriesProjectName (deprecated)

Changes the name of Repositories directory within the workspace to accommodate legacy workspaces (e.g., EVNProjects for old EVN workspaces)

Default: Repositories

publicServices

Configure public services

Syntax: Space-separated list of URLs relative the the application root
Default: -
Example: service/myAssetCollection/ex/SomeService service/other/ex/OtherService

Syntax 

The setup file uses the properties file format. In summary:

An entry consists of a single line with a field name and a value:
```
fieldName = value
```
Comments: Lines starting with #, and empty lines, are ignored
Values may span multiple lines if the end in a backslash character \. Whitespace at the beginning of subsequent lines will be ignored:
```
fieldName = This is a \
            multiline value
```
Backslash characters, such as in Windows file paths, must be doubled:
```
workspacePath = C:\\EDG\\workspace
```

If the same field name occurs multiple times, only the last value will be used:

fieldName = First value will be ignored
fieldName = Last value will be used

UTF-8 character encoding is used for international characters

Directories and file names as values 

Some fields expect file paths as values. These rules apply:

Relative paths are interpreted relative to the setup file location. For example, the value users.yaml references a file called users.yaml in the same directory as the setup file.
On Windows, either a single forward slash / or a double backslash \\ must be used as directory separator.

Comma-separated values 

Some fields expect multiple values separated by commas. In these fields, each value can be optionally enclosed by double quotes. This is necessary when a value itself contains commas. Any double quotes inside a quoted value must be replaced by two double quotes.

For example, this field has three values:

exampleField = unquoted value, "x, y and z","2'4"" wide, 4' deep"``

unquoted value
x, y and z
2'4" wide, 4' deep

Reading values from files or environment variables 

Environment variables: ${env:XXX}: When used in a value, the syntax ${env:XXX} will be replaced with the environment variable $XXX.
File contents: ${file:xxx.txt}: When used in a value, the syntax ${file:xxx.txt} will be replaced with the contents of the file xxx.txt. The path can be absolute or relative. If relative, it is interpreted relative to the setup file’s location. Ideally, this file will be on an encrypted volume for additional security.

In this example, the Secure Storage password is read from an environment variable $EDG_VAULT_PW to avoid having it in clear text in the setup file:

vaultPassword = ${env:EDG_VAULT_PW}