Chapter 7. Sending Notifications
Prev |  | Next

## Chapter 7. Sending Notifications

## About the espnotify Tool

The ESP software suite includes the `espnotify` tool, which you can use to perform the following types of notification:

- Display a message on the system console

- Display a message on a local or remote X Window System display

- Send an e-mail message

- Send a page to an alphanumeric or chatty pager

| Note: This chapter describes how to use the `espnotify` command to create notifications, which was the only way to create notifications when ESP 2.0 was first released. ESP now includes a method to automatically generate the `espnotify` command from options that you select from the graphical user interface (when you use the `Notification Action` option in the `Add An Action` window). The information in this chapter remains in the document to provide examples of how you can create command lines as actions. If you need to create standard notification actions, it is easiest to use the automated method.

### Command Line Options for Displaying a Message on the Console

Use the following format of the `espnotify` command to display a message on the system console:

    /usr/bin/espnotify -A <message> [-n <number>]

This format of the `espnotify` command has the following command line options:

`-A` |  | Specifies that the message should be displayed in the console window
`<message>` |  | Specifies the message that the window should display
|  | Enclose `<message>` in single quotes (` `) if the message contains more than one word.
`-n <number>` |  | Specifies an optional priority message, which is determined by the value that you specify for `<number>`
|  | The `<number>` parameter can be a value from 1 to 7. `espnotify` attaches a label to the message based on the value of `<number>`: 1 or 2 (`Critical System Error`), 3 (`System Error`), 4 (`System Warning`), or 5 to 7 (`System Information`)

For example, the following command displays the message `This is the message to display.` on the console (refer to Figure 7-1):

    /usr/bin/espnotify -A `This is the message to display.'

Figure 7-1. Displaying a Message in the Console Window

### Displaying a Message on an X Window System Display

Use the following format of the `espnotify` command to display a message on a local or remote X Window System display:

    /usr/bin/espnotify -c <message> [-a] [-D <display>] [-g <geometry>]
    [-i <icon>] -n <number>] [-t <title>]

This format of the `espnotify` command has the following command line options:

`-c <message>` |  | Specifies the message that the window should display
|  | Enclose `<message>` in double quotes (“ “) if the message contains more than one word.
`-a` |  | Specifies that an audio file should be played
|  | The `/usr/bin/ssplay` application plays the audio file. Audio notification cannot be performed without graphical notification. Audio notification can be performed only on the local host.
`-D <display>` |  | Specifies the display to use. (If you do not specify a display, the window is displayed on the host specified by the `$DISPLAY` environment variable.)
`-g <geometry>` |  | Specifies an optional X Window System geometry string for the window (in the standard WIDTHxHEIGHTxXOFFxYOFF format)
|  | For example, `-g 120x80x50x100` specifies a window that is 120 pixels wide by 80 pixels high and is located 50 pixels from the left edge of the screen and 100 pixels from the top edge of the screen. (Refer to the `x(1)` man page for more information.)
`-i <icon>` |  | Specifies an optional image to display as an icon for the window
`-n <number>` |  | Specifies an optional priority message, which is determined by the value that you specify for `<number>`
|  | The `<number>` parameter can be a value from 1 to 7. `espnotify` attaches a label to the message based on the value of `<number>`: 1 or 2 (`Critical System Error`), 3 (`System Error`), 4 (`System Warning`), or 5 to 7 (`System Information`)
`-t <title>` |  | Specifies an optional title of the window.
|  | Enclose `<title>` in double quotes (“ “) if the title contains more than one word.

For example, the following command displays a window on the local host (refer to Figure 7-2):

    /usr/bin/espnotify -c "This is the message to display." -D localhost:0 -t "This is the title."

Figure 7-2. Displaying a Message on an X Window System Display

### Sending an E-mail Message

Use the following format of the `espnotify` command to send an e-mail message:

    /usr/bin/espnotify -E <address> { -f <filename> | -m <message> } [-n <number>] [-o <options>] [-s <subject>]

This format of the `espnotify` command has the following command line options:

`-E <address>` |  | Specifies the e-mail addresses that should receive the message
|  | Enclose <address> in single quotes (` `) if the list contains more than one address.
`-f <filename>` |  | Specifies a text file to use as content for the message
|  | You cannot use the `-f` and `-m` options at the same time.
`-m <message>` |  | Specifies text to use as content for the message
|  | Enclose `<message>` in single quotes (` `) if the message contains more than one word.
|  | You cannot use the `-f` and `-m` options at the same time.
`-n <number>` |  | Specifies an optional priority message, which is determined by the value that you specify for `<number>`
|  | The `<`number`>` parameter can be a value from 1 to 7. `espnotify` attaches a label to the message based on the value of `<`number`>`: 1 or 2 (`Critical System Error`), 3 (`System Error`), 4 (`System Warning`), or 5 to 7 (`System Information`)
`-o <options>` |  | Specifies processing options for the message
|  | Two options are available: `-o COMP` (compress and uuencode the message) and `-o ENCO` (uuencode the message). These options are valid only if you also use the `-f` option.
`-s <subject>` |  | Specifies the subject of the message
|  | The format of the default subject is `[HOSTNAME]: <text>`, where `HOSTNAME` is replaced with the name of the host and `<text>` is replaced with a priority message (for example, `Critical System Error`).
|  | If you use the `-n` and`-s` options, the `-s` option overrides the `-n` option.

For example, the following command sends a message to dtg@sgi.com (refer to Figure 7-3):

    /usr/bin/espnotify -E dtg@sgi.com -m 'This is the text of the message.' -n 1

Figure 7-3. Sending an E-mail Message

### Sending a Page

Use the following format of the `espnotify` command to send a page to an alphanumeric or chatty pager:

    /usr/bin/espnotify -C <message> -p <pagers> [-n <number>] [-Q <server>] [-S <service>]

This format of the `espnotify` command has the following command line options:

`-C <message>` |  | Specifies the message that the window should display.
|  | Enclose `<message>` in double quotes (“ “) if the message contains more than one word.
`-p <pagers>` |  | Specifies a comma-separated list of pager names (or pager identification numbers) that should receive the message
|  | Pager information is stored in the `/etc/qpage.cf` file on the server that is sending the page. You can set up pager names on the ESP interface.
`-n <number>` |  | Specifies an optional priority message, which is determined by the value that you specify for `<number>`
|  | The `<number>` parameter can be a value from 1 to 7. `espnotify` attaches a label to the message based on the value of `<`number`>`: 1 or 2 (`Critical System Error`), 3 (`System Error`), 4 (`System Warning`), or 5 to 7 (`System Information`)
`-Q <server>` |  | Specifies an alternate paging server to use
|  | If you do not specify this option, `espnotify` uses the `QPage` software on the local host.
`-S <service>` |  | Specifies an alternate paging service to use
|  | Paging service information is stored in the `/etc/qpage.cf` file on the server that is sending the page. You can set up paging service information on the ESP interface.
|  | If you do not specify this option, `espnotify` uses the default paging service specified in the `/etc/qpage.cf` file.

For example, the following command sends the message `This is the message` to the pager named mypager:

    /usr/bin/espnotify -C “This is the message” -p mypager

## Invoking espnotify from ESP

Because `espnotify` is a command line utility, you can configure it as an ESP action. To do this, create a new action or update an existing action with a command string that uses the `/usr/bin/espnotify` command. This section shows two examples of how to create ESP actions that use `espnotify`.

### Example 1: Creating an Action to Send an E-mail

The first example shows how to set up an ESP action to send notification by E-mail.

1. Click on the `Configuration` button.

2. Click on the `Actions` button.

3. Click on the `Add` button.

4. Click on the radio button next to `Other action`.

5. Click on the `Continue` button.

6. Update the parameters. (Table 7-1 lists the parameters for this example.)

   Table 7-1. Example Action Parameters for Sending an E-mail Notification

   Field | Setting
   --- | ---
   `Action description` | `Send notification via e-mail to abc123@sgi.com`
   `Action string` | `/usr/bin/espnotify -E abc123@sgi.com -m %D -s `An event was just registered.'`
   `Execute action as` | `nobody`
   `Action timeout (in multiples of 5)` | `10`
   `Before the action will be taken, the event must be registered` | `1`
   `Retry (up to 23 times; more than 4 is not recommended)` | `4`

   Figure 7-4 shows an interface page with the proper settings for this example.

   Figure 7-4. Example Action Parameters for Sending an E-mail Message

7. Click on the `Add` button. (Figure 7-5 shows the verification message for this example.)

   Figure 7-5. Example Verification Message for Sending an E-mail Message Action

8. Click on the `Commit` button. (Figure 7-6 shows the confirmation message for this example.)

   Figure 7-6. Example Confirmation Message for Sending an E-mail Message Action

### Example 2: Creating an Action to Send a Page

The second example shows how to set up an ESP action to send notification to a pager.

1. Click on the `Configuration` button.

2. Click on the `Actions` button.

3. Click on the `Add` button.

4. Click on the radio button next to `Other action`.

5. Click on the `Continue` button.

6. Update the parameters. (Table 7-2 lists the parameters for this example.)

   Table 7-2. Example Action Parameters for Sending a Message to a Pager

   Field | Setting
   --- | ---
   `Action description` | `Page Darrin`
   `Action string` | `/usr/bin/espnotify -C `There is a system problem.' -p Darrin_Goss`
   `Execute action as` | `nobody`
   `Action timeout (in multiples of 5)` | `10`
   `Before the action will be taken, the event must be registered` | `1`
   `Retry (up to 23 times; more than 4 is not recommended)` | `4`

   Figure 7-7 shows an example interface page with the proper settings for this example.

   Figure 7-7. Example Action Parameters for Sending a Message to a Pager

7. Click on the `Add` button. (Figure 7-8 shows the verification message for this example.)

   Figure 7-8. Example Verification Message for Sending a Message to a Pager Action

8. Click on the `Commit` button. (Figure 7-9 shows the confirmation message for this example.)

   Figure 7-9. Example Confirmation Message for Sending a Message to a Pager Action

Prev | Table of Contents | Next
Chapter 6. Using the ESP Logbook |  | Chapter 8. Logging Events from Applications and Scripts