Go to main content
5/17

# 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 10.3
    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 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 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 10.3.0.0
    login: admin
    Password:
    ob> quit
    [root@osblin1 ~]# obtool
    ob> logout
    [root@osblin1 ~]# obtool
    Oracle Secure Backup 10.3.0.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 10.3.0.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 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
fs | File-system operations for Network Attached Storage (NAS) devices
host | Host configuration
invocation | obtool invocation options
job | Scheduler job management
library | Tape 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 Network Attached Storage (NAS) devices
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

Chapter 2, "obtool Commands" organizes obtool commands alphabetically. 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

- Duplication on Demand Commands

- Duplication Window 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

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

- 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

- 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 Appendix 7, "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

### 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 Appendix C, "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

- 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

- 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 Appendix 4, "obtool Variables").

The obtool utility includes the following tape library commands:

- 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

- 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. Appendix 6, "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.

The obtool utility includes the following PNI commands:

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

- 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

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