Documentation Nexus IQ Server 1.20

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

4.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.

[Tip]

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

4.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 figs/web/clm-server-system-preferences-icon.png located in the top right of the IQ Server header (resembles a cog/gear) and choose the desired option to configure:

  • Configure Users and Roles in the System Preferences menu, potentially combined with LDAP as well. Read more about the security setup outlined in the Security Administration documentation.
  • Configure Proprietary Packages so that the IQ Server can distinguish your own code from other unknown components. For more information, refer to the component match and identification documentation in the report chapter.
  • Inspect or update or configure your Product License

4.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.

4.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.

4.2.4. Reverse Proxy Authentication

In some single sign-on (SSO) configurations, a reverse proxy is used to authenticate the user and to send the username to the server through a HTTP header.

The IQ Server can be configured to accept this kind of SSO configuration, allowing you to specify the exact header to be used.

[Warning]

As the configuration item below indicates, there are potential risks with this type of setup. Caution should be given to prevent any unwanted access to secured systems.

# Configures reverse proxy authentication for the web UI.
reverseProxyAuthentication:

    # Enables/disables authentication via a reverse proxy. Once the reverse proxy has authenticated a user's identity,
    # it is expected to forward the username to the IQ Server via the HTTP header configured below. The IQ Server
    # will then consider the user logged in without further password prompt.
    #
    # WARNING: If improperly configured, this feature poses a security vulnerability. To guard against authentication
    #   bypass it is crucial that all HTTP access to the IQ Server is proxied such that the designated username header
    #   is only settable by the reverse proxy that performs authentication and cannot be forged by end users themselves.
    #
    #enabled: false

    # The name of the HTTP request header that carries the username of an authenticated user.
    #usernameHeader: "REMOTE_USER"

4.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"
[Note]

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

4.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.

4.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.ymlHere’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.

4.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.

4.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

4.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.

4.2.11. Anonymous Access

By default the IQ Server allows anonymous access when submitting applications for evaluation. If you would like to require users to authenticate their access with a username and password in all situations, add the following line to the config.yml:

anonymousClientAccessAllowed: false

4.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
[Note]

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.