It’s an age-old problem: you have brought in a shiny new server host that is going to join your Domino environment and eventually replace your wheezing old server whose fans blow out dust that stinks of death. But that old server has accumulated tens or hundreds of databases that need to be moved over to the new server before it can ride off into the sunset. The choices have often been having downtime and client ire for a filesystem-level copy or manually replicating databases over and spending countless hours on the dull task. Fortunately, Domino has the AdminP replica creation tool, which can handle all this for you and, if you know what to look for, is quick and easy to configure.
The very first thing you’ll want to check is that the servers can connect to each other, have access permissions, and have replication scheduled between the two of them.
To verify the servers can connect to each other, the easiest thing is to run a trace from the server console. From either inside the Administrator (under Server -> Status -> Server Console) or directly from the console on the server itself, run a “trace <<REMOTESERVER/ORG>>”. If you are successful, the last lines of the trace should something like this:
Connected to server REMOTESERVER/ORG
Attempting Authenticated Connection
Compression is Enabled
Encryption is Enabled
If this has failed, you may be able to fix it on the connection document, which is the next item we want to look at. From the Domino Administrator or the names.nsf you can find these under Configuration -> Server -> Connections. You will most likely see a section for each server in your domain, and you can hit + (shift-=) in order to expand the listing and see all the connections. You can either create new connections or edit existing documents, but when you’re finished you want to have a connection from your old server to your new server and vice-versa.
In each of these connection documents, there are just a few items on each tab you’ll want to set/verify:
- Basics tab: The source and destination server names and domains should be correct, and if you are unable to trace (per above) without explicitly telling the server the remote server’s location, you should be sure your TCPIP port is specified and the FQDN or IP of the remote server is entered into the Optional network address field.
- Replication/Routing tab: Replication task should be enabled, set to replicate all priority databases and, at least for the duration of the database migration, the Files/Directory paths to replicate should be left blank (to replicate all databases).
- The Schedule tab: Schedule should be Enabled. Connect at times should optimally be for 24 hours a day (12:00 AM – 11:59 PM), but if you are worried about replication affecting performance during the day you can restrict this to overnight hours. The repeat interval can generally be set to 30 minutes, though if you have primarily large databases you may want to slow this to hourly.
- Comments and Administration tabs should require no changes.
Lastly, you’ll want to verify permissions in the server documents. In the server document (Configuration -> Server -> Server Documents) for each server, the opposite server can either be explicitly entered or part of a group that, in the lower-left Server Access section, is listed in the Access Server, Create Databases & Templates, and Create New Replicas fields. If this is not the case, the most reliable method is to add the remote server explicitly, such that Server B/Org is listed in these three fields on the server doc for Server A and vice-versa, though listing LocalDomainServers will generally work, as well. And don’t forget to replicate the names.nsf changes to the other server!
At the end of this section, the trace command from above should work properly, and all the replica creation permissions should be ready.
Part 2: Check database ACLs
Next, you will need to prepare the databases for the replication process. There are three key permissions that will be needed for every database you will migrate:
- The current host must have at least reader permission,
- The remote host must have at least reader permission,
- The AdminP requestor (you, the administrator) must have at least reader permission.
One additional warning: for databases whose administration server (under the Advanced tab of the ACL) is not specified, is in a different domain, or is not a reachable host, LocalDomainServers or similar local groups may NOT be sufficient to meet this demand. If you are concerned about this possibility you can either explicitly add both servers to the ACL or you can test on a smaller set of databases and check whether AdminP throws any errors (covered in Part 4).
Part 3: Generate Create Replica requests
From the Administrator client, open the current server and go to the Files tab. Depending on what your folder structure is like, you may wish to view the databases in All view (immediately to the left of the Tools menu). If you are looking to make the new server a 100% replacement for the existing one, you can hit the All view and then ctrl-A to select all in the files view. Since AdminP will NOT overwrite existing system databases, if the new server is a fresh install this will replicate over all non-default databases without forcing you to manually un-select default system DBs.
When you’ve selected all of the databases you wish to migrate over, open the twisty for the Tools menu in the upper-right, then expand Database and click Create Replica(s). The remote server may already be listed in the field for Create Replicas on these servers, but if not you can choose Other… to manually specify it.
NOTE: If you manually enter the server you will need to specify the full Domino server name, Remote server/Org. Once this is created you should see the Destination database and server box on the right populate with your remote server(s) and databases, then when you hit OK you’ll see these process through in the status bar at the bottom of your administrator.
Part 4: AdminP, Engage!
At this point, the databases should all be prepared to be replicated from your origin server to the destination server, and all that is left should be to run the actual AdminP requests themselves. While these should run within a short time on any server with AdminP enabled, it is quicker to launch this process manually. Open the server console on the origin server and issue “tell AdminP process all.”
You will then see the server reply with one or more messages per database that will each fall into three categories:
- If the servers are not clustered, you will most likely see a green status indicator followed by the message that a create replica request has been created for further processing.
- Qualified success. You may see an indicator that full-text index options differ, that special object cannot be initialized, or similar, followed by an indication that a create replica request has been generated for further processing. While any such instance means you will want to be sure to more carefully check the database’s creation, it generally does not predict a failure.
- This will be followed with a failure reason, typically either that a file with that name already exists (in the case of system databases) or a connection or permission error related to one of the items in Part 1, above.
As long as not all databases failed, the next step is to replicate the admin4.nsf to the destination server; issue a “replicate <<REMOTESERVER/ORG>> admin4” on the server console. You may see some databases begin to initiate already, clearly a good sign, though if you do not it is not yet an indicator that the migration process failed.
Switch to the console for the destination server and then run another “tell AdminP process all”. You will likely see few messages or some database initializations; even if there is no console feedback that may be okay. Then issue a “pull <<REMOTESERVER/ORG” (of course indicating the origin server, here). You should start seeing replicas being created and populating immediately, and can track the progress either through the files view (NOTE: this is not updated in real-time and you will have to refresh or use F9 in order to see the updated files and file sizes) or by issuing a “show tasks” on the server console to see what replication processes are running.
Part 5: Verify Results
While the most obvious indicator of success or failure will be seeing the databases actually created by the end of the previous steps, there are two great ways to double-check the full results or correct any problems.
First, open the admin4.nsf on the origin server, then select Errors by Server from the left-hand view menu. Expand the sections for both your origin and destination servers and the most likely error categories will be “Accelerated Create Replica” or “Check Access for New Replica Creation”. In the former category, you can expect the majority of the errors to be related to files that already exist on the remote server, most frequently system databases. In the Check Access category you are likely to find any files that failed due to any lapses in Part 1, above.
Opening each document, you can see the error field, which generally is populated with good, specific information on why the request failed, whether the source or destination server didn’t have access, whether the requestor didn’t, or whether the source server didn’t have create replica privileges or a connection to the destination. In any of these cases, you should be able to address the specific issue by fixing the ACL, connection, or server permissions per the steps in Part 1, and then once that is done just return to the admin4.nsf, select the documents to be re-run from the Errors view, and then use the Reprocess Selected Requests button from the action bar. These requests will be re-queued anew and you can return to Part 4 to monitor their activity.
Second, once you have finished checking all of the admin4 errors or failures, running a decommission server analysis is a great way to verify your files did make it across successfully. Open the Server tab of Administrator, then the Analysis sub-tab. From the right-side Tools menu, select Analyze -> Decommission Server. Specify Source Server and Target Server as the source and destination servers (NOTE: if your server names are too long to be entered manually you will have to use the drop-down menu to populate these fields. If a server is not listed here opening a database on that server will typically fix this.). Returning the results to a local database is fine, and overwriting the database for each server decommission pair and then appending further reports helps keep organization simple.
Once the decommission analysis report completes, we will want to open the Databases section and look over the Databases – No Matching Replica and Databases – Name Conflict reports. The former will list any databases where a matching replica is not found, most likely due to not having been selected for migration, an AdminP migration failure, or an existing file with the same name. The name conflict report will indicate all databases that have the same name but different replica ID—these will mostly be system databases that should exist as separate replicas on each server, but you’ll want to be certain the names.nsf or admin4.nsf aren’t listed.
Going through these five sections, you should be able to get replication stubs of databases created on a remote server in short order. While the time savings are immediate if you have a large number of databases to move, admins familiar with the steps will generally find them faster than manually creating replication stubs for even as few as 5-10 databases, particularly as parts 1 and 2, generally the most time-consuming, need to be reviewed even for either method.
You can also read on how to migrate Cross-Domain databases using AdminP.