Configure Built-in TLS from the Command Line

The instructions on this page show you how to configure built-in TLS for an existing installation using command-line arguments.

Using the command line, you can switch between the following connection modes:

Mode	Description
HTTP	The default HTTP mode. TLS is disabled. HTTP mode is only suitable for test installations or when connections to Hub are routed through an SSL-terminating reverse proxy server.
HTTPS	A secure HTTPS mode. TLS is enabled. The configuration parameters let you secure your server connections using the following file formats: A keystore that contains private key/certificate data in JKS or PKCS #12 format. A private key, certificate, and (optional) certificate chain as separate files in PEM format.

Mode

Description

HTTP

The default HTTP mode. TLS is disabled.

HTTP mode is only suitable for test installations or when connections to Hub are routed through an SSL-terminating reverse proxy server.

HTTPS

A secure HTTPS mode. TLS is enabled.

The configuration parameters let you secure your server connections using the following file formats:

A keystore that contains private key/certificate data in JKS or PKCS #12 format.
A private key, certificate, and (optional) certificate chain as separate files in PEM format.

To switch modes, stop Hub and run the configure command. The values that you specify for each of the parameters in the command define your configuration of choice. See below for detailed instructions and a complete list of properties for each configuration.

You can also use these procedures if you have already configured HTTPS and simply want to apply new private key/certificate to the server.

Use this information to configure built-in TLS for installations that run Hub version 2018.4.11214 and later. If you are running an earlier version of Hub, switch to the tab that shows instructions for Hub versions from 2018.2 through 2018.4.11214.

To switch to HTTP mode:

Stop the Hub service.
Enter the following command:

<hub_home>/bin/hub.sh configure \ --listen-port=8080 \ [--base-url=<new base URL>] \ --secure-mode=disable

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

When you change the base URL of your Hub installation, you must update the settings for integrations and connected service to use the new URL. This includes settings that are stored in Upsource and YouTrack. If you have enabled auth modules that support OAuth 2.0, you need to generate new client IDs and secrets for each third-party authorization service.

For more information about the parameters that are used in this command, see Configuration Parameters.
Start the Hub service.

To switch to HTTPS mode using an SSL keystore file:

Stop the Hub service.
Run the following command:

<hub_home>/bin/hub.sh 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 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.
  
  When you change the base URL of your Hub installation, you must update the settings for integrations and connected service to use the new URL. This includes settings that are stored in Upsource and YouTrack. If you have enabled auth modules that support OAuth 2.0, you need to generate new client IDs and secrets for each third-party authorization service.
- If you are switching from HTTP to HTTPS mode, you can designate a redirect listen port. This non-secure port receives all HTTP requests and redirects them to the secure listen port. To do so, use tls-redirect-from-http=true and specify a value for the tls-redirect-from-http-listen-port=<your redirect port number> property.
For more information about the parameters that are used in this command, see Configuration Parameters.
Start the Hub service.

To switch to the HTTPS mode using a private key and certificate:

Stop the Hub service.
Run the following command:

<hub_home>bin/hub.sh 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 the tls-server-cert-private-key-passphrase property to provide the passphrase for the key.
- 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.
  
  When you change the base URL of your Hub installation, you must update the settings for integrations and connected service to use the new URL. This includes settings that are stored in Upsource and YouTrack. If you have enabled auth modules that support OAuth 2.0, you need to generate new client IDs and secrets for each third-party authorization service.
- If you are switching from HTTP to HTTPS mode, you can designate a redirect listen port. This non-secure port receives all HTTP requests and redirects them to the secure listen port. To do so, use tls-redirect-from-http=true and specify a value for the tls-redirect-from-http-listen-port=<your redirect port number> property.
For more information about the parameters that are used in this command, see Configuration Parameters.
Start the Hub service.

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

Configuration Parameters

Property	Value	Description
secure-mode	`disable` \| `tls`	The connection mode that is applied to the Hub server. This property supports the following values: `disable` — TLS is disabled. This is the default value for this property. `tls` — TLS is enabled.
listen-port		The port on which Hub listens to HTTP traffic.
base-url		The URL that end users request to access your Hub installation. For example, `https://hub.mydomain.com`. When the value for the `secure-mode` property is `tls` or your Hub installation is secured behind an SSL-terminating reverse proxy server, the URL should begin with `https`. Otherwise (when running Hub using plain HTTP), the URL begins with `http`.
tls-redirect-from-http	`true` \| `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-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`).
tls-server-cert-folder		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-file		The location of a keystore file in either JKS or PKCS #12 format.
tls-server-cert-keystore-password		Keystore integrity password
tls-server-cert-keystore-key-alias		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-password		Password that protects your server's private key entry in the keystore.
tls-server-cert-key-file		The location of a private key (PKCS #1 or PKCS #8) file, stored in PEM format.
tls-server-cert-file		The location of a certificate file, stored in PEM format.
tls-server-cert-chain-file		The (optional) location of a file that contains the certificate chain, stored in PEM format.
tls-server-cert-private-key-passphrase	string	If 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.

Use this information to configure built-in TLS for installations that run on a Hub version starting from 2018.2 through 2018.4.11214. If you are running a later version of Hub, switch to the tab that shows instructions for Hub versions 2018.4.11214 and later.

To switch to HTTP mode:

Stop the Hub service.
Enter the following command:

<hub_home>/bin/hub.sh configure \ --listen-port=8080 \ [--base-url=<new base URL>] \ --secure-mode=disable

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

When you change the base URL of your Hub installation, you must update the settings for integrations and connected services to use the new URL. This includes settings that are stored in Upsource and YouTrack. If you have enabled auth modules that support OAuth 2.0, you need to generate new client IDs and secrets for each third-party authorization service.

For more information about the parameters that are used in this command, see HTTP.
Start the Hub service

To switch to HTTPS mode using an SSL keystore file:

Create a temporary folder and place the file keystore.jks containing the server's private key and certificate in that folder.
Stop the Hub service.
Run the following command:

<hub_home>/bin/hub.sh configure \ --listen-port=443 \ [--base-url=<new base URL>] \ --secure-mode=tls \ --tls-server-cert-storage-type=keystore \ --tls-server-cert-folder=<folder with file keystore.jks> \ --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 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.
  
  When you change the base URL of your Hub installation, you must update the settings for integrations and connected services to use the new URL. This includes settings that are stored in Upsource and YouTrack. If you have enabled auth modules that support OAuth 2.0, you need to generate new client IDs and secrets for each third-party authorization service.
- If you are switching from HTTP to HTTPS mode, you can designate a redirect listen port. This non-secure port receives all HTTP requests and redirects them to the secure listen port. To do so, use tls-redirect-from-http=true and specify a value for the tls-redirect-from-http-listen-port=<your redirect port number> property.
For more information about the parameters that are used in this command, see HTTPS.
Start the Hub service

To switch to HTTPS mode using a private key and certificate:

Create a temporary folder (let's call it <certificates_folder>) to store the files with private key, certificate, and certificate chain (if any).
Place the private key (in the PEM format) into file <certificates_folder>/privateKey.pem.
Place the server certificate (in the PEM format) associated with the private key into the file <certificates_folder>/certificate.crt.
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.
Stop Hub: <hub_home>/bin/hub.sh stop
Run the following command:

<hub_home>/bin/hub.sh configure \ --listen-port=443 \ --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 the tls-server-cert-private-key-passphrase property to provide the passphrase for the key.
- 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.
  
  When you change the base URL of your Hub installation, you must update the settings for integrations and connected service to use the new URL. This includes settings that are stored in Upsource and YouTrack. If you have enabled auth modules that support OAuth 2.0, you need to generate new client IDs and secrets for each third-party authorization service.
- If you are switching from HTTP to HTTPS mode, you can designate a redirect listen port. This non-secure port receives all HTTP requests and redirects them to the secure listen port. To do so, use tls-redirect-from-http=true and specify a value for the tls-redirect-from-http-listen-port=<your redirect port number> property.
For more information about the parameters that are used in this command, see HTTPS.
Start Hub: <hub_home>/bin/hub.sh start.

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

HTTP

Property	Value	Description
secure-mode	disable	The default value of the property. TLS is disabled by default.
listen-port		The port on which Hub listens to the HTTP traffic.

HTTPS (common properties)

Property	Value	Description
secure-mode	tls	TLS is enabled
tls-server-cert-storage-type	`keystore\|privateKeyAndCert`	Defines the format (storage type) of a server certificate. See descriptions of each storage type below.
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`)
tls-server-cert-folder		Specify the directory that contains server certificate files to be applied to Hub. If you use a keystore format, set the value for the `tls-server-cert-storage-type` to `keystore`. The directory should contain the file `keystore.jks`. If you use the PEM format, set the value for the `tls-server-cert-storage-type` to `privateKeyAndCert`. The directory should contain the files `privateKey.pem`, `certificate.crt`, and `certificateChain.crt` (if applicable).

HTTPS (keystore - additional settings)

Property	Value	Description
tls-server-cert-storage-type	keystore	Use this property if your private key/certificate data is stored in a generated keystore file. In this mode, the server's private key/certificate pair is derived from the keystore.jks file that is stored in the directory that is referenced in the `tls-server-cert-folder` property. The keystore file is saved in either JKS or PKCS #12 format.
tls-server-cert-keystore-password		Keystore integrity password
tls-server-cert-keystore-key-alias		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-password		Password that protects your server's private key entry in the keystore.

HTTPS (privateKeyAndCert - additional settings)

Property	Value	Description
tls-server-cert-storage-type	privateKeyAndCert	In this mode, the server's private key/certificate pair is extracted from the files that are stored in the directory that is referenced in the `tls-server-cert-folder` property. Certificate files are assumed to be stored in PEM format. The private key can be stored in either PKCS #1 or PKCS #8 format.
tls-server-cert-private-key-passphrase	string	If 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.

Property

Value

Description

tls-server-cert-storage-type

privateKeyAndCert

In this mode, the server's private key/certificate pair is extracted from the files that are stored in the directory that is referenced in the tls-server-cert-folder property.

Certificate files are assumed to be stored in PEM format. The private key can be stored in either PKCS #1 or PKCS #8 format.

tls-server-cert-private-key-passphrase

string

If 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: 3 July 2019