General Information

Full List

Obsolete

API Call Basics

There are 4 basic pieces of an API request:

• Namespace: Top-level subsystem to access
• Name: Lower-level subsystem to access
• ID: (Websocket only) Used for correlating a request with a reply (Websocket connections are asynchronous - replies may come back in a different order than they were requested)
• Arguments: JSON Object containing additional information for the request/reply

HTTP Connections

• URL: http[s]://[system_IP]/api
• Supported Verbs: "PUT", "POST", "GET", "HEAD", and "OPTIONS"

GET [namespace]/[name] [HTTP Version]
Authorization: basic [base-64 encoded "[user]:[pass]"]
{
[Additional JSON Arguments]
}

Example of using curl to sent a TCP/REST request:

WebSocket Connections

• URL: ws[s]://[system_IP]/websocket
• The rpc/auth or rpc/auth_token API call must be the first one sent in after establishing the connection in order to login and allow access to the rest of the APIs.
• The rpc/auth_clear API can be used to logout when done.

{
"namespace" : "[namespace]",
"name" : "[name]",
"id" : "[some_unique_id]",
"args" : [Additional JSON Arguments]
}

Error Detection

{
"namespace":"error",
"name":"error",
"id":"same_id_as_request",
"args": {
 "code":"404",
 "message":"Not Found"
 }
}

Changes in this Release

API Calls

[Obsolete] alertplugins/add

Install a new alert plugin

Required Arguments

• plugins: (string or JSON array of strings)Name of the plugin(s) to install.

Optional Arguments

• None

Examples

{
 "plugins": "smtp-email"
}

{
 "smtp-email": "Text of installation process"
}

Changelog

• v2.0
• All alert plugins are now built-in and no longer dynamically added/removed.

alertplugins/change_settings

Modify the settings for alert plugins. Note that each plugin's settings are managed independently of each other, but must be updated in bulk (all of the settings for a single plugin must be submitted at the same time, even of some of those settings are unchanged from previous).

Required Arguments

• [plugin-name]: (JSON Object)Settings object for the listed plugin.
• delete_[plugin-name]: (boolean)Delete the settings for the listed plugin.

Optional Arguments

• None

Examples

{
 "delete_Plugin_A": true,
 "smtp-email": {
  "auth_pass": "MySamplePassword01",
  "auth_type": "plain",
  "auth_user": "example@example.net",
  "bcc": null,
  "cc": null,
  "from": "no-reply@truecommand.io",
  "mailserver": "smtp.gmail.com",
  "mailserver_port": 587,
  "subject": "TrueCommand Alert Notice",
  "to": [
   "example@example.net"
  ]
 }
}

{
 "result": "success"
}

Changelog

• v2.0
• The 'delete_[plugin-name]' arguments were added, replacing the 'null' value submission to delete a plugin configuration.

[Obsolete] alertplugins/check_updates

Scan all the installed notification plugins and see if any updates are available. This returns an object of plugins where the remote version is newer than the locally-installed version.

Required Arguments

• None

Optional Arguments

• None

Examples

{}

{
 "smtp-email": {
  "date_released": "2019-07-19",
  "description": "Send email alerts via SMTP.",
  "icon_url": "",
  "name": "smtp-email",
  "repository": "ix-alertme",
  "summary": "Email alerts",
  "tags": [
   "email",
   "ssmtp",
   "sendmail",
   "plaintext"
  ],
  "version": "1.0"
 }
}

Changelog

• v2.0
• All alert plugins are now built-in and no longer dynamically added/removed.

alertplugins/current_settings

Return all the current settings for alert plugins for the current user.

Required Arguments

• None

Optional Arguments

• plugins: (string of JSON array of strings)Only return the settings for these plugins.

Examples

{
 "plugins": "smtp-email"
}

{
 "smtp-email": {
  "auth_pass": "----",
  "auth_type": "plain",
  "auth_user": "example@example.net",
  "bcc": null,
  "cc": null,
  "from": "no-reply@truecommand.io",
  "mailserver": "smtp.gmail.com",
  "mailserver_port": 587,
  "subject": "TrueCommand Alert Notice",
  "to": [
   "example@example.net"
  ]
 }
}

Changelog

• v2.0
• Sensitive settings (such as passwords), no longer get obfuscated in this API return. This permits confirmation of saved settings now.

alertplugins/list

List all the alert provider plugins that are currently available.

Required Arguments

• None

Optional Arguments

• None

Examples

{}

{
 "smtp-email": {
  "api": [
   {
    "default": null,
    "fieldname": "mailserver",
    "is_array": false,
    "is_required": true,
    "summary": "Address for the SMTP server",
    "type": "string"
   },
   {
    "default": null,
    "fieldname": "mailserver_port",
    "is_array": false,
    "is_required": true,
    "summary": "Port number for the SMTP server",
    "type": [
     "int",
     1,
     65535
    ]
   },
   {
    "default": null,
    "fieldname": "auth_type",
    "is_array": false,
    "is_required": true,
    "summary": "Type of authentication to SMTP server",
    "type": [
     "list",
     [
      "plain",
      "Username/password authentication"
     ],
     [
      "none",
      "No authentication"
     ]
    ]
   },
   {
    "default": null,
    "fieldname": "auth_user",
    "is_array": false,
    "is_required": false,
    "summary": "Username for plain authentication",
    "type": ""
   },
   {
    "default": null,
    "fieldname": "auth_pass",
    "is_array": false,
    "is_required": false,
    "summary": "Password for plain authentication",
    "type": ""
   },
   {
    "default": null,
    "fieldname": "from",
    "is_array": false,
    "is_required": true,
    "summary": "Email address to send from",
    "type": [
     "regex",
     "[^@]+@[.]+"
    ]
   },
   {
    "default": null,
    "fieldname": "to",
    "is_array": true,
    "is_required": true,
    "summary": "Email addresses to send to",
    "type": [
     "regex",
     "[^@]+@[.]+"
    ]
   },
   {
    "default": null,
    "fieldname": "subject",
    "is_array": false,
    "is_required": true,
    "summary": "Subject line for the email",
    "type": ""
   }
  ],
  "date_released": "2019-07-19",
  "description": "Send email alerts via SMTP.",
  "exec": "smtp-email",
  "icon_url": "",
  "name": "smtp-email",
  "summary": "Email alerts",
  "tags": [
   "email",
   "ssmtp",
   "sendmail",
   "plaintext"
  ],
  "version": "1.0"
 }
}

Changelog

• v2.0
• Supported fields/settings for the 'smtp-email' plugin changed significantly. Run this API to see the current 'api' fields.

[Obsolete] alertplugins/remove

Remove an existing alert plugin.

Required Arguments

• plugins: (string or JSON array of strings)Name of the plugin(s) to remove.

Optional Arguments

• None

Examples

{
 "plugins": "smtp-email"
}

{
 "smtp-email": "Text output of removal"
}

Changelog

• v2.0
• All alert plugins are now built-in and no longer dynamically added/removed.

[Obsolete] alertplugins/search

Search for plugins that are available to install

Required Arguments

• None

Optional Arguments

• None

Examples

{}

{
 "smtp-email": {
  "date_released": "2019-07-19",
  "description": "Send email alerts via SMTP.",
  "icon_url": "",
  "name": "smtp-email",
  "repository": "ix-alertme",
  "summary": "Email alerts",
  "tags": [
   "email",
   "ssmtp",
   "sendmail",
   "plaintext"
  ],
  "version": "1.0"
 }
}

Changelog

• v2.0
• All alert plugins are now built-in and no longer dynamically added/removed.

alertplugins/test

This will send a test alert to the current user. An individual plugin can be specified or the test can be sent through all configured plugins for the current user.

Required Arguments

• plugin: (string)Name of a single plugin to test.

Optional Arguments

• settings: (JSON Object)Custom settings object to use for the test instead of using the currently-saved configuration for the user.

Examples

{
 "plugin": "smtp-email"
}

{
 "result": "Error/Confirmation message for the test"
}

Changelog

• v2.0
• 'plugin' input argument moved from optional to required

[Obsolete] alertplugins/update

Update an existing alert notification plugin.

Required Arguments

• plugins: (string or JSON array of strings)Name of the plugin(s) to update.

Optional Arguments

• None

Examples

{
 "plugins": "smtp-email"
}

{
 "smtp-email": "Text output of update procedure"
}

Changelog

• v2.0
• All alert plugins are now built-in and no longer dynamically added/removed.

alerts/add

Create a new alert rule. The user making the request must either be an administrator, or be granted alert-creation permission via the user or team settings. The creator of an alert rule is also automatically tagged as the owner of the rule. This grants permission to edit/delete the rule even if the user is not an administrator.

Required Arguments

• name: (string)User-visible text/nickname for this rule. Useful for easily identifying rules.
• priority: (string)One of the following options: 'critical', 'warning', or 'information'.
• triggers: (JSON array of objects)Each object may contain the following fields:
• average_over_minutes: (integer)Use the average value of the measurement over this time period.
• Default value: 1
• metric: (string)Data category to scan for alert trigger.
• See the data/list_fields API for a list of available identifiers.
• field: (string)Data value to scan for alert trigger within the metric category.
• Default Value: 'avg'
• The 'total' and 'avg' fields are always supported.
• comparison: (string)One of the following options: 'equals', 'not_equals', 'less_than', 'not_less_than', 'greater_than', 'not_greater_than', 'contains', 'not_contains'.
• value: (number)Specific number for comparison.
• The logical sentance is always: [metric / field] [comparison] [value]
• Example: 'memory_used_percent' 'total' 'greater_than' 90

Optional Arguments

• isactive: (boolean)This alert rule should be active and used
• tags: (JSON array of strings)List of search tags.
• text: (string)Custom text to display as the visual description of the alert when it is triggered.
• needall: (boolean)If multiple conditions are listed, all of them must be matched before the alert itself is triggered.
• Default Value: true - all conditions must be met for the alert rule to trigger.
• A 'true' value corresponds to an 'AND' operation, while a 'false' value corresponds to an 'OR' operation
• owner: (string)User ID for a non-administrator account that also has ownership permissions for this alert rule.
• Note: Only an administration account can change the 'owner' property of an alert rule.

Examples

{
 "name": "Custom Rule 1",
 "priority": "warning",
 "triggers": [
  {
   "average_over_minutes": 10,
   "comparison": "greater_than",
   "field": "total",
   "metric": "memory_used_percent",
   "value": 99
  }
 ]
}

{
 "caid": "new_alert_rule_id",
 "result": "success"
}

Changelog

• v1.1
• Owner field added. Non-admins may now create alerts if granted permission.
• v2.0
• Input/Output format changed. Uses the new 'triggers' object array which replaces the individual 'alerttype', 'source', and 'value' arrays.

alerts/edit

Modify a custom alert rule. The user making the request must either be an administrator, or be listed as the 'owner' of the designated alert rule.

Required Arguments

• caid: (string)Custom Alert ID

Optional Arguments

• tvid: (string)Only apply this rule to the specified system.
• Default Value: '', which means to apply to all systems
• name: (string)User-visible text/nickname for this rule. Useful for easily identifying rules.
• priority: (string)One of the following options: 'critical', 'warning', or 'information'.
• isactive: (boolean)This alert rule should be active and used
• tags: (JSON array of strings)List of search tags.
• text: (string)Custom text to display as the visual description of the alert when it is triggered.
• needall: (boolean)If multiple conditions are listed, all of them must be matched before the alert itself is triggered.
• Default Value: true - all conditions must be met for the alert rule to trigger.
• A 'true' value corresponds to an 'AND' operation, while a 'false' value corresponds to an 'OR' operation
• owner: (string)User ID for a non-administrator account that also has ownership permissions for this alert rule.
• Note: Only an administration account can change the 'owner' property of an alert rule.
• triggers: (JSON array of objects)Each object may contain the following fields:
• average_over_minutes: (integer)Use the average value of the measurement over this time period.
• Default value: 1
• metric: (string)Data category to scan for alert trigger.
• See the data/list_fields API for a list of available identifiers.
• field: (string)Data value to scan for alert trigger within the metric category.
• Default Value: 'avg'
• The 'total' and 'avg' fields are always supported.
• comparison: (string)One of the following options: 'equals', 'not_equals', 'less_than', 'not_less_than', 'greater_than', 'not_greater_than', 'contains', 'not_contains'.
• value: (number)Specific number for comparison.
• The logical sentance is always: [metric / field] [comparison] [value]
• Example: 'memory_used_percent' 'total' 'greater_than' 90

Examples

{
 "caid": "alert_rule_1",
 "text": "System alert triggered! alert_rule_1"
}

{
 "alert_rule_1": {
  "caid": "alert_rule_1",
  "isactive": true,
  "name": "Custom Rule 1",
  "owner": "user_id_2",
  "priority": "warning",
  "text": "System alert triggered! alert_rule_1",
  "triggers": [
   {
    "average_over_minutes": 10,
    "comparison": "greater_than",
    "field": "total",
    "metric": "memory_used_percent",
    "value": 99
   }
  ],
  "tvid": ""
 }
}

Changelog

• v1.1
• Owner field added. Non-admins may now edit alerts where they are tagged as the owner.
• v2.0
• Input/Output format changed. Uses the new 'triggers' object array which replaces the individual 'alerttype', 'source', and 'value' arrays.

alerts/list

List all the alert rules that are currently defined.

Required Arguments

• None

Optional Arguments

• tvid: (string or JSON array of strings)Only show the alert rules that impact the designated system(s).
• active_only: (boolean)Only return active alert rules (default: false)

Examples

{
 "tvid": [
  "server_id_1",
  "server_id_2"
 ]
}

{
 "alert_rule_1": {
  "caid": "alert_rule_1",
  "isactive": true,
  "name": "Custom Rule 1",
  "owner": "user_id_1",
  "priority": "warning",
  "triggers": [
   {
    "comparison": "less_than",
    "source": "memory%free_percent",
    "value": "10"
   }
  ],
  "tvid": ""
 },
 "alert_rule_2": {
  "caid": "alert_rule_2",
  "isactive": false,
  "name": "Custom Rule 2",
  "owner": "user_id_4",
  "priority": "critical",
  "triggers": [
   {
    "comparison": "less_than",
    "source": "memory%free_percent",
    "value": "5"
   }
  ],
  "tvid": "server_id_1"
 }
}

Changelog

• v2.0
• Output format changed. Uses the new 'triggers' object array.

alerts/remove

Delete an existing alert rule. The user making the request must either be an administrator, or be listed as the 'owner' of the designated alert rule. Internal alert rules cannot be deleted, those can only be set inactive with the alerts/edit API.

Required Arguments

• caid: (string)ID of the custom alert to remove.

Optional Arguments

• None

Examples

{
 "caid": "alert_rule_1"
}

{
 "result": "success"
}

cluster/db_backup

Initiate a backup of the configuration database from specific NASs. This is automatically performed when database changes are detected by TrueCommand, and does not typically need to be started manually.

Required Arguments

• tvid: (string or JSON array of strings)Backup these system(s).

Optional Arguments

• None

Examples

{
 "tvid": "1da1363e-98ac-481c-a47d-54b87bfecbcd"
}

{
 "started_backup": [
  "1da1363e-98ac-481c-a47d-54b87bfecbcd"
 ]
}

cluster/db_delete

Delete backup configuration database file(s). This can only be performed for systems that the user has write access to. All other systems will be ignored.

Required Arguments

• db_id: (string or JSON array of strings)ID of the database backup(s) that should be deleted.

Optional Arguments

• None

Examples

{
 "db_id": "sasdkjasdtf733"
}

{
 "removed": [
  "sasdkjasdtf733"
 ],
 "result": "success"
}

cluster/db_list

Return a list of all the NAS database backups that are stored on TrueCommand. This can only be performed for systems that the user has write access to. All other systems will be ignored.

Required Arguments

• None

Optional Arguments

• tvid: (string or JSON array of strings)Only show backups of these system(s).

Examples

{
 "tvid": "1da1363e-98ac-481c-a47d-54b87bfecbcd"
}

{
 "db_list": [
  {
   "date": "2019-10-09",
   "id": "adfkjysjb434rjb8",
   "tvid": "1da1363e-98ac-481c-a47d-54b87bfecbcd",
   "version": "FreeNAS-11.2-U6"
  },
  {
   "date": "2021-04-10",
   "id": "adsfgjhzv876234bf7",
   "tvid": "1da1363e-98ac-481c-a47d-54b87bfecbcd",
   "version": "FreeNAS-11.3-U5"
  }
 ]
}

cluster/db_restore

Restore a saved configuration database to a specific system or group of systems. This can only be performed for systems that the user has write access to. All other systems will be ignored.

Required Arguments

• db_id: (string)ID of the configuration backup that you wish to restore.
• tvid: (string or JSON array of strings)Apply the backup configuration database to these system(s).

Optional Arguments

• None

Examples

{
 "db_id": "asdgjh42478b",
 "tvid": "1da1363e-98ac-481c-a47d-54b87bfecbcd"
}

{
 "ids_failed": [],
 "ids_restoring": [
  "1da1363e-98ac-481c-a47d-54b87bfecbcd"
 ],
 "nicknames_failed": [],
 "nicknames_restoring": [
  "System 1"
 ],
 "restoring_to": "asdgjh42478b"
}

data/current_stats

This will return the latest data for the designated systems (or all systems user has read permission for if particular systems are not specified). The data object for each system is identical to the format used by the 'data/retrieve' API call, but only contains the most recent data point. The default behavior only returns a pruned-down list of the stats from the system. To retrieve the entire stats object, you will need to enable the optional 'full_stats' flag.

Required Arguments

• None

Optional Arguments

• tvid: (string or JSON array of strings)Only return stats for these system IDs.
• raw_stats: (boolean)Return the raw information from the NAS instead of the compressed version. (False by default)

Examples

{
 "tvid": "system_id_1"
}

{
 "system_id_1": {
  "cpu": {},
  "cpu_temp": {},
  "disks": {},
  "jails": {},
  "memory": {},
  "network": {},
  "services": {},
  "storage": {},
  "system_info": {},
  "time_t": 1544629127,
  "vms": {}
 }
}

Changelog

• v1.3
• Optional 'summaries' flag added.
• v2.0
• Optional flags 'full_stats' and 'summaries' removed.

[Obsolete] data/curve_fit

Calculate a line or point from real data, and perform interpolations or extrapolations as desired.

Required Arguments

• x-data: (JSON array of numbers)X-axis coordinate points for real data (must be same length as 'y-data' list).
• y-data: (JSON array of numbers)Y-axis coordinate points for real data (must be same length as 'x-data' list).

Optional Arguments

• find-y-for-x: (JSON array of numbers)Array of X values in which to report points for the fitted-curve. (Will calculate associated Y values for each point)
• Default Value: Will automatically return curve points using the same 'x-data' coordinate points, but Y values are adjusted to fit the curve.
• find-x-for-y: (JSON array of numbers)Array of Y values in which to report points for the fitted-curve. (Will calculate associated X values for each point)
• Default Value: This will replace the 'find-y-for-x' default value.
• extrapolate-y-for-x: (Number)Extra X coordinate point with which to calculate Y (can be used in conjunction with the 'find-x-for-y' optional input).
• extrapolate-x-for-y: (Number)Extra Y coordinate point with which to calculate X (can be used in conjunction with the 'find-y-for-x' optional input).

Examples

{
 "extrapolate-x-for-y": 100,
 "find-y-for-x": [
  10,
  11,
  12
 ],
 "x-data": [
  0,
  1,
  2,
  3,
  4,
  5,
  6,
  7,
  8
 ],
 "y-data": [
  0,
  2,
  4,
  6,
  8,
  10,
  12,
  14,
  16
 ]
}

{
 "curve_fits": {
  "x-data": [
   10,
   11,
   12,
   50
  ],
  "y-data": [
   20,
   22,
   24,
   100
  ]
 }
}

{
 "extrapolate-x-for-y": 100,
 "x-data": [
  0,
  1,
  2,
  3,
  4,
  5,
  6,
  7,
  8
 ],
 "y-data": [
  0,
  2,
  4,
  6,
  8,
  10,
  12,
  14,
  16
 ]
}

{
 "curve_fits": {
  "x-data": [
   0,
   1,
   2,
   3,
   4,
   5,
   6,
   7,
   8,
   50
  ],
  "y-data": [
   0,
   2,
   4,
   6,
   8,
   10,
   12,
   14,
   16,
   100
  ]
 }
}

data/list_fields

List all the types of data which are available for particular server(s). The available data is always broken up into a 2-step format: 'Measurements': (also called 'metrics') These act as the categories of numbers and determine what type of number/units are provided. 'Fields': The specific number. The 'total' and 'avg' fields are always valid, but there may be system-specific fields available as well (such as for specific disks, network interfaces, storage pools, etc).

Required Arguments

• None

Optional Arguments

• tvid: (string)ID of the specific system to scan for fields.

Examples

{}

[
 "net_in_kbps",
 "net_out_kbps",
 "net_total_kbps",
 "net_used_percent",
 "cpu_used_percent",
 "cpu_temperature",
 "zfs_arc_used_percent",
 "zfs_arc_miss_percent",
 "disk_busy_percent",
 "disk_read_ops_per_sec",
 "disk_write_ops_per_sec",
 "disk_read_bytes_per_sec",
 "disk_write_bytes_per_sec",
 "memory_used_percent",
 "storage_pool_usage_percent",
 "storage_pool_usage_bytes",
 "storage_pool_total_bytes"
]

{
 "tvid": "server_id_1"
}

