10.7 Using TSAIF to Back Up and Restore the iFolder Store

10.7.1 Understanding TSAIF

iFolder TSA

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 and Simias

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.

iFolder TSA Granularity

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.

10.7.2 Syntax

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.

10.7.3 iFolder Path Options

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.

10.7.4 iFolder Path Examples

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.

10.7.5 SMSConfig Options

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.

10.7.6 TSAIF and SMSConfig Examples

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%.

10.7.7 NBackup Options

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.

10.7.8 TSAIF and NBackup Examples

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

10.7.9 Additional Information

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).