Configuring Data Protection for Domino in Unix / Linux

Answer

There may be cases where additional information is needed for unique installations, troubleshooting, or as a reference for how the Data Protection for Domino is configured. The following technote has several sections to assist an Administrator with understanding and configuring the Data Protection for Domino in the Unix / Linux environment. Note that in all sections, the term "NotesID" is used as a substitute for the OS-level username of the Domino instance owner. In all cases the actual username should be substituted wherever "NotesID" is seen.

Data Protection for Domino environment configuration needed after running dominstall Verifying the domdsmc links Configuring the Tivoli Storage Manager API for Data Protection for Domino operations Verifying the Data Protection for Domino install Configuring the Data Protection for Domino Web GUI Manually performing the dominstall steps Configuring the Tivoli Storage Manager scheduler with Data Protection for Domino

Data Protection for Domino environment configuration needed after running dominstall

The dominstall script, after a successful execution, will create a file called NotesID.profile in the domdsmc_NotesID subdirectory within the Data Protection for Domino install directory. This file contains commands that augment a user's environment. This NotesID.profile can either be sourced by the user's startup profile or the contents can be directly inserted into the user's startup profile. In either case, the setting of environment variables is a crucial step required before the domdsmc commands will work correctly.

To source the ".../domdsmc_NotesID/NotesID.profile" file in the $HOME/.bash_profile in a Bourne-Again (bash) shell (typical with Linux):

• At the bottom of the $HOME/.bash_profile, add the following:

source /opt/tivoli/tsm/client/domino/bin/domdsmc_NotesID/NotesID.profile

To source the ".../domdsmc_NotesID/NotesID.profile" file in the $HOME/.profile in a Korn or Bourne shell (typical with AIX or Solaris):

• At the bottom of the $HOME/.profile, add the following:

. /usr/tivoli/tsm/client/domino/bin/domdsmc_NotesID/NotesID.profile
Note: That is <dot><space><full path and filename>

Logging in as the NotesID and running the set command should now show several DOMI_* environment variables set. Output of the set command can be used to compare against the contents of the NotesID.profile to verify the correct environment configuration.

Verifying the domdsmc links

With any third party utility that uses the Domino API, Lotus Domino requires that the utility must first call the Domino tools/startup wrapper script. A crucial task performed by the dominstall script is the correct linkage of domdsmc to the tools/startup script within the Domino binary directories. The basic progression of links is as follows:

• domdsmc is an alias to domdsmc_NotesID
• When looking for the domdsmc_NotesID executable, the shell will look in the path statement and locate the first occurrence of the domdsmc_NotesID that can be found. By default, with Domino 7 this is in the /opt/ibm/lotus/bin directory.
• /opt/ibm/lotus/bin/domdsmc_NotesID is a link to /opt/ibm/lotus/bin/tools/startup
• /opt/ibm/lotus/bin/tools/startup is a link to ../../notes/latest/<architecture>/startup (/opt/ibm/lotus/notes/latest/ibmpow/startup, for example)
• The Domino 'startup' script is a wrapper script that calls the executable that called it. In this case, startup will try to call domdsmc_NotesID from the same directory as the startup script. /opt/ibm/lotus/bin/tools/domdsmc_NotesID is a symbolic link back to the Data Protection for Domino instance-specific directory (/usr/tivoli/tsm/client/domino/bin/domdsmc_NotesID/domdsmc for example)

Problems can occur when:

1. domdsmc is called by root
2. domdsmc is called directly (./domdsmc) by the user
3. The symbolic links are set incorrectly
4. The permissions on the symbolic links are incorrect
5. The alias from domdsmc to domdsmc_NotesID is not set
6. The PATH environment variable contains a directory that has a domdsmc or domdsmc_NotesID executable, preventing the shell from executing the proper series of symbolic links required

Solutions to those problems:

1. Do not call domdsmc as root
2. Call domdsmc without the ./ or, if a direct call is desired, call the /opt/ibm/lotus/bin/domdsmc_NotesID directly.
3. Verify with the above information that the symbolic links are set correctly
4. Verify that the NotesID has execute permissions on each of the domdsmc_NotesID symbolic links, the tools/startup wrapper script, and the domdsmc executable in the domdsmc_NotesID subdirectory. Also ensure that the domdsmc executable has the SUID bit set (rwsrws--x).
5. Issue the command type domdsmc and verify that it has been set as an alias to domdsmc_NotesID. If not, modify the user's profile to include "alias domdsmc=domdsmc_NotesID"
6. Modify the PATH environment variable inside the user's profile to specify the location of the primary domdsmc_NotesID link (located in the Domino binary directory) first, and the location of the notes.ini (Domino partition data directory) second. For example, PATH=/opt/ibm/lotus/bin:/notesdata:/usr/bin:/etc:/usr/sbin:/usr/ucb:/home/notes/bin:/usr/bin/X11:/sbin:.

Note: The default Domino executable path for Domino 6.x is /opt/lotus/bin/

Configuring the Tivoli Storage Manager API for Data Protection for Domino operations

The Data Protection for Domino uses the 32-bit Tivoli Storage Manager API to interact with the Tivoli Storage Manager Server. The Data Protection client will use the dsm.opt specified by the ADSMOPTFILE parameter in the domdsm.cfg file specified by the DOMI_CONFIG environment variable. If the ADSMOPTFILE parameter is not set, the DSMI_CONFIG environment variable will be used for the dsm.opt. To check the current settings of the domdsm.cfg file, run the domdsmc query preferences command. To set the ADSMOPTFILE parameter in the domdsm.cfg the domdsmc set ADSMOPTFILE=</Fully/Qualified/Path/dsm.opt> command should be used.

The dsm.opt specifies a servername stanza within the dsm.sys file. The dsm.sys file is located, by default, in the API install directory (/usr or opt/tivoli/tsm/client/api/bin/dsm.sys) but can be specified in an alternate location by the DSMI_DIR environment variable. In most cases we do not recommend setting the DSMI_DIR environment variable if using the default installation paths since the DSMI_DIR environment variable also specifies the message repository for the API (dsmclientV3.cat).

Note that if the PASSWORDACCESS generate option is going to be used, the PASSWORDDIR option must also be set to a writable location for the Data Protection for Domino (frequently the domdsmc_NotesID subdirectory). Failure to set the PASSWORDDIR option will cause the Data Protection client to attempt setting the password in the default location (such as /etc/security/adsm/TSM.PWD), a location that is only writable by root.

Verifying the Data Protection for Domino install

Running the following commands will verify the installation and configuration:

• domdsmc q adsm -adsmpwd=<password>
• domdsmc q adsm
• domdsmc q domino
• domdsmc sel names.nsf

Configuring the Data Protection for Domino Web GUI

Commonly, there is a misconception that the Data Protection for Domino has a stand-alone Web GUI. This is not accurate; the Data Protection for Domino provides a plug-in to the Tivoli Storage Manager B/A client Web GUI. Configuration of the Data Protection for Domino Web GUI requires modification to the Tivoli Storage Manager B/A client configuration.

To configure the Web GUI for a Data Protection for Domino instance/partition:

• Verify that the B/A client's Web GUI is functioning properly.
• Log in as the NotesID used by the Data Protection for Domino instance you are trying to configure.
• Verify that the domdsmc query adsm and domdsmc query domino commands work properly.
• Verify that the ADSMOPTFILE parameter is defined in the domdsm.cfg by running the domdsmc query preferences command. If it is not defined the domdsmc set ADSMOPTFILE=</Fully/Qualified/Path/dsm.opt> command should be used.
• In the relevant dsm.sys stanza used by the B/A client, add a single line:

DOMNODE "/usr/tivoli/tsm/client/domino/bin/domdsmc_NotesID/domdsm.cfg"

• Restart the dsmcad as the root user

Note: When clicking on either the backup or restore button you will be prompted for a nodename and password. Use the Tivoli Storage Manager B/A Client nodename and password at this prompt, not the Data Protection for Domino nodename and password.

Manually performing the dominstall steps

If execution of the dominstall script is not possible or cannot be performed due to special circumstances, the same steps can be performed manually. The steps taken by dominstall are:

1. Create a domdsmc_NotesID directory in <tdp_directory>
2. Copy the domdsmc executable into the domdsmc_NotesID directory from <tdp_directory>
3. Create a domdsm.cfg file in the domdsmc_NotesID directory with some basic settings:
ADSMLOGDIR=<tdp_directory>/domdsmc_NotesID
DOMI_DIR=<tdp_directory>
LOGFILE=<tdp_directory>/domdsmc_NotesID/domdsm.log
NOTESINIPATH=<path to Lotus Data directory>
DOMINSTALLPATH=<domino_directory>
4. Create a dsm.opt file in the domdsmc_NotesID directory
5. Run chown -R <notesuser> <tdp_directory>/*
6. Run chown -R <notesuser> <tdp_directory>
7. Run chgrp -R <notesgroup> <tdp_directory>/*
8. Run chgrp -R <notesgroup> <tdp_directory>
9. Run chmod 6771 <tdp_directory>/domdsmc
10. Run chmod 6771 <tdp_directory>/domdsmc_NotesID/domdsmc
11. Run chmod 755 <tdp_directory>
12. Create a symbolic link from <domino_directory>/domdsmc_NotesID to <domino_directory>/tools/startup
13. Create a symbolic link from <domino_directory>/../notes/latest/<architecture>/domdsmc_NotesID to <tdp_directory>/domdsmc_NotesID/domdsmc
14. Create a NotesID.profile in the domdsmc_NotesID directory with the following lines:
export DSMI_LOG=<tdp_directory>/domdsmc_NotesID
export DOMI_DIR=<tdp_directory>
export DOMI_LOG=<tdp_directory>/domdsmc_NotesID
export DOMI_CONFIG=<tdp_directory>/domdsmc_NotesID/domdsm.cfg
alias domdsmc=domdsmc_NotesID
export PATH=<domino_directory>:<path to Lotus Data Directory>:$PATH
15. If using AIX, also append the following line into the domdsmc_NotesID/NotesID.profile:
export AIXTHREAD_MNRATIO=1:1

Note: Replace <tdp_directory> with the directory where the Data Protection for Domino was installed (/usr/tivoli/tsm/client/domino/bin, for example)
Note: Replace <domino_directory> with the directory where Lotus Domino was installed (/opt/ibm/lotus/bin, for example)
Note: Replace <notesuser> and <notesgroup> with the username and groupname.

Configuring the Tivoli Storage Manager scheduler with Data Protection for Domino

Data Protection for Domino comes with several scripts that can be used in conjunction with the Tivoli Storage Manager scheduler facilities to provide a way to schedule Data Protection for Domino operations. The scripts are located in the Data Protection for Domino installation directory and are named:

• domarc.smp - used for archiving transaction logs
• domina.smp - used for inactivating old transaction logs on the Tivoli Storage Manager server
• dominc.smp - used for incremental backups
• domsel.smp - used for selective (full) backups

To pre-configure the domarc.smp script:

• Copy the domarc.smp file into the domdsmc_NotesID subdirectory.
• Rename the domarc.smp in the domdsmc_NotesID subdirectory to domarc.sh
• Open the domarc.sh file with a text editor
• Locate the line:

DOM_ID=notes
Replace the word "notes" with your NotesID. For example, DOM_ID=dpar07

• Locate the line:

su - ${DOM_ID} "-c /opt/lotus/bin/domdsmc_${DOM_ID} archivelog -adsmoptfile=${DOM_ID_DIR}/dsm.schd.opt -logfile=${DOM_ID_DIR}/domarc.log" >>${DOM_ID_DIR}/domsched.log.arc &
Replace the /opt/lotus/bin/ with the Domino install directory. For Lotus Domino 7 and higher, this directory has changed to /opt/ibm/lotus/bin/
Replace the dsm.schd.opt with the desired dsm.opt file (Usually this is simply dsm.opt)

• Locate the line:

/opt/lotus/bin/domdsmc_${DOM_ID} archivelog -adsmoptfile=${DOM_ID_DIR}/dsm.schd.opt -logfile=${DOM_ID_DIR}/domarc.log >>${DOM_ID_DIR}/domsched.log.arc &
Replace the /opt/lotus/bin/ with the Domino install directory. For Lotus Domino 7 and higher, this directory has changed to /opt/ibm/lotus/bin/
Replace the dsm.schd.opt with the desired dsm.opt file (Usually this is simply dsm.opt)

• Ensure the trailing ampersands are not truncated off the line. Do not make other changes to the script unless you are confident you understand the changes being made.
• Save the script and exit the text editor
• Ensure the permissions on the domarc.sh are set to 755 (rwxr-xr-x).

To pre-configure the domina.smp script:

• Copy the domina.smp file into the domdsmc_NotesID subdirectory.
• Rename the domina.smp in the domdsmc_NotesID subdirectory to domina.sh
• Open the domina.sh file with a text editor
• Locate the line:

DOM_ID=notes
Replace the word "notes" with your NotesID. For example, DOM_ID=dpar07

• Locate the line:

su - ${DOM_ID} "-c /opt/lotus/bin/domdsmc_${DOM_ID} inactivatelogs -adsmoptfile=${DOM_ID_DIR}/dsm.schd.opt -logfile=${DOM_ID_DIR}/domina.log" >>${DOM_ID_DIR}/domsched.log.ina &
Replace the /opt/lotus/bin/ with the Domino install directory. For Lotus Domino 7 and higher, this directory has changed to /opt/ibm/lotus/bin/
Replace the dsm.schd.opt with the desired dsm.opt file (Usually this is simply dsm.opt)

• Locate the line:

/opt/lotus/bin/domdsmc_${DOM_ID} inactivatelogs -adsmoptfile=${DOM_ID_DIR}/dsm.schd.opt -logfile=${DOM_ID_DIR}/domina.log >>${DOM_ID_DIR}/domsched.log.ina &
Replace the /opt/lotus/bin/ with the Domino install directory. For Lotus Domino 7 and higher, this directory has changed to /opt/ibm/lotus/bin/
Replace the dsm.schd.opt with the desired dsm.opt file (Usually this is simply dsm.opt)

• Ensure the trailing ampersands are not truncated off the line. Do not make other changes to the script unless you are confident you understand the changes being made.
• Save the script and exit the text editor
• Ensure the permissions on the domina.sh are set to 755 (rwxr-xr-x).

To pre-configure the dominc.smp script:

• Copy the dominc.smp file into the domdsmc_NotesID subdirectory.
• Rename the dominc.smp in the domdsmc_NotesID subdirectory to dominc.sh
• Open the dominc.sh file with a text editor
• Locate the line:

DOM_ID=notes
Replace the word "notes" with your NotesID. For example, DOM_ID=dpar07

• Locate the line:

su - ${DOM_ID} "-c /opt/lotus/bin/domdsmc_${DOM_ID} incremental "'"*"'" -adsmoptfile=${DOM_ID_DIR}/dsm.schd.opt -logfile=${DOM_ID_DIR}/dominc.log" >>${DOM_ID_DIR}/domsched.log.inc &
Replace the /opt/lotus/bin/ with the Domino install directory. For Lotus Domino 7 and higher, this directory has changed to /opt/ibm/lotus/bin/
Replace the dsm.schd.opt with the desired dsm.opt file (Usually this is simply dsm.opt)

• Locate the line:

/opt/lotus/bin/domdsmc_${DOM_ID} incremental '*' -adsmoptfile=${DOM_ID_DIR}/dsm.schd.opt -logfile=${DOM_ID_DIR}/dominc.log >>${DOM_ID_DIR}/domsched.log.inc &
Replace the /opt/lotus/bin/ with the Domino install directory. For Lotus Domino 7 and higher, this directory has changed to /opt/ibm/lotus/bin/
Replace the dsm.schd.opt with the desired dsm.opt file (Usually this is simply dsm.opt)

• Ensure the trailing ampersands are not truncated off the line. Do not make other changes to the script unless you are confident you understand the changes being made.
• Save the script and exit the text editor
• Ensure the permissions on the dominc.sh are set to 755 (rwxr-xr-x).

If there are databases in subdirectories that need to be backed up, be sure to include the "-subdir=yes" parameter as part of the dsmdsmc command. Alternatively, the SUBDIR YES setting can be placed in the Data Protection for Domino configuration file (dsmdsm.cfg).

To use the domsel.smp script:

• Copy the domsel.smp file into the domdsmc_NotesID subdirectory.
• Rename the domsel.smp in the domdsmc_NotesID subdirectory to domsel.sh
• Open the domsel.sh file with a text editor
• Locate the line:

DOM_ID=notes
Replace the word "notes" with your NotesID. For example, DOM_ID=dpar07

• Locate the line:

su - ${DOM_ID} "-c /opt/lotus/bin/domdsmc_${DOM_ID} selective "'"*"'" -adsmoptfile=${DOM_ID_DIR}/dsm.schd.opt -logfile=${DOM_ID_DIR}/domsel.log" >>${DOM_ID_DIR}/domsched.log.sel &
Replace the /opt/lotus/bin/ with the Domino install directory. For Lotus Domino 7 and higher, this directory has changed to /opt/ibm/lotus/bin/
Replace the dsm.schd.opt with the desired dsm.opt file (Usually this is simply dsm.opt)

• Locate the line:

/opt/lotus/bin/domdsmc_${DOM_ID} selective '*' -adsmoptfile=${DOM_ID_DIR}/dsm.schd.opt -logfile=${DOM_ID_DIR}/domsel.log >>${DOM_ID_DIR}/domsched.log.sel &
Replace the /opt/lotus/bin/ with the Domino install directory. For Lotus Domino 7 and higher, this directory has changed to /opt/ibm/lotus/bin/
Replace the dsm.schd.opt with the desired dsm.opt file (Usually this is simply dsm.opt)

• Ensure the trailing ampersands are not truncated off the line. Do not make other changes to the script unless you are confident you understand the changes being made.
• Save the script and exit the text editor
• Ensure the permissions on the domsel.sh are set to 755 (rwxr-xr-x).

If there are databases in subdirectories that need to be backed up, be sure to include the "-subdir=yes" parameter as part of the dsmdsmc command. Alternatively, the SUBDIR YES setting can be placed in the Data Protection for Domino configuration file (dsmdsm.cfg).

Verifying the correct modifications were made to the scripts:

• Execute the modified script (dom???.sh) as the NotesID user
• Execute the modified script (dom???.sh) as the root user.
• Verify that the domdsmc_NotesID/dom.sched.??? log files are owned by the NotesID user. If the script was first run as root, these files will be owned by root and will not be writable by the regular NotesID user.
• Check the dom???.log and the dom.sched.??? log files to ensure that execution of the script as both the NotesID user and the root user were successful.
• Repeat these steps as needed for each command script desired to be used by the scheduler.

The scripts are now ready to be executed by a Tivoli Storage Manager scheduler service. On the Tivoli Storage Manager server, the defined schedule should be configured with the "action=command" parameter and the location of the script specified as the object parameter. The schedule can then be associated to the Tivoli Storage Manager node that the scheduler service on the Domino instance is running as. For example, if the scheduler service is polling the Tivoli Storage Manager server for scheduled events for the b/a client node, the defined schedule should be associated with the b/a client node. The data will still be sent to the nodename specified by the Data Protection for Domino configuration settings, however.

Please observe that the limitations for these scripts (within the OS) is that they may change the value of the return code that is received from the Data Protection for Domino backup. For example, if the Data Protection for Domino client encounters an error 402 (RC_ERRORS_PROCESSING_REQUEST), this return code is modified first by the UNIX shell and then by Domino's /opt/lotus/bin/tools/startup script to a value of 18.

Mathematically, the operations are:
RC modulo 256 --> new RC (OS limitation)
new RC modulo 128 --> final RC (Domino startup script limitation)

Example:
402 % 256 = 146
146 % 128 = 18

This emphasizes an important point of scheduled events with the Data Protection for Domino: the domdsm.log should be checked to verify the actual cause for the failure.