{
 "cpu_temperature": {
  "avg": "float32",
  "total": "float32"
 },
 "cpu_used_percent": {
  "avg": "float32",
  "total": "float32"
 },
 "disk_busy_percent": {
  "avg": "float32",
  "total": "float32"
 },
 "disk_read_bytes_per_sec": {
  "avg": "float32",
  "total": "float32"
 },
 "disk_read_ops_per_sec": {
  "avg": "float32",
  "total": "float32"
 },
 "disk_write_bytes_per_sec": {
  "avg": "float32",
  "total": "float32"
 },
 "disk_write_ops_per_sec": {
  "avg": "float32",
  "total": "float32"
 },
 "memory_used_percent": {
  "avg": "float32",
  "total": "float32"
 },
 "net_in_kbps": {
  "avg": "float32",
  "total": "float32"
 },
 "net_out_kbps": {
  "avg": "float32",
  "total": "float32"
 },
 "net_total_kbps": {
  "avg": "float32",
  "total": "float32"
 },
 "net_used_percent": {
  "avg": "float32",
  "total": "float32"
 },
 "storage_pool_total_bytes": {
  "avg": "float32",
  "pool2": "float32",
  "pool_1": "float32",
  "total": "float32"
 },
 "storage_pool_usage_bytes": {
  "avg": "float32",
  "pool2": "float32",
  "pool_1": "float32",
  "total": "float32"
 },
 "storage_pool_usage_percent": {
  "avg": "float32",
  "pool2": "float32",
  "pool_1": "float32",
  "total": "float32"
 },
 "zfs_arc_miss_percent": {
  "avg": "float32",
  "total": "float32"
 },
 "zfs_arc_used_percent": {
  "avg": "float32",
  "total": "float32"
 }
}

Changelog

• v2.0
• Optional 'tvid' input changed to a string only (no more lists).
• Optional flags 'with_type', 'filter_type', and 'ui_format' removed.

data/retrieve

Retrieve data from specified servers/fields.

Required Arguments

• tvid: (string)ID of the system to scan for data.

Optional Arguments

• time_start: (int64)Unix timestamp of the start time (seconds since epoch)
• Default: 1 hour ago is the start time
• time_stop: (int64)Unix timestamp of the stop time (seconds since epoch)
• Default: Uses the current time as the end time
• metrics: (JSON array of strings)List of measurements to return. See 'data/list_fields' for options.
• Default: Returns all available metrics
• Note: This always returns the 'avg' field for the given measurements.

Examples

{
 "metrics": [
  "disk_busy_percent"
 ],
 "tvid": "server_id_1"
}

{
 "disk_busy_percent": [
  0.010078575,
  0.00096163,
  0.005286186,
  0.024224812,
  0.0057681757,
  0.0148801,
  0.0014428925,
  0.01491251
 ],
 "time_t": [
  1621878796,
  1621878856,
  1621878916,
  1621878977,
  1621879037,
  1621879097,
  1621879157,
  1621879217
 ]
}

Changelog

• v2.0
• 'tvid' input changed to string-only (dropped []string support).
• 'time_start' and 'time_end' input formats changed to Unix timestamp only.
• 'raw_objects' input option removed.
• 'data_list' input option removed (replaced by 'metrics' option).

[Obsolete] external/submit_alerts

API hook for external systems to submit alert notices to TrueCommand. This requires that the external system use a valid system auth token to submit the API call over HTTP. **Note:** This works for both 'external' types of systems as well as FreeNAS/TrueNAS systems. It just needs a valid auth token which associates the API request with a currently-registered system. **Note 2:** This will NOT work with websocket connections. HTTP API submissions only.

Required Arguments

• [alert_id]: (JSON Object of alert info)

Optional Arguments

• None

Examples

{
 "external_alert_1": {
  "source": "external_alert_system_XYZ",
  "text": "This is a test of alert system XYZ forwarding to TrueCommand",
  "time_t": "1565274547",
  "type": "warning"
 }
}

{
 "result": "success"
}

[Obsolete] external/submit_stats

API hook for external systems to submit statistics to TrueCommand. This requires that the external system use a valid system auth token to submit the API call over HTTP. **Note:** This works for both 'external' types of systems as well as FreeNAS/TrueNAS systems. It just needs a valid auth token which associates the API request with a currently-registered system. **Note 2:** This will NOT work with websocket connections. HTTP API submissions only.

Required Arguments

• hostname: (string)
• cpu: (JSON Array of objects - one per CPU)
• memory: (JSON Object of memory fields)
• network: (JSON Array of objects - one per interface)
• storage: (JSON Object of storage fields)
• version: (string)
• uptime_seconds: (number)

Optional Arguments

• disk: (JSON Array of objects - one per disk)
• timezone: (string)
• model: (string)

Examples

{
 "cpu": [
  {
   "idle": 60,
   "system": 25,
   "user": 15
  }
 ],
 "hostname": "1.2.3.4",
 "memory": {
  "active-pages": 35654568,
  "bytes-per-page": 256,
  "cache-hit-percent": 23,
  "free-bytes": 12885465088,
  "inactive-pages": 234980
 },
 "network": [
  {
   "KB/s in": 13568,
   "KB/s out": 2036,
   "name": "igb0"
  }
 ],
 "storage": {
  "total-bytes": 32098409238230,
  "used-bytes": 430984030458
 },
 "uptime_seconds": 518799978,
 "version": "2.7.6"
}

{
 "result": "success"
}

license/check

Check whether the current license is expired or already reached.

Required Arguments

• None

Optional Arguments

• None

Examples

{}

{
 "custom_license_valid": false,
 "disks_over_limit": false,
 "license_expired": false
}

license/gettvuid

Return the unique system ID for the TrueCommand instance.

Required Arguments

• None

Optional Arguments

• None

Examples

{}

{
 "system_id": "my_unique_system_id"
}

license/info

Return the information contained within the current license.

Required Arguments

• None

Optional Arguments

• None

Examples

{}

{
 "current_disks": 10,
 "current_systems": 3,
 "license": {
  "contact": {
   "sales_email": "sales@ixsystems.com",
   "sales_phone": "1-408-943-4100",
   "support_email": "support@ixsystems.com",
   "support_phone": "1-408-943-4100"
  },
  "license": {
   "id": "license_id_string",
   "name": "Default License",
   "system_id": "compatible_system_id"
  },
  "limits": {
   "max_disks": 50,
   "max_systems": 50
  }
 }
}

license/register

Register a new license with TrueCommand. Not valid for the cloud-based version of TrueCommand.

Required Arguments

• license_file_contents: (string)Contents of the license file encapsulated as a string (file contents are already base64-encoded and can just be read/passed through as text).

Optional Arguments

• None

Examples

{
 "license_file_contents": "contents_of_the_license_file_on_client_system"
}

{
 "result": "success"
}

logs/search

Search through the system logs and return results

Required Arguments

• None

Optional Arguments

• time_start: (int64)Unix time (secs since epoch) for search start
• Default value: 1 month ago
• time_end: (int64)Unix time (secs since epoch) for search end
• Default value: current time
• uuid: (string)Filter results to show changes by this user only.
• header: (string or JSON array of strings)Filter results to show entries associated with these API calls only.

Examples

{
 "header": "users/add",
 "uuid": "user_uuid"
}

{
 "logs": [
  {
   "header": "users/add",
   "summary": {
    "field": "info"
   },
   "timestamp": "\u003cISO 8601 date format (yyyy-MM-ddThh:mm:ssZ)\u003e",
   "uuid": "user_uuid"
  },
  {
   "header": "users/add",
   "summary": {
    "field": "info"
   },
   "timestamp": "\u003cISO 8601 date format (yyyy-MM-ddThh:mm:ssZ)\u003e",
   "uuid": "user_uuid"
  }
 ],
 "logs_end": 1621961367,
 "logs_start": 1619369367
}

notices/add_comment

Add a comment to an alert notice. This can be done for any notice, even ones that have been marked as resolved.

Required Arguments

• aid: (string)ID for the alert notice to comment on
• comment: (string)Text to add as a comment

Optional Arguments

• None

Examples

{
 "aid": "3",
 "comment": "Anybody looking into this?"
}

{
 "3": {
  "aid": "3",
  "alert_rule": {
   "alerttype": "less_than",
   "caid": "alert_rule_4",
   "dataset": "value",
   "isactive": true,
   "priority": "warning",
   "source": "memory",
   "tvid": "",
   "type": "memory-free",
   "value": "20%"
  },
  "caid": "alert_rule_4",
  "comments": [
   "[20180102T15:32:55Z](admin_1) Anybody looking into this?"
  ],
  "priority": "warning",
  "resolved": false,
  "resolved_by": "",
  "resolved_time": "",
  "source": "memory",
  "system_time_triggered": [
   1104541261
  ],
  "tvid": "server_id_1"
 }
}

notices/create_fake

This is a way to automatically create a 'fake' alert notice for QA testing.

Required Arguments

• tvid: (string)ID of the system which 'triggered' the fake alert.
• caid: (string)ID of the alert rule that will be used as the trigger for the notice.

Optional Arguments

• None

Examples

{
 "caid": "alert_rule_1",
 "tvid": "system_id_1"
}

{
 "aid": "test-4",
 "result": "success"
}

notices/delete

Delete an alert notice in its entirety. There is no way to recover an alert notice that has been deleted, so this should be handled with extreme care.

Required Arguments

• aid: (string or JSON array of strings)Notice ID(s) to delete

Optional Arguments

• None

Examples

{
 "aid": "3"
}

{
 "result": "success"
}

notices/delete_comment

Delete a comment from an alert notice. This can be done for any notice, even ones that have been marked as resolved.

Required Arguments

Optional Arguments

• None

Examples

{
 "aid": "3",
 "comment": [
  "[20180102T15:32:55Z](admin_1)"
 ]
}

{
 "3": {
  "aid": "3",
  "alert_rule": {
   "alerttype": "less_than",
   "caid": "alert_rule_4",
   "dataset": "value",
   "isactive": true,
   "priority": "warning",
   "source": "memory",
   "tvid": "",
   "type": "memory-free",
   "value": "20%"
  },
  "caid": "alert_rule_4",
  "comments": [],
  "priority": "warning",
  "resolved": false,
  "resolved_by": "",
  "resolved_time": "",
  "source": "memory",
  "system_time_triggered": [
   1104541261
  ],
  "tvid": "server_id_1"
 }
}

notices/list

List alert notices for systems that the user can view.

Required Arguments

• None

Optional Arguments

• tvid: (string or JSON array of strings)Restrict the search to notices about the specified systems. Default value is to search for notices from all systems the current user can view (read access).
• all_notices: (boolean)Return notices that have been marked as resolved. (False by default)
• count: (integer)Maximum limit for the number of notices returned
• limit_datetime: (int64)Unix timestamp (seconds since epoch) providing a date/time cutoff for the search (default value: current date/time)
• newer_than_datetime: (boolean)Return notices newer than the datetime cutoff (default: false - older than cutoff)

