# 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](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](http://www.dropwizard.io/) 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:
- 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_
### 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`](https://books.sonatype.com/sonatype-clm-book/1.26/html/book/main-configuration.html#server-proxy-config "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.
- [https://clm.sonatype.com](https://clm.sonatype.com/)
- [http://cdn.sonatype.com/](http://cdn.sonatype.com/)
### 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](https://books.sonatype.com/sonatype-clm-book/1.26/html/book/main-configuration.html#reverse-proxy-authentication "6.2.4. 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:
- **CLM for Maven**: [Evaluating Project Components with Sonatype CLM Server](https://books.sonatype.com/sonatype-clm-book/1.26/html/book/clm-server-evaluation.html "23.1. Evaluating Project Components with Sonatype CLM Server").
- **Nexus IQ CLI**: [Evaluating an Application](https://books.sonatype.com/sonatype-clm-book/1.26/html/book/evaluating-an-application-cli.html "22.3. Evaluating an Application").
- **Nexus Repository Manager 2**: [Connecting Nexus Repository Manager 2.x to IQ Server](https://books.sonatype.com/sonatype-clm-book/1.26/html/book/_integrating_nexus_repository_manager_2_x_and_iq_server.html#iq-server-connection "14.1.1. Connecting to IQ Server").
- **Nexus Repository Manager 3**: [Connecting Nexus Repository Manager 3.x to IQ Server](https://books.sonatype.com/sonatype-clm-book/1.26/html/book/_integrating_nexus_repository_manager_3_x_and_iq_server.html#iq-server-connect-nxrm3 "14.2.1. Connecting to IQ Server").
- **Nexus IQ for Bamboo**: [Configure Nexus IQ for Bamboo](https://books.sonatype.com/sonatype-clm-book/1.26/html/book/clm-bamboo-configuration.html "16.2. Configure Nexus IQ for Bamboo").
- **Nexus IQ for Hudson/Jenkins 1.x**: [Nexus IQ for Hudson/Jenkins 1.x Global Configuration](https://books.sonatype.com/sonatype-clm-book/1.26/html/book/integrating-jenkins-1.x.html#clm-for-ci-global-config "17.2.2. Global Configuration").
- **IQ for IDEA**: [Configuring IQ for IDEA](https://books.sonatype.com/sonatype-clm-book/1.26/html/book/idea-config.html "20.2. Configuring IQ for IDEA").
- **IQ for Eclipse**: [Configuring Sonatype CLM for Eclipse](https://books.sonatype.com/sonatype-clm-book/1.26/html/book/eclipse-config.html "19.2. Configuring Sonatype CLM for Eclipse").
- **CLM for SonarQube**: [CLM for SonarQube Configuration](https://books.sonatype.com/sonatype-clm-book/1.26/html/book/sonarqube-configure.html "21.2. Configuration").
### 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`](https://books.sonatype.com/sonatype-clm-book/1.26/html/book/main-configuration.html#server-file-config "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`](https://books.sonatype.com/sonatype-clm-book/1.26/html/book/main-configuration.html#server-mail "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](https://books.sonatype.com/sonatype-clm-book/1.26/html/book/main-configuration.html#base-url "6.2.3. Setting 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](http://dropwizard.github.io/dropwizard/0.6.2/manual/core.html#logging).
### 6.2.9. HTTP Configuration
The HTTP configuration in `config.yml` is displayed in [HTTP Configuration in `config.yml`](https://books.sonatype.com/sonatype-clm-book/1.26/html/book/main-configuration.html#server-http "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](http://httpd.apache.org/) or [nginx](http://nginx.org/en/) 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://books.sonatype.com/sonatype-clm-book/1.26/html/book/main-configuration.html#server-https "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](http://dropwizard.github.io/dropwizard/0.6.2/manual/core.html#ssl) and the [documentation\ for keytool](http://docs.oracle.com/javase/7/docs/technotes/tools/windows/keytool.html).
### 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_. |