Upsource 2020.1 Help

Configuring TLS

There are several ways to set up an encrypted HTTPS connection with TLS (SSL) between your Upsource server and its clients.

  • Use Upsource's built-in TLS. You can configure Upsource to run in the HTTPS mode:

  • Use a third-party TLS-terminating proxy server. This option is preferable when you have to run Upsource behind a proxy server for other reasons than encryption. See Proxy configuration for details.

You can switch from a third-party TLS-terminating proxy to the Upsource built-in TLS and vice-versa at any time regardless of your current settings.

Configuring built-in TLS in your current Upsource installation

Using the command line, you can switch between the HTTP and HTTPS modes.

  • HTTP— default HTTP mode. Built-in TLS is disabled.

To enable the secure HTTPS mode, you need to have a private key and certificate which you provide to Upsource either in the form of a keystore or separate files, using a corresponding configuration option:

To switch to a desired mode, you need to stop Upsource and run the configure command defining all the properties required for the configuration of your choice. See below for detailed instructions and complete lists of properties for each configuration.

Switch to the HTTP mode—disable built-in TLS

  1. Stop Upsource: <upsource_home>/bin/upsource.bat stop

  2. Enter the following command:

    <upsource_home>/bin/upsource.bat configure --listen-port=8080 --base-url=<new base URL> --secure-mode=disable

  3. Start Upsource: <upsource_home>/bin/upsource.bat start

Switch to the HTTPS mode with keystore

  1. Prepare the keystore file containing the server's private key and certificate. The certificate data it contains can be in JKS or PKCS#12 format, but the file name should be keystore.jks in order for Upsource to accept it. If it's not—rename the file to keystore.jks.

  2. Create a temporary folder and place the file keystore.jks containing the server's private key and certificate into that folder.

  3. Stop Upsource: <upsource_home>/bin/upsource.bat stop

  4. Run the following command:

    <upsource_home>/bin/upsource.bat configure \ --listen-port=443 \ --base-url=<new base URL> \ --secure-mode=tls \ --tls-server-cert-keystore-file=<path-to-keystore> \ --tls-server-cert-keystore-password=<keystore password> \ --tls-server-cert-keystore-key-alias=<private key entry alias> \ --tls-server-cert-keystore-key-password=<private key entry password> \ --tls-redirect-from-http=<[true|false]> [--tls-redirect-from-http-listen-port=8080]

    If your keystore file's format is PKCS#12:

    • The value of the parameter --tls-server-cert-keystore-key-alias should be friendlyName or a serial number of the bag with the server certificate. (Bag numbering starts with 1, so if there is only one bag in the keystore, then its serial number is 1.)

    • Skip the parameter --tls-server-cert-keystore-key-password=<private key entry password> if the private key entry is not protected with a password.

  5. Start Upsource: <upsource_home>/bin/upsource.bat start

Switch to the HTTPS mode with separate private key and certificate

  1. Stop Upsource: <upsource_home>/bin/upsource.bat stop

  2. Run the following command:

    <upsource_home>/bin/upsource.bat configure \ --listen-port=443 \ --base-url=<new base URL> \ --secure-mode=tls \ --tls-server-cert-key-file=<path-to-private-key-file> \ --tls-server-cert-file=<path-to-certificate-file> \ [--tls-server-cert-chain-file=<path-to-certificate-chain-file>] \ --tls-redirect-from-http=<[true|false]> \ [--tls-redirect-from-http-listen-port=8080] \

    • If the private key is encrypted, add this property to the command: --tls-server-cert-private-key-passphrase=<your passphrase>

    • If you want to define relative paths to the certificate files, use tls-server-cert-key-file, tls-server-cert-file, and tls-server-cert-chain-file. Set the value for the additional tls-server-cert-folder property with the absolute path to the directory. Relative paths are resolved against the specified absolute path.

    • If the server base URL changes as a result of switching to HTTPS mode, use the --base-url=<new base URL> parameter to set this value.

  3. Start Upsource: <upsource_home>/bin/upsource.bat start

