# Configuring the Runtime Environment This section details configuring the Nexus RepositoryTM runtime with recipes for specific tasks. Configuration is separated into the following categories: the Java Virtual Machine and the Nexus Application environments. See the [Directories](https://help.sonatype.com/en/directories.html "Directories") topic on the `$install-dir` and `$data-dir` in Nexus Repository. ## Java Virtual Machine Environment The startup of the Nexus Repository Java Virtual Machine (JVM) is managed within the installation directory. The application startup loads JVM arguments from the Java properties file. ``` $install-dir/bin/nexus.vmoptions ``` To edit Java options: 1. Open `$install-dir/bin/nexus.vmoptions` in a text editor 2. Specify each Java option on a new line. 3. Save the file with permission and ownership of the user who owns the Nexus Repository process. ### [nexus.vmoptions](https://help.sonatype.com/en/configuring-the-runtime-environment.html#nexus-vmoptions_body) ``` -Xms2703m -Xmx2703m -XX:MaxDirectMemorySize=2703m -XX:+UnlockDiagnosticVMOptions -XX:+LogVMOutput -XX:LogFile=../sonatype-work/nexus3/log/jvm.log -XX:-OmitStackTraceInFastThrow -Djava.net.preferIPv4Stack=true -Dkaraf.home=. -Dkaraf.base=. -Dkaraf.etc=etc/karaf -Djava.util.logging.config.file=etc/karaf/java.util.logging.properties -Dkaraf.data=../sonatype-work/nexus3 -Dkaraf.log=../sonatype-work/nexus3/log -Djava.io.tmpdir=../sonatype-work/nexus3/tmp -Dkaraf.startLocalConsole=false -Djava.endorsed.dirs=lib/endorsed ``` ### Memory Before changing the default memory settings, review the memory guidelines. Changing settings requires adjusting all 3 values. The `-Xms` and `-Xmx` settings must always have the same value. See [Memory Requirement](https://help.sonatype.com/en/sonatype-nexus-repository-system-requirements.html#memory-requirements "Memory Requirements") 1. Locate the lines that configure memory: ``` -Xms2703M -Xmx2703M -XX:MaxDirectMemorySize=2703M ``` 2. Edit the values of each setting using the following format. The size is a number and the literal unit letters represent gigabytes (g,G), megabytes (m,M), or kilobytes (k,K). ``` -Xmssize[g|G|m|M|k|K] -Xmxsize[g|G|m|M|k|K] -XX:MaxDirectMemorySize=size[g|G|m|M|k|K] ``` ### Overriding the Java Version in Container Environments Starting with the Nexus Repository 3.78 release, the `nexus.vmoptions` file no longer applies to Docker images. Instead, users must now configure JVM options using the `INSTALL4J_ADD_VM_PARAMS` environment variable. See the [Nexus Repository Docker Container README](https://github.com/sonatype/docker-nexus3?tab=readme-ov-file#notes) for details. ### DNS Caching in Cloud Environments Java's default DNS caching may cause connection issues in dynamic AWS environments where resource IPs change. Configure the JVM's DNS cache Time-To-Live (TTL) to 5 seconds to ensure your application quickly adapts to these changes. This is highly recommended when using an external database such as RDS in failover scenarios. ``` -Dnetworkaddress.cache.ttl=5 ``` See documentation from [AWS on TTL for DNS](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/jvm-ttl-dns.html) ### Data Directory The **Data Directory** is used to store the content that you want to preserve. Set the value as an absolute path or a path relative to the `$install-dir/bin` directory. ``` -Dkaraf.data=/opt/sonatype-work/nexus3 -Djava.io.tmpdir=/opt/sonatype-work/nexus3/tmp -XX:LogFile=/opt/sonatype-work/nexus3/log/jvm.log -Dkaraf.log=/opt/sonatype-work/nexus3/log ``` ### Temporary Directory Nexus Repository uses the Java virtual machine temporary directory for downloading and editing files. The temporary directory is set inside the data directory to isolate file ownership and permissions under a single directory tree. To change the location of the temporary directory, edit the following line: ``` -Djava.io.tmpdir=../sonatype-work/nexus3/tmp ``` - Do not manipulate files in the temp directory - Make sure the disk has more than 1GB of free space ### Overriding the License File Location Override the default location of where the license is stored by modifying the Java user preferences. This method only works for Linux and MacOS environments. The location must be an absolute path that is readable by the user account owning the repository manager process. This is the directory where the product license is written when installed. 1. Find and edit the `/bin/nexus.vmoptions` file. 2. At the end of the file, add a new line including the following property: ``` -Djava.util.prefs.userRoot=/absolute/path/to/already/created/directory ``` ## Nexus Application Environment The main location for the application configuration files is the `$install-dir/etc` directory. This directory includes one properties file and several nested directories: - #### fabric Configuration files for Ehcache, Elasticsearch, and OrientDB - #### jetty Eclipse Jetty is used as the webserver for the Nexus Repository application. We manage configuration files for Eclipse Jetty in this directory. Eclipse Jetty has a default of 400 threads in its pool size. Our support article [Understanding Eclipse Jetty 9.4.8 Thread Allocation](https://support.sonatype.com/hc/en-us/articles/360000744687) provides details on how allocation works and why at a certain amount of repositories with connectors the pool can maxed out. The `IllegalStateExceptions` warning may be seen indicating that there are insufficient configured threads. - #### logback Logger definition for the log file name, logging levels, pattern layout, and rotation rules. The configuration files for logback including: See [Logging](https://help.sonatype.com/en/logging.html "Logging") for information on adjusting the logging configuration. - #### logback.xml For the `nexus.log` and `tasks.log` files. - #### logback-access.xml For the `request.log` file. - #### spring Empty java.util.logging.properties to prevent the log to stderr, so that all logs will be delegated to pax logging JUL handler only. - #### ssl A directory to put keystores when configuring HTTPS See [Configuring SSL](https://help.sonatype.com/en/configuring-ssl.html "Configuring SSL") for details. ### nexus-default.properties ``` $install-dir/etc/nexus-default.properties ``` This file contains the system default property values such as the main HTTP connector port and the context path. **This file should not be modified** rather configuration changes should be maintained in the `nexus.properties` file stored in the data directory. Keeping the application configuration in the data directory simplifies upgrading as when new application properties are added you do not have to find the difference between the two files. ### nexus.properties ``` $data-dir/etc/nexus.properties ``` Configuration stored in the `nexus.properties` file overrides the settings found in the `nexus-default.properties` file. This file provides a more simple upgrade process as custom configuration is maintained separately from the default application configuration. The `$data-dir/etc/nexus.properties` file is created the first time Nexus Repository is started. When you need to add configuration before the first start-up, manually created file with any of the customizations stored there. ### Application Port We recommend configuring Nexus Repository behind a proxy server when directing traffic from the domain to the service. From the running server, you may access the service directly using the localhost and the default port for the application, `8081`. ``` http://localhost:8081/ ``` Set the port by adding the following line to your `nexus.properties` file: ``` application-port=8081 ``` See [Setting up SSL](https://help.sonatype.com/en/configuring-ssl.html "Configuring SSL") to use a secured port instead of HTTP. ### Application Context Path The application context path is the directory found after the domain name in the site's URL. By default, this value is set to a slash `(/)` to locate the service at the root of the domain. The location may be changed by setting the `nexus-context-path` property in the `nexus.properties` file. ``` nexus-context-path=/nexus ``` In the above configuration, the exposed URL is now `https://your_url.domain/nexus/` ### Local User Password Algorithm Administrators are able to configure a property on `nexus.properties` file to configure the algorithm used to hash local users passwords. Available options are: - **PBKDF2WithHmacSHA256** - refers to a specific implementation of the Password-Based Key Derivation Function 2 (PBKDF2) that uses HMAC-SHA256 as its pseudo-random function (PRF) - **PBKDF2WithHmacSHA1** - a specific implementation of the Password-Based Key Derivation Function 2 (PBKDF2) algorithm, utilizing HMAC-SHA1 as its underlying pseudorandom function. - **SHA512** - the default algorithm that Nexus Repository will use if another option is not configured. Note that you cannot set SHA512. ``` nexus.security.password.algorithm=PBKDF2WithHmacSHA256 ``` ### Set the Secrets Encryption Algorithm Administrators set a property on `nexus.properties` file to configure the algorithm used to encrypt secrets. Consider updating the encryption algorithm to using one-way hashing with `PBKDF2WithHmacSHA256`. See [Re-encryption in Nexus Repository](https://help.sonatype.com/en/re-encryption-in-nexus-repository.html "Re-encryption in Nexus Repository") Available options are: - **PBKDF2WithHmacSHA256** - refers to a specific implementation of the Password-Based Key Derivation Function 2 (PBKDF2) that uses HMAC-SHA256 as its pseudo-random function (PRF) - **PBKDF2WithHmacSHA1** - a specific implementation of the Password-Based Key Derivation Function 2 (PBKDF2) algorithm, utilizing HMAC-SHA1 as its underlying pseudorandom function. This is the default algorithm used for secrets encryption. ``` nexus.security.secrets.algorithm=PBKDF2WithHmacSHA256 ``` ### Use a Secrets File to the Nexus Repository Configuration Use one of the following methods to configure Nexus Repository with the custom encryption key. - #### Set in the Secrets File Property in nexus.properties Add the `nexus.secrets.file` property pointing to the secrets JSON file in your `nexus.properties`. ``` nexus.secrets.file=/full/path/to/your/secrets/.json ``` - #### Set the Secrets File as an Environment Variable Use the `NEXUS_SECRETS_KEY_FILE` environment variable to pass your JSON key file to the Nexus Repository. ``` export NEXUS_SECRETS_KEY_FILE=/opt/nexus/keys/.json ``` - #### Configuring in Helm Charts In the Helm chart configuration, at a minimum you must set the following parameters: ``` secret.nexusSecret.enabled=true secret.nexusSecret.secretKeyfile=/path/to/json ``` Specify the key file in the command line using the following syntax: ``` --set-file secret.nexusSecret.secretKeyfile=/path/to/json ``` See the [Helm chart README](https://github.com/sonatype/nxrm3-ha-repository/blob/main/nxrm-ha/README.md#configuration). - #### Using AWS Secrets Manager or Azure Key Vault Those using AWS Secrets Manager or Azure Key Vault need to include the secret in AWS Secrets Manager/Azure Key Vault. See the [Helm chart README](https://github.com/sonatype/nxrm3-ha-repository/blob/main/nxrm-ha/README.md#configuration) for details. #### Create a JSON File Containing Your Custom Encryption Key Create a JSON file containing your encryption key. This file is to remain part of your deployment to decrypt persisted secrets throughout the deployment. Use the following JSON format and save it as a `.json` file in a secured location. ``` { "active": "my-key", "keys": [\ {\ "id": "my-key",\ "key": "some-secret-key"\ }\ ], "fixedEncryption": { "keyId": "my-key", "salt": "myCustomSaltForEncryption", "iv": "0123456789ABCDEF" } } ``` The JSON file specifies the following properties: - `active` - The key to use for encryption; the value matches the `id` in the `keys` array - `keys` - An array containing key objects. It should have 112 bits of complexity for FIPS Compliance. - `id` - A unique identifier for the key - `key` - The secret key value - `fixedEncryption` - Optional field used to change the default values of Nexus Encryption. See [Nexus Repository FIPS 140-3 Compliance](https://help.sonatype.com/en/nexus-repository-fips-140-3-compliance.html "Nexus Repository FIPS 140-3 Compliance") - `keyId` - Optional; Identifier for a Key - `salt` - Optional; must have 128 bits of complexity - `iv` - (initialization vector) Optional; must be 16 bytes - `previousFixedEncryption` - Optional field used when changing fixed encryption. It describes the previous fixed encryption parameters so Nexus Repository can decrypt existing secrets while re-encrypting them with the new configuration. ##### Previous Fixed Encryption When you change the `fixedEncryption` configuration that protects your secrets, there may be a period where some secrets are still encrypted with the old configuration while new ones should use the updated configuration. The `previousFixedEncryption` allows Nexus Repository to handle this transition by describing the previous `fixedEncryption` parameters. During re-encryption, Nexus Repository uses the `previousFixedEncryption` values to decrypt existing secrets and then encrypts them using the current configuration. **Note** If the `fixedEncryption` is present, the new values defined there are used for encryption. If it is omitted, Nexus Repository will revert to using its default encryption values. The `previousFixedEncryption` block supports the same fields as `fixedEncryption`. Include the values that correspond to the previous fixed encryption. You only need to specify the values that have changed; for example, either keyId, or salt, or both. Example: Rotating a Fixed Encryption Key ``` { "active": "my-key1", "fixedEncryption" : { "keyId": "my-key3", "salt": "fixed-salt-value2" }, "previousFixedEncryption" : { "keyId": "my-key2", "salt": "fixed-salt-value2" }, "keys": [\ {\ "id": "my-key1",\ "key": "somesecretkey1"\ },\ {\ "id": "my-key2",\ "key": "somesecretkey2"\ },\ {\ "id": "my-key3",\ "key": "somesecretkey3"\ }\ ] } ``` Example: Reverting to Default Encryption Values ``` { "active": "my-key1", "previousFixedEncryption" : { "keyId": "my-key3", "salt": "fixed-salt-value2" }, See [Re-encryption in Nexus Repository](https://help.sonatype.com/en/re-encryption-in-nexus-repository.html "Re-encryption in Nexus Repository") ### Uncommon Configuration Properties The following configuration properties are uncommon and in most cases should only be set with the guidance from Sonatype Support. #### Global URL Escaping Behaviour The logic used to escape URL path segments sent to Nexus Repository may occasionally cause valid inbound requests (already escaped) to become double-escaped when proxied to remote repositories, resulting in `404 Not Found` or `400 Bad Request` responses. Use the following feature flag to control how Nexus Repository escapes special characters in URLs globally. ```//when adding a custom escape, include the default values first: (%:%25,::%3A, :%20) nexus.proxy.url.escape.rules=%:%25,::%3A, :%20,+:%2B ``` When rules overlap, the order in the configuration determines which rule wins — the first match in insertion order is applied. New in 3.94 For repository-level handling of encoded characters in proxy requests, see [Preserve Encoded Characters](urn:resource:component:747831). This setting is configured per proxy repository and is separate from the global URL escaping rules. New in 3.95 You can configure custom URL escape rules for individual proxy repositories. It enhances the global URL escaping behaviour by allowing repository-specific customization. To configure it, enable the _Preserve Encoded Characters_ checkbox for the required proxy repository and configure `nexus.proxy.url.escape.rules` in `nexus.properties`. ``` nexus.proxy.url.escape.rules=repositoryName={pattern:replacement,pattern:replacement} ``` Example: ``` nexus.proxy.url.escape.rules=pypi-proxy={+:%2B},maven-central={+:%2B},npm-registry={} ``` Note that the repository names are case-sensitive. If it is not set, the repositories follow the default behaviour. #### Limiting Excessive Audit Log Line Length Due for Asset Updates When the metadata of an artifact is updated, those changes are logged in the `audit.log`. In some cases, the log entries are very large when they contain the `attribute.changes` attribute extracted from the artifact manifest. This logging may excessively fill the audit.log with metadata exponentially adding to the growth of log files. PyPi and NuGet are known repository formats that can cause this issue. Disable logging the `attribute.changes` value of the event for ALL formats by setting the following property: ``` nexus.audit.attribute.changes.enabled=false ``` Add this property to `nexus.properties` file for each node of your deployment and restart the node to take effect. #### Compact Blobstore Task in HA Environments In highly available environments, concurrent `HEAD/GET` requests to the same file may cause nodes to attempt to update the blob property file (`lastDownloaded`) at the same time. This results in one update failing, leaving the request without blob attributes. The following properties are used to adjust the timing and the number of retry attempts when updating artifact metadata during the execute of the Compact Blobstore task. Number of retries for blob attribute reads (default: 1). Setting the value to zero (0) may prevent file uploads and is not recommended. ``` nexus.blobstore.get.maxRetries=1 ``` Delay in milliseconds between retries (default: 500) ``` nexus.blobstore.get.retryDelayMs=500 ``` #### Changing the Thread Pool Size Changing the thread pool size is not a sustainable solution for scaling performance. We suggest being conservative in increasing the maximum threads as each new thread in the pool has the potential to increase workload inside of Nexus Repository for concurrent request threads. Modify the number of threads in the thread pool by adding the following to the jetty configuration. Nexus Repository must be restarted for the changes to be picked up. ``` $install-dir/etc/jetty/jetty.xml ``` ``` 400 ```