Skip to main content

Prepare and install a Medulla relay server

This page describes the steps for preparing a server to become a Medulla relay server.

A relay server is installed as close as possible to the client computers. In particular, it relays communications between the main Medulla server and the computers associated with it.

A Medulla relay server contains the following components, among others:

  • an XMPP server;
  • a relay agent;
  • a Guacamole server.

Note:
This procedure covers preparing the server before installing the Medulla components. Assigning computers to the relay server and synchronizing packages are covered in the following pages of this chapter.


1. Relay server prerequisites

The relay server must meet the following minimum requirements:

Component Requirement
Operating system Debian 12.x
Architecture x86-64
CPU 4 cores
RAM 8 GB
/ partition At least 20 GB – EXT4
/var partition At least 400 GB – XFS

/var storage can also be provided by a dedicated mount point on an external storage array or volume.

Special case – DMZ relay:
The disk space on the DMZ relay server can be reduced to 200 GB for /var.


2. Install Debian

Install Debian 12.x on the x86-64 architecture.

During installation:

  • separate /var from /;
  • use LVM for the volumes;
  • use EXT4 for /;
  • use XFS for /var;
  • install the SSH server;
  • install the standard system utilities.

Important:
The Medulla installation documentation recommends that you do not install any antivirus software or local firewall on the Debian server before installing Medulla.


3. Configure the server name

The relay server must have a full FQDN, consisting of the hostname and the domain.

Example:

relay-paris.example.local

Check the hostname with:

hostname

Then verify the FQDN with:

hostname -f

The result of hostname -f must match the FQDN specified for the relay server.

Important:
The FQDN must be correctly configured before installing Medulla.


4. Verify DNS resolution

Verify that the relay server can resolve the name of the main Medulla server.

For example:

getent hosts MEDULLA_SERVER_FQDN

Also verify that the relay’s FQDN resolves correctly:

getent hosts RELAY_FQDN

Expected result:
The names used by the Medulla infrastructure must resolve correctly to the expected IP addresses.


5. Configure network addressing

The relay server must have a stable network configuration.

Before installation, note and verify:

  • the relay’s IP address;
  • its subnet mask;
  • its gateway;
  • its DNS servers;
  • its FQDN.

To view the configured addresses:

ip addr

To view the routing table:

ip route

6. Create the installation account

As part of an installation performed by the Medulla team, create a user:

medulla

For example:

adduser medulla

This account must have sudo privileges.

Add the user to the appropriate group:

usermod -aG sudo medulla

Automated installation requires sudo access without a password prompt.

Important:
Privileged access must be limited to the account used for the installation and must comply with your organization’s security policies.


7. Install the SSH installation key

For an installation assisted by Medulla, the provided SSH public key must be installed for the medulla account.

Create the SSH directory if necessary:

mkdir -p /home/medulla/.ssh

Then add the provided public key to:

/home/medulla/.ssh/authorized_keys

Set the appropriate permissions:

chown -R medulla:medulla /home/medulla/.ssh
chmod 700 /home/medulla/.ssh
chmod 600 /home/medulla/.ssh/authorized_keys

Note:
Use only the SSH key provided to you for your installation. Do not copy a public key from another document or environment.


8. Verify SSH access

Verify that the SSH server is running:

systemctl status ssh

The service must be running.

Also verify that the installation account can log in via SSH to the relay server.


9. Open network flows

The relay server must be able to communicate with the main Medulla server.

In a dedicated Medulla SaaS infrastructure, the current documentation specifies the following flows.

Medulla server to relay server

Port Protocol / Use
5269 TCP / XMPP
22 TCP / SSH
22000 TCP / Syncthing
8081 TCP / HTTP(S)
9990 TCP / XML-RPC HTTPS

Relay server to Medulla server

Port Protocol / Use
5269 TCP / XMPP
22 TCP / SSH
22000 TCP / Syncthing
8443 TCP / HTTPS
22067 TCP / BEP-Relay/TLS
9999 TCP / XML-RPC HTTPS
7080 TCP / XML-RPC HTTPS

Caution:
This list corresponds to the flows currently documented for adding a relay to a dedicated Medulla SaaS infrastructure. The flows to be authorized may depend on the chosen architecture. For an On-Premise installation, refer to the Medulla network flow diagram corresponding to your architecture.


10. Verify connectivity to the Medulla server