Redirecting HTTP traffic

If you are going to use a secure HTTPS mode, you can optionally set up a Redirect listen port — a non-secure port that will receive all HTTP requests and redirect them to the secure listen port. To do so, set the parameter tls-redirect-from-http=true and add tls-redirect-from-http-listen-port=<your redirect port number> to the configure command.

If you're already running your server in the HTTPS mode, you can enable or disable the Redirect listen port at any time by running the configure command with the aforementioned properties — no need to include other properties in the command.

Make sure to stop Upsource before you run the configure command.

Switching between a third-party TLS-terminating proxy and Upsource's built-in TLS

Switching from a third-party TLS-terminating proxy to Upsource's built-in TLS or vice-versa requires no specific procedures and can be done with the following steps:

To switch from a third-party TLS-terminating proxy to the Upsource's built-in TLS:

  1. Disable your third-party TLS-terminating proxy.

  2. Enable the Upsource's built-in TLS as described above, choosing either of the two available certificate storage options: HTTPS (keystore) or HTTPS (privateKeyAndCert).

To switch from the Upsource's built-in TLS to a third-party TLS-terminating proxy:

  1. Switch Upsource to the HTTP mode as described above.

  2. Configure and enable a third-party proxy.

Configuration parameters

The following table provides a list of parameters that you can use to configure built-in TLS.

secure-modedisable | tls

The connection mode that is applied to the Upsource server. This property supports the following values:

  • disable— TLS is disabled. This is the default value for this property.

  • tls— TLS is enabled.

listen-portThe port on which Upsource listens to HTTP traffic.

The URL that end users request to access your Upsource installation. For example,

  • When the value for the secure-mode property is tls or your Upsource installation is secured behind an SSL-terminating reverse proxy server, the URL should begin with https.

  • Otherwise (when running Upsource using plain HTTP), the URL begins with http.

tls-redirect-from-httptrue | false

Set to true, to enable an additional port (defined by property tls-redirect-from-http-listen-port) to accept unencrypted HTTP traffic and redirect it to a secure port defined by the property listen-port.

The default value is false.

tls-redirect-from-http-listen-portSpecify an additional port to accept unencrypted HTTP traffic and redirect it to a secure port defined by the property listen-port (to enable this port, set the property tls-redirect-from-http to true).

An (optional) absolute path to resolve relative paths defined by other command line parameters, when present. Relative paths to server certificate files that are specified in other properties are resolved against this directory. The properties that can reference relative paths are:

  • tls-server-cert-key-file
  • tls-server-cert-file
  • tls-server-cert-chain-file
  • tls-server-cert-keystore-file
tls-server-cert-keystore-fileThe location of a keystore file in either JKS or PKCS #12 format.
tls-server-cert-keystore-passwordKeystore integrity password

The alias of the entry in the keystore that contains the server certificate and the private key. If your keystore uses the PKCS #12 format, follow these guidelines:

  • Use the value that is stored as the friendlyName in the keystore.

  • If the private key and certificate pair was not marked with a friendlyName during generation, use this parameter to provide the sequential number of this pair in the keystore. For a keystore that only contains one certificate and private key pair, set the value to 1.

tls-server-cert-keystore-key-passwordPassword that protects your server's private key entry in the keystore.
tls-server-cert-key-fileThe location of a private key (PKCS #1 or PKCS #8) file, stored in PEM format.
tls-server-cert-fileThe location of a certificate file, stored in PEM format.
tls-server-cert-chain-fileThe (optional) location of a file that contains the certificate chain, stored in PEM format.
tls-server-cert-private-key-passphrasestringIf you use an encrypted private key, then use this property to provide the passphrase that was used for encryption. Supported for both PKCS #1 and PKCS #8 formats.
Last modified: 09 July 2020