Examples

{
 "all_notices": true,
 "tvid": "server_id_1"
}

{
 "1": {
  "aid": "1",
  "alert_notice_created_time_t": 504925265,
  "alert_rule": {
   "alerttype": "less_than",
   "caid": "alert_rule_4",
   "isactive": true,
   "priority": "warning",
   "source": "memory%free_percent",
   "tvid": "",
   "value": "20"
  },
  "caid": "alert_rule_4",
  "comments": [
   "[20170620T11:50:05Z](admin_4) I got this",
   "[20170620T11:51:42Z](admin_2) Sure thing",
   "[20170620T12:02:05Z](admin_4) Fixed - just needed to restart Samba to free up a stale memory cache"
  ],
  "last_update_time": "20170619T12:02:375Z",
  "priority": "warning",
  "resolved": true,
  "resolved_by": "user_id_4",
  "resolved_time": "20170620T12:02:05Z",
  "source": "memory%free_percent",
  "system_time_triggered": [
   504925261,
   504925335
  ],
  "tvid": "server_id_1",
  "users_notified": [
   "user_id_5",
   "user_id_2"
  ]
 },
 "3": {
  "aid": "3",
  "alert_notice_created_time_t": 1104541266,
  "alert_rule": {
   "alerttype": "less_than",
   "caid": "alert_rule_4",
   "isactive": true,
   "priority": "warning",
   "source": "memory%free_percent",
   "tvid": "",
   "value": "20"
  },
  "caid": "alert_rule_4",
  "comments": [
   "[20180102T15:32:55Z](admin_1) Anybody looking into this?"
  ],
  "last_update_time": "20180101T12:02:375Z",
  "priority": "warning",
  "resolved": false,
  "resolved_by": "",
  "resolved_time": "",
  "source": "memory%free_percent",
  "system_time_triggered": [
   1104541261
  ],
  "tvid": "server_id_1",
  "users_notified": [
   "user_id_1",
   "user_id_3"
  ]
 }
}

Changelog

• v2.0
• The 'limit_datetime' input format changed to Unix timestamp only.
• The 'sort_ascending_time' optional flag was removed. Always returns list sorted in ascending order now.

notices/set_resolved

Mark an alert notice as resolved, and optionally add a comment about why.

Required Arguments

• aid: (string or JSON array of strings)ID(s) for the alert notice to resolve.

Optional Arguments

• comment: (string)Text to add as a comment about why the alert was resolved.

Examples

{
 "aid": "1",
 "comment": "Fixed - just needed to restart Samba to free up a stale memory cache"
}

{
 "1": {
  "aid": "1",
  "alert_rule": {
   "caid": "alert_rule_1",
   "isactive": true,
   "name": "Custom Rule 1",
   "owner": "user_id_2",
   "priority": "warning",
   "text": "System alert triggered! alert_rule_1",
   "triggers": [
    {
     "average_over_minutes": 10,
     "comparison": "greater_than",
     "field": "total",
     "metric": "memory_used_percent",
     "value": 99
    }
   ],
   "tvid": ""
  },
  "caid": "alert_rule_4",
  "priority": "warning",
  "resolved": true,
  "resolved_by": "user_id_4",
  "resolved_time": "20170620T12:02:05Z",
  "source": "memory_used_percent",
  "system_time_triggered": [
   504925261
  ],
  "tvid": "server_id_1"
 },
 "comments": [
  "[20170620T11:50:05Z](admin_4) I got this",
  "[20170620T11:51:42Z](admin_2) Sure thing",
  "[20170620T12:02:05Z](admin_4) Fixed - just needed to restart Samba to free up a stale memory cache"
 ]
}

reports/add

Create a new report. The user who creates the report is always included in the 'owners' list for the report, and is granted full edit/delete permissions for the report in the future. In addition, the owner of a report is able to share the report with other users/teams on a read-only basis, or grant ownership of a report to other users for edit capabilities as well. TrueCommand Administrators have permission to edit all reports, even if they are not explicitly included in the 'owners' list.

Required Arguments

• name: (string)Visible title to be shown for the report.

Optional Arguments

• description: (string)Short description of the report
• owners: (string or JSON array of strings)User ID's for those who are granted edit permission for this report.
• Note: The middleware ensures that the user editing the report always keeps ownership of the report.
• The word 'all' can be provided in order to grant edit permission to all users.
• shared_users: (string or JSON array of strings)User ID's for those who are granted read access for this report.
• The word 'all' can be used in place of an ID in order to grant access to all users.
• shared_teams: (string or JSON array of strings)Team ID's for those who are granted read access for this report.
• The word 'all' can be used in place of an ID in order to grant access to all teams.
• widgets: (JSON Object)Special data object for defining the visible widgets for this report. Run the 'reports/list_templates' API to see the format.
• tags: (JSON array of strings)Search tags to help filter available reports

Examples

{
 "name": "My Report 1",
 "shared_users": "all"
}

{
 "5": {
  "last_modified_time_t": 1562075297,
  "last_modified_user": "user_id_1",
  "name": "My Report 1",
  "owners": [
   "user_id_1"
  ],
  "roid": "5",
  "shared_teams": [],
  "shared_users": [
   "all"
  ],
  "tags": [],
  "widgets": {}
 },
 "result": "success"
}

Changelog

• v2.0
• Add 'description' option for reports.

reports/edit

Modify an existing report. Any user included in the 'owners' list has permission to modify a report, including granting edit access to other users. TrueCommand Administrators have permission to edit all reports, even if they are not explicitly included in the 'owners' list.

Required Arguments

• roid: (string)Report Object ID for the desired report to be changed.

Optional Arguments

• name: (string)Visible title to be shown for the report.
• description: (string)Short description of the report
• owners: (string or JSON array of strings)User ID's for those who are granted edit permission for this report.
• Note: The middleware ensures that the user editing the report always keeps ownership of the report.
• The word 'all' can be provided in order to grant edit permission to all users.
• shared_users: (string or JSON array of strings)User ID's for those who are granted read access for this report.
• The word 'all' can be used in place of an ID in order to grant access to all users.
• shared_teams: (string or JSON array of strings)Team ID's for those who are granted read access for this report.
• The word 'all' can be used in place of an ID in order to grant access to all teams.
• widgets: (JSON Object)Special data object for defining the visible widgets for this report. Run the 'reports/list_templates' API to see the format.
• tags: (JSON array of strings)Search tags to help filter available reports

Examples

{
 "name": "My New report Name",
 "roid": "5"
}

{
 "5": {
  "last_modified_time_t": 1562075384,
  "last_modified_user": "user_id_1",
  "name": "My New report Name",
  "owners": [
   "user_id_1"
  ],
  "roid": "5",
  "shared_teams": [],
  "shared_users": [
   "all"
  ],
  "tags": [],
  "widgets": {}
 },
 "result": "success"
}

Changelog

• v2.0
• Add the 'description' option for reports.

reports/generate

This will take a designated report object with a time range and system list and return a complete report structure with all data associated with the systems pre-populated and formatted for display in the UI.This will return JSON data structures formatted for use with the 'chart.js' javascript library when charts are requested as part of a report.

Required Arguments

• roid: (string)Report Object ID for the report to generate.
• tvid: (string or JSON array of strings)System(s) for which to generate the report.
• time_start: (int64)Unix timestamp for start time (seconds since epoch).

Optional Arguments

• time_end: (int64)Unix timestamp for end time (seconds since epoch). Defaults to current time.

Examples

{
 "roid": "my_report_1",
 "time_start": 1590682420,
 "tvid": [
  "system_1",
  "system_2"
 ]
}

{
 "my_report_1": {
  "last_modified_time_t": 1562075297,
  "last_modified_user": "user_id_1",
  "name": "My Report",
  "owners": [
   "user_1",
   "user_2"
  ],
  "roid": "my_report_1",
  "shared_teams": [
   "team_A"
  ],
  "shared_users": [
   "user_3"
  ],
  "widgets": {
   "column_count": 2,
   "items": [
    {
     "api": null,
     "custom_settings": false,
     "data": "{ \u003cchart.js data object\u003e }",
     "data_paths": null,
     "id": "network_chart_1",
     "internal_type": "chart:line",
     "name": "Network Traffic Chart",
     "preview_image": "",
     "settings": null,
     "summary": "Chart of network traffic"
    }
   ]
  }
 },
 "result": "success"
}

reports/list

This will list all the reports where the current user is tagged as an 'owner' of the repo, or any reports that are shared with the current user.

Required Arguments

• None

Optional Arguments

• None

Examples

{}

{
 "read_only": {
  "internal-3": {
   "last_modified_time_t": 1562075297,
   "last_modified_user": "user_id_1",
   "name": "Internal Report",
   "owners": [
    "user_id_1"
   ],
   "roid": "internal-3",
   "shared_teams": [
    "team_id_3"
   ],
   "shared_users": [
    "user_id_4",
    "all"
   ],
   "widgets": {
    "\u003ctruncated\u003e": "\u003cdetails appear here\u003e"
   }
  }
 },
 "read_write": {
  "5": {
   "last_modified_time_t": 1562075297,
   "last_modified_user": "user_id_1",
   "name": "My Sample Report",
   "owners": [
    "user_id_1"
   ],
   "roid": "5",
   "shared_teams": [
    "team_id_3"
   ],
   "shared_users": [
    "user_id_4"
   ],
   "widgets": {
    "\u003ctruncated\u003e": "\u003cdetails appear here\u003e"
   }
  }
 },
 "result": "success"
}

reports/list_templates

This will return all the known report item template objects by the current version of TrueCommand. These can be inserted into the 'widgets' object within a report into order to enable that type of item in the report.

Required Arguments

• None

Optional Arguments

• None

Examples

{}

{
 "result": "success",
 "templates": {
  "chart_line": {
   "api": [
    {
     "fieldname": "title",
     "summary": "Title for the chart",
     "value": {
      "type": "string"
     }
    },
    {
     "fieldname": "subtitle",
     "summary": "Subtitle for the chart",
     "value": {
      "type": "string"
     }
    },
    {
     "fieldname": "axis_label",
     "summary": "Label for the Y axis",
     "value": {
      "type": "string"
     }
    },
    {
     "fieldname": "point_size",
     "summary": "Size of data points (px)",
     "value": {
      "default": 8,
      "max": 512,
      "min": 0,
      "type": "integer"
     }
    },
    {
     "fieldname": "line_size",
     "summary": "Width of the line (px)",
     "value": {
      "default": 4,
      "max": 512,
      "min": 1,
      "type": "integer"
     }
    },
    {
     "fieldname": "series_color",
     "is_array": true,
     "summary": "Color codes for series",
     "value": {
      "type": "string"
     }
    },
    {
     "fieldname": "y_min",
     "summary": "Minimum Y-axis value",
     "value": {
      "type": "float"
     }
    },
    {
     "fieldname": "y_max",
     "summary": "Maximum Y-axis value",
     "value": {
      "type": "float"
     }
    }
   ],
   "custom_settings": true,
   "data": null,
   "data_paths": [],
   "id": "chart_line",
   "internal_type": "chart:line",
   "name": "Generic Line Chart",
   "preview_image": "",
   "settings": {},
   "summary": "Add a chart of data points pointing to custom data"
  },
  "network_chart": {
   "api": [],
   "custom_settings": false,
   "data": null,
   "data_paths": [
    {
     "legend": "Total Download",
     "path": "network%total%KB/s in"
    },
    {
     "legend": "Total Upload",
     "path": "network%total%KB/s out"
    }
   ],
   "id": "network_chart",
   "internal_type": "chart:line",
   "name": "Network Traffic Chart",
   "preview_image": "",
   "settings": {
    "axis_label": "KB/s",
    "line_size": 3,
    "point_size": 0,
    "subtitle": "",
    "title": "Network Traffic",
    "y_min": 0
   },
   "summary": "Chart of network traffic"
  }
 }
}

reports/remove

Remove a custom report. You must be listed as either an 'owner' on the report or a TrueCommand administrator.

Required Arguments

• roid: (string or JSON array of strings)Report Object ID

Optional Arguments

• None

Examples

{
 "roid": [
  "1",
  "5"
 ]
}

{
 "result": "success"
}

rpc/auth

Login to TrueCommand with a username and password. This needs to be performed within a few seconds of establishing the websocket connection, otherwise the server will close down the connection.

Required Arguments

• username: (string)Name of the user to login
• password: (string)Password associated with the specific user

Optional Arguments

• None

Examples

{
 "args": {
  "password": "mypassword",
  "username": "myuser"
 },
 "id": "some_id",
 "name": "auth",
 "namespace": "rpc"
}

[
 "long_random_auth_token",
 900,
 "user_uuid"
]

rpc/auth_clear

Logout of an existing session. This will invalidate any existing auth tokens for the user session and close down the websocket connection.

Required Arguments

• None

Optional Arguments

• None

Examples

{}

null

rpc/auth_token

Login to TrueCommand with a previously-provided login token. This needs to be performed within a few seconds of establishing the websocket connection, otherwise the server will close down the connection. A successful login with an auth token will automatically invalidate that token and a new token will be returned for future use again.

Required Arguments

• token: (string)Authorization token to use.

Optional Arguments

• None

Examples

{
 "token": "long_random_auth_token"
}

[
 "long_random_auth_token",
 900,
 "user_uuid"
]

rpc/query

List all the available API namespace/name combinations that the user can interact with.

Required Arguments

• None

Optional Arguments

• None

Examples

{}

{
 "rpc": [
  "auth",
  "auth_token",
  "auth_clear",
  "query"
 ]
}

servers/add

Register a new TrueNAS server to the TrueCommand administration framework.

Required Arguments

• ip: (string)IP or DNS Hostname for the system.
• Note: This supports custom port numbers by specifying ':[portnum]' on the end of the IP.
• login_user: (string)Username for the TrueNAS. Typically 'root'.
• login_password: (string)Password for the TrueNAS account. This can also be an auth token from the NAS instead of a password.
• nickname: (string)The nickname to use for this system within TrueCommand.

Optional Arguments

• groups: (JSON array of strings)List of groups this system belongs to.
• tags: (JSON array of strings)List of search tags for this system.
• ignore_alerts: (string or JSON array of strings)Types of passthrough alerts to ignore from this NAS
• Possible values: 'information', 'warning', 'critical', or 'all'.
• If specified, this overwrites the system-wide settings for this particular system. Submit a null value to reset back to system defaults.

Examples

{
 "groups": [
  "group1",
  "group2"
 ],
 "ip": "192.168.0.1",
 "login_password": "server_password",
 "login_user": "root",
 "nickname": "server_nickname"
}

{
 "id": "new_server_id",
 "result": "success"
}

Changelog

• v2.0
• The 'is_external' flag was removed.
• The 'nickname' field is now required.

[Obsolete] servers/add_tokens

Create authentication tokens that are associated with a specific system. These tokens may be used to submit information to TrueCommand via the 'external' namespace of API calls.

Required Arguments

• tvid: (string)System ID for where to generate the auth tokens.
• name: (string or JSON array of strings)Nicknames for the tokens to generate. These must be unique.

Optional Arguments

• None

Examples

{
 "names": "token_4",
 "tvid": "server_id_1"
}

{
 "result": "success",
 "tokens": {
  "token_1": "XXXXXXXXXXXXX",
  "token_2": "YYYYYYYYYYYYY",
  "token_3": "ZZZZZZZZZZZZZZ",
  "token_4": "ABCDEFGHIJKLMNOP"
 }
}

servers/available

[Cloud-service only] Display the list of NAS's that are currently available within the wireguard network. This only displays the nicknames and internal wireguard IP's of the systems as generated by the cloud-instance account portal. It does not verify the availability of the systems in any way.

Required Arguments

• None

Optional Arguments

• None

Examples

{}

{
 "available": {
  "172.28.0.13": "my-nas.local",
  "172.28.0.19": "nas2.local"
 }
}

[Obsolete] servers/current_stats

Ask for any information about the servers. NOTE: This will only return information about servers that the current user has read access to. By default this will return the information about all the servers the user is aware of, but the 'tvid' input can be used to restrict the output information as needed. More information may be returned than that shown in the example below.

Required Arguments

• None

Optional Arguments

• tvid: (string or JSON array of strings)

Examples

{}

{
 "server_id_1": {
  "cpu_num": 1,
  "hostname": "server_hostname",
  "memory_bytes": 1024,
  "version": "server_version"
 }
}

servers/direct_auth

Request direct access to a server (requires user write permissions for server) This will return all the necessary information to directly connect to the server for advanced configuration. NOTE: The authentication token returned is only temporary - any significant delay in using it to login to the server may result in the token becoming invalid.

Required Arguments

• id: (string)ID of the system where access is requested.

Optional Arguments

• None

Examples

{
 "id": "server_id_1"
}

{
 "server_auth_token": "some_temporary_authentication_token",
 "server_ip": "192.168.0.1",
 "server_status": "online",
 "server_url": "https://192.168.0.1:443"
}

servers/edit

Modify an existing server settings

Required Arguments

• id: (string)ID of the server to modify.

Optional Arguments

• ip: (string)IP or DNS Hostname for the system.
• Note: This supports custom port numbers by specifying ':[portnum]' on the end of the IP.
• login_user: (string)Username for the TrueNAS. Typically 'root'.
• login_password: (string)Password for the TrueNAS account. This can also be an auth token from the NAS instead of a password.
• nickname: (string)The nickname to use for this system within TrueCommand.
• groups: (JSON array of strings)List of groups this system belongs to.
• tags: (JSON array of strings)List of search tags for this system.
• connection_paused: (boolean)Pause the connection. Will connect to the system and allow minimal access (passive listening mode). Will not retrieve stats or run periodic probes on the NAS.
• ignore_alerts: (string or JSON array of strings)Types of passthrough alerts to ignore from this NAS
• Possible values: 'information', 'warning', 'critical', or 'all'.
• If specified, this overwrites the system-wide settings for this particular system. Submit a null value to reset back to system defaults.

Examples

{
 "groups": [
  "group3",
  "group4"
 ],
 "id": "server_id_1",
 "nickname": "new_nickname"
}

{
 "server_id_1": {
  "connection_error": "Connected",
  "connection_paused": false,
  "connection_secure": true,
  "groups": [
   "group3",
   "group4"
  ],
  "id": "server_id_1",
  "ip": "192.168.0.1",
  "login_user": "root",
  "mac_address": "system_mac_address",
  "nickname": "new_nickname"
 }
}

[Obsolete] servers/find_available

Ask for a list of all non-associated servers on the local network which are discoverable via MDNS.

Required Arguments

• None

Optional Arguments

• None

Examples

{}

{
 "192.168.10.10": {
  "address": "192.168.10.10",
  "name": "my_local_server",
  "port": "80",
  "target": "my_local_server.local"
 },
 "192.168.10.11": {
  "address": "192.168.10.11",
  "name": "my_local_server2",
  "port": "80",
  "target": "my_local_server2.local"
 }
}

servers/groups_add

Simplification for adding existing servers to new or existing groups

Required Arguments

• [server_id]: (string or JSON array of strings)Groups which need to be added to this server
• The fieldname is the ID of the server
• The value is the group name(s) that this server needs to be added to.

Optional Arguments

• None

Examples

{
 "server_id_1": "new_group_1",
 "server_id_2": [
  "new_group_1",
  "new_group_2"
 ]
}

{
 "server_id_1": [
  "previous_group_1",
  "previous_group_2",
  "new_group_1"
 ],
 "server_id_2": [
  "previous_group_1",
  "previous_group_2",
  "new_group_1",
  "new_group_2"
 ]
}

servers/groups_remove

Simplification for removing servers from existing groups

Required Arguments

• [server_id]: (string or JSON array of strings)Groups which need to be removed from this server
• The fieldname is the ID of the server
• The value is the group name(s) that need to be removed from that server.

Optional Arguments

• None

Examples

{
 "server_id_1": "previous_group_1",
 "server_id_2": [
  "previous_group_2",
  "previous_group_3"
 ]
}

{
 "server_id_1": [
  "previous_group_2",
  "previous_group_3"
 ],
 "server_id_2": [
  "previous_group_1"
 ]
}

servers/groups_rename

Simplification for renaming a server group to a different name. If a group with the new name exists, then this will effectively 'merge' the old group into the new one.

Required Arguments

• groupname_old: (string)Existing name for the group.
• groupname_new: (string)New name for the group.

Optional Arguments

• None

Examples

{
 "groupname_new": "group_1",
 "groupname_old": "group01"
}

{
 "group_renamed": "group01",
 "new_group": "group_1",
 "result": "success"
}

[Obsolete] servers/groups_replace

Simplification for replacing the group assignments for existing servers

Required Arguments

• [server_id]: (string or JSON array of strings)Groups which need to include this system.

Optional Arguments

• None

Examples

{
 "server_id_1": "new_group_1",
 "server_id_2": [
  "new_group_1",
  "new_group_2"
 ]
}

{
 "server_id_1": [
  "new_group_1"
 ],
 "server_id_2": [
  "new_group_1",
  "new_group_2"
 ]
}

servers/list

List basic information about the associated servers

Required Arguments

• None

Optional Arguments

• with_details: (boolean)Also include the information from the 'servers/current_stats' API call.

Examples

{}

{
 "server1": {
  "connection_error": "",
  "connection_is_up": true,
  "groups": [
   "group1",
   "group2"
  ],
  "hostname": "server_hostname",
  "id": "server1",
  "last_sync": "yyyy-MM-dd hh:mm:ss",
  "nickname": "server_nickname",
  "updates_available": true,
  "updates_running": false
 }
}

{}

{
 "server1": {
  "connection_error": "",
  "connection_is_up": true,
  "groups": [
   "group1",
   "group2"
  ],
  "hostname": "server_hostname",
  "id": "server1",
  "ip": "192.168.0.1",
  "last_sync": "yyyy-MM-dd hh:mm:ss",
  "login_user": "root",
  "mac_address": "system_mac_address",
  "nickname": "server_nickname",
  "updates_available": true,
  "updates_running": false
 }
}

{
 "with_details": true
}

{
 "server1": {
  "connection_error": "",
  "connection_is_up": true,
  "current_stats": {
   "cpu_num": 1,
   "hostname": "server_hostname",
   "memory_bytes": 1024,
   "version": "server_version"
  },
  "groups": [
   "group1",
   "group2"
  ],
  "hostname": "server_hostname",
  "id": "server1",
  "last_sync": "yyyy-MM-dd hh:mm:ss",
  "nickname": "server_nickname",
  "updates_available": true,
  "updates_running": false
 }
}

servers/list_groups

List all the current groups and which servers are associated with each group. If a non-administrator makes this API call, it will only return information about the groups that the user currently has access to see.

Required Arguments

• None

Optional Arguments

• None

Examples

{}

{
 "group1": [
  "server_1",
  "server_2"
 ],
 "group2": [
  "server_1",
  "server_3"
 ],
 "group3": [
  "server_4"
 ]
}

Changelog

• v1.2
• Remove admin-only restriction.

[Obsolete] servers/list_tokens

These are tokens that may be used to submit system information via the 'external' namespace of API calls, and are associated with a specific system registration.

Required Arguments

• tvid: (string)System ID for which to return current auth tokens

Optional Arguments

• None

Examples

{
 "tvid": "system_id_1"
}

{
 "tokens": {
  "token_1": "XXXXXXXXXXXXX",
  "token_2": "YYYYYYYYYYYYY",
  "token_3": "ZZZZZZZZZZZZZZ"
 }
}

servers/list_writable

List all the servers that the current user has write access to. This is useful for determining which servers the current user can directly access for administration purposes.

Required Arguments

• None

Optional Arguments

• None

Examples

{}

{
 "server_id_1": {
  "hostname": "server_hostname",
  "id": "server_id_1",
  "nickname": "server_nickname",
  "server_status": "online"
 },
 "server_id_2": {
  "hostname": "server_2_hostname",
  "id": "server_id_2",
  "nickname": "server_2_nickname",
  "server_status": "offline"
 }
}

servers/reconnect

Trigger TrueCommand to attempt to restart the connection to designated NAS's. This can be run for any NAS that the user has write-access to.

Required Arguments

• id: (string or JSON array of strings)System ID's for which systems to queue up reconnections

Optional Arguments

• None

Examples

{
 "id": "server_id_1"
}

{
 "restart_queued": [
  "server_id_1"
 ],
 "result": "success"
}

servers/remove

Remove a FreeNAS/TrueNAS server from the administration framework

Required Arguments

• id: (string or JSON array of strings)ID of the server(s) to remove

Optional Arguments

• None

Examples

{
 "id": "server_id_1"
}

{
 "result": "success"
}

Changelog

• v1.1
• 'id' field now supports an array of id's for bulk operations.

[Obsolete] servers/remove_tokens

Remove special access tokens from server registrations.

Required Arguments

• tvid: (string)System ID where the auth token needs to be removed
• name: (string or JSON array of strings)Name(s) of the tokens to remove

Optional Arguments

• None

Examples

{
 "names": [
  "token_1",
  "token_2"
 ],
 "tvid": "server_id_1"
}

{
 "result": "success",
 "tokens": {
  "token_3": "XXXXXXXXXXXXX"
 }
}

servers/update

Have a NAS start performing updates. The system will automatically reboot to finish the update procedures. These updates will only occur on the currently-selected update train. Switching update trains must be performed on the NAS itself.

Required Arguments

• id: (string or JSON array of strings)System ID's for the systems to start upgrading.

Optional Arguments

• None

Examples

{
 "id": "server_id_1"
}

{
 "result": "success",
 "starting_updates": [
  "server_id_1"
 ],
 "unsupported": []
}

ssl/ca_import

Import a custom certificate authority (CA) certificate which will be accepted for all NAS connections. If the 'name' matches an already existing custom CA, then that CA file will be overwritten with the new contents.

Required Arguments

• name: (string)Internal name to use for the CA certificate
• pem: (string)Certificate contents (must be in PEM format).

Optional Arguments

• pem_as_base64: (boolean)The 'pem' string is provided in base64-encoded format (default: false).

Examples

{
 "name": "mycustomCA-1",
 "pem": "ASFIJBGIOUWSKLDFGJBNSDF:GJBNBGSDFIVU54394785SDIGHB",
 "pem_as_base64": true
}

{
 "result": "success"
}

ssl/ca_list

List the internal names of all custom CA files that have been imported.

Required Arguments

• None

Optional Arguments

• None

Examples

{}

{
 "custom_ca_list": [
  "mycustomca-1"
 ]
}

ssl/ca_remove

Remove custom certificate authority file(s).

Required Arguments

• ca_certs: (string or JSON array of strings)Name of the certificate(s) to remove.

Optional Arguments

• None

Examples

{
 "ca_certs": "mycustomCA-1"
}

{
 "result": "success"
}

ssl/cert_import

Import a custom SSL certificate to be used for the TrueCommand web interface.

Required Arguments

• pem: (string)Certificate contents (must be in PEM format).
• key: (string)Key contents (must be in RSA/PEM format without a passphrase).

Optional Arguments

• pem_as_base64: (boolean)The 'pem' string is provided in base64-encoded format (default: false).
• key_as_base64: (boolean)The 'key' string is provided in base64-encoded format (default: false).

Examples

{
 "key": "SZGFJISBEGILUWSGELIFUBIUGBSILUDGBGLRKS",
 "key_as_base64": true,
 "pem": "ASFIJBGIOUWSKLDFGJBNSDF:GJBNBGSDFIVU54394785SDIGHB",
 "pem_as_base64": true
}

{
 "result": "success"
}

ssl/cert_info

View information about the current TrueCommand SSL certificate

Required Arguments

• None

Optional Arguments

• None

Examples

{}

{
 "using_custom_cert": false
}

ssl/cert_reset

Remove any custom SSL certificate for TrueCommand itself and replace it with the automatically-generated self-signed certificate. n Note that this API call will return an error if there is currently no custom SSL certificate being used.

Required Arguments

• None

Optional Arguments

• None

Examples

{}

{
 "result": "success"
}

sys/info

Return general information about the system itself

Required Arguments

• None

Optional Arguments

• None

Examples

{}

{
 "middleware_version": "2.0-20210426",
 "online_docs_url": "http://www.truenas.com/docs/truecommand",
 "system_id": "my_unique_system_id",
 "system_version": "2.0"
}

sys/list_config

View the current system configuration settings. See the 'sys/set_config' API for all the possible settings.

Required Arguments

• None

Optional Arguments

• None

Examples

{}

{
 "config": {
  "server_polling_seconds": 20,
  "ssl_accept_hostmismatch": true,
  "ssl_accept_selfsigned": true,
  "stats_keep_months": 24
 }
}

sys/middleware_log

Return the contents of the middleware log file (typically used for system debugging). NOTE: The contents of the log file will use the html '<br>' tag for line breaks.

Required Arguments

• None

Optional Arguments

• None

Examples

{}

{
 "log": "Really long block of text with \u003cbr\u003e elements as line breaks"
}

[Obsolete] sys/reboot

Schedule a system reboot for the TrueCommand appliance. There is a 5 minute delay by default in order to allow other logged-in users enough time to finish up whatever they are doing before the system goes down. There will also be system-wide events announcing the impending reboot to all active user sessions.

Required Arguments

• None

Optional Arguments

• delay_seconds: (integer)Schedule the reboot to happen this many seconds after the API call is received.
• Default Value: 300 (5 minutes)
• poweroff: (boolean)Power off the system instead of rebooting (default: false).
• When enabled, the 'reboot_type' info field will change to 'poweroff' during the delay.

Examples

{
 "delay_seconds": 15
}

{
 "reboot_delay_seconds": 15,
 "reboot_time": "2019-01-01T05:40:19Z",
 "reboot_type": "restart"
}

[Obsolete] sys/reboot_stop

Cancel any pending reboot or shudown procedure. Requires administrator permissions.

Required Arguments

• None

Optional Arguments

• None

Examples

{}

{
 "result": "success"
}

[Obsolete] sys/reboot_time

See if there is a scheduled reboot of the TrueCommand system, and the time remaining before the system reboot occurs.

Required Arguments

• None

Optional Arguments

• None

Examples

{}

{
 "reboot_delay_seconds": 13,
 "reboot_scheduled": true,
 "reboot_time": "2019-01-01T05:40:19Z",
 "reboot_type": "restart"
}

sys/set_config

Change various system-configuration options for TrueCommand.

Required Arguments

• None

Optional Arguments

• offline_delay_seconds: (integer)Number of seconds after a system goes offline without warning to wait before generating an alert. (Default: 30)
• stats_keep_months: (integer)Number of months of statistics to keep within the TrueCommand database
• ssl_accept_selfsigned: (boolean)Accept self-signed certificates when establishing a connection to a NAS.
• ssl_accept_hostmismatch: (boolean)Accept certificate even if the hostname on the cert does not match the URL/IP of the NAS.
• This is particularly useful if the certificate only contains the DNS hostname, but TC was provided with the direct IP address (or vice-versa).
• ssl_ignore_all: (boolean)Ignore any SSL errors with certificates when connecting to a NAS. When enabled, this will overwrite take precedence over the self-signed and hostmismatch options.
• nas_ssl_only: (boolean)Require SSL connections to all NAS's.
• nas_ignore_alerts: (string or JSON array of strings)Ignore passthrough alerts of the listed type(s) for all NAS
• Possible values: 'information', 'warning', 'critical', or 'all'.
• NOTE: These defaults are only respected if the custom ignore rules for the individual NAS is empty. See the 'servers/edit' API call for setting custom ignore rules for specific systems.
• nas_backup_config_keep: (positive integer)Number of configuration backups to keep for each NAS.
• Set this to 0 to disable automatic backups
• ldap_create_users: (boolean)Allow valid LDAP authentication to dynamically create user accounts as needed.
• ldap_default_teams: (JSON array of strings)List of team ID's that a new user should be added to.
• This is how to auto-assign LDAP users to specific team(s) for permission settings
• ldap_servers: (JSON array of objects)List of LDAP settings objects. Each object contains the following fields:
• url: (string, Required)IP or DNS name of hte LDAP server, with port number on the end.
• Example: 'ldap.mycorp.com:389'
• domain: (string, Required)Base domain settings of the user
• Example: 'dc=mycorp,dc=com' for a typical username@mycorp.com user account
• verify_ssl: (boolean, Optional)Require strict SSL certificate verification (default: false)
• Disable this option if the hostname of the system is different than the one listed on the SSL certificate, an IP is used for the connection instead of the DNS hostname, or if a self-signed certificate is used by the LDAP server.
• user_id_field: (string, Optional)Domain fieldname to use for user-matching (default: 'uid').
• Another field commonly-used is 'cn' (common name)
• group_id_field: (string, Optional)Domain fieldname to use when searching for a group name (default: 'cn').
• group_domain_base: (string, Optional)Alternative domain setting to use when searching for groups (default: Same as 'domain')
• bind_user_domain: (string, Optional)Full domain setting for a pre-authenticated bind to the server.
• Example: 'uid=binduser,cn=read-only-bind,dc=mycorp,dc=com'
• For an unauthenticated bind set this field to just a name (example: 'truecommand-bind'). This is sometimes used for logging purposes on the LDAP, but otherwise is not validated.
• bind_user_password: (string, Optional)Password for the bind user
• For an unauthenticated bind, leave this field blank while setting the 'bind_user_domain' to a non-empty value.

