1 About obtool

This chapter explains how to use the obtool command-line interface. The following topics are covered:

obtool Invocation
obtool Online Help
obtool Command Categories

obtool Invocation

This section explains how to invoke the obtool utility, which is a command-line interface to Oracle Secure Backup. You can obtain online help about obtool invocation options by running the following command at the operating system prompt:

% obtool help invocation

The obtool utility displays the following output:

obtool invocation:
Usage: To enter interactive mode:
       obtool [<cl-option>]...]
Usage: To execute one command and exit:
       obtool [<cl-option>]... <command> [<option>]... [<argument>]...
Usage: To display program version number and exit:
       obtool --version/-V
Usage: To create a new administrative domain with this machine acting as the
       administrative server:
       obtool --initnewdomain [--adminpassword/-A passwd] [--force] 
       [--nullpassword/-N] [--verbose/-v]

The following sections explain the obtool invocation options in more detail.

obtool Login

The first time you invoke the obtool utility, you are required to establish your identity as an Oracle Secure Backup user. If you have not yet established a user identity, then obtool prompts you for a user name and password, as shown in the following example:

% obtool
Oracle Secure Backup 10.1
login:

On a new installation, Oracle Secure Backup creates the admin user automatically and prompts you for the password.

Login and Preauthorization

After you have logged into obtool, Oracle Secure Backup stores your identity in a login token located in the /admin/config/user subdirectory. The information for each user is stored in a separate file. The lifetime of the login token is controlled by the loginduration security policy.

The Oracle Secure Backup command-line tools authenticate users either with an explicit login or with a preauthorization. In the latter case, access is authorized only for the specified operating system user on the specified host. You can create a preauthorization by specifying --preauth on the mkuser command.

When you invoke an Oracle Secure Backup command-line tool, it finds the user ID according to the following rules of precedence:

If you specify an explicit user ID, then the user ID is used for the operation. You must specify the correct password for this user ID.
If you do not specify a user ID, and if an applicable login token exists that indicates that this user has a persistent explicit login, then Oracle Secure Backup uses the user ID associated with this token for the operation. Note that persistent tokens are never created for sessions that have been preauthorized.
If you do not specify a user ID, and if no applicable persistent login token exists, then Oracle Secure Backup attempts to find a matching preauthorization. If no preauthorization exists, then some command-line tools prompt for a user ID, whereas others fail and exit.

The rules for locating a matching preauthorization are the same for both command-line operations and RMAN backup and restore operations. If two or more preauthorizations could match, then Oracle Secure Backup prioritizes matches as shown in Table 1-1.

Table 1-1 Priority of Preauthorization Matching

priority	hostname	userid	domain
1	explicitly specified	explicitly specified	explicitly specified
2	*	explicitly specified	explicitly specified
3	*	explicitly specified	unspecified
4	*	unspecified	unspecified

obtool Interactive Mode

To use obtool in interactive mode, enter obtool at the operating system command line once.

obtool Syntax for Interactive Mode

Use the following syntax when invoking obtool in interactive mode:

obtool [ cl-option ]...

Table 1-2 describes the legal substitutions for the cl-option placeholder.

Table 1-2 cl-option

Option Meaning

Option	Meaning
`--longerrors/-E`	Shows error messages in long form. See also "errors".
`--norc/-n`	Does not execute commands from `.obtoolrc`. You can put a sequence of `obtool` commands in this file for `obtool` to execute whenever it is invoked. By default, `obtool` automatically searches for `.obtoolrc` in the current directory. If this file is not found and if the `HOME` environment variable is defined, then `obtool` searches for the file in the `HOME` directory. When the file is located, `obtool` reads the file before it enters interactive mode.
`--verbose/-v`	Displays extra informational messages. See also "verbose".

--longerrors/-E

Shows error messages in long form. See also "errors".

--norc/-n

Does not execute commands from .obtoolrc. You can put a sequence of obtool commands in this file for obtool to execute whenever it is invoked.

By default, obtool automatically searches for .obtoolrc in the current directory. If this file is not found and if the HOME environment variable is defined, then obtool searches for the file in the HOME directory. When the file is located, obtool reads the file before it enters interactive mode.

--verbose/-v

Displays extra informational messages. See also "verbose".

Command Execution in Interactive Mode

After a successful login to obtool, the following prompt is displayed:

ob>

