Nexus Documentation - Nexus IQ Server 1.26 - Sonatype.com

Documentation Nexus IQ Server 1.26

Nexus IQ Server 1.26

Our documentation site has moved. For the most current version, please see http://help.sonatype.com.

6.2. Advanced Configuration

The main configuration file for the IQ Server installation is a YAML formatted file called config.yml found in the installation directory. The IQ Server is an application running on a Dropwizard server.

In addition, a number of configuration steps can be taken within the running server user interface.

This section will discuss various configuration options in the config file as well as some other configuration scenarios. When editing the file it is important to preserve the indentations, since they are significant for the resulting values created when parsing the configuration file.

| | | | The config.yml format does not support tab characters. Use an editor
that displays special characters like tabs when editing the file. |

6.2.1. Initial Configuration of the IQ Server

Besides the license installation mentioned earlier, there are a few further configuration steps you should consider before diving right into using the IQ Server. You can configure various aspects in the System Preferences section of the IQ Server user interface, which you can access by clicking on the System Preferences icon and choose the desired option to configure:

6.2.2. Running the IQ Server Behind a HTTP Proxy Server

Many organizations filter, control and optimize access to the internet via a proxy server. Any server or even any computer within the organization is forced to connect to the internet via the proxy server. The IQ Server needs to communicate with the Sonatype Data Services via the internet.

To allow the IQ Server to connect via a proxy, you have to specify the connection details in the proxy section of the config.yml file displayed in Proxy Configuration in config.yml.

Proxy Configuration in config.yml.

proxy:
    hostname: "127.0.0.1"
    port: 80
    username: "anonymous"
    password: "guest"

If your proxy server is based on whitelisted URLs, you can use the following list of URLs to ensure that the IQ Server can reach all the required services.

6.2.3. Setting the Base URL

If your IQ Server is accessed via a https proxy or a proxy server that changes the http port or for other reasons can potentially not determine what the authoritative URL to access the server itself is, you need to configure the baseUrl parameter.

baseUrl: http://nexus-iq-server.example.com/

It is used by the server for any user facing links e.g. located in email notifications sent by the server to direct users to the server.

6.2.4. Reverse Proxy Authentication

Browser-based single sign-on (SSO) configurations allow a user to log into the system in a web browser without the need to log into any individual web applications. Any user navigation to further applications carries the authenticated username through to the application and the user is automatically logged in.

Typically this is implemented with a reverse proxy server and the username is supplied via a HTTP header field.

The IQ Server can be configured to accept this kind of SSO configuration in the config.yml file, allowing you to specify the exact header field to be used:

# Configures reverse proxy authentication for the web UI.
reverseProxyAuthentication:
    # Set to true to activate authentication
    enabled: true
    # Name of the HTTP request header field that carries the username
    usernameHeader: "REMOTE_USER"
    # Set to true for backward compatibility with old client plugins
    csrfProtectionDisabled: false

| | | | When using reverse proxy authentication from integration points to IQ Server, Cross-Site Request Forgery
(CSRF) protection is enabled by default. If an integration does not support CSRF protection, it should be updated
to the latest version. Alternatively, CSRF protection can be disabled by setting csrfProtectionDisabled: true
in the IQ Server configuration. |

The default config.yml contains a commented out section for this configuration with some further details.

This authentication method applies to all users, both IQ Server and LDAP users. Incoming usernames are matched first to IQ Server users, then to LDAP users, and then the configuration in the IQ Server determines the access level granted to the user.

Public Key Infrastructure (PKI) Authentication

| | | | In order to implement PKI authentication, a reverse proxy server is needed to translate PKI supplied credentials to users known by IQ Server. See the Reverse Proxy Authentication section for details. |

Tools and plugins can be configured to use PKI authentication, which delegates authentication to the Java Virtual Machine (JVM). When delegated, the tool or plugin does not handle authentication and instead the JVM supplies PKI information to the reverse proxy for authentication.

For information on setting PKI authentication for a specific tool or plugin, please see the following:

6.2.5. Appending a User Agent String

To address the firewall configurations set by some organizations, you can customize the user agent header used for HTTP requests. To add a user agent string, add the following line to the IQ Server config.yml:

userAgentSuffix: "test string"

| | | | Control characters are not permitted, and the max length of the string is
128 characters. |

6.2.6. File Configuration

IQ Server stores various files and data related to its operations in a work directory. By default this data is stored in a /sonatype-work/clm-server directory in the path the server runs. The directory is configurable using the sonatypeWork field in File Configuration in config.yml.

File Configuration in config.yml.

sonatypeWork: ./sonatype-work/clm-server

In addition, IQ Server uses the system temporary directory during its operation. This folder varies by operating system but is usually controlled by an environmental variable. If a specific directory needs to be used, the IQ Server can be started with a command line flag as such:

cd /opt/nexus-iq-server
java -jar -Djava.io.tmpdir=/path/to/tmpdir nexus-iq-server-*.jar server config.yml

Note that the user account which the server runs under must have sufficient access rights to both the work and temporary directory in order for IQ Server to function properly.

6.2.7. Email Configuration

The IQ Server can be configured to send email notifications for events such as policy violation notifications. This functionality requires an SMTP server, which is configured along with a number of other options in the mail section of the config.yml file displayed in Mail Configuration in config.yml.

Mail Configuration in config.yml. Here’s an example configuration:

mail:
    hostname: your.mailserver.com
    port: 465
    username: user@company.com
    password: password
    tls: true
    ssl: true
    systemEmail: "Sonatype@localhost"

The connection details are established with hostname and port and optionally with the addition of username, password, tls and ssl. The systemEmail parameter will be used as the sender email for any emails the IQ Server sends. All fields are required.

Finally, when setting email configuration, make sure you have also set the Base URL, otherwise sending of notification emails may fail.

6.2.8. Logging Configuration

The IQ Server application logging can be configured in the logging section of the config.yml file. By default, a log directory is created in the installation directory and the clm-server.log is rotated. Further logging configuration is documented in the Dropwizard\ manual.

6.2.9. HTTP Configuration

The HTTP configuration in config.yml is displayed in HTTP Configuration in config.yml. The port parameter for the IQ Server allows you to set the port at which the application is available. The adminPort exposes the operational menu. Both ports can be freely changed to other values, as long as these port numbers are not used and in the allowed range of values greater than 1024.

HTTP Configuration in config.yml.

http:
    port: 8070
    adminPort: 8071

6.2.10. HTTPS/SSL

One option to expose the IQ Server via https, is to use an external server like Apache httpd or nginx and configure it for reverse proxying the external connections via https to internal http connection. This reverse proxy can be installed on the same server as the IQ Server or a different server and numerous tutorials for this setup are available on the internet.

A second option is to directly configure SSL support for Dropwizard by modifying the http: segment in the config.yml file following the example in HTTPS Configuration in config.yml.

HTTPS Configuration in config.yml.

http:
  port: 8443
  adminPort: 8471

connectorType: nonblocking+ssl

ssl:
    keyStore: /path/to/your/keystore/file
    keyStorePassword: yourpassword

The keystore file can be generated and managed with the keytool. Further documentation is available in the Dropwizard\ documentation and the documentation\ for keytool.

6.2.11. Anonymous Access

By default, the IQ Server requires users to authenticate when submitting applications for evaluation. While not recommended, if you need to allow anonymous application evaluation submissions, add the following line to the config.yml:

anonymousClientAccessAllowed: true

6.2.12. CSRF Protection

Attacks on the IQ Server could occur via a cross-site request forgery (CSRF). To protect against this, a configuration item csrfProtection has been provided. This option is set to true by default.

# Enables/disables cross-site request forgery protection. Defaults to true for increased security.
#csrfProtection: true

| | | | In cases where the HTTP headers are stripped (e.g. a proxy
configuration), this protection would block usage of the UI. To address this,
you can disable this protection by setting the configuration item to false. |