July 27, 2007
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
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.
DE on OES Linux is not multi-threaded, instead each session is a separate process.
DE implements its features as specified in the API documentation (sms_docs.pdf). For details, refer the API documentation.
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:
Download the novell-sms rpm under dependencies section in SMS Developer Components .
Install the novell-sms rpm and start SMS services. Refer the readme for instructions.
Use make to build using the sample Makefile. Makefile is available at /opt/novell/samples/sms/de.
Execute ./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
Source File: demain.c
Function: EstablishConnection
API: NWSMListSMDRs NWSMListTSAs NWSMConnectToTSA NWSMTSListTargetServices NWSMTSConnectToTargetService NWSMTSConnectToTargetServiceEx NWSMTSGetTargetServiceAPIVersion
After running DE,
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.
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.
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
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:
This section details the following:
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.
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.
After completing the selection item, you are returned to the selection item menu, where you may want to specify other selections.
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.
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.
Source File: demain.c
Function: FreeSelectionList
API: (None)
This command deletes any existing selection lists and frees memory allocated for the list.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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):
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.
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.
Source File: demain.c
Function: EndSession
API: NWSMTSReleaseTargetService NWSMReleaseTSA
From the main menu, type Q to exit the Demonstration Engine.
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.
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
Novell, Inc. makes no representations or warranties with respect to the contents or use of this documentation, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. Further, Novell, Inc. reserves the right to revise this publication and to make changes to its content, at any time, without obligation to notify any person or entity of such revisions or changes.
Further, Novell, Inc. makes no representations or warranties with respect to any software, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. Further, Novell, Inc. reserves the right to make changes to any and all parts of Novell software, at any time, without any obligation to notify any person or entity of such changes.
Any products or technical information provided under this Agreement may be subject to U.S. export controls and the trade laws of other countries. You agree to comply with all export control regulations and to obtain any required licenses or classification to export, re-export, or import deliverables. You agree not to export or re-export to entities on the current U.S. export exclusion lists or to any embargoed or terrorist countries as specified in the U.S. export laws. You agree to not use deliverables for prohibited nuclear, missile, or chemical biological weaponry end uses. Please refer to the Novell International Trade Services Web page for more information on exporting Novell software. Novell assumes no responsibility for your failure to obtain any necessary export approvals.
Copyright © 2007 Novell, Inc. All rights reserved. No part of this publication may be reproduced, photocopied, stored on a retrieval system, or transmitted without the express written consent of the publisher.
Novell, Inc. has intellectual property rights relating to technology embodied in the product that is described in this document. In particular, and without limitation, these intellectual property rights may include one or more of the U.S. patents listed on the Novell Legal Patents Web page and one or more additional patents or pending patent applications in the U.S. and in other countries.
For Novell trademarks, see the Novell Trademark and Service Mark list.
All third-party trademarks are the property of their respective owners.