Qlik Sense Enterprise on Windows: Change hostname (and certificates) after an installation

[Andre_Sostizzo]

The hostname in Qlik Sense is determined by the content of host.cfg.  In order to change the hostname you must change the value in this file. This will also result in all certificates being invalidated. 

Once invalidated, they need to be recreated and any passwords stored in the database will need to be reset (e.g Data Connections and User Directory Connector credentials). Passwords are encrypted based on the server certificates. 

Please note the information in this article pertains to steps when changing the server hostname only, and not the Windows domain to which it is joined. When changing the domain please see the links below for more information:

• Qlik Sense and changing the Active Directory Domain name
• How and When to Contact the Consulting Team?

Environment:

• Qlik Sense Enterprise on Windows, all versions

 

For Video transcript click here.

 

For Single Node Environments: (only Central node exists)

1. Change hostname in Windows as usual.
2. Restart the server as required by Windows.
3. Log in as the service account.
4. Stop all the Qlik Sense services, except for the Qlik Sense Repository Database.
5. Use Microsoft Management Console(MMC) to backup and then delete all the Qlik Sense related certificates (client, server, trusted root). See Backing up certificates - Qlik Sense for Administrators 
6. Delete or rename the folder %ProgramData%\Qlik\Sense\Repository\Exported Certificates\.Local Certificates
7. Make a copy of %ProgramData%\Qlik\Sense\Host.cfg and rename the copy to Host.cfg.old
8. Host.cfg contains the hostname encoded in base64. You can generate this string for the new hostname using a site such as base64encode or by running the following PowerShell scriptlet:

   [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("yourServerHostname.yourDomain.com"))

9. Open Host.cfg and replace the content with the new string.
10. Finalize:
    
    Instead of starting the Repository Service directly, run Windows Command Prompt as Administrator and execute the following command:
    
    "C:\Program Files\Qlik\Sense\Repository\Repository.exe" -bootstrap -restorehostname -standalone
    
    Note: If the script doesn't get to "Bootstrap mode has terminated. Press ENTER to exit.." and gets stuck at "[INFO] Entering main startup phase.." start the "Qlik Sense dispatcher service" and it will get to the end)
    
    
11. Start all the Qlik Sense services in the proper order. If the Qlik Logging Service (Centralized logging database) has been installed see Error 1064 Unable to start Qlik logging service after hostname was changed. Also see Manual Start and Stop order of Qlik Sense services.
12. Keep in mind: The central certificate is used to encrypt password strings being used in connectors, so changing this certificate means that you will need to recreate all connectors that include password information.  See related article Reload of the Operations Monitor app or other monitoring apps fail with 401 (Unauthorized)  The steps for resetting passwords are also mentioned in the following article Repository System Log Shows Error "Not possible to decrypt encrypted string in database".

Correcting Share paths if it is shared on the Central Node:

1. Test the share locally and from any RIM nodes in the environment and re-share the path if needed.
   
   • Right Click on the Windows Icon > Computer Management > Shared Folders > Shares
     • Be sure to note the permissions on the share so that they can be replicated later
   • Right click on the Share > Stop Sharing
   • Navigate to the Share path and reshare with the same permissions as before
   • Validate permissions in Computer Management
2. Use the QlikSenseUtil at C:\Program Files\Qlik\Sense\Repository\Util\QlikSenseUtil\QlikSenseUtil.exe to inject in the new share path. Note: Use alternative installation path if Qlik Sense is not installed to C:\Program Files
   
   1. First, connect to the database under the Connect to database tab.  For Host Name type the new Central node FQDN. Use the default postgres Database user and the password created during the Qlik Sense installation.
   2. In the Service cluster tab, click OK to retrieve the current Share paths. 
   3. Change them to include the new hostname and click Save.
   4. Click Clear and then OK once more to confirm the new paths have been saved to the database.

3. Update the Qlik Sense Data connections via the Qlik Management Console (QMC):

   • ArchivedLogsFolder: Path to share needs to be updated with the new hostname manually via QMC > Data connections > ArchivedLogsFolder > Connection string
   • AttachedFiles:  Path to share needs to be updated with the new hostname manually via QMC > Data connections > AttachedFiles > Connection string
   • DataPrepAppCache: Path to share needs to be updated with the new hostname manually via QMC > Data connections > DataPrepAppCache > Connection string

Repository Database consideration:

