Skip to main content

Rename the FQDN and Switch to HTTPS on Medulla

Applies to: Medulla
Version: All
Environment: On-Premise
Category: Server Administration

Background

This procedure allows you to change the FQDN (Fully Qualified Domain Name) of a Medulla instance.

Example:

Medulla.old-domain.lan → Medulla.new-domain.fr

The rename_fqdn_and_protocol.py script also allows you to:

  • Automatically modify Medulla configuration files
  • Update the URLs stored in the database
  • Migrate from HTTP to HTTPS
  • Automatically configure Apache for SSL
  • Regenerate Medulla agents with the new FQDN

Important:
Before running the script, the new FQDN must be resolvable via DNS and point to your Medulla server.

Prerequisites

  • The new FQDN must exist in DNS
  • The new FQDN must point to the Medulla server’s IP address
  • The script must be run as root
  • The Python mysql-connector module must be installed
  • For HTTPS: You must have an SSL certificate in PEM format and its unencrypted private key

Recommendation:
Back up the configuration files and the xmppmaster database before running the script.

Download the script

Retrieve the script from the following URL:

https://dl.medulla-tech.io/ma/rename_fqdn_and_protocol.py

Download the script:

wget https://dl.medulla-tech.io/ma/rename_fqdn_and_protocol.py

Then make the script executable:

chmod +x rename_fqdn_and_protocol.py

Display the script's help:

./rename_fqdn_and_protocol.py --help

Change the server's FQDN

To change an existing FQDN:

Medulla.mydomain.lan → Medulla.mydomain.fr

Command:

./rename_fqdn_and_protocol.py \
--old-fqdn medulla.mydomain.lan \
--new-fqdn medulla.mydomain.fr

This command automatically updates:

  • Medulla configuration files
  • Guacamole URLs
  • Apache settings
  • The xmppmaster database
  • The Windows installation script ` install-agent.ps1`
  • URLs used by Medulla services

Propagation to workstations

Each machine’s Guacamole URL is updated in the database with a reconfiguration flag (need_reconf). The new URL is then transmitted to each workstation the next time it checks in with the Medulla server.

Note:
The FQDN change is therefore not immediate on the client side: propagation may take some time depending on how frequently the agents connect. It is normal for some workstations to temporarily still point to the old Guacamole URL.

Switching from HTTP to HTTPS

It is possible to migrate URLs from HTTP to HTTPS simultaneously.

Command:

./rename_fqdn_and_protocol.py \
--old-fqdn medulla.mondomaine.lan \
--new-fqdn medulla.mondomaine.fr \
--new-protocol https

The protocol will be automatically replaced in URLs managed by Medulla. If the --new-protocol option is not specified, the existing protocol is retained.

Note:
For a complete HTTPS configuration, it is recommended that you provide a valid SSL certificate.

Complete example with an SSL certificate

./rename_fqdn_and_protocol.py \
--old-fqdn Medulla.old.fr \
--new-fqdn Medulla.new.fr \
--new-protocol https \
--ssl-pem-chain-filename /root/fullchain.pem \
--ssl-pem-key-filename /root/privkey.pem

The script will automatically perform the following:

  • Enable SSL for Apache
  • Configuration of HTTPS VirtualHosts
  • HTTP → HTTPS redirection
  • Installing the certificates

Regenerating the agents with the new FQDN

If client workstations communicate directly with Medulla via the public FQDN, it is recommended to regenerate the agents so that they automatically use the new DNS name.

Command:

./rename_fqdn_and_protocol.py \
--old-fqdn medulla.mydomain.lan \
--new-fqdn medulla.mydomain.fr \
--update-agent-conf

Information:
This option:

  • Updates the agentconf.ini file
  • Updates the .generation_options file
  • Automatically regenerates the Medulla agents

Note:
The Windows installation script install-agent.ps1 is updated automatically, regardless of whether the --update-agent-conf option is used.

Warning:
After the agents are regenerated, you’ll need to perform the deployment of the new configuration on the workstations so they can continue to communicate with the Medulla server.

Available script options

Argument Required Description
--old-fqdn Yes Current FQDN to be replaced
--new-fqdn Yes New Medulla FQDN
--new-protocol No HTTP or HTTPS. If omitted, the existing protocol is retained
--ssl-pem-chain-filename No PEM SSL certificate (full chain). Requires --new-protocol https
--ssl-pem-key-filename No Unencrypted PEM private key
--update-agent-conf No Regenerates the agents with the new FQDN

What exactly does the script change?

Element Action Performed
relayconf.ini.local Updates the Guacamole URL
xmppmaster.ini.local Updates to the Guacamole / Graph / Render URLs
assessor_agent.ini.local Update the Guacamole URL
xmppmaster database Updates to Guacamole URLs in the machines and relayserver tables, with the " need_reconf" flag
Apache Update ProxyPass / Referer / SSL
Medulla Agents Reconfiguration and regeneration (only with --update-agent-conf)
Windows script install-agent.ps1 Update of the download URL (automatic)

Services Automatically Restarted

While the script is running, the following services are automatically restarted:

  • pulse-xmpp-agent-relay
  • mmc-agent
  • pulse-xmpp-master-substitute-assessor
  • apache2

Warning:
A brief service interruption may occur while the script is running.

Special case: remote assessor

If the assessor server is hosted on a remote server, the script will not be able to automatically update the following file:

/etc/pulse-xmpp-agent-substitute/assessor_agent.ini.local

In this case, the change must be made manually on the affected server. This failure does not interrupt the script’s execution: the subsequent steps proceed as normal.

Error Handling

In the event of a failure, the script stops immediately (except in the case of the remote assessor described above).

Important:
The script does not perform any automatic rollback.

Changes that have already been applied remain in effect. Once the problem has been corrected, the script can be rerun safely: the operations are idempotent, meaning that a replacement that has already been performed has no effect (however, the affected services will be restarted).

Default Values

Element Value
SQL host localhost
SQL Port 3306
SQL User mmc
Protocol Retained if not specified
HTTPS Optional
Agent regeneration Disabled without --update-agent-conf

Note:
SQL connection settings are read from /etc/mmc/plugins/xmppmaster.ini (and .local if it exists). The values above apply only if they are not defined there.

Back to top