Upsource 2018.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

Parameters

Property

Value

Description

secure-mode

disable

The default value of the property. TLS is disabled by default.

listen-port

The port on which Upsource listens to the HTTP traffic.

base-url

The URL that end users will request to access your running Upsource instance (i.e. http://upsource.mydomain.com)

The URL should begin with http — not https, unless you're going to use a third-party TLS-terminating proxy.

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-storage-type=keystore \ --tls-server-cert-folder=<folder with the keystore file> \ --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 not protected with a password.

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

Parameters

Property

Value

Description

listen-port

The port on which Upsource listens to the HTTPS traffic.

base-url

The URL that end users will request to access your running Upsource instance (i.e. https://upsource.mydomain.com).

The URL should begin with https — not http.

secure-mode

tls

TLS is enabled

tls-server-cert-storage-type

keystore

Indicates that your private key/certificate data is stored in a generated keystore file in the JKS or PKCS#12 format.

tls-server-cert-folder

Specify the directory that contains the server certificate file to be applied to Upsource. The directory should contain the file keystore.jks.

tls-server-cert-keystore-password

Keystore integrity password

tls-server-cert-keystore-key-alias

For JKS format: Alias that is associated with the private key/certificate entry in the keystore.

For PKCS#12 format: Bag's serial number or friendlyName.

tls-server-cert-keystore-key-password

Password that protects your server's private key entry in the keystore.

tls-redirect-from-http

true or false. The default value is 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.

tls-redirect-from-http-listen-port

Specify 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. If tls-redirect-from-http is set to false, this property can be omitted.

Switch to the HTTPS mode with separate private key and certificate

  1. Create a temporary folder (let's call it <certificates_folder>) to store the files with private key, certificate and certificate chain (if any).

  2. Place the private key (in the PEM format) into file <certificates_folder>/privateKey.pem.

  3. Place the server certificate (in the PEM format) associated with the private key into the file <certificates_folder>/certificate.crt.

  4. If you have a certificate chain for signing the server's certificate (in the PEM format), place it into the file <certificates_folder>/certificateChain.crt.

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

  6. Run the following command:

    <upsource_home>/bin/upsource.bat configure \ --listen-port=443 \ --base-url=<new base URL> \ --secure-mode=tls \ --tls-server-cert-storage-type=privateKeyAndCert \ --tls-server-cert-folder=<certificates_folder> \ --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>

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

Parameters

Property

Value

Description

listen-port

The port on which Upsource listens to the HTTP traffic.

base-url

The URL that end users will request to access your running Upsource instance (i.e. https://upsource.mydomain.com).

The URL should begin with https — not http.

secure-mode

tls

TLS is enabled

tls-server-cert-storage-type

privateKeyAndCert

Indicates that your private key/certificate data is stored in the files privateKey.pem and certificate.crt located in the directory specified by tls-server-cert-folder. Also, a certificate chain can be defined in the file certificateChain.crt. All files are assumed to be stored in the PEM format.

tls-server-cert-folder

Specify the directory that contains the server certificate files to be applied to Upsource. The directory should contain the files privateKey.pem, certificate.crt and certificateChain.crt (if any).

tls-server-cert-private-key-passphrase

Passphrase used for private key encryption if any (for both PKCS#8 and PKCS#1 formats)

tls-redirect-from-http

true or false. The default value is 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.

tls-redirect-from-http-listen-port

Specify 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. If tls-redirect-from-http is set to false, this property can be omitted.

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.

Last modified: 13 March 2019
Upsource Cassandra propertiesTLS Server Certificate