Recover an Incremental Backup

BRMS for IBM i uses the Lotus C backup and recovery APIs to provide backup and restore services for Domino databases. The Lotus C APIs operate on a database level. To recover a document in a database, the entire database must be restored to a point in time when the document was available. If you need to recover a document, while not losing the documents that may have come after this point in time, then you must either restore the database to a different server or restore the database to a different directory, under the data directory of the current Domino server. The desired document or documents can then be copied to the original database. This preserves the original database and allows recovery of the requested documents. The ability to restore to a point in time is available if your currently active Domino server has been previously set up to be incrementally saved, and at least one full save has occurred.

Below are two different sets of instructions documenting how to restore a database so documents can be recovered from that restored database. If you choose to restore the database to a different server, then follow the first set of instructions. If you choose to restore the database to a different directory under the current Domino server, then follow the second set of instructions. Both sets of instructions are designed to guide you in the recovery process of the database. Whichever set of instructions you follow, restoring to a different server or restoring to a different directory under the current Domino server, you should read those instructions in their entirety prior to attempting the restore.

Which recovery process is right for you? There isn't one answer to that, which is why both sets of instructions are described here. Restoring to a different server, while a little more time consuming to set up, may be marginally safer than restoring the database to the same server, but a different directory under the data directory. There is less of a chance of an inadvertent mistake causing you problems on the active Domino server when restoring to a completely different Domino server. Having said that, restoring to the same server, but a different directory under that Domino server, is much quicker to set up, and if no mistakes are made, can be as safe as the option for restoring to a different server. If you are still unsure, read both sets of instructions and then choose which one you want to try.

Recovering a database by restoring the database to a different Domino server:

Steps 1-3 need only be done the first time you set up a recovery Domino server.

Configure a Domino server to be used in this recovery process (this server should never be started, so make sure AUTOSTART(*NO) and STRDOMSVR(*NO) are specified on the CFGDOMSVR command).

To clarify which server is being worked with in the following instructions, this newly configured server will be called the Domino Recovery server. The Domino server that has the database that needs to be recovered will be called the active Domino server. If you have previously created a Domino Recovery server, you can re-use that server without having to configure another Domino recovery server. Just follow the instructions for cleaning up data from previous recovery requests.
Copy the notes.ini database file in the Domino Recovery server to the same data directory and give it a new name.

If you have previously created and used this Domino Recovery server, and copied the original notes.ini, you will not have to make a new copy of the notes.ini. Just follow the instructions in the following steps for editing the notes.ini file.
Make QNOTES the owner of the copied notes.ini via the CHGOWN command.
Edit the current notes.ini of the Domino Recovery server (you can use option 13 off of the WRKDOMSVR screen for this Recovery server). The notes.ini for the Domino recovery server should ONLY have the following lines in it:

[Notes]
Directory=
KeyFilename=
TRANSLOG_Status=1
TRANSLOG_Style=1
TRANSLOG_Path=/
TRANSLOG_MEDIAONLY=1
Timezone=

If you have previously used the Domino Recovery server, or this is the first time using this server, there will be extra lines in the notes.ini that need to be deleted or changed so that you only have the lines identified above in the notes.ini.

Here's a brief description of the data to be filled in:

Directory=
this is the path of the data directory for the Domino recovery server that was specified on the CFGDOMSVR

KeyFilename=
this is a database name and is copied from the Active Domino server

TRANSLOG_Path=/
/ - A subdirectory under the Domino Recovery data directory to contain the active transaction log that is copied from the active Domino server.

Timezone=
The line may be needed to recover a data base to the correct point in time. This line would match the line in the active Domino server that contains the database you wish to restore on this Domino Recovery server. It is optional if you aren't doing point in time recoveries and you can try it without that line. If you are having trouble recovering to the correct point in time, possibly adding this line will help correct that problem.
The needs to be created as a sub directory under the data directory of the Domino Recovery server. If this is the first time using this Domino Recovery server do a: mkdir '/' Replace the '/' with your specific directory values.
Do a: CHGOWN '/' QNOTES to change the owner of the subdirectory to QNOTES.

Replace the '/' with your specific directory values.
In the notes.ini for Domino Recovery server, find the KeyFilename= entry. It should specify a name, usually ending in .id. Find that file under the Domino Recovery server and delete it.
In the notes.ini of the active Domino server, find the KeyFilename= entry. Find that file, usually ending in .id, associated with the active Domino server and copy it (using the CPY command), to the Domino Recovery server's data directory. When using the CPY command you want to specify the following values: TODIR('<path to Domino Recovery server's data directory>') DTAFMT(*BINARY) OWNER(*KEEP). Remember to replace the actual path of Domino Recovery server's data directory in the TODIR parameter.
Verify that the copied file is owned by QNOTES. If the file that was copied is not owned by QNOTES, then do a CHGOWN OBJ('<path to Domino Recovery data directory/<file name>') OWNER(QNOTES). Replace your specific path and file name for the '<path to Domino Recovery data directory/<file name>' in the command.
Change the KeyFilename= entry in the Domino Recovery servers' notes.ini to be the name of the copied file.
Verify that there are no files found under the directory specified by the TRANSLOG_Path=/ entry in the Domino Recovery servers' notes.ini.

The first time you use the Domino Recovery server there won't be any objects in that subdirectory to be deleted. If you have used this Domino Recovery server previously there could be files in that subdirectory and they need to be deleted. Failure to delete these files may cause the recovery process to fail.
An Incremental save must now be done on the active Domino server.

The active Domino server had to previously been setup to support incremental saves. To save the active Domino server incrementally, on a V5R1 or later system, you can issue the command STRBKUBRM and specify ACTIVITY(*INCR). If you are on a V4R5 system, you will have to change the control group appropriately to get an incremental save. This assumes you have a BRMS control group to save this particular active Domino server. This also assumes that a full save had been done on that active server, with that control group, prior to the attempt to do this incremental save. Failure to have a prior full save will cause the recovery attempt to fail. Depending upon what release of BRMS you are using, you may also be able to do this incremental save thru the GUI interface.
The current active transaction log database, from the active Domino server that was just saved, must be copied to the transaction log subdirectory of the Recovery Domino server.

When the incremental save occurred in the prior step, the current active transaction log was copied to the following location:

//BRMS/COPIEDLOG/

Sxxxxxxx.TXN. The xxxxxxx part of the transaction log name is a 7 digit number. Do the following to the copy of this most current transaction log:

WRKLNK '//BRMS/COPIEDLOG/*'

Take a 3 option to copy the file named Sxxxxxxx.TXN and press F4 to prompt (there should be only one, if more than one select the largest numbered name). In the To Directory field of the copy command fill in the path: '/'

Make sure the Data format is *BINARY. If you have a field called Owner, specify *KEEP so QNOTES remains the owner of the copied file. After verifying the fields, press the Enter key to copy the file.

After copying the current active transaction log, go check the Recovery server's to verify that the file got copied and that QNOTES is the owner.

If QNOTES is not the owner, issue a CHGOWN command to change the owner to QNOTES>

It is important to note that the transaction log must be the same name in the Domino Recovery server as the name in the active Domino server where it was copied from.
If the database to be recovered needs to be restored to a specific date and time, to be able to recover a document, depending upon what release of BRMS you are using, you may need to create a data area and change the data area to contain the date and time of the recovery. If you are recovering the database to the most current time, no data area or point in time needs to be specified.
Use WRKMEDIBRM to select the database to be restored and specify that the database is to be placed in the data directory of the Domino Recovery Server.

The name of the database to be restored to the Domino Recovery server must be the same name and case as is found on the active domino server. Depending upon what release of BRMS you are using, you may be able to use the GUI interface to do this point in time restore request.

Note: For Domino 8.5 and later there is an enhancement available to allow you to reset the replica ID on the Domino database that is being incrementally restored so it doesn't potentially conflict with the original database. By default the Replica ID is left alone on the restored incremental database. If you wish to have the Replica ID reset, you can accomplish this by creating a data area in the QUSRNOTES library called QNNIDIFFID. The command to create such a data area would look something like this.

CRTDTAARA DTAARA(QUSRNOTES/QNNIDIFFID) TYPE(*CHAR) LEN(1)

The data area needs to be owned by QNOTES. The command to change the owner of the data area would look like this: CHGOBJOWN QUSRNOTES/QNNIDIFFID *DTAARA QNOTES.The incremental restore code will check if this data area exists. If the data area does exist the parm on the Domino API will be updated to indicate to reset the Replica ID on the incremental restore. If you do not want the Replica ID to be reset on the incremental restore, then make sure this data area is deleted if it currently exists.
Once the database has been recovered, copy (or FTP in binary mode), that newly recovered database to a Domino server that can be accessed from a client.

Because we never want to start the Domino Recovery server, it is desirable to copy this recovered database to a Domino server that is active and can be accessed by a client. Remember to CHGOWN the database to make QNOTES the owner of the newly copied version of the database before accessing the database. Be careful where you move the database to. You wouldn't want to move it to a server that could replicate this database file and either cause problems for the newly recovered database file or the existing database file.
If you are trying to recover a document from the database, then you can use cut and paste from this database to the database on the active Domino server.
Having successfully recovered the database, do not forget to delete the database from the Domino Recovery server. At some point you will also want to delete the copied database from the active Domino server that you copied the database file to.