Before installation, verify that the relay server can reach the main Medulla server on the ports required by your architecture.

For example:

nc -zv MEDULLA_SERVER_FQDN 5269
nc -zv MEDULLA_SERVER_FQDN 22000

Add any other ports applicable to your environment.

Expected result:
The necessary connections between the relay and the main Medulla server must be allowed before beginning the software installation.


11. Verify the date and time

Verify that the server’s date and time are correct:

timedatectl

Time synchronization must be working properly.

Tip:
An incorrect system time can cause abnormal behavior with certain authentication mechanisms, certificates, or inter-server communications.


12. Check disk space

Before installation, check the partitioning and available space:

df -hT

In particular, verify that:

  • that / has the allocated space;
  • that /var is properly separated;
  • that /var uses XFS;
  • that its capacity matches the planned size.

To view the volumes and mount points:

lsblk -f

13. Check the server's resources

Check the amount of memory:

free -h

Check the number of available processors:

nproc

For a standard relay server, the expected minimum values are:

  • CPU: 4 cores
  • RAM: 8 GB

14. Check IPv6

Before installing Medulla, the installation documentation recommends checking the Debian server’s IPv6 configuration.

In some environments, an improper IPv6 configuration can cause connectivity or network resolution issues.

If IPv6 needs to be disabled, refer to the Medulla documentation on disabling IPv6 on Debian.


15. Run the pre-installation verification script

Medulla provides a script to check the server configuration before installation.

Download the script:

wget https://dl.medulla-tech.io/nc/check_server_before_install.sh

Make it executable:

chmod +x check_server_before_install.sh

Then run it:

./check_server_before_install.sh

Expected result:
All checks in the script must pass before continuing with the Medulla installation.


16. Information to prepare before installation

Before starting the relay installation, prepare the following information:

Information Example
Hostname relay-paris
FQDN relay-paris.example.local
IP address Relay IP address
Subnet mask Network on which the relay is located
Gateway Server gateway
DNS DNS servers used
Main Medulla server FQDN / IP address
Installation account medulla if assisted installation
SSH key Key provided for installation
Network flows Confirmation of their opening

As part of a dedicated SaaS infrastructure, also prepare the ITSM entity to which the relay must be associated if an entity other than the parent entity is desired.


17. Installing Medulla components

Once the server has been properly prepared, the Medulla software components can be installed.

As part of the dedicated Medulla SaaS procedure, the relay’s software installation is performed by the Medulla team using Ansible.

A Medulla agent is then generated to allow the relevant workstations to connect to this relay.

Note:
The method for installing Medulla components depends on how your infrastructure is deployed. This page focuses primarily on the system preparation that must be completed before this step.


18. Post-installation checks

After installing the relay, do not consider the installation complete until you have verified that it is functioning properly.

In particular, verify:

  • that the relay is accessible;
  • that the expected Medulla components are running;
  • that the relay is communicating with the main Medulla server;
  • that it is properly registered in Medulla;
  • that at least one computer can be associated with it;
  • that the necessary packages can be synchronized;
  • that a test deployment can be performed.

Next:
To perform these checks, see the page “Verifying the proper functioning of a Medulla relay server – Health Check.”


19. Preparation checklist

Check Expected value
OS Debian 12.x
Architecture x86-64
CPU At least 4 cores
RAM At least 8 GB
/ At least 20 GB – EXT4
/var At least 400 GB – XFS
DMZ relay /var can be reduced to 200 GB
FQDN Configured and operational
DNS Resolution working
SSH Installed and accessible
Installation account Configured with the required permissions
SSH key Installed if necessary
Network flows Opened according to the architecture
Date/time Correct and synchronized
Verification script All required tests passed

20. Summary

Before installing a Medulla relay server:

  1. prepare a properly sized Debian 12.x server;
  2. configure the partitioning, specifically setting /var to XFS;
  3. set up a stable FQDN;
  4. verify DNS resolution and routing;
  5. set up the SSH access required for installation;
  6. open the flows corresponding to your architecture;
  7. check system resources and configuration;
  8. run the pre-installation verification script;
  9. install the Medulla components according to the selected deployment method;
  10. finish with a complete Health Check of the new relay.

Recommendation:
Do not begin the relay software installation until the sizing, FQDN, DNS, SSH, storage, and network connectivity checks have been validated. Proper server preparation helps prevent most of the issues encountered during the installation and integration of the relay.