---
title: "Step 3. Set up the installation properties file"
slug: "dpo-install-using-linux-set-up-the-installation-properties-file"
updated: 2026-10-27T19:53:14Z
published: 2026-10-27T19:53:14Z
canonical: "docs.onespan.com/dpo-install-using-linux-set-up-the-installation-properties-file"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onespan.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Step 3. Set up the installation properties file

Control how the Servers are configured during installation by editing the properties contained in the nnl-install.properties file. This file specifies directory locations, hostname and port numbers for the nodes, database properties, tenant properties, as well as information to support out-of-band (OOB) authentication. This installer script contains detailed comments describing each property.

Refer to the [Sample nnl-install.properties file](/dpoa/docs/s3suite94-sample-nnl-installproperties-file-1) to see a finished installer script.

Edit <NNL_HOME>/install/nnl-install.properties for your configuration and required properties:

## A. Assign Server-related Properties

| **Property** | **Description** |
| --- | --- |
| ACCEPT_NNL_LICENSE_ENV | Mandatory. Boolean. Indicates acceptance of the Server licensing agreement. Must be true for the Server to work. |
| JAVA_HOME_ENV | Mandatory. The full path to the JDK install directory. |
| NNL_ADMIN_URL_ENV | Mandatory. The hostname and port number of your Admin node. |
| NNL_CLEANUP_ENV | Optional. Whether cleanup is required after installation. - true: Nonessential files and directories are removed after installation. - false (default): No files or directories are removed. |
| NNL_CRYPTO_PLUGIN_CLASS_NAME | Optional. Specifies the Crypto Plugin class name used to encrypt/decrypt data. For example: com.noknok.uaf.crypto.internal.handlers.SampleCryptoPlugin |
| NNL_EXT_DIR_PATHS | Optional. A comma-separated list of directories containing custom libraries (or custom data encryption plugins). Supports encryption of data at rest. Ask [OneSpan Customer Support](mailto:support@onespan.com) for *Data at Rest Encryption Configuration Technical Note* for details about implementing encryption. |
| NNL_INSTALL_DIR_ENV | Mandatory. The full path to the Server installation root directory. Typically where you extracted the server tar file. |
| NNL_INSTALL_MODE_ENV | Optional. Indicates your desired installation type, production or non-production. Use non-production for evaluation, development, testing, or staging. Leave this blank (default) for a non-production installation. Set this to "production" for a production installation. |
| NNL_JAVA_OPTS_PROPERTIES | Optional. Specifies the JAVA, CATALINA, nnl.restrict.input. field.regex and other system properties. These properties are required for Java and web applications. The values are used by setenv.sh and other NNL internal scripts. Multiple properties can be set with a blank space as delimiter. |
| NNL_JS_APPSDK_URL | Optional. Specifies the hostname and port number of your DigipassONE App SDK for Web. The origin for NNL_JS_APPSDK_URL and the [API_SERVER_URL](/dpoa/docs/s3suite94-step-3-set-up-the-installation-properties-file-1#e-assign-the-api-servers-url) should be the same. If they are different, then you must set up Cross-Origin Resource Sharing between the two origins. Example value: https://nnlapi.example.com/nnljs |
| NNL_SECRETS_PLUGIN_CLASS_NAME | Optional. Specifies the Secrets plugin class name. If a Secrets Plugin is deployed, do one of the following: - Assign the handle for the password to the DB_SECRET_HANDLE_ENV property. - Assign the encrypted password to the DB_ENCRYPTED_USER_PASSWD_ENV property. > For details about the above properties, see [Assign Database-connection-related Properties for the Operational Database](/dpoa/docs/s3suite94-step-3-set-up-the-installation-properties-file-1#c-assign-databaseconnectionrelated-properties-for-the-operational-database). > > Also you must assign the path for the plugin libraries to the NNL_EXT_DIR_PATHS property. This property is defined earlier in this table. |
| NNL_SERVER_URL_ENV | Mandatory. The host name and port number of the Runtime node (or Auth Server). If you have a load balancer before your runtime nodes, use the load balancer’s hostname and port: https://<load-balancer-hostname>.<domain-name>:<port>. |
| TOMCAT_INSTALL_DIR_ENV | Mandatory. The full path to the Tomcat install directory. |

## B. Assign Log Properties

During installation, you can select an appropriate logging level for your needs that balances the amount of information captured with the troubleshooting you have to do. You can also specify the time zone to use when the date and time are saved in a log entry.

| **Property** | **Description** |
| --- | --- |
| NNL_LOG_LEVEL_FOR_PROD | Controls the logging level for the diagnostic log (nnl.log), an invaluable tool for troubleshooting production installations. Defaults to ERROR for production installations and INFO for development installations. - ALL: Turns on all diagnostic logging. - DEBUG: The highest log setting. Use this setting while you are developing to get more information needed to debug issues. - ERROR: Only log errors that might still allow the Server to run. - FATAL: Only log severe errors that could lead to the Server crashing. - INFO: A typical log level that shows operations and failures. - OFF: Turns off all logging. - TRACE: Log finer-grained events than used for DEBUG. - WARN: Log potentially harmful situations. |
| NNL_LOGS_DATETIME_FORMAT | The specified format and time zone to use for diagnostic log entry timestamps (nnl.log). Defaults to {ISO8601}{UTC}. The value must be a valid Java time zone string, examples include: - {ISO8601}{PST} - {ISO8601}{GMT-10} - {ISO8601}{GMT+5} - {ISO8601}{IST} |
| NNL_ENABLE_ACCESS_LOG | Enable structured access logs that record requests and responses made to the Auth Server and the API Server. Defaults to false. Example: NNL_ENABLE_ACCESS_LOG=true Auth Server access log: <TOMCAT_HOME>/logs/nnl-access.log API Server access log: <TOMCAT_DIR>/logs/nnlgateway-access.log |
| NNL_ACCESS_LOG_REQUEST_HEADER_FILTER | A CSV list of Server request headers that you don't want included in the access logs. By default, all request headers are logged. In this example, these 4 request headers are filtered out of the access logs. Example: NNL_ACCESS_LOG_REQUEST_HEADER_FILTER=postman-token,host,accept-encoding,path |

## C. Assign Database-connection-related Properties for the Operational Database

| **Property** | **Description** |
| --- | --- |
| DB_ADDITIONAL_PROPS_ENV | Optional. Specifies the additional JDBC connection properties if required for the database. These properties are key/value pairs with a semicolon as delimiter. |
| DB_ENCRYPTED_USER_PASSWD_ENV | Required if you are not using the Secrets plugin. The Authentication Server uses this password to access the Operational Database. Enter encrypted password. To encrypt the password, follow steps in [Step 4. Encrypt Credentials Used by the Server](/dpoa/docs/s3suite94-step-4-encrypt-credentials-used-by-the-server-1). |
| DB_SECRET_HANDLE_ENV | Optional. If you are using the Secrets plugin, then this property specifies the handle for the operational database password in your external secrets manager. Prefix the handle with {handle}. For example, DB_SECRET_HANDLE_ENV={handle}runtimedb.password.handle |
| DB_TYPE_ENV | Required. The type of database that you are using: oracle, mysql, cockroachdb, or postgres. |
| DB_USER_NAME_ENV | Required. The Operational Database user name. |
| SKIP_DB_SCHEMA_CREATION | Optional. Tells the installer whether database setup is required or not. - true: The installer does NOT set up a database schema. - false (default): The installer DOES set up a database schema. |
| DB_DRIVER_CLASS_NAME_ENV | Optional. Specifies the database driver class name. If you use the standard JDBC drivers such as PostgreSQL JDBC Driver, MySQL Connector/J, or Oracle JDBC Driver, then nnl-install.sh configures this property automatically. Configure this property if you want to use a custom JBDC driver. For example, to use an AWS JDBC Wrapper, configure this property to software.amazon.jdbc.Driver. |

> If SKIP_DB_SCHEMA_CREATION is true, then you must create the database tables manually before executing nnl-install.sh. See Step 9. H. in [Before You Begin](/dpoa/docs/s3suite94-before-you-begin-1) for instructions.

For the remaining database properties, you can either use DB_CUSTOM_JDBC_STRING or the properties listed in the table below.

The information contained in DB_CUSTOM_JDBC_STRING is equivalent to assigning values to the DB_* properties shown under it. DB_CUSTOM_JDBC_STRING’s value overrides values assigned to the properties listed under it in the table if they are present in the installer script.

| **Property** | **Description** |
| --- | --- |
| DB_CUSTOM_JDBC_STRING | A database connection string. |
| DB_HOSTNAME_ENV | The Operational Database hostname or IP address. |
| DB_PORT_ENV | The Operational Database port number. |
| DB_NAME_ENV | - MySQL, CockroachDB, or PostgreSQL: the Operational Database name - Oracle: ORACLE_SID |

Example connection strings that you can assign to DB_CUSTOM_JDBC_STRING are listed below:

MySQL

```plaintext
"jdbc:mysql://localhost:3306/testdb?useSSL=true\&requireSSL=true\&verifyServerCertificate=true\&trustCertificateKeyStoreUrl=file:///etc/cert/truststore.jks\&trustCertificateKeyStorePassword=storepass"
```

Postgres

```plaintext
"jdbc:postgresql://localhost:5432/testdb?ssl=true&sslmode=verify-ca&sslcert=./test-cert.pem&;sslkey=./test-key.pem&sslrootcert=./test-server-ca.pem"
```

Oracle

```plaintext
"jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCPS)(PORT=1522)(HOST=myhost))
        (CONNECT_DATA=(SERVICE_NAME=myorcldbservicename))
        (SECURITY=(ssl_server_cert_dn="CN=testcert.oracle.com, O=Oracle Corporation,L=Redwood City,ST=California,C=US")))"
```

Cockroach

```plaintext
"jdbc:postgresql://localhost:26257/testdb?sslmode=verify-full\&sslrootcert=./ca.crt\&sslcert=./client.root.crt\&sslkey=./client.root.key"
```

## D. Assign Other Database Properties for the Operational Database

| **Property** | **Description** |
| --- | --- |
| DB_JDBC_PATH_ENV | Mandatory if using an Oracle or MySQL database. Filename and absolute path of the Oracle or MySQL JDBC drive. For example, /opt/ojdbc.jar or /opt/mysql-connector.jar. |

## E. Assign the API Server's URL

The following property is required.

| **Property** | **Description** |
| --- | --- |
| API_SERVER_URL | The host name and port number of the API Server. |

## F. Assign Out-of-band Authentication Properties for the default Tenant

Optional. If you plan to use out-of-band (OOB) authentication for the default tenant, uncomment the properties listed below and configure them. You can also configure these properties later. See [Out-of-band](/dpoa/docs/s3suite94-configure-an-out-of-band-authentication-method-1).

| **Property** | **Description** |
| --- | --- |
| OOB_REG_URL_ENV | URL for OOB registration. If you use a load balancer, this should be something like: https://<load-balancer-hostname>.<domain-name>:<port>/nnlgateway/nnl/reg. This URL exists after you install the API Server. |
| OOB_AUTH_URL_ENV | URL for OOB authentication. If you use a load balancer, this should be something like: https://<load-balancer-hostname>.<domain-name>:<port>/nnlgateway/nnl/auth. This URL exists after you install the API Server. |

## G. Assign the UAF Application ID for the default Tenant

Optional if you aren't using the UAF protocol for the default tenant. OneSpan strongly recommends that you assign the URL to facets.uaf, your organization's list of trusted apps, as the App ID.

For a detailed explanation of what the App ID is, how it is used, and recommendations, see [Assigning the App ID](/dpoa/docs/s3suite94-assigning-the-app-id-1).

| **Property** | **Description** |
| --- | --- |
| UAF_APPLICATION_ID | The UAF App ID for the default tenant. Assign the URL to the file facets.uaf. For example: https://<publicly_accessible_server>.<domain-name>:<port>/<path_to_file>/facets.uaf or https://www.example.com/facets/facets.uaf. |

## H. Assign FIDO2 Properties for the default Tenant

Optional if you aren't using the FIDO2 protocol for the default tenant.

The FIDO protocol requires that the RP ID and facet IDs must satisfy specific requirements. If you are not familiar with these requirements, please read section [FIDO2: RP IDs and Facet IDs](/dpoa/docs/s3suite94-configure-a-fido2-authentication-method-1).

| **Property** | **Description** |
| --- | --- |
| WEB_RP_ID | Specifies the FIDO/WebAuthn RP ID for the default tenant. Assign the domain for your organization. For example, example.com. |
| WEB_FACET_ID | Specifies the WebAuthn facet ID for the default tenant. For example, https://example.com:8443. |

## I. List Optional Web Applications

DigipassONE Authenticate ships with two optional DigipassONE utility apps, *nnlsignin* and *nnlfedapp*. Use nnlsignin together with a DigipassONE Federation Adapter to bring FIDO authentication into a Federation Server. Use nnlfedapp to support Federated Credential Management accessible through an OIDC flow. For more information about these apps, see [Utility Apps](/dpoa/docs/s3suite94-nok-nok-utility-apps-1)*.*

| **Property** | **Description** |
| --- | --- |
| DEPLOY_OPTIONAL_WEB_APP_LIST | Optional. Specifies the list of DigipassONE utility apps that the installer deploys during installation. Comma separated list of app names. For example: DEPLOY_OPTIONAL_WEB_APP_LIST=nnlfedapp,nnlsignin |

> If you are deploying a Crypto plugin and/or a Secrets plugin, then configure properties for the plugin(s) at this time. See [Crypto and Secrets](/dpoa/docs/s3suite94-crypto-and-secrets-plugins-1) for instructions.

To protect against the log4j vulnerability, OneSpan Servers ensure that the Tenant ID and Correlation ID fields do not match the value in nnl.restrict.input.field.regex

Example of a NNL_JAVA_OPTS_PROPERTIES that sets multiple properties in one string: NNL_JAVA_OPTS_PROPERTIES="-Dnnl.restrict.input.field.regex=.\$\{.\}.* -Dexample.key1=value1 -Dexample.key2=value2"

Formerly known as Digipass S3 Web App SDK, Digipass S3 JavaScript App SDK.

Formerly known as Digipass S3 Authentication Software. Enables passkeys, multi-factor authentication (MFA), hardware authenticators, one-time password (OTP).

Formerly known as Digipass S3.