TrueNAS SCALE Version Documentation
This content follows the TrueNAS SCALE 23.10 (Cobia) releases. Use the Product and Version selectors above to view content specific to different TrueNAS software or major version.
Alert
10 minute read.
Last Modified 2024-03-19 08:38 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).
The class command allows you to view and update the default 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
system alert class config
+---------+--------+
| id | 1 |
| classes | <dict> |
+---------+--------+
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.
system alert class update classes={"UPSBatteryLow":{"level":"INFO","policy":"HOURLY"}}
The dismiss command dismisses alerts based on alert UUID.
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.
dismiss uuid="59579a69-55a4-4cad-8d20-3bfceee2c4c5"
The list command lists all types of alerts including active and dismissed currently in the system.
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
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.
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
system alert list_categories
+-------------------+-------------------------------------------------+---------+
| id | title | classes |
+-------------------+-------------------------------------------------+---------+
| APPLICATIONS | Applications | <list> |
| CERTIFICATES | Certificates | <list> |
| CLUSTERING | Clustering | <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.
The restore command dismisses alerts based on alert UUID.
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.
restore uuid="59579a69-55a4-4cad-8d20-3bfceee2c4c5"
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.
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.
| 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).
service create name=NewAlertService type=PagerDuty attributes={"service_key":"u+Pgbsif8kE5rH5fzpXQ","client_name":"clientname"} level=INFO enabled=false
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.
system alert service delete id=1
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.
system alert service get_instance id=1
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
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 |
+------------+------------+
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
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 |
+----+-----------+----------+------------+---------+---------+-------------+
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.
| 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.
system alert service query name
+-----------+
| name |
+-----------+
| SNMP Trap |
| E-Mail |
+-----------+
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.
system alert service test alert_service_create={"name":"E-Mail","type":"Mail","level":"WARNING"}
true
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.
| 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.
system alert service update id=1 Name=NewName type=Mail attributes={"email":"newemail@mail.com"} level=INFO enabled=true
Related CLI System Articles
Related Alert Articles
Have more questions or want to discuss your specific configuration? 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).