The relevant tables in the repository database that contain the host name information are:
LocalConfigs ( Hostname column )
ServerNodeConfigurations ( Host Name )
Note: Please make sure that the above table hostname column should contain the correct server FQDN ( network host name and not the individual machine host name ) this should be exactly the hostname that is in the host.config file
Note : LocalConfigs table has been removed in Qlik Sense Enterprise February 2019 and newer.

For Multi-Node Environments:

There are three possible scenarios in a multi-node environment. Changing the hostname for a Rim node only, the hostname of the Central node, or both. Certificates are always generated by the central node and are based on hostname so the change of hostname on the Central node consumes more time, will require redistribution, and in some cases also the deletion and re-adding of node information.

 

Changing only the Rim Node Hostname

On the Rim node:

1. Change hostname in Windows as usual.
2. Restart the server as required by Windows.
3. Log in as the service account
4. Stop all the Qlik Sense services
5. Use Microsoft Management Console (MMC) to delete all the Qlik Sense related certificates.
6. Delete %ProgramData%\Qlik\Sense\Repository\Exported Certificates\.Local Certificates
7. For backup purposes, make a copy of %ProgramData%\Qlik\Sense\Host.cfg and rename the copy to Host.cfg.old
8. Host.cfg contains the hostname encoded in base64. You can generate this string for the new hostname using a site such as base64encode or by running the following PowerShell scriptlet:

   [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("qlikserver.domain.local"))

9. Open Host.cfg and replace the content with the new string
10. Start up Qlik Sense, when it fails to find the certificates it will enter set up mode

Unfortunately it is not possible to adjust the hostname of a node in QMC, so a when a Rim node's hostname is changed you have to then delete and re-add it with the steps below.

On the Central server:

1. Open Qlik Management Console (QMC)
2. Click Nodes
3. Select the node whose hostname has changed
4. Click Delete
5. Confirm your decision
6. Click Create New
7. Fill in the node details as appropriate and redistribute the certificates to the Rim node.
8. You will need to recreate and/or modify any rules that specifically named the old node.

 

Changing Central Node Hostname

All certificates used by Qlik Sense are created and signed by the central node and are based on its hostname, changing the hostname on the central node and recreating all self-signed certificates breaks this chain of trust and thus all certificates on all rim nodes will need to be recreated and redistributed.

On every Rim node:

1. Stop all Qlik Sense services
2. Open Microsoft Management Console(MMC) using the Qlik Sense service account, backup, and delete all the Qlik Sense related certificates. See Backing up certificates - Qlik Sense for Administrators 
3. Delete  or rename %ProgramData%\Qlik\Sense\Repository\Exported Certificates\.Local Certificates
4. Start Qlik Sense services
5. Upon starting without certificates they will enter Setup mode, meaning they will be listening for new certificates.
6. Complete the steps bellow On the central node and then continue on the steps for the rim node Back on the Rim node(s) that follows.

On the central node:

1. Change hostname in Windows as usual.
2. Restart the server as required by Windows.
3. Stop all the Qlik Sense services, except for the Qlik Sense Repository Database
4. Open Microsoft Management Console(MMC) using the Qlik Sense service account, backup, and delete all the Qlik Sense related certificates. See Backing up certificates - Qlik Sense for Administrators 
5. Delete  or rename %ProgramData%\Qlik\Sense\Repository\Exported Certificates\.Local Certificates
6. Make a copy of %ProgramData%\Qlik\Sense\Host.cfg as Host.cfg.old
7. Host.cfg contains the hostname encoded in base64. You can generate this string for the new hostname using a site such as base64encode or by running the following PowerShell scriptlet below:

   [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("qlikserver.domain.local"))

8. Open Host.cfg and replace the content with the new string.
9. Finalize:
   
   Instead of starting the Repository Service directly, run Windows Command Prompt as Administrator and execute the following command:
   
   "C:\Program Files\Qlik\Sense\Repository\Repository.exe" -bootstrap -restorehostname -standalone
   
   Note: If the script doesn't get to "Bootstrap mode has terminated. Press ENTER to exit.." and gets stuck at "[INFO] Entering main startup phase.." start the "Qlik Sense dispatcher service" and it will get to the end)
10. Start all the Qlik Sense services in the proper order. If the Qlik Logging Service (Centralized logging database) has been installed see Error 1064 Unable to start Qlik logging service after hostname was changed. Also see Manual Start and Stop order of Qlik Sense services.
11.  Confirm the new certificates are created and QMC is accessible.
12. In the QMC under Nodes, select each Rim node and click Redistribute, and follow the instructions displayed in order to install the certificates on the Rim node.
13. Perform the steps under "Correcting Share paths if it is shared on the Central Node" above under the Single Node section.
14. Also if Centralized logging is enabled, the following Data Connection host value needs to be updated:
    
    QLogs: Updated with the new hostname manually via QMC > Data connections > QLogs > Connection string
    
    