It is important to follow the above instructions in the order they are presented. Failure to follow the steps as presented can cause failures when trying to recover a Domino database.

Having read the above steps, here are some items of interest summarizing the above or further explaining some of the details:

You must have archival transaction logging enabled for the active server and for the databases you will wish to recover
You must be using BRMS for IBM i to backup your active Domino servers
A full online save, using the BRMS control group, has been done previously for this server so an incremental save can occur and be used in the recovery process
You must have enough authority to successfully run the CFGDOMSVR command
You must have enough authority to copy Domino database files
You must have enough authority to run the necessary BRMS commands to recover a Domino database
QNOTES must be the owner of objects that the Domino server references and you have enough authority to change the owner of a file to QNOTES if need be.
You should copy the recovered database to a server that will not try to replicate with this recovered database.
If a database you are recovering is being restored to the active Domino server and you are replicating that database, you need to consider if temporarily turning off replication for this database is necessary or not. You may not need to turn off replication, but this is intended to make you consider what is happening to this database prior to actually restoring the database.
You must have enough authority to cut and paste the identified documents from the recovered database to the active database
Do not try and use CHGDOMSVR on the modified notes.ini of the recovery server. This doesn't work and could cause problems.

Since the recovery server is not recommended to be started, there are no valid Domino console entries to be displayed. By never starting the Domino Recovery server you reduce the chances of problems occurring on the recovery of a database.
Until there are some additional changes made available from BRMS, the saved transaction logs that are restored, and used in the recovery process, are initially restored to the active Domino server's directory that they were saved from and then copied to the Domino Recovery server. This means that either you have to restore to a Domino Recovery server that is located on the same system as the save occurred OR if restoring to a different system, you may have to create the directories and subdirectories of the active Domino server as it existed when it was saved. When the BRMS changes are made available, then the saved transaction logs will be restored to the Domino Recovery server specified on the restore.

Recovering a database by restoring the database to a different directory under the data directory of the active Domino server:

If you have a problem restoring a database using the following steps, you may wish to try restoring the database to a different server as outlined above. As in the scenario above, you must have archival logging enabled and have previously saved the database you wish to restore. You are restoring this database to a point in time to be able to recover a document or documents (that point in time may be very recent, but you need to specify a point in time for this restore to work).

Create a subdirectory under the data directory of the Active Domino server where the current database file is located.
Make sure QNOTES is the owner of that subdirectory. You can do a: CHGOWN '/data directory of the current server/subdirectory' QNOTES
Do an incremental save of the current active Domino server.
Use WRKMEDIBRM to select the database to be restored and specify that the database is to be placed in the sub directory of the Active Domino Server.

The name of the database to be restored to the sub directory of the Active Domino server must be the same name and case as is found on the active domino server. Depending upon what release of BRMS you are using, you may be able to use the GUI interface to do this point in time restore request.

Note: For Domino 8.5 and later there is an enhancement available to allow you to reset the replica ID on the Domino database that is being incrementally restored so it doesn't potentially conflict with the original database. By default the Replica ID is left alone on the restored incremental database. If you wish to have the Replica ID reset, you can accomplish this by creating a data area in the QUSRNOTES library called QNNIDIFFID. The command to create such a data area would look something like this CRTDTAARA DTAARA(QUSRNOTES/QNNIDIFFID) TYPE(*CHAR) LEN(1)

The data area needs to be owned by QNOTES. The command to change the owner of the data area would look like this: CHGOBJOWN QUSRNOTES/QNNIDIFFID *DTAARA QNOTES.The incremental restore code will check if this data area exists. If the data area does exist the parm on the Domino API will be updated to indicate to reset the Replica ID on the incremental restore. If you do not want the Replica ID to be reset on the incremental restore, then make sure this data area is deleted if it currently exists.

Otherwise follow the instructions for specifying a date and time for the point in time restore.

During the actual recovery process of the selected databases, no new saves of this particular server should occur. It could affect the recovery process adversely.
Verify that the restore worked. Open the new database to recover the documents. This new database will have a new DBIID associated with it. If you wish to be able to recover this version of the database, you will need to do a full save. If this is only a temporary file, and no longer needed after recovering the documents, then there is no need to do a full save.

Failure to do the steps above, and in the order presented, could adversely affect your current Active Domino server environment.