TrueNAS CORE
TrueNAS Enterprise
TrueNAS SCALE
Compare Editions
TrueCommand
Software Status
FreeNAS
Compare Systems
F-Series
M-Series
X-Series
R-Series
Mini Series
Download TrueNAS CORE
Download TrueNAS SCALE
Get TrueNAS Enterprise
Where to BuyTrueNAS SCALE Nightly Development Documentation
This content follows experimental early release software. Use the Product and Version selectors above to view content specific to a stable software release.
Alert
10 minute read.
Last Modified 2024-03-15 13:07 EDTThe alert namespace has seven commands and is based on alert functions found in the SCALE API and web UI. It provides access to alert management methods through the alert commands.
The following alert commands allow you to view and manage alerts and policies.
You can enter commands from the main CLI prompt or from the alert namespace prompt.
The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Enter the
--flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).Click for more information
The interactive argument editor is a text user interface (TUI) that can help enter complex commands with multiple configurable properties. It shows expected properties, defaults, input types (string, boolean, integer, or array), and can include command instructions or warnings.
Optional properties, indicated by the
#symbol, are disabled by default. Required properties are enabled. Do not disable properties that are enabled by default.To configure required properties, enter a space after the colon then add the value.
To enable optional properties, delete
#from the corresponding line.Some required properties are disabled if they are part of a pair of properties where one or the other is required. Select one property to enable and enter a value.
Press F2 or click Save to save the modified file.
Press F10, Esc, or click Quit to exit the TUI. The command automatically executes upon exit.
The class command allows you to view and update the default alert settings.
Viewing Current Alert Settings
The class command requires the config property to view current alert settings.
Enter the command then press Enter.
The command returns a table of current alert settings when successful.
From the CLI prompt, enter:
system alert class config
Updating Default Alert Settings
The class command requires the update property and classes argument to update default alert settings.
Enter the command then press Enter.
The command returns a blank line when successful.
From the CLI prompt, enter:
system alert class update classes={"class":{"level":"LEVEL","policy":"POLICY"}}
Where:
- class is the alert category class you want to update.
- LEVEL is the alert level you want to apply.
- POLICY is the alert notification frequency you want to apply.
The dismiss command dismisses alerts based on alert UUID.
Using the Dismiss Command
The dismiss command requires the UUID property.
Enter the command then press Enter.
The command returns a blank line when successful.
From the CLI prompt, enter:
system alert dismiss uuid="alertuuid"
Where alertuuid is the UUID of the alert you want to dismiss.
The list command lists all types of alerts including active and dismissed currently in the system.
Using the List Command
The list command has no required properties.
Enter the command then press Enter.
The command returns a table of current alerts when successful.
From the CLI prompt, enter:
system alert list
Command Example
system alert list
+--------------------------------------+-----------------+------------------+--------------------+--------------+------------------------+---------------------------+---------------------------+-----------+--------+------------------------------------------------------------------+--------------------------------------+----------+------------------------------------------------------------------+----------+
| uuid | source | klass | args | node | key | datetime | last_occurrence | dismissed | mail | text | id | level | formatted | one_shot |
+--------------------------------------+-----------------+------------------+--------------------+--------------+------------------------+---------------------------+---------------------------+-----------+--------+------------------------------------------------------------------+--------------------------------------+----------+------------------------------------------------------------------+----------+
| 59579a69-55a4-4cad-8d20-3bfceee2c4c5 | USBStorage | USBStorage | /dev/sr0 | Controller A | "/dev/sr0" | 2023-05-24T16:08:04+00:00 | 2023-09-19T19:06:48+00:00 | false | <null> | A USB storage device %r has been connected to this system. Pl... | 59579a69-55a4-4cad-8d20-3bfceee2c4c5 | CRITICAL | A USB storage device '/dev/sr0' has been connected to this sy... | false |
| a9a5ada0-0dde-42a0-b3c4-df878696e38a | | PoolUpgraded | tank | Controller A | "tank" | 2023-09-06T01:13:03+00:00 | 2023-09-06T01:13:03+00:00 | false | <null> | New ZFS version or feature flags are available for pool '%s'.... | a9a5ada0-0dde-42a0-b3c4-df878696e38a | WARNING | New ZFS version or feature flags are available for pool 'tank... | false |
| 949f4fd7-051a-481e-bdc0-d9dab216c9df | EnclosureStatus | EnclosureHealthy | R30 NVMe Enclosure | Controller A | ["R30 NVMe Enclosure"] | 2023-05-24T16:08:02+00:00 | 2023-09-19T19:06:48+00:00 | false | <null> | Enclosure (%s) is healthy. | 949f4fd7-051a-481e-bdc0-d9dab216c9df | INFO | Enclosure (R30 NVMe Enclosure) is healthy. | false |
| bd3afbac-fd91-4461-a346-6f05a8679d8b | | ScrubFinished | tank | Controller A | "tank" | 2023-09-03T07:00:08+00:00 | 2023-09-03T07:00:08+00:00 | false | <null> | Scrub of pool %r finished. | bd3afbac-fd91-4461-a346-6f05a8679d8b | INFO | Scrub of pool 'tank' finished. | true |
| 43f9025e-29c3-4a22-b95f-88186a4fd93b | | ScrubFinished | boot-pool | Controller A | "boot-pool" | 2023-09-18T10:45:04+00:00 | 2023-09-18T10:45:04+00:00 | false | <null> | Scrub of pool %r finished. | 43f9025e-29c3-4a22-b95f-88186a4fd93b | INFO | Scrub of pool 'boot-pool' finished. | true |
+--------------------------------------+-----------------+------------------+--------------------+--------------+------------------------+---------------------------+---------------------------+-----------+--------+------------------------------------------------------------------+--------------------------------------+----------+------------------------------------------------------------------+----------+
The list_categories command lists all types of alerts that the system can issue.
Using the List_Categories Command
The list_categories command has no required properties.
Enter the command then press Enter.
The command returns a table of alert types when successful.
From the CLI prompt, enter:
system alert list_categories
Command Example
system alert list_categories
+-------------------+-------------------------------------------------+---------+
| id | title | classes |
+-------------------+-------------------------------------------------+---------+
| APPLICATIONS | Applications | <list> |
| CERTIFICATES | Certificates | <list> |
| DIRECTORY_SERVICE | Directory Service | <list> |
| HA | High-Availability | <list> |
| HARDWARE | Hardware | <list> |
| KMIP | Key Management Interoperability Protocol (KMIP) | <list> |
| NETWORK | Network | <list> |
| REPORTING | Reporting | <list> |
| SHARING | Sharing | <list> |
| STORAGE | Storage | <list> |
| SYSTEM | System | <list> |
| TASKS | Tasks | <list> |
| UPS | UPS | <list> |
+-------------------+-------------------------------------------------+---------+
The list_policies command lists all possible alert policies. Alert policies indicate the frequency of the alerts.
Using the List_Policies Command
The list_policies command has no required properties.
Enter the command then press Enter.
The command returns a list of alert types when successful.
From the CLI prompt, enter:
system alert list_policies
The restore command dismisses alerts based on alert UUID.
Using the Restore Command
The restore command requires the UUID property.
Enter the command then press Enter.
The command returns a blank line when successful.
From the CLI prompt, enter:
system alert restore uuid="alertuuid"
Where alertuuid is the UUID of the alert you want to restore.
The service command allows you to view and modify alert services.
The service command has seven options, but can only run one at a time. Alert service command options are create, delete, get_instance, list_types, query, test, and update.
Creating an Alert Service
The service create command requires the name, type, attributes, level, and enabled properties.
Enter the command then press Enter.
The command returns a blank line when successful.
Service Create Properties
| Property | Required | Description | Syntax Example |
|---|---|---|---|
name | Yes | The name of the service. | name=name |
type | Yes | The service type. View all types using the system alert service list_types command. | type=Type |
attributes | Yes | Authentication attributes for the service. Required attributes vary depending on the service. Separate each attribute and value pair with a comma. | attributes={"attribute":"value","attribute":"value"} |
level | Yes | The alert level for the service. | level=LEVEL |
enabled | Yes | Whether or not to enable the service | enabled=true/false |
From the CLI prompt, enter:
system alert service create name=name type=type attributes={"attribute":"value"} level=LEVEL enabled=true/false
Where:
- name is the name you want to give the service.
- type is the service type.
- attributes are the authentication attributes for the service.
- level is the alert level you want to assign to the service.
- enabled turns the service on (true) or off (false).
Deleting an Alert Service
The service delete command requires the id property.
Enter the command then press Enter.
The command returns a blank line when successful.
From the CLI prompt, enter:
system alert service delete id=number
Where number is the ID number of the alert service you want to delete.
Viewing an Alert Service Instance
The service get_instance command requires the id property.
Enter the command then press Enter.
The command returns a table of settings for the identified alert service.
From the CLI prompt, enter:
system alert service get_instance id=number
Where number is the ID number of the alert service you want to view.
Listing Alert Service Types
The service list_types has no required properties.
Enter the command then press Enter.
The command returns a table of alert service types.
From the CLI prompt, enter:
system alert service list_types
Command Example
system alert service list_types
+------------+------------+
| name | title |
+------------+------------+
| AWSSNS | AWS SNS |
| Mail | Email |
| InfluxDB | InfluxDB |
| Mattermost | Mattermost |
| OpsGenie | OpsGenie |
| PagerDuty | PagerDuty |
| Slack | Slack |
| SNMPTrap | SNMP Trap |
| Telegram | Telegram |
| VictorOps | VictorOps |
+------------+------------+
Running a Basic Alert Service Query
The service query command has no required properties.
Enter the command then press Enter.
The command returns a table of alert services when successful.
From the CLI prompt, enter:
system alert service query
Command Example
system alert service query
+----+-----------+----------+------------+---------+---------+-------------+
| id | name | type | attributes | enabled | level | type__title |
+----+-----------+----------+------------+---------+---------+-------------+
| 1 | SNMP Trap | SNMPTrap | <dict> | true | WARNING | SNMP Trap |
| 2 | E-Mail | Mail | <dict> | true | WARNING | Email |
+----+-----------+----------+------------+---------+---------+-------------+
Running a Filtered Alert Service Query
Enter the service query command with one of the optional attributes to filter out other attributes from the query return.
See Query Attributes below for the list of seven available query attributes.
Enter the command string then press Enter.
The command returns a table with the specified attribute.
Query Attributes
| Attribute | Purpose |
|---|---|
id | Alert service ID number. |
name | Alert service name. |
type | Alert service type. |
attributes | Alert service authentication attributes. |
enabled | Whether service is enabled or disabled. |
level | Alert level for the service. |
type__title | Alert service type name. |
From the CLI prompt, enter:
system alert service query attribute
Where attribute is the query attribute you want to filter for.
Sending an Alert Service Test Alert
The service test command with requires the alert_services_create argument with the name, type, and level attributes.
Enter the command string then press Enter.
The command returns true or false depending on if the test alert succeeded or not.
From the CLI prompt, enter:
system alert service test alert_services_create{“name”:"name", “type”:"type", “level”:"LEVEL"}
Where:
- name is the alert service name.
- type is the service type.
- level is the alert level for the service.
Updating an Alert Service
The update command requires entering id and has five optional properties.
See Update Command Properties below for details.
After specifying the id of the alert service you want to update, you must include at least one property to update.
Enter the command string, then press Enter.
The command returns nothing when successful.
Update Command Properties
| Attribute | Purpose |
|---|---|
id | Alert service ID number. |
name | Alert service name. |
type | Alert service type. |
attributes | Alert service authentication attributes. |
level | Alert level for the service. |
enabled | Whether service is enabled or disabled. |
From the CLI prompt, enter:
storage disk update id=number property=option
Where:
- number is the ID number of the alert service you want to update.
- option is any of the properties listed in the Update Command Properties table above.
Related Content
SCALE Tutorials
SCALE UI Reference
Have more questions?
For further discussion or assistance, see these resources:
- TrueNAS Community Forum
- TrueNAS Community Discord
- iXsystems Enterprise Support (requires paid support contract)
Found content that needs an update? You can suggest content changes directly! To request changes to this content, click the Feedback button located on the middle-right side of the page (might require disabling ad blocking plugins).