This chapter explains how to use the obtool command-line interface. The following topics are covered:
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.
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.
See Also:
"User Commands" for information on setting up user identities
"Policy Commands" for more information about the security/loginduration policy
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.
To use obtool in interactive mode, enter obtool at the operating system command line once.
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.
| Option | Meaning |
|---|---|
|
|
Shows error messages in long form. See also "errors". |
|
|
Does not execute commands from By default, |
|
|
Displays extra informational messages. See also "verbose". |
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 |
|---|---|
|
|
Perform the operation on the object named in the query. |
|
|
Do not perform the operation on the object named in the query and proceed to the next selection (if any). |
|
|
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 |
|
|
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 |
|
|
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.
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
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 ofobtool 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.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.
Table 1-4 displays the online help options for the obtool utility.
| Help topic | Command |
|---|---|
|
A list of help topics |
|
|
Help for a specific topic |
|
|
Usage for a specific command |
|
|
Usage for all commands related to a topic |
|
|
Single glossary term |
|
|
Glossary of all terms used for a topic |
|
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 |
|
|
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 |
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
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
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.
Chapter 2, "obtool Commands" organizes obtool commands alphabetically. Like the obtool online help, this section categorizes commands into the following categories:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
The lsfs command enables you to list file systems on an NDMP-accessed NAS device.
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:
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:
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:
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:
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:
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:
Commands in this category enable you to manage restore jobs.
The obtool utility includes the following restore 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:
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:
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:
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:
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:
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: