This appendix describes the language used in dataset files. A dataset file is a text file that describes the data that Oracle Secure Backup should back up.
This chapter contains the following topics:
See Also:
The sample dataset files located in the samples
subdirectory of the Oracle Secure Backup home
The Oracle Secure Backup dataset language provides a simple, text-based means to define file system data that you want Oracle Secure Backup to back up. The language has the following characteristics:
Comments can appear anywhere following a pound sign (#).
Dataset statements use the following syntax:
statement-name [ statement-argument ]
The statement-name placeholder represents a dataset statement. These statements are described in "Dataset Statements".
Some statements can begin a nested block. Statements within the block apply only to the statement that began the block. Nested block statements have the following form:
statement-name [ statement-argument ] { statement-name [ statement-argument ] ... }
An escape character, which is represented by a backslash (\
), can appear anywhere to remove the special meaning of the character following it.
Blank lines are ignored.
Example D-1 is a sample dataset file that describes a backup of directories on brhost2
.
# # A sample dataset file # exclude name *.backup # never back up directories or files exclude name *~ # matching *.backup and *~ include host brhost2 { # back up host brhost2 include path /usr1/home { # back up /usr1/home on brhost2, exclude path /usr1/home/peter # but skip directories peter and dinesh exclude path /usr1/home/dinesh } include path /usr2/home # also back up /usr2/home, including } # peter and dinesh if they exist
A dataset description can contain the following types of statements:
See Also:
"Dataset File Examples" for examples of description files that use these statements.Use the after backup
statement to direct Oracle Secure Backup to run a machine executable or interpreted program after completing a backup. By using the before backup statement, you can also execute the same or a different program before the backup begins. These statements are useful, for example, when you want to shut down and restart a database server or inform users that a backup has started or completed.
By default, Oracle Secure Backup stops the backup job and considers it failed if the specified executable does not exist or fails, that is, returns a nonzero exit code.
after backup [ optional ] pathname
The pathname placeholder represents the name of the program to be executed on a client host. For backups using an NDMP data service, Oracle Secure Backup executes the program on the administrative server.
The optional
keyword specifies that Oracle Secure Backup should ignore the status returned from the invoked program and also the inability to invoke this program.
Example D-2 directs Oracle Secure Backup to pass the argument /usr2 is being saved
to program /etc/local/nfy
on host brhost2
after backing up directory /usr2
.
Example D-2 after backup Statement
include host fserver { include path /usr2 after backup "/etc/local/nfy '/usr2 backup complete'" }
Oracle Secure Backup automatically appends the following arguments to any that you specify:
The token after
The name of the client
The name of the directory or file being backed up
Thus, in Example D-2 Oracle Secure Backup executes the nfy
program on brhost2
as if you entered:
/usr/local/nfy '/usr2 is being saved' after brhost2 /usr2
Use the before backup
statement to direct Oracle Secure Backup to run a machine executable or interpreted program before beginning a backup. This statement is parallel to the after backup statement.
By default, Oracle Secure Backup does not begin the backup job and considers it failed if the specified executable does not exist or fails, that is, returns a nonzero exit code.
before backup [ optional ] pathname
The pathname placeholder represents the name of the program to be executed on a client host. For backups using an NDMP data service, Oracle Secure Backup executes the program on the administrative server.
The optional
keyword specifies that Oracle Secure Backup should ignore the status returned from the invoked program and also the inability to invoke this program.
Example D-3 directs Oracle Secure Backup to pass the argument /usr2 is being saved
to program /etc/local/nfy
on host brhost2
before backing up directory /usr2
.
Example D-3 before backup Statement
include host brhost2 { include path /usr2 before backup "/etc/local/nfy '/usr2 is being saved'" }
Oracle Secure Backup automatically appends the following arguments to any that you specify:
The token before
The name of the client
The name of the directory or file being backed up
Thus, in Example D-3 Oracle Secure Backup executes the nfy
program on brhost2
as if you entered:
/usr/local/nfy '/usr2 is being saved' before brhost2 /usr2
Use the cross all mountpoints
statement to cross local and remote mount points. A local mount point mounts a local file system; a remote mount point is a local mount of a file system accessed over the network. By default, file system backups do not cross mount points.
Suppose /home/usr1/loc_data
mounts a local file system, while /home/usr1/rem_data
is an NFS mount point for a file system on a network host. You can use cross all mountpoints
to specify that a backup of /home/usr1
includes all files in this directory, whether local or mounted.
Example D-4 crosses all local and remote mount points on hosts brhost1
and brhost2
.
Example D-4 Global Host Inclusion
cross all mountpoints include host brhost1 { include path /home/usr1 } include host brhost2 { include path /home/usr2 }
Example D-5 crosses all local and remote mount points in the paths for host brhost1
but not brhost2
.
Example D-5 Global Path Inclusion
include host brhost1 { cross all mountpoints include path /home/usr1 } include host brhost2 { include path /home/usr2 }
Example D-6 crosses all local and remote mount points in the /home/usr1
path, but not in the /home/usr2
path, on brhost1
.
Use the cross local mountpoints
statement to cross local (but not remote) mount points.
Suppose /home/usr1/loc_data
mounts a local file system while /home/usr1/rem_data
is an NFS mount point for a file system on a network host. You can use cross local mountpoints
to specify that a backup of /home/usr1
includes files in /home/usr1/loc_data
but not /home/usr1/rem_data
.
Example D-7 crosses only local mount points in the file systems for hosts brhost1
and brhost2
.
Example D-7 Global Host Inclusion
cross local mountpoints include host brhost1 { include path /home/usr1 } include host brhost2 { include path /home/usr2 }
Example D-8 crosses local mount points in the /home/usr1
path on host brhost1
, but does not cross mount points in the /home/usr2
path on brhost2
.
Example D-8 Global Path Inclusion
include host brhost1 { cross local mountpoints include path /home/usr1 } include host brhost2 { include path /home/usr2 }
Example D-9 crosses local mount points found in the /home/usr1
path, but no mount points in the /home/usr2
path, on brhost1
.
Use the cross remote mountpoints
statement to cross remote (but not local) mount points.
Suppose /home/usr1/loc_data
is a mount point for a local file system, while /home/usr1/rem_data
is an NFS mount point for a file system on a network host. You can use cross remote mountpoints
to specify that a backup of /home/usr1
includes files in /home/usr1/rem_data
but not /home/usr1/loc_data
.
Example D-10 crosses only remote mount points in the file systems on hosts brhost1
and brhost2
.
Example D-10 Global Host Inclusion
cross remote mountpoints include host brhost1 { include path /home/usr1 } include host brhost2 { include path /home/usr2 }
Example D-11 crosses only remote mount points in the /home/usr1
path on brhost1
.
Example D-11 Global Path Inclusion
include host brhost1 { cross remote mountpoints brhost3 include path /home/usr1 } include host brhost2 { include path /home/usr2 }
Example D-12 crosses only remote mount points in the /home/usr1
path and only local mount points in the /home/usr2
path.
Use the exclude name
statement to identify the right-most component name, which is called the leafname, of a file system object that you want to exclude from the backup.
exclude name leafname
Oracle Secure Backup compares the component name of each file system object with the specified leafname and, if they match, does not back up the file system object; if it is a directory, then Oracle Secure Backup does not back up the directory contents.
Oracle Secure Backup interprets leafname as a UNIX-style wildcard expression if it contains any of the unescaped special characters *
, ?
, [
, or ]
. If leafname contains these characters, then Oracle Secure Backup performs a wildcard comparison rather than a string comparison to determine whether the names match.
The dataset statements shown in Example D-13 exclude files named core
and files whose names ends in .backup
.
Use the exclude oracle database files
statement to exclude all Oracle database-related files that would ordinarily be backed up by RMAN or files whose backup is not recommended. Oracle Secure Backup excludes the files regardless of whether the files being excluded are part of an existing RMAN backup strategy.
Oracle Secure Backup excludes the following types of files:
Datafiles (production files and image copies of those files)
Control files
Redo logs, both online and archived
Flashback logs
Change tracking file
Backup pieces
Tempfiles
Note:
You use the Oracle Enterprise Manager job scheduler to schedule database backups through RMAN and the Oracle Secure Backup job scheduler to schedule file system backups. Thus, to back up an Oracle database host with Oracle Secure Backup, you must set up two schedules in Enterprise Manager and Oracle Secure Backup. Use theexclude oracle files
statement in the Oracle Secure Backup schedule so that the Oracle database-related files are not backed up twice.The dataset file shown in Example D-14 excludes Oracle database-related files from the backup of host brhost2
.
Use the exclude path
statement to identify the path name of a file system object that you want to exclude from the backup.
The dataset statements shown in Example D-15 specify a backup up the D:\Public
directory on host brhost3
, but skip two subdirectories.
Use the include dataset
statement to direct Oracle Secure Backup to read another dataset file and logically substitute its contents in place of the include dataset statement. This statement is analogous to include statements found in most programming languages.
include dataset dataset_file_name
The dataset_file_name placeholder represents the name of a dataset file or directory. If you supply the name of a dataset directory, then Oracle Secure Backup includes each member of the directory.
Use the include host
statement to identify the name of a client host that you want to back up. An include host
statement can be located anywhere in the dataset file.
A usable dataset file must have at least one host statement either within the dataset file or within an included dataset file.
The include host
statements takes either of the following forms.
include host hostname
include host hostname { statements_that_apply_to_hostname }
The hostname placeholder represents the name of a client you defined earlier with the Web tool interface or the mkhost
or renhost
commands.
Use the include path
statement to identify the name of a file system object that you want to back up.
Note:
Backup paths cannot exceed the maximum path length of the file system being backed up and in any case cannot exceed 1023 characters.
include path absolute-pathname
The absolute-pathname placeholder represents the path name of the file system object to back up, starting at the file system root. Surround path names containing spaces within single or double quotes.
Example D-17 shows an include path
statement on a Windows system. The path contains spaces, so it is surrounded by double quotes.
For Linux and Unix systems, the include path
statements do not include drive designators or quotation marks. Example D-18 shows an include path statement on a Linux or UNIX system.
Example D-18 include path Statement on Linux/UNIX
include path /space { # include the local root directory exclude name core # but no core files (for UNIX) exclude name *~ # and no emacs backup files } include path /etc
You can nest an include path
statement within an include host
statement. Consider the dataset statements shown in Example D-19.
Example D-19 include host Statements
include host brhost2 include host brhost3 include path /home include path /project
Oracle Secure Backup interprets each include path
statement in the dataset file to apply to each include host
statement. Thus, Oracle Secure Backup backs up the /home
and /project
directories on each host, brhost2
and brhost3
.
The statements in Example D-19 are equivalent to the statements in Example D-20.
Example D-20 Dataset File with include host and include path Statements
include host brhost2 { include path /home include path /project } include host brhost3 { include path /home include path /project }
Example D-21 backs up /home
on host brhost2
and /project
on host brhost3
.
Example D-21 Dataset File with include host and include path Statements
include host brhost2 { include path /home } include host brhost3 { include path /project }
You should only include multiple host or paths in a dataset file if you always back them up together. The Oracle Secure Backup scheduler and on-demand backup function use dataset file names, not path names, to define each backup job.
This section presents examples of dataset files. This section contains the following topics:
Example D-22 shows a complex dataset file that describes four host systems to be backed up. It specifies that all files in the /home
, /usr
, and /usr2
directories and all files in subdirectories within these directories are to be backed up.
All files in the /usr/tmp
directory are excluded from the dataset. Files that have the name core
and files that have names ending in .bak
, regardless of where they reside, are also excluded from the dataset.
A dataset file can logically include the contents of another dataset file. The include dataset
statement lets you include by reference the contents of another dataset file.
Consider the sample dataset file called common-exclusions.ds
shown in Example D-23.
Example D-23 common-exclusions.ds
exclude name core exclude name *~ exclude name *.tmp exclude name *.temp
A dataset file can use these exclusions with the statement shown in Example D-24.
To apply these exclusions to one path but not to another, specify the include dataset
directive within braces as shown in Example D-25.
You can use braces with an include rule to define the scope of a backup. In Example D-26, Oracle Secure Backup backs up paths /usr1
and /usr2
on all servers and backs up /usr3
and /usr4
on brhost3
only. Note that the order in which the rules appear within the braces has no affect on the rules.
Example D-26 Using Braces to Limit Scope
# Common trees backed up on all servers: include path /usr1 include path /usr2 # Servers to back up; on brhost3, we also back up usr3 & usr4, too: include host brhost1 include host brhost2 include host brhost3 { include path /usr3 include path /usr4 }
You can use additional braces to further refine the scope of rules. Example D-27 alters Example D-26 to exclude files ending with .junk
from /usr4
on brhost3
only.
Example D-27 Refining the Scope of a Set of Rules
# Common trees backed up on all servers: include path /usr1 include path /usr2 # Servers to back up; on brhost3, back up /usr3 and /usr4, but exclude *.junk # files in /usr4 only: include host brhost1 include host brhost2 include host brhost3 { include path /usr3 include path /usr4 { exclude name *.junk } }