1 About obtool

This chapter explains how to use the obtool command-line interface. It contains the following topics:

• obtool Invocation

• obtool Online Help

• obtool Command Categories

• obtool Lexical Conventions

• obtool Exit Codes

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

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 an Oracle Secure Backup user identity, then obtool prompts you for a user name and password, as shown in the following example:

% obtool
Oracle Secure Backup 12.2.0.1.0
login:

Oracle Secure Backup creates the admin user automatically at installation and prompts you for the password.

Note:

The practice of supplying a password in clear text on a command line or in a command script is not recommended by Oracle. It is a security vulnerability. The recommended procedure is to have the Oracle Secure Backup user be prompted for the password.

See Also:

• "User Commands" for information on setting up Oracle Secure Backup user identities

• "Policy Commands" for more information about the security/loginduration policy

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 Oracle Secure Backup user is stored in a separate file. The lifetime of the login token is controlled by the loginduration security policy.

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:

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

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

3. 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 Recovery Manager (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	host name	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.

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
--longerrors/-E	Shows error messages in long form. See also "errors".
--norc/-n	Does not run commands from .obtoolrc. You can put a sequence of obtool commands in this file for obtool to run 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 obtool Commands: addbw to lsvol at the obtool prompt. Note that some commands provide an --nq option, which specifies that no confirmation message should be displayed after you run the command. If you do not include the --nq option for these commands, then obtool prompts you for confirmation. You must enter a value from 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 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 answered n are not 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 must 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 pass a command to obtool on the command line, use the following syntax:

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

The following example runs 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

Escaping Special Characters in obtool Command Line

As with any command line, it might be necessary to quote characters that are significant to the command line interpreter or shell from which obtool is invoked. For example:

• When running obtool commands from the command line that include a semicolon, quotes might be required to prevent the semicolon from being interpreted by the shell. See "Running Multiple obtool Commands Non-Interactively" for details on the use of the semicolon in command lines.

• If the obtool 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.

Running Multiple obtool Commands Non-Interactively

To run multiple obtool commands in non-interactive mode, separate the commands with a semicolon. When used in this manner, the output of each obtool command is preceded by a line of text that displays the command processed. The following example illustrates the use of two commands in a Linux bash shell:

oblin1$ obtool lsmf -s ';' lsh -s
Output of command : lsmf -s
RMAN-DEFAULT

Output of command : lsh -s
brhost2
brhost3
stacb40

Each command returns Output of command : and the command name even if the command does not give any other output.

Redirecting obtool Commands From an Input File

You can 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

Exiting obtool

You can end an obtool session by using either the exit or quit commands, or the logout command.

The exit command ends the obtool session, but a login token preserves the user's credentials, so that the next time you start obtool you are not prompted for a user name or password. The quit command is a synonym for exit.

Logging Out of obtool

The logout command destroys the login token, so that the user is prompted for credentials during the next obtool session.

For example:

[root@osblin1 ~]# obtool
Oracle Secure Backup 12.2.0.1.0
login: admin
Password:
ob> quit
[root@osblin1 ~]# obtool
ob> logout
[root@osblin1 ~]# obtool
Oracle Secure Backup 12.2.0.1.0
login:

You can also use the logout command in obtool when invoking it in non-interactive mode. For example:

[root@osblin1 ~]# obtool -logout
[root@osblin1 ~]# obtool
Oracle Secure Backup 12.2.0.1.0
login:

Starting obtool as a Specific User: obtool -u

You can force obtool to use different credentials when starting, destroying any existing login token. To do so, use the -u option with obtool, specifying the name of the Oracle Secure Backup user for the session. For example:

[root@osblin1 ~]# obtool -u admin
Password:
ob> 

obtool Domain Authentication

You can force obtool to use request credentials, regardless of whether there is an existing login token. To do so, use the following syntax:

obtool --authenticate

obtool Version Number

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

obtool --version/-V

obtool Date and Time Information

If a date reported by an obtool command is more than six months earlier or more than two months in the future, then it is reported in a yyyy/mm/dd format. If a date is less than six months earlier or less than two months in the future, then it is reported in a mm/dd.hh:mm format.

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
duplication	Volume duplication operations
fs	File-system operations for Network Attached Storage (NAS) devices
host	Host configuration
images	Backup image and backup image instance management
invocation	obtool invocation options
job	Scheduler job management
library	Tape library and volume management operations
location	Location configuration
mediafamily	Media family configuration
miscellany	Miscellaneous commands
piece	Backup piece display
policy	Defaults and policies configuration
ssel	Database backup storage selector
reports	Media management reports
restores	Data restore operations
rotation	Rotation policy configuration
schedule	Schedule configuration
section	Backup section database commands
snapshot	Snapshot management for Network Attached Storage (NAS) devices
staging	Staging of disk backup image instances
summary	Summary report scheduling configuration
user	User configuration
variables	Variables that affect obtool operations

obtool Topics

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

ob> help class

The command displays the following output:

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 (vids), 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

The command displays the following output:

<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

obtool Commands: addbw to lsvol organizes obtool commands alphabetically. This section categorizes commands into the following categories:

• Backup Commands

• Backup Image Commands

• Backup Image Instance Management

• Backup Piece Commands

• Backup Window Commands

• Browser Commands

• Checkpoint Commands

• Class Commands

• Cloud Authentication and Configuration Commands

• Daemon Commands

• Database Backup Storage Selector Commands

• Dataset Commands

• Device Commands

• Duplication on Demand Commands

• Duplication Window Commands

• File-System Command

• Host Commands

• Job Commands

• Library Commands

• Location Commands

• Media Family Commands

• Miscellaneous Commands

• Policy Commands

• Preferred Network Interface Commands

• Reports Commands

• Restore Commands

• Rotation Policy Commands

• Schedule Commands

• Section Commands

• Snapshot Commands

• Staging Commands

• Summary Commands

• User Commands

• Volume Rotation Commands

• Volume Duplication Commands

Backup Commands

Commands in this category enable you to create, display, and delete a file-system backup request.

The obtool utility includes the following commands for file-system backup:

• backup

• lsbackup

• rmbackup

Backup Image Commands

Commands in this category enable you to list and manage backup images.

The obtool utility includes the following commands for backup images:

• lsbkup

• renbkup

Backup Image Instance Management

Commands in this category enable you to create, display, remove, and move backup image instances. A backup image instance is a complete representation of a backup image that exists on a storage location.

The obtool utility includes the following commands for managing backup image instances:

• lsinstance

• chinstance

• cpinstance

• rminstance

• validatechecksum

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.

These commands enable advanced users to correct any synchronization errors between RMAN backups and Oracle Secure Backup backups. The obtool utility includes the following backup piece commands:

• lspiece

• rmpiece

Backup Window Commands

Commands in this category enables you to configure backup windows. A backup window defines the times during which a scheduled backup runs. 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 do not run. The default backup window is daily 00:00-24:00.

The obtool utility includes the following backup window commands:

• addbw

• chkbw

• lsbw

• rmbw

• setbw

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, then 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:

• cd

• find

• ls

• lsbu

• pwd

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 Network Data Management Protocol (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 it can be restarted, then Oracle Secure Backup periodically establishes a checkpoint that it can later use to restart the backup. When each additional 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:

• lscheckpoint

• rmcheckpoint

Class Commands

Commands in this category enable you to configure classes. A class defines a set of rights that are granted to an Oracle Secure Backup 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 several classes, which are described in 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:

• chclass

• lsclass

• mkclass

• renclass

• rmclass

Cloud Authentication and Configuration Commands

Commands in this category enable you to configure,and modify authentication objects that contain credentials used to perform backups to Oracle Cloud.

The obtool utility includes the following cloud authentication and configuration commands:

• mkauth
• chauth

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:

• ctldaemon

• lsdaemon

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 an Oracle Secure Backup user belonging to a class with the modify configuration right. As with other configuration objects such as hosts, tape devices, and users, storage selectors are stored on the administrative server.

Storage selectors give Oracle Secure Backup 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 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:

• chssel

• lsssel

• mkssel

• renssel

• rmssel

Dataset Commands

Commands in this category enable you to create and configure an Oracle Secure Backup dataset. 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:

• catds

• cdds

• chkds

• edds

• lsds

• mkds

• pwdds

• rends

• rmds

Device Commands

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

The obtool utility includes the following device commands:

• borrowdev

• chdev

• discoverdev

• dumpdev

• lsdev

• managedev

• mkdev

• mountdev

• pingdev

• rendev

• resdev

• returndev

• rmdev

• unmountdev

• unresdev

• vfylibs

Duplication on Demand Commands

Commands in this category enable you to duplicate volumes on demand.

The obtool utility includes the following duplication on demand commands:

• dupvol

Duplication Window Commands

Commands in this category enable you to manage duplication windows, which are time and day ranges.

The obtool utility includes the following duplication window commands:

• adddw

• chkdw

• lsdw

• rmdw

• setdw

File-System Command

The lsfs command enables you to list file systems on a Network Attached Storage (NAS) device accessed through Network Data Management Protocol (NDMP).

Host Commands

Commands in this category enable you to configure one or more hosts. A host is a computer that is accessible through TCP/IP (Transmission Control Protocol/Internet Protocol) in the Oracle Secure Backup administrative server network; a host is identified by a host name paired with an IP address.

The obtool utility includes the following host commands:

• chhost

• lshost

• mkhost

• pinghost

• renhost

• revhost

• rmhost

• updatehost

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:

• canceljob

• catxcr

• lsjob

• rmjob

• rpyjob

• runjob

Library Commands

Commands in this category enable you to manage the contents of a tape library. A tape library is a medium changer that accepts Small Computer System Interface (SCSI) commands to move media between a storage location and a tape drive.

Most tape 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 tape library, then you can specify either a tape library or a tape drive because the identity of a tape drive uniquely identifies a tape library.

• If a command requires a tape drive, then you must specify a tape drive because a tape library name is sometimes insufficient to uniquely identify a tape drive.

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

The obtool utility includes the following tape library commands:

• catalog

• clean

• closedoor

• exportvol

• extractvol

• identifyvol

• importvol

• insertvol

• inventory

• labelvol

• loadvol

• lsvol

• movevol

• opendoor

• reusevol

• unlabelvol

• unloadvol

Location Commands

Commands in this category enable you to manage locations.

The obtool utility includes the following location commands:

• chloc

• lsloc

• mkloc

• renloc

• rmloc

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 a Recovery Manager (RMAN) job and if 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:

• chmf

• lsmf

• mkmf

• renmf

• rmmf

Miscellaneous Commands

The obtool utility includes the following miscellaneous commands:

• exit

• id

• logout

• set

• unset

• show

• quit

Policy Commands

Commands in this category enable you to create and manage policies. Oracle Secure Backup 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. 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:

• addp

• cdp

• lsp

• pwdp

• resetp

• rmp

• setp

Preferred Network Interface Commands

Commands in this category enable you to configure a PNI (Preferred Network Interface). 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 Fiber Distributed Data Interface (FDDI) connections. The PNI commands enable you to specify which of the server's network interfaces should transmit data for each client.

Network load balancing ensures optimal utilization of network interfaces by distributing the data transfer load acorss all available network interfaces. When a PNI is configured, then load balancing is disabled and PNI takes precedence.

See Also:

Oracle Secure Backup Installation and Configuration Guide for more information about network load balancing

The obtool utility includes the following PNI commands:

• chpni

• lspni

• mkpni

• rmpni

Reports Commands

Commands in this category enable you to display and list media management reports.

The obtool utility includes the following reports commands:

• catrpt

• lsrpt

Restore Commands

Commands in this category enable you to manage restore jobs.

The obtool utility includes the following restore commands:

• lsrestore

• restore

• rmrestore

Rotation Policy Commands

Commands in this category enable you to manage rotation policies

The obtool utility includes the following rotation policy commands:

• chrot

• lsrot

• mkrot

• renrot

• rmrot

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:

• chsched

• lssched

• mksched

• rensched

• rmsched

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 instance that occupies one physical volume. A backup image instance that fits on a single volume consists of one backup section.

The obtool utility includes the following schedule commands:

• lssection

• rmsection

• unrmsection

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 a Network Appliance filer running Data ONTAP 6.4 or later.

The obtool utility includes the following snapshot commands:

• lssnap

• mksnap

• rensnap

• rmsnap

Staging Commands

The staging commands allow you to create stage rules that control which backup images are copied, and when they are copied. Stage rules can also be used to control the minimum time a backup image is guaranteed to remain on a stage device.

The obtool utility includes the following staging commands:

• chstage

• lsstage

• mkstage

• renstage

• rmstage

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 Oracle Secure Backup user 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:

• chsum

• lssum

• mksum

• rensum

• rmsum

User Commands

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

The obtool utility includes the following user commands:

• chuser

• lsuser

• mkuser

• renuser

• rmuser

Volume Rotation Commands

Commands in this category enable you to control volume rotation as part of media lifecycle management.

The obtool utility includes the following volume rotation commands:

• chvol

• recallvol

• releasevol

• rmvol

• vault

Volume Duplication Commands

Commands in this category enable you to control volume duplication as part of media lifecycle management.

The obtool utility includes the following volume duplication commands:

• chdup

• lsdup

• mkdup

• rendup

• rmdup

obtool Lexical Conventions

This section describes the conventions used in the obtool command syntax diagrams and code examples of this manual. It describes:

• Conventions in Syntax Diagrams

• Conventions in Code Examples

Conventions in Syntax Diagrams

Syntax diagrams indicate legal syntax for Oracle Secure Backup commands. Syntax diagrams are displayed in a monospace (fixed-width) font and are preceded with a heading as shown in the following example:

clean::=

clean [ --drive/-D drivename ] [ --force/-f ] [ --use/-u element-spec ]

The following table describes typographic conventions used in syntax diagrams.

Convention	Meaning	Example
[ ]	Brackets enclose optional items from which you can choose one or none. A space is included after a beginning bracket and before a closing bracket for improved readability. Note that a comma-delimited list of tokens following a command option cannot be separated by spaces unless the entire string is enclosed within quotes.	cancel•job [ --quiet/-q | --verbose/-v ] [ --tag/-t tag[,tag]... ]
{ }	Braces are required items for which you must select one of the enclosed values. Each value is separated by a vertical bar (|). A space is included after a beginning brace and before a closing brace for improved readability. Note that a comma-delimited list of tokens following a command option cannot be separated by spaces unless the entire string is enclosed within quotes.	disc•overdev { --host/-h hostname }... { * | dbname[,dbname]... }
|	A vertical bar represents a choice of two or more options within brackets or braces. Enter exactly one of the options.	ls [ --long/-l | --short/-s ]
--text/-text	A slash separating two flags, each preceded by one or two dashes, indicates an either-or choice between semantically equivalent options. For example, --in/-i represents a choice between the --in and -i flags.	[ --level/-l backup-level ]
...	Horizontal ellipsis points indicate that the preceding syntax item can be repeated. Note that spaces are not permitted between comma-delimited items.	sho•w [ variable-name ]...
•	A bullet within command syntax indicates that the characters between the bullet and the terminating whitespace can be omitted for convenience.	inv•entory
Italics	Italicized text indicates placeholders or variables for which you must supply particular values.	chkds dataset-file-name ...

Conventions in Code Examples

Code examples illustrate Oracle Secure Backup command-line statements. They are displayed in a monospace (fixed-width) font and separated from normal text as shown in this example:

ob> backup --dataset homedir.ds --go

The following table describes typographic conventions used in examples.

Convention	Meaning	Example
courier	Courier typeface indicates command line entries, system output display, options and arguments that you enter, executables, filenames, and directory names.	ob> cdds /mydatasets
Bold	Bold typeface distinguishes user input from command output in examples in cases where the two could be confused.	ob> mkds --nq --input mydataset.ds Input the new dataset contents. Terminate with an EOF or a line containing just a dot ("."). include host brhost2 include path /home .
. . .	Vertical ellipsis points in an example mean that information not directly related to the example has been omitted.	ob> lsvol --library lib1 Inventory of library lib1: . . . in dte: vacant

obtool Exit Codes

When obtool encounters an error, it reports an exit code with a brief description. The exit code file obexit.h is in /usr/local/oracle/backup/samples. It lists and describes all obtool exit codes. You might find it useful to anticipate errors and branch accordingly when building obtool scripts.