You can enter the commands described in Chapter 2, "obtool Commands" at the obtool prompt. Note that some commands provide an --nq option, which specifies that no confirmation message should be displayed after you execute the command. If you do not include the --nq option for these commands, then obtool prompts you for confirmation. You must enter one of the values shown in Table 1-3 at the confirmation prompt.

Table 1-3 Values for Confirmation Message

Value	Meaning
`y`	Perform the operation on the object named in the query.
`n`	Do not perform the operation on the object named in the query and proceed to the next selection (if any).
`q`	Do not perform the operation on the object named in the query and stop processing this command immediately. Note that objects for which you have already answered `y` have been affected.
`a`	Perform the operation on the object named in the query and on all objects that the command has not yet included in a query. Note that objects for which you have already answered `n` will not be affected.
`?`	Display brief help text and then redisplay the prompt.

In the prompt, the item in brackets ([...]) indicates the default if you do not reply to the prompt.

Input Redirection in Interactive Mode

In interactive mode, you can redirect input to a script containing multiple obtool commands. This technique is useful if you need to run the same series of obtool commands on a regular basis. The syntax is as follows, where pathname is the path name of a file containing obtool commands:

ob> < pathname

For example, you can create a file called mycommands.txt with the following content:

# begin mycommands.txt
lsdev --long
lshost --long
# end

You can redirect the obtool input to this script as follows:

ob> < /home/mycommands.txt

Exiting obtool

Use the exit command to exit obtool, as shown in the following example:

ob> exit

obtool Noninteractive Mode

To execute commands in obtool noninteractively, use the following syntax:

obtool  [ cl-option ]... command-name [ option ]... [ argument ]...

The following example executes the obtool lsdev command and then returns to the operating system prompt:

% obtool lsdev
library    lib1             in service
  drive 1  tape1            in service
library    lib2             in service
  drive 1  tape2            in service

Note:

If the escape character is set to the ampersand (&) character (see "escape"), and if you specify & as part of a file name when running obtool commands noninteractively, then enclose the file name within single quotes. For example:

obtool cd -h phred '/home/markb&patti'

Because the ampersand character is within single quotes, it is not interpreted and is considered part of the file name.

You can also redirect input to obtool when in noninteractive mode. For example, you can create a file called mycommands.txt with the following content:

# begin mycommands.txt
lsdev --long
lshost --long
# end

You can redirect the obtool input to this script as follows:

obtool < /home/mycommands.txt

You can also nest redirection files. For example, you can create a second command file called mycommands2.txt and then edit mycommands.txt as follows to redirect input from mycommands2.txt:

# begin mycommands.txt
lsdev --long
lshost --long
# redirect input to second command file
< /home/mycommands2.txt
# end

Note:

In the following sections, all examples of obtool commands are shown with a preceding ob> as if you were executing in interactive mode. If you are executing a single command, replace ob> with obtool.

obtool Administrative Domain Configuration

When you run installob and specify a host as the administrative server, Oracle Secure Backup implicitly initializes the administrative domain. Initializing the domain means assigning the host the role of administrative server within the domain.

In some circumstances, you may need to initialize a new domain or reinitialize an old domain. You can use the following syntax to establish the local host as the administrative server for a new Oracle Secure Backup administrative domain:

obtool --initnewdomain [--adminpassword/-A passwd] [--force] 
       [--nullpassword/-N] [--verbose/-v]

If the local host is already established as an administrative server, then specifying --force causes the host to reinitialize itself. The --force option is useful when you have forgotten your password.

obtool Version Number

To display program version number and exit, use the following syntax:

obtool --version/-V

obtool Online Help

Table 1-4 displays the online help options for the obtool utility.

Table 1-4 Online Help Options

Help topic	Command
A list of help topics	`help` topics
Help for a specific topic	`help` topic-name
Usage for a specific command	`help` command-name
Usage for all commands related to a topic	`help` topic-name usage
Single glossary term	`help` <term>
Glossary of all terms used for a topic	`help` topic-name glossary

For example, enter the following command to view help topics:

ob> help topics

Online help is available for the topics listed in Table 1-5.

Table 1-5 Command Topics for Oracle Secure Backup

Topic	Description
advanced	Advanced and seldom-used commands
backups	Data backup operations
backupwindow	Backup window definition
browser	File system browser
checkpoint	Checkpoint management
class	User class rights
daemon	Daemon (service) display and control
dataset	Dataset descriptions
device	Device configuration
fs	File system operations for NAS devices
host	Host configuration
invocation	`obtool` invocation options
job	Scheduler job management
library	Library and volume management operations
mediafamily	Media family configuration
miscellany	Miscellaneous commands
piece	Backup piece display
policy	Defaults and policies configuration
ssel	Database backup storage selector
restores	Data restore operations
schedule	Schedule configuration
section	Backup section database commands
snapshot	Snapshot management for NAS devices
summary	Summary report scheduling configuration
user	User configuration
variables	Variables that affect `obtool`'s operation

obtool Topics

For a list of commands on a particular topic, enter help followed by the topic name. For example, execute the following command to display help about the class commands:

ob> help class

Sample output appears below:

Class definition commands:
chclass             change the attributes of a user class
lsclass             list the names and attributes of one or more user classes
mkclass             define a user class
renclass            assign a new name to a user class
rmclass             remove a user class from the administrative domain

obtool Command Syntax

For the syntax of a particular command, enter help followed by the command name. For example, enter the following command to display help for the lssection command:

ob> help lssection

The command displays the following output:

Usage: lssection [--long | --short] [--noheader/-H] [--incomplete/-i]
                 [--oid/-o <oid-list>]...
                 [ { {--vid/-v <vid-list>} | {--void/-V <oid-list>} }
                 [--file/-f <filenumber-list>]...]

You can also display help for placeholders in the syntax. For example, you can display the help for the vid-list placeholder as follows:

ob> help <vid-list>

The command displays the following output:

<vid-list>          one or more volume IDs (<vid>s), each separated by a comma

obtool Glossary

For a glossary of terms for a topic, enter the keyword help, the topic name, and then the keyword glossary. For example, the following command displays the keyword glossary for the snapshot commands:

ob> help snapshot glossary

Sample output appears below:

<filesystem-name>   the logical or physical name of a file system that is
                    logically connected to a host
<hostname>          a name of a host assigned by the user via mkhost or renhost
<numberformat>      the format in which to display large numbers, one of:
                        friendly      displays large values in "KB", "MB", ...
                        precise       shows precise values (with commas)
                        plain         like precise, but eschews commas
                        (unspecified) uses "numberformat" variable or, if
                                      unset, "friendly"

The remaining sections describe the obtool commands.

obtool Command Categories

Chapter 2, "obtool Commands" organizes obtool commands alphabetically. Like the obtool online help, this section categorizes commands into the following categories:

Backup Commands
Backup Piece Commands
Backup Window Commands
Browser Commands
Checkpoint Commands
Class Commands
Daemon Commands
Database Backup Storage Selector Commands
Dataset Commands
Device Commands
File System Command
Host Commands
Job Commands
Library Commands
Media Family Commands
Miscellaneous Commands
Policy Commands
Preferred Network Interface Commands
Restore Commands
Schedule Commands
Section Commands
Snapshot Commands
Summary Commands
User Commands
Variable Commands

Backup Commands

Commands in this category enable you to create, display, and delete file system backups requests.

The obtool utility includes the following commands for file system backups:

Backup Piece Commands

Commands in this category enable you to list and remove Recovery Manager (RMAN) backup pieces. A backup piece is a physical file in an Oracle proprietary format. An RMAN backup piece is created on tape as a backup image.

The obtool utility includes the following backup piece commands:

Backup Window Commands

Commands in this category enables you to configure backup windows. A backup window defines the times during which scheduled backups will run. You can identify a single backup window that applies to all days of the week (a default backup window), or fine-tune backup windows based on specific days or dates.

Note:

If no backup windows are identified, then scheduled backups will not run. The default backup window is daily 00:00-24:00.

The obtool utility includes the following backup window commands:

Browser Commands

Commands in this category enable you to browse the Oracle Secure Backup catalog. Each time Oracle Secure Backup performs a scheduled or on-demand backup, it records the name and attributes of each file system object it backs up. It writes this data to a repository — an Oracle Secure Backup catalog — stored on the administrative server file system. Oracle Secure Backup maintains a discrete backup catalog for each client in your administrative domain.

When you browse a backup catalog, Oracle Secure Backup presents the data in the form of a file system tree as it appeared on the client from which the data was saved. For example, if you backed up the /home/myfile.f file located on myhost, the backup catalog for myhost represents the contents of the backup image as /home/myfile.f.

