Demo Engine How To

July 27, 2007

4.5 Backup

1.0 Overview

The Demonstration Engine (DE) is a sample that demonstrates the use of Storage Management Services™ (SMS) API to perform backup and restore operations. The sample provides a simple implementation of a backup application in order to present SMS concepts and familiarize the developer on usage of SMS API. It also provides an implementation of new features discussed in this developer release to supplement the documentation. DE is available on OES NetWare® and OES Linux and supports the following features:

  • Connecting to a target service

  • Backup and restore using sessions

  • Rename restore

  • Selection Lists

  • Erase and rename data sets

  • UTF-8 path names.

  • Extended character passwords

  • Cluster fail back/failover

2.0 Implementation Details

2.1 Sessions

DE uses sessions to identify operations. Every session is identified by a session name that the user provides and a session number that is generated internally. Data is backed up into a file that is created based on the session number. The session name is cross referenced to the session number, and thus the session name can be used to restore data backed up in a particular session. A session that was created on one server can be restored on a different server, by copying the session files. DE also maintains log files which records information about errors. Log files are names as de-n.log where n is session number-1.

2.2 Threading

DE on OES Linux is not multi-threaded, instead each session is a separate process.

2.3 Features

DE implements its features as specified in the API documentation (sms_docs.pdf). For details, refer the API documentation.

2.4 Name space and data set names

Target services work with different name spaces that qualify a data set name. In DE, whenever a data set name is expected as input from the user, the GetNameSpace function is called to get the appropriate name space in which the data set name is entered. The function displays the available name spaces on the target service and prompts for a name space. The following output is an example of what is displayed by the GetNameSpace function.

Name Space Type:
	1: NFS
	2: Quit
	Enter option:

3.0 Building and Running DE on OES Linux

  1. Download the novell-sms rpm under dependencies section in SMS Developer Components .

  2. Install the novell-sms rpm and start SMS services. Refer the readme for instructions.

  3. Use make to build using the sample Makefile. Makefile is available at /opt/novell/samples/sms/de.

  4. Execute ./de

4.0 Working with DE

DE provides a simple interface, that is similar on both OES NetWare and OES Linux, to perform common backup and restore operations.

Each operation has been detailed as follows:

  • Name of the file that you can find it in.

  • Corresponding function that you can view in the DE source code

  • SMS API used

  • User interface and operation

4.1 Connecting to Target Service

Source File:  demain.c

Function: EstablishConnection

API: NWSMListSMDRs NWSMListTSAs NWSMConnectToTSA NWSMTSListTargetServices NWSMTSConnectToTargetService NWSMTSConnectToTargetServiceEx NWSMTSGetTargetServiceAPIVersion

After running DE,

  1. Enter the name for the session.

    DE displays the list of SMDRs as follows:

    Visible Storage Management Data Requestors:
    
    SMDR_1
    
    SMDR_2
    
    SMDR: SMDR_2
    

    SMDR_1 and SMDR_2 are the names of two servers that have SMDR loaded and is visible to DE.

  2. Select a SMDR. In this case, SMDR_2 has been selected.

    A list of TSAs registered with this SMDR is then displayed. Enter the TSA name.

    Enter the TSA name.
    
    Visible Target Service Agents:
    
    SMDR_2.Linux File System
    
    TSA: SMDR_2.Linux File System
    

    SMDR_2.Linux File System is the name of the TSA that supports backup of the Linux file system.

  3. Enter a Target Name (Server or Virtual Server name).

    Target Service(s): SMDR_2 
    
    Which Target Service do you want to connect to? SMDR_2
    
  4. Enter the UserName and Password. After you have successfully authenticated to the TSA, the main menu screen is displayed

    L: Do not log Session Output
    
    C: Create SelectionList
    
    D: Display SelectionList
    
    F: Free SelectionList
    
    E: Delete File
    
    N: Rename File
    
    B: Backup
    
    R: Restore
    
    Q: Quit
    
    Select option:
    

4.2 Selection Lists

This section details the following:

4.2.1 Create Selection Lists

Source File:  demain.c, deutil.c

Function: BuildSelectionList

API: NWSMTSScanTargetServiceResource NWSMTSListSupportedNameSpaces, NWSMTSGetTargetSelectionTypeStr

This command lets you to create a list of data sets to be included or excluded from a backup/restore session. An empty include list means that everything is included. An empty exclude list means that nothing is excluded. If the include list is not empty then the resource name to scan should include the parents of the data sets in the include lists.

  1. The Selection Type menu is displayed.

    Selection Type:   
    
    1: Exclude major TSA resources       
    
    2: Include major TSA resources 
    
    3: Exclude directories (full path)        
    
    4: Include directories (full path)
    
    5: Exclude files
    
    6: Include files 
    
    7: Exclude path/files
    
    8: Include path/files 
    
    9: Return to previous menu 
    
    Enter Selection Type:
    

    After selecting one of the include/exclude options, you are prompted to enter the name of the data set you want to add to the selection list. Wild cards (* or ?) are supported for files, but not for directories. For example, enter *.c to include or exclude all of the files with a ".c" extension.

  2. After completing the selection item, you are returned to the selection item menu, where you may want to specify other selections.

  3. When you have finished defining selection list items, select Quit at the Name Space Type menu prompt. All selections are saved before returning to the main menu.

4.2.2 Display Selection List

Source File:  demain.c

Function: DisplaySelectionList

API: NWSMGetFirstName NWSMGetNextName NWSMCloseName

This command displays the selection list that was created with the Create SelectionList command. There is no menu associated with this command. After reviewing the selection list, press any key to return to the main menu.

4.2.3 Free Selection List

Source File: demain.c

Function: FreeSelectionList

API: (None)

This command deletes any existing selection lists and frees memory allocated for the list.

4.3 Delete File

Source File: demain.c

Function: EraseFile

API: NWSMPutOneName NWSMTSScanDataSetEnd NWSMTSScanDataSetBegin NWSMTSScanNextDataSet NWSMGetDataSetName NWSMTSDeleteDataSet

This command deletes a data set on the Target Service. When this command is selected, you are prompted for the following information:

Delete File or Directory? (f/d):

Enter the fully qualified name of the data set to delete. The data set is then checked for existence and deleted.

4.4 Rename File

Source File: demain.c

Function: RenameFile

API: NWSMPutOneName NWSMTSScanDataSetBegin NWSMTSScanNextDataSet NWSMGetDataSetName NWSMTSSeparateDataSetName NWSMTSRenameDataSet  NWSMTSScanDataSetEnd

This command renames a data set (file or directory) on the Target Service. When this command is selected, you are prompted for the following information:

Rename File or Directory? (f/d):

Enter the fully qualified name of the data set being renamed. Then enter the new dataset name that it is to be renamed to. The new name has to be terminal node name only.

4.5 Backup

Source File: demain.c

Function: Backup

API: NWSMPutOneName NWSMTSScanDataSetBegin NWSMGetDataSetName  NWSMTSOpenDataSetForBackup NWSMTSReadDataSet NWSMTSCloseDataSet NWSMTSScanNextDataSet NWSMTSScanDataSetEnd NWSMTSScanDataSetContinue

This command lets you backup the selected Target Service. Data sets can be backed up with this command and then restored with the Restore command. In all the following cases, data sets are included or excluded based on the selection list if you have created one. If no selection list exists, all data sets under the selected subdirectory are backed up. Also, all path names must be full path names.

  1. When this command is selected, the following menu is displayed:

    T:  Save backup data
    
    BR: Backup Resource  
    
    BS: Backup Subdirectories
    
    SR: Scan Resource
    
    SS: Scan Subdirectories 
    
    Q:  Return to previous menu
    
    Select option:
    

    By pressing T, you can select whether or not you want the backup data to be saved in a file on your disk ("T" toggles the save option). If you do not save the data, it is read from the Target Service but not stored anywhere. Pressing Q returns you to the main menu.

  2. BR: Backup Resource - Pressing BR results in the following menu being displayed:

    Enter Resource to backup:
    
    1: /
    
    2: /home/sms
    
    3: /mnt/remote
    
    Please enter selection:
    

    At the prompt enter the index of the primary resource that you want to backup. The Backup Resource option starts backing up the Target Service at the primary resource. An example would be a mount point like /home/sms on OES Linux.

  3. BS: Backup subdirectory - Pressing BS results in the following prompt being displayed:

    Enter subdirectory to backup:
    

    The Backup Subdirectories option starts backing up the Target Service at the subdirectory you enter at the prompt.

  4. SR: Scan Resource - Pressing SR results in the following menu being displayed:

    Enter Resource to scan:
    
    1: /
    
    2: /home/sms
    
    3: /mnt/remote
    
    Please enter selection:
    

    The Scan options differ from the Backup options in that the names of the data sets are returned but no data is read from the data sets. The Scan Resource option starts scanning the Target Service at the object you enter at the prompt.

  5. SS - Scan Subdirectory - Pressing SS results in the following prompt being displayed:

    Enter subdirectory to scan:
    

    The Scan Subdirectory option starts scanning the Target Service at the subdirectory you enter at the prompt.

4.6 Restore

Source File: demain.c

Function: Restore

API: NWSMTSSetRestoreOptions NWSMTSOpenDataSetForRestore NWSMTSWriteDataSet NWSMTSCloseDataSet

This command allows you to restore data sets that you have backed up using the Backup command. Note that if you had created a selection list, it is used to exclude data sets from the restore.

  1. Selecting the Restore command results in the following menu to be displayed:

    List of available sessions:
    
    1.trail1
    
    2.trail2
    
    Enter the choice of the session to be restored (’q’ to Escape):
    
  2. Select the backup session that you would want to restore. The following screen is displayed:

    R: Restore Session 
    
    T: Rename Restore
    
    D: Display Rename Restore Path
    
    F: Free Rename Restore Path
    
    P: Overwrite Parent 
    
    C: Overwrite Child
    
    Q: Return to previous menu
    
    Select option:
    

    The P and C options select whether or not to overwrite the parent or child data sets, respectively, when restoring. The Restore Session (R) option causes the data sets stored on your disk to be restored to the Target Service. The D and F options help display or free the restore path.

4.7 Rename Restore

Source File: demain.c

Function: RenameRestore

API: NWSMTSFixDataSetName

This command allows you to restore data to a different location. Note that full paths should be used to specify the source data set to rename.

Selecting the Rename restore command results in the following prompt being displayed:

Enter Source Path:
Enter Destination Path:

Enter the source and the destination path for rename, the source path if found in the backed up session is renamed to the appropriate destination path entered.

The Display Rename List and Free Rename List commands can be used to view or free the list of rename paths.

4.8 Ending a Session

Source File:  demain.c

Function: EndSession 

API: NWSMTSReleaseTargetService NWSMReleaseTSA

From the main menu, type Q to exit the Demonstration Engine.

5.0 Limitations

  • Session numbers start from 1 on every run of the DE. If DE is run multiple times from the same location, older sessions will be overwritten.

  • DE on OES Linux is not multi-threaded.

6.0 Documentation Conventions

In this documentation, a greater-than symbol (>) is used to separate actions within a step and items in a cross-reference path.

A trademark symbol (® , TM, etc.) denotes a Novell trademark; an asterisk (*) denotes a third-party trademark