Alert Notification Attributes

7.7.1.2.4.2 Alert Notification Attributes

Configuring Alert Notifications

To set up the cell to send notifications about alerts, you can configure the following cell attributes:

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.
smtpPort: Email server port used to send alert notifications
smtpUseSSL: Specification to use Secure Socket Layer (SSL) encryption for alert notifications.
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.
smtpToAddr: Address to which email is sent. It can be a comma-delimited list in quotation marks to allow multiple subscribers to alerts.
snmpSubscriber: List of hosts that subscribe to the SNMP alert notifications
snmpUser: Defines users who receives SNMP alerts
snmpEngineID: An identifier used by the SNMP managers to subscribe to alerts from the storage cells
notificationMethod: Notification method for alerts
notificationPolicy: Indicator for severity alerts to be sent to subscribers
emailFormat: File format for email messages
emailSubscriber: List of names that subscribe to the alert notifications

Usage Notes

mailServer

The mailServer attribute identifies the email relay server used to send alert notifications. When you modify the mailServer attribute value, the Exadata Management Server (MS) automatically configures and restarts the sendmail service. You can clear the mailServer attribute and remove the email relay server from the sendmail configuration by setting mailServer to an empty string enclosed by quotation marks (mailServer='').
smtpPort

The smtpPort attribute can be reset to the default value by setting it to an empty string enclosed by quotation marks (smtpPort='').
smtpUseSSL

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

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

The snmpSubscriber attribute can be set to a list of SNMP targets to which the SNMP alert notification is sent. The targets are specified as follows:
```
snmpSubscriber[-|+]=(
  (host=host[,port=port][,type=subscriber_type][,community=community][,snmpuser=snmp_user_name][,fromIP="ip"][,asrmPort="ASRManager_port"])
[,(host=host[,port=port][,type=subscriber_type][,community=community][,snmpuser=snmp_user_name][,fromIP="ip"][,asrmPort="ASRManager_port"])] ...)
```
The snmpSubscriber attribute uses the following values:
- The host must be specified as either a host name or an IP address. Enclose the host name or IP address in quotation marks if it contains non-alphanumeric characters.
- The default value for port is 162. This value is optional.
- The valid type values are v1, ASR, v3, and v3ASR.
  - Starting with Oracle Exadata System Software release 24.1.0, you must specify the type value.
    
    Previously, setting the type is optional, and the default value is v1.
  - The type=v3 and type=v3ASR options use SNMP V3. SNMP V3 is considered more secure than earlier SNMP versions, and should be used where possible.
  - The snmpSubscriber with type=ASR or type=v3ASR should only be configured to point to Oracle ASR Manager.
  - The type=ASR and type=v3ASR options set the Oracle ASR destination for Oracle Exadata Storage Server, and its ILOM. Removing all snmpSubscriber entries with type=ASR and type=v3ASR from the SNMP subscriber list disables the Oracle ASR trap mechanism for Oracle Exadata Storage Server and its ILOM.
  - For the v3ASR type, the user must be defined with authProtocol=SHA, and privProtocol=AES. These are the only protocols supported by Oracle ASR Manager. Setting the snmpSubscriber as type v3ASR also sets the ILOM properties and rules for traps sent by ILOM.
- Starting with Oracle Exadata System Software release 24.1.0, you must specify the community value for subscribers with type=v1 or type=ASR. Also, common default values such as public and private are discouraged for security reasons.
  
  Previously, setting the community is optional, and the default value is public.
- For subscribers with type=v3 or type=v3ASR, you must specify an SNMP user name (snmpuser=snmp_user_name), which is already configured within the server.
  
  For example:
```
CellCLI> ALTER CELL snmpuser.snmpuser1=(authprotocol=SHA,authpassword=*)
...

CellCLI> ALTER CELL snmpSubscriber=((host=newhost,port=162,type=v3,snmpuser=snmpuser1))
```
- 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 SNMP subscribers whose type is either ASR or v3ASR.
  
  For example:
```
CellCLI> ALTER CELL snmpSubscriber=((host=asrhost,port=162,community=asrcommunity,fromIP="1.1.1.1",type=ASR))
```
  The following example returns an error because the type is not ASR or v3ASR.