Examples

{
 "ssl_accept_hostmismatch": false,
 "stats_keep_months": 12
}

{
 "result": "success"
}

Changelog

• v2.0
• 'server_polling_seconds' option removed. Realtime feed (non-polling) from TrueNAS now.
• 'offline_delay_seconds' option added.

[Obsolete] sys/update_check

Have TrueCommand perform a check for whether system updates are available. This is a manual probe to start the update check only. TrueCommand automatically checks for system updates every 24 hours or whenever the middleware is restarted otherwise.

Required Arguments

• None

Optional Arguments

• None

Examples

{}

{
 "result": "success",
 "status": "starting check for updates"
}

[Obsolete] sys/update_now

Perform TrueCommand system updates and reboot the system. Note that for offline updates, this process generally takes less than 10 seconds before the system will reboot to finish the update. For online updates this may take a while longer while it downloads the update files. During an online update, the current status of the update process can be found with the sys/update_status API call.

Required Arguments

• None

Optional Arguments

• fetch_url: (string)Fetch an offline update file from a designated URL on the local network.
• file_upload: (string)Filename of the offline update file that was previously uploaded via the sys/upload_file API.

Examples

{
 "fetch_url": "http://mylocalserver.net/system-update.img"
}

{
 "result": "success",
 "updates": "starting"
}

[Obsolete] sys/update_status

View the log file for the current update procedure, and report whether the system is waiting to reboot to finish performing updates.

Required Arguments

• None

Optional Arguments

• None

Examples

{}

{
 "reboot_required": true,
 "update_running": false,
 "update_status": "log file of information\u003cbr\u003eon multiple lines"
}

[Obsolete] sys/updates_available

Check for available updates to the TrueCommand appliance. **NOTE** This requires the ability to connect to the iXsystems update server.

Required Arguments

• None

Optional Arguments

• None

Examples

{}

{
 "updates_available": true,
 "updates_info": "information about update"
}

[Obsolete] sys/upload_file

Request a temporary authentication token for uploading a file to the TrueCommand system. Access credentials are only valid for 10 minutes after the request, and can be used to send a POST request to the '[TrueCommand system IP]/upload' URL to upload the file. Files that are uploaded are **temporary**. They will be removed the next time the system is rebooted.

Required Arguments

• None

Optional Arguments

• None

Examples

{}

{
 "upload_expires": "yyyyMMddhhmmss",
 "upload_pass": "oihvUIiu8yvU6y75786yv",
 "upload_user": "ihgUyfkljh"
}

sys/version_info

Return general information about the current system version and other versions.

Required Arguments

• None

Optional Arguments

• None

Examples

{}

{
 "version_info": {
  "current_version": "1.2.2",
  "updates_available": false,
  "versions": [
   {
    "date": "2020-03-11",
    "latest": true,
    "notes": "Patch fix 2: More CA and DB restore fixes",
    "url": "https://www.ixsystems.com/blog/library/truecommand-1-2-2/",
    "version": "1.2.2"
   },
   {
    "date": "2020-02-25",
    "latest": false,
    "notes": "Patch fix for CA certificate handling",
    "url": "https://www.ixsystems.com/blog/library/truecommand-1-2-1/",
    "version": "1.2.1"
   },
   {
    "date": "2020-02-18",
    "latest": false,
    "notes": "First docker release of TrueCommand",
    "url": "https://www.ixsystems.com/blog/library/truecommand-1-2/",
    "version": "1.2"
   }
  ]
 }
}

teams/add

Create a new team. These provide the ability to define custom sets of permissions that users may be associated to.

Required Arguments

• name: (string)Name of the team. Must be unique, otherwise it will return an error.

Optional Arguments

• allowed_servers: (JSON Array)List of system ID and permission pairs.
• Element Format: '["server_id", "r or r/w"]'
• allowed_groups: (JSON Array)List of group ID and permission pairs.
• Element Format: '["group_id", "r or r/w"]'
• icon_base64: (string)Base64-encoded icon file that can be used to represent the team.
• tags: (JSON array of strings)Search tags for this team
• create_alerts: (boolean)Team members are allows to create alert rules (default value: false)

Examples

{
 "name": "My Team"
}

{
 "name": "My Team",
 "result": "success",
 "ugid": "new_team_ugid"
}

Changelog

• v1.1
• 'create_alerts' option added.

teams/edit

Modify an existing team. Any user accounts associated with this team will automatically transition to the modified permissions or team name without any further action in the user account settings.

Required Arguments

• ugid: (string)ID of the team to be modified.

Optional Arguments

• name: (string)Name of the team. Must be unique, will return an error otherwise.
• allowed_servers: (JSON Array)List of system ID and permission pairs.
• Element Format: '["server_id", "r or r/w"]'
• allowed_groups: (JSON Array)List of group ID and permission pairs.
• Element Format: '["group_id", "r or r/w"]'
• icon_base64: (string)Base64-encoded icon file that can be used to represent the team.
• tags: (JSON array of strings)Search tags for this team
• create_alerts: (boolean)Team members are allows to create alert rules (default value: false)

Examples

{
 "icon_base64": "new_base64_icon_contents",
 "name": "My New Team Name",
 "ugid": "my_team-1"
}

{
 "result": "success"
}

Changelog

• v1.1
• 'create_alerts' option added

teams/list

List all the currently-defined teams and the associated permission sets. Note: The 'allowed_servers', 'allowed_groups', and 'team_members' fields will only be visible when this API is used by an administrator.

Required Arguments

• None

Optional Arguments

• None

Examples

{}

{
 "team_1": {
  "allowed_groups": [
   [
    "group_1",
    "r/w"
   ],
   [
    "group_2",
    "r"
   ]
  ],
  "allowed_servers": [
   [
    "server_id_1",
    "r/w"
   ],
   [
    "server_id_2",
    "r"
   ]
  ],
  "create_alerts": false,
  "icon_base64": "base64_string_of_icon",
  "name": "Test Team 1",
  "team_members": {
   "user_id_1": {
    "extra_info": {
     "email": "sysadmin1@somewhere.net",
     "full_name": "SysAdmin 1"
    },
    "isAdministrator": false,
    "username": "user1",
    "uuid": "user_id_1"
   },
   "user_id_2": {
    "extra_info": {
     "email": "sysadmin2@somewhere.net",
     "full_name": "SysAdmin 2"
    },
    "isAdministrator": false,
    "username": "user2",
    "uuid": "user_id_2"
   }
  },
  "ugid": "team_1"
 },
 "team_2": {
  "allowed_groups": [
   [
    "group_4",
    "r/w"
   ],
   [
    "group_5",
    "r"
   ]
  ],
  "allowed_servers": [
   [
    "server_id_1",
    "r/w"
   ],
   [
    "server_id_2",
    "r"
   ]
  ],
  "create_alerts": true,
  "icon_base64": "base64_string_of_icon",
  "name": "Test Team 2",
  "team_members": {
   "user_id_2": {
    "extra_info": {
     "email": "sysadmin2@somewhere.net",
     "full_name": "SysAdmin 2"
    },
    "isAdministrator": false,
    "username": "user2",
    "uuid": "user_id_2"
   },
   "user_id_5": {
    "extra_info": {
     "email": "sysadmin5@somewhere.net",
     "full_name": "SysAdmin 5"
    },
    "isAdministrator": false,
    "username": "user5",
    "uuid": "user_id_5"
   }
  },
  "ugid": "team_2"
 }
}

{}

{
 "team_1": {
  "icon_base64": "base64_string_of_icon",
  "name": "Test Team 1",
  "ugid": "team_1"
 },
 "team_2": {
  "icon_base64": "base64_string_of_icon",
  "name": "Test Team 2",
  "ugid": "team_2"
 }
}

teams/remove

Remove a team. Does not remove any user accounts, just the team associations.

Required Arguments

• ugid: (string)ID of the team (user group) to be removed.

Optional Arguments

• None

Examples

{
 "ugid": "my_team-1"
}

{
 "result": "success"
}

[Obsolete] freenas/available_methods

Returns a list of all the supported FreeNAS API methods which can be used for the 'freenas/send_method' API call. This will return all the known/supported methods as well as the permission level required in order to use it.

Required Arguments

• None

Optional Arguments

• None

Examples

{}

{
 "methods": {
  "disk.decrypt": "r/w",
  "disk.get_encrypted": "r",
  "disk.get_unused": "r",
  "disk.query": "r",
  "disk.update": "r/w",
  "disk.wipe": "r/w"
 }
}

truenas/send_method

[Websocket Only] Call a designated TrueNAS method API and return the result. TrueCommand verifies read or read/write permission checks before forwarding the API to the NAS. The return format of the API calls vary widely and the general TrueCommand API structure is not maintained in the reply. The 'id' field is the only one guaranteed to be returned in the reply object.

Required Arguments

• tvid: (string or JSON array of strings)ID of the system(s) to send the method to.
• method: (string)API method to call (Example: 'disk.query')
• params: (-anything-)This field is passed directly to the NAS as the method arguments (typically a JSON array of information).

Optional Arguments

• None

Examples

{
 "args": {
  "method": "disk.query",
  "params": [],
  "tvid": "server_id_1"
 },
 "id": "freenas_api_call_1",
 "name": "send_method",
 "namespace": "freenas"
}

{
 "id": "freenas_api_call_1",
 "msg": "result",
 "result": [
  {
   "acousticlevel": "DISABLED",
   "advpowermgmt": "DISABLED",
   "description": "",
   "enclosure_slot": null,
   "expiretime": null,
   "hddstandby": "ALWAYS ON",
   "identifier": "{serial}30GS10WTT84Z",
   "multipath_member": "",
   "multipath_name": "",
   "name": "ada0",
   "number": 0,
   "passwd": "",
   "serial": "30GS10WTT84Z",
   "size": "30016659456",
   "smartoptions": "",
   "subsystem": "ada",
   "togglesmart": true,
   "transfermode": "Auto"
  },
  {
   "acousticlevel": "DISABLED",
   "advpowermgmt": "DISABLED",
   "description": "",
   "enclosure_slot": null,
   "expiretime": null,
   "hddstandby": "ALWAYS ON",
   "identifier": "{serial}5NH0N524",
   "multipath_member": "",
   "multipath_name": "",
   "name": "ada1",
   "number": 1,
   "passwd": "",
   "serial": "5NH0N524",
   "size": "80026361856",
   "smartoptions": "",
   "subsystem": "ada",
   "togglesmart": true,
   "transfermode": "Auto"
  }
 ]
}

Changelog

• v2.0
• The namespace changed from 'freenas' to 'truenas'. Both namespaces are currently supported for backwards compatibility.

uilogs/add

Create a new log entry

Required Arguments

• log_entry: (JSON Object)Generic data object to be saved as a log entry.

Optional Arguments

• None

Examples

{
 "log_entry": {
  "error_info": "A problem occurred..."
 }
}

{
 "result": "success"
}

Changelog

• v2.0
• Reply structure no longer returns a copy of the new log entry

uilogs/clear

Remove all UI log records from the database.

Required Arguments

• None

Optional Arguments

• None

Examples

{}

{
 "result": "success",
 "total_removed": 12
}

uilogs/list

Requests a list of all UI log entries. These logs are used to temporarily store error reports generated by the UI. Logs are wiped every 24 hours.

Required Arguments

• None

Optional Arguments

• None

Examples

{}

{
 "entries": [
  {
   "log_entry": {
    "error_info": "A problem occurred..."
   },
   "log_id": "f7d4c622-f432-4431-9506-4cbf68b0082d",
   "time_t": 1554996212
  },
  {
   "log_entry": {
    "dashboard": "Failed to load..."
   },
   "log_id": "6043af9c-fdbd-42c7-a820-ab4a5568e092",
   "time_t": 1554996673
  }
 ],
 "result": "success"
}

users/add

Add a new user account to TrueCommand.

Required Arguments

• username: (string)Must be unique. Used to login with this user.
• password: (string)Used to login with this user.
• isAdministrator: (boolean)Make this user an administrator.

Optional Arguments

• allowed_servers: (JSON array)List of system ID and permission pairs.
• Element Format: '["server_id", "r or r/w"]'
• allowed_groups: (JSON array)List of group ID and permission pairs.
• Element Format: '["group_id", "r or r/w"]'
• allowed_teams: (JSON array of strings)Team ID's the user is associated with.
• create_alerts: (boolean or null)User can create alert rules (even if no an administrator).
• If null, the user will inherit this permission from any associated teams
• If true or false, the user will have this specific permission.
• full_name: (string)Appears in the 'extra_info' object
• email: (string)Appears in the 'extra_info' object
• Set this field to get email notifications about alerts and more.
• title: (string)Appears in the 'extra_info' object
• phone_number: (string)Appears in the 'extra_info' object
• contact_info: (string)Appears in the 'extra_info' object
• notes: (string)Appears in the 'extra_info' object
• icon_base64: (string)Appears in the 'extra_info' object
• tags: (JSON array of strings)Search tags. Appears in the 'extra_info' object

Examples

{
 "allowed_groups": [
  [
   "group1",
   "r/w"
  ]
 ],
 "allowed_servers": [
  [
   "server1",
   "r"
  ]
 ],
 "full_name": "John Doe",
 "isAdministrator": false,
 "password": "mypassword",
 "username": "newuser"
}

{
 "result": "success",
 "uuid": "new_user_uuid"
}

Changelog

• v1.1
• 'create_alerts' field added
• v2.0
• LDAP integrations removed from individual user structures. Use the 'sys/set_config' API to setup system-wide LDAP settings.

users/edit

Modify an existing user account. **Note:** Non-administrators only have access to change their own password **only if LDAP authentication is not being used**. Non-admins also have permission to change some of the extra_info fields. Administrator status and allowed servers/groups will not be touched.

Required Arguments

• uuid: (string)User ID of the account to modify

Optional Arguments

• Administrator Modification Only
• username: (string)Must be unique, otherwise will return an error.
• is_admin: (boolean)Make this user an administrator.
• allowed_servers: (JSON array)List of system ID and permission pairs.
• Element Format: '["server_id", "r or r/w"]'
• allowed_groups: (JSON array)List of group ID and permission pairs.
• Element Format: '["group_id", "r or r/w"]'
• allowed_teams: (JSON array of strings)Team ID's the user is associated with.
• create_alerts: (boolean or null)User can create alert rules (even if no an administrator).
• If null, the user will inherit this permission from any associated teams
• If true or false, the user will have this specific permission.
• Self Modification Allowed
• password: (string)Login password. Cannot be changed if the user account is tied into LDAP.
• verify_password: (string)Current password of the user making the request.
• Required if the 'password' is being changed.
• full_name: (string)Appears in the 'extra_info' object
• email: (string)Appears in the 'extra_info' object
• Set this field to get email notifications about alerts and more.
• title: (string)Appears in the 'extra_info' object
• phone_number: (string)Appears in the 'extra_info' object
• contact_info: (string)Appears in the 'extra_info' object
• notes: (string)Appears in the 'extra_info' object
• icon_base64: (string)Appears in the 'extra_info' object
• tags: (JSON array of strings)Search tags. Appears in the 'extra_info' object

Examples

{
 "allowed_groups": [
  [
   "group1",
   "r/w"
  ]
 ],
 "allowed_servers": [
  [
   "server1",
   "r"
  ]
 ],
 "full_name": "John Doe",
 "isAdministrator": true,
 "username": "new_username",
 "uuid": "user_id_1"
}

{
 "user_id_1": {
  "allowed_groups": [
   [
    "group1",
    "r/w"
   ]
  ],
  "allowed_servers": [
   [
    "server1",
    "r"
   ]
  ],
  "extra_info": {
   "full_name": "John Doe"
  },
  "isAdministrator": true,
  "username": "new_username",
  "uuid": "user_id_1"
 }
}

Changelog

• v1.1
• 'verify_password' field added
• 'create_alerts' field added
• v2.0
• LDAP integrations removed from individual user structures. Use the 'sys/set_config' API to setup system-wide LDAP settings.

users/get_data

Fetch any data associated with the currently logged-in user. This is a generic cache of information utilized by the Web UI.

Required Arguments

• None

Optional Arguments

• None

Examples

{}

{
 "obj1": {
  "obj2": {
   "value1": "my_nested_value"
  }
 },
 "value1": "top_level_value"
}

Changelog

• v2.0
• 'key_path' and 'key_default_value' optional arguments removed.

[Obsolete] users/insert_data

Save any random data to be associated with the currently logged-in user. This is different from the users/set_data API call in that the fields within the input arguments will be **added** to the current user data rather than replace it. Any input objects/variables with the same name as existing fields in the user data **will** overwrite those fields however.

Required Arguments

• None

Optional Arguments

• None

Examples

{
 "dataobject": {
  "datafield1": "1"
 },
 "generic_data": "sample field"
}

{
 "dataobject": {
  "datafield1": "1"
 },
 "dataobject2": {
  "B": "b"
 },
 "generic_data": "sample field"
}

[Obsolete] users/insert_data_value

Save any random data to be associated with the currently logged-in user. This is different from the 'set_data' API call in that the fields within the input arguments will be **added** to the current user data rather than replace it. Any input objects/variables with the same name as existing fields in the user data **will** overwrite those fields however.

Required Arguments

• [key_path]: (anything)Fieldname is a '/'-delimited path to a field within the current data object where the value should be changed.

Optional Arguments

• None

Examples

{
 "dataobject/datafield1": "1",
 "generic_data": "sample_field"
}

{
 "dataobject": {
  "A": "a",
  "datafield1": "1"
 },
 "dataobject2": {
  "B": "b"
 },
 "generic_data": "sample field"
}

users/list

List user information. If currently logged-in with an administrator account, this will show all info about all users, otherwise only the basic info about the current user account will be returned

Required Arguments

• None

Optional Arguments

• users: (string or JSON array of strings)Filter the return list to just these user accounts.

Examples

{}

{
 "current_user_id": {
  "isAdministrator": false,
  "is_active": true,
  "username": "myuser",
  "uuid": "current_user_id"
 }
}

{}

{
 "user_id_1": {
  "allowed_groups": [
   [
    "group1",
    "r"
   ],
   [
    "group2",
    "r"
   ]
  ],
  "allowed_servers": [
   [
    "server1",
    "r/w"
   ],
   [
    "server2",
    "r"
   ]
  ],
  "create_alerts": false,
  "extra_info": {
   "email": "sysadmin1@somewhere.net",
   "full_name": "SysAdmin 1"
  },
  "isAdministrator": false,
  "is_active": true,
  "username": "user1",
  "uuid": "user_id_1"
 },
 "user_id_2": {
  "allowed_groups": [
   [
    "group1",
    "r/w"
   ],
   [
    "group2",
    "r/w"
   ]
  ],
  "allowed_servers": [
   [
    "server1",
    "r/w"
   ],
   [
    "server2",
    "r/w"
   ]
  ],
  "create_alerts": null,
  "extra_info": {
   "email": "sysadmin2@somewhere.net",
   "phone_number": "123-456-7890"
  },
  "isAdministrator": true,
  "username": "user2",
  "uuid": "user_id_2"
 }
}

users/list_active

List all currently-active user sessions (admin user), or the number of active sessions for the current user (non-admin user). The output reply contains all users with active sessions, as well as the number of active sessions for each user.

Required Arguments

• None

Optional Arguments

• None

Examples

{}

{
 "list_active": {
  "user1": 1,
  "user2": 2
 }
}

Changelog

• v2.0
• Remove admin-only requirement. For non-admins, only return session count for the user making the request.

users/remove

Removes a user account from TrueCommand.

Required Arguments

• uuid: (string or JSON array of strings)User ID of the account(s) to remove

Optional Arguments

• None

Examples

{
 "uuid": "user_id_1"
}

{
 "result": "success"
}

Changelog

• v2.0
• Allow the 'uuid' field to also be an array of strings.

users/set_data

Save any random data to be associated with the currently logged-in user. This is used to provide a general settings cache for the Web UI. **WARNING:** This API call with overwrite the entire data object for the user with the given arguments.

Required Arguments

• None

Optional Arguments

• None

Examples

{
 "dataobject": {
  "datafield1": "1"
 },
 "generic_data": "sample field"
}

{
 "result": "success"
}