Changing Jira environment DNS and Base URL
Platform Notice: Data Center Only - This article only applies to Atlassian products on the Data Center platform.
Note that this KB was created for the Data Center version of the product. Data Center KBs for non-Data-Center-specific features may also work for Server versions of the product, however they have not been tested. Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
Summary
If the DNS records (SMTP, servers FQDN, email domain, etc) of Jira is updated, this article might help you cover the changes required to keep Jira running.
Solution
Environment
Jira's base URL
If the new DNS record is already in place and pointing to the existing server IP, you'll need to update Jira's base URL , if you use a reverse proxy(or a load balancer) that means you'll need to update its value in the connector under Jira_INSTALLATION\conf\server.xml.
Jira's applications link
If you have another system reaching Jira, it needs to be updated that also includes DVCS and the webhooks.
SSL certificates
With the new DNS, the SSL checks will fail for unmatching hostname between what is on the certificate and the destination, the administrator will need to make the following changes :
The administrator needs to recreate/update Jira's truststore and keystore by importing the new certificates ,
The administrator should verify that Jira's base URL have an updated certificate and may use tools such as 'Portecle' or 'Keystore explorer' to search for the existing certificates that have the old DNS , they are candidates for change.
Mail servers
If the change will reach your SMTP/IMAP and they are self-hosted servers, you might want to reimport their certificates, update the incoming and outgoing values from Jira's UI.
Sometimes it is a little complex/time consuming to push a new certificate for the mail server , Jira has a dark feature to stop verifying the SMTP server hostname against the certificate
Do not enable this Dark feature in an environment exposed to the internet, your environment will be at risk of MITM attack.
Visit https://JIRA-BASE-URL/secure/SiteDarkFeatures!default.jspa
Add the following flag com.atlassian.mail.server.managers.hostname.verification.disabled
Disable the feature as soon as the mismatching hostname issue is fixed.
LDAP
Update the directory setup from the menu
User management> user_directories > by setting the new domain controller hostname configured for LDAP connection.
Mobile and MDM
If your user base uses the mobile application and you're pushing the settings using an MDM rule , remember to update the base URL value.
Users mail domain
If you have an ldap connector not a delegated connector this shouldn't be a problem since the synchronization will update the user attributes, otherwise you can run a bulk change
Abstract steps
Backup Jira installation and home directories, the database, the network configuration for your proxy, and the node network configuration (for Linux "/etc/hosts" and for Windows "C:\Windows\System32\drivers\etc\hosts").
Start by listing and finding what needs to be changed from the list above and make sure you acquired the needed certificates and the new DNS entries are live.
Run Jira over HTTP and make sure it's accessible using the new DNS , you can add a new connector if it doesn't already exist.
Recreate/reconfigure java's Keystore and truststore.
Run Jira over SSL.
Update the users emails.
Recreate the applications links.
Reconfigure LDAP / email servers
Validate if everything works fine with new domain URL to ensure correctness, this completes the process.
Was this helpful?