At the root of the backup catalog file system appears the super-directory, which contains all files and directories saved from the top-most file system level. The super-directory provides you with a starting point from which to access every top-level file system object stored in the backup catalog.

The obtool utility includes the following browser commands:

Checkpoint Commands

Commands in this category enable you to list and remove checkpoints. Checkpoints are position markers created periodically during restartable Network Attached Storage (NAS) backups to provide a location on the tape to which an interrupted backup can return and resume.

A backup is restartable if it meets the following conditions:

The backup client is a Network Appliance filer running Data ONTAP 6.4 or later.
The backup image is saved to a tape drive controlled by an NDMP server version 3 or later.
The restartablebackups operations policy is enabled.
The backup has reached a point from which it can be restarted.

At the beginning of each backup job, Oracle Secure Backup automatically determines whether the backup can be restarted from a mid-point. If so, Oracle Secure Backup periodically establishes a checkpoint that it can later use to restart the backup. When each new checkpoint is recorded, the previous checkpoint is discarded. You can control checkpoint behavior with the fullbackupcheckpointfrequency, incrbackupcheckpointfrequency, and maxcheckpointrestarts operations policies.

Note:

If you use the restartable backups feature, then ensure that the /tmp directory on the administrative server is on a partition that maintains at least 1 GB of free space.

The obtool utility includes the following checkpoint commands:

Class Commands

Commands in this category enable you to configure classes. A class defines a set of rights that are granted to a user. You can assign multiple users to a class, each of whom is a member of exactly one class. A class is similar to a UNIX group, but it defines a finer granularity of access rights tailored to the needs of Oracle Secure Backup.

Oracle Secure Backup automatically predefines a number of classes, which are described in Appendix B, "Classes and Rights". You can perform the same operations on these classes as on user-defined classes.

The obtool utility includes the following class commands:

Daemon Commands

Commands in this category enable you to configure Oracle Secure Backup daemons. A daemon is a process or service that runs in the background and performs a specified operation at predefined times or in response to certain events.

The obtool utility includes the following daemon commands:

Database Backup Storage Selector Commands

Commands in this category enable you to manage Oracle configuration data.

Oracle configuration data is stored in a database backup storage selector. Storage selectors are created, named, and modified by a user belonging to a class with the modify configuration right. As with other configuration objects such as hosts, devices, and users, storage selectors are stored on the administrative server.

Storage selectors give users fine-grained control over database backup operations. Oracle Secure Backup uses the information encapsulated in storage selectors when interacting with Recovery Manager (RMAN). As explained in Appendix E, "RMAN Media Management Parameters", you can override storage selectors by specifying media management parameters in RMAN.

The obtool utility includes the following Oracle configuration commands:

Dataset Commands

Commands in this category enable you to create and configure Oracle Secure Backup datasets. A dataset file is an editable file that describes which hosts and paths that Oracle Secure Backup should back up.

Oracle Secure Backup stores and manages dataset files on the administrative server file system. Like Windows and UNIX file systems, Oracle Secure Backup datasets are organized in a naming tree. You can optionally create dataset directories to help you organize your data definitions. You can nest directories 10 levels deep.

The samples subdirectory of the Oracle Secure Backup home contains sample dataset files. Before you begin to define datasets, you can view these dataset files to get an idea of how to define a strategy for constructing your own.

For more details about datasets, see Oracle Secure Backup Administrator's Guide.

The obtool utility includes the following dataset commands:

Device Commands

Commands in this category enable you to configure devices for use with Oracle Secure Backup. A device is a tape drive or tape library identified by a user-defined device name.

The obtool utility includes the following device commands:

File System Command

The lsfs command enables you to list file systems on an NDMP-accessed NAS device.

Host Commands

Commands in this category enable you to configure one or more hosts. A host is a machine that is accessible through TCP/IP in the Oracle Secure Backup administrative server network; a host is identified by a hostname paired with an IP address.

The obtool utility includes the following host commands:

Job Commands

Commands in this category enable you to manage jobs, which are backup or restore operations that you have defined with the backup or restore commands.

The obtool utility includes the following job commands:

Library Commands

Commands in this category enable you to manage the contents of a tape library. A library is a medium changer that accepts SCSI commands to move media between storage locations and tape drives.

Most library commands accept either the --library/-L or --drive/-D option, depending on the operation requested. These options interact in the following ways:

If a command requires a library, then you can specify either a library or a drive because the identity of a drive uniquely identifies a library.
If a command requires a drive, then you must specify a drive because a library name is sometimes insufficient to uniquely identify a drive.

If you specify neither a library nor a drive, then obtool uses the library and drive variables (see Appendix C, "obtool Variables").

The obtool utility includes the following library commands:

Media Family Commands

Commands in this category enable you to configure media families. A media family is a named classification of backup volumes that share the following characteristics:

Volume ID sequence
Expiration policy
Write-allowed time period, which is called the volume write window

Write windows and expiration policies give you control over tape recycling. The default for both settings is to allow tapes to be written to indefinitely and kept forever. Setting limits enables you to overwrite tapes automatically at predetermined intervals.

Oracle Secure Backup is installed with a default content-managed media family named RMAN-DEFAULT. If no media family specified in an RMAN job and no matching backup storage selector exists, then RMAN uses RMAN-DEFAULT. You cannot delete or rename this default media family, although you can change specified attributes with chmf.

The obtool utility includes the following media family commands:

Miscellaneous Commands

The obtool utility includes the following miscellaneous commands:

Policy Commands

Commands in this category enable you to create and manage policies. Defaults and policies are configuration data that control how Oracle Secure Backup operates within an administrative domain. You can use policies to tailor many characteristics of Oracle Secure Backup. Appendix A, "Defaults and Policies" contains a complete list of policies and policy classes.

Policies are grouped into policy classes. Each class contains policies that describe a particular area of Oracle Secure Backup operation. Use the lsp command display a list of classes and policies.

The obtool utility includes the following policy commands:

Preferred Network Interface Commands

Commands in this category enable you to configure a preferred network interface (PNI). A network can have multiple physical connections between a client and the server performing an operation on behalf of the client. For example, a pair of hosts can maintain both Ethernet and FDDI connections. The PNI commands enable you to specify which of the server's network interfaces should transmit data for each client.

The obtool utility includes the following preferred network interface commands:

Restore Commands

Commands in this category enable you to manage restore jobs.

The obtool utility includes the following restore commands:

Schedule Commands

Commands in this category enable you to configure a backup schedule to tell Oracle Secure Backup when to back up file system data. In the backup schedule you describe the following:

Triggers that indicate when the backups should occur. You an specify the days of the week, month, quarter, or year on which you want to the backup to occur and the time in each day that a backup should begin.
Name of each dataset file describing the data to back up. Oracle Secure Backup uses the host and path names, exclusion rules, and other information from each dataset file.
Name of a media family to use. Oracle Secure Backup uses media families to assign selected characteristics to the backup.

The obtool utility includes the following schedule commands:

Section Commands

Commands in this category enable you to manage backup sections. When Oracle Secure Backup performs a backup (either file system or database), it creates a backup image on one or more tapes. A backup section is the portion of a backup image that occupies one physical volume. A backup image that fits on a single volume consists of one backup section.

The obtool utility includes the following schedule commands:

Snapshot Commands

Commands in this category enable you to manage snapshots. A snapshot is a consistent copy of a volume or a file system. Snapshots are supported only for Network Appliance filers running Data ONTAP 6.4 or later.

The obtool utility includes the following snapshot commands:

Summary Commands

Commands in this category enable you to configure job summaries. A job summary is a generated text file report that indicates whether backup and restore operations were successful. A job summary schedule is the user-defined schedule according to which Oracle Secure Backup generates job summaries.

Oracle Secure Backup can generate and email job summaries detailing the status of backup and restore jobs. You can configure Oracle Secure Backup to generate one or more of these summaries. For each summary, you can choose the following:

The schedule according to which Oracle Secure Backup produces the summary
The start of the time period the summary spans (the end time is always the summary generation time)
The users to whom the summary is emailed

Each job summary contains the following sections:

Pending jobs
Ready and running jobs
Successful jobs
Unsuccessful jobs

The obtool utility includes the following job summary commands:

User Commands

Commands in this category enable you to configure user accounts for logging into and using Oracle Secure Backup. To configure users, you must be belong to a class with the modify administrative domain's configuration right.

The obtool utility includes the following user commands:

Variable Commands

Commands in this category enable you to maintain a number of internal variables that control Oracle Secure Backup operation. See Appendix C, "obtool Variables" for a complete list of obtool variables. You can also access this list in online help by executing the following command:

ob> help var

The obtool utility includes the following variable commands: