1. Maintenance Guide
  2. Using the DBMCLI Utility

9 Using the DBMCLI Utility

The Oracle Exadata Database Machine Command-Line Interface (DBMCLI) utility is used to manage database servers and provides many of the features that are provided with SQL*Plus, including the use of script files.

9.1 Overview of the DBMCLI Utility

The DBMCLI utility is the command-line administration tool for configuring database servers, and managing objects in the server environment.

DBMCLI runs on each server to enable you to configure an individual database server. You use DBMCLI to start and stop the server, to manage server configuration information, and to enable or disable servers. The command-line utility is already installed when Oracle Exadata is shipped.

Parent topic: Using the DBMCLI Utility

9.1.1 Starting DBMCLI

You can start DBMCLI from the operating system command line on the database server that you want to manage or remotely from a network-attached client using Secure Shell (SSH). The command-line syntax is as follows:

dbmcli [-n] [-m] [-xml] [-x] [-e command]

The following table lists the options that can be used with the DBMCLI command:

Option Description

-n

Runs the DBMCLI utility in non-interactive mode. This option suppresses the command prompt and disables the command-line editing features.

-m

Runs DBMCLI in monitor (read-only) mode.

-xml

Causes command output to be displayed in XML format.

-x

Suppresses the banner.

-e command

Runs the specified DBMCLI command. For example:

$ dbmcli -e list dbserver detail
$ dbmcli -e "list dbserver attributes name where name like '.*dbm01'"

DBMCLI exits after running the command.

DBMCLI uses the database server operating system authentication. DBMCLI does not have a login parameter or a connect command. The directory from which DBMCLI is invoked is the default directory for unqualified file access in DBMCLI SPOOL and START commands.

Parent topic: Overview of the DBMCLI Utility

9.1.2 Understanding Command Syntax and Options for DBMCLI

This topic describes the syntax and command options for DBMCLI.

DBMCLI syntax is as follows: 

{admin-command | object-command object} [options] ;

In the preceding syntax, the following arguments are used:

  • admin-command is an administrative action.

  • object-command is an action performed on an object.

  • object is an object or target on which a command performs an action.

  • options extend the use of a command combination to include additional parameters for the command.

When using the DBMCLI utility, the following rules apply:

  • Commands, objects, and options are not case-sensitive except where explicitly stated, such as in string patterns used in filtering strings with the LIKE operator.

  • Use single quotation marks or double quotation marks around the name of an object that includes spaces or punctuation. The use of quotation marks should match. For example, "this is incorrect' is incorrect because the first mark is double quotation marks, and the second is a single quotation mark.

  • The current, local cell is the cell to which all DBMCLI commands apply.

  • A semicolon (;) is optional at the end of a DBMCLI command.

  • A hyphen (-) is used at the end of a line to continue a long command onto the next line. If you are using hyphens in names or to denote negative values, it must be immediately followed by an alphanumerical value.

Parent topic: Overview of the DBMCLI Utility

9.1.3 Reserved Words

The following are DBMCLI reserved words: 

ALERTDEFINITION
ALERTHISTORY
ALL
ALTER
BMC
CONFIGUREBMC
CREATE
DESCRIBE
DETAIL
DROP
FORCE
LED
LIST
LUN
MAIL
MEMORY
METRICDEFINITION
METRICCURRENT
METRICHISTORY
MS
NULL
OFF
ON
PHYSICALDISK
RESTART
RS
SHUTDOWN
SNMP
STARTUP
THRESHOLD
VALIDATE

If these keywords are used as values in commands, then they must be enclosed in quotation marks.

Parent topic: Overview of the DBMCLI Utility

9.1.4 DBMCLI Command-Line Editing

The DBMCLI utility supports command-line history and editing, similar to BSD editline and GNU readline functionality. Most of the command editing features of DBMCLI are similar to modern shells, such as bash and tcsh.

Parent topic: Overview of the DBMCLI Utility

9.1.5 DBMCLI Input and Output Options

The database command-line utility reads commands from standard input and writes output to standard output. You can use the host operating system options for redirecting input and output to compose and process command scripts. For example, you can perform the following redirection: 

$ dbmcli < command-script-in  > results-out

In the preceding example, the output from DBMCLI commands in the command-script-in file are written to the results-out file.

Parent topic: Overview of the DBMCLI Utility

9.1.6 Comments in DBMCLI Scripts

You can add single-line comments to DBMCLI scripts using several formats. You can begin the comment line with REMARK,REM or -- (two hyphens).

For example, the following are valid syntax for comments:

REMARK This is a comment
REM This is a comment
-- This is a comment

Parent topic: Overview of the DBMCLI Utility

9.1.7 Line Continuation in DBMCLI Commands

To continue a long command on to the next line, insert a hyphen (-) at the end of the line. Then, press Enter, and continue typing the command.

For example:

DBMCLI> LIST dbserver WHERE name LIKE '*.dbm04' -
        attributes name, status, comment

Parent topic: Overview of the DBMCLI Utility

9.2 About DBMCLI Administration Commands

DBMCLI administrative commands do not act directly on objects.

DBMCLI uses the following administration commands:

Note:

The dbmadmin user should be used to run all services on the database server. The dbmmonitor user is for monitoring purposes. The dbmmonitor user can run the following commands:

  • DESCRIBE

  • EXIT

  • HELP

  • LIST

  • REMARK

  • SET

  • START

Parent topic: Using the DBMCLI Utility

9.3 About DBMCLI Object Commands

DBMCLI has object commands, object types, and object attributes.

The following DBMCLI commands operate on Oracle Database objects:

Related Topics

Parent topic: Using the DBMCLI Utility

9.4 About DBMCLI Object Types

The following Oracle Exadata System Software object types can be used with DBMCLI object commands:

  • ALERTDEFINITION — An alert definition provides a definition for every alert that can be produced on the database server. Alerts are defined on metrics and other sources of alerts.

  • ALERTHISTORY — An alert history provides a list of alerts that have occurred on the database server.

  • DBSERVER — The current or local database server.

  • DBSERVER — A diagpack represents a compressed file under $LOG_HOME and contains log files and trace files.

  • IBPORT — The InfiniBand Network Fabric ports for the database server.

    Note:

    This command does not work on Oracle Exadata servers with RoCE Network Fabric.

  • LUN — Logical unit number (LUN) is the address for a RAID set of physical disk devices. LUNs are automatically discovered when the server is started. They are assigned to the corresponding disk when the disk is first created or when disks are discovered after the system is restarted. LUNs that are not yet assigned to a disk have a NULL value.

  • METRICCURRENT — A current metric describes a set of observations on the current value of an individual metric.

  • METRICDEFINITION — A metric definition describes the configuration of a metric,

  • METRICHISTORY — A metric history describes a collection of past individual observations of all metric values.

  • PHYSICALDISK — A disk is called a physical disk on the server.

  • PRIVILEGE — A right or permission assigned to a role.

  • ROLE — A named group of related privileges.

  • SOFTWAREHISTORY — A software history is a list of final states for past software updates

  • SOFTWAREUPDATE — An object that contains the software location and time parameters for scheduling software updates.

  • THRESHOLD — A threshold describes the rules for generating stateful alerts based on a specific metric. The rules include boundary (threshold) values and how long the metric values can violate these boundaries before an alert is generated.

  • USER — An account that can manage the compute nodes using DBMCLI.

Not all possible command-object combinations are valid. For valid command-object combinations, review the syntax for the specific object command.

Parent topic: Using the DBMCLI Utility

9.5 DBMCLI Object Attributes

Each DBMCLI object has a set of attributes that are assigned when the object is created or altered. Attribute filters and lists are used to specify which attributes and objects are displayed in the output of the LIST command.

All attributes can be displayed, but only some can be modified directly by the user. To display a list of attributes and determine which ones can be modified, use the DESCRIBE command.

Related Topics

Parent topic: Using the DBMCLI Utility

9.5.1 Restrictions on Values of Common Attributes

Review the following restrictions for the values of attributes used by multiple DBMCLI objects.

  • The value of the name attribute must be less than 256 characters and composed only of the following ASCII characters:

    • Lowercase alphabetic characters (a to z)
    • Uppercase alphabetic characters (A to Z)
    • Numbers (0 to 9)
    • Underscore (_)
    • Hyphen (-)

      Note:

      On Oracle Exadata System Software release 19.2.0, or earlier, you must enclose the string in double quotes. For example: "hyphenated-string"

  • The value of the comment attribute must be less than 256 characters.

See the syntax of each DBMCLI command for any additional restrictions on attribute values.

Parent topic: DBMCLI Object Attributes

9.5.2 Attribute Lists in LIST Command

You can specify which attributes to display for the LIST command with the following optional clause: 

ATTRIBUTES { ALL | attribute1 [, attribute2] ... }

ALL displays all possible object attributes for the LIST object combination.

Parent topic: DBMCLI Object Attributes

9.5.3 Attribute Filters in LIST and ALTER Commands

You can use the attribute_filters clause to specify the objects to display in LIST commands. Some ALTER commands also support the attribute_filters clause.

This syntax of the attribute_filters clause is: 

WHERE attribute_filter1 [ AND attribute_filter2 ... ]

Each attribute_filterN has the following syntax: 

attribute [ NOT | ! ] operator comparison_value

The attribute placeholder represents the name of the attribute to use for filtering. The supported types of operator are listed in the following table. These operators can be combined with NOT or !.

Table 9-1 Supported Operators in Attribute Filters

Operator Description

=

Tests for equality between string, status, or numeric attributes. For example:

status NOT = normal

>

Tests for values greater than the numeric attributes. For example:

size > 139920M

<

Tests for values less than the numeric attributes. For example:

freeSpace !< 100M

LIKE

Tests for a regular expression match with a string attribute using case-sensitive matching. For example:

LIKE 'GD_IO_RQ.*'

When used with the supported operators, comparison_value is one of the following data types:

  • Numeric
  • Literal: Value such as active or normal
  • Datetime: Time value supported only for ALERTHISTORY
  • String: Value delimited by single quotation marks ('') or double quotation marks (" ")
  • NULL: Unassigned strings or empty lists

Parent topic: DBMCLI Object Attributes

9.6 Monitoring Database Server with Metrics

You can monitor a database server by viewing its metrics.

Metrics are of the following type:

  • Cumulative: Statistics since the metric was created.
  • Instantaneous: Values at the time the metric is collected.
  • Rate: Computed value for metric by averaging statistics over a period of time.
  • About Metrics
    Exadata metrics are recorded observations of important properties or values relating to the Exadata system software.
  • Displaying Metrics
    You can use the DBMCLI LIST command to display and monitor metrics for database objects.
  • Database Server Metrics
    Database server metrics provide information about the server, such as CPU utilization, memory or network interconnections.
  • Real-Time Insight
    You can use the Real-Time Insight feature to enable real-time monitoring of your Exadata systems.
  • Using Real-Time Insight
    You can use the Real-Time Insight feature to enable real-time monitoring of your Exadata systems using an external metric collection platform.

Parent topic: Using the DBMCLI Utility

9.6.1 About Metrics

Exadata metrics are recorded observations of important properties or values relating to the Exadata system software.

Exadata metrics contain detailed statistics for most Exadata components.

Metrics are of the following types:

  • Cumulative metrics are statistics that accumulate over time since the metric was created or the server was restarted.

  • Instantaneous metrics contain the current value at the time of the metric observation.

  • Rate metrics are computed statistics where the value is observed over time.

By default, metric collections occur at 1-minute intervals. However, commencing with Oracle Exadata System Software 22.1.0, you can optionally configure fine-grained metrics. To enable fine-grained metrics, you must specify a collection interval between 1 and 60 seconds. You can also choose the metrics to include in the fine-grained collection.

Fine-grained metric collection is the foundation for real-time metric streaming. Consequently, fine-grained metrics are only recorded in memory to support streaming to an external collection. Regular (non-fine-grained) metrics are initially recorded in memory and later written to a disk-based repository. By default, seven days of metrics history is maintained for regular metrics.

Parent topic: Monitoring Database Server with Metrics

9.6.2 Displaying Metrics

You can use the DBMCLI LIST command to display and monitor metrics for database objects. You can display metric definitions, current metrics, and metric history using the LIST command.

Parent topic: Monitoring Database Server with Metrics

9.6.2.1 Displaying Specific Attributes for Metrics

Use the ATTRIBUTES keyword to list the specific attributes you want to view in the output.

This example shows the LIST METRICHISTORY command with the name, metrictype, and alertState attributes specified. The output is limited to a one hour time period. A portion of the output is shown in following the command. 

LIST METRICHISTORY ATTRIBUTES name, metrictype, alertState -
WHERE collectionTime > '2019-07-12T13:00:00-05:00' -
AND collectionTime < '2019-07-12T14:00:00-05:00'
         DS_TEMP                 Instantaneous   normal
         DS_FANS                 Instantaneous   normal
         DS_BBU_CHARGE           Instantaneous   normal
         DS_BBU_TEMP             Instantaneous   normal
         DS_CPUT                 Instantaneous   normal
         DS_CPUT_MS              Instantaneous   normal
         DS_FSUT                 Instantaneous   normal
         DS_FSUT                 Instantaneous   normal
         DS_FSUT                 Instantaneous   normal
         DS_MEMUT                Instantaneous   normal
         DS_MEMUT_MS             Instantaneous   normal
         DS_RUNQ                 Instantaneous   normal
         DS_SWAP_IN_BY_SEC       Instantaneous   normal
         DS_SWAP_OUT_BY_SEC      Instantaneous   normal
         DS_SWAP_USAGE           Instantaneous   normal
         DS_VIRTMEM_MS           Instantaneous   normal
         N_HCA_MB_RCV_SEC        Rate            normal
         N_HCA_MB_TRANS_SEC      Rate            normal
         N_IB_MB_RCV_SEC         Rate            normal
         N_IB_MB_RCV_SEC         Rate            normal
         N_IB_MB_RCV_SEC         Rate            normal
 ...

Parent topic: Displaying Metrics

9.6.2.2 Displaying Metric Definitions

Use the LIST METRICDEFINITION command to display the metric definitions for a database server.

A metric definition listing shows the configuration of a metric. Example 9-1 shows how to display attributes for the METRICDEFINITION object.

Example 9-1 Displaying Metric Definitions 

DBMCLI> LIST METRICDEFINITION DS_CPUT DETAIL

DBMCLI> LIST METRICDEFINITION WHERE name LIKE 'DS_SWAP_*' -
         ATTRIBUTES name, metricType, description
9.6.2.3 Displaying Current Metrics

Use the LIST METRICCURRENT command to display the current metric values for a database server.

A current metric listing shows a set of observations on the current value of an individual metric. Example 9-2 shows how to display attributes for the METRICCURRENT object.

Example 9-2 Displaying Current Metric Values

DBMCLI> LIST METRICCURRENT DS_FANS DETAIL


DBMCLI> LIST METRICCURRENT WHERE objectType = 'DBSERVER' AND                 - 
         metricValue != 0 ATTRIBUTES name, metricObjectName,                  -
         metricValue, collectionTime
9.6.2.4 Displaying Metric History

Use the LIST METRICHISTORY command to display the metric history for a database server.

A metric history listing shows a collection of past individual observations of all metric values. Example 9-3 shows how to display attributes for the METRICHISTORY object.

The retention period for most metric history files is specified by the metricHistoryDays attribute. The default retention period is 7 days. You can modify this setting with the DBMCLI ALTER DBSERVER command.

In addition to the metrics governed by the metricHistoryDays attribute, a subset of key metric observations are retained for up to one year. In all cases, historical metric observations are purged automatically if the server detects a storage space shortage.

Example 9-3 Displaying Metric History Values

DBMCLI> LIST METRICHISTORY DS_TEMP WHERE alertState='critical' DETAIL

DBMCLI> LIST METRICHISTORY WHERE objectType = 'DBSERVER' AND metricValue != 0   -
         AND collectionTime > '2014-08-12T09:10:51-07:00' -ATTRIBUTES name,      -
         metricObjectName, metricValue, collectionTime

9.6.3 Database Server Metrics

Database server metrics provide information about the server, such as CPU utilization, memory or network interconnections.

To display database server metrics, use an object type attribute equal to DBSERVER with the METRICCURRENT, METRICDEFINITION, and METRICHISTORY objects. Example 9-4 shows how to display database server metrics.

The following list describes the metric names and descriptions for database server metrics. The database server for the metric is specified by the metricObjectName attribute of the METRICCURRENT and METRICHISTORY objects.

  • DS_BBU_CHARGE: Disk controller battery charge.

  • DS_BBU_TEMP: Temperature of disk controller battery.

  • DS_CPUT: The server CPU utilization which is the instantaneous percentage of time over the previous minute that the system CPUs were not idle (from /proc/stat).

  • DS_CPUT_MS: The percentage of CPU time used by MS.

  • DS_FANS: The instantaneous number of working fans on the server.

  • DS_FSUT: The percentage of total space utilized on the file system that is currently in use. This metric shows the space utilization in the various files systems on the server.

  • DS_MEMUT: The percentage of total physical memory used on the server.

  • DS_MEMUT_MS: The percentage of physical memory used by MS.

  • DS_RUNQ: The instantaneous average number (over the preceding minute) of processes in the Linux run queue marked running or uninterruptible (from /proc/loadavg).

  • DS_SWAP_IN_BY_SEC: The number of swap pages read in KB per second.

  • DS_SWAP_OUT_BY_SEC: The number of swap pages written in KB per second.

  • DS_SWAP_USAGE: The percentage of swap space used.

  • DS_TEMP: The instantaneous temperature (Celsius) of the server, provided by the Baseboard Management Controller (BMC).

  • DS_VIRTMEM_MS: The amount of virtual memory used by MS in megabytes.

  • N_NIC_KB_RCV_SEC: The number of kilobytes received by the Ethernet interfaces per second.

  • N_NIC_KB_TRANS_SEC: The number of kilobytes transmitted by the Ethernet interfaces per second

  • InfiniBand Network Fabric metrics, not applicable to Oracle Exadata servers with RoCE Network Fabric.:
    • N_HCA_MB_RCV_SEC: The number of megabytes received by the InfiniBand interfaces per second.
    • N_HCA_MB_TRANS_SEC: The number of megabytes transmitted by the InfiniBand interfaces per second.
    • N_IB_MB_RCV_SEC: The number of megabytes received by an InfiniBand port per second.
    • N_IB_MB_TRANS_SEC: The number of megabytes transmitted by an InfiniBand port per second.
    • N_IB_UTIL_RCV: The percentage of an InfiniBand port capacity utilized for receiving data.
    • N_IB_UTIL_TRANS: The percentage of an InfiniBand port capacity utilized for transmitting data.

Example 9-4 Displaying Database Server Metrics

CellCLI> LIST METRICCURRENT DS_CPUT DETAIL

         name:                   DS_CPUT
         alertState:             normal
         collectionTime:         2014-12-17T15:54:25-08:00
         metricObjectName:       abcd2x3
         metricType:             Instantaneous
         metricValue:            6.7 %
         objectType:             DBSERVER

Parent topic: Monitoring Database Server with Metrics

9.6.4 Real-Time Insight

You can use the Real-Time Insight feature to enable real-time monitoring of your Exadata systems.

Commencing with Oracle Exadata System Software 22.1.0, Real-Time Insight provides infrastructure to:

  • Categorize specific metrics as fine-grained, and enable the collection of fine-grained metrics as often as every second.

  • Stream metric observations to user-defined locations in real-time, using either push (upload) or pull (download) transmission models.

Related Topics

Parent topic: Monitoring Database Server with Metrics

9.6.5 Using Real-Time Insight

You can use the Real-Time Insight feature to enable real-time monitoring of your Exadata systems using an external metric collection platform.

Parent topic: Monitoring Database Server with Metrics

9.6.5.1 Using Fine-Grained Metrics

Traditionally, Exadata metric collections occur at 1-minute intervals. However, real-time monitoring requires more timely metrics. Commencing with Oracle Exadata System Software 22.1.0, you can configure fine-grained metric collection.

Fine-grained metric collection is the foundation for the Real-Time Insight feature. Fine-grained metric collection works in conjunction with an external metric collection platform, where the fine-grained metric observations are collected and processed for visualization. Fine-grained metric observations reside only in server memory and are not persisted on the server. Consequently, no fine-grained metric history is maintained on each server.

9.6.5.1.1 Controlling Fine-Grained Metric Collection

The metricFGCollIntvlInSec attribute controls fine-grained metric collection.

  • To enable fine-grained metric collection, you must set the collection interval to a value between 1 and 60 seconds.

    For example:

    DBMCLI> ALTER DBSERVER metricFGCollIntvlInSec=1

    The metricFGCollIntvlInSec setting is related to the automatic upload frequency specified in the metricStreamIntvlInSec attribute. When automatic metric upload and fine-grained collection are both enabled (metricStreamIntvlInSec>0 and metricFGCollIntvlInSec>0), metricStreamIntvlInSec must be between 5 and 30 times metricFGCollIntvlInSec. For example, if metricStreamIntvlInSec=60, then metricFGCollIntvlInSec must be between 2 and 12.

  • To disable fine-grained metric collection on a server, set metricFGCollIntvlInSec=0.

    For example:

    DBMCLI> ALTER DBSERVER metricFGCollIntvlInSec=0

    Fine-grained metric collection can be disabled only when automatic metric upload is disabled (metricStreamIntvlInSec=0) or the automatic upload frequency is between 5 and 30 minutes (metricStreamIntvlInSec is between 300 and 1800).

9.6.5.1.2 Customizing Fine-Grained Metric Collection

By default, a set of key performance metrics is automatically enabled for fine-grained collection. But, you can customize fine-grained metric collection by enabling or disabling specific metrics.

  • To enable a metric for fine-grained collection, use the ALTER METRICDEFINITION command and specify finegrained=enabled. For example: 

    DBMCLI> ALTER METRICDEFINITION N_NIC_KB_TRANS_SEC finegrained=enabled
    DBMCLI> ALTER METRICDEFINITION N_MB_SENT,N_MB_RECEIVED finegrained=enabled
    DBMCLI> ALTER METRICDEFINITION finegrained=enabled WHERE name LIKE 'N_NIC.*'

  • To disable a metric for fine-grained collection, use the ALTER METRICDEFINITION command and specify finegrained=disabled. For example: 

    DBMCLI> ALTER METRICDEFINITION N_MB_SENT finegrained=disabled

  • At any time, to view the metrics enabled for fine-grained collection, use the following command:

    DBMCLI> LIST METRICDEFINITION WHERE finegrained=enabled

  • At any time, to view all of the metric definition details, including each metric description and whether the metric is enabled for fine-grained collection, use the following command:

    DBMCLI> LIST METRICDEFINITION DETAIL
9.6.5.2 Uploading Metric Observations to a Collection Platform

You can enable an Exadata server to automatically upload (push) metric observations to an external metric collection platform.

9.6.5.2.1 Controlling the Automatic Metric Upload Frequency

The metricStreamIntvlInSec attribute sets the upload interval (in seconds) for automatic uploads to the metric streaming endpoints specified by the metricStreamEndPoint attribute.

  • To enable automatic metric uploads, set the metricStreamIntvlInSec attribute to a non-zero value.

    For example:

    DBMCLI> ALTER DBSERVER metricStreamIntvlInSec=25

    The metricStreamIntvlInSec setting is related to the fine-grained collection frequency specified in the metricFGCollIntvlInSec attribute:

    • When automatic metric upload and fine-grained collection are both enabled (metricStreamIntvlInSec>0 and metricFGCollIntvlInSec>0), metricStreamIntvlInSec must be between 5 and 30 times metricFGCollIntvlInSec. For example, if metricFGCollIntvlInSec is set to 5, then metricStreamIntvlInSec must be between 25 and 150.

    • When automatic metric upload is enabled and fine-grained collection is disabled (metricStreamIntvlInSec>0 and metricFGCollIntvlInSec=0), the automatic upload frequency must be between 5 and 30 minutes (metricStreamIntvlInSec must be between 300 and 1800).

  • To disable automatic metric uploads, set metricStreamIntvlInSec=0.

    For example:

    DBMCLI> ALTER DBSERVER metricStreamIntvlInSec=0
9.6.5.2.2 Customizing the Metric Stream

By default, a set of key performance metrics is automatically enabled for streaming. But, you can customize the metric stream by enabling or disabling specific metrics.

  • To include a metric in the metric stream, use the ALTER METRICDEFINITION command and specify streaming=enabled. For example: 

    DBMCLI> ALTER METRICDEFINITION N_NIC_KB_TRANS_SEC streaming=enabled
    DBMCLI> ALTER METRICDEFINITION N_MB_SENT,N_MB_RECEIVED streaming=enabled
    DBMCLI> ALTER METRICDEFINITION streaming=enabled WHERE name LIKE 'N_NIC.*'

  • To remove a metric from the metric stream, use the ALTER METRICDEFINITION command and specify streaming=disabled. For example: 

    DBMCLI> ALTER METRICDEFINITION N_MB_SENT streaming=disabled

  • At any time, to view the metrics that are included in the metric stream, use the following command:

    DBMCLI> LIST METRICDEFINITION WHERE streaming=enabled

  • At any time, to view all of the metric definition details, including each metric description and whether the metric is included in the metric stream, use the following command:

    DBMCLI> LIST METRICDEFINITION DETAIL
9.6.5.2.3 Configuring the Endpoints for Automatic Metric Upload

You can automatically upload (push) the metric stream to one or more collection endpoints by setting the metricStreamEndPoint attribute as follows: 

metricStreamEndPoint[+]=((host="endpoint-URL"[,type="stream-format"][,token="authentication-token"][,{httpProxy|httpsProxy}="proxy-server"])
                          [,(host="endpoint-URL"[,type="stream-format"][,token="authentication-token"][,{httpProxy|httpsProxy}="proxy-server"])]...)

In the metricStreamEndPoint definition:

  • host: Specifies the URL for the collection endpoint. The URL can use HTTP or HTTPS.

  • type: Optionally specifies the format of the stream. Supported values are:

    • json: Provides the stream in a JSON format

    • plaintext: Provides the stream in a plain text format

    The default value is json.

  • token: Optionally specifies the authentication token for the collection endpoint. Consult the metric collection platform for details about generating the token.

  • httpProxy or httpsProxy: Optionally specifies a proxy server to facilitate network connectivity to the collection endpoint. A proxy server is required if a firewall resides between the Exadata system and the collection endpoint.

You can use the optional += operator to add collection endpoints to an existing metricStreamEndPoint definition. Otherwise, the = operator overwrites the previous attribute value.

Example 9-5 Setting Up a JSON Stream

This example shows how to set up a JSON stream. In the example command, the host and token values come from the collection platform and we assume that network connectivity is through the specified proxy. 

DBMCLI> ALTER DBSERVER metricStreamEndPoint=((host="https://ingest.stream.example.com/v2/datapoint",type="json",token="wcfA_**********Z58QpKg",httpProxy="www-proxy.example.com:80"))

Example 9-6 Adding a Plain Text Endpoint

This example shows how to add a plain text endpoint to the existing metricStreamEndPoint. In the example command, the host and token values come from the collection platform. The example also assumes that the collection platform is within the corporate network requiring no network proxy. 

DBMCLI> ALTER DBSERVER metricStreamEndPoint+=((host="http://idbsrv.example.com:8086/api/v2/write?org=Exadata&bucket=Metrics&precision=ns",type="plaintext",token="6unif**********rOXwtfkG0gWGENyePd6uN6OLR_deTZL4IuG9VTfDWwvpB-QvJcCcFs_NVjmpsyANz0Q8psA=="))
9.6.5.3 Downloading Metric Observations from an Exadata Server

You can download (pull) the metric stream from an Exadata server by using the provided REST endpoint. This includes all metrics enabled for streaming (streaming=enabled), regardless of whether the system is enabled for fine-grained metric collection or configured for automatic metric upload.

On each storage server, the REST endpoint URL is:

https://server-name/metricstream/list?stream=true

On each database server, the endpoint uses port 7879. Consequently, the URL is:

https://server-name:7879/metricstream/list?stream=true

For maximum efficiency, the download interval should be a multiple of the metric collection interval. If fine-grained metric collection is enabled (metricFGCollIntvlInSec>0) on the server, then coordinate the download frequency with the fine-grained collection interval. Otherwise, coordinate the download frequency with the standard 1-minute collection interval.

To facilitate access to the metric stream, you should use a dedicated user account, which only has access to the stream. You can use the following command sequence to appropriately configure a user account in DBMCLI, which you can then use for authentication to the REST endpoint. In the command sequence, substitute your own user and role names. 

CREATE ROLE metric_collector_role
GRANT PRIVILEGE LIST ON METRICSTREAM ALL ATTRIBUTES WITH ALL OPTIONS TO ROLE metric_collector_role
CREATE USER metric_collector PASSWORD=<password>
GRANT ROLE metric_collector_role TO USER metric_collector

Parent topic: Using Real-Time Insight

9.6.5.4 Tagging Metric Observations

In each Exadata database server and storage server you can define a set of metric tags, which are included in every observation in the metric stream. These tags can help you to organize and group observations generated by numerous Exadata servers.

You can configure metric tags by setting the metricStreamTags attribute to a valid JSON string containing tag and value pairs as follows: 

metricStreamTags='{"tag1":"value1"[,"tag2":"value2"]...}'

For example:

DBMCLI> ALTER DBSERVER metricStreamTags='{"application":"personnel","department":"HR"}'

Parent topic: Using Real-Time Insight

9.6.5.5 Understanding the Metric Stream Format

Real-time metric observations contain a core set of attributes. However, the format of the metric stream depends on the mode of access.

If you are automatically uploading the metric stream to a metric collection platform, you can specify the metric stream format in the metric endpoint configuration. The available formats are JSON or plain text.

Following is an example of the JSON format:

json: {
    "gauge": [{
            "metric": "OS_NET_RX_BY_SEC",
            "value": "0.0012989044189453125",
            "timestamp": 1652473286000,
            "unit": "MB/sec",
            "dimensions": {
                "server": "celadm09.example.com",
                "objectName": "eth0",
                "nodeType": "STORAGE",
                "fleet": "example-fleet",
                "pod": "dbm01",
                "cluster": "c01"
            }
        }, {
            "metric": "SIO_IO_RD_FC_HD_SEC",
            "value": "0.0",
            "timestamp": 1652473286000,
            "unit": "MB/sec",
            "dimensions": {
                "server": "celadm09.example.com",
                "objectName": "SMARTIO",
                "nodeType": "STORAGE",
                "fleet": "example-fleet",
                "pod": "dbm01",
                "cluster": "c01"
            }
        }
    ]
}

The plain text format contains essentially the same information as the JSON stream. However, with the plain text format, each metric observation is presented on a separate line. Following is an example of the plain text format:

metrics,name=OS_NET_RX_BY_SEC,objectName=eth0,server=celadm09.example.com,unit=MB/sec,nodeType=STORAGE,fleet=example-fleet,pod=dbm01,cluster=c01 value=9.441184615324398E-4 1652473456000000000
metrics,name=OS_NET_RX_BY_SEC,objectName=eth0,server=celadm09.example.com,unit=MB/sec,nodeType=STORAGE,fleet=example-fleet,pod=dbm01,cluster=c01 value=0.002647613311980988 1652473457000000000

If you are downloading the metric stream by using the provided REST endpoint, the data is presented in a format similar to the plan text upload format where each metric observation is presented on a separate line. Following is an example of the download format:

DS_CPUT{objectName="dbadm05",unit="%",server="dbadm05.example.com",nodeType="KVMHOST",fleet="example-fleet",pod="dbm01",cluster="c01"} 23.10906363831155 1652485449597
DS_MEMUT{objectName="dbadm05",unit="%",server="dbadm05.example.com",nodeType="KVMHOST",fleet="example-fleet",pod="dbm01",cluster="c01"} 99 1652485449597
DS_MEMUT_MS{objectName="dbadm05",unit="%",server="dbadm05.example.com",nodeType="KVMHOST",fleet="example-fleet",pod="dbm01",cluster="c01"} 0.12396045794483294 1652485449597

The following list describes the attributes contained in the metric stream:

  • The metric name is identified as follows:

    • In the JSON upload format, the metric name follows the metric tag.

    • In the plain text upload format, the metric name is the value following name=.

    • In the download format, the metric name is the first element on each line, preceding the left braces ({).

  • The metric value is located as follows:

    • In the JSON upload format, the metric value follows the value tag.

    • In the plain text upload format, the metric value follows value=.

    • In the download format, the metric value is the second last element on each line, following the right braces (}).

  • The time of the metric observation is located as follows:

    • In the JSON upload format, the timestamp follows the timestamp tag. The timestamp is expressed as the number of milliseconds (1 x 10-3 sec) since January 1, 1970, 00:00:00 GMT.

    • In the plain text upload format, the timestamp is the last element on each line. The timestamp is expressed as the number of nanoseconds (1 x 10-9 sec) since January 1, 1970, 00:00:00 GMT.

    • In the download format, the timestamp is the last element on each line. The timestamp is expressed as the number of milliseconds (1 x 10-3 sec) since January 1, 1970, 00:00:00 GMT.

  • The unit value describes the unit of measurement for the metric observation.

  • The server value contains the name of the Exadata server that generated the metric observation.

  • The objectName value contains the name of the Exadata object associated with the metric.

  • The nodeType value contains the type of the Exadata server that generated the metric observation.

  • The fleet, pod, and cluster attributes are examples of user-defined metric tags, which you can use to organize and group observations generated by numerous Exadata servers. You can tag metrics by setting the metricStreamTags DBSERVER attribute.

9.7 DBMCLI Command Reference

DBMCLI has both administrative and object commands.

The following commands are available with the DBMCLI utility:

Parent topic: Using the DBMCLI Utility

9.7.1 ALTER

Purpose

The ALTER command performs an action on or changes attributes of a single database server object or multiple objects. The ALTER command can be used to change an attribute or to take an action upon the object.

Syntax

ALTER { object_type object_name[, object_name]... operation
      | attribute_name = attribute_value 
        [, attribute_name = attribute_value]...
     }

Usage Notes

The following arguments can be used with the command:

  • object_type can be the following:
    • ALERTHISTORY
    • DBSERVER
    • IBPORT (not available in user domain (domU) environments)
    • THRESHOLD (not available in user domain (domU) environments)
    • USER (not available in user domain (domU) environments)
  • object_name is the name or identifier of an alert history, database server, LUN, or threshold.
  • operation is a valid action for the specified object_type.

When multiple objects are the target of an ALTER command, there is the possibility of partial success. If an error occurs, then the command is interrupted, and the remaining objects are not changed.

Related Topics

Parent topic: DBMCLI Command Reference

9.7.1.1 ALTER ALERTHISTORY

Purpose

The ALTER ALERTHISTORY command changes the attributes of all or specified alert histories.

Syntax

ALTER ALERTHISTORY { ALL | alertid1  [,alertid2 ...]}
       examinedBy=user_name

Usage Notes

The following arguments can be used with the command:

  • alertidn: The identifier of the alerts to be changed.

  • user_name: The name of the user who acknowledged the alert.

Examples

Example 9-7 shows the ALTER command used with the ALERTHISTORY object to update the examinedBy attribute. The examinedBy attribute is the only ALERTHISTORY attribute that can be modified.

Example 9-7 Altering ALERTHISTORY Attributes

DBMCLI> ALTER ALERTHISTORY 1671443714 -
                            examinedBy="jdoe"

DBMCLI> ALTER ALERTHISTORY ALL examinedBy="jdoe"

Parent topic: ALTER

9.7.1.2 ALTER DBSERVER

The ALTER DBSERVER command changes the attributes of the database server.

Syntax

ALTER DBSERVER  {
  | SHUTDOWN SERVICES { RS | MS | ALL }
  | RESTART SERVICES { RS | MS | ALL }
  | RESTART BMC
  | STARTUP SERVICES { RS | MS | ALL }
  | LED { ON | OFF }
  | VALIDATE { MAIL | SNMP | CONFIGURATION }
  | VALIDATE SYSLOGCONF facility.priority
  | CONFIGUREBMC
  | { snmpuser=((user_clause)[,(user_clause)[,..]]) | snmpuser.name=(user_clause) }
  | attribute_name = attribute_value 
        [, attribute_name = attribute_value]...
  }

Usage Notes

The following table lists the arguments and options for the ALTER DBSERVER command:

Argument Options Description

SHUTDOWN SERVICES

MS (Management Server)

RS (Restart Server)

ALL

The MS service is shut down.

The RS service is shut down.

The ALL option shuts down the MS and RS services.

RESTART SERVICES

MS

RS

ALL

The MS service is shut down, and then started.

The RS service is shut down, and then started.

The ALL option shuts down, then starts up, the MS and RS services.

RESTART BMC

n/a

Restarts the Baseboard Management Controller (BMC).

STARTUP SERVICES

MS

RS

ALL

The MS service is started.

The RS service is started.

The ALL option starts up the MS and RS services.

LED

ON

OFF

LED ON and LED OFF operations turn on and off the chassis LED.

You can manually set the LED to light to indicate that a database server requires maintenance. The LED is also set to light automatically if a component fails.

VALIDATE

MAIL

SNMP

CONFIGURATION

The VALIDATE MAIL operation sends a test message using the email attributes configured for the database server.

The VALIDATE SNMP operation sends a test message using the SNMP attributes configured for the database server. The VALIDATE SNMP TYPE=ASR operation validates ASR on Exadata Storage Server.

The VALIDATE CONFIGURATION operation validates the server configuration.

VALIDATE SYSLOGCONF

facility.priority

The VALIDATE SYSLOGCONF facility.priority sends a test message for the specified facility and priority.

CONFIGUREBMC

n/a

Configures the BMC for hardware alerts to the local database server so that Management Server can pick up the alerts.

snmpuser or snmpuser.name

 user_clause

Defines the user who receives SNMP alerts. You can either supply a list of user clauses for all SNMP users, or individual user clauses using the attribute snmpuser.name. The user_clause is of the form: 

([name=user1,] authProtocol=auth_type, authPassword=*,                   \
privProtocol=priv_type, privPassword=*) ,                               \
(name=user2, authProtocol=auth_type, authPassword=*,                    \
privProtocol=priv_type, privPassword=*, )

If updating a single user, then do not include the phrase name=user1, in the user_clause.

attributes

N/A

The attributes that can be changed using the ALTER DBSERVER command are shown as modifiable in Example 9-43.

Note:

In user domain (domU) environments, the following commands are not permitted:

  • ALTER DBSERVER CONFIGUREBMC
  • ALTER DBSERVER RESTART BMC
  • ALTER DBSERVER LED { ON | OFF }

The following are additional usage notes for the ALTER DBSERVER command:

  • It may be necessary to restart, shut down, or start up a database server for the following reasons:
    • Software upgrades
    • Service outages that include any condition under which a database server is not responding to service requests
  • To set up the database server to send notifications about alerts, you can configure the following database server attributes:
    • mailServer
    • smtpPort
    • smtpUseSSL
    • smtpFrom
    • smtpFromAddr
    • smtpToAddr
    • snmpSubscriber
    • snmpUser
    • snmpEngineID
    • notificationMethod
    • notificationPolicy
    • emailSubscriber

    The smtpToAddr attribute can be set to a list of comma-delimited email addresses that are the recipients of the alert notification. The list must be enclosed in quotation marks.

    The snmpSubscriber attribute can be set to a list of SNMP targets to which the SNMP alert notification is sent. These targets are specified as follows: 

    snmpSubscriber=(
  (host=host[,port=port][,community=community][,type=user_type][,fromIP="ip"]
[,asrmPort="ASRManager_port"])
[,(host=host[,port=port][,community=community][,type=user_type][,fromIP="ip"]
[,asrmPort="ASRManager_port"])] ...)

    Note:

    • The ALTER DBSERVER ... smnpSubscriber command replaces the existing value set for smnpSubscriber. To add to the list of SNMP targets ensure that you include the existing values in the command. The following message is displayed after running the command: 

      snmpSubscriber {0} has been replaced with {1}.

    • The snmpSubscriber attribute is used to configure Oracle Auto Service Request (ASR).

    • The SNMP alerts conform to MIBs (management information base) which are included with each installation of Oracle Exadata System Software. The MIB files on the database server are available at /opt/oracle/dbserver/dbms/deploy/config/.

      Type ASR and v3ASR alerts conform to SUN-HW-TRAP-MIB, which is available in the SUB-HW-TRAP-MIB.mib file.

      The other alert types conform to the cell_alert MIB, which is available in the cell_alert.mib file.

      The SNMP alerts and MIB conform to SNMP version 1 (SNMPv1). However, the Auto Service Request alerts conform to SNMP version 2c (SNMPv2c).

    The default value for port is 162. The default value for community is public.

    The notificationMethod attribute value can be mail, snmp, none, or a combination of mail and snmp, such as notificationMethod='mail,snmp'. The default value is mail.

    The snmpSubscriber types are ASR, v3, and v3ASR. For types v3 and v3ASR, a snmpUser must be defined, and the user name is provided instead of community.

    For the v3ASR type, the user must be defined with authProtocol=SHA, and privProtocol=AES. These are the only protocols supported by ASR Manager. Setting the snmpSubscriber as type v3ASR also sets the ILOM properties and rules for traps sent by ILOM.

    If type is not specified, the default is version 1, cell_alert traps. There is no string to specify this type. To use this type, just omit the type field.

    The fromIP field enables you to specify an IP address from which the trap is sent. If this field is not specified, it defaults to the IP address associated with eth0. Use this field if the default IP address is not registered with Oracle ASR Manager. Oracle ASR Manager only processes SNMP traps that are sent from IP addresses that it recognizes.

    The fromIP field is allowed only for snmpSubscriber with type set to either ASR or v3ASR.

    For example:

    DBMCLI> alter dbserver snmpSubscriber=((host=asrhost,port=162,community=public,fromIP="1.1.1.1",type=ASR))

    The following example returns an error because the type is not ASR or v3ASR. 

    DBMCLI> alter dbserver snmpSubscriber=((host=localhost,port=162,community=public,fromIP="1.1.1.1"))
DBM-00068: The fromIP field is only supported for ASR SNMP subscribers.

    The asrmPort field enables you to specify the port number on an Oracle ASR Manager machine that MS uses to communicate with Oracle ASR Manager. This port must be the same as the HTTP port of Oracle ASR Manager’s HTTP Receiver. You can check this by running asr show_http_receiver on the Oracle ASR Manager machine.

    The asrmPort field is allowed only for snmpSubscriber with type set to either ASR or v3ASR. The default value for this port is 16161.

    The snmpUser attribute defines the user who receives SNMP alerts. This command can only be run in interactive mode. There are two methods for configuring this attribute. 

    snmpuser=((user_clause)[,(user_clause)[,..]])

snmpuser.name=(user_clause)

    • If you specify snmpuser, then you must provide a user_clause for every configured user. If you omit a user, then that user will no longer receive SNMP alerts. The ((user_clause)[,(user_clause)[,..]]) string that you provide overwrites the previous string used for the snmpuser attribute.

    • If you specify snmpuser.name, then you must provide a user_clause for only the specified user. This allows you to add, delete, or modify each user individually, without having to supply the entire snmpuser attribute string each time.

    • If you use snmpuser='', then all SNMP users are removed. If you use snmpuser.name='', then only the specified user is removed. You cannot remove an SNMP user while it is still referenced by a V3 SnmpSubscriber.

    Each method uses a user_clause, which has the following format: 

    (([name=user1,] authProtocol=auth_type, authPassword=*,               \
privProtocol=priv_type, privPassword=*) ,                            \
(name=user2, authProtocol=auth_type, authPassword=*,                 \
privProtocol=priv_type, privPassword=*, ), ...)

    If updating a single user, then do not include the phrase name=user1, in the user_clause, because you have already supplied the name as part of snmpuser.name.

    • name is the user name.

    • Only * is allowed for the password values in the command. Passwords are not stored or displayed. Secure hash keys are computed and used for trap authentication and encryption.

    • authProtocol is the authentication protocol. Options are MD5 or SHA.

      The authProtocol must be specified for the snmpUser attribute.

      The system prompts for the authentication password. The authentication password must have 8 to 12 alphanumeric characters.

    • privProtocol is encryption protocol. Options are none, AES, or DES. The default is none when the privProtocol attribute is not specified.

      The system prompts for an encryption password if the encryption protocol is specified. The password is exactly 8 alphanumeric characters, and they are case sensitive.

    The smtpUseSSL attribute enables Secure Socket Layer (SSL) encryption on the email notifications when the attribute is set to true.

    The notificationPolicy attribute value can be none or a combination of critical, warning, or clear, such as notificationPolicy='warning,clear.'

    • The critical value refers to hardware-generated alerts or alerts generated by Automatic Diagnostic Repository (ADR) or Baseboard Management Controller (BMC). The critical value also refers to a metric alert when the value exceeds the critical threshold specified in the metric definition.
    • The warning value refers to a metric alert when the value exceeds the warning threshold specified in the metric definition.
    • The clear value refers to a metric alert when the value is below the threshold boundary after having previously exceeded a warning or critical threshold.
    • The maintenance value refers to all hardware-related errors. The hardware errors are reported as "Maintenance" in email message subject lines.

  • For each subscriber, the host must be specified as either a domain name or an IP address. Enclose the host name or IP address in quotation marks if it contains non-alphanumeric characters. Port and community values are optional. The default port value is 162. The default community value is public. The type value is optional. The default value for type is NULL. The types ASR, V3, and v3ASR are the only supported non-NULL value.

  • After startup of the Management Server (MS), the snmpSubscriber list entries with type ASR or v3ASR are added to the ILOM for the database server. This ensures that when an ILOM is replaced, the entries are set for the new ILOM. If the entries are removed from the ILOM, then they must be manually added to the ILOM using the ALTER DBSERVER ... snmpUser= command.

  • The snmpSubscriber with type=asr or type=v3ASR should only be configured to point to Oracle ASR Manager.

  • To validate that email messages are successfully sent for database server alerts or events, use the ALTER command with the VALIDATE MAIL option. The validation process sends a test email message to the configured recipient. If that test email message is not received, then an email configuration setting is not valid.

  • The emailFormat attribute can be html or text. By default, email notifications are sent in HTML format. Change the value to text to receive plain text email notifications.

  • The ALTER DBSERVER snmpEngineID command is used by the SNMP managers to subscribe to alerts from the database servers. The snmpEngineID parameter can be up to 20 characters. It should be unique for each target within a data center. The default is the database server name. This default is used if the snmpEngineID attribute is not set before the SNMP users are defined.

    The engine identifier should not be changed after SNMP users are defined. Any change to an engine identifier causes the user keys to be re-computed, and user passwords must be re-entered.

  • If the database server name is changed, then you must choose a unique database server name.
  • If an ipaddressN attribute is modified, then the network configuration file /etc/oracle/cell/network-config/cellinit.ora is modified.
  • The ALTER DBSERVER snmpSubscriber command configures the Oracle ASR subscriber, and sends traps.

  • The ALTER DBSERVER emailSubscriber command sets a list of comma-delimited email addresses that are the recipients of alert notifications for specific alert types. The following is an example of the syntax: 

    ALTER DBSERVER emailSubscriber = ((email="email_address1",                \ 
           alertType="alert_type")                               \
          [, (email="email_address2",alertType="alert_type"), ...])

    The email address must be a valid email address. The email parameter is mandatory. The alertType parameter specifies the type of alert, and is optional. The alert types are HARDWARE, SOFTWARE, METRIC or ADR. If the alert type is not specified, then the subscription is for all alert types.

    An empty input string removes the current set of subscribers.

    The notification policy must be set before alert notifications can be received. The policy applies to all email subscribers. The notification policy for these alerts are the same as for snmpSubscriber alerts.

  • The syslogconf attribute extends syslog rules for a database server. The attribute can be used to designate that syslog messages be forwarded to a specified management server. On the management server, the forwarded messages are directed to a file, console, or management application, depending on the syslog configuration on the management server. The following shows the syntax for the attribute: 

    syslogconf = ('selector @node' [, 'selector @node']... )

    In the preceding syntax, selector is the message type, and node is the specified server. Both variables follow syslog.conf standard syntax rules.

    • The facility option for the syslogconf attribute must be one of the following: auth, authpriv, cron, daemon, ftp, kern, lpr, mail, mark, news, security, syslog, user, uucp, local0, local1, local2, local3, local4, local5, local6, local7, none, or *.

    • The priority option for the syslogconf attribute must be one of the following: alert, crit, debug, emerg, err, error, info, notice, panic, warn, warning, none, or * (asterisk).

  • The ALTER DBSERVER VALIDATE syslogconf selector command sends a test log message. The test message is directed as specified by rules in the /etc/syslog.conf file. If the syslogconf assignment extends the syslog rules, then a test message is forwarded to the specified management servers.

  • Starting with Oracle Exadata System Software release 19.1.0, you can use the syslogFormat attribute to change the standard format for syslog to any format by setting the value to the desired format string. Setting the syslogFormat attribute to an empty string removes the format change, reverting the syslog format to the default format. If the format string contains a control character, it must be preceded by a backslash when entering the command.

    See Example 9-24 for examples.

  • Starting with Oracle Exadata System Software release 19.3.0, you can use the syslogFormat attribute to enable sending syslog in an encrypted format. For the complete configuration steps, refer to Encrypting System Log Information.

  • You can turn off the diagnostic pack attachment to emails by running the following command:

    ALTER DBSERVER diagPackEmailAttach=FALSE

  • Starting with Oracle Exadata System Software release 19.1.0, the httpsAccess attribute can be used to specify a list of IP addresses or IP subnet masks that control who can access the RESTful service via HTTPs. The value you specify for httpsAccess overwrites any previous value. You can use the following values for httpsAccess:

    • ALL — to allow access to all hosts (Default)
    • NONE — to disable the HTTPs port completely
    • IP1, IP2,..., IPn — to only allow access to hosts with IP addresses IP1, IP2,..., IPn where IPn is a valid IP address in IPv4, IPv4 subnet, IPv6 or IPv4-embedded IPv6 format. You can specify a maximum of 512 IP addresses for the access control list.

    Additionally, instead of a single IP address, you can use the / character to specify a range of IP addresses using a subnet mask. For example the range '192.168.10.0/24' corresponds to hosts having IP addresses from 192.168.10.1 to 192.168.10.255. If you specify an IP address range, you need to enclose the IP address string in quotes.

  • To set up CA-certified security certificates on the cell for use with ExaCLI, use the following attributes:

    Note:

    The following attributes can be used only if you are running the ALTER CELL command from ExaCLI.

    • securityPubKey - Specifies the URL to the public key file.

    • securityPrivKey - Specifies the URL to the private key file.

    • securityPrivKeyPW - Specifies the password to use if the private key file is encrypted.

    For example:

    ExaCLI> alter cell securityPubKey="http://www.example.com/security/newkey.crt",  -
                   securityPrivKey="http://www.example.com/security/newkey.key", -
                   securityPrivKeyPW=*

password=****************

    After you upload the CA-certified security certificate, you must restart MS before the new security certificate is visible. 

    CellCLI> alter cell restart services ms

    See Also:

    Using a CA-Certified Security Certificate

  • Starting with Oracle Exadata System Software release 21.2.0, the ilomSyslogClients attribute specifies the remote destination to forward syslog messages from the Integrated Lights Out Manager (ILOM) service processor (SP).

    The ilomSyslogClients attribute accepts a comma-separated list of up to two loghost servers. For each loghost server, you must specify a valid hostname or IP address.

    For example:

    DBMCLI> ALTER DBSERVER ilomSyslogClients="192.0.2.101,192.0.2.201"

    Note:

    The specified ilomSyslogClients must listen on port 514 to receive the ILOM syslog messages.

  • Starting with Oracle Exadata System Software release 22.1, the syslogInput attribute enables syslog on the local host (database server or storage server) to forward additional logs to remote log servers.

    The syntax for configuring the syslogInput attribute is: 

    syslogInput = ('selector @[@]node[:remote_port]' [, 'selector @[@]node[:remote_port]']... )

    In the preceding syntax, selector specifies the additional logs being forwarded. The selector value can contain the following entries:

    • audit - Specifies the audit log at /var/log/audit/audit.log.

    • aide - Specifies the Advanced Intrusion Detection Environment (AIDE) log at /var/log/aide/aide.log.

    • yum - Specifies the YUM log at /var/log/yum.log.

    Multiple selector entries must be separated by a semicolon (;) character.

    Each node is specified using the hostname or IP address preceded by one or two ampersand (@) characters. You can specify one ampersand (@) character to use UDP for communications or specify two ampersand (@@) characters to use TCP.

    By default, the remote system receives communications on port 514, which is the default rsyslogd port. You can specify another port number by appending a colon (:) character and remote port number to the node specification

    In the following example, loghost1 is configured to receive audit and AIDE logs using UDP on the default rsyslogd port (514). Also, loghost2 is configured to receive YUM logs using TCP on port 10514. 

    DBMCLI> ALTER DBSERVER syslogInput=('audit;aide @loghost1','yum @@loghost2:10514')

    To stop and remove additional log forwarding, set syslogInput to an empty string. For example: 

    DBMCLI> ALTER DBSERVER syslogInput=''

  • Set the pendingCoreCount attribute to increase the number of active cores on Oracle Exadata using capacity-on-demand.

    See also:

Examples

Example 9-8 shows how to set the asrmPort field for an snmpSubscriber.

Example 9-9 shows how to enable and disable the auto diagpack upload feature.

Example 9-10 shows how to set up email notifications for the database server.

Example 9-11 shows how to validate the email setup on a database server.

Example 9-12 shows how to change the format of email messages.

Example 9-13 shows how to validate the SNMP setup on a database server.

Example 9-14 shows how to specify the type of email alerts. In the example, one subscriber gets hardware and software alerts, and the other subscriber gets ADR alerts.

Example 9-15 shows how to modify the SNMP user.

Example 9-16 shows how to modify a single SNMP user.

Example 9-17 shows how to start up and shut down database server services.

Example 9-18 shows how to set the LED on the database server.

Example 9-19 shows setting the pending core count for capacity-on-demand.

Example 9-20 shows how to add a rule using the syslogconf attribute.

Example 9-21 shows how to add and validate a rule with test message.

Example 9-22 shows how to remove the syslog.conf rule.

Example 9-23 shows how to restrict HTTPS Access to the Exadata RESTful service to a specific range of IP addresses.

Example 9-8 Setting the asrmPort for an snmpSubscriber

DBMCLI> ALTER DBSERVER snmpSubscriber=((host=host1,port=162,community=public,type=asr,asrmPort=16161))

Example 9-9 Enabling/Disabling Auto Diagpack Upload

You can enable or disable this feature by setting the diagPackUploadEnabled attribute on the dbserver object.

Set the attribute to false to disable this feature, true to enable it. The default is true. 

DBMCLI> ALTER DBSERVER diagPackUploadEnabled=FALSE

Example 9-10 Configuring Email Notifications for a Database Server

DBMCLI> ALTER DBSERVER mailServer='mail_relay.example.com',            -
                    smtpFromAddr='john.doe@example.com',         -
                    smtpFrom='John Doe',                         -
                    smtpToAddr='jane.smith@example.com',         -
                    snmpSubscriber=((host=host1),(host=host2)),  -
                    notificationPolicy='clear',                  -
                    notificationMethod='mail,snmp'

Example 9-11 Validating Email on a Database Server

DBMCLI> ALTER DBSERVER VALIDATE MAIL

Example 9-12 Changing the Format of Email Messages

DBMCLI> ALTER DBSERVER emailFormat='text'
DBMCLI> ALTER DBSERVER emailFormat='html'

Example 9-13 Validating SNMP on a Database Server

DBMCLI> ALTER DBSERVER VALIDATE SNMP

Example 9-14 Specifying the Type of Email Alert

ALTER DBSERVER emailSubscriber=                                             \
           ((email="email1@example.com",alertType="HARDWARE,SOFTWARE"), \
           (email="email2@example.com",alertType="ADR"))

Example 9-15 Modifying the SNMP User

This example shows the initial configuration of a single SNMP user, where the administrator is prompted to enter the passwords.

CellCLI> ALTER CELL snmpuser = ((name=ASR, authprotocol=md5, authpassword=*,   \
                    privprotocol=AES, privpassword=*))
snmpUser ASR authpassword: password
Confirm snmpUser ASR authpassword: password
snmpUser ASR privpassword: password
Confirm snmpUser ASR privpassword: password

Example 9-16 Modifying a Single SNMP User

The following code examples show adding an SNMP user, changing that user's password, and then removing that user.

## adding users individually
CellCLI> ALTER CELL snmpuser.user2=(authprotocol=SHA,authpassword=*)

snmpUser user2 authpassword: password
Confirm snmpUser user2 authpassword: password

snmpUser ((name=user1, authProtocol=SHA, privProtocol=AES)) has been replaced with 
((name=user1, authProtocol=SHA, privProtocol=AES),(name=user2, authProtocol=SHA)).
Cell cel01 successfully altered

## changing a password of an existing user
CellCLI> ALTER CELL snmpuser.user2 = (authprotocol=SHA,authpassword=password)

Cell cel01 successfully altered

## delete a user individually
CellCLI> ALTER CELL snmpuser.user2=''

snmpUser ((name=user1, authProtocol=SHA, privProtocol=AES),(name=user2, authProtocol=SHA)) has
 been replaced with ((name=user1, authProtocol=SHA, privProtocol=AES)).
Cell cel01 successfully altered

Example 9-17 Starting Up and Shutting Down Database Server Services

DBMCLI> ALTER DBSERVER SHUTDOWN SERVICES MS

DBMCLI> ALTER DBSERVER RESTART SERVICES MS

Example 9-18 Setting the Database Server LED Off and On

DBMCLI> ALTER DBSERVER LED OFF
DBMCLI> ALTER DBSERVER LED ON

Example 9-19 Setting Pending Core Count

This example shows how to set the pending core count on a database server. Use the LIST DBSERVER command to verify the correct value is set. 

DBMCLI> ALTER DBSERVER pendingCoreCount=20

Example 9-20 Using the syslogconf Attribute

DBMCLI> ALTER DBSERVER syslogconf=('*.err;authpriv.none @loghost', -
         '*.emerg @loghost')

Example 9-21 Adding and Validating a Rule 

DBMCLI> ALTER DBSERVER syslogconf=('kern.crit @loghost')
DBMCLI> ALTER DBSERVER VALIDATE syslogconf   'kern.crit'

Example 9-22 Removing All syslog.conf Rules

DBMCLI> ALTER DBSERVER syslogconf=''

Example 9-23 Restricting HTTPS Access to the Exadata RESTful Service

The following command allows HTTPs port access to hosts having IP addresses in the range from 192.168.10.1 to 192.168.10.255.

DBMCLI> ALTER DBSERVER httpsAccess="192.168.10.0/24"

Example 9-24 Setting the Syslog Format to a Custom String Then Reverting to the Default Format

DBMCLI> ALTER DBSERVER syslogformat="%TIMESTAMP:::date-rfc3339% %HOSTNAME%%syslogtag%
%syslogseverity-text%:%msg:::sp-if-no-1st-sp%%msg:::drop-last-lf%\\n"

DBMCLI> ALTER DBSERVER syslogformat="%TIMESTAMP% %HOSTNAME% %msg%\\n"

DBMCLI> ALTER DBSERVER syslogformat=""
9.7.1.2.1 Real-Time Insight Attributes

Commencing with Oracle Exadata System Software 22.1.0, you can use the Real-Time Insight feature to enable real-time monitoring of your Exadata systems.

Fine-Grained Metric Collection

The metricFGCollIntvlInSec attribute controls fine-grained metric collection.

  • To enable fine-grained metric collection, you must set the collection interval to a value between 1 and 60 seconds.

    For example:

    DBMCLI> ALTER DBSERVER metricFGCollIntvlInSec=1

    The metricFGCollIntvlInSec setting is related to the automatic upload frequency specified in the metricStreamIntvlInSec attribute. When automatic metric upload and fine-grained collection are both enabled (metricStreamIntvlInSec>0 and metricFGCollIntvlInSec>0), metricStreamIntvlInSec must be between 5 and 30 times metricFGCollIntvlInSec. For example, if metricStreamIntvlInSec=60, then metricFGCollIntvlInSec must be between 2 and 12.

  • To disable fine-grained metric collection on a server, set metricFGCollIntvlInSec=0.

    For example:

    DBMCLI> ALTER DBSERVER metricFGCollIntvlInSec=0

    Fine-grained metric collection can be disabled only when automatic metric upload is disabled (metricStreamIntvlInSec=0) or the automatic upload frequency is between 5 and 30 minutes (metricStreamIntvlInSec is between 300 and 1800).

Automatic Metric Upload

The metricStreamIntvlInSec attribute sets the upload interval (in seconds) for automatic uploads to the metric streaming endpoints specified by the metricStreamEndPoint attribute.

  • To enable automatic metric uploads, set the metricStreamIntvlInSec attribute to a non-zero value.

    For example:

    DBMCLI> ALTER DBSERVER metricStreamIntvlInSec=25

    The metricStreamIntvlInSec setting is related to the fine-grained collection frequency specified in the metricFGCollIntvlInSec attribute:

    • When automatic metric upload and fine-grained collection are both enabled (metricStreamIntvlInSec>0 and metricFGCollIntvlInSec>0), metricStreamIntvlInSec must be between 5 and 30 times metricFGCollIntvlInSec. For example, if metricFGCollIntvlInSec is set to 5, then metricStreamIntvlInSec must be between 25 and 150.

    • When automatic metric upload is enabled and fine-grained collection is disabled (metricStreamIntvlInSec>0 and metricFGCollIntvlInSec=0), the automatic upload frequency must be between 5 and 30 minutes (metricStreamIntvlInSec must be between 300 and 1800).

  • To disable automatic metric uploads, set metricStreamIntvlInSec=0.

    For example:

    DBMCLI> ALTER DBSERVER metricStreamIntvlInSec=0

Metric Upload Endpoints

The metricStreamEndPoint attribute specifies one or more collection endpoints that automatically receive the metric stream. You can set metricStreamEndPoint as follows: 

metricStreamEndPoint[+]=((host="endpoint-URL"[,type="stream-format"][,token="authentication-token"][,{httpProxy|httpsProxy}="proxy-server"])
                          [,(host="endpoint-URL"[,type="stream-format"][,token="authentication-token"][,{httpProxy|httpsProxy}="proxy-server"])]...)

In the metricStreamEndPoint definition:

  • host: Specifies the URL for the collection endpoint. The URL can use HTTP or HTTPS.

  • type: Optionally specifies the format of the stream. Supported values are:

    • json: Provides the stream in a JSON format

    • plaintext: Provides the stream in a plain text format

    The default value is json.

  • token: Optionally specifies the authentication token for the collection endpoint. Consult the metric collection platform for details about generating the token.

  • httpProxy or httpsProxy: Optionally specifies a proxy server to facilitate network connectivity to the collection endpoint. A proxy server is required if a firewall resides between the Exadata system and the collection endpoint.

You can use the optional += operator to add collection endpoints to an existing metricStreamEndPoint definition. Otherwise, the = operator overwrites the previous attribute value.

Metric Tags

The metricStreamTags attribute defines a set of metric tags, which are included in every metric observation generated by the server. These tags can help you to organize and group observations generated by numerous Exadata servers.

You can set the metricStreamTags attribute to a valid JSON string containing tag and value pairs as follows: 

metricStreamTags='{"tag1":"value1"[,"tag2":"value2"]...}'

For example:

DBMCLI> ALTER DBSERVER metricStreamTags='{"application":"personnel","department":"HR"}'

Parent topic: ALTER DBSERVER

9.7.1.3 ALTER IBPORT

Purpose

The ALTER IBPORT command performs an action on all InfiniBand Network Fabric ports, or specific ports.

Note:

This command does not work on Oracle Exadata servers with RoCE Network Fabric.

Syntax

ALTER IBPORT {ALL | ibport_name [, ibport_name] ...} RESET COUNTERS

Usage Notes

The RESET COUNTERS option resets all counters on the InfiniBand Network Fabric port.

Example 9-25 Altering IBPORT Attributes

This example shows the how to reset the IBPORT counters for all ports, or for a specific port. 

DBMCLI> ALTER IBPORT ALL RESET COUNTERS

         InfiniBand Port HCA-1:1 successfully altered.
         InfiniBand Port HCA-1:2 successfully altered.
 
DBMCLI> ALTER IBPORT "HCA-1:1" RESET COUNTERS

         InfiniBand Port HCA-1:1 successfully altered.

Parent topic: ALTER

9.7.1.4 ALTER METRICDEFINITION

Purpose

The ALTER METRICDEFINITION command controls the metrics that are included in the metric stream and in the fine-grained collection.

Syntax

ALTER METRICDEFINITION metric_name [, metric_name ]... attribute_name = attribute_value [, attribute_name = attribute_value]...
ALTER METRICDEFINITION attribute_name = attribute_value [, attribute_name = attribute_value]... attribute_filters

Usage Notes

  • In the command:

    • metric_name: Identifies a specific metric definition to alter.

    • attribute_filters: Identifies the metric definitions to alter by filtering according to attribute values.

    • attribute_name=attribute_value: Specifies an attribute setting:

      • The finegrained attribute controls whether the metric is enabled for fine-grained collection.

        Specify finegrained=enabled to enable the metric for fine-grained collection, or specify finegrained=disabled to disable fine-grained collection for the metric.

      • The streaming attribute controls whether the metric is included in the metric stream.

        Specify streaming=enabled to include the metric in the metric stream, or specify streaming=disabled to exclude the metric from the metric stream.

  • By default, a set of key performance metrics is automatically enabled for fine-grained collection and automatically included in the metric stream. However, you can customize the finegrained and streaming attributes independently. In other words, you can enable a metric for fine-grained collection without including it in the metric stream. Likewise, you can include a metric in the metric stream when it is not in the fine-grained collection.

  • To view the metrics enabled for fine-grained collection, use the LIST METRICDEFINITION command and examine the finegrained attribute value.

  • To view the metrics included in the metric stream, use the LIST METRICDEFINITION command and examine the streaming attribute value.

Example 9-26 Alter a Specific Metric Definition

This example shows the command to enable fine grained metric collection for the metric that shows the Ethernet network interface transfer rate (N_NIC_KB_TRANS_SEC). 

DBMCLI> ALTER METRICDEFINITION N_NIC_KB_TRANS_SEC finegrained=enabled

Example 9-27 Alter a List of Metric Definitions

This example shows the command to disable fine grained metric collection for a listed set of metrics.

DBMCLI> ALTER METRICDEFINITION N_MB_SENT,N_MB_RECEIVED finegrained=disabled

Example 9-28 Alter Metric Definitions Using a Filter

This example shows the command to include in the metric stream all of the metrics specified by the attribute filter.

DBMCLI> ALTER METRICDEFINITION streaming=enabled WHERE name LIKE 'N_NIC.*'
9.7.1.5 ALTER SOFTWAREUPDATE

Software updates can be scheduled for database servers by setting the SoftwareUpdate attributes starting with Oracle Exadata System Software release 19.3.0 or later.

Purpose

The ALTER SOFTWAREUPDATE command enables you to alter modifiable Software Update attributes, to validate the prerequisites for the software update, or to start the upgrade immediately.

You can also run the ALTER SOFTWAREUPDATE command using dcli or exacli.

Note:

Currently, database node rolling upgrade automation is not supported, so you must plan the upgrades to avoid service outage downtime.

Syntax

ALTER SOFTWAREUPDATE {VALIDATE PREREQ [FORCE] | UPGRADE [FORCE] | attribute = attribute value 
[,attribute = attribute value...]}

Options for the ALTER SOFTWAREUPDATE Command

  • VALIDATE PREREQ [FORCE]

    Run software update check prerequisite steps now. This will download the software update prerequisite code for the update specified by the store attribute. These checks are run automatically as part of update. Use this option only if you want to run prerequisite checks explicitly. Any error found will be displayed. A stateful alert will be raised if any error is found by the VALIDATE PREREQ command.

    If you include the FORCE option, then the dbnodeupdate command is run with the -modify_on_prereq option.

  • UPGRADE [FORCE]

    Run the software update (including the prerequisite steps) now, using the software location specified by the Software Update store attribute. Use this command if you want to perform the update now rather than wait for the time specified by the Software Update time attribute.

    If FORCE is specified, then the upgrade continues despite any prerequisite check errors.

  • attribute = attribute value

    Modify the specified Software Update attributes to the values provided.

Attributes for SOFTWAREUPDATE

The following attributes for the ALTER SOFTWAREUPDATE command are modifiable:

  • frequency: Database server updates can automatically be done periodically by setting the frequency attribute to the desired frequency. You can specify one of the following values: {none | daily | weekly | biweekly }. If the value specified for frequency is '' or none, then the scheduled update is only done once.

  • name: The name of the patch to use in the update, which includes the software version string such as 19.3.1.0.0.190918. The name can be an ARU-style file name containing the ISO file (for example, p28802069_193000 or p28802067_193000), or it can be the label-based name (for example, exadata_ovs_19.3.0.0.0.190913 or exadata_ol7_19.3.0.0.0.190913). After downloading these ISO zip files, the database server update software is automatically downloaded from the same store location.

    If name is not set (it has a value of unknown), then the latest version of the exadata_oxx_...zip patch will be selected from the store when UPGRADE or VALIDATE PREREQ is specified.

    If name is not set (it has a value of unknown), then when you use the ALTER SOFTWAREUPDATE UPGRADE or ALTER SOFTWAREUPDATE VALIDATE PREREQ command, the software store is checked and the name attribute is set automatically (if not already set) to the latest available version in the software store. If there are multiple software versions at the store site, then this attribute can be used to specify which version should be used.

  • store: A URL for the location of the software store.

    If you specify a network store location using the HTTP or HTTPS protocol:

    • The URL must be accessible using the management network or RDMA Network Fabric.

    • MS automatically finds and downloads the required software update files.

    • The local staging location for the downloaded software update files depends on the system configuration:

      • When Oracle Exadata Database Machine is configured without virtual machines (VMs) (otherwise known as a bare-metal configuration), the local staging location for the downloaded software update files is /u01/swupdate.

      • When Oracle Exadata Database Machine is configured with virtual machines (VMs), the local staging location for the downloaded software update files is:

        • /EXAVMIMAGES/swupdate inside the VM server (KVM host or Oracle VM management domain).

        • /u01/swupdate inside each VM (KVM guest or Oracle VM user domain).

    Alternatively, you can use the FILE protocol to specify a URL for a local store. When using a local store:

    • MS does not need to download the patch zip files or perform the associated space checks.

    • MS does not manage the local software store content. You must download the required patch files before patching and remove them afterward to free up space.

    • The file URL must use one of the following formats:

      • file:///localpath
      • file:/localpath

  • time: A future date and time at which the software update should be performed. The time can be specified as a local informal date and time, for example "1 AM, next Tuesday". If the date and time is valid then the output from setting this attribute shows the interpreted time in standard format with timezone offset, such as 2017-08-22T01:00:00-08:00.

    If you set this attribute to the empty string "", it cancels the scheduled software update.

  • timeLimitInMinutes: An update may wait for other database servers to complete their updates in order to preserve disk group redundancy. By default, there is no limit on the amount of time which can be spent waiting to update. This attribute may be set to a positive, maximum integer which represents the number of minutes a database server will spend waiting to update. If the update does not start within the time specified by the limit, then the update is canceled and an update alert is reported.

Usage Notes

  • Currently, only ISO file repository downloads are supported.
  • Software download and the prerequisite check will begin up to a week before the scheduled update time.
  • The update progress can be monitored by displaying the non-modifiable Software Update status attribute.
  • Software updates do not occur if the upgrade software is already installed.
  • You can use dcli or exacli to schedule and install updates using the ALTER SOFTWAREUPDATE command.

  • The Software Update feature supports using HTTPS transport for software downloads. When using HTTPS, TLS certificate checks are performed by default. If the remote server’s certificate cannot be validated then the following error is reported:

    CELL-00076: An error occurred during download of software update:
source https://hostname:port is not available.
CELL-00092: The store's TLS certificate cannot be authenticated with known CA certificates.

    This can happen if the remote server uses a self-signed certificate or if the remote server uses a certificate signed by a certificate authority (CA) that is not included in the database server’s CA store. You can use the following procedure to add a CA certificate to the database servers CA store. This is a security setup step which requires shell access as root on the database server.

    1. Get a CA certificate that can verify the remote server. The certificate should be stored in PEM or DER file format.
    2. Copy the file to the database server at this directory: /etc/pki/ca-trust/source/anchors/
    3. Run following commands:
      update-ca-trust enable
update-ca-trust extract

    Use man to get more information about the update-ca-trust command.

Examples

Example 9-29 Modifying the Software Update time Attribute

Modify the scheduled time of the next software update to 12:30 a.m. on December 27, 2019.

ALTER SOFTWAREUPDATE time="2019-12-27T00:30"

Example 9-30 Setting the Software Update store Attribute

This example shows how to set the store attribute to a location that uses HTTPS protocol.

ALTER SOFTWAREUPDATE store="https://my-exa-store/compute"

Example 9-31 Starting a Software Update Immediately

This example shows how to immediately start a software update using the attribute values already specified, after running a prerequisites check.

ALTER SOFTWAREUPDATE VALIDATE PREREQ

ALTER SOFTWAREUPDATE UPGRADE FORCE

Parent topic: ALTER

9.7.1.6 ALTER THRESHOLD

Purpose

The ALTER THRESHOLD command updates the attribute values of all thresholds or the specified thresholds.

Syntax

ALTER THRESHOLD { ALL |threshold_name [, threshold_name ...] }
   attribute_name = attribute_value 
   [, attribute_name = attribute_value]...

Usage Notes

The attributes that can be changed with the ALTER command are shown as modifiable in Example 9-53.

Examples

Example 9-32 shows how to alter threshold attributes.

Example 9-32 Altering Threshold Attributes

DBMCLI> ALTER THRESHOLD temp  warning=30

DBMCLI> ALTER THRESHOLD ALL occurrences=3

See Also:

"CREATE" for additional information about setting threshold attributes

Parent topic: ALTER

9.7.1.7 ALTER USER

Purpose

The ALTER USER command changes the attributes of a user.

Syntax

ALTER USER username attribute_name = attribute_value      \
[, attribute_name = attribute_value, ...]

Usage Notes

  • The username cannot be root, dbmadmin or dbmmonitor. Those are reserved.

  • The user name should be unique.

  • The system prompts for a password for the new user. The password must have 12 to 40 alphanumeric characters or special characters !@#$%^&*() with at least one digit, one lowercase letter, and one uppercase letter. Starting with Oracle Exadata System Software release 18.1.0.0.0, the password can be 8 to 40 characters in length and can also utilize the special characters - and _.

  • The new password cannot be the same as the current password for the user.

Example 9-33 Using the ALTER USER Command

DBMCLI> ALTER USER scott password=TOPsecret2345

Parent topic: ALTER

9.7.2 CREATE

Purpose

The CREATE command creates a new object and assigns initial attributes to the object.

Syntax

CREATE object_type [name] [attributename=attribute_value [, attributename=attribute_value]...]

Usage Notes

  • object_type can be as follows:

    • DBSERVER

    • DIAGPACK

    • ROLE

    • THRESHOLD

    • USER

  • name is the name of the new object.

  • attribute_value is the name of a modifiable attribute for the object_type.

  • attribute_value is the initial setting for the attribute.

  • When multiple objects are valid as the target of a CREATE command, there is the possibility of partial success. If an error occurs, then the command is interrupted, and the remaining objects are not created.

Related Topics

Parent topic: DBMCLI Command Reference

9.7.2.1 CREATE DBSERVER

Purpose

The CREATE DBSERVER command creates the DBSERVER object type.

Syntax

CREATE DBSERVER [name] 
    [interconnect1=intValue1 [, interconnect2=intValue2 ...]] 
    [ { , ipaddress1=ipValue1 [, ipaddress2=ipValue2 ...] }]
    [, attributeName = attributeValue ...]

Usage Notes

The attributes that can be set are shown as modifiable in DESCRIBE DBSERVER.

  • This command can be used to assign the ASR value to the snmpSubscriber attribute.

  • If a name is not provided, then the default is to set the database server name to the network host name of the server with hyphens in the network name replaced with underscores. You can display the network name with the uname -n command. If you change the database server name, then you must choose a unique database server name.

    If you provide a name, ensure that the name meets the guidelines.

  • One to four interconnects can be specified. The interconnect1 attribute must be specified if the interconnect2 attribute is specified. The interconnect1 and interconnect2 attributes must be specified if interconnect3 is specified, and so on.

  • If interconnectn and ipaddressn are specified, then an ipaddressn entry is automatically written to the /etc/oracle/cell/network-config/cellinit.ora file.

  • Interconnects use the RDMA Network Fabric (ibN or reN).

  • Starting with Oracle Exadata System Software release 19.1.0, the httpsAccess attribute can be used to specify a list of IP addresses or IP subnet masks that control who can access the RESTful service via HTTPs. The value you specify for httpsAccess overwrites any previous value. You can use the following values for httpsAccess:

    • ALL — to allow access to all hosts (Default)
    • NONE — to disable the HTTPs port completely
    • IP1, IP2,..., IPn — to only allow access to hosts with IP addresses IP1, IP2,..., IPn where IPn is a valid IP address in IPv4, IPv4 subnet, IPv6 or IPv4-embedded IPv6 format. You can specify a maximum of 512 IP addresses for the access control list.

    Additionally, instead of a single IP address, you can use the / character to specify a range of IP addresses using a subnet mask. For example the range '192.168.10.0/24' corresponds to hosts having IP addresses from 192.168.10.1 to 192.168.10.255. If you specify an IP address range, you need to enclose the IP address string in quotes.

Examples

Example 9-34 shows the CREATE DBSERVER command with the interconnectn attribute.

Example 9-35 shows how to create a DBSERVER object that restricts HTTPs access to the RESTful server to a set of hosts.

Example 9-34 Creating a DB Server and setting the interconnectn attribute for the DBSERVER object

For racks that use InfiniBand Network Fabric: 

DBMCLI> CREATE DBSERVER interconnect1=ib0, interconnect2=ib1

For racks that use RoCE Network Fabric: 

DBMCLI> CREATE DBSERVER interconnect1=re0, interconnect2=re1

Example 9-35 Creating a DBServer with Restricted HTTPs Access

This example shows how to create a DBSERVER object that allows HTTPs port access only from hosts having IP addresses in the range 192.168.10.1 to 192.168.10.255.

For racks that use InfiniBand Network Fabric: 

DBMCLI> CREATE DBSERVER interconnect1=ib0, httpsAccess="192.168.10.0/24"

For racks that use RoCE Network Fabric: 

DBMCLI> CREATE DBSERVER interconnect1=re0, httpsAccess="192.168.10.0/24"
9.7.2.2 CREATE DIAGPACK

Purpose

The CREATE DIAGPACK command creates a diagnostic package, which contains logs and traces that you can use to troubleshoot problems in your system. You can also send the package to Oracle Support, as needed.

Syntax

CREATE DIAGPACK packStartTime=time, [durationInHrs=duration]

or

CREATE DIAGPACK alertName=alertName

Usage Notes

When an alert occurs, a diagnostic package is created automatically. This package contains logs and traces related to the alert.

The CREATE DIAGPACK command enables you to generate diagnostic packages manually.

  • The packStartTime parameter specifies when to start collecting the logs and traces. The format of packStartTime is: 

    yyyy_MM_ddTHH_mm_ss

    For example: 2015_07_07T09_00_00

    You can also specify the keyword now for packStartTime. The packStartTime cannot be in the future and cannot be older than 7 days. The value of packStartTime is used as part of the name of the diagnostic package.

  • The durationInHrs parameter specifies the number of hours of logs and traces to include in the diagnostic package. Valid values are from 1 (default) to 6.

    Every diagnostic package includes logs 1 hour before and 1 hour after the packStartTime. For example, if you specify a time of 12_00_00, then logs will collected from 11_00_00 to 13_00_00, unless the end time is in the future.

  • The alertName parameter specifies the alert name for which to create the diagnostic package. You can run the LIST ALERTHISTORY command to view the alert names.

Name of Diagnostic Packages

The name of the diagnostic package is formed as follows:

hostname + packStartTime + unique package ID

For example: scaqab04adm08_2016_05_17T11_58_54_5_1.tar.bz2

For alerts, the name of the diagnostic package is formed as:

hostname + timestamp of when the package was created + alert ID

For example: scaqab04adm08_2016_05_17T11_58_54_5_1.tar.bz

Location of Diagnostic Packages

The location of the diagnostic packages is /opt/oracle/dbserver/dbms/deploy/log.

Status of Diagnostic Packages

You can run the LIST DIAGPACK command to get a list of diagnostic packages in your system, and their status.

Privileges Needed to Create, List, and Download Diagnostic Packages

Users need to be granted roles before they can download the diagnostic packages. Use DBMCLI to grant the following privileges to a role:

  • Privilege to create diagnostic packages:

    grant privilege CREATE ON DIAGPACK to ROLE role

  • Privilege to list diagnostic packages and check their status:

    grant privilege LIST ON DIAGPACK to ROLE role

  • Privilege to download diagnostic packages:

    grant privilege DOWNLOAD ON DIAGPACK to ROLE role

You can then grant the role to users. For example, if you named your role diagpack_role, the following command grants the role to the user fred. 

DBMCLI> GRANT ROLE diagpack_role TO USER fred

During deployment, Oracle Exadata Deployment Assistant (OEDA) creates an Exadata storage software user called CELLDIAG. You can use this user to connect to a cell remotely using ExaCLI or REST API. This user has privileges to create, list, and download diagnostic packages.

Downloading Diagnostic Packages

You can download diagnostic packages using any of the following methods. Note that you need the DOWNLOAD ON DIAGPACK privilege before you can download diagnostic packages.

  • Using the REST API

    • To download the diagnostic package by name, use the following URL, where hostname specifies the host name of the server and diagpackname specifies the name of the diagnostic package. The URL must point to the secure socket port, which is 7879 by default: 

      https://hostname:7879/diagpack/download?name=diagpackname

      If the user is not already logged in, the URL will prompt for a user name and password.

      Diagnostic packages can also be accessed at

      https://hostname:7879/diagpack

      For example:

      https://dbnode01.example.com:7879/diagpack

      The page then prompts the user to log in:

      User: fred
Password: *******

      Based on the user's privileges, various sections of this page could be hidden. The form to create a new diagpack will not be shown if the user does not have the CREATE ON DIAGPACK privilege. Similarly, the list of alerts and their diagnostic packages will not be shown if the user does not have the LIST ON DIAGPACK privilege.

      To download the diagnostic package by alert name, use the following URL, where hostname specifies the host name of the server and alertName specifies the alert name of the diagnostic package: 

      https://hostname:7879/diagpack/download?alert=alertName

      This is the same alert name that is used in AlertHistory. It looks like 1, 2, 3 for stateless alerts, and 1_1, 2_1, 3_1, 3_2 for stateful alerts.

  • Using the download ExaCLI command

    ExaCLI enables you to run CellCLI commands on storage nodes remotely from compute nodes. To run the download command, run the following commands on a compute node:

    1. Start up ExaCLI and connect to the cell containing the diagnostic pack. Use a command similar to the following where hostname specifies the host name of the cell: 

      exacli -l celladministrator -c hostname
Password=********

    2. Run the download command. Use a command similar to the following where name specifies the name of the diagnostic package to download, and destinationFolder specifies the directory where you want to save the downloaded diagnostic package: 

      exacli> download diagpack name destinationFolder

  • Getting the diagnostic package from the alert emails

    The alert emails include diagnostic packages for all alerts except INFO, CLEAR, and WARNING. Diagnostic packages are generated for critical alerts only.

Turning Off the Diagnostic Pack Attachment in Emails

To turn off the diagnostic pack attachment in emails, use the command alter dbserver diagPackEmailAttach=FALSE. The diagnostic packs are still generated and stored on the system. To download the diagnostic packs, see the section "Downloading Diagnostic Packages."

Examples

Example 9-36 Using "now" for packStartTime

This example creates a diagnostic package using NOW as the start time and the default duration of one hour.

The output is a single compressed file in the directory /opt/oracle/dbserver/dbms/deploy/log. 

DBMCLI> create diagpack packStartTime="now"
    Processing: dm01db01_diag_2015_07_08T17_53_58_1
    Use 'list diagPack' to check its status.

Example 9-37 Specifying a duration

This example creates 3 diagnostic packages under /opt/oracle/dbserver/dbms/deploy/log:

  • The first package has a start time of 2015_07_07T09_00_00.

  • The second package has a start time of 2015_07_07T10_00_00.

  • The third package has a start time of 2015_07_07T11_00_00. 

DBMCLI> create diagpack packStartTime="2015_07_07T09_00_00", durationInHrs=3
    Processing: dm01db01_diag_2015_07_07T09_00_00_1
    dm01db01_diag_2015_07_07T10_00_00_1 (In queue...)
    dm01db01_diag_2015_07_07T11_00_00_1 (In queue...)
    Use 'list diagPack' to check its status.
9.7.2.3 CREATE ROLE

Purpose

The CREATE ROLE command creates a role for a user accessing a database server.

Syntax

CREATE ROLE  role_name1 [, role_name2, ...]

Usage Notes

The role name should be unique.

Examples

Example 9-38 shows how to create a role.

Example 9-38 Creating a Role

DBMCLI> CREATE ROLE dbmonitor

Parent topic: CREATE

9.7.2.4 CREATE THRESHOLD

Purpose

The CREATE THRESHOLD command creates a threshold object that specifies the conditions for generation of a metric alert.

Syntax

CREATE THRESHOLD name attributename=value [, attributename=value]...

Usage Notes

The attributes that can be specified are comparison, critical, occurrences, observation, and warning.

  • The name argument is required. The name is comprised of a metric name and an object name with the format metricName.objectName, such as db_io_rq_sm_sec.db123 or ct_io_wt_rq.interactive.. Use the LIST METRICCURRENT metric command to display the available object name for metric. The object name is optional.

  • When a object name is not specified, then the threshold is applied to all metric objects for the given metric.

  • The comparison attribute is required with a condition value. The value must be '<', '<=', '=', '>=', or '>'.

  • The occurrences attribute specifies the number of consecutive measurements over the threshold value that trigger a state change.

    When specifying occurrences and observations, you need the specified number of consecutive occurrences of sample averages over the number of observations to cause an alert. For example, if the following five observations (observations=5) happen on a database server, then the average sample would be 10 because the number of consecutive occurrences (occurrences=2) had values of 5 and 15. 

    Observation 1: 0
Observation 2: 30
Observation 3: 0
Observation 4: 5
Observation 5: 15

  • The observation attribute is the number of measurements over which measured values are averaged.

  • A state change to the value set in warning or critical causes a stateful alert to be generated.

Example 9-39 Creating a Threshold

This example shows how to create a threshold.

DBMCLI> CREATE THRESHOLD temp comparison='>', critical=30

See Also:

Parent topic: CREATE

9.7.2.5 CREATE USER

Purpose

The CREATE USER command creates a user.

Syntax

CREATE USER name PASSWORD = *

Usage Notes

  • The user name should be unique.

  • The username cannot be root, dbmadmin or dbmmonitor. Those are reserved.

  • The system prompts for a password for the new user. The password must have 12 to 40 alphanumeric characters or special characters !@#$%^&*() with at least one digit, one lowercase letter, and one uppercase letter. Starting with Oracle Exadata System Software release 18.1.0.0.0, the password can be 8 to 40 characters in length and can also utilize the special characters - and _.

  • The new password cannot be the same as the current password for the user.

Example 9-40 Creating a User

DBMCLI> CREATE USER jdoe PASSWORD = *
password: 
Confirm password: password
User jdoe successfully created.

Parent topic: CREATE

9.7.3 DESCRIBE

Purpose

The DESCRIBE command displays a list of attributes for the object type that is provided as an argument. The tag modifiable indicates whether an attribute can be modified using the ALTER command.

Syntax

DESCRIBE object_type

Usage Notes

  • The object_type is one of the supported object types.

  • The list of attributes can be used as arguments in the LIST command.

  • DESCRIBE does not display all of the attributes for the objects.

Related Topics

Parent topic: DBMCLI Command Reference

9.7.3.1 DESCRIBE ALERTDEFINITION

Purpose

The DESCRIBE ALERTDEFINITION command displays a list of attributes for the ALERTDEFINITION object type.

Syntax

DESCRIBE ALERTDEFINITION

Usage Notes

Table 9-2 lists the attributes for the DESCRIBE ALERTDEFINITION command.

Table 9-2 DESCRIBE ALERTDEFINITION Attributes

Attribute Description

alertShortName

Abbreviated name for the alert. If the alert is based on a metric, then the short name is the same as the corresponding metric name attribute.

alertSource

Source of the alert, such as BMC or ADR.

alertType

Type of the alert. Values are stateful or stateless.

  • Stateful alerts are automatically cleared on transition to normal.

  • Stateless alerts are never cleared. You can change the alert by setting the examinedBy attribute.

description

Description for the alert.

metricName

Metric name if the alert is based on a metric.

name

Identifier for the alert.

Examples

Example 9-41 shows the DESCRIBE command with the ALERTDEFINITION object.

Example 9-41 Describing the ALERTDEFINITION Object

DBMCLI> DESCRIBE ALERTDEFINITION

         name
         alertShortName
         alertSource
         alertType
         description
         metricName

Parent topic: DESCRIBE

9.7.3.2 DESCRIBE ALERTHISTORY

Purpose

The DESCRIBE ALERTHISTORY command displays a list of attributes for the ALERTHISTORY object type.

Syntax

DESCRIBE ALERTHISTORY

Usage Notes

The following table lists the attributes for the DESCRIBE ALERTHISTORY command.

Table 9-3 DESCRIBE ALERTHISTORY Attributes

Attribute Description

alertAction

Recommended action to perform for this alert.

alertMessage

Brief explanation of the alert.

alertSequenceID

Unique sequence ID for the alert. When an alert changes its state, such as warning to critical or critical to clear, another occurrence of the alert is created with the same sequence number and a time stamp of the transition.

alertShortName

Abbreviated name for the alert. If the alert is based on a metric, then the short name is the same as the corresponding metric name attribute.

alertType

Type of the alert. Values are stateful or stateless.

  • Stateful alerts are automatically cleared on transition to normal.

  • Stateless alerts are never cleared. You can change the alert by setting the examinedBy attribute.

beginTime

Time stamp when an alert changes its state.

endTime

Time stamp for the end of the period when an alert changes its state.

examinedBy

Administrator who reviewed the alert.

failedMail

Intended e-mail recipient when a notification failed.

failedSNMP

Intended SNMP subscriber when a notification failed.

metricObjectName

Object, such as database server disk for which a metric threshold has caused an alert.

metricValue

Value of the metric that caused the alert.

name

Unique identifier for the alert.

notificationState

Number indicating progress in notifying subscribers to alert messages:

  • 0: never tried

  • 1: sent successfully

  • 2: retrying, up to 5 times

  • 3: 5 failed retries

sequenceBeginTime

Time stamp when an alert sequence ID is first created.

severity

Severity level. Values are clear, info, warning, or critical.

Examples

Example 9-42 shows the DESCRIBE command with the ALERTHISTORY object.

Example 9-42 Describing the ALERTHISTORY Object

DBMCLI> DESCRIBE ALERTHISTORY

         name
         alertAction
         alertMessage
         alertSequenceID
         alertShortName
         alertType
         beginTime
         endTime
         examinedBy              modifiable
         failedMail
         failedSNMP
         metricObjectName
         metricValue
         notificationState
         sequenceBeginTime
         severity

Related Topics

Parent topic: DESCRIBE

9.7.3.3 DESCRIBE DBSERVER

Purpose

The DESCRIBE DBSERVER command displays a list of attributes for the DBSERVER object type.

Syntax

DESCRIBE DBSERVER

Usage Notes

The following table lists the attributes for the DESCRIBE DBSERVER command.

Table 9-4 DESCRIBE DBSERVER Attributes

Attribute Description
accountLockInDays

Number of days after a password expires before a user account is locked.

bbuStatus

Status of hard disk controller battery-backed unit (BBU).

comment

User-supplied text string.

corecount

Number of CPU cores in the database server.

If expressed using the format n1/n2, then n1 is the number of currently enabled CPU cores and n2 is the total number of CPU cores in the database server.

cpuCount

Number of CPUs on the database server as reported by the operating system in /proc/cpuinfo and other utilities.

This value factors in hyperthreading, so will always be twice the value of corecount.

If expressed using the format n1/n2, then n1 is twice the number of currently enabled CPU cores and n2 is twice the total number of CPU cores in the database server.

diagHistoryDays

Number of days ADR files are retained. The default is 7 days.

diagPackEmailAttach

Whether a diagpack is included as an attachment in the alert email or not. The default is true.

diagPackUploadEnabled

Whether the auto diagpack upload feature is enabled or not. The default is true.

emailFormat

File format for email messages. The value can be HTML or text.

fanCount

Count of working fans and total fans, displayed as working/total.

fanStatus

Status of the fan. The value can be normal, warning, or critical.

httpsAccess

Control list of IP addresses for HTTPs port access to the Exadata RESTful Service

id

Global unique identifier (GUID) supplied by the hardware vendor.

interconnect1-4

Interconnect 1 to 4 for the database server. For example: bondeth0.

interconnectCount

Number of network interconnects.

ipaddress1-4

IP address 1 to 4 for the database server.

kernelVersion

Version of the host kernel software.

location

Physical location of the cell hardware supplied by the user.

locatorLEDStatus

Status of cell LOCATE LED. The value can be on or off.

mailServer

Fully qualified domain name of the email relay server used to send alert notifications. This attribute only requires specification in cases where DNS returns an unreachable or invalid mail exchange (MX) record for the email server specified in smtpToAddr.

makeModel

Make and model of the cell hardware supplied by the vendor.

metricCollection

Indicator for whether Management Server performs metric collection. Values are TRUE or FALSE. If set to FALSE, then all collection and alert mining is stopped. The default setting is TRUE.

metricHistoryDays

Number of days that regular metric history files are retained. The default is 7 days.

msVersion

Version of the management server.

name

Name of the database server.

notificationMethod

Notification method for alerts. The value should be mail, snmp, none, or both mail and snmp.

notificationPolicy

Indicator for severity alerts to be sent to subscribers. The value for notificationPolicy should be none or any combination of critical, warning, and clear.

powerCount

Count of power supplies, displayed as working/total.

powerStatus

Status of the power. The value can be normal, warning, or critical.

pwdExpInDays

The number of days before a user's password expires.

pwdExpWarnInDays

The number of days before a user's password expires that a warning message is issued during login attempts.

releaseImageStatus

Indicator for knowing whether imaging is successful or not.

releaseTrackingBug

Patch number for the cell software, such as 11223344.

releaseVersion

Release number for the cell software, such as 11.2.2.3.0.

remotePwdChangeAllowed

Whether or not a user password can be changed remotely through REST services.

rescuePlan

A list of commands that you can run after a server rescue to restore settings, such as thresholds and notifications, to the last known values.

smtpFrom

User name that appears in the From: header of the alert notifications.

smtpFromAddr

Email address that appears in the From: header of the alert notifications. This email address is not authenticated with the email server.

smtpPort

Email server port used to send alert notifications.

smtpSubscriber

List of hosts that subscribe to the SNMP alert notifications.

smtpToAddr

Address to which email is sent. It can be a comma-delimited list in quotation marks to allow multiple subscribers to alerts.

smtpUseSSL

Specification to use Secure Socket Layer (SSL) encryption for alert notifications.

status

Status of the database server.

syslogConf

Rules for the system logging utility syslogd.

temperatureReading

Current temperature (Celsius) of the cell obtained from the BMC.

temperatureStatus

Status of the temperature. The value can be normal, warning, or critical.

traceLevel

Level for which trace messages are written. This can be a valid Java logging level (SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST) or a valid Oracle Diagnostic Logging (ODL) logging level (INCIDENT_ERROR:1, ERROR:1, WARNING:1, NOTIFICATION:1, NOTIFICATION:16, TRACE:1, TRACE:16, TRACE:32). The default is FINE.

upTime

Time (days, hours:minutes) since the system was restarted.

Examples

Example 9-43 Describing the DBSERVER Object

DBMCLI> DESCRIBE DBSERVER

	name                   modifiable
	bbuStatus
	comment                modifiable
	coreCount
	cpuCount
	diagHistoryDays        modifiable
	diagPackEmailAttach    modifiable
	diagPackUploadEnabled  modifiable
	emailFormat            modifiable
	emailSubscriber        modifiable
	fanCount
	fanStatus
	httpsAccess            modifiable
	iaasIdleInUse          modifiable
	iaasMode               modifiable
	iaasReason             modifiable
	id
	interconnectCount
	interconnect1          modifiable
	interconnect2          modifiable
	interconnect3          modifiable
	interconnect4          modifiable
	interconnect5          modifiable
	interconnect6          modifiable
	interconnect7          modifiable
	interconnect8          modifiable
	ipaddress1
	ipaddress2
	ipaddress3
	ipaddress4
	ipaddress5
	ipaddress6
	ipaddress7
	ipaddress8
	kernelVersion
	locatorLEDStatus
	location               modifiable
	mailServer             modifiable
	makeModel
	metricCollection       modifiable
	metricHistoryDays      modifiable
	msVersion
	notificationMethod     modifiable
	notificationPolicy     modifiable
	pendingCoreCount       modifiable
	powerCount
	powerStatus
	releaseImageStatus
	releaseVersion
	releaseTrackingBug
	securityCert           modifiable
	smtpFrom               modifiable
	smtpFromAddr           modifiable
	smtpPort               modifiable
	smtpToAddr             modifiable
	smtpUseSSL             modifiable
	snmpSubscriber         modifiable
	snmpUser               modifiable
	status
	syslogConf             modifiable
	temperatureReading
	temperatureStatus
	traceLevel             modifiable
	upTime
	msStatus
	rsStatus

Parent topic: DESCRIBE

9.7.3.4 DESCRIBE IBPORT

Purpose

The DESCRIBE IBPORT command displays a list of attributes for the IBPORT object type.

Note:

This command does not work on Oracle Exadata servers with RoCE Network Fabric.

Syntax

DESCRIBE IBPORT

Usage Notes

Table 9-5 DESCRIBE IBPORT Attributes

Attribute Description

activeSlave

Indicator whether the port is currently the active port for the bonded IP.

dataRate

The data rate of the InfiniBand Network Fabric port.

hcaFWVersion

The version of the host channel adapter firmware.

id

The Global unique identifier (GUID) of the InfiniBand Network Fabric port.

lid

The local identifier of the InfiniBand Network Fabric port. It is unique within the subnet, and the 16-bit identifiers are used within a network by switches for routing.

linkDowned

The number of times the port training state machine has failed the link error recovery process, and halted the link.

linkIntegrityErrs

The number of link integrity errors.

linkRecovers

The number of times the port training state machine has successfully completed the link error recovery process.

name

The name of the InfiniBand Network Fabric port.

physLinkState

The physical link state.

portNumber

The port number of the InfiniBand Network Fabric port.

rcvConstraintErrs

The number of received constraint errors experienced by the InfiniBand Network Fabric port.

rcvData

The number of 32-bit data words received by the InfiniBand Network Fabric port.

rcvErrs

The number of packets received at the InfiniBand Network Fabric port containing an error.

rcvRemotePhysErrs

The number of physical errors experienced at the InfiniBand Network Fabric port.

status

The link status.

symbolErrs

The number of minor link errors experienced at the InfiniBand Network Fabric port.

vl15Dropped

The number of incoming VL15 packets dropped at the InfiniBand Network Fabric port due to resource limitations, such as lack of buffers.

xmtConstraintErrs

The number of transmitted constraint errors experienced at the InfiniBand Network Fabric port.

xmtData

The number of 32-bit data words transmitted on the InfiniBand Network Fabric port.

xmtDiscards

The number of outbound packets discarded by the InfiniBand Network Fabric port because the port was down or congested.

Example 9-44 Describing the IBPORT Object

This example shows the possible output for the DESCRIBE IBPORT command. 

DBMCLI> DESCRIBE IBPORT

        name
        activeSlave
        dataRate
        hcaFWVersion
        id
        lid
        linkDowned
        linkIntegrityErrs
        linkRecovers
        physLinkState
        portNumber
        rcvConstraintErrs
        rcvData
        rcvErrs
        rcvRemotePhysErrs
        status
        symbolErrs
        vl15Dropped
        xmtConstraintErrs
        xmtData
        xmtDiscards

Parent topic: DESCRIBE

9.7.3.5 DESCRIBE LUN

Purpose

The DESCRIBE LUN command displays a list of attributes for the LUN object type.

Syntax

DESCRIBE LUN

Usage Notes

Table 9-6 DESCRIBE LUN Attributes

Attribute Description

deviceName

Operating system device name for the LUN. For example, /dev/c1d5

diskType

The type of disk.

errorCount

Number of errors on this LUN.

id

Identifier assigned by the system.

lunSize

Raw size of the LUN before being converted to a database server disk.

lunUID

Unique identifier assigned by the system.

name

Unique name assigned to the LUN. This might be different (or extended from) the LUN ID if the ID is not unique.

overProvisioning

Indicator of the percentage of over-provisioned blocks in flash storage that are still available for a particular LUN. This attribute is only used for flash disks.

raidLevel

Value of the RAID level that is used on the LUN. For example: RAID 0.

status

Status of the LUN, which can be normal, warning, or critical.

Example 9-45 Describing the LUN Object

This example shows the DESCRIBE command with the LUN object. 

DBMCLI> DESCRIBE LUN

         name
         deviceName
         diskType
         errorCount
         id
         lunSize
         lunUID
         overProvisioning
         raidLevel
         status

Parent topic: DESCRIBE

9.7.3.6 DESCRIBE METRICCURRENT

Purpose

The DESCRIBE METRICCURRENT command displays a list of attributes for the METRICCURRENT object type.

Syntax

DESCRIBE METRICCURRENT

Usage Notes

Table 9-7 DESCRIBE METRICCURRENT Attributes

Attribute Description

alertState

Indicator of the alert state. Values are normal, warning, or critical.

collectionTime

Time stamp when the metric value was collected.

metricObjectName

Name of the object, such as database server being measured.

metricType

Specification for how the statistic was created or defined.

metricValue

Value of the metric when it was collected.

name

Unique name of the current metric.

objectType

Options are DBSERVER, DBSERVER_FILESYSTEM, and IBPORT.

Example 9-46 Describing the METRICCURRENT Object

This example shows the DESCRIBE command with the METRICCURRENT object. 

DBMCLI> DESCRIBE METRICCURRENT

         name
         alertState
         collectionTime
         metricObjectName
         metricType
         metricValue
         objectType

Related Topics

Parent topic: DESCRIBE

9.7.3.7 DESCRIBE METRICDEFINITION

Purpose

The DESCRIBE METRICDEFINITION command displays a list of attributes for the METRICDEFINITION object type.

Syntax

DESCRIBE METRICDEFINITION

Usage Notes

Table 9-8 lists the attributes for the DESCRIBE METRICDEFINITION command.

Table 9-8 DESCRIBE METRICDEFINITION Attributes

Attribute Description

description

Description of the metric.

metricType

Indicator of how the statistic was created or defined. The options are as follows:

  • cumulative: Cumulative statistics since the metric was created.

  • instantaneous: Value at the time that the metric is collected.

  • rate: Rates computed by averaging statistics over observation periods.

  • transition: Transition metrics are collected at the time their value has changed and typically capture important transitions in hardware status.

name

Unique name of the metric definition. The value of the name attribute is a composite of abbreviations. The attribute value starts with an abbreviation of the object type on which the metric is defined:

  • DS_ (database server)

  • N_ (network)

objectType

Options are DBSERVER, DBSERVER_FILESYSTEM, and IBPORT.

persistencePolicy

Amount of time metric values are stored.

unit

Unit for the metric explicitly, and is related to the metric collected:

  • Number

  • % (percentage)

  • F (Fahrenheit)

  • C (Celsius)

Example 9-47 Describing the METRICDEFINITION Object

This example shows the DESCRIBE command with the METRICDEFINITION object. 

DBMCLI> DESCRIBE METRICDEFINITION

         name
         description
         metricType
         objectType
         persistencePolicy
         unit

Parent topic: DESCRIBE

9.7.3.8 DESCRIBE METRICHISTORY

Purpose

The DESCRIBE METRICHISTORY command displays a list of attributes for the METRICHISTORY object type.

Syntax

DESCRIBE METRICHISTORY

Usage Notes

Table 9-9 lists the attributes for the DESCRIBE METRICHISTORY command.

Table 9-9 DESCRIBE METRICHISTORY Attributes

Attribute Description

alertState

Indicator of the alert state. Values are normal, warning, or critical.

collectionTime

Time stamp when the metric value was collected.

memory

The metrics in Management Server memory. This attribute can be used instead of the collectionTime attribute when the collection time is less than an hour.

metricObjectName

Name of the object, such as database server disk being measured.

metricType

Specification for how the statistic was created or defined.

metricValue

Value of the metric when it was collected.

metricValueAvg

Average value of the metric.

metricValueMax

Maximum value of the metric.

metricValueMin

Minimum value of the metric.

name

Unique name of the current metric.

objectType

Options are DBSERVER, DBSERVER_FILESYSTEM, and IBPORT

over

Specification for amount of time in minutes for the aggregation. This attribute works in conjunction with the max, min and avg keywords.

Example 9-48 Describing the METRICHISTORY Object

This example shows the DESCRIBE command with the METRICHISTORY object. 

DBMCLI> DESCRIBE METRICHISTORY

         name
         alertState
         collectionTime
         memory
         metricObjectName
         metricType
         metricValue
         metricValueAvg
         metricValueMax
         metricValueMin
         objectType
         over

Parent topic: DESCRIBE

9.7.3.9 DESCRIBE PHYSICALDISK

Purpose

The DESCRIBE PHYSICALDISK command displays a list of attributes for the PHYSICALDISK object type.

Syntax

DESCRIBE PHYSICALDISK

Usage Notes

The following table lists the attributes for the DESCRIBE PHYSICALDISK command.

Table 9-10 DESCRIBE PHYSICALDISK Attributes

Attribute Description

ctrlHwVersion

Controller version. This attribute is only applicable to Oracle Exadata System Software on HP Oracle Database Machine.

diskType

Type of the disk, whether it is a HARDDISK or a FLASHDISK.

enclosureDeviceId

Identifier for the hard disk enclosure. This attribute is only applicable to Oracle Exadata System Software on Oracle Exadata Storage Server.

errCmdTimeoutCount

Count of the number of command timeout SCSI errors on the disk. This attribute is only applicable to Oracle Exadata System Software on HP Oracle Database Machine.

errHardReadCount

Count of the number of hard read errors on the disk. This attribute is only applicable to Oracle Exadata System Software on HP Oracle Database Machine.

errHardWriteCount

Count of the number of hard write errors on the disk. This attribute is only applicable to Oracle Exadata System Software on HP Oracle Database Machine.

errMediaCount

Count of the number of media errors on the hard disk. This attribute is only applicable to Oracle Exadata System Software on Oracle Exadata Storage Server.

errOtherCount

Count of unclassified errors on the hard disk. This attribute is only applicable to Oracle Exadata System Software on HP Oracle Database Machine.

errSeekCount

Count of the number of SCSI seek errors on the disk. This attribute is only applicable to Oracle Exadata System Software on HP Oracle Database Machine.

hotPlugCount

Count of the times the disk has been inserted into the rack. This attribute is only applicable to Oracle Exadata System Software on HP Oracle Database Machine.

lastFailureReason

Type of the most-recent error on the disk. This attribute is only applicable to Oracle Exadata System Software on HP Oracle Database Machine.

luns

List of LUNs converted from this disk.

makeModel

Model description provided by the system.

name

Unique name of the physical disk.

physicalFirmware

System-assigned name of the firmware for the disk. This attribute is only applicable to Oracle Exadata System Software on HP Oracle Database Machine.

physicalInsertTime

Time that the disk was inserted.

physicalInterface

Interface type used by the hard disk. For example, SAS

physicalPort

Port on the controller for this disk. This attribute is only applicable to Oracle Exadata System Software on HP Oracle Database Machine.

physicalRPM

Disk revolutions per minute. This attribute is only applicable to Oracle Exadata System Software on HP Oracle Database Machine.

physicalSerial

System-assigned unique ID.

physicalSize

Size of the disk in bytes.

physicalUseType

Intended use of the disk. For example, Data Drive.

sectorRemapCount

Count of all sector remap operations for the physical disk. This attribute is only applicable to Oracle Exadata System Software on HP Oracle Database Machine.

slotNumber

Physical location of disk.

status

Status of the physical disk. Values can be as follows:

  • failed: disk has failed. In earlier releases, this status was called critical.

  • normal: disk is functioning normally

  • not present: disk has been removed

  • peer failure: flash disk failure only

  • poor performance: disk is performing poorly

  • predictive failure: disk is expected to fail

  • write-through caching: flash disk caching only.

Example 9-49 Describing the PHYSICALDISK Object on a Hard Drive in a Database Server

This example shows the DESCRIBE command with the PHYSICALDISK object on Oracle Exadata Storage Server. 

DBMCLI> DESCRIBE PHYSICALDISK

         name
         ctrlFirmware
         diskType
         enclosureDeviceId
         errMediaCount
         errOtherCount
         luns
         makeModel
         physicalFirmware
         physicalInsertTime
         physicalInterface
         physicalSerial
         physicalSize
         slotNumber
         status

Parent topic: DESCRIBE

9.7.3.10 DESCRIBE ROLE

Purpose

The DESCRIBE ROLE command displays a list of attributes for the ROLE object type.

Syntax

DESCRIBE ROLE

Usage Notes

Table 9-11 DESCRIBE ROLE Attributes

Attribute Description

name

Unique name of the user assigned the role.

privileges

Privileges granted to the role.

Examples

Example 9-50 Describing the ROLE Object

This example shows the DESCRIBE command with the ROLE object. 

DBMCLI> DESCRIBE ROLE
        name
        privileges

Parent topic: DESCRIBE

9.7.3.11 DESCRIBE SOFTWAREHISTORY

Purpose

The DESCRIBE SOFTWAREHISTORY command displays a list of attributes for the ALERTHISTORY object type.

Syntax

DESCRIBE SOFTWAREHISTORY

Usage Notes

The attributes for the DESCRIBE SOFTWAREHISTORY command can include the following:

  • name: The name of the software update

  • status: The status of the software update

Example 9-51 Describing the SOFTWAREHISTORY Object

CellCLI> DESCRIBE SOFTWAREHISTORY
        name
        status

Parent topic: DESCRIBE

9.7.3.12 DESCRIBE SOFTWAREUPDATE

Purpose

The DESCRIBE SOFTWAREUPDATE command displays a list of attributes for the SOFTWAREUPDATE object type.

Syntax

DESCRIBE SOFTWAREUPDATE

Usage Notes

The attributes for the DESCRIBE SOFTWAREUPDATE command can include the following:

  • frequency: The time period in which this software update is performed automatically. The value can be none, daily, weekly, or biweekly. The value none is available in Oracle Exadata System Software release 19.1.0 or later.
  • name: The name of the patch to use in the update, or unknown. If the name defaults to unknown, then when the software update is performed, the most recent patch is chosen for the upgrade.
  • status: The status of this software update.
  • store: The URL for the location of the software update file
  • time: The specified date and time at which the software update should be performed
  • timeLimitInMinutes: The number of minutes a cell will spend waiting to update the software before canceling and issuing an alert.

Example 9-52 Describing the SOFTWAREUPDATE Object

CellCLI> DESCRIBE SOFTWAREUPDATE
        name                   modifiable
        status
        store                  modifiable
        time                   modifiable
        timeLimitInMinutes     modifiable

Parent topic: DESCRIBE

9.7.3.13 DESCRIBE THRESHOLD

Purpose

The DESCRIBE THRESHOLD command displays a list of attributes for the THRESHOLD object type.

Syntax

DESCRIBE THRESHOLD

Usage Notes

Table 9-12 lists the attributes for the DESCRIBE THRESHOLD command.

Table 9-12 DESCRIBE THRESHOLD Attributes

Attribute Description

comparison

Operator for comparing the metric value to the threshold value (>, >=, =, <, <=) to determine whether the value violates the threshold.

critical

Limit beyond which the metric value is considered to be in the critical state for generating alerts.

name

Unique name of the threshold.

observation

Number of measurements over which the rate metric is averaged before being compared with the threshold value.

occurrences

Number of consecutive violations of the threshold limit by the metric value before the appropriate alert is issued.

warning

Limit beyond which the metric value is considered to be in the warning state for generating alerts.

Example 9-53 Describing the THRESHOLD Object

This example shows the DESCRIBE command with the THRESHOLD object. 

DBMCLI> DESCRIBE THRESHOLD

         name
         comparison              modifiable
         critical                modifiable
         observation             modifiable
         occurrences             modifiable
         warning                 modifiable

Parent topic: DESCRIBE

9.7.3.14 DESCRIBE USER

Purpose

The DESCRIBE USER command displays a list of attributes for the USER object type.

Syntax

DESCRIBE USER

Usage Notes

The following table lists the attributes for the DESCRIBE USER command.

Table 9-13 DESCRIBE USER Attributes

Attribute Description

name

Unique name of the user.

roles

Roles assigned to the user.

Example 9-54 Describing the USER Object

This example shows the DESCRIBE command with the USER object. 

DBMCLI> DESCRIBE USER

         name
         roles

Parent topic: DESCRIBE

9.7.4 DROP

Purpose

The DROP command removes the named objects from the database server or resets a database server.

Syntax

DROP object_type [object_name [, object_name]...] [options]

Usage Notes

  • object_type can be one of the following:

    • ALERTHISTORY

    • DBSERVER

    • ROLE

    • THRESHOLD

    • USER

  • object_name is the name of a database server disk, role, threshold, or user.

  • When multiple objects are the target of a DROP command, there is the possibility of partial success. If an error occurs, then the command is interrupted, and the remaining objects are not dropped.

Related Topics

Parent topic: DBMCLI Command Reference

9.7.4.1 DROP ALERTHISTORY

Purpose

The DROP ALERTHISTORY command removes alerts from the alert history of a database server.

Syntax

DROP ALERTHISTORY {ALL | alert1 {, alert2}, ...}

Usage Notes

  • In the command, alertN is the name of the alert to be dropped from the history.

  • When dropping stateful alerts, you must drop all members of the alert sequence at the same time. If you do not drop all members, then an error is issued by the system.

Example 9-55 Dropping a Database Server Alert History

DBMCLI> DROP ALERTHISTORY 1, 2_1, 2_2

Parent topic: DROP

9.7.4.2 DROP DBSERVER

Purpose

The DROP DBSERVER command resets MS on the database server to its original state.

Syntax

DROP DBSERVER

Usage Notes

  • Any thresholds that were set for the database server are also dropped for the database server.

  • The DBSERVER attributes are set to their default values.

Example 9-56 Dropping a Database Server

DBMCLI> DROP DBSERVER

Parent topic: DROP

9.7.4.3 DROP ROLE

Purpose

The DROP ROLE command removes user roles from the cell.

Syntax

DROP ROLE  { ALL | role_name1 [, role_name2, ...]} [FORCE]

Usage Notes

The FORCE option drops the role even if the role has been granted to a user.

Example 9-57 Dropping a Role

DBMCLI> DROP ROLE r1,r2

Parent topic: DROP

9.7.4.4 DROP SOFTWAREHISTORY

Purpose

The DROP SOFTWAREHISTORY command removes all history or individual update history.

Syntax

DROP SOFTWAREHISTORY { ALL | 'update_name[,update_name...]'}

Example 9-58 Dropping the History of Scheduled Software Updates

CellCLI> DROP SOFTWAREHISTORY '12.2.1.2.0.170509,12.2.1.2.0.17052'

CellCLI> DROP SOFTWAREHISTORY ALL

Parent topic: DROP

9.7.4.5 DROP THRESHOLD

Purpose

The DROP THRESHOLD command removes all or the specified thresholds from the database server.

Syntax

DROP THRESHOLD { ALL |threshold_name [, threshold_name ...] }

Example 9-59 Dropping Thresholds

DBMCLI> DROP THRESHOLD temp

Parent topic: DROP

9.7.4.6 DROP USER

Purpose

The DROP USER command removes a user from a database server.

Syntax

DROP USER { ALL | user1 [, user2]... }

Usage Notes

  • user(n) is the name of a user to drop.

Example 9-60 Dropping a User

DBMCLI>DROP USER jdoe

Parent topic: DROP

9.7.5 GRANT

Purpose

The GRANT command sets attributes for privileges and roles.

Syntax

GRANT object_type [name] TO sub_object_type [sub_object_name]

Usage Notes

  • object_type can be as follows:

    • PRIVILEGE
    • ROLE

  • The following values can be used for PRIVILEGE object type:

    • name is in the following format: 

      { ALL ACTIONS | action } ON { ALL OBJECTS | object }               \
[{ ALL ATTRIBUTES | ATTRIBUTES attribute1 [, attribute2, ...] }]   \
[{ WITH ALL OPTIONS | WITH OPTIONS option1 [, option2, ...] }]

    • The sub_object_type must be ROLE.

    • The sub_object_name is the name of the role.

  • The following can be used for the ROLE object type:

    • name is the role name.

    • The sub_object_type must be USER.

    • The sub_object_name is the name of the user.

Parent topic: DBMCLI Command Reference

9.7.5.1 GRANT PRIVILEGE

Purpose

The GRANT PRIVILEGE command sets the access privileges for a role.

Syntax

GRANT PRIVILEGE { ALL ACTIONS | action } ON { ALL OBJECTS | object }   \
{ ALL ATTRIBUTES | ATTRIBUTES attribute1 [, attribute2, ...] }         \
{ WITH ALL OPTIONS | WITH OPTIONS option1 [, option2, ...] }           \
TO ROLE { ALL | role1 [, role2, ...] }

Usage Notes

  • action is the command. Examples: ALTER, CREATE, DESCRIBE, DROP, EXPORT, IMPORT, LIST.

    Notes:

    • The GRANT and REVOKE commands cannot be granted.

    • CREATE USER and DROP USER cannot be granted.

    • CREATE ROLE and DROP ROLE cannot be granted.

  • object is object type for the action. It can be any DBMCLI object. Examples: DBSERVER, THRESHOLD, PHYSICALDISK, ALERTHISTORY, ROLE.

  • attribute are the attributes for the object. To get a list of attributes for an object, run the LIST object_type command.

  • option are the options for the object. Examples: DETAIL, LIMIT, ORDER BY, WHERE.

  • role is the name of the role to grant privileges.

  • The ALL ACTIONS argument grants privileges for all actions.

  • The ALL OBJECTS argument grants privileges for all objects.

  • The ALL ATTRIBUTES argument grants privileges for all attributes.

  • The WITH ALL OPTIONS argument grants privileges for all options.

  • Specifying attributes and WITH OPTIONS is optional. If they are not specified, then all attributes and options are granted with the privilege.

Examples

Example 9-61 Granting Privileges to a Role

This example shows how to grant privileges to a role.

DBMCLI> GRANT PRIVILEGE list on alerthistory ATTRIBUTES alertAction,alertMessage  \
        WITH OPTIONS detail TO ROLE dbmonitor

Example 9-62 Granting All Attributes and Options to a Role

This example shows how to grant all attributes and options for a specified action and object to a role.

DBMCLI> GRANT PRIVILEGE { ALL ACTIONS | action } ON { ALL OBJECTS | object } to ROLE role1

Example 9-63 Granting All Options with Specified Action, Object and Attributes

This example shows how to grant all options with a specified action, object and attributes to a role.

DBMCLI> GRANT PRIVILEGE { ALL ACTIONS | action } ON { ALL OBJECTS | object }  \
ATTRIBUTES attribute1 [, attribute2, ...] to ROLE role1

Example 9-64 Granting All Attributes with Specified Action, Object and Options

This example shows how to grant all attributes with a specified action, object, and options to a role.

DBMCLI> GRANT PRIVILEGE { ALL ACTIONS | action } ON { ALL OBJECTS | object }   \
WITH OPTIONS option1 [, option, ...] to ROLE role1

Parent topic: GRANT

9.7.5.2 GRANT ROLE

Purpose

The GRANT ROLE command sets the role for a user.

Syntax

GRANT ROLE { ALL | role1 [, role2, ...] } TO USER { ALL | user1 [, user2...] }

Usage Notes

  • role is the name of the role.

  • The ALL argument grants all roles to the user.

  • The TO USER ALL argument grants the role to all users.

Example 9-65 Granting a Role to a User

This example shows how to grant a role to a user.

DBMCLI> GRANT ROLE dbmonitor TO USER agarcia

Parent topic: GRANT

9.7.6 HELP

Purpose

The HELP command displays syntax and usage descriptions for all DBMCLI commands.

Syntax

HELP [help_topic]

If no topic argument is provided, HELP displays the name of all available topics. If a topic is specified, then detailed help text is displayed for that topic.

Example 9-66 shows examples of the HELP command.

Example 9-66 Display Help Text with the HELP Command

DBMCLI> HELP
DBMCLI> HELP ALTER
DBMCLI> HELP DROP ALERTHISTORY

Parent topic: DBMCLI Command Reference

9.7.7 LIST

Purpose

The LIST command displays attributes for database server objects. Objects displayed are identified by name or by filters. The attributes displayed for each object are determined by the specified attribute list.

Syntax

LIST object_type  [ name |  attribute_filters] [attribute_list] 
[DETAIL] [ORDER BY order_by_attribute_list] [LIMIT integer]

Usage Notes

  • object_type can be the following:

    • ALERTDEFINITION
    • ALERTHISTORY
    • DBSERVER
    • IBPORT (not available in user domain (domU) environments)
    • LUN (not available in user domain (domU) environments)
    • METRICCURRRENT
    • METRICDEFINITION
    • METRICHISTORY
    • PHYSICALDISK (not available in user domain (domU) environments)
    • ROLE
    • THRESHOLD
    • USER

  • Using LIST with only an object_type (without the DETAIL option or an attribute list) displays the names of the existing objects of this type and a default list of attributes.

    • For an object type that has a status attribute, the object name and the status are displayed.
    • For the METRICHISTORY object type, the collection time, the object name, and value are displayed.
    • For the PHYSICALDISK and LUN object types, the ID attribute is displayed.
    • For the ALERTHISTORY object type, the time and alert message are displayed.
    • For the KEY object type, the key value is displayed.

  • The attributes displayed for each object are determined by the specified attribute list. Attribute values that are strings with embedded blank spaces or tabs must be enclosed in quotation marks.

  • Attribute filters determine the specific objects that are displayed. Because of the amount of metrics, you should use filters when using the LIST METRICCURRENT or LIST METRICHISTORY commands to narrow the output of the command.

  • In the default format without the DETAIL option, each object is displayed on a separate line, with successive attribute values separated by tabs in the order of the specified list of attributes.

  • In the DETAIL format, each attribute of a specific object is displayed on a separate line, with an attribute name followed by its value. If no attribute list is provided, then all attributes that have values are displayed. Blank lines separate each object in the display. DETAIL is similar to the ATTRIBUTES ALL option, only the format is different.

  • Attributes that are not set are not listed with the DETAIL option. However, attributes that are set to an empty value are listed with the DETAIL option.

  • ORDER BY orders the objects by attributes in ascending or descending order. The default is ascending.

  • LIMIT sets a limit on the number of objects to display.

Related Topics

Parent topic: DBMCLI Command Reference

9.7.7.1 LIST ALERTDEFINITION

Purpose

The LIST ALERTDEFINITION command displays all available sources of the alerts on the database server.

Syntax

LIST ALERTDEFINITION [ name |  attribute_filters ]  [attribute_list]  [DETAIL]

Usage Notes

The list of attributes that can be displayed is shown in Example 9-41.

Examples

Example 9-67 shows the LIST command with the ALERTDEFINITION object.

Example 9-67 Listing ALERTDEFINITION Attributes

DBMCLI> LIST ALERTDEFINITION HardwareAlert DETAIL
         name:                   HardwareAlert
         alertShortName:         Hardware
         alertSource:            Hardware
         alertType:              Stateless
         description:            "Hardware Alert"
         metricName:

Parent topic: LIST

9.7.7.2 LIST ALERTHISTORY

Purpose

The LIST ALERTHISTORY command displays all alerts that occurred on the database server.

Syntax

LIST ALERTHISTORY [ name |  attribute_filters ]  [attribute_list]  [DETAIL]

Usage Notes

  • You can use the DESCRIBE ALERTHISTORY command to view the complete list of ALERTHISTORY attributes.

  • A WHERE clause can include the ageInMInutes attribute to specify the list is limited to those alerts which have the specified age. For example, the following command would show the alerts created in the previous 15 minutes: 

    DBMCLI> LIST ALERTHISTORY WHERE ageInMinutes < 15

Examples

Example 9-68 shows the LIST command with the ALERTHISTORY object.

Example 9-68 Listing ALERTHISTORY Attributes

DBMCLI> LIST ALERTHISTORY 1_1 DETAIL
        name:                   1_1
        alertDescription:       "Data hard disk of size 300GB in slot 3 entered
                                 predictive failure status"
        alertMessage:           "Data hard disk entered predictive failure status.
                                 Status        : WARNING - PREDICTIVE FAILURE 
                                 Manufacturer  : HITACHI  Model
                                 Number  : H103030SCSUN300G  Size          : 300GB 
                                 Serial Number : 1026GZKMDE 
                                 Firmware      : A2A8  Slot Number   : 3"
        alertSequenceID:        1
        alertShortName:         Hardware
        alertType:              Stateful
        beginTime:              2014-09-22T20:18:23-05:00
        examinedBy:            
        metricObjectName:       252:3
        notificationState:      0
        sequenceBeginTime:      2014-09-22T20:18:23-05:00
        severity:               critical
        alertAction:            "Informational. The hard disk has entered
predictive failure status. A white DB server locator LED has been turned on to
help locate the affected cell, and an amber service action LED has been lit on the
drive to help locate the affected drive. Detailed information on this problem can
be found at
https://support.oracle.com/CSP/main/article?cmd=show&type=NOT&id=1112995.1
Automatic Service Request has been notified with Unique Identifier:
c84839be-e8d8-4e5e-b315-e145ccd7cbc8."

Parent topic: LIST

9.7.7.3 LIST DBSERVER

Purpose

The LIST DBSERVER command displays all alerts that occurred on the database server.

Syntax

LIST DBSERVER [ name |  attribute_filters ]  [attribute_list]  [DETAIL]

Usage Notes

You can use the DESCRIBE DBSERVER command to view the complete list of DBSERVER attributes.

Examples

Example 9-69 shows the output of the LIST DBSERVER DETAIL command.

Example 9-70 shows how to display the value of the rescuePlan attribute.

Example 9-71 shows how to retrieve the value of the httpsAccess attribute.

Example 9-69 Listing DBSERVER Attributes

DDBMCLI> LIST DBSERVER DETAIL
         name:                   myexadb03
         bbuStatus:              normal
         cpuCount:               24
         diagHistoryDays:        7
         fanCount:               16/16
         fanStatus:              normal
         httpsAccess             ALL
         id:                     1029FMM085
         interconnectCount:      2
         ipaddress1:             192.168.10.25/22
         kernelVersion:          2.6.39-400.220.0.el6uek.x86_64
         locatorLEDStatus:       on
         makeModel:              Oracle Corporation SUN FIRE X4170 M2 SERVER
         metricHistoryDays:      7
         msVersion:              OSS_MAIN_LINUX.X64_140921
         powerCount:             2/2
         powerStatus:            normal
         releaseImageStatus:     success
         releaseVersion:         12.1.2.1.0.140728
         releaseTrackingBug:     17885582
         snmpSubscriber:          
         host=10.133.131.130,port=162,community=public,type=asr
         status:                 online
         temperatureReading:     20.0
         temperatureStatus:      normal
         upTime:                 55 days, 5:12
         msStatus:               running
         rsStatus:               running

DBMCLI> LIST DBSERVER ATTRIBUTES status,uptime
         online  161 days, 3:11

Example 9-70 Displaying the rescuePlan Attribute

DBMCLI> LIST DBSERVER ATTRIBUTES rescuePlan

CREATE ROLE "listdbserverattrs"

GRANT PRIVILEGE list ON DBSERVER ATTRIBUTES bbuStatus, coreCount WITH ALL OPTIONS TO ROLE "listdbserverattrs"

ALTER DBSERVER diagHistoryDays="7", metricHistoryDays="7", bbuLearnSchedule="MONTH 1 DATE 17 HOUR 2 MINUTE 0", alertSummaryStartTime="2016-09-26T08:00:00-07:00", alertSummaryInterval=weekly, pendingCoreCount="128" force

Example 9-71 Displaying the HTTPs Access Control List

This example shows how to view the HTTPs access control list for the Exadata RESTful service.

DBMCLI> LIST DBSERVER ATTRIBUTES httpsAccesss
         ALL

The value of ALL is the default value and allows access to all hosts.

Parent topic: LIST

9.7.7.4 LIST DIAGPACK

Purpose

The LIST DIAGPACK command lists the diagnostic packages in your system, along with their status.

Syntax

LIST DIAGPACK [DETAIL]

Usage Notes

The location of the diagnostic packages is /opt/oracle/dbserver/dbms/deploy/log.

Examples

Example 9-72 Output of the LIST DIAGPACK Command

This example shows the output of the LIST DIAGPACK command. 

DBMCLI> LIST DIAGPACK
dbm04adm01_2016_06_07T12_28_23_17_1.tar.bz2
dbm04adm01_2016_04_11T12_51_05_16_1.tar.bz2

Example 9-73 Output of the LIST DIAGPACK command with the DETAIL option

This example shows the output of the LIST DIAGPACK command with the DETAIL option. 

DBMCLI> LIST DIAGPACK DETAIL
   name:                   dbm04adm01_2019_08_07T12_28_23_17_1.tar.bz2
   alertDescription:       "Hard disk of size 600GB in slot 5 failed"
   alertName:              17_1
   diagPackHostName:       dbm04adm01
   packStartTime:          2016-06-07T12:28:23-07:00

   name:                   dbm04adm01_2019_08_11T12_51_05_16_1.tar.bz2
   alertDescription:       "InfiniBand Port HCA-4:1 may require attention. State:Down, Physical State:Disabled."
   alertName:              16_1
   diagPackHostName:       dbm04adm01
   packStartTime:          2016-04-11T12:51:05-07:00

   name:                   dbm04adm01_diag_2019_08_12T18_37_30_1
   alertDescription:       Processing...

Related Topics

Parent topic: LIST

9.7.7.5 LIST IBPORT

Purpose

The LIST IBPORT command displays attributes for InfiniBand Network Fabric ports determined by the specified attributes and filters.

Note:

This command does not work on Oracle Exadata servers with RoCE Network Fabric.

Syntax

LIST IBPORT  [ name |  attribute_filters ]  [attribute_list] [DETAIL]

Usage Notes

  • You can use the DESCRIBE IBPORT command to view the complete list of IBPORT attributes.

  • If the activeSlave attributes for both InfiniBand Network Fabric ports on a server are not listed, then active-active bonding is being used. If an activeSlave attribute is TRUE, then active-passive bonding is being used.

Example 9-74 Listing IBPORT Attributes

This example demonstrates the output you might see from the LIST IBPORT command. 

DBMCLI> LIST IBPORT
         HCA-1:1         Active
         HCA-1:2         Active

DBMCLI> LIST IBPORT DETAIL
         name:                   HCA-1:1
         activeSlave:            TRUE
         dataRate:               "40 Gbps"
         hcaFWVersion:           2.7.0
         id:                     0x00212800013e8c67
         lid:                    20
         linkDowned:             0
         linkIntegrityErrs:      0
         linkRecovers:           0
         physLinkState:          LinkUp
         portNumber:             1
         rcvConstraintErrs:      0
         rcvData:                84653709
         rcvErrs:                0
         rcvRemotePhysErrs:      0
         status:                 Active
         symbolErrs:             0
         vl15Dropped:            0
         xmtConstraintErrs:      0
         xmtData:                84572496
         xmtDiscards:            0

         name:                   HCA-1:2
         activeSlave:            FALSE
         dataRate:               "40 Gbps"
         hcaFWVersion:           2.7.0
         id:                     0x00212800013e8c68
         lid:                    21
         linkDowned:             0
         linkIntegrityErrs:      0
         linkRecovers:           0
         physLinkState:          LinkUp
         portNumber:             2
         rcvConstraintErrs:      0
         rcvData:                79355427
         rcvErrs:                0
         rcvRemotePhysErrs:      0
         status:                 Active
         symbolErrs:             0
         vl15Dropped:            0
         xmtConstraintErrs:      0
         xmtData:                79274016
         xmtDiscards:            0

Parent topic: LIST

9.7.7.6 LIST LUN

Purpose

The LIST LUN command displays attributes for LUNs determined by the specified attributes and filters.

Syntax

LIST LUN [ name |  attribute_filters ]  [attribute_list] [DETAIL]

Usage Notes

You can use the DESCRIBE LUN command to view the complete list of LUN attributes.

Examples

Example 9-75 shows the LIST command with the LUN object, and the corresponding output.

Example 9-75 Listing LUN Attributes

DBMCLI> LIST LUN
         0_0     0_0     normal
 
DBMCLI> LIST LUN 0_0 DETAIL
         name:                   0_0
         diskType:               HardDisk
         id:                     0_0
         lunSize:                556.9289999008179G
         lunUID:                 0_0
         raidLevel:              5
         lunWriteCacheMode:      "WriteBack, ReadAheadNone, Direct,   \
                                  No Write Cache if Bad BBU"
         status:                 normal

Parent topic: LIST

9.7.7.7 LIST METRICCURRENT

Purpose

The LIST METRICCURRENT command displays a list of collections of all metrics.

Syntax

LIST METRICCURRENT [ name |  attribute_filters ]  [attribute_list]  [DETAIL]

Usage Notes

  • You can use the DESCRIBE METRICCURRENT command to view the complete list of METRICCURRENT attributes.

  • To reduce the size of the output when you run the LIST METRICCURRENT command, use filters.

Examples

Example 9-76 shows the LIST command with filters to display information about the METRICCURRRENT object, and the corresponding output.

Example 9-76 Listing METRICCURRENT Attributes

DBMCLI> LIST METRICCURRENT attributes name, objecttype
         DS_BBU_CHARGE           DBSERVER
         DS_BBU_TEMP             DBSERVER
         DS_CPUT                 DBSERVER
         DS_CPUT_MS              DBSERVER
         DS_FANS                 DBSERVER
         DS_FSUT                 DBSERVER_FILESYSTEM
         DS_FSUT                 DBSERVER_FILESYSTEM
         DS_FSUT                 DBSERVER_FILESYSTEM
         DS_MEMUT                DBSERVER
         DS_MEMUT_MS             DBSERVER
         DS_RUNQ                 DBSERVER
         DS_SWAP_IN_BY_SEC       DBSERVER
         DS_SWAP_OUT_BY_SEC      DBSERVER
         DS_SWAP_USAGE           DBSERVER
         DS_TEMP                 DBSERVER
         DS_VIRTMEM_MS           DBSERVER
         N_HCA_MB_RCV_SEC        DBSERVER
         N_HCA_MB_TRANS_SEC      DBSERVER
         N_IB_MB_RCV_SEC         IBPORT
         N_IB_MB_RCV_SEC         IBPORT
         N_IB_MB_TRANS_SEC       IBPORT
         N_IB_MB_TRANS_SEC       IBPORT
         N_IB_UTIL_RCV           IBPORT
         N_IB_UTIL_RCV           IBPORT
         N_IB_UTIL_TRANS         IBPORT
         N_IB_UTIL_TRANS         IBPORT
         N_NIC_KB_RCV_SEC        DBSERVER
         N_NIC_KB_TRANS_SEC      DBSERVER
         N_NIC_NW                DBSERVER

DBMCLI> LIST METRICCURRENT where objectType='IBPORT'
         N_IB_MB_RCV_SEC         HCA-1:1         0.026 MB/sec
         N_IB_MB_RCV_SEC         HCA-1:2         0.009 MB/sec
         N_IB_MB_TRANS_SEC       HCA-1:1         0.021 MB/sec
         N_IB_MB_TRANS_SEC       HCA-1:2         0.004 MB/sec
         N_IB_UTIL_RCV           HCA-1:1         0.0 %
         N_IB_UTIL_RCV           HCA-1:2         0.0 %
         N_IB_UTIL_TRANS         HCA-1:1         0.0 %
         N_IB_UTIL_TRANS         HCA-1:2         0.0 %

DBMCLI> LIST METRICCURRENT where name = DS_CPUT and metricobjectname= myexadb04 detail
         name:                   DS_CPUT
         alertState:             normal
         collectionTime:         2014-03-13T16:15:25-05:00
         metricObjectName:       myexadb04
         metricType:             Instantaneous
         metricValue:            0.9 %
         objectType:             DBSERVER
 
 
DBMCLI> LIST METRICCURRENT DS_FSUT
         DS_FSUT         /       50 %
         DS_FSUT         /boot   18 %
         DS_FSUT         /u01    82 %

Related Topics

Parent topic: LIST

9.7.7.8 LIST METRICDEFINITION

Purpose

The LIST METRICDEFINITION command displays a list of metric definitions on the database server.

Syntax

LIST METRICDEFINITION [ name |  attribute_filters ]  [attribute_list]  [DETAIL]

Usage Notes

You can use the DESCRIBE METRICDEFINITION command to view the complete list of METRICDEFINITION attributes.

Examples

Example 9-77 shows the LIST command with the METRICDEFINITION object, and the corresponding output.

Example 9-77 Listing METRICDEFINITION Attributes

DBMCLI> LIST METRICDEFINITION
         DS_BBU_CHARGE
         DS_BBU_TEMP
         DS_CPUT
         DS_CPUT_MS
         DS_FANS
         DS_FSUT
         DS_MEMUT
         DS_MEMUT_MS
         DS_RUNQ
         DS_SWAP_IN_BY_SEC
         DS_SWAP_OUT_BY_SEC
         DS_SWAP_USAGE
         DS_TEMP
         DS_VIRTMEM_MS
         N_HCA_MB_RCV_SEC
         N_HCA_MB_TRANS_SEC
         N_IB_MB_RCV_SEC
         N_IB_MB_TRANS_SEC
         N_IB_UTIL_RCV
         N_IB_UTIL_TRANS
         N_NIC_KB_RCV_SEC
         N_NIC_KB_TRANS_SEC
         N_NIC_NW

Parent topic: LIST

9.7.7.9 LIST METRICHISTORY

Purpose

The LIST METRICHISTORY command displays a list of individual metrics.

Syntax

LIST METRICHISTORY [ name |  attribute_filters ]  [attribute_list]  
                   {over_specification] [MEMORY] [DETAIL]

Usage Notes

  • You can use the DESCRIBE METRICHISTORY command to view the complete list of METRICHISTORY attributes.

  • The retention period for most metric history files is specified by the metricHistoryDays attribute. The default retention period is 7 days. You can modify this setting with the DBMCLI ALTER DBSERVER command.

    In addition to the metrics governed by the metricHistoryDays attribute, a subset of key metric observations are retained for up to one year. In all cases, historical metric observations are purged automatically if the server detects a storage space shortage.

  • The over_specification syntax is as follows: 

    OVER number [aggregation_type [aggregation_type]...]

    In the preceding syntax, number is amount of time in minutes for the aggregation, and aggregation_type can be max, min, or avg.

  • A WHERE clause can include the ageInMinutes attribute to specify the list is limited to those metrics which have the specified age. For example, the following command would show the metrics created in the previous 15 minutes: 

    DBMCLI> LIST METRICHISTORY WHERE ageInMinutes < 15

Examples

Example 9-78 shows the LIST METRICHISTORY command with the name and collectionTime attributes.

Example 9-79 shows the LIST METRICHISTORY command with the ds_cput attribute.

Example 9-78 Listing METRICHISTORY Using the Name and CollectionTime Attributes

DBMCLI> LIST METRICHISTORY WHERE name LIKE 'DS_.*' AND collectionTime > '2014-03-27T17:48:16-05:00'

         DS_FANS                 myexadb03       16              2014-03-27T17:49:15-05:00
         DS_TEMP                 myexadb03       20.0 C          2014-03-27T17:49:15-05:00
         DS_BBU_CHARGE           myexadb03       52.0 %          2014-03-27T17:49:16-05:00
         DS_BBU_TEMP             myexadb03       45.0 C          2014-03-27T17:49:16-05:00
         DS_CPUT                 myexadb03       0.3 %           2014-03-27T17:49:16-05:00
         DS_CPUT_MS              myexadb03       0.0 %           2014-03-27T17:49:16-05:00
         DS_FSUT                 /               73 %            2014-03-27T17:49:16-05:00
         DS_FSUT                 /boot           18 %            2014-03-27T17:49:16-05:00
         DS_FSUT                 /u01            43 %            2014-03-27T17:49:16-05:00
         DS_MEMUT                myexadb03       42 %            2014-03-27T17:49:16-05:00
         DS_MEMUT_MS             myexadb03       0.3 %           2014-03-27T17:49:16-05:00
         DS_MEMUT_MS             myexadb03       0.3 %           2014-03-27T17:49:16-05:00
         DS_RUNQ                 myexadb03       0.2             2014-03-27T17:49:16-05:00
         DS_SWAP_IN_BY_SEC       myexadb03       0.0 KB/sec      2014-03-27T17:49:16-05:00
         DS_SWAP_OUT_BY_SEC      myexadb03       0.0 KB/sec      2014-03-27T17:49:16-05:00
         DS_SWAP_USAGE           myexadb03       0 %             2014-03-27T17:49:16-05:00
         DS_VIRTMEM_MS           myexadb03       981 MB          2014-03-27T17:49:16-05:00
         DS_VIRTMEM_MS           myexadb03       981 MB          2014-03-27T17:49:16-05:00

Example 9-79 Listing METRICHISTORY for the ds_cput Attribute

DBMCLI> LIST METRICHISTORY ds_cput OVER 10 MIN MAX MEMORY
         DS_CPUT  myexadb03  1.0 %   2014-03-27T16:59:16-05:00       0.3 %   1.0 %
         DS_CPUT  myexadb03  0.7 %   2014-03-27T17:09:16-05:00       0.2 %   0.8 %
         DS_CPUT  myexadb03  0.7 %   2014-03-27T17:19:16-05:00       0.3 %   1.1 %
         DS_CPUT  myexadb03  0.7 %   2014-03-27T17:29:16-05:00       0.3 %   0.9 %
         DS_CPUT  myexadb03  0.7 %   2014-03-27T17:39:16-05:00       0.2 %   0.8 %
         DS_CPUT  myexadb03  0.8 %   2014-03-27T17:49:16-05:00       0.3 %   0.8 %
9.7.7.10 LIST METRICSTREAM

Purpose

The LIST METRICSTREAM command displays metrics in the metric stream.

Syntax

LIST METRICSTREAM [ name |  attribute_filters ]  [attribute_list]  [DETAIL]

Usage Notes

  • The LIST METRICSTREAM command is functionally equivalent to the LIST METRICCURRENT command, except that LIST METRICSTREAM only displays metrics that are included in the metric stream.

Example 9-80 Listing METRICSTREAM Attributes

This example shows the LIST METRICSTREAM command with a filter to display cell disk attributes. 

DBMCLI> LIST METRICSTREAM WHERE name LIKE 'N_NIC.*'
9.7.7.11 LIST PHYSICALDISK

Purpose

The LIST PHYSICALDISK command displays attributes for one or more physical disks determined by the specified attributes and filters.

Syntax

LIST PHYSICALDISK [ name |  attribute_filters ]  [attribute_list]  [DETAIL]

Usage Notes

You can use the DESCRIBE PHYSICALDISK command to view the complete list of PHYSICALDISK attributes.

Examples

Example 9-81 shows the LIST command with the PHYSICALDISK object, and the corresponding output.

Example 9-81 Listing Physical Disk Attributes

DBMCLI> LIST PHYSICALDISK
         252:0   G08VKE  normal
         252:1   GYVAXE  normal
         252:2   G07Z5E  normal
         252:3   G0889E  normal

Parent topic: LIST

9.7.7.12 LIST ROLE

Purpose

The LIST ROLE command displays the specified attributes for a role.

Syntax

LIST ROLE [name | filters] [attribute_list] [DETAIL]

Usage Notes

  • name is the name of the role.

  • filters is an expression that determines which roles are displayed.

  • attribute_list is the attributes to display. The ALL option can be used to display all attributes.

  • The DETAIL option formats the output as an attribute on each line, with an attribute descriptor preceding each value.

Examples

Example 9-82 shows the LIST ROLE command.

Example 9-82 Displaying a Role

DBMCLI> LIST ROLE DETAIL

DBMCLI> LIST ROLE where name like 'db_*'

Parent topic: LIST

9.7.7.13 LIST SOFTWAREHISTORY

Purpose

The LIST SOFTWAREHISTORY command displays a list of final states for past software updates.

Syntax

LIST SOFTWAREHISTORY [attribute_filters] [attribute_list] [DETAIL]

Example 9-83 Displaying the History of a Scheduled Software Update

By default, only the update name and status are shown.

CellCLI> LIST SOFTWAREHISTORY
  12.2.1.2.0.170509  Last update completed at: 2017-05-20T08:00:57-07:00
  12.2.1.2.0.170520  Last update completed at: 2017-05-21T06:39:54-07:00
  12.2.1.2.0.17052   Last update completed at: 2017-06-08T08:56:45-07:00
  12.2.1.2.0.170603  Last update completed at: 2017-06-08T16:03:17-07:00

Example 9-84 Displaying the Detailed History of a Specific Software Update

This example shows the detailed software update history for a particular update which is referenced by its name.

CellCLI> LIST SOFTWAREHISTORY WHERE name='12.2.1.2.0.170808.1' DETAIL
         name:                   12.2.1.2.0.170808.1
         status:                 Upgrade failed. See alerts at: 2017-08-10T10:56:15-07:00

Parent topic: LIST

9.7.7.14 LIST SOFTWAREUPDATE

Purpose

The LIST SOFTWAREUPDATE command displays the status of the most recently scheduled update.

Syntax

LIST SOFTWAREUPDATE [attribute_list] [DETAIL]

Usage Notes

The possible states for the software update are:

  • Ready to update at: update_time

  • Downloading

  • Checking prerequisites

  • Prerequisites failed. See alerts.

  • Last update completed at: update_time

  • Running

  • Upgrade failed. See alerts.

Example 9-85 Displaying the Status of a Scheduled Software Update

By default, only the update name and status are shown.

CellCLI> LIST SOFTWAREUPDATE
  12.2.1.2.0.170603   Last update completed at: 2017-06-08 16:03:17 -0700

Example 9-86 Displaying the Detailed Status of a Scheduled Software Update

By default, only the update name and status are shown.

CellCLI> LIST SOFTWAREUPDATE DETAIL
         name:                   12.2.1.2.0.170808.1
         status:                 Upgrade failed. See alerts
         store:                  https://mystore_url:4443
         time:                   2017-08-10T10:35:00-07:00

Parent topic: LIST

9.7.7.15 LIST THRESHOLD

Purpose

The LIST THRESHOLD command displays attributes for one or more thresholds determined by the specified attributes and filters.

Syntax

LIST THRESHOLD [ name |  attribute_filters ]  [attribute_list] [DETAIL]

Usage Notes

You can use the DESCRIBE THRESHOLD command to view the complete list of THRESHOLD attributes.

Examples

Example 9-87 shows the LIST command with the THRESHOLD object, and the corresponding output.

Example 9-87 Listing Threshold Attributes

DBMCLI> LIST THRESHOLD                                               
         DS_CPUT.myexadb04
         DS_TEMP.myexadb04
 
DBMCLI> LIST THRESHOLD DS_CPUT.myexadb04 detail
         name:                   DS_CPUT.myexadb04
         comparison:             >
         warning:                90.0
 
DBMCLI> LIST THRESHOLD DS_TEMP.myexadb04 detail
         name:                   DS_TEMP.myexadb04
         comparison:             >
         critical:               30.0

Parent topic: LIST

9.7.7.16 LIST USER

Purpose

The LIST USER command displays the specified attributes for a user.

Syntax

LIST USER [name | filters] [attribute_list] [DETAIL]

Usage Notes

  • name is the user name.

  • filters is an expression that determines which users are displayed.

  • attribute_list is the attributes to display. The ALL option can be used to display all attributes.

  • The DETAIL option formats the output as an attribute on each line, with an attribute descriptor preceding each value.

Examples

Example 9-88 shows the LIST USER command.

Example 9-88 Using the LIST USER Command

DBMCLI> LIST USER DETAIL

DBMCLI> LIST USER where name like 'jdoe' DETAIL
         name:                   jdoe
         roles:                  role=db_monitor
         Privileges:             object=dbserver 
                                 verb=list
                                 attributes=all attributes
                                 options= all options

Parent topic: LIST

9.7.8 REVOKE

Purpose

The REVOKE command removes privileges and roles.

Syntax

REVOKE object_type [name] FROM sub_object_type [sub_object_name]

Usage Notes

  • object_type can be as follows:

    • PRIVILEGE

    • ROLE

  • The following can be used for PRIVILEGE object type:

    • name is in the following format: 

      { ALL ACTIONS | action } ON { ALL OBJECTS | object }  { ALL ATTRIBUTES | \
ATTRIBUTES attribute1 [, attribute2, ...] }  { WITH ALL OPTIONS |        \
WITH OPTIONS option1 [, option2, ...] }

    • The sub_object_type must be ROLE.

    • The sub_object_name is a role name, a comma-delimited list of role names, or the keyword ALL.

  • The following can be used for the ROLE object type:

    • name is a role name, a comma-delimited list of role names, or the keyword ALL.

    • The sub_object_type must be USER.

    • The sub_object_name is the name of the user, a comma-delimited list of user names, or the keyword ALL.

Parent topic: DBMCLI Command Reference

9.7.8.1 REVOKE PRIVILEGE

Purpose

The REVOKE PRIVILEGE command revokes privileges from a role.

Syntax

REVOKE PRIVILEGE { ALL ACTIONS | action } ON { ALL OBJECTS | object } { ALL ATTRIBUTES | ATTRIBUTES attribute1 [, attribute2...] } { WITH ALL OPTIONS | WITH OPTIONS option1 [, option2, ...] } FROM ROLE { ALL | role1 [, role2, ...] }

Usage Notes

  • action is the command.

  • object is object type for the action.

  • attribute are the attributes for the object.

  • option are the options for the object.

  • role is the name of the role from which to revoke privileges.

  • The ALL ACTIONS argument revokes privileges for all actions.

  • The ALL OBJECTS argument revokes privileges for all objects.

  • The ALL ATTRIBUTES argument revokes privileges for all attributes.

  • The WITH ALL OPTIONS argument revokes privileges for all options.

Examples

Example 9-89 shows the REVOKE PRIVILEGE command.

Example 9-89 Revoking a Privilege

DBMCLI> REVOKE PRIVILEGE ALL ACTIONS ON ALL OBJECTS ALL ATTRIBUTES -
         WITH ALL OPTIONS FROM ROLE ALL

DBMCLI> REVOKE PRIVILEGE list ON dbserver ATTRIBUTES name     -
         WITH OPTIONS detail FROM ROLE db_monitor

Parent topic: REVOKE

9.7.8.2 REVOKE ROLE

Purpose

The REVOKE ROLE command revokes the role for a user.

Syntax

REVOKE ROLE { ALL | role1 [, role2, ...] } FROM USER { ALL | user1 [, user2...] }

Usage Notes

  • role1 and role2 are the names of roles.

  • user1 and user2 are the names of users.

  • The ALL argument revokes all roles from the user.

  • The FROM USER ALL argument revokes the role from all users.

Examples

Example 9-90 shows how to revoke a role from a user.

Example 9-90 Revoking a Role From a User

DBMCLI> REVOKE ROLE db_monitor FROM USER jdoe

Parent topic: REVOKE

9.7.9 SET

Purpose

The SET command sets a variable to alter the DBMCLI environment settings for the current session.

Syntax

SET DATEFORMAT {LOCAL | STANDARD}
SET ECHO [ON | OFF]

Usage Notes

The SET DATEFORMAT command controls the format of displayed dates. For commands that accept dates, the standard date-time format is recommended. The local format is also accepted. The standard format is recommended for scripts because that format is less sensitive to the time zone, region, and locale changes that might occur when running a script.

The SET ECHO command controls whether to echo commands in a script that is run with @ or START. The ON option displays the commands on screen. The OFF option suppresses the display. The SET ECHO command does not affect the display of commands entered interactively or redirected from the operating system.

Example 9-91 Setting the Date Format with the SET Command

SET DATEFORMAT STANDARD

Parent topic: DBMCLI Command Reference

9.7.10 SPOOL

Purpose

The SPOOL command writes (spools) the results of commands to the specified file.

Syntax

SPO[OL] [file_name [ CRE[ATE] | REP[LACE] | APP[END] ] | OFF]

Usage Notes

If you issue SPOOL file_name with no option, then the output is spooled to that file whether or not the file already exists. The REPLACE option is the default behavior.

Table 9-14 SPOOL Options

Option Description

APPEND

Adds the results to the end of the file specified.

CREATE

Creates a new file with the name specified, and raises an error if the file exists.

file_name

Names the file to which the results are written. It can be specified with a fully-qualified path name, or with a partially-qualified path name relative to the current directory.

no option

Displays the name of the current spool target file, if any.

OFF

Stops writing (spooling) output to the file.

REPLACE

Replaces the contents of an existing specified file. If the file does not exist, then REPLACE creates the file. This is the default behavior.

Parent topic: DBMCLI Command Reference

9.7.11 START

Purpose

The START command runs the DBMCLI commands in the specified script file.

Syntax

STA[RT] file_name

Usage Notes

The START option is file_name. It is the name of the script file that contains the DBMCLI commands. If the file name does not include a fully-qualified path, then the DBMCLI utility searches for the file relative to the current directory.

The START command is useful when entering long or multiple DBMCLI commands. For example, all the commands in Example 9-10 can be entered in a text file named alter_dbserver, then run as follows, assuming that the alter_dbserver file is in the current directory: 

START alter_dbserver

Parent topic: DBMCLI Command Reference