YouTrack Server
 
2019.2
Get YouTrack Standalone
You are viewing the documentation for an earlier version of YouTrack Server. View this page in the current documentation
  1. Installation and Upgrade
  2. Working with External Hub
  3. Update the Certificate for Your Hub Server

Update the Certificate for Your Hub Server

Last modified: 17 December 2019

note

These instructions only apply to YouTrack installations that are connected to an external Hub service.

To exchange information with an external Hub service over a secure connection, YouTrack stores a copy of the SSL certificate for the Hub server in its internal keystore. If the SSL certificate for the Hub server is updated or renewed, YouTrack may no longer trust the connection to the Hub service.

If YouTrack can't establish a trusted connection to Hub, the YouTrack server fails to start. When you try to run YouTrack, you encounter a Server SSL certificate not trusted error. To resolve this issue, you need to import the updated Hub certificate into the internal keystore for YouTrack. This operation is performed by applying a command to the YouTrack server.

There are a few situations where you need to update a Hub certificate in YouTrack.

  • The SSL certificate for your Hub server has expired. You need to replace the expired certificate with a renewed certificate.

  • Hub URL changes because the Hub service is migrated to another server location.

  • You were previously connecting to the Hub service over plain HTTP and have just installed the certificate.

The last two cases also require that you update the URL for your external Hub service in YouTrack. For specific instructions, see Update the URL for your Hub Server.

This procedure requires that you have a copy of your Hub certificate in PEM format. The command described here only imports the certificate. The private key is not required.

To update the SSL certificate for an external Hub server:

  1. Open a command-line interface on the YouTrack server and enter the following command:

    keytool -import -alias hub-<alias> -keystore <youtrack_home>/conf/internal/keystore.jks -file /path/to/imported/certificate

    Replace the command-line parameters with values as described here:

    Parameter

    Description

    alias

    An arbitrary alias name that is assigned to the imported certificate. You can enter any string, but it helps you and other administrators recognize where this certificate came from when you assign it a meaningful value.

    keystore

    The path to the internal keystore file for your YouTrack server. This path is relative to your YouTrack home directory.

    Replace the <youtrack_home> placeholder with the actual path to the YouTrack home directory on your server.

    • For an MSI installation, the <youtrack_home> directory is the location where YouTrack was installed.

    • For a ZIP installation, the <youtrack_home> directory is the location where the ZIP distribution was unpacked during installation.

    If the keystore file doesn't already exist in the specified location, it is created.

    file

    The path to the SSL certificate for your Hub server.

  2. When prompted, enter the password that protects the keystore file. The password is stored as the value for the additional-keystore-password property in the >YouTrack home directory</conf/internal/bundle.properties file.

    • If the password is correct, the properties for the SSL certificate are printed in the console.

  3. When prompted to confirm whether you trust the certificate, enter yes in the console.

    • If the certificate is imported successfully, the message Certificate was added to keystore is printed in the console.

  4. Restart YouTrack.

    • YouTrack uses the updated SSL certificate from the keystore file to authenticate with the Hub server.

The following example shows you what this procedure should look like in a command-line interface. Here, the keytool command is executed in the same directory where the keystore.jks and certificate.crt files are both stored.

> keytool -import -alias hub-<hostname> -keystore keystore.jks -file certificate.crt
Enter keystore password: <keystore password>

Owner: EMAILADDRESS=...
Issuer: EMAILADDRESS=...
Serial number: acee3222e1df2767
...

Trust this certificate? [no]:  yes
Certificate was added to keystore