How to Change Qlik Sense server's hostname recreating certificates
[Video embedded here. Use Insert Video button in the menu bar]
Hello everyone! This video will go through the steps needed to change the hostname of the Qlik Sense Central and Rim server nodes. The steps that will be covered here require recreating all the Qlik Sense self-signed certificates. Keep in mind that when the Qlik Sense self-signed certificates are recreated, stored encrypted passwords for Data Connections need to be re-typed via QMC. So this option may be less attractive with a large number of Data Connections. For an alternative method see the article "How to Change the Qlik Sense server hostname" in Qlik Community. We will start on the Rim node, but if this does not apply to your environment ignore these steps. Change the hostname in Windows. We will change it to qlikserverRim, then restart the server as required by Windows. Log back in as the service account. If the service account is not a local admin as in this case, login with a local administrator account. Stop all Qlik Sense services starting with the Qlik Sense Repository service then the remaining services. Then right-click start and open the command prompt as an Administrator. Use the MMC command to open the Microsoft Management Console and add the Local Computer and Current User Certificates Store snap-ins. Now delete all the Qlik Sense related certificates. You may obtain a backup prior as a precaution as well. See the procedure under Qlik's help site. If logged on with an account other then the Service account, as in this case, hold shift and right-click the Command Prompt taskbar icon in order to open a new instance using the Qlik Sense Service account. Then open a new instance of MMC from the Command Prompt which is running under the Service account. If prompted, type the service account credentials again, and add the Current User certificate store snap-in. This MMC instance will allow for deleting the QlikClient certificate under the service account's personal store as seen here. Next, rename the directory .Local Certificates under this location. (%ProgramData%\Qlik\Sense\Repository\Exported Certificates) Then, make a backup copy of the Host.cfg file under this location. (%ProgramData%\Qlik\Sense). This file contains the hostname encoded in base64. We need to generate a new string for the new hostname using the following PowerShell script: [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("qlikserverRim.domain.local")) Then, copy and replace the string in the hosts file. Now we can start up the Service Dispatcher and Repository services, and when it fails to find the certificates it will enter set up mode. However, in this case we will need to start the repository service using the bootstrap command ("C:\Program Files\Qlik\Sense\Repository\Repository.exe" -bootstrap) since the service account does not have local administrative rights. To confirm Qlik Sense has entered set up mode, use the following netstat command to confirm it is listening on port 4444. Please note that if there is no intention to rename the Central node hostname, the Rim node is now ready to obtain new certificates from the Central node by deleting and re-adding the node with the new hostname. You can skip the next steps related to central hostname changes, and continue later on the video with additional rim node steps. Otherwise, we need to change the Central node hostname first in order to update the certificates before redistributing them to the Rim nodes. Change the Central node hostname in Windows and reboot the server. We will change it to qlikCentral, confirm the changes, and accept the system restart. Log back on to the Central node using the service account. If the service account is not a local administrator on the server, logon with another local admin account. Stop all the Qlik Sense services, except for the Qlik Sense Repository Database. Again we need to delete all self-sign certificates as performed on the Rim node. Right-click start and open the command prompt as an Administrator. Use the MMC command to open the Microsoft Management Console and add the Local Computer and Current User Certificates Store snap-ins. Delete all the Qlik Sense related certificates. You may obtain a backup prior as a precaution as well. See the procedure under Qlik's help site. If logged on with an account other then the Service account, as in this case, hold shift and right-click the Command Prompt taskbar icon in order to open a new instance using the Qlik Sense Service account. Then open a new instance of MMC from the Command Prompt running under the Service account. If prompted, type the service account credentials again, and add the Current User certificate store snap-in. This MMC instance will allow for deleting the QlikClient certificate under the service account's personal store as seen here. Next, rename the .Local Certificates directory in this location. (%ProgramData%\Qlik\Sense\Repository\Exported Certificates\.Local Certificates) Then make a backup copy of the Host.cfg file under this location. (%ProgramData%\Qlik\Sense). This file contains the hostname encoded in base64. We need to generate a new string for the new hostname using the following PowerShell script: [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("qlikCentral.domain.local")) Then, copy and replace the string in the hosts file. On the Command prompt running as Administrator, execute the following command to start the Repository Service in bootstrap mode with the restorehostname switch in order to recreate all the self-signed certificates based on the new hostname. ("C:\Program Files\Qlik\Sense\Repository\Repository.exe" -bootstrap -iscentral -restorehostname) Then immediately start the Dispatcher service and wait for the Repository service bootstrap process to terminate. Start all the remaining Qlik Sense services beginning with the Repository Service. If Centralized logging is enabled, note this error when attempting to start the Qlik Logging Service. In order to resolve this we need to tell the the Logging Service to point to the new Central node hostname. Use the following command to set the new hostname. ("C:\Program Files\Qlik\Sense\Logging\Qlik.Logging.Service.exe" update --hostname QlikCentral.domain.local) Using the "validate" parameter retrieves the current status. (Qlik.Logging.Service.exe validate) If the logging service still cannot be started and fails to validate as shown here, the listen_addresses setting may need to be updated in postgres, under the following location. Note however that regardless if Centralized logging is enabled or not, we need to make sure that the postgresql config file allows for connections to the database using the new hostname. Update the listen_addresses value with the new Qlik Sense Central node FQDN. And then restart the Qlik Sense Repository Database service which restarts all the dependent services. Now we can confirm that the Qlik Logging service can be started as well, and that the validate command parameter returns information about the service. We can confirm also that the new certificates have been created, and that QMC is accessible. It is common to have the Qlik Sense share hosted on the Central node itself. If this is the case the share path needs to be updated in the database. After confirming that the share path can still be accessed from all nodes, and that the service account has full rights to it, use the QlikSenseUtil tool which is located in the following location. (C:\Program Files\Qlik\Sense\Repository\Util\QlikSenseUtil\QlikSenseUtil.exe) First, connect to the database. In this case we can use localhost for address, since the Qlik Sense databases are hosted on the central node. Then under the Service cluster tab, click ok to load the share paths from the database and update the hostname in each of the UNC paths, then click Save. Click Clear, and then OK to confirm the change has been done. We can also confirm in QMC the share path has been updated. Next, we need to update the Data Connections that use the old Central node hostname in the connection string. Here are example ones that use by default either localhost - such as in Single node environments - or, the central node's hostname. Note that the Monitoring apps have two values in the connection string that needs to be updated with the new FQDN. The url, and trustedLocations values. While updating these Data Connections we can re-type the password as well. Remember that this is a requirement since the prior encrypted password stored in the database can no longer be decoded with the new self-signed certificates that were created. Any other custom Data Connection that requires a password will need to have the password retyped, as in this example. The next step is to redistribute the new certificates to any rim nodes present in the environment. Note that this step is required regardless of having a RIM node's hostname changed or not. Remember that the Central node, is the certificate signing authority, and has changed its root CA cert, so any certificates issued to the Rim nodes previously are no longer valid. Since we cannot change the hostname listed in QMC, delete and recreate the node, which triggers the certificate redistribution. Follow the information needed to have the certificates properly installed on the rim node via a web browser on the rim node itself. In some cases, Qlik Sense may be unable to redistribute the certificates to the Rim node. The error shown and others, such as this one indicating port 4444 is unreachable may be displayed. This usually happens due to environmental constraints. One way to workaround this issue to to manually export the certificates from the Central node, and import them on the Rim node. Under Certificates in QMC, for Machine Name type the FQDN of the rim node, check to Include secret key, and export a set of certificates in both Windows and PEM format. Then in MMC, export the QlikServiceCluster certificate, and make sure to include the Private Key in the certificate. If the Rim node is also a Failover Candidate, export the root CA including the Private key, via the MMC. Copy all the exported certificates to the rim node, and via MMC running as the local Administrator, import the client.pfx. Then import the root.cer for a regular Rim node or the root.pfx file that contains the private key for Failover candidate rim nodes. Follow with installing the QlikServiceCluster.pfx file, and then the server.pfx file. In this scenario, the repository service which was in bootstrap mode awaiting for certificates will continue the set up immediately after the server certificate is installed. The .Local Certificate folder should be automatically recreated, and an additional QlikClient cert will be installed in the service account Personal certificate store. This should happen a few seconds after the Repository Service is started. Next on the Rim node, we will need to update the hostname used for database connections. Stop all Qlik Sense rim node services, and Test that the Central node is reachable via the new FQDN in order to rule out DNS environmental issues. Then open the QlikSenseUtil as done prior on the Central node. Under the Connection String Editor, update the Host parameter with the new Central node FQDN in all connection strings used by the Repository Service. Click save, and then Read again to confirm that it has been changed. Next, in order to update the hostname used by other services when connecting to the databases hosted on the Central node, we need to update the appsettings.json files for those services. The appsettings files live in the following locations. (C:\Program Files\Qlik\Sense\) For example, the Licenses service setting file contains two host address fields that need to be updated. The following script available in the article where this video is posted, can edited with the appropriate password and new hostname, and run to make the change for all needed services. By default, when the database is installed on the Central node together with Qlik Sense by the installation wizard, postgres only allows connections to the loopback localhost address. As mentioned prior, it may be necessary to update the listen_addresses setting in the postgres.conf file on the central node, by adding the new Central node's hostname separated by comma or use an asterisk to listen on all local IP addresses. If Centralized logging is enabled on the Rim as well, again use the following command to set the new hostname. ("C:\Program Files\Qlik\Sense\Logging\Qlik.Logging.Service.exe" update --hostname QlikCentral.domain.l) Now we can finally start the Qlik Sense services, starting with the Dispatcher, Repostiroy services, and then the remaining services. Then, validate that the node is registered as online in QMC under Nodes with all applicable services up and running. Keep in mind that since the Rim node had to be recreated, certain settings will need to be reconfigured, such as making sure an engine node is set under that rim node's Virtual Proxy. Also, any other settings and rules that involve the old rim node's name may need to be redone as well.