```
CellCLI> ALTER CELL snmpSubscriber=((host=localhost,port=162,community=asrcommunity,fromIP="1.1.1.1",type=v1))
CELL-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 SNMP subscribers whose type is either ASR or v3ASR. The default value for this port is 16161.
By default, ALTER CELL snmpSubscriber=(SNMPtargets) replaces the existing snmpSubscriber value. However, starting with Oracle Exadata System Software release 21.2.0, you can add to the existing list of SNMP targets by using snmpSubscriber+=(SNMPtarget). For example:
```
CellCLI> ALTER CELL snmpSubscriber+=((host=newhost,port=162,community=snmpcommunity,type=v1))
```
Also, starting with Oracle Exadata System Software release 22.1, you can remove an entry from the existing list of SNMP targets by using snmpSubscriber-=(SNMPtarget). For example:
```
CellCLI> ALTER CELL snmpSubscriber-=((host=myhost,port=162,community=snmpcommunity,type=v1))
```
After startup of the Management Server (MS), the snmpSubscriber list entries with type=ASR are added to the ILOM for the CELL. 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 CELL ... snmpUser= command.
snmpUser

The snmpUser attribute defines users who receives SNMP alerts. This command can only be run in interactive mode. There are two methods for configuring this attribute.
```
snmpuser=((user_clause1)[,(user_clauseN)]...)

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_clause1)[,(user_clauseN)]...) 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 general format:
```
([name=user1,] authProtocol=auth_type, authPassword=*
   [, privProtocol=priv_type, privPassword=*]) 
[,(name=userN, authProtocol=auth_type, authPassword=*
   [, privProtocol=priv_type, privPassword=*] )]...
```
If updating a single user using the snmpuser.name notation, do not include the phrase name=user1 in the user_clause.
- 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 specifies the authentication protocol.
  
  Options include MD5 and SHA. Additionally, Oracle Exadata System Software release 24.1.0 introduces the following SHA2 authentication protocols for SNMP V3 subscribers: SHA-224, SHA-256, SHA-384, and SHA-512.
  
  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.
snmpEngineID

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

Note:
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.
notificationMethod

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

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

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

The ALTER CELL emailSubscriber command sets a list of comma-delimited email addresses that are the recipients of alert notifications for specific alert types. The syntax for this command is:
```
ALTER CELL 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.
To validate that email messages are successfully sent for cell 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.

Examples

Example 7-11 shows how to set the asrmPort field for an snmpSubscriber.

Example 7-12 shows how to set up email notifications for the cell.

Example 7-13 shows how to modify the SNMP user.

Example 7-14 shows how to modify a single SNMP user.

Example 7-15 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 7-16 shows how to change the format of email messages.

Example 7-17 shows how to unsubscribe from email alerts.

Example 7-18 shows how to reset the notificationPolicy attribute to its default value.

Example 7-11 Setting the asrmPort for an snmpSubscriber

CellCLI> ALTER CELL snmpSubscriber=((host=host1,port=162,community=asrcommunity,type=asr,asrmPort=16161))

Example 7-12 Configuring Email Notifications for a Cell

The example includes multiple SNMP subscribers. Note that because host2 is an SNMP v3 subscriber, there is no community specification. Instead, for SNMP v3 subscribers, you must specify an existing SNMP user. See also the following for examples for modifying an SNMP user.

CellCLI> ALTER CELL mailServer='my_mail_relay.example.com',                                  -
                    smtpFromAddr='john.doe@example.com',                                     -
                    smtpFrom='John Doe',                                                     -
                    smtpToAddr='jane.smith@example.com',                                     -
                    snmpSubscriber=((host=host1,port=162,community=snmpcommunity,type=v1),   -
                                    (host=host2,port=162,snmpuser=user2,type=v3)),                          -
                    notificationPolicy='clear',                                              -
                    notificationMethod='mail,snmp'

Example 7-13 Modifying the SNMP User

This example shows SNMP user configuration, where the administrator is prompted to enter the passwords. The example contains one user definition, but the same approach can be expanded to define multiple SNMP users in the same command.

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 7-14 Modifying an 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)).
...

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

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

Example 7-15 Specifying the Type of Email Alert

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

Example 7-16 Changing the Format of Email Messages

CellCLI> ALTER CELL emailFormat='text'
CellCLI> ALTER CELL emailFormat='html'

Example 7-17 Unsubscribing from Email Alerts

ALTER CELL emailSubscriber=""

Example 7-18 Setting the Default Value for the notificationPolicy Attribute

This example shows how to set the default value for the notificationPolicy attribute.

CellCLI> alter cell notificationPolicy=""

Parent topic: ALTER CELL Commands for Setting Attributes