YouTrack Standalone 2018.2 Help

Configure Built-in TLS in Command Line

Configuring TLS in your current YouTrack installation

Using the command line, you can switch between the following secure mode configurations:

  • HTTP — default HTTP mode. TLS is disabled
  • HTTPS(keystore) — secure HTTPS mode. TLS is enabled. The private key/certificate data is stored in a keystore file.
  • HTTPS(privateKeyAndCert) — secure HTTPS mode. TLS is enabled. The private key, certificate, and certificate chain(optional) are stored in separate files in the PEM format.
To switch to a desired mode, you need to stop YouTrack and run the configure command defining all the properties required for the configuration of your choice. See below for detailed instructions and a complete list of the properties for each configuration.

To switch to the HTTP mode:

  1. Stop YouTrack: <youtrack_home>/bin/youtrack.sh stop

  2. Enter the following command:

    <youtrack_home>/bin/youtrack.sh configure --listen-port=8080 --secure-mode=disable

  3. Start YouTrack: <youtrack_home>/bin/youtrack.sh start

To switch to the HTTPS (keystore) mode:

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

  2. Stop YouTrack: <youtrack_home>/bin/youtrack.sh stop

  3. Run the following command:

    <youtrack_home>/bin/youtrack.sh configure --listen-port=443 --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]

  4. Start YouTrack: <youtrack_home>/bin/youtrack.sh start

To switch to the HTTPS (privateKeyAndCert) mode:

  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 YouTrack: <youtrack_home>/bin/youtrack.sh stop

  6. Run the following command:
    <youtrack_home>/bin/youtrack.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, also add the tls-server-cert-keystore-key-password property to provide the passphrase for the key.
  7. Start YouTrack: <youtrack_home>/bin/youtrack.sh 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, add the parameters tls-redirect-from-http=true and tls-redirect-from-http-listen-port=<your redirect port number> to the configure command.

Configuration Parameters

HTTP

Property Value Description
secure-mode disable The default value of the property. TLS is disabled by default.
listen-port The port on which YouTrack 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 YouTrack. The directory should contain the file keystore.jks. If you are using the keystore format (the property tls-server-cert-storage-type is set to keystore in that case). The directory should contain the files privateKey.pem, certificate.crt and certificateChain.crt (if any) if you are using the PEM format (the property tls-server-cert-storage-type is set to privateKeyAndCert in that case).

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 will be derived from the file internal/cert/keystore/keystore.jks located in the conf directory. The keystore file is saved in the JKS format.

tls-server-cert-keystore-password Keystore integrity password
tls-server-cert-keystore-key-alias Alias that is associated with the private key/certificate entry in the keystore.
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 taken from the files internal/cert/privateKeyAndCert/privateKey.pem, internal/cert/privateKeyAndCert/certificate.crt that are located in the conf directory. Also, a certificate chain can be defined in the file internal/cert/privateKeyAndCert/certificateChain.crt. All files are assumed to be stored in the PEM format. Private key in PKCS#8 or PKCS#1 format.

tls-server-cert-private-key-passphrase stringIf you use an encrypted private key, then use this property to provide the passphrase that was used for encryption. Supported for both PKCS#8 and PKCS#1 formats.
Last modified: 14 June 2018