# Configure 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 YouTrack 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](https://en.wikipedia.org/wiki/Keystore) or [PKCS #12](https://en.wikipedia.org/wiki/PKCS_12) format. * A private key, certificate, and (optional) certificate chain as separate files in [PEM](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail) format. | To switch modes, stop YouTrack 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. ## Switching to HTTP Mode When you run YouTrack with plain HTTP mode, the connections between web browsers and your server are not secured over SSL/TLS. YouTrack is also optimized to use the HTTP/2 protocol, which most servers only support for HTTPS connections. For optimal performance, strongly advise against using plain HTTP. The one case where it's safe to switch from HTTPS mode to HTTP is when you modify your server environment to use an SSL-terminating reverse proxy. In this case, you switch YouTrack to run in HTTP mode. Instead of using built-in TLS, you configure the reverse proxy to secure your server traffic and support HTTP/2 connections. Procedure: To switch to HTTP mode: 1. Stop YouTrack: Linux (Bash): ```CONSOLE docker exec stop ``` Windows (PowerShell): ```CONSOLE docker exec stop.cmd ``` 2. Run the following command: > **Note:** > To make sure you see information that is relevant to your installation, select the tab that corresponds with the operating system used in your host environment. Linux (Bash): ```CONSOLE docker run --rm -it \ -v :/opt/youtrack/conf \ jetbrains/youtrack: \ configure \ --listen-port=8080 \ --base-url= \ --secure-mode=disable ``` Windows (PowerShell): ```CONSOLE docker run --rm --it ` -v :/opt/youtrack/conf ` jetbrains/youtrack: ` configure ` --listen-port=8080 ` --base-url= ` --secure-mode=disable ``` If the server base URL changes as a result of switching to HTTP mode, use the `--base-url=` parameter to set this value. > **Note:** > When you change the base URL, you need to re-register YouTrack in each of the services that are integrated with your installation. This includes generating new client IDs and secrets for third-party authentication modules and access tokens for VCS and build server integrations. For more information about the parameters that are used in this command, see [Configuration Parameters](#configure-properties). 3. Start YouTrack: ```CONSOLE docker start ``` ## Switching to HTTPS Mode The `configure` command lets you switch from HTTP to HTTPS mode. To enable secure HTTPS mode, you need to provide YouTrack with a private key and certificate. You can supply the private key and certificate as: * A keystore that contains private key/certificate data in [JKS](https://en.wikipedia.org/wiki/Keystore) or [PKCS #12](https://en.wikipedia.org/wiki/PKCS_12) format. * A private key, certificate, and (optional) certificate chain as separate files in [PEM](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail) format. Before you start, copy your secure files to a location that is available to your YouTrack server. For a Docker installation, use the paths inside the container when you set the values for TLS-related parameters. If your certificate files are stored outside the host directory that is mapped to `/opt/youtrack/conf`, mount an additional host directory that contains these files and use the mounted path in the command. The `configure` command supports different properties that are specific to these file types. Follow the procedure that is applicable for the type of files that are available to you. You can also follow these procedures if you have already configured HTTPS and simply want to apply a new certificate and private key to your YouTrack server. Procedure: To switch to HTTPS mode using an SSL keystore file: 1. Stop YouTrack: Linux (Bash): ```CONSOLE docker exec stop ``` Windows (PowerShell): ```CONSOLE docker exec stop.cmd ``` 2. Run the following command: > **Note:** > To make sure you see information that is relevant to your installation, select the tab that corresponds with the operating system used in your host environment. Linux (Bash): ```CONSOLE docker run --rm -it \ -v :/opt/youtrack/conf \ jetbrains/youtrack: \ configure \ --listen-port=443 \ --base-url= \ --secure-mode=tls \ --tls-server-cert-keystore-file= \ --tls-server-cert-keystore-password= \ --tls-server-cert-keystore-key-alias= \ [--tls-server-cert-keystore-key-password=] \ --tls-redirect-from-http=<[true|false]> \ [--tls-redirect-from-http-listen-port=8080] ``` Windows (PowerShell): ```CONSOLE docker run --rm --it ` -v :/opt/youtrack/conf ` jetbrains/youtrack: ` configure ` --listen-port=443 ` --base-url= ` --secure-mode=tls ` --tls-server-cert-keystore-file= ` --tls-server-cert-keystore-password= ` --tls-server-cert-keystore-key-alias= ` [--tls-server-cert-keystore-key-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=` parameter to set this value. > **Note:** > When you change the base URL, you need to re-register YouTrack in each of the services that are integrated with your installation. This includes generating new client IDs and secrets for third-party authentication modules and access tokens for VCS and build server integrations. * 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=` property. For more information about the parameters that are used in this command, see [Configuration Parameters](#configure-properties). 3. Start YouTrack: ```CONSOLE docker start ``` Procedure: To switch to the HTTPS mode using a private key and certificate: 1. Stop YouTrack: Linux (Bash): ```CONSOLE docker exec stop ``` Windows (PowerShell): ```CONSOLE docker exec stop.cmd ``` 2. Run the following command: > **Note:** > To make sure you see information that is relevant to your installation, select the tab that corresponds with the operating system used in your host environment. Linux (Bash): ```CONSOLE docker run --rm -it \ -v :/opt/youtrack/conf \ jetbrains/youtrack: \ configure \ --listen-port=443 \ --base-url= \ --secure-mode=tls \ --tls-server-cert-key-file= \ --tls-server-cert-file= \ [--tls-server-cert-chain-file=] \ --tls-redirect-from-http=<[true|false]> \ [--tls-redirect-from-http-listen-port=8080] ``` Windows (PowerShell): ```CONSOLE docker run --rm --it ` -v :/opt/youtrack/conf ` jetbrains/youtrack: ` configure ` --listen-port=443 ` --base-url= ` --secure-mode=tls ` --tls-server-cert-key-file= ` --tls-server-cert-file= ` [--tls-server-cert-chain-file=] ` --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=` parameter to set this value. > **Note:** > When you change the base URL, you need to re-register YouTrack in each of the services that are integrated with your installation. This includes generating new client IDs and secrets for third-party authentication modules and access tokens for VCS and build server integrations. * 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 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=` property. For more information about the parameters that are used in this command, see [Configuration Parameters](#configure-properties). 3. Start YouTrack: ```CONSOLE docker start ``` ## Update a TLS Server Certificate In situations where the TLS certificate that secures your YouTrack server is about to expire or has past its expiry date, you can update it directly from the command line. Given that the current TLS certificate has already been configured, you only need to specify the certificate files in the command. All other parameters can be safely ignored. PEM: Procedure: To update a certificate using a private key and certificate in PEM format: 1. Stop YouTrack: Linux (Bash): ```CONSOLE docker exec stop ``` Windows (PowerShell): ```CONSOLE docker exec stop.cmd ``` 2. Run the following command: > **Note:** > To make sure you see information that is relevant to your installation, select the tab that corresponds with the operating system used in your host environment. Linux (Bash): ```CONSOLE docker run --rm -it \ -v :/opt/youtrack/conf \ jetbrains/youtrack: \ configure \ --tls-server-cert-key-file= \ --tls-server-cert-file= \ [--tls-server-cert-chain-file=] ``` Windows (PowerShell): ```CONSOLE docker run --rm -it ` -v :/opt/youtrack/conf ` jetbrains/youtrack: ` configure ` --tls-server-cert-key-file= ` --tls-server-cert-file= ` [--tls-server-cert-chain-file=] ``` If the private key is encrypted, use the `tls-server-cert-private-key-passphrase` property to specify the passphrase for the key. 3. Start YouTrack: ```CONSOLE docker start ``` JKS or PKCS #12: Procedure: To update a certificate stored in JKS or PKCS #12 format: 1. Stop YouTrack: Linux (Bash): ```CONSOLE docker exec stop ``` Windows (PowerShell): ```CONSOLE docker exec stop.cmd ``` 2. Run the following command: > **Note:** > To make sure you see information that is relevant to your installation, select the tab that corresponds with the operating system used in your host environment. Linux (Bash): ```CONSOLE docker run --rm -it \ -v :/opt/youtrack/conf \ jetbrains/youtrack: \ configure \ --tls-server-cert-keystore-file= \ --tls-server-cert-keystore-password= \ --tls-server-cert-keystore-key-alias=] [--tls-server-cert-keystore-key-password=] ``` Windows (PowerShell): ```CONSOLE docker run --rm -it ` -v :/opt/youtrack/conf ` jetbrains/youtrack: ` configure ` --tls-server-cert-keystore-file= ` --tls-server-cert-keystore-password= ` --tls-server-cert-keystore-key-alias=] ` [--tls-server-cert-keystore-key-password=] ``` 3. Start YouTrack: ```CONSOLE docker start ``` ## Configuration Parameters The following table provides a list of parameters that you can use to configure built-in TLS. | Property | Value | Description | | --- | --- | --- | | secure-mode | `disable` \| `tls` | The connection mode that is applied to the YouTrack 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 YouTrack listens to HTTP traffic. | | base-url | | The URL that end users request to access your YouTrack installation. For example, `https://youtrack.mydomain.com`. * When the value for the `secure-mode` property is `tls` or your YouTrack installation is secured behind an SSL-terminating reverse proxy server, the URL should begin with `https`. * Otherwise (when running YouTrack 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](https://en.wikipedia.org/wiki/Keystore) or [PKCS #12](https://en.wikipedia.org/wiki/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](https://en.wikipedia.org/wiki/PKCS_12) format, follow these guidelines: * Use the value 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](https://en.wikipedia.org/wiki/PKCS_1) or [PKCS #8](https://en.wikipedia.org/wiki/PKCS_8)) file, stored in [PEM](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail) format. | | tls-server-cert-file | | The location of a certificate file, stored in [PEM](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail) format. | | tls-server-cert-chain-file | | The (optional) location of a file that contains the certificate chain, stored in [PEM](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail) 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](https://en.wikipedia.org/wiki/PKCS_1) and [PKCS #8](https://en.wikipedia.org/wiki/PKCS_8) formats. |