Manage Learn to apply best practices and optimize your operations.

How to perform an in-place upgrade of Lotus Domino server hardware

Because some Lotus Notes and Domino shops have their current server name deeply embedded in their Lotus Notes agents, they cannot replace their server with one that has a new name. This makes a gradual server upgrade impossible. To solve this dilemma, contributor Chuck Connell explains step-by-step how to bring up a new server with the exact same name (server ID) as an old server in order to perform an in-place upgrade of Lotus Domino server hardware.

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, a physical name Cheerios that points to this IP address, and an alias Server1 that points to Cheerios.

  1. 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 address.

    In our example, find references to 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.)


  2. 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.)


  3. Build the new server hardware.


  4. Install the operating system on the new Lotus Domino server, giving it a new local IP address and physical name -- such as and FruitLoops. Boot up the machine and make it available on the network.


  5. Look at the Notes.ini file on Cheerios to see what tasks and options are enabled.


  6. 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).


  7. 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.


  8. 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.


  9. In the server document for NewServer1/Acme, set up restricted access to the server, allowing just LocalDomainServers and LocalDomainAdmins (or their equivalent groups).


  10. 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.


  11. 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.


  12. 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.


  13. 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 fully.


  14. Copy the ID file for the existing server (Server1/Acme) into the Domino data directory on FruitLoops, but do not use it yet there.


  15. 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.


  16. 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.


  17. Drop any open user sessions from Server1/Acme.


  18. Log onto NewServer1/Acme and do a full pull replication from Server1/Acme. Repeat again.


  19. Shut down Lotus Domino on both machines.


  20. 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.


  21. 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 OldServer1/Acme.


  22. 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.


  23. 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 to The goal is for the new machine to appear to Notes to be the old machine when you restart it.)


  24. 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.


  25. Perform basic tests of connectivity and database access to the new Server1/Acme on FruitLoops.


  26. Re-enable user logon to Server1/Acme, by removing the "x_" you prepended to entries in the server access field.


  27. 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 new server.)

    Wait several weeks, and then perform the following operations:


  28. Remove the server and connection documents for NewServer1/Acme and OldServer1/Acme.


  29. Remove entries for NewServer1/Acme and OldServer1/Acme from the group LocalDomainServers (or similar).


  30. Archive databases on Cheerios.


  31. 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.

Dig Deeper on Lotus Notes Domino Deployment and Migration Advice



  • iSeries tutorials's tutorials provide in-depth information on the iSeries. Our iSeries tutorials address areas you need to know about...

  • V6R1 upgrade planning checklist

    When upgrading to V6R1, make sure your software will be supported, your programs will function and the correct PTFs have been ...

  • Connecting multiple iSeries systems through DDM

    Working with databases over multiple iSeries systems can be simple when remotely connecting logical partitions with distributed ...