Does this site look plain?

This site uses advanced css techniques

The Evolution payroll service-bureau system hosts the database on one or more Linux system, and though all systems are given a name at the initial setup time, occasionally tech staff may need to change the machine's hostname.

This can be done, but it must be done properly.

Changing the hostname of a Linux server while any part of Firebird is running will assuredly lead to catastrophic database corruption.

Firebird and Shared Memory

Evolution and Firebird

This Evo Tip is mainly written for the Evolution community that relies on this software for their payroll businesses, but the narrative applies to any software running Firebird on Linux systems. Hence, this page may receive visits from those who don't have these environments.

Evolution relies on Firebird 2.0 and typically runs on Red Hat Enterprise Linux or CentOS Linux.

When Firebird is running, there is one lock manager (fb_lock_mgr) and usually many database server processes (fb_inet_server) running; this is normal.

In order to coordinate access to common resources, the system incorporates the use of a lock table. The oversimplified description is that when one server process requires access to a certain part of a DB file, it places a marker in the lock table representing the desired location.

While the marker is in place, the "owner" of the lock can do what it wishes with the block of data, and other processes who need that same chunk wait in line. When the first process is done, its marker is removed and the next one in line gets to place his marker and take a turn.

This is a robust locking system with a very long history of reliabilty.

Though Linux (and its predecessor UNIX) have long supported the notion of pure shared memory segments (which live only in memory), Firebird instead uses a mapped file, where the data lives both in the filesystem and in memory.

The file /opt/firebird/isc_lock1.hostname is created in the filesystem — it's just an ordinary binary file — but each Firebird process uses the mmap() system call to map the file into the process's address space.

With this technique, each Firebird program accesses the lock table via regular memory pointers, but changes to the table are reflected immediately in the tables mapped in all other Firebird processes as well. It truly is shared memory.

The problem: the name of this shared memory file is based on the system's hostname, and if the hostname changes, future Firebird processes will use a different shared memory filename than all the current ones are using. This means that "old" processes and "new" processes will not be cooperating for access to common database blocks.

The result is uncoordinated access, and it produces database corruption sufficiently extensive that it will require restoring from a recent backup. This is universally devastating corruption.

Only if there are no Firebird processes running can this name be changed, such that the first process starting up will initialize the shared memory table/file properly.

How to change the hostname - method 1

The safest way to change a hostname is to edit the file /etc/sysconfig/network and change the value of the HOSTNAME variable, then save the file:

/etc/sysconfig/network
NETWORKING=yes
HOSTNAME=evodb1.stevepay.lan
NOZEROCONF=yes
GATEWAY=192.168.1.1

This change by itself doesn't change the current running hostname, it only says what will take effect on the next reboot, which can be queued up at a convenient time.

The reboot gracefully terminates any existing DB connections, and after coming back up, the new hostname takes effect without any remnants of the old one, so there won't be an contention for shared memory lock tables.

How to change the hostname - method 2

This can be done safely without rebooting, though in practice it's not a bad idea to reboot soon, when it's convenient.

As noted, it's not a bad idea to reboot later at a convenient time, perhaps in conjunction with Linux updates.

First Published: 2013/04/08