The best way to replace a Lotus Domino server with a new machine is to bring up the new server alongside the old one. You give the new server a new name within your Lotus Domino domain and replicate the existing databases to the new server.
Users can then gradually begin to use the new Lotus Domino server instead of the old one. In addition to moving users, you also modify nightly agents to run on the new server, change users' home server locations to the new server, change the admin server for databases, etc. You do all of these operations over a period of time, so you can easily roll back if something goes wrong.
When everything is running correctly on the new Lotus Domino server, you simply stop the Domino process on the old server. You keep the old Lotus Domino server's operating system up for a few weeks, just in case you forgot something. After that, you back up the old server's data and shut it down fully. I have performed this kind of Lotus Domino server upgrade many times, with zero disruption to normal user workflow.
Sometimes, however, this gradual process is not viable. Some Lotus Notes and Domino shops are dependent on the exact name of the existing Lotus Domino server and cannot replace that server with one having a new name.
This occurs if the current server name is deeply embedded in many Lotus Notes agents or programs, and it is not realistic to find and change all these lines of code. (Of course, it is poor programming technique to use hard-coded server names, but I will leave that lecture for another time.)
In these situations, the administrator needs to bring up a new Lotus Domino server that has the exact same name (server ID) as the old Lotus Domino server. This tip explains how to do that.
I assume that you have an internal DNS server, so that each computer has a machine name and a network IP address. I also assume that your DNS server allows you to assign aliases for machine names.
If you do not run a full DNS server with these capabilities, you can still perform an in-place Lotus Domino server upgrade, but it is slightly less convenient. I address this issue where relevant in the instructions below.
In this example, let's say that your existing server has a Notes name Server1/Acme, a local IP address of 192.168.1.3, a physical name Cheerios that points to this IP address, and an alias Server1 that points to Cheerios.
- Check the Domino Directory for connection documents or server-network pages that contain
hard-coded IP addresses or machine names. Change these references to the DNS alias, or remove the
network location completely, since Lotus Domino can often find its own servers without a network
In our example, find references to 192.168.1.3 or Cheerios, and replace them with Server1. (If you cannot assign machine aliases, but can assign machine names, look for IP addresses and replace them with the name. If you cannot assign names at all, leave the IP addresses in place.)
- Perform the same check for items in personal address books that contain hard-coded IP addresses
or machine names. Replace with the machine alias. (If you cannot assign machine aliases, but can
assign machine names, look for IP addresses and replace them with the name. If you cannot assign
names at all, leave the IP addresses in place.)
- Build the new server hardware.
- Install the operating system on the new Lotus Domino server, giving it a new local IP address
and physical name -- such as 192.168.1.4 and FruitLoops. Boot up the machine and make
it available on the network.
- Look at the Notes.ini file on Cheerios to see what tasks and options are enabled.
- Make two temporary Lotus Domino server IDs: NewServer1/Acme and OldServer1/Acme. Add both names
to the Domino group LocalDomainServers (or whatever similar group you are using).
- Put the ID file for NewServer1/Acme into the Domino data directory on the new server
(FruitLoops). You may have to create this directory first, since the Lotus Domino software is not
yet installed on this machine.
- Put the ID file for OldServer1/Acme into the Domino data directory of the existing server
(Cheerios). Do not use this ID yet, continuing to run this server as Server1/Acme.
- In the server document for NewServer1/Acme, set up restricted access to the server, allowing
just LocalDomainServers and LocalDomainAdmins (or their equivalent groups).
- Install the Lotus Domino server software on FruitLoops, using the same options and tasks as you
found on Cheerios. During installation, use the ID file for NewServer1/Acme, since this ID is
already installed in the data directory.
- Create a connection document from NewServer1/Acme to Server1/Acme. Make this replication
one-way (pull only) so data flows from the existing server to its new counterpart. Enable
replication every 15 minutes or so.
- Create database replicas from Server1/Acme to NewServer1/Acme. (This is an opportunity to
reduce unneeded databases, by not copying them onto the new server.) For each database being
replicated, make sure its "enable replication" option is set and that it has an ACL entry of
LocalDomainServers=Manager (or whatever similar setting you use). If you do not check the
ACL settings for a server group, the new server may not have permission to copy the databases.
- Test the Notes/Domino applications on NewServer1/Acme. Look in the server logs for any
replication errors. Also check the document counts of key databases to make sure they replicated
- Copy the ID file for the existing server (Server1/Acme) into the Domino data directory on
FruitLoops, but do not use it yet there.
- Inform users that Server1/Acme will be unavailable for several hours at a specified date and
time. In reality, the operation of replacing the old server with the new hardware can often take 10
minutes, but it is safer to allow yourself extra time.
- When the downtime begins, disable normal user logon to Server1/Acme. Do this by changing the
"server access" field in its server document. Prepend "x_" to the front of all the
names and groups being disabled. Do not disable access for yourself or NewServer1/Acme.
- Drop any open user sessions from Server1/Acme.
- Log onto NewServer1/Acme and do a full pull replication from Server1/Acme. Repeat again.
- Shut down Lotus Domino on both machines.
- If Lotus Domino is an automatic system service on Cheerios, disable this service, to make sure
it does not start up again when the machine is rebooted.
- Modify Notes.ini on Cheerios, so if Lotus Domino is restarted manually, it will come up
with the server name OldServer1/Acme. Check the INI lines for KeyFilename,
ServerKeyFilename, CertificateExpChecked, and MailServer. You can comment-out
all of these lines except ServerKeyFilename, which you modify to point to the ID file for
- Now change Notes.ini on FruitLoops to use the ID file for Server1/Acme. Check the INI
lines for KeyFilename, ServerKeyFilename, CertificateExpChecked, and
MailServer. You can comment-out all except ServerKeyFilename, which you modify to point to
the ID file for Server1/Acme.
- Change the DNS entry for the Server1 alias, so it now points to FruitLoops instead of
Cheerios. (If you cannot assign machine aliases, but can assign machine names, rename the new
server from FruitLoops to Cheerios. If you cannot assign names at all, change the IP address of the
new server from 192.168.1.4 to 192.168.1.3. The goal is for the new machine to appear to Notes to
be the old machine when you restart it.)
- Restart FruitLoops. If you have not installed Lotus Domino as an automatic system service,
start Lotus Domino manually on this machine. It should come up with the name Server1/Acme.
- Perform basic tests of connectivity and database access to the new Server1/Acme on FruitLoops.
- Re-enable user logon to Server1/Acme, by removing the "x_" you prepended to entries in the
server access field.
- If you find that you must restart Cheerios as a Lotus Notes server, you can do so manually, and
it will run under the name OldServer1/Acme. (If you did not use machine aliases, be sure to change
the machine name or IP address of Cheerios before you restart it, so it does not conflict with the
Wait several weeks, and then perform the following operations:
- Remove the server and connection documents for NewServer1/Acme and OldServer1/Acme.
- Remove entries for NewServer1/Acme and OldServer1/Acme from the group LocalDomainServers (or
- Archive databases on Cheerios.
- Shut down Cheerios.
About the author: Chuck Connell is president of CHC-3 Consulting, which helps organizations with all aspects of Domino and Notes.
Do you have comments on this tip? Let us know.
Please let others know how useful this tip is via the rating scale below. Do you have a
useful Lotus Notes, Domino, Workplace or WebSphere tip or code snippet to share? Submit it to our tip
contest and you could win a prize.
This was first published in March 2007