-connection-settings | bnd
Description: This chapter discusses the connection settings of bnd that are used when bnd is asked to download or upload a file from a remote server. The connection settings can provide a userid/password for basic authentication, proxies, and/or the trust policy for verifying the host name of a TLS/SSL server. These settings can obviously not be part of the workspace since they are unique to the actual user of the workspace. That is, they need to be stored outside the workspace in a user accessible area.

- # -connection-settings

  This chapter discusses the connection settings of bnd that are used when bnd is asked to download or upload a file from a remote server. The connection settings can provide a userid/password for basic authentication, proxies, and/or the trust policy for verifying the host name of a TLS/SSL server. These settings can obviously not be part of the workspace since they are unique to the actual user of the workspace. That is, they need to be stored outside the workspace in a user accessible area.

  Since Maven is very popular we’ve followed the same syntax for settings. The supported elements in this file are `<server>` and `<proxy>`. Other elements are ignored.

  ## Finding the Settings

  The default order in which bnd looks for settings is:

      `~/.bnd/connection-settings.xml`
      `~/.m2/settings.xml`

  If you want to disable the use of default from the workspace then you can use the `-connection-settings` instruction in the workspace’s `cnf/build.bnd` file. If you set the instruction to `false` then it will not look for the aforementioned files.

      -connection-settings: false

  In this setting, you can also list additional files to parse that must be of the same syntax as the Maven settings file. The names `maven` and `bnd` are recognized as `~/.m2/settings.xml` and `~/.bnd/connection-settings.xml` respectively. For example, if we first want to look in the home directory in `~/foo/settings.xml` and then in the bnd settings, we can set the `-connection-settings` to:

      -connection-settings: ~/foo/settings.xml, bnd

  In addition, you could also specify the maven settings inline. For example:

      -connection-settings: \
         server; \
             id="http://server"; \
             username="myUser"; \
             password=${env;PASSWORD}

  ## Logging

  You can create a log file specific for the connections by specifying:

      -connection-log: somefile.txt

  This file will contain the detailed trace output

  ## Syntax

  The settings files have the following XML structure:

      <settings>
        <proxies>
          <proxy>
          <id/>
            <active>        'true' | 'false' </active>
            <protocol>      'http'| 'direct' | 'socks' </protocol>
            <host>          domain name </host>
            <port>          port to use </port>
            <username>      user name to use for the proxy </username>
            <password>      password to use for the proxy </password>
            <verify> true | false </verify>
            <nonProxyHosts> glob ( '|' glob )* </nonProxyHosts>
          </proxy>
        </proxies>
        <servers>
          <server>
            <id>default</id>
      	    <username>username</username>
              <password>password</password>
      	    <verify> true | false </verify>
      	    <trust> comma separated paths to X509 certificates </trust>
              <maxConcurrentConnections>10</maxConcurrentConnections>
          </server>
        </servers>
      </settings>

  Any additional elements are ignored.

  ### Proxies

  The purpose of the proxy definitions is to define a communication proxy. We support `HTTP` and `SOCKS` proxies. An additional built-in proxy is the `DIRECT` ‘proxy’. Proxies can be authenticated with a username and password.

  Tag | Default | Values | Description
  --- | --- | --- | ---
  `id` | `default` | `NAME` | Identifies the proxy, must be unique in
  |  |  | the list of proxies.
  `active` | `true` | `true | false` | If this proxy is active
  `protocol` | `http` | `socks | http | direct` | The proxy protocol to use.
  `host` |  | `domain-name` | The domain name or IP address of the proxy host
  `port` |  | `INTEGER` | Port number, maybe absent if default
  |  |  | port for protocol
  `username` |  |  | User name for authentication to the proxy
  `password` |  |  | Password for authentication to the proxy
  `nonProxyHosts` | none | `GLOB ('|' GLOB)*` | Filter on the destination hosts that should not be proxied

  ### Servers

  In maven, the servers are identified by an id; when you define a repository you tell which id to use. In bnd this works slightly different. Instead of using the id we use the id in the settings as a glob expression on the protocol, host name, and port number. The glob expression must match the scheme, the host and the port if the port is not the default port. To match the url `https://maven2-repository.dev.java.net/`, the server component could look like (pay attention to the missing trailing slash):

      <server>
      	<id>https://*java.net</id>
      	...
      </server>

  The first server that matches the id will provide the parameters.

  Tag | Default | Values | Description
  --- | --- | --- | ---
  `id` |  | `GLOB` | A glob expression on the scheme + host + port
  `username` |  |  | User name for authentication to the server
  `password` |  |  | Password for authentication to the server
  `verify` | `true` | `false | true` | Enable/disable the verification of the host name against a certificate for HTTPS
  `trust` |  |  | Provide paths to certificate that provide trust to the host certificate. The format most of a X.509 certificate file. Normally the extension is `.cer`
  `maxConcurrentConnections` | 0 (unlimited) | 0.. | Limits the number of parallel connections to a host. Some hosts use the number of concurrent connections as a sign of a denial of service attack.

  ## oAuth2 authentication

  It also supports Bearer (OAuth2) authentication. If the `<server>` configuration has only a password and no username, then Bearer authentication is in effect with the password used as the token.

      -connection-settings: server;id="https://*.server.com";password="oauth2token"

  will cause

      Authorization: Bearer oauth2token

  request header to be sent to servers matching the glob https://*.server.com.

  See https://github.github.com/maven-plugins/site-plugin/authentication.html for an example of a `<server>` configuration for OAuth2.

  ## Commands

  The bnd command line provides a number of commands to display and verify the settings as well as getting the information from getting a remote file.

      $ bnd com
      Available sub-commands:

      clear                       -         Clear the cached file that is
                                           associated with the givenURI
      info                        -         Show the information used by the
                                            Http Client to get aremote file
      settings                    -         Show the bnd -connection-settings

  ## Certificate Authentication

  Certificate authentication is only suppprted using the Java settings through system properties. Either with `-D` on the command line or in the `eclipse.ini` file or through some other means. In that case, make sure not specify the `<trust/>` nor `<verify/>` element in a `connection-settings.xml`. The reason is that once you specify those element, the built-in Java mechanism is replaced with bnd code.