(408) 943-4100               V   Commercial Support
TrueNAS.com Software Systems Company Community Security iX Portal Download

  1. Documentation Hub
  2. /
  3. TrueCommand
  4. /
  5. API Calls
  6. /
  7. Server management
  8. /
  9. servers/add
Edit this page

servers/add

  2 minute read.

Last Modified 2021-02-04 11:38 EST
NamespaceNameAdmin OnlyLog SummaryGenerates EventVersion Added
serveraddyesyesyes1

Description

Add a new FreeNAS/TrueNAS server to the TrueCommand administration framework.

Input Arguments

  • Required Arguments:
    • “ip” (string) : DNS name or IP address of the system on the network.
    • “login_user” (string) : Name of the user to login to the system
      • NOTE: Not needed/used if the “is_external” flag is enabled
    • “login_password” (string) : Password for the user to login to the system
      • NOTE: Not needed/used if the “is_external” flag is enabled
  • Optional Arguments:
    • “nickname” (string) : User-visible name for this system
      • NOTE: This field is required if the “is_external” flag is enabled
    • “groups” (JsonArray of strings)
    • “tags” (JsonArray) : Search tags, Format - [“tag_1”, “tag_2”]
    • “ignore_alerts” (string or JsonArray of strings) : Types of passthrough alerts to ignore from the NAS
      • Added in TrueCommand 1.1
      • Valid types: “information”, “warning”, “critical”, or “all”
      • Default value: null. No alerts are ignored.
    • “is_external” (boolean) : This system is a not a FreeNAS/TrueNAS system (default: false)
      • Added in TrueCommand 1.1
      • Information from this system is only submitted via the “external” API namespace
      • TrueCommand does not connect to this system directly. TC is just an endpoint for storing/viewing stats that the system periodically submits.
      • This flag cannot be changed later.

Request Example Arguments

ARGUMENTS ONLY: See the basics of API requests for additional formatting information.

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

Reply Example

  • Example Reply Arguments (success):
{
  "result" : "success",
  "id" : "new_server_id"
}
  • Example Reply Arguments (error: IP already managed)
{
  "error" : "IP Exists",
  "code" : "400",
  "message" : "Bad Request"
}

Events

Events from this change will be sent to all currently-connected administrators and any user with read access to the new server (such as from adding a server to an existing group).

Example event message:

{
"namespace" : "event",
"name" : "servers/add",
"id" : "",
"args" : {
  "tvid" : "new_server_id"
  }
}

Log Summary

Log entries for this API call will have the following “summary” object. Note that empty fields from the input arguments (hostname, mac_address, groups, nickname) will result in those fields getting excluded from the summary as well (the summary only lists the changes).

"summary" : {
  "action" : "servers/add",
  "added_by_username" : "admin_user",
  "added_by_uuid" : "admin_user_uuid",
  "new_ip" : "newuser",
  "new_tvid" : "new_server_id",
  "new_nickname" : "server_nickname",
  "new_groups" : ["group1","group2"]
}

See Also