# Appliance [Appliances](https://docs.trustgrid.io/docs/nodes/appliances/) are physical or virtual machine Trustgrid nodes providing full network, VPN, edge compute, and monitoring capabilities. 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. ## Generate a license key for registering a new node to the organization - [GET /node/license](https://apidocs.trustgrid.io/appliance/getnodelicense.md) ## 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 alert thresholds and notification settings for a specific appliance - [PUT /node/{nodeID}/config/alert](https://apidocs.trustgrid.io/appliance/paths/~1node~1%7Bnodeid%7D~1config~1alert/put.md): Applicable to appliances only. ## Configure high-availability cluster settings for a specific appliance - [PUT /node/{nodeID}/config/cluster](https://apidocs.trustgrid.io/appliance/paths/~1node~1%7Bnodeid%7D~1config~1cluster/put.md): Applicable to appliances only. ## 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 network interfaces, routing, and firewall rules for an appliance - [PUT /node/{nodeID}/config/network](https://apidocs.trustgrid.io/appliance/paths/~1node~1%7Bnodeid%7D~1config~1network/put.md): Update network configuration for a node (appliance) --- Requires node::configure:network 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 Zero Trust Network Access gateway settings for secure remote access - [PUT /node/{nodeID}/config/ztnagw](https://apidocs.trustgrid.io/appliance/paths/~1node~1%7Bnodeid%7D~1config~1ztnagw/put.md): Update ZTNA gateway configuration for a node (appliance) Note that this endpoint used to be apigw. The config section is still named apigw. --- "WireGuard" is a registered trademark of Jason A. Donenfeld. Requires node::configure::apigw permissions ## Remove ZTNA gateway configuration and disable secure remote access - [DELETE /node/{nodeID}/config/ztnagw](https://apidocs.trustgrid.io/appliance/paths/~1node~1%7Bnodeid%7D~1config~1ztnagw/delete.md): Delete the ZTNA gateway configuration for a node (appliance) --- Requires node::configure::apigw 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). ## Retrieve real-time network usage statistics and bandwidth metrics for nodes - [GET /stats/realtime/usage](https://apidocs.trustgrid.io/appliance/getrealtimeusage.md): Returns an array of usage data buckets for specified nodes within the specified time range and interval. ## Delete a file or directory - [DELETE /v2/node/{nodeID}/data-store](https://apidocs.trustgrid.io/appliance/paths/~1v2~1node~1%7Bnodeid%7D~1data-store/delete.md): Requires nodes::service:datastore-manager permission. ## Copy a file from an HTTP location to the data store - [POST /v2/node/{nodeID}/data-store/http-download](https://apidocs.trustgrid.io/appliance/paths/~1v2~1node~1%7Bnodeid%7D~1data-store~1http-download/post.md): Requires nodes::service:datastore-manager permission. ## Upload a file from the node to an HTTP endpoint - [POST /v2/node/{nodeID}/data-store/http-upload](https://apidocs.trustgrid.io/appliance/paths/~1v2~1node~1%7Bnodeid%7D~1data-store~1http-upload/post.md): Requires nodes::service:datastore-manager permission. ## List the data store contents - [GET /v2/node/{nodeID}/data-store/list](https://apidocs.trustgrid.io/appliance/listnodedatastorecontents.md): Requires nodes::service:datastore-manager permission. ## Create a directory - [POST /v2/node/{nodeID}/data-store/mkdir](https://apidocs.trustgrid.io/appliance/paths/~1v2~1node~1%7Bnodeid%7D~1data-store~1mkdir/post.md): Requires nodes::service:datastore-manager permission. ## Copy a file from S3 to the data store - [POST /v2/node/{nodeID}/data-store/s3-download](https://apidocs.trustgrid.io/appliance/paths/~1v2~1node~1%7Bnodeid%7D~1data-store~1s3-download/post.md): Requires nodes::service:datastore-manager permission. ## Upload a file from the node to an S3 bucket - [POST /v2/node/{nodeID}/data-store/s3-upload](https://apidocs.trustgrid.io/appliance/paths/~1v2~1node~1%7Bnodeid%7D~1data-store~1s3-upload/post.md): Requires nodes::service:datastore-manager permission. ## List recent data store activity - [GET /v2/node/{nodeID}/data-store/tasks](https://apidocs.trustgrid.io/appliance/listnodedatastoretasks.md): Requires nodes::service:datastore-manager permission. ## Get per-minute gateway RTT telemetry for a node's VPN peer connections - [GET /v2/node/{nodeID}/plugin-logs/gateway-details](https://apidocs.trustgrid.io/appliance/getnodegatewaydetails.md): Returns time-series RTT (round-trip time) statistics for each VPN peer the node is connected to. Each element covers one minute bucket. Results are only available for online appliance nodes. --- Requires nodes::read permission. ## 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.