# Agent [Agents](https://docs.trustgrid.io/docs/nodes/agents/) are lightweight software clients installed on user devices or servers, supporting VPN/ZTNA connectivity. Requires `nodes::read` permission. ## Retrieve all network nodes including appliances and agents with filtering options - [GET /node](https://apidocs.trustgrid.io/appliance/listnodes.md): List both appliances and agents. The fields config and shadow will be empty unless specified in the projection parameter. The query for the config or shadow must be at least one level deep - projection0=config won't work, but projection0=config&projection0=gateway will result in config.gateway being populated. --- Requires nodes::read permission. ## Retrieve a node by its fully-qualified domain name - [GET /node/by-fqdn/{fqdn}](https://apidocs.trustgrid.io/appliance/getnodebyfqdn.md): Get a node using its FQDN directly, as an alternative to looking up the nodeID first. --- Requires nodes::read permission on the node. ## Permanently remove a node from the organization and revoke access - [DELETE /node/{nodeID}](https://apidocs.trustgrid.io/appliance/paths/~1node~1%7Bnodeid%7D/delete.md): Delete a node (appliance or agent) --- Requires nodes::delete permission. ## Retrieve detailed configuration and status information for a specific node - [GET /node/{nodeID}](https://apidocs.trustgrid.io/appliance/getnode.md): Get a node (appliance or agent) --- Requires nodes::read permission. ## Modify node settings including cluster assignment and operational state - [PUT /node/{nodeID}](https://apidocs.trustgrid.io/appliance/paths/~1node~1%7Bnodeid%7D/put.md): Update a node (appliance or agent) --- Requires nodes::manage permission. ## Configure inbound network connectors for external access to node services - [PUT /node/{nodeID}/config/connectors](https://apidocs.trustgrid.io/appliance/paths/~1node~1%7Bnodeid%7D~1config~1connectors/put.md) ## Remove all connector configurations from a node - [DELETE /node/{nodeID}/config/connectors](https://apidocs.trustgrid.io/appliance/paths/~1node~1%7Bnodeid%7D~1config~1connectors/delete.md) ## Create a new inbound connector to expose services running on the node - [POST /v2/node/{nodeID}/config/connectors](https://apidocs.trustgrid.io/appliance/paths/~1v2~1node~1%7Bnodeid%7D~1config~1connectors/post.md): Requires node::configure::connectors permissions ## Migrate a node's connector configuration to the latest V2 format - [POST /v2/node/{nodeID}/config/connectors/upgrade](https://apidocs.trustgrid.io/appliance/paths/~1v2~1node~1%7Bnodeid%7D~1config~1connectors~1upgrade/post.md): Requires node::configure::connectors permissions ## Modify settings for an existing connector on a node - [PUT /v2/node/{nodeID}/config/connectors/{connectorID}](https://apidocs.trustgrid.io/appliance/paths/~1v2~1node~1%7Bnodeid%7D~1config~1connectors~1%7Bconnectorid%7D/put.md): Applies to appliances and agents. Requires V2 connector config. --- Requires node::configure::connectors permissions ## Remove a specific connector configuration from a node - [DELETE /v2/node/{nodeID}/config/connectors/{connectorID}](https://apidocs.trustgrid.io/appliance/paths/~1v2~1node~1%7Bnodeid%7D~1config~1connectors~1%7Bconnectorid%7D/delete.md): Delete a connector from a node (appliance or agent). Requires V2 connector config. --- Requires node::configure::connectors permissions ## Configure outbound services for external connections from the node - [PUT /node/{nodeID}/config/services](https://apidocs.trustgrid.io/appliance/paths/~1node~1%7Bnodeid%7D~1config~1services/put.md): Update services configuration for a node (appliance or agent) --- Note: request body will be validated by JSON schema of the plugin ## Create a new outbound service connection for external resource access - [POST /v2/node/{nodeID}/config/services](https://apidocs.trustgrid.io/appliance/paths/~1v2~1node~1%7Bnodeid%7D~1config~1services/post.md): Requires node::configure::services permissions ## Migrate a node's service configuration to the latest V2 format - [POST /v2/node/{nodeID}/config/services/upgrade](https://apidocs.trustgrid.io/appliance/paths/~1v2~1node~1%7Bnodeid%7D~1config~1services~1upgrade/post.md): Requires node::configure::services permissions ## Modify settings for an existing service connection on a node - [PUT /v2/node/{nodeID}/config/services/{serviceID}](https://apidocs.trustgrid.io/appliance/paths/~1v2~1node~1%7Bnodeid%7D~1config~1services~1%7Bserviceid%7D/put.md): Update a service on a node. Requires V2 services config. --- Requires node::configure::services permissions ## Remove a specific service configuration from a node - [DELETE /v2/node/{nodeID}/config/services/{serviceID}](https://apidocs.trustgrid.io/appliance/paths/~1v2~1node~1%7Bnodeid%7D~1config~1services~1%7Bserviceid%7D/delete.md): Delete a service from a node. Requires V2 services config. --- Requires node::configure::services permissions ## Configure node as a network gateway for routing traffic between networks - [PUT /node/{nodeID}/config/gateway](https://apidocs.trustgrid.io/appliance/paths/~1node~1%7Bnodeid%7D~1config~1gateway/put.md): Update gateway configuration Use host (not ip) for the gateway hostname. --- Requires nodes::configure:gateway permission. ## Configure SNMP monitoring settings for network management integration - [PUT /node/{nodeID}/snmp](https://apidocs.trustgrid.io/appliance/paths/~1node~1%7Bnodeid%7D~1snmp/put.md): Update SNMP configuration --- Requires nodes::configure:snmp permission. ## Remove a metadata tag from a node for organizational categorization - [DELETE /node/{nodeID}/tag/{tagName}](https://apidocs.trustgrid.io/appliance/paths/~1node~1%7Bnodeid%7D~1tag~1%7Btagname%7D/delete.md) ## Add or update a metadata tag on a node for organizational categorization - [PUT /node/{nodeID}/tag/{tagName}](https://apidocs.trustgrid.io/appliance/paths/~1node~1%7Bnodeid%7D~1tag~1%7Btagname%7D/put.md) ## Execute a remote operation or command on a specific node - [POST /node/{nodeID}/trigger/{event}](https://apidocs.trustgrid.io/appliance/paths/~1node~1%7Bnodeid%7D~1trigger~1%7Bevent%7D/post.md): Sends an event to the node and optionally waits for its response. Common event values: - node-restart-service — restart the Trustgrid node service (requires nodes::service:node-restart-service) - node-reboot — reboot the host OS (requires nodes::service:node-reboot) - node-upgrade — upgrade node software (requires nodes::service:node-upgrade) - gateway-routes — fetch current gateway routes (requires nodes::service:gateway-routes) - vpn-routes — fetch virtual network routing table (requires nodes::service:vpn-routes) - vpn-nats — fetch virtual network NAT table (requires nodes::service:vpn-nats) - tg-ping — run a ping via the Trustgrid overlay (requires nodes::service:tg-ping) - tg-traceroute — run a traceroute via the overlay (requires nodes::service:tg-traceroute) - tg-net-ping — ping through the virtual network (requires nodes::service:tg-net-ping) - speed-test — measure internet bandwidth (requires nodes::service:speed-test) - flows — manage active network flows (requires nodes::service:flows) - bgp — interact with the BGP server (requires nodes::service:bgp) - ipsec-restart — restart the IPSec service (requires nodes::service:ipsec-restart) - ipsec-statusall — retrieve IPSec status (requires nodes::service:ipsec-statusall) All services require either nodes::remote-execute or nodes::service:{event} permission. Add ?wait=1 to block until the node responds (useful for synchronous checks). ## Update the lifecycle state of a specific node - [PUT /v2/node/{nodeID}/lifecycle-state](https://apidocs.trustgrid.io/appliance/paths/~1v2~1node~1%7Bnodeid%7D~1lifecycle-state/put.md): Update the lifecycle state for a node (appliance or agent). --- Requires nodes::manage permission. ## Retrieve all network nodes including appliances and agents with filtering options - [GET /node](https://apidocs.trustgrid.io/agent/listnodes.md): List both appliances and agents. The fields config and shadow will be empty unless specified in the projection parameter. The query for the config or shadow must be at least one level deep - projection0=config won't work, but projection0=config&projection0=gateway will result in config.gateway being populated. --- Requires nodes::read permission. ## Retrieve a node by its fully-qualified domain name - [GET /node/by-fqdn/{fqdn}](https://apidocs.trustgrid.io/agent/getnodebyfqdn.md): Get a node using its FQDN directly, as an alternative to looking up the nodeID first. --- Requires nodes::read permission on the node. ## Permanently remove a node from the organization and revoke access - [DELETE /node/{nodeID}](https://apidocs.trustgrid.io/agent/paths/~1node~1%7Bnodeid%7D/delete.md): Delete a node (appliance or agent) --- Requires nodes::delete permission. ## Retrieve detailed configuration and status information for a specific node - [GET /node/{nodeID}](https://apidocs.trustgrid.io/agent/getnode.md): Get a node (appliance or agent) --- Requires nodes::read permission. ## Modify node settings including cluster assignment and operational state - [PUT /node/{nodeID}](https://apidocs.trustgrid.io/agent/paths/~1node~1%7Bnodeid%7D/put.md): Update a node (appliance or agent) --- Requires nodes::manage permission. ## Configure inbound network connectors for external access to node services - [PUT /node/{nodeID}/config/connectors](https://apidocs.trustgrid.io/agent/paths/~1node~1%7Bnodeid%7D~1config~1connectors/put.md) ## Remove all connector configurations from a node - [DELETE /node/{nodeID}/config/connectors](https://apidocs.trustgrid.io/agent/paths/~1node~1%7Bnodeid%7D~1config~1connectors/delete.md) ## Create a new inbound connector to expose services running on the node - [POST /v2/node/{nodeID}/config/connectors](https://apidocs.trustgrid.io/agent/paths/~1v2~1node~1%7Bnodeid%7D~1config~1connectors/post.md): Requires node::configure::connectors permissions ## Migrate a node's connector configuration to the latest V2 format - [POST /v2/node/{nodeID}/config/connectors/upgrade](https://apidocs.trustgrid.io/agent/paths/~1v2~1node~1%7Bnodeid%7D~1config~1connectors~1upgrade/post.md): Requires node::configure::connectors permissions ## Modify settings for an existing connector on a node - [PUT /v2/node/{nodeID}/config/connectors/{connectorID}](https://apidocs.trustgrid.io/agent/paths/~1v2~1node~1%7Bnodeid%7D~1config~1connectors~1%7Bconnectorid%7D/put.md): Applies to appliances and agents. Requires V2 connector config. --- Requires node::configure::connectors permissions ## Remove a specific connector configuration from a node - [DELETE /v2/node/{nodeID}/config/connectors/{connectorID}](https://apidocs.trustgrid.io/agent/paths/~1v2~1node~1%7Bnodeid%7D~1config~1connectors~1%7Bconnectorid%7D/delete.md): Delete a connector from a node (appliance or agent). Requires V2 connector config. --- Requires node::configure::connectors permissions ## Configure outbound services for external connections from the node - [PUT /node/{nodeID}/config/services](https://apidocs.trustgrid.io/agent/paths/~1node~1%7Bnodeid%7D~1config~1services/put.md): Update services configuration for a node (appliance or agent) --- Note: request body will be validated by JSON schema of the plugin ## Create a new outbound service connection for external resource access - [POST /v2/node/{nodeID}/config/services](https://apidocs.trustgrid.io/agent/paths/~1v2~1node~1%7Bnodeid%7D~1config~1services/post.md): Requires node::configure::services permissions ## Migrate a node's service configuration to the latest V2 format - [POST /v2/node/{nodeID}/config/services/upgrade](https://apidocs.trustgrid.io/agent/paths/~1v2~1node~1%7Bnodeid%7D~1config~1services~1upgrade/post.md): Requires node::configure::services permissions ## Modify settings for an existing service connection on a node - [PUT /v2/node/{nodeID}/config/services/{serviceID}](https://apidocs.trustgrid.io/agent/paths/~1v2~1node~1%7Bnodeid%7D~1config~1services~1%7Bserviceid%7D/put.md): Update a service on a node. Requires V2 services config. --- Requires node::configure::services permissions ## Remove a specific service configuration from a node - [DELETE /v2/node/{nodeID}/config/services/{serviceID}](https://apidocs.trustgrid.io/agent/paths/~1v2~1node~1%7Bnodeid%7D~1config~1services~1%7Bserviceid%7D/delete.md): Delete a service from a node. Requires V2 services config. --- Requires node::configure::services permissions ## Configure node as a network gateway for routing traffic between networks - [PUT /node/{nodeID}/config/gateway](https://apidocs.trustgrid.io/agent/paths/~1node~1%7Bnodeid%7D~1config~1gateway/put.md): Update gateway configuration Use host (not ip) for the gateway hostname. --- Requires nodes::configure:gateway permission. ## Configure SNMP monitoring settings for network management integration - [PUT /node/{nodeID}/snmp](https://apidocs.trustgrid.io/agent/paths/~1node~1%7Bnodeid%7D~1snmp/put.md): Update SNMP configuration --- Requires nodes::configure:snmp permission. ## Remove a metadata tag from a node for organizational categorization - [DELETE /node/{nodeID}/tag/{tagName}](https://apidocs.trustgrid.io/agent/paths/~1node~1%7Bnodeid%7D~1tag~1%7Btagname%7D/delete.md) ## Add or update a metadata tag on a node for organizational categorization - [PUT /node/{nodeID}/tag/{tagName}](https://apidocs.trustgrid.io/agent/paths/~1node~1%7Bnodeid%7D~1tag~1%7Btagname%7D/put.md) ## Execute a remote operation or command on a specific node - [POST /node/{nodeID}/trigger/{event}](https://apidocs.trustgrid.io/agent/paths/~1node~1%7Bnodeid%7D~1trigger~1%7Bevent%7D/post.md): Sends an event to the node and optionally waits for its response. Common event values: - node-restart-service — restart the Trustgrid node service (requires nodes::service:node-restart-service) - node-reboot — reboot the host OS (requires nodes::service:node-reboot) - node-upgrade — upgrade node software (requires nodes::service:node-upgrade) - gateway-routes — fetch current gateway routes (requires nodes::service:gateway-routes) - vpn-routes — fetch virtual network routing table (requires nodes::service:vpn-routes) - vpn-nats — fetch virtual network NAT table (requires nodes::service:vpn-nats) - tg-ping — run a ping via the Trustgrid overlay (requires nodes::service:tg-ping) - tg-traceroute — run a traceroute via the overlay (requires nodes::service:tg-traceroute) - tg-net-ping — ping through the virtual network (requires nodes::service:tg-net-ping) - speed-test — measure internet bandwidth (requires nodes::service:speed-test) - flows — manage active network flows (requires nodes::service:flows) - bgp — interact with the BGP server (requires nodes::service:bgp) - ipsec-restart — restart the IPSec service (requires nodes::service:ipsec-restart) - ipsec-statusall — retrieve IPSec status (requires nodes::service:ipsec-statusall) All services require either nodes::remote-execute or nodes::service:{event} permission. Add ?wait=1 to block until the node responds (useful for synchronous checks). ## Update the lifecycle state of a specific node - [PUT /v2/node/{nodeID}/lifecycle-state](https://apidocs.trustgrid.io/agent/paths/~1v2~1node~1%7Bnodeid%7D~1lifecycle-state/put.md): Update the lifecycle state for a node (appliance or agent). --- Requires nodes::manage permission.