The Target Service Agent (TSA) for iFolder supports the back up of the iFolder store.
Novell Storage Management Services (SMS) is an API framework that backup applications consume to provide a complete backup solution. The SMS framework is implemented by two main components: The Storage Management Data Requester and the Target Service Agent.
The TSA provides an abstraction of a particular backup target. The TSA uses native interfaces to read target data and transforms it to a continuous stream of data objects. The data objects are formatted in the ECMA standard System Independent Data Format (SIDF).
The TSA for iFolder (TSAIF) provides an implementation of the SMS API for an iFolder store. Backup applications, such as nbackup(1), can make use of its features by writing to the SMS API.
iFolder is built upon Simias technology. Simias is a general-purpose object repository that provides a foundation for building collaborative solutions. A Simias Collection store contains Collection objects. At a minimum, a Simias Collection store contains a Local Database Collection and one or more Domain Collections. The Local Database Collection controls access to the physical storage of the Collection store on the file system. A Domain Collection contains a list of members in a given domain. For example, a Domain might contain all the members from a given LDAP directory. Each Collection is owned by exactly one Domain member.
An iFolder is a type of Simias Collection that has a root directory on the file system. Each file or subdirectory in the iFolder’s root directory has a corresponding FileNode or DirNode in the Collection. An iFolder store is a Simias Collection store that contains one or more iFolders and includes the directories and files associated with the iFolders.
For more information on the iFolder and Simias technologies, see the iFolder Project at www.ifolder.com.
TSAIF supports creating archives that contain the following:
The entire iFolder store
All iFolders owned by a specified Domain member
An individual iFolder
TSAIF supports restoring the following:
The entire iFolder store
All iFolders owned by a specified Domain member
An individual iFolder
An individual subdirectory in an iFolder
An individual file in an iFolder
The entire iFolder store should be backed up regularly. In certain cases, a backup administrator might choose to back up an individual iFolder or to back up all iFolders owned by a specific owner. These special-case archives can be restored only to the same iFolder store from which they were backed up.
IMPORTANT:If you are restoring an entire iFolder and want to ensure that it is in the exact state it was in when it was backed up, you should first delete it from the server using a client or the iFolder Web Admin console or Web Access console.
Deleting the iFolder is not necessary to restore any or all of the files in the iFolder; the difference is in what metadata is given preference during the restore. If you do not delete the iFolder before restoring, the attributes of the iFolder, such as the owner, members, file type or size restrictions, remain as they are in the current version.
At an OES server terminal console, enter
smsconfig -l tsaif [OPTION]...
The -1 option registers the TSAIF with the Storage Management Data Requester (SMDR).
TSAIF uses the libtsaif.so file. The library implements all the necessary service functions to backup an iFolder target.
The top-level resource for an iFolder store is / (a single forward slash) and represents the root of the iFolder store. The paths for iFolder data objects are specified relative to the root of the iFolder store, using the syntax of the Network File System (NFS) namespace. iFolder paths are logical paths into an iFolder store and do not correspond directly to file system paths.
|
Parameter |
Description |
|---|---|
path |
iFolder path such as the following: / /owner /owner/collection /owner/collection/relative-path |
owner |
owner-name.owner-id |
owner-name |
Collection owner name (Simias.Storage.Collection.Owner.Name) |
owner-id |
Collection owner ID (Simias.Storage.Collection.Owner.ID) |
collection |
collection-name.collection-id |
collection-name |
Collection name (Simias.Storage.Collection.Name) |
collection-id |
Collection ID (Simias.Storage.Collection.ID) |
relative-path |
Relative path such as file subdir subdir/relative-path |
file |
name of file on file system |
subdir |
name of subdirectory on file system |
The \fIowner-id\fR and \fIcollection-id\fR are required because \fIowner-name\fR and \fIcollection-name\fR are not guaranteed to be unique. Using both the name and ID properties to identify Collections and Collection owners provides a “friendly” name along with the required unique identifier.
In many configurations, the names of Collections and Collection owners are unique. For example, if Domain members are obtained from an LDAP directory, it is not likely that two members would have the same username. Likewise, it would be unusual for an owner to give two iFolders the same name.
Although a backup application must pass both the name and ID to TSAIF, it might display only the name to the backup administrator to simplify the user interface. The ID would need to be displayed to the backup administrator only when two Collections, or two Collection owners, have the same name and the backup administrator wants to perform an operation on only one of them.
The name of the Collection or Collection owner can be obtained by stripping off the pattern
".????????-????-????-????-????????????"
from the first two components of the path TSAIF returns to the backup application.
The following examples show how to use iFolder paths to backup and restore data at different levels in the iFolder store.
/
Back up or restore the entire iFolder store.
/myOwner.12345678-1234-1234-1234-123456789abc
Back up or restore all Collections owned by myOwner.
/myOwner.12345678-1234-1234-1234-123456789abc/myCollection.22345678-1234-1234-1234-123456789abc
Back up or restore the Collection named myCollection. If the Collection is an iFolder, all files and directories in the iFolder will be backed up or restored along with the Simias data in the Collection store.
To backup and restore individual or group of files or subdirectories, use the backup engine- supported file filters. These file filters perform the include or exclude operations for selective backup and restore.
The TSAIF command is not a standalone shell command; it is exercised using smsconfig. All configuration options are managed via smsconfig. The TSAIF can be configured during registration and the configuration persists until TSAIF is unloaded.
All long options (options that have the format --optionname) are case insensitive.
|
Option |
Command |
|---|---|
--help |
Displays the options supported by the TSA. |
--ReadBufferSize |
This is the amount of data (Bytes) read from the Simias store and/or file system by a single read operation. This switch is based on the buffer sizes used by the applications. For example, if the application requests 32 KB of data for each read operation, set the buffer size to 32 KB to allow the TSA to service the application better. This value works well with Simias store and/or file system reads if set in multiples of 512 Bytes. The default value is 64 KB. |
--ReadThreadsPerJob |
This enables the TSA to read data ahead of the application request during backup. This switch is based on the number of processors in the system. This switch can also be used to influence the disk activity based on system configuration. The default value is 4. |
--ReadThreadAllocation |
This sets the maximum number of read threads that process a data set at a given time. This determines the percentage of ReadThreadsPerJob that should be allocated to a data set before proceeding to cache another data set. This enables the TSA to store a cache of data sets in a non sequential manner. This sets all read threads to completely process a data set before proceeding to another data set. The default value is 100. |
--ReadAheadThrottle |
This sets the maximum number of data sets that the TSA caches simultaneously. This prevents the TSA from caching parts of data sets and enables complete caching of data sets instead. Use this switch along with the ReadThreadAllocation switch. The default value is 2. |
--CacheMemoryThreshold |
This is used to specify the percentage of available server memory that the TSA can utilize to store cached data sets. This represents a maximum percentage value of available server memory that the TSA uses to store cached data sets. The default value is 10% of the total server memory. |
The following examples show how to perform typical TSAIF configuration for SMS.
smsconfig -l tsaif --help
Displays the options supported by the TSAIF.
smsconfig -l tsaif --readthreadsperjob=8
Sets the number of read threads that the TSAIF starts per job to 8.
smsconfig -l tsaif --readbuffersize=32768 --cachememorythreshold=15
Sets the read buffer size to 32KB and the maximum amount of cache memory that the TSAIF should use to 15%.
TSAIF supports the following typical nbackup(1) options:
|
Option |
Command |
|---|---|
--exclude-file=pattern |
Excludes all files matching the name (owner, folder, or file) or pattern for back up or restore. Use this option multiple times to exclude more than one pattern. |
-F, --full-paths |
Stores the full paths for both directories and files in the created archive. |
-k, --keep-old-files |
Does not overwrite existing files while extracting files from the archive. Files are overwritten if this option is not present. |
-N, --after-date=date |
Backs up files newer than date. |
-P, --password=password |
The password to connect to the TSA. The password can be supplied at runtime. |
-R, --remote-target=hostname |
Connects to the file system TSA of the host specified in hostname for backup. Use with the --target-type option. |
--target-type=target_name |
Connects to the TSA specified by target_name, where the target name is Linux, or iFolder. |
-T, --input-file=file |
Takes file containing fully qualified paths as input for creating archive. This file should contain one path per line. |
-U, --user=username |
Username to use while connecting to the TSA. |
TSAIF does not support the following nbackup(1) options:
|
Option |
Command |
|---|---|
-m, --move-to=path |
Extracts the archive to the given path. This does not work with TSAIF because iFolder puts files in a SimiasFiles directory. |
-r, --restore-to="backup_path new_path" |
Restores by replacing backup_path with new_path. This does not work with TSAIF because iFolder puts files in a SimiasFiles directory. |
If TSAIF cannot back up or restore a file, it skips the file and returns a warning. This can occur for various reasons. When this occurs, nbackup(1) creates a file with a .warn extension that contains a list of each file that was skipped along with the date and time it was skipped and the error code that was returned.
If files are skipped, try to resolve the issue, then run the operation again.
If you are unable to identify why the file was skipped, try running the operation again when the server is less busy.
If files are skipped during a restore, and if relatively few files are skipped, try individually restoring each skipped file.
The back-up administrator should use root or root-equivalent system user for both back-up and restore.
The following examples show how to perform typical TSAIF backup and restore operations using NBackup.
|
Backup or Restore Task |
Command |
|---|---|
|
Full backup |
nbackup -cvf full.sidf -U root -P password --target-type=ifolder / |
|
Full restore |
nbackup -xvf full.sidf -U root -P password --target-type=ifolder |
|
Owner backup |
nbackup -cvf owner.sidf -U root -P password --target-type=ifolder /owner.id |
|
Owner restore |
nbackup -xvf owner.sidf -U root -P password --target-type=ifolder |
|
Owner restore from the full backup file full.sidf |
nbackup -xvf full.sidf -U root -P password --target-type=ifolder --extract-dir=/owner |
|
iFolder backup |
nbackup -cvf ifolder.sidf -U root -P password --target-type=ifolder /owner/collection.id |
|
iFolder restore |
nbackup -xvf ifolder.sidf -U root -P password --target-type=ifolder nbackup -xvf owner.sidf -U root -P password --target-type=ifolder --extract-dir=/owner/collection nbackup -xvf full.sidf -U root -P password --target-type=ifolder --extract-dir=/owner/collection If you are restoring an entire iFolder and want to ensure that it is in the exact state it was in when it was backed up, you should first delete the current iFolder from the server using a client or the iFolder 3 plug-in for iManager. Deleting the iFolder is not necessary to restore any or all of the files in the iFolder; the difference is in what metadata is given preference during the restore. If you do not delete the iFolder before restoring, the attributes of the iFolder, such as the owner, members, file type or size restrictions, remain as they are in the current version. |
|
Subdirectory restore |
nbackup -xvf ifolder.sidf -U root -P password --target-type=ifolder --extract-dir=/owner/collection/relative-path nbackup -xvf owner.sidf -U root -P password --target-type=ifolder --extract-dir=/owner/collection/relative-path nbackup -xvf full.sidf -U root -P |
For more information about backup, see the following man pages on your iFolder enterprise server: nbackup(1), sms(7), smdrd(8), smsconfig(1), tsaif.conf(5).