.. include:: /includes.rst.txt .. comments - headings # with overline, for parts * with overline, for chapters = for sections - for subsections ^ for subsubsections " for paragraphs * for H5 + for H6 .. _setup_file: The Setup File ============== .. contents:: :local: 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 :ref:`ServerAdministrationPage`. .. note:: In :ref:`topbraid_edg_studio`, the setup file is optional, and reasonable default values are assumed. The file uses a simple ``fieldName = value`` syntax. See :ref:`setup_file_syntax` for details. .. _setup_file_template: 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). .. _setup_file_location: 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 :ref:`catalina_opts` for more information. .. note:: In :ref:`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_file_reference: Setup field reference --------------------- This section lists all available setup fields, grouped thematically. General ^^^^^^^ .. _setup_workspacePath: ``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:** :ref:`Directory path ` * **Default:** - * **Example:** ``/var/lib/tomcat10/Workspace`` .. _setup_licenseFile: ``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 :ref:`ProductRegistrationAdminPage`. * **Syntax:** :ref:`File path ` * **Default:** - * **Example:** ``./edg-license.lic`` .. _setup_file_authentication: Authentication ^^^^^^^^^^^^^^ .. _setup_endUserAuthMethod: ``endUserAuthMethod`` Defines how users authenticate with EDG. See :ref:`authentication_overview` for more information, and :ref:`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`` (:ref:`cookie authentication `) .. _setup_apiAuthMethods: ``apiAuthMethods`` Defines additional authentication methods for API clients and other integrations that connect to :ref:`EDG APIs `. See :ref:`authentication_overview` for more information, and :ref:`authentication_methods` for details on the available methods. * **Syntax:** Comma-separated list of ``basic``, ``oauth2`` * **Default:** - .. _setup_authMethod: ``authMethod`` (deprecated) Enables one of the :ref:`Tomcat-based authentication methods `. Cannot be combined with ``endUserAuthMethod`` or ``apiAuthMethods``. * **Syntax:** One of ``form``, ``basic`` * **Default:** - .. _setup_usersFile: ``usersFile`` The location and name of the :ref:`users.yaml file ` which defines user accounts and security roles for some (non-SSO) authentication methods. * **Syntax:** :ref:`File path ` * **Default:** ``./users.yaml`` .. _setup_ldapConfigFile: ``ldapConfigFile`` The location and name of the cofiguration file for :ref:`ldap_authentication`. If this file exists, LDAP authentication will be used. * **Syntax:** :ref:`File path ` * **Default:** ``./ldap.yaml`` .. _setup_saml2ConfigFile: ``saml2ConfigFile`` The location and name of the cofiguration file for :ref:`saml_authentication`. * **Syntax:** :ref:`File path ` * **Default:** ``./saml2.yaml`` .. _setup_oidcConfigFile: ``oidcConfigFile`` The location and name of the cofiguration file for :ref:`oidc_authentication`. * **Syntax:** :ref:`File path ` * **Default:** ``./oidc.yaml`` .. _setup_oauth2ConfigFile: ``oauth2ConfigFile`` The location and name of the cofiguration file for :ref:`oauth_authentication`. * **Syntax:** :ref:`File path ` * **Default:** ``./oauth2.yaml`` .. _setup_authRealm: ``authRealm`` Sets the realm name for :ref:`HTTP Basic Authentication `. The option is provided for completeness and has little relevance in practice. * **Default:** ``TopBraid EDG`` .. _setup_file_authorization: Authorization ^^^^^^^^^^^^^ .. _setup_securityRoles: | ``securityRoles`` | ``adminSecurityRoles`` | ``powerUserSecurityRoles`` | ``managerSecurityRoles`` | ``explorerSecurityRoles`` | ``serviceAccountSecurityRoles`` These fields define :ref:`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 :ref:`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 :ref:`RightsManagementAdminPage`. .. 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 :ref:`RightsManagementAdminPage`. * **Syntax:** Comma-separated list of names (:ref:`details `) * **Default:** - * **Example:** .. code-block:: properties adminSecurityRoles = admin powerUserSecurityRoles = poweruser managerSecurityRoles = manager explorerSecurityRoles = explorer serviceAccountSecurityRoles = api securityRoles = user Lockout Feature ^^^^^^^^^^^^^^^ .. _setup_lockout: ``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 ^^^^^^^^^^^^^^ .. _setup_vaultType: ``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`` .. _setup_vault: ``vault<...>`` This special syntax **adds an entry to the Secure Storage** without going through the manual UI of the :ref:`PasswordManagementAdminPage`. 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 :ref:`setup_value_replacement`. * **Syntax:** .. code-block:: properties vault = secret vault = secret vault/ = secret * **Example:** .. code-block:: properties vault = 5J;5Jz68/1}D vault = ${env:SC_PROD_DB_PASSWORD} .. _setup_file_secure_storage_local: 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. .. _setup_vaultPath: ``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:** :ref:`File path ` * **Default:** - * **Example:** ``./vault.properties`` .. _setup_vaultPassword: ``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 :ref:`setup_value_replacement`. EDG will log a warning if this value is stored in plain text. **Default:** - .. _setup_vaultEncryption: ``vaultEncryption`` The encryption algorithm used for the vault file. * **Syntax:** A valid `Java cipher algorithm names`_ * **Default:** ``PBEWithHMACSHA512AndAES_256`` .. _setup_file_hashicorp: 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 :ref:`hashicorp` for more information. .. _setup_hashicorpVaultURL: ``hashicorpVaultURL`` The location of the Hashicorp Vault server. Must start with `https://` to be secure. * **Syntax:** URL * **Default:** - * **Example:** ``http://localhost:8200`` .. _setup_hashicorpVaultDataPath: ``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/`` .. _setup_hashicorpVaultMetadataPath: ``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/`` .. _setup_hashicorpVaultAuthMethod: ``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`` .. _setup_hashicorpVaultRoleId: ``hashicorpVaultRoleId`` For ``hashicorpVaultAuthMethod = AppRole``: The ``role-id`` configured in Vault for EDG. * **Syntax:** Usually a UUID * **Default:** - .. _setup_hashicorpVaultSecretId: ``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 :ref:`setup_value_replacement`. EDG will log a warning if this value is stored in plain text. * **Syntax:** Usually a UUID * **Default:** - .. _setup_hashicorpVaultCertFile: ``hashicorpVaultCertFile`` For ``hashicorpVaultAuthMethod = TLS``: A trusted certificate file that has been configured in Vault for EDG. * **Syntax:** :ref:`File path ` * **Default:** - * **Example:** ``./cert.pem`` ``hashicorpVaultCertFile`` For ``hashicorpVaultAuthMethod = TLS``: The private key file for the trusted certificate. * **Syntax:** :ref:`File path ` * **Default:** - * **Example:** ``./key.pem`` Data Platform ^^^^^^^^^^^^^ Setup fields for :ref:`topbraid_data_platform`, a high-availability solution for EDG servers. .. _setup_databaseType: ``databaseType`` Selects the storage engine to use for EDG. See :ref:`database_type_app_data_storage` for more information. The default engine (``SharedTDB``) requires no further setup. * **Syntax:** ``DataPlatform`` or ``SharedTDB`` * **Default:** ``SharedTDB`` .. _setup_dpServerURL: ``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/`` .. _setup_isPrimaryNode: ``isPrimaryNode`` Exactly one node in a Data Platform cluster must have this set to ``true``. * **Syntax:** ``true``/``false`` * **Default:** ``false`` .. _setup_dpZone: ``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 :ref:`workspacePath ` * **Default:** ``Zone`` .. _setup_file_security: 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 :ref:`setup_value_replacement`. 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. .. _setup_disableADSSQL: ``disableADSSQL`` Disable ADS SQL features such as ``SQL.query()`` * **Syntax:** ``true``/``false`` * **Default:** ``false`` .. _setup_disableADSHTTP: ``disableADSHTTP`` Disable ADS ``IO.http`` function * **Syntax:** ``true``/``false`` * **Default:** ``false`` .. _setup_disableExternalFiles: ``disableExternalFiles`` Disable access to files outside of the workspace * **Syntax:** ``true``/``false`` * **Default:** ``false`` .. _setup_disableProjectUpload: ``disableProjectUpload`` Disable upload of customization projects via the :ref:`UploadProjectAdminPage` * **Syntax:** ``true``/``false`` * **Default:** ``false`` .. _setup_disableSPARQLSERVICE: ``disableSPARQLSERVICE`` Disable the ``SERVICE`` keyword in SPARQL queries. The keyword allows sub-queries to external SPARQL endpoints. * **Syntax:** ``true``/``false`` * **Default:** ``false`` .. _setup_disableSWPHTTP: ``disableSWPHTTP`` Disable HTTP access from SWP scripts * **Syntax:** ``true``/``false`` * **Default:** ``false`` .. _setup_disableCorpusUrlList: ``disableCorpusUrlList`` Disable the URL list corpus connector * **Syntax:** ``true``/``false`` * **Default:** ``false`` .. _setup_disableRemoteData: ``disableRemoteData`` Disable support for :ref:`remote data sources ` * **Syntax:** ``true``/``false`` * **Default:** ``false`` .. _setup_disableRemoteEditing: ``disableRemoteEditing`` Disable editing of :ref:`remote data sources `. Only meaningful if ``disableRemoteData`` is not set to ``true``. * **Syntax:** ``true``/``false`` * **Default:** ``false`` .. _setup_cors: Cross-Origin Resource Sharing (CORS) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``corsAllowedOrigins`` Configure :ref:`CORS allowed origins ` * **Syntax:** Comma-separated list of URLs * **Default:** - * **Example:** ``http://www.example.com, http://api.example.com`` Miscellaneous ^^^^^^^^^^^^^ .. _setup_sessionTimeout: ``sessionTimeout`` Session timeout in minutes. Users will have to log in again after this period of inactivity. * **Syntax:** Integer number * **Default:** 90 .. _setup_repositoriesProjectName: ``repositoriesProjectName`` (deprecated) Changes the name of ``Repositories`` directory within the workspace to accommodate legacy workspaces (e.g., ``EVNProjects`` for old EVN workspaces) * **Default:** ``Repositories`` .. _setup_publicServices: ``publicServices`` Configure :ref:`public services ` * **Syntax:** Space-separated list of URLs relative the the application root * **Default:** - * **Example:** ``service/myAssetCollection/ex/SomeService service/other/ex/OtherService`` .. _setup_file_syntax: 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**: .. code-block:: properties 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: .. code-block:: properties fieldName = This is a \ multiline value * **Backslash characters**, such as in Windows file paths, must be doubled: .. code-block:: properties workspacePath = C:\\EDG\\workspace * If the **same field name** occurs multiple times, only the last value will be used: .. code-block:: properties fieldName = First value will be ignored fieldName = Last value will be used * **UTF-8 character encoding** is used for international characters .. _setup_file_paths: 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**. .. _setup_file_comma_separated_fields: 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: .. code-block:: exampleField = unquoted value, "x, y and z","2'4"" wide, 4' deep"`` * ``unquoted value`` * ``x, y and z`` * ``2'4" wide, 4' deep`` .. _setup_value_replacement: 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}