For the complete documentation index, see llms.txt. This page is also available as Markdown.

Nodeum Server IP Migration Guide

Overview

This guide describes the process for migrating a Nodeum Data Archiving server to a new IP address.

Pre-Migration Checklist

Current State Assessment

Step 1: Identify Current Configuration

Check the current system IP address:

ip a

Expected output example:

Review the Nodeum environment configuration:

Note all IP addresses that need to be updated:

  • CORE_MYSQL_HOST - MySQL/Database host IP

  • REFPARSER_MYSQL_HOST - LTFS reference parser database host

  • SOLR_HOST - Solr search engine host IP

  • CATALOG_INDEXER_MYSQL_HOST - Catalog indexer database host IP

Migration Steps

Step 2: Update System Network Configuration

Change the system IP address to the new IP on the network interface (e.g., using nmtui, nmcli, netplan, or any OS network manager software).

Verify the change:

Step 3: Update Nodeum Environment Configuration File

Update /etc/nodeum_env to replace all occurrences of the old IP address with the new IP address.

Original entries (example with old IP 10.3.1.175):

Updated entries (example with new IP 10.3.1.30):

To update the file:

Edit with nano or vi:

Or use sed to replace all occurrences (replace 10.3.1.175 with 10.3.1.30):

Verify the changes:

Step 4: Re-apply Ansible Playbook

After updating the configuration file, re-apply the Ansible playbook that was originally used to configure this server. This ensures all services are properly restarted and configured with the new IP addresses.

Identify the playbook location and name:

Execute the playbook:

Expected output: The playbook should complete successfully with no errors. Services will restart during this process.

Step 5: Verify Services Are Running

After the playbook completes, verify all Nodeum services are running in accessing the UI / services page.

Step 6: Verify Configuration Loaded

Confirm Nodeum environment is using the updated configuration:

Should show the new IP address:

Post-Migration Validation

Troubleshooting

Services Not Starting

  • Verify all IPs in /etc/nodeum_env are correct

  • Ensure network connectivity: ping 10.3.1.30

  • Re-run the Ansible playbook

MySQL Connection Errors

  • Verify MySQL is listening on the new IP: netstat -tlnp | grep 3306

  • Check MySQL configuration for bind address

  • Ensure firewall allows connections to port 3306

Scheduler/Mount/Catalog Indexer Not Running

  • Check their respective listening ports are accessible

  • Review /etc/nodeum_env for correct configuration

  • Check system logs: dmesg or journalctl

Rollback Procedure

If issues occur and you need to rollback:

  1. Restore the original IP address on the network interface

  2. Restore the backup of /etc/nodeum_env with original IPs

  3. Re-run the Ansible playbook

  4. Verify services restart correctly

Key IP References in Nodeum

Service
Configuration Variable
Default Port
Notes

MySQL (Core)

CORE_MYSQL_HOST

3306

Database for core Nodeum services

MySQL (LTFS)

REFPARSER_MYSQL_HOST

3306

Database for LTFS reference parser

MySQL (Catalog)

CATALOG_INDEXER_MYSQL_HOST

3306

Database for catalog indexer

Solr

SOLR_HOST

8983

Search and indexing engine

Scheduler

SCHEDULER_LISTENING

8081

Job scheduling service

Mount

MOUNT_LISTENING

8082

Mount management service

Catalog Indexer

CATALOG_INDEXER_LISTENING

8083

Catalog indexing service

Reference Parser

REFPARSER_LISTENING

8084

LTFS reference parser service

Rails Web UI

NODEUM_RAILS

80/443

Web interface

Notes

  • All internal communication (listening addresses) should remain as 0.0.0.0 unless specified otherwise

  • Only external connectivity references (MySQL hosts, Solr host) need to be updated to the new IP

  • The hostname (NODEUM_RAILS=http://nodeum-host:80) can remain unchanged if DNS is properly configured

  • Database passwords remain unchanged; only IP addresses are modified

  • Services will restart during playbook execution; plan for brief downtime

Support

For additional assistance or complex scenarios, contact Nodeum support with:

  • Current configuration (/etc/nodeum_env)

  • Service logs (journalctl output)

  • Network configuration details

  • Ansible playbook version information

Last updated

Was this helpful?