15. 15. Change the 'trustedLocations' and 'url' values in all the monitor_REST_* Data Connections to the new Fully Qualified Domain Name (FQDN). Any other Qlik Sense Data Connections' Connection string need to be updated to have these values in the Connection string set to the new FQDN of the Central node. These are listed in QMC under the Data Connections section. See example under How to set up Monitoring Apps in a clustered environment 
16. Keep in mind: The central certificate is used to encrypt password strings being used in connectors, so changing this certificate means that you will need to re-type and save the passwords for all Data Connections and User Directory Connectors that include password information. See related article Reload of the Operations Monitor app or other monitoring apps fail with 401 (Unauthorized)  The steps for resetting passwords are also mentioned in the following article Repository System Log Shows Error "Not possible to decrypt encrypted string in database".

Back on the Rim node(s):

1. Stop all Qlik Sense services on the Rim node.
2. Open the file C:\Program Files\Qlik\Sense\Repository\Util\QlikSenseUtil\QlikSenseUtil.exe  (default location) and change the FQDN that the Rim node would use to connect to the database. Note: May need to launch this program with administrator rights.
   • Under the Connection String Editor, update the Host='<hostname' parameter with the new Central node FQDN / hostname for all databases. (e.g. Database=QSR, QSMQ, etc)
3. Test if DNS records have been updated in the environment. Otherwise, as a temporary workaround determine the IP address for the Central node and modify the Windows hosts file for both the hostname and FQDN.
4. In a multi-node Qlik Sense environment, if the postgreSQL databases are on the Central node, update the hostname used by the RIM node's service to connect to these databases (e.g:  Licenses, QSR, SenseServices, and QSMQ) on the Central node.  The following PowerShell script can be run to update the hostname information. (Note: subsitute MyPassword with the superuser password configured during installation and localhost with the new FQDN string for the Central node). For an alternative and more information see Postgres database moved to new host but some Qlik Sense is still accessing the old database 
   

   # Set the Installation Directory for Qlik Sense
   $installDir = 'C:\Program Files\Qlik\Sense\'
   # Specify the new password for the qliksenserepository account
   $password = 'MyNewPassword'
   $files = Get-ChildItem -Path $installDir -Include Configure-Service.ps1 -Recurse
   foreach ($file in $files) {
       $ScriptToRun=$($file.FullName)
       &$ScriptToRun localhost 4432 qliksenserepository $password
   }​

5. The RIM node points to a FQDN for connections to the QSR database. This is different than in a Single Node environment with postgreSQL installed locally where 'localhost' is used in the connection strings instead of the FQDN to connect to the database. So the listen_addresses setting in the postgres.conf file on the central node needs to be updated if in fact the postgreSQL (QSR) database is hosted on the Central node. The article on step 7 covers this as well. For more information see PostgreSQL: postgresql.conf and pg_hba.conf explained
6. Start all the Qlik Sense services in the proper order. See Manual Start and Stop order of Qlik Sense services .
7. If Centralized Logging / Logging Database is enabled in the environment, follow the steps documented in Error 1064 Unable to start Qlik logging service after hostname was changed.
8. Validate that in the QMC, the node is registered as online in the Nodes section.

 

Repository Database consideration:

the relevant tables in the repository database that contain the host name information are:
LocalConfigs ( Hostname column )
ServerNodeConfigurations ( Host Name )
Note: Please make sure that the above table hostname column should contain the correct server FQDN ( network host name and not the individual machine host name ) this should be exactly the hostname that is in the host.config file
Note : LocalConfigs table has been removed in Qlik Sense Enterprise February 2019 and newer.

Related Articles:

• Convert Qlik Sense Users To New User Directory
• Error 1064 Unable to start Qlik logging service after hostname was changed

[dtbit123]

if i understand,

this a greate article , BUT  you forget to change the share directory.

beacuse its still look to the old share 

[Sonja_Bauernfeind]

Hello @Qlik_FZ 

Either method can be performed first. It depends on the order in which your IT wishes to migrate the server (to a new domain first or rename first, then move to a new domain). If you require direct guidance on how to perform this activity, we recommend either posting about it in detail in our Deployment and Management forum, where you have access to our larger userbase, or to contact out consulting services for direct help.

All the best,
Sonja