Go to main content
9/17

# 5 Dataset Language

This chapter 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:

- Overview of the Dataset Language

- Dataset File Examples

- Backward Compatibility

- Dataset Statements

See Also:

- "Dataset Commands"

- The sample dataset files located in the samples subdirectory of the Oracle Secure Backup home

## Overview of the Dataset Language

The Oracle Secure Backup dataset language provides a simple, text-based means to define file-system data 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 5-1 is a sample dataset file that describes a backup of directories on brhost2.

Example 5-1 Sample Dataset

    #
    # 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 peter               # skip subdirectory peter (relative path)
            exclude path /usr1/home/dinesh   # also skip subdir dinesh (absolute path)
        }
        include path /usr2/home              # also back up /usr2/home, including
    }                                        # all subdirectories

## Dataset File Examples

This section presents examples of dataset files.

This section contains the following topics:

- Backing Up Multiple Paths on Multiple Hosts

- Including Dataset Files Within Dataset Files

- Defining the Scope of a Backup

### Backing Up Multiple Paths on Multiple Hosts

Example 5-2 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.

Example 5-2 Backing Up Multiple Paths on Multiple Hosts

    include host brhost1
    include host brhost2
    include host brhost3
    include host brhost4

    include path /home
    include path /usr
    include path /usr/usr2

    exclude path /usr/tmp
    exclude name core
    exclude name *.bak

### Including Dataset Files Within Dataset Files

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 5-3.

Example 5-3 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 5-4.

Example 5-4 Including a Dataset File

    include dataset common-exclusions.ds

To apply these exclusions to one path but not to another, specify the `include` `dataset` directive within braces as shown in Example 5-5.

Example 5-5 Applying Exclusions to a Path

    include path /home/root            # do not exclude here
    include path /home/frank {         # do exclude here
          include dataset common-exclusions.ds
    }

### Defining the Scope of a Backup

You can use braces with an include rule to define the scope of a backup. In Example 5-6, 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 5-6 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 5-7 alters Example 5-6 to exclude files ending with .junk from `/usr4` on `brhost3` only.

Example 5-7 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
          }
     }

## Backward Compatibility

If you specify a wildcard pattern in an `exclude` `path` or `exclude` `name` statement, then Oracle Secure Backup release 10.3 attempts to match the pattern while respecting path separators. If you specify pattern `src/*.pl`, for example, then Oracle Secure Backup would exclude `src/a.pl` but not `src/tmp/b.pl`.

The exclusion statement wildcard pattern matching in previous releases of Oracle Secure Backup did not respect path separators. If you specified the same `src/*.pl` pattern, for example, then Oracle Secure Backup would exclude both `src/a.pl` and `src/tmp/b.pl`.

If you have upgraded to Oracle Secure Backup release 10.3 from an earlier Oracle Secure Backup release, then you can continue using your existing `exclude` `path` and `exclude` `name` statements. Some files and directories that were excluded from backups in the earlier Oracle Secure Backup release are now not excluded. This causes your backup files to be somewhat larger, but all data still backed up.

## Dataset Statements

A dataset description can contain the following types of statements:

- after backup

- before backup

- cross all mountpoints

- cross local mountpoints

- cross remote mountpoints

- exclude dir

- exclude file

- exclude name

- exclude oracle database files

- exclude path

- include catalog

- include dataset

- include host

- include path

See Also:

"Dataset File Examples" for examples of description files that use these statements.

### after backup

Purpose

Use the `after` `backup` statement to direct Oracle Secure Backup to run a computer executable or interpreted program after completing a backup. By using the before backup statement, you can also run 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.

Syntax

after backup::=

      after backup [ optional ] pathname

The `pathname` placeholder represents the name of the program to be run on a client host. For backups using a Network Data Management Protocol (NDMP) data service, Oracle Secure Backup runs 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

Example 5-8 after backup Statement

This example 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`.

    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

- The exit status of the backup operation (a numeric value documented in the file `OSB_HOME/samples/obexit.h`.)

Thus, in this example Oracle Secure Backup runs the `nfy` program on `brhost2` as if you entered:

    /usr/local/nfy '/usr2 backup complete' after brhost2 /usr2 exit-code

### before backup

Purpose

Use the `before backup` statement to direct Oracle Secure Backup to run a computer 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.

Syntax

The `pathname` placeholder represents the name of the program to be run on a client host. For backups using a Network Data Management Protocol (NDMP) data service, Oracle Secure Backup runs the program on the administrative server.

before backup::=

      before backup [ optional ] pathname

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

Example 5-9 before backup Statement

This example 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`.

    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 this example Oracle Secure Backup runs the `nfy` program on `brhost2` as if you entered:

    /usr/local/nfy '/usr2 is being saved' before brhost2 /usr2

### cross all mountpoints

Purpose

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, a file-system backup does not cross mount points.

Suppose `/home/usr1/loc_data` mounts a local file system, while `/home/usr1/rem_data` is an Network File System (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.

Syntax

cross all mountpoints::=

      cross all mountpoints

Examples

Example 5-10 Global Host Inclusion

This example crosses all local and remote mount points on hosts `brhost1` and `brhost2`.

    cross all mountpoints
    include host brhost1 {
          include path /home/usr1
    }
    include host brhost2 {
          include path /home/usr2
    }

Example 5-11 Global Path Inclusion

This example crosses all local and remote mount points in the paths for host `brhost1` but not `brhost2`.

    include host brhost1 {
          cross all mountpoints
          include path /home/usr1
    }
    include host brhost2 {
          include path /home/usr2
    }

Example 5-12 Local Path Inclusion

This example crosses all local and remote mount points in the `/home/usr1` path, but not in the `/home/usr2` path, on `brhost1`.

    include host brhost1 {
          include path /home/usr1 {
                cross all mountpoints
          }
          include path /home/usr2
    }

### cross local mountpoints

Purpose

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 a Network File System (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`.

Syntax

cross local mountpoints::=

      cross local mountpoints

Examples

Example 5-13 Global Host Inclusion

This example crosses only local mount points in the file systems for hosts `brhost1` and `brhost2`.

    cross local mountpoints
    include host brhost1 {
          include path /home/usr1
    }
    include host brhost2 {
          include path /home/usr2
    }

Example 5-14 Global Path Inclusion

This example 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`.

    include host brhost1 {
          cross local mountpoints
          include path /home/usr1
    }
    include host brhost2 {
          include path /home/usr2
    }

Example 5-15 Local Path Inclusion

This example crosses local mount points found in the `/home/usr1` path, but no mount points in the `/home/usr2` path, on `brhost1`.

    include host brhost1 {
          include path /home/usr1 {
                cross local mountpoints
          }
          include path /home/usr2
    }

### cross remote mountpoints

Purpose

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 a Network File System (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`.

Syntax

cross remote mountpoints::=

      cross remote mountpoints

Examples

Example 5-16 Global Host Inclusion

This example crosses only remote mount points in the file systems on hosts `brhost1` and `brhost2`.

    cross remote mountpoints
    include host brhost1 {
          include path /home/usr1
    }
    include host brhost2 {
          include path /home/usr2
    }

Example 5-17 Global Path Inclusion

This example crosses only remote mount points in the `/home/usr1` path on `brhost1`.

    include host brhost1 {
          cross remote mountpoints brhost3
          include path /home/usr1
    }
    include host brhost2 {
          include path /home/usr2
    }

Example 5-18 Local Path Inclusion

This example crosses only remote mount points in the `/home/usr1` path and only local mount points in the `/home/usr2` path.

    include host brhost1 {
          include path /home/usr1 {
                cross remote mountpoints
          }
          include path /home/usr2 {
                cross local mountpoints
          }
    }

### exclude dir

Purpose

Use the `exclude` `dir` statement to identify a directory or set of directories to exclude from a backup. It differs from `exclude` `name` in that it does not exclude files matching the specified pattern.

Syntax

exclude dir::=

      exclude dir pattern

Semantics

pattern

  Specifies the directory or set of directories to be excluded. The `pattern` placeholder must not include any path separators. It supports UNIX-style wildcard syntax expression-based pattern matching.

### exclude file

Purpose

Use the `exclude` `file` statement to identify file-system objects to exclude from backup by file name, without regard for the directory location of the file. It differs from `exclude` `name` in that it does not exclude directories matching the specified pattern.

Syntax

exclude file::=

      exclude file pattern

Semantics

pattern

  Specifies the file or set of files to be excluded. The `pattern` placeholder must not include any path separators. It supports UNIX-style wildcard syntax expression-based pattern matching.

### exclude name

Purpose

Use the `exclude` `name` statement to identify file-system objects to exclude from backup either by the right-most matching component name in the path, which is called the leafname, or by a matching relative path or pattern.

See Also:

"Backward Compatibility"

Syntax

exclude name::=

      exclude name  { leafname | relative_pathname }

Semantics

leafname

  Oracle Secure Backup compares the component name of each file-system object with the specified `leafname`. If they match, then Oracle Secure Backup 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.

relative_pathname

  Oracle Secure Backup compares the component name of each file-system object with the specified `relative_pathname` relative to the current included path. If they match, then Oracle Secure Backup does not back up the file-system object. If `relative_pathname` references a directory, then Oracle Secure Backup does not back up the directory contents.

  Oracle Secure Backup interprets `relative_pathname` as a UNIX-style wildcard expression if it contains any of the unescaped special characters `*`, `?`, `[`, or `]`. If `relative_pathname` contains these characters, then Oracle Secure Backup performs a wildcard comparison rather than a string comparison to determine whether the names match.

Example

Example 5-19 exclude name Statement

Assume a directory tree containing the following files and directories:

    /src
    /src/abc
    /src/abc/a.pl
    /src/tmp
    /src/tmp/g.pl
    /src/tmp/src/d.plaf
    /src/tmp/src/a.pldir
    /src/tmp/src/a.pldir/a.pl
    /src/tmp/src/a.pldir/s.tmp
    /src/tmp/src/a.pl
    /src/a.pl
    /src/b.pl

You create a dataset with the following contents:

    exclude name d
    exclude name *.tmp

The dataset statements exclude files or directories named `d` and files whose names end in `.tmp`. For the assumed directory tree, the following items would be excluded from backup operations:

    /src/tmp/src/d.plaf
    /src/tmp/src/a.pldir/s.tmp

### exclude oracle database files

Purpose

Use the `exclude oracle database files` statement to exclude all Oracle database-related files that would ordinarily be backed up by Recovery Manager (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:

- Data files (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 a database backup through RMAN and the Oracle Secure Backup job scheduler to schedule a file-system backup. 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 the `exclude oracle files` statement in the Oracle Secure Backup schedule so that the Oracle database-related files are not backed up twice.

Syntax

exclude oracle database files::=

      exclude oracle database files

Example

Example 5-20 exclude oracle database files Statement

This dataset file excludes Oracle database-related files from the backup of host `brhost2`.

    exclude name *.backup
    exclude name *~
    include host brhost2 {
          exclude oracle database files
          exclude path /usr1/home
    }

### exclude path

Purpose

Use the `exclude` `path` statement to identify the path name or wildcard pattern of file-system objects to exclude from the backup.

See Also:

"Backward Compatibility"

Syntax

exclude path::=

      exclude path
         (absolute-path | relative-path)

Semantics

absolute-path

  Specifies a path or pattern matching subdirectories or files in subdirectories relative to the root of the file system. Absolute paths on Windows platforms begin with `drive-letter`:\, and on UNIX with /.

relative-path

  Specifies a path or pattern matching subdirectories or files in subdirectories relative to the current `include path`.

Examples

Example 5-21 exclude path Statement

Assume the following set of directories and files to be backed up on host `osblin1`:

    /src
    /src/abc
    /src/abc/a.tmp
    /src/tmp
    /src/tmp/g.pl
    /src/tmp/src/d.tmp1
    /src/tmp/src/a.tmprary
    /src/tmp/src/a.pldir/a.tmp
    /src/tmp/src/d.tmp-out
    /src/tmp/src/a.
    /src/a.pl
    /src/b.pl
    /misc
    /misc/yesterday.tmp
    /misc/tmpsql.out

The following dataset specifies a backup of the `/` directory on `osblin1`, but skips files in `/src/tmp` and files with the extension `.tmp` at any level of the `/src` directory.

    include host osblin1 {
          include path / {
                exclude path src/tmp
                exclude path recursive *.tmp
          }
    }

### include catalog

Purpose

Use the `include` `catalog` statement to direct Oracle Secure Backup to back up all data on the administrative server required to restore the Oracle Secure Backup catalog. This directive is expanded internally by the dataset parser to a list of all required files and databases.

This directive can be included in other datasets. But it cannot be used within an include host bloc, because by definition it only applies to the administrative server host.

You can add extra files and paths on the administrative server host to the files backed up by `include` `catalog` by listing include path, exclude path and exclude name directives within block delimiters beneath the `include` `catalog` directive. No other directives are permitted within the `include` `catalog` block.

A catalog backup is always created as a full backup and never as an incremental backup. Restoring from incremental backups is difficult without the contents of the catalog, so creating catalog backups as full backups is more reliable.

In a catalog recovery situation, the wallet containing encryption keys might not be available. Therefore, the expanded catalog directive and its children are handled in a separate job by the scheduler, which runs with storage encryption policies disabled.

You can still use transient passphrase encryption to protect this backup, because transient passphrase encryption does not depend upon the wallet.

If you use `include` `path` directives to add extra files with sensitive contents to the catalog backup, then consider using transient passphrase encryption to protect the backup containing these files.

Syntax

include catalog::=

      include catalog
           [ { directive... } ]

Semantics

include catalog

  Include all data required for a future catalog recovery.

directive

  Specify include path directives to add to the data backed up for catalog backups. Use exclude path and exclude name directives to subtract from the data backed up for catalog backups.

Example

Example 5-22 include catalog Directive with Extra Files

This example includes every dataset file in the `admin/default_rules` directory.

    include catalog {
         include path /home/adminuser
       }

### include dataset

Purpose

Use the `include` `dataset` statement to direct Oracle Secure Backup to read another dataset file and logically substitute its contents for the `include` `dataset` statement. This statement is analogous to include statements found in most programming languages.

Syntax

include dataset::=

      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.

Example

Example 5-23 include dataset Statement

This example includes all dataset files in the `admin/default_rules` directory.

    include dataset admin/default_rules

### include host

Purpose

Use the `include host` statement to identify the name of a client host 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.

Syntax 1

include host::=

      include host hostname

Syntax 2

include host::=

      include host hostname {statements_that_apply_to_hostname}

The `hostname` placeholder represents the name of a client you defined earlier with the Oracle Secure Backup Web tool interface or the `mkhost` or `renhost` commands.

Example

Example 5-24 include path Statement

This example includes host `brhost2`:

    include host brhost2

### include path

Purpose

Use the `include` `path` statement to identify the name of a file-system object to back up.

Backup paths cannot exceed the maximum path length of the file system being backed up, and in any case they cannot exceed 260 characters on Windows systems or 1024 characters on other operating systems.

Path names on both Windows and Linux/UNIX can include the standard wildcard characters `*`, `?`, `[`, and `]`. If you have path names that include any of these wildcard characters, then you must precede each such character with a backslash (`\`) character to prevent special interpretation of these characters.

Syntax

include path::=

      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.

Examples

Example 5-25 include path Statement on Windows

This example shows an `include path` statement on a Windows system. The path contains spaces, so it is surrounded by double quotes.

    include path "C:\Documents and Settings"

Example 5-26 include path Statement on Linux/UNIX

For Linux or UNIX systems, the `include path` statements do not include tape drive designators or quotation marks. This example shows an `include` `path` statement on a Linux or UNIX system.

    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

Example 5-27 include host Statements

You can nest an `include path` statement within an `include host` statement. Consider the dataset statements shown in this example.

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

    include host brhost2
    include host brhost3
    include path /home
    include path /project

Example 5-28 Dataset File with include host and include path Statements

This example backs up `/home` on host `brhost2` and `/project` on host `brhost3`. The statements in this example are equivalent to the statements in Example 5-29.

    include host brhost2 {
          include path /home
          include path /project
    }
    include host brhost3 {
          include path /home
          include path /project
    }

Example 5-29 Dataset File with include host and include path Statements

The statements in this example are equivalent to the statements in Example 5-28.

    include host brhost2 {
          include path /home
    }
    include host brhost3 {
          include path /project
    }

Only include multiple hosts or paths in a dataset file if you always back them up. The Oracle Secure Backup scheduler and on-demand backup functions use dataset file names, not path names, to define each backup job.