22.3 Using the eMBox Client for Backup and Restore

The eMBox Client is a command line Java client that gives you access to eMBox tools such as the eDirectory Backup eMTool. You can back up, restore, and configure roll-forward logging for multiple servers from a single machine if you have access behind the firewall. It enables you to perform most backup and restore tasks tasks remotely in a browser using iManager, inside or outside the firewall. You can perform advanced tasks remotely using the eMBox Client, a command line Java client, with access behind the firewall or through a VPN.

In iManager, you can use all the features except cold backup, unattended backup, and advanced restore options, as explained in Section 22.4, Using NetIQ iManager for Backup and Restore.

The eDirectory Backup Tool is part of the eMBox tool set. The eMBox is a service that is installed on the server as part of eDirectory.

The Backup Tool comprises the following files:

Filename

Description

backupcr

Core library that contains all backup and restore functionality.

This library has no user interface. It is loaded and linked dynamically by the backuptl program.

backuptl

Tool interface to the backupcr library. Provides backup and restore functionality through the DSBK architecture.

This can be accessed via the iManager plug-in or DSBK, the Java command line client.

dsbackup_en.xlf

Language file containing messages returned by the Backup Tool.

IMPORTANT:The restore verification process is backward compatible only with eDirectory 8.5 or later. If you want to use the new backup and restore on servers that participate in a replica ring, make sure you upgrade all the servers in the replica ring to eDirectory 8.5 or later.

Because the eMBox Client can be run in batch mode, you can use it to do unattended backups using the eDirectory Backup eMTool.

The eMBoxClient.jar file is installed on your server as part of eDirectory. You can also copy the file and run it on any machine with Sun JVM 1.3.1. For more information, see The eDirectory Management Toolbox and Running the Client on a Workstation.

Before performing backup and restore tasks, review Section 17.1, Checklist for Backing Up eDirectory for an overview of the issues involved in planning an effective eDirectory backup strategy.

22.3.1 Prerequisites

  • Make sure the eMBoxClient.jar file is on the machine you want to initiate the backup from.

    The file is installed on your server as part of eDirectory installation. You can copy it from there and run it on any machine with Sun JVM 1.1.3. You can run backups for multiple servers from a single machine if you have access behind the firewall. For more information, see Section 22.1, Using the Command Line Client.

  • If you are planning to use roll-forward logs for this server, make sure they are turned on before a backup is made.

    You must turn on roll-forward logging for servers that participate in a replica ring. If you don't, when you try to restore from your backup files you will get errors and the database will not open.

    For more information on roll-forward logs, see Section 17.3, Using Roll-Forward Logs. For how to turn them on, see Configuring Roll-Forward Logs with the eMBox Client.

  • Review the description of the command line options in Backup and Restore Command Line Options.

  • For multiple-server trees, you should upgrade all the servers that share replicas with this server to eDirectory 8.5 or later.

22.3.2 Backing Up Manually with the eMBox Client

Use the eMBox Client to back up data from an eDirectory database to a file you specify on the server where the backup is being performed. This backup file or set of files contains information necessary to restore eDirectory to the state it was in at the time of the backup. The results of the backup process are written to the log file you specify.

To back up the eDirectory database on a server using the eMBox Client:

  1. Run the eMBox Client in interactive mode.

    • Linux: At the command line, enter edirutil -i.

    • Windows: Run drive\novell\nds\edirutil.exe -i

    The edirutil file gives you a shortcut to running the eMBox Client. It points to the Java executable and the default location where the eMBox Client is installed with eDirectory.You can also enter the information manually, as described in Setting Up the Path and Classpath for Client.

    When the eMBox Client opens, the eMBox Client prompt appears: eMBox Client>

  2. Log in to the server you want to back up by entering

    login -s server_name_or_IP_address -p port_number -u username.context -w password

    For example, in Windows enter

    login -s 151.155.111.1 -p 8009 -u admin.mycompany -w mypassword

    If you get an error saying that a secure connection cannot be established, make sure your machine has the JSSE files listed in Establishing a Secure Connection with the Client.

    For help finding out which port number to use, see Finding Out eDirectory Port Numbers.

    The eMBox Client indicates whether the login is successful.

  3. Enter the backup command at the eMBox Client prompt, following this general pattern:

    backup -b -f backup_filename_and_path -l backup_log_filename_and_path -u include_file_filename_and_path -t -w

    A space must be between each switch. The order of the switches is not important.

    For example, in Windowsin Windows enter

    backup -b -f c:\backups\8_20_2001.bak -l c:\backups\backup.log -u c:\backups\myincludefile.txt -t -w

    This example command would result in a full backup (-b) with the backup file placed at c:\backups\8_20_2001.bak and the log file for the process placed at c:\backups\backup.log. This command specifies that other files should be backed up along with the database:

    • The files listed in an include file (-u c:\backups\myincludefile.txt) that was created beforehand by the administrator.

    • Stream files (-t)

    This example command specifies that the backup file should be overwritten (-w), so if a file of the same name existed, the Backup eMTool would replace it.

    The eMBox Client indicates whether the backup is successful.

  4. Log out from the server by entering the following command:

    logout

  5. Exit the eMBox Client by entering the following command:

    exit

  6. Make sure you do a file system backup shortly after the eDirectory backup is created, to put the eDirectory backup files safely on tape. The Backup eMTool only places them on the server.

For more information on manual backup, refer to Section 17.5.3, Backing Up Manually with DSBK.

22.3.3 Doing Unattended Backups, Using a Batch File with the eMBox Client

Use a batch file to do unattended backups of eDirectory through the eMBox Client. For example, you might want to do a full backup of eDirectory on your servers weekly and an incremental backup nightly.

You can run the eMBox Client in batch mode using a system batch file, an eMBox Client internal batch file, or a combination of both. For more information, see Running the Command Line Client in Batch Mode.

This procedure describes using a system batch file:

  1. Create a system batch file to back up the servers, following these general patterns, with one line per server.

    In Windows and UNIX environments, this is the general pattern:

    java -cp path/eMBoxClient.jar embox -s server_name -p port_number -u username.context -w password -t backup.backup -b -f backup_filename_and_path -l backup_log_filename_and_path -u include_file_filename_and_path -t -w
    

    For examples and more explanation, see Example of System Batch Files for Unattended Backups.

    For nightly incremental backups, you could use the same file you use for full backups, but change the -b switch to -i to do an incremental backup instead of a full backup. It's also probably a good idea to use a different backup filename for incremental backups than for the full backup.

    For help finding out which port number to use, see Finding Out eDirectory Port Numbers. If you want to use a secure connection, see Establishing a Secure Connection with the Client. For information on using an eMBox Client internal batch file as well, see Running the Command Line Client in Batch Mode.

  2. Run the batch files unattended, according to the instructions in your operating system or third-party documentation.

  3. Make sure you schedule file system backups shortly after eDirectory backups, to place the eDirectory backup files safely on tape.

    The Backup eMTool only places them on the server.

  4. Periodically check the results recorded in the log file you specified, to make sure the unattended backups are successful.

Example of System Batch Files for Unattended Backups

Below is an example system batch file:

Example Batch File for Windows
java -cp c:\novell\nds\embox\eMBoxClient.jar embox -s myserver -p 8008 -u admin.myorg -w mypassword -n -t backup.backup -b -f c:\backup\backup.bak -u c:\backup\includes\includefile.txt -l c:\backup\backup.log -t -w

In this example batch file, the following options are shown.

  • A full backup is specified (-b).

  • An include file is specified (-u). This is optional. You can use an include file if you want to back up other files of your choice. The include file must be created beforehand.

  • Stream files (-t) are also backed up.

  • The option to overwrite a backup file of the same name is specified (-w).

    IMPORTANT:If a backup file of the same name exists (this is likely if you use the same batch file regularly), it's important to use the -w option to overwrite the existing backup file to make sure your backup is successful.

    In batch mode, if -w is not specified and a file of the same name exists, the default behavior is to not overwrite the file, so a backup will not be created. In interactive mode, if -w is not specified, the eMBox Client will ask you whether you want to overwrite the file.

    If you are making a file system backup shortly after each full or incremental backup of eDirectory, your previous backup files should have been copied from the server to file system backup tapes, so it should be safe to use this option to overwrite the existing backup file.

  • A nonsecure port is used in this example (-p 8008), so a nonsecure connection is specified (-n).

22.3.4 Configuring Roll-Forward Logs with the eMBox Client

Use the eMBox Client to change the settings for roll-forward logs. You can do the following tasks:

  • Find out the current settings

  • Turn roll-forward logging on or off

    You must turn on roll-forward logging for servers that participate in a replica ring. If you don't, when you try to restore from your backup files you will get errors and the database will not open.

  • Change the roll-forward logs directory

  • Set the minimum and maximum roll-forward log size

  • Find out the current and last unused roll-forward log

  • Turn stream file logging on or off for the roll-forward logs

For information about roll-forward logging, see Section 17.3, Using Roll-Forward Logs.

  1. Run the eMBox Client in interactive mode:

    • Linux: At the command line, enter edirutil -i.

    • Windows: Run drive\novell\nds\edirutil.exe -i.

    The edirutil file gives you a shortcut to running the eMBox Client. It points to the Java executable and the default location where the eMBox Client is installed with eDirectory. it includes the necessary -ns option. You can also enter the options manually, as described in Running the Client on a Workstation.

    When the eMBox Client opens, the eMBox Client prompt appears: eMBox Client>

  2. Log in to the server you want to configure roll-forward logging on by entering

    login -s server_name_or_IP_address -p port_number -u username.context -w password

    For example, in Windows enter

    login -s 151.155.111.1 -p 8009 -u admin.mycompany -w mypassword
    

    If you get an error saying that a secure connection cannot be established, make sure your machine has the JSSE files listed in Establishing a Secure Connection with the Client.

    For help finding out which port number to use, see Finding Out eDirectory Port Numbers.

    The eMBox Client indicates whether the login is successful.

  3. (Optional) Find out the current settings by entering the following command:

    getconfig

    No switches are necessary.

    The following is an example of the information you receive:

    Roll forward log status OFF
    Stream file logging status OFF
    Current roll forward log directory C:\rfl\nds.rfl
    Minimum roll forward log size (bytes) 104857600
    Maximum roll forward log size (bytes) 4294705152
    Last roll forward log not used 00000000.log
    Current roll forward log 00000001.log
    *** END ***
    
  4. Change the settings using the setconfig command, following this general pattern:

    setconfig [-L|-l] [-T|-t] -r path_to_roll-forward_logs -n minimum_file_size -m maximum_file_size

    A space must be between each switch. The order of the switches is not important.

    Ideally, you would have a separate disk partition/volume dedicated to roll-forward logs to make it easier to monitor disk space and rights.

    WARNING:If you turn on roll-forward logging, don't use the default location. For fault tolerance, put the directory on a different disk partition/volume and storage device than eDirectory. The roll-forward logs directory must be on the server where the backup configuration is being changed.

    IMPORTANT:If you turn on roll-forward logging, you must monitor disk space on the volume where you place the roll-forward logs. If left unchecked, the log file directory will grow until it fills up the disk partition/volume. If roll-forward logs cannot be created because no more disk space is available, eDirectory stops responding on that server. We recommend you periodically back up and remove unused roll-forward logs from your server. See Backing Up and Removing Roll-Forward Logs.

  5. Log out from the server by entering the following command:

    logout

  6. Exit the eMBox Client by entering the following command:

    exit

22.3.5 Restoring from Backup Files with the eMBox Client

Use the eMBox Client to restore an eDirectory database from data stored in backup files you created manually or with a batch file. The results of the restore process are written to the log file you specify.

The eMBox Client also lets you use advanced restore options not available in iManager. They are described in Backup and Restore Command Line Options, under restore and restadv.

To restore an eDirectory database on a server using the eMBox Client:

  1. Make sure you have gathered the backup files you need, as described in Section 17.4, Preparing for a Restore.

  2. Run the eMBox Client in interactive mode:

    • Linux: At the command line, enter edirutil -i.

    • Windows: Run drive\novell\nds\edirutil.exe -i

    The edirutil file gives you a shortcut to running the eMBox Client. It points to the Java executable and the default location where the eMBox Client is installed with eDirectory, it includes the necessary -ns option. You can also enter the information manually, as described in Running the Client on a Workstation.

    When the eMBox Client opens, the eMBox Client prompt appears: eMBox Client>

  3. Log in to the server you want to restore by entering

    login -s server_name_or_IP_address -p port_number -u username.context -w password

    For example, in Windows enter

    login -s 151.155.111.1 -p 8009 -u admin.mycompany -w mypassword
    

    If you get an error saying that a secure connection cannot be established, make sure your machine has the JSSE files listed in Establishing a Secure Connection with the Client.

    For help finding out which port number to use, see Finding Out eDirectory Port Numbers.

    The eMBox Client indicates whether the login is successful.

  4. Enter the restore command at the eMBox Client prompt, following this general pattern:

    restore -r -a -o -f full_backup_path_and_filename -d roll-forward_log_location -l restore_log_path_and_filename

    A space must be between each switch. The order of the switches is not important. Make sure you use the -r switch to restore the eDirectory database itself. Otherwise only the other kinds of files will be restored. If you want the database to be active and open when the restore is complete, make sure you specify -a and -o.

    If you are restoring roll-forward logs, make sure you include the full path to the logs, including the directory that is automatically created by eDirectory, usually named \nds.rfl. For more information about this directory, see Location of the Roll-Forward Logs.

    For example:

    restore -r -a -o -f sys:/backup/nds.bak -d $HOME/rfldir/nds.rfl -l $HOME/backups/backup.log

    This example command specifies that the database itself should be restored (-r), and it should be activated (-a) and opened (-o) after the restore verification is successfully completed. The -f switch indicates where the full backup file is, -d the roll-forward logs, and -l the log file in which to record the results of the restore.

    The eMBox Client will restore the full backup, then prompt you for the incremental backup files.

  5. (Conditional) If you are restoring incremental backup files, provide the path and filename for each one when the eMBox Client prompts you for the next incremental file.

    It will tell you the ID of the next file, which you can find in the incremental backup file header.

    The eMBox Client indicates whether the restore was successful.

  6. (Conditional) If the restore was not successful, check the log file to see the errors.

    If the restore verification fails, see Section 17.7, Recovering the Database If Restore Verification Fails.

    NOTE:If the server you are restoring shares a replica with a server running an earlier version than eDirectory 8.5, the restore log will show a -666 error (incompatible DS version) for that replica.

  7. Log out from the server by entering the following command:

    logout

  8. Exit the eMBox Client by entering the following command:

    exit

  9. (Conditional) If you restored NICI security files, after completing the restore, restart the server to reinitialize NICI and then restore DIB.

  10. Make sure the server is responding as usual.

  11. (Conditional) If you are using roll-forward logging on this server, you must re-create your configuration for roll-forward logging to make sure it is turned on and the logs are being saved in a fault-tolerant location. After turning on the roll-forward logs, you must also do a new full backup.

    This step is necessary because during a restore, the configuration for roll-forward logging is set back to the default, which means that roll-forward logging is turned off and the location is set back to the default. The new full backup is necessary so that you are prepared for any failures that might occur before the next unattended full backup is scheduled to take place.

    For more information about roll-forward logs and their location, see Section 17.3, Using Roll-Forward Logs.

Your restore should now be complete, and NICI reinitialized with the restored NICI files so you can access encrypted information. If you use roll-forward logging, you have prepared for any failures in the future by turning on roll-forward logging again after the restore and creating a new full backup as a baseline.