{ "openapi": "3.2.0", "info": { "title": "Forward: Controller-Managed Setups API", "summary": "Specify the SDN controllers to collect from and the devices they manage", "description": "A _controller-managed setup_ groups an SDN controller cluster (such as a Cisco APIC cluster or an SD-WAN\norchestrator) with the devices it manages so that the network’s Collector collects from them together. Each setup\nhas a unique name, one or more `controllers`, and, for setup types whose managed devices are collected directly,\n`managedDevices`.\n\nControllers and managed devices take the same connection and collection settings as\n[classic devices](https://docs.fwd.app/latest/api/classic-devices/). A setup’s name and the names of its devices\nmust be unique (ignoring case) among all of the network’s collection source names.", "contact": { "email": "support@forwardnetworks.com" }, "license": { "name": "MIT", "url": "https://spdx.org/licenses/MIT" }, "version": "26.10" }, "servers": [ { "url": "/api" } ], "security": [ { "api_token": [] } ], "tags": [ { "name": "Collection Sources", "description": "Specify the devices, endpoints, and other sources to collect from" }, { "name": "Controller-Managed Setups", "description": "Specify the SDN controllers to collect from and the devices they manage", "parent": "Collection Sources" }, { "name": "Experimental", "description": "Operations whose contract may change without a deprecation period", "kind": "badge" } ], "paths": { "/networks/{networkId}/controller-managed-setup-tests": { "post": { "tags": [ "Controller-Managed Setups", "Experimental" ], "summary": "Test connectivity to an unsaved controller", "description": "Tests whether the Collector can reach and log in to a controller before the setup is saved, and waits for the\nresult.", "operationId": "testControllerManagedSetup", "x-position": 12, "parameters": [ { "name": "networkId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControllerManagedSetupConnectivityTestRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceConnectivityResult" } } } } } } }, "/networks/{networkId}/controller-managed-setups": { "get": { "tags": [ "Controller-Managed Setups", "Experimental" ], "summary": "Get all controller-managed setups", "operationId": "getControllerManagedSetups", "x-position": 1, "parameters": [ { "name": "networkId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "with", "in": "query", "description": "Optional properties to include in each controller and managed device. Use a comma (as in\n`?with=tags,testResult`) or repeat this parameter to request more than one.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "tags", "locationId", "testResult" ] } } }, { "name": "type", "in": "query", "description": "Limits the results to setups of this type. Omit to get setups of all types.", "schema": { "$ref": "#/components/schemas/ControllerManagedSetupType" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControllerManagedSetups" } } } } } }, "post": { "tags": [ "Controller-Managed Setups", "Experimental" ], "summary": "Add a controller-managed setup", "operationId": "addControllerManagedSetup", "x-position": 2, "parameters": [ { "name": "networkId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewControllerManagedSetup" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControllerManagedSetup" } } } } } }, "patch": { "tags": [ "Controller-Managed Setups", "Experimental" ], "summary": "Update specific controllers and managed devices", "description": "Applies the same `update` to every selected controller and managed device. Selected names that don’t match any\ndevice are ignored.", "operationId": "patchControllersAndManagedDevices", "x-position": 10, "parameters": [ { "name": "networkId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControllerManagedDevicesBulkPatch" } } }, "required": true }, "responses": { "204": { "description": "No Content", "content": {} } } } }, "/networks/{networkId}/controller-managed-setups?action=delete": { "post": { "tags": [ "Controller-Managed Setups", "Experimental" ], "summary": "Delete specific controllers and managed devices", "description": "Selecting by `setupNames` deletes the entire setups. Selecting by `names` removes the devices from their setups,\nand fails without deleting anything if that would leave a setup with no controllers or no managed devices.", "operationId": "deleteControllersAndManagedDevices", "x-position": 11, "parameters": [ { "name": "networkId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControllerAndManagedDeviceSelection" } } }, "required": true }, "responses": { "204": { "description": "No Content", "content": {} } } } }, "/networks/{networkId}/controller-managed-setups?action=migrate": { "post": { "tags": [ "Controller-Managed Setups", "Experimental" ], "summary": "Add a controller-managed setup with migration", "description": "Adds the setup after deleting any classic devices whose names match one of its controllers or managed devices.\nUse this to convert classic devices into members of a setup.", "operationId": "addControllerManagedSetupWithMigration", "x-position": 3, "parameters": [ { "name": "networkId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewControllerManagedSetup" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControllerManagedSetup" } } } } } } }, "/networks/{networkId}/controller-managed-setups?action=test": { "post": { "tags": [ "Controller-Managed Setups", "Experimental" ], "summary": "Test controller-managed setups", "description": "Queues connectivity tests and returns immediately. Each result appears in the device’s `testResult` (see\n`with=testResult` on the get-all operation) once the Collector finishes.", "operationId": "testControllerManagedSetups", "x-position": 13, "parameters": [ { "name": "networkId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "collectorId", "in": "query", "description": "The `id` of the Collector to run the tests on. Omit to use the one that collects from each\nsetup.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControllerAndManagedDeviceSelection" } } }, "required": true }, "responses": { "204": { "description": "No Content", "content": {} } } } }, "/networks/{networkId}/controller-managed-setups/{setupName}": { "patch": { "tags": [ "Controller-Managed Setups", "Experimental" ], "summary": "Update a controller-managed setup", "operationId": "patchControllerManagedSetup", "x-position": 4, "parameters": [ { "name": "networkId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "setupName", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControllerManagedSetupPatch" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControllerManagedSetup" } } } } } }, "delete": { "tags": [ "Controller-Managed Setups", "Experimental" ], "summary": "Delete a controller-managed setup", "description": "Deletes the setup and its controllers and managed devices, including their tags and test results.", "operationId": "deleteControllerManagedSetup", "x-position": 5, "parameters": [ { "name": "networkId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "setupName", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content", "content": {} } } } }, "/networks/{networkId}/controller-managed-setups/{setupName}/controllers/{name}": { "patch": { "tags": [ "Controller-Managed Setups", "Experimental" ], "summary": "Update a setup’s controller", "operationId": "patchControllerDevice", "x-position": 6, "parameters": [ { "name": "networkId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "setupName", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The `name` of the controller to update.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControllerDevicePatch" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControllerDevice" } } } } } }, "delete": { "tags": [ "Controller-Managed Setups", "Experimental" ], "summary": "Remove a controller from a setup", "description": "Also deletes the controller’s tags and test result. Fails if it’s the setup’s only controller.", "operationId": "deleteControllerDevice", "x-position": 7, "parameters": [ { "name": "networkId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "setupName", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The `name` of the controller to remove.", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content", "content": {} } } } }, "/networks/{networkId}/controller-managed-setups/{setupName}/controllers/{name}?action=test": { "post": { "tags": [ "Controller-Managed Setups", "Experimental" ], "summary": "Test connectivity to a setup’s controller", "description": "Queues a connectivity test on the Collector that collects from the setup, and returns immediately. The result\nappears in the controller’s `testResult` (see `with=testResult` on the get-all operation) once the Collector\nfinishes.", "operationId": "testControllerDevice", "x-position": 14, "parameters": [ { "name": "networkId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "setupName", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The `name` of the controller to test.", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content", "content": {} } } } }, "/networks/{networkId}/controller-managed-setups/{setupName}/managed-devices/{name}": { "patch": { "tags": [ "Controller-Managed Setups", "Experimental" ], "summary": "Update a setup’s managed device", "operationId": "patchManagedDevice", "x-position": 8, "parameters": [ { "name": "networkId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "setupName", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The `name` of the managed device to update.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedDevicePatch" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControllerManagedDevice" } } } } } }, "delete": { "tags": [ "Controller-Managed Setups", "Experimental" ], "summary": "Remove a managed device from a setup", "description": "Also deletes the device’s tags and test result. Fails if it’s the setup’s only managed device.", "operationId": "deleteManagedDevice", "x-position": 9, "parameters": [ { "name": "networkId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "setupName", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The `name` of the managed device to remove.", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content", "content": {} } } } }, "/networks/{networkId}/controller-managed-setups/{setupName}/managed-devices/{name}?action=test": { "post": { "tags": [ "Controller-Managed Setups", "Experimental" ], "summary": "Test connectivity to a setup’s managed device", "description": "Queues a connectivity test on the Collector that collects from the setup, and returns immediately. The result\nappears in the device’s `testResult` (see `with=testResult` on the get-all operation) once the Collector\nfinishes.", "operationId": "testManagedDevice", "x-position": 15, "parameters": [ { "name": "networkId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "setupName", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The `name` of the managed device to test.", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content", "content": {} } } } } }, "components": { "schemas": { "ControllerAndManagedDeviceSelection": { "type": "object", "properties": { "names": { "type": "array", "items": { "type": "string" }, "description": "The names of the controllers and managed devices to select.", "examples": [ [ "apic1", "leaf-101" ] ] }, "setupNames": { "type": "array", "items": { "type": "string" }, "description": "The names of the setups whose controllers and managed devices to select.", "examples": [ [ "my-aci-fabric" ] ] } }, "description": "Selects controllers and managed devices by device name or by setup name. Specify exactly one of `names` and\n`setupNames`." }, "ControllerDevice": { "allOf": [ { "type": "object", "required": [ "name", "host" ], "properties": { "ndoName": { "type": "string", "description": "The `name` of the Cisco Nexus Dashboard Orchestrator (NDO) host linked to this APIC, if any." }, "name": { "type": "string", "description": "A name that’s unique (ignoring case) among all of the network’s collection source names. May consist of\nletters, digits, dots, hyphens, and underscores.", "examples": [ "apic1" ] }, "type": { "$ref": "#/components/schemas/ControllerDeviceType", "description": "Auto-detected during connectivity testing if unspecified.", "examples": [ "cisco_apic_api" ] }, "host": { "type": "string", "description": "IP address or hostname used to connect to the device.", "examples": [ "10.121.7.13" ] }, "port": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 65535, "description": "Port used to connect to the device. The default value depends on the collection protocol: 22 for SSH, 443\nfor HTTPS, etc.", "examples": [ 22 ] }, "cliCredentialId": { "type": "string", "description": "The `id` of a CliCredential of type `LOGIN`. Relevant for devices collected via SSH or Telnet. Credential\nauto-association will be attempted using credentials configured to allow it if this property is unspecified\nand collecting from this device requires this kind of credential.", "examples": [ "L-3" ] }, "cliCredential2Id": { "type": "string", "description": "The `id` of a CliCredential of type `PRIVILEGED_MODE` (for Cisco-like or Checkpoint devices) or `SHELL` (for\nAvi controllers). On Checkpoint, this credential is used for TACACS privilege escalation. Credential\nauto-association will be attempted using credentials configured to allow it if this property is unspecified\nand collecting from this device requires this kind of credential.", "examples": [ "PM-2" ] }, "cliCredential3Id": { "type": "string", "description": "The `id` of a CliCredential of type `EXPERT_MODE` (for Checkpoint devices). Can be set with or without a\n`PRIVILEGED_MODE` credential for `cliCredential2Id`. Credential auto-association will be attempted using\ncredentials configured to allow it if this property is unspecified and collecting from this device requires\nthis kind of credential.", "examples": [ "EM-6" ] }, "httpCredentialId": { "type": "string", "description": "The `id` of an HttpCredential of type `LOGIN` or `API_KEY`. Relevant for devices collected via HTTPS or\nHTTP. Credential auto-association will be attempted using credentials configured to allow it if this\nproperty is unspecified and collecting from this device requires this kind of credential.", "examples": [ "H-5" ] }, "snmpCredentialId": { "type": "string", "description": "The `id` of an SnmpCredential. Used to collect performance data (counters) if `enableSnmpCollection` is\ntrue. Credential auto-association will be attempted using credentials configured to allow it if this\nproperty is unspecified and collecting from this device requires this kind of credential.", "examples": [ "S-4" ] }, "jumpServerId": { "type": "string", "description": "The `id` of the JumpServer that should be used to collect from this device.", "examples": [ "J-0" ] }, "disableIpv6Collection": { "type": "boolean", "description": "Disables collection of any IPv6 forwarding state on the device. Defaults to false.", "examples": [ false ] }, "fullCollectionLog": { "type": "boolean", "description": "Enables more detailed logging during collection. Defaults to false.", "examples": [ false ] }, "paginationMode": { "$ref": "#/components/schemas/PaginationMode", "description": "The pagination mode to use during collection. Relevant for devices collected via SSH or Telnet. Defaults to\n`DISABLE_PAGINATION`. Per-command pagination (such as appending `| more`) may be used if set to\n`ENABLE_PAGINATION` for a device that doesn’t have a per-session pagination mode setting.", "examples": [ "KEEP_UNCHANGED" ] }, "terminalWidth": { "type": "integer", "format": "int32", "minimum": 80, "maximum": 500, "description": "Width of pseudo-terminal in characters. A high value can prevent long lines from wrapping. Defaults to 500.\nRelevant for devices collected via SSH or Telnet.", "examples": [ 500 ] }, "largeRtt": { "type": "boolean", "description": "Whether the device has a large round-trip time (requires a longer response timeout).", "examples": [ false ] }, "minBytesReadPerSec": { "type": "integer", "format": "int64", "description": "The minimum read rate in bytes/sec required to prevent collection from failing with a\n`SLOW_READ_RATE_DETECTED` error. Defaults to 500.", "examples": [ 1000 ] }, "maxConnectionsPerMin": { "type": "integer", "format": "int32", "description": "The maximum number of connections to this device that should be attempted per minute. Setting this property\ncan prevent spurious connectivity test failures if the device’s SSH server is configured with a connection\nrate limit.", "examples": [ 10 ] }, "useFileTransferForLargeOutput": { "type": "boolean", "description": "Whether to use file transfer instead of printing large command output directly to the shell. This is\ncurrently only supported for Juniper devices when executing routing table commands. The primary purpose is\nto avoid printing large outputs directly to the shell, which on Juniper devices can interfere with packet\nforwarding performance. Instead, the command output is written to a temporary file on the device and then\ntransferred over a separate connection. After the transfer is complete, the temporary file is deleted to\nprevent unnecessary disk usage on the device.", "examples": [ false ] }, "bmpStationHost": { "type": "string", "description": "IP address or hostname of the BMP station from which BMP collection should be performed for this device. If\nset, a jump server won’t be used for BMP collection.", "examples": [ "10.121.7.33" ] }, "bgpAndBmpFailureHandling": { "type": "string", "description": "How to handle BGP or BMP collection failure. Defaults to `FAIL_DEVICE`.", "examples": [ "SWITCH_TO_CLI" ], "enum": [ "FAIL_DEVICE", "SWITCH_TO_CLI", "ALWAYS_USE_CLI", "ALWAYS_USE_BMP", "CONTINUE_WITHOUT_BGP_DATA" ] }, "collectBgpAdvertisements": { "type": "boolean", "description": "Whether BGP advertisements should be collected. Defaults to `false` unless advertisement collection is\nrequired to model a [synthetic device](https://docs.fwd.app/latest/api/synthetic-devices/) connected to this\ndevice.", "examples": [ false ] }, "bgpTableType": { "type": "string", "description": "The BGP route types to collect. Honored only if `collectBgpAdvertisements` is true. Defaults\nto `BOTH`.", "examples": [ "BOTH" ], "enum": [ "BOTH", "ADJ_RIB_IN", "ADJ_RIB_OUT" ] }, "bgpPeerType": { "type": "string", "description": "The BGP peer types from which to collect routes. Honored only if `collectBgpAdvertisements` is true.\nDefaults to `BOTH`.", "examples": [ "BOTH" ], "enum": [ "BOTH", "EBGP", "IBGP" ] }, "bgpSubnetsToCollect": { "type": "array", "items": { "type": "string" }, "description": "Restricts collection of BGP advertisements to specific subnets if the device supports it. Honored only if\n`collectBgpAdvertisements` is `true`.", "examples": [ [ "123.223.47.0/24" ] ] }, "prompt": { "type": "string", "description": "A case-insensitive glob pattern used to identify an interactive prompt. When this pattern matches the end of\nthe prompt, ignoring any trailing whitespace, the Collector will enter the configured `promptResponse`.\nRelevant for devices collected via SSH or Telnet.", "examples": [ "y/n" ] }, "promptResponse": { "type": "string", "description": "What the Collector should enter in response to a device prompt matching `prompt` in order to proceed.\nRelevant for devices collected via SSH or Telnet. Required if `prompt` is set.", "examples": [ "y" ] }, "collect": { "type": "boolean", "description": "Whether to collect from the device. Defaults to true.", "examples": [ false ] }, "note": { "type": "string", "description": "An optional description or note about the device." }, "enableSnmpCollection": { "type": "boolean", "description": "Whether to collect performance data (counters) via SNMP. Defaults to false.", "examples": [ false ] }, "highCpuUsage": { "type": "number", "format": "float", "minimum": 0.75, "maximum": 1, "description": "Threshold at or above which CPU usage is considered high. Defaults to 0.8 (80.0%).", "examples": [ 0.85 ] }, "highMemoryUsage": { "type": "number", "format": "float", "minimum": 0.75, "maximum": 1, "description": "Threshold at or above which memory usage is considered high. Defaults to 0.9 (90.0%).", "examples": [ 0.92 ] }, "highInputUtilization": { "type": "number", "format": "float", "minimum": 0.75, "maximum": 1, "description": "Threshold at or above which input interface utilization is considered high. Defaults to 0.9\n(90.0%).", "examples": [ 0.8 ] }, "highOutputUtilization": { "type": "number", "format": "float", "minimum": 0.75, "maximum": 1, "description": "Threshold at or above which output interface utilization is considered high. Defaults to 0.9\n(90.0%).", "examples": [ 0.88 ] }, "mediumCpuUsage": { "type": "number", "format": "float", "minimum": 0.5, "maximum": 1, "description": "Threshold at or above which CPU usage is considered medium high. Has no default value.", "examples": [ 0.7 ] }, "mediumMemoryUsage": { "type": "number", "format": "float", "minimum": 0.5, "maximum": 1, "description": "Threshold at or above which memory usage is considered medium high. Has no default value.", "examples": [ 0.71 ] }, "mediumInputUtilization": { "type": "number", "format": "float", "minimum": 0.5, "maximum": 1, "description": "Threshold at or above which input interface utilization is considered medium high. Has no\ndefault value.", "examples": [ 0.72 ] }, "mediumOutputUtilization": { "type": "number", "format": "float", "minimum": 0.5, "maximum": 1, "description": "Threshold at or above which output interface utilization is considered medium high. Has no\ndefault value.", "examples": [ 0.73 ] }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags assigned to the device. Present only if specifically requested." }, "locationId": { "type": "string", "description": "The `id` of the device’s assigned Location (see\n[Network Locations](https://docs.fwd.app/latest/api/network-locations/)). Present only if specifically\nrequested. Defaults to \"default\" (the Unassigned location).", "examples": [ "atl" ] }, "testResult": { "$ref": "#/components/schemas/SourceConnectivityResult", "description": "The device’s most recent connectivity test result. Present only if specifically requested. Absent if the\ndevice’s connectivity hasn’t been tested since the last substantial edit to the device." } } }, { "$ref": "#/components/schemas/Attribution" } ] }, "ControllerDevicePatch": { "type": "object", "properties": { "name": { "type": "string", "description": "A name that’s unique (ignoring case) among all of the network’s collection source names. May consist of\nletters, digits, dots, hyphens, and underscores. Use `null` to clear. Omit to leave the property alone.", "examples": [ "apic1" ] }, "type": { "$ref": "#/components/schemas/ControllerDeviceType", "description": "Auto-detected during connectivity testing if unspecified. Use `null` to clear. Omit to leave the property\nalone.", "examples": [ "cisco_apic_api" ] }, "host": { "type": "string", "description": "IP address or hostname used to connect to the device. Use `null` to clear. Omit to leave the\nproperty alone.", "examples": [ "10.121.7.13" ] }, "port": { "type": "integer", "format": "int32", "description": "Port used to connect to the device. The default value depends on the collection protocol: 22 for SSH, 443\nfor HTTPS, etc. Use `null` to clear. Omit to leave the property alone.", "examples": [ 22 ] }, "cliCredentialId": { "type": "string", "description": "The `id` of a CliCredential of type `LOGIN`. Relevant for devices collected via SSH or Telnet. Credential\nauto-association will be attempted using credentials configured to allow it if this property is unspecified\nand collecting from this device requires this kind of credential. Use `null` to clear. Omit to leave the\nproperty alone.", "examples": [ "L-3" ] }, "cliCredential2Id": { "type": "string", "description": "The `id` of a CliCredential of type `PRIVILEGED_MODE` (for Cisco-like or Checkpoint devices) or `SHELL` (for\nAvi controllers). On Checkpoint, this credential is used for TACACS privilege escalation. Credential\nauto-association will be attempted using credentials configured to allow it if this property is unspecified\nand collecting from this device requires this kind of credential. Use `null` to clear. Omit to leave the\nproperty alone.", "examples": [ "PM-2" ] }, "cliCredential3Id": { "type": "string", "description": "The `id` of a CliCredential of type `EXPERT_MODE` (for Checkpoint devices). Can be set with or without a\n`PRIVILEGED_MODE` credential for `cliCredential2Id`. Credential auto-association will be attempted using\ncredentials configured to allow it if this property is unspecified and collecting from this device requires\nthis kind of credential. Use `null` to clear. Omit to leave the property alone.", "examples": [ "EM-6" ] }, "httpCredentialId": { "type": "string", "description": "The `id` of an HttpCredential of type `LOGIN` or `API_KEY`. Relevant for devices collected via HTTPS or\nHTTP. Credential auto-association will be attempted using credentials configured to allow it if this\nproperty is unspecified and collecting from this device requires this kind of credential. Use `null` to\nclear. Omit to leave the property alone.", "examples": [ "H-5" ] }, "snmpCredentialId": { "type": "string", "description": "The `id` of an SnmpCredential. Used to collect performance data (counters) if `enableSnmpCollection` is\ntrue. Credential auto-association will be attempted using credentials configured to allow it if this\nproperty is unspecified and collecting from this device requires this kind of credential. Use `null` to\nclear. Omit to leave the property alone.", "examples": [ "S-4" ] }, "jumpServerId": { "type": "string", "description": "The `id` of the JumpServer that should be used to collect from this device. Use `null` to clear. Omit to\nleave the property alone.", "examples": [ "J-0" ] }, "disableIpv6Collection": { "type": "boolean", "description": "Disables collection of any IPv6 forwarding state on the device. Defaults to false. Use `null` to clear. Omit\nto leave the property alone.", "examples": [ false ] }, "fullCollectionLog": { "type": "boolean", "description": "Enables more detailed logging during collection. Defaults to false. Use `null` to clear. Omit to leave the\nproperty alone.", "examples": [ false ] }, "paginationMode": { "$ref": "#/components/schemas/PaginationMode", "description": "The pagination mode to use during collection. Relevant for devices collected via SSH or Telnet. Defaults to\n`DISABLE_PAGINATION`. Per-command pagination (such as appending `| more`) may be used if set to\n`ENABLE_PAGINATION` for a device that doesn’t have a per-session pagination mode setting. Use `null` to\nclear. Omit to leave the property alone.", "examples": [ "KEEP_UNCHANGED" ] }, "terminalWidth": { "type": "integer", "format": "int32", "description": "Width of pseudo-terminal in characters. A high value can prevent long lines from wrapping. Defaults to 500.\nRelevant for devices collected via SSH or Telnet. Use `null` to clear. Omit to leave the property alone.", "examples": [ 500 ] }, "largeRtt": { "type": "boolean", "description": "Whether the device has a large round-trip time (requires a longer response timeout). Use `null` to clear.\nOmit to leave the property alone.", "examples": [ false ] }, "minBytesReadPerSec": { "type": "integer", "format": "int64", "description": "The minimum read rate in bytes/sec required to prevent collection from failing with a\n`SLOW_READ_RATE_DETECTED` error. Defaults to 500. Use `null` to clear. Omit to leave the property alone.", "examples": [ 1000 ] }, "maxConnectionsPerMin": { "type": "integer", "format": "int32", "description": "The maximum number of connections to this device that should be attempted per minute. Setting this property\ncan prevent spurious connectivity test failures if the device’s SSH server is configured with a connection\nrate limit. Use `null` to clear. Omit to leave the property alone.", "examples": [ 10 ] }, "useFileTransferForLargeOutput": { "type": "boolean", "description": "Whether to use file transfer instead of printing large command output directly to the shell. This is\ncurrently only supported for Juniper devices when executing routing table commands. The primary purpose is\nto avoid printing large outputs directly to the shell, which on Juniper devices can interfere with packet\nforwarding performance. Instead, the command output is written to a temporary file on the device and then\ntransferred over a separate connection. After the transfer is complete, the temporary file is deleted to\nprevent unnecessary disk usage on the device. Use `null` to clear. Omit to leave the property alone.", "examples": [ false ] }, "bmpStationHost": { "type": "string", "description": "IP address or hostname of the BMP station from which BMP collection should be performed for this device. If\nset, a jump server won’t be used for BMP collection. Use `null` to clear. Omit to leave the property alone.", "examples": [ "10.121.7.33" ] }, "bgpAndBmpFailureHandling": { "type": "string", "description": "How to handle BGP or BMP collection failure. Defaults to `FAIL_DEVICE`. Use `null` to clear. Omit to leave\nthe property alone.", "examples": [ "SWITCH_TO_CLI" ], "enum": [ "FAIL_DEVICE", "SWITCH_TO_CLI", "ALWAYS_USE_CLI", "ALWAYS_USE_BMP", "CONTINUE_WITHOUT_BGP_DATA" ] }, "collectBgpAdvertisements": { "type": "boolean", "description": "Whether BGP advertisements should be collected. Defaults to `false` unless advertisement collection is\nrequired to model a [synthetic device](https://docs.fwd.app/latest/api/synthetic-devices/) connected to this\ndevice. Use `null` to clear. Omit to leave the property alone.", "examples": [ false ] }, "bgpTableType": { "type": "string", "description": "The BGP route types to collect. Honored only if `collectBgpAdvertisements` is true. Defaults to `BOTH`.\nUse `null` to clear. Omit to leave the property alone.", "examples": [ "BOTH" ], "enum": [ "BOTH", "ADJ_RIB_IN", "ADJ_RIB_OUT" ] }, "bgpPeerType": { "type": "string", "description": "The BGP peer types from which to collect routes. Honored only if `collectBgpAdvertisements` is true.\nDefaults to `BOTH`. Use `null` to clear. Omit to leave the property alone.", "examples": [ "BOTH" ], "enum": [ "BOTH", "EBGP", "IBGP" ] }, "bgpSubnetsToCollect": { "type": "array", "items": { "type": "string" }, "description": "Restricts collection of BGP advertisements to specific subnets if the device supports it. Honored only if\n`collectBgpAdvertisements` is `true`. Use `null` to clear. Omit to leave the property alone.", "examples": [ [ "123.223.47.0/24" ] ] }, "prompt": { "type": "string", "description": "A case-insensitive glob pattern used to identify an interactive prompt. When this pattern matches the end of\nthe prompt, ignoring any trailing whitespace, the Collector will enter the configured `promptResponse`.\nRelevant for devices collected via SSH or Telnet. Use `null` to clear. Omit to leave the property alone.", "examples": [ "y/n" ] }, "promptResponse": { "type": "string", "description": "What the Collector should enter in response to a device prompt matching `prompt` in order to proceed.\nRelevant for devices collected via SSH or Telnet. Required if `prompt` is set. Use `null` to clear. Omit to\nleave the property alone.", "examples": [ "y" ] }, "ndoName": { "type": "string", "description": "The `name` of the Cisco Nexus Dashboard Orchestrator (NDO) host linked to this APIC, if any. Use `null` to clear.\nOmit to leave the property alone." }, "collect": { "type": "boolean", "description": "Whether to collect from the device. Defaults to true. Use `null` to clear. Omit to leave the\nproperty alone.", "examples": [ false ] }, "note": { "type": "string", "description": "An optional description or note about the device. Use `null` to clear. Omit to leave the\nproperty alone." }, "enableSnmpCollection": { "type": "boolean", "description": "Whether to collect performance data (counters) via SNMP. Defaults to false. Use `null` to clear. Omit to\nleave the property alone.", "examples": [ false ] }, "highCpuUsage": { "type": "number", "format": "float", "description": "Threshold at or above which CPU usage is considered high. Defaults to 0.8 (80.0%). Use `null` to clear. Omit\nto leave the property alone.", "examples": [ 0.85 ] }, "highMemoryUsage": { "type": "number", "format": "float", "description": "Threshold at or above which memory usage is considered high. Defaults to 0.9 (90.0%). Use `null` to clear.\nOmit to leave the property alone.", "examples": [ 0.92 ] }, "highInputUtilization": { "type": "number", "format": "float", "description": "Threshold at or above which input interface utilization is considered high. Defaults to 0.9 (90.0%). Use\n`null` to clear. Omit to leave the property alone.", "examples": [ 0.8 ] }, "highOutputUtilization": { "type": "number", "format": "float", "description": "Threshold at or above which output interface utilization is considered high. Defaults to 0.9 (90.0%). Use\n`null` to clear. Omit to leave the property alone.", "examples": [ 0.88 ] }, "mediumCpuUsage": { "type": "number", "format": "float", "description": "Threshold at or above which CPU usage is considered medium high. Has no default value. Use `null` to clear.\nOmit to leave the property alone.", "examples": [ 0.7 ] }, "mediumMemoryUsage": { "type": "number", "format": "float", "description": "Threshold at or above which memory usage is considered medium high. Has no default value. Use `null` to\nclear. Omit to leave the property alone.", "examples": [ 0.71 ] }, "mediumInputUtilization": { "type": "number", "format": "float", "description": "Threshold at or above which input interface utilization is considered medium high. Has no default value. Use\n`null` to clear. Omit to leave the property alone.", "examples": [ 0.72 ] }, "mediumOutputUtilization": { "type": "number", "format": "float", "description": "Threshold at or above which output interface utilization is considered medium high. Has no default value.\nUse `null` to clear. Omit to leave the property alone.", "examples": [ 0.73 ] } } }, "ControllerManagedDevice": { "allOf": [ { "type": "object", "required": [ "name", "host" ], "properties": { "name": { "type": "string", "description": "A name that’s unique (ignoring case) among all of the network’s collection source names. May consist of\nletters, digits, dots, hyphens, and underscores.", "examples": [ "leaf-101" ] }, "type": { "$ref": "#/components/schemas/ControllerManagedDeviceType", "description": "Auto-detected during connectivity testing if unspecified.", "examples": [ "cisco_nxos_aci_ssh" ] }, "host": { "type": "string", "description": "IP address or hostname used to connect to the device.", "examples": [ "10.121.7.13" ] }, "port": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 65535, "description": "Port used to connect to the device. The default value depends on the collection protocol: 22 for SSH, 443\nfor HTTPS, etc.", "examples": [ 22 ] }, "cliCredentialId": { "type": "string", "description": "The `id` of a CliCredential of type `LOGIN`. Relevant for devices collected via SSH or Telnet. Credential\nauto-association will be attempted using credentials configured to allow it if this property is unspecified\nand collecting from this device requires this kind of credential.", "examples": [ "L-3" ] }, "cliCredential2Id": { "type": "string", "description": "The `id` of a CliCredential of type `PRIVILEGED_MODE` (for Cisco-like or Checkpoint devices) or `SHELL` (for\nAvi controllers). On Checkpoint, this credential is used for TACACS privilege escalation. Credential\nauto-association will be attempted using credentials configured to allow it if this property is unspecified\nand collecting from this device requires this kind of credential.", "examples": [ "PM-2" ] }, "cliCredential3Id": { "type": "string", "description": "The `id` of a CliCredential of type `EXPERT_MODE` (for Checkpoint devices). Can be set with or without a\n`PRIVILEGED_MODE` credential for `cliCredential2Id`. Credential auto-association will be attempted using\ncredentials configured to allow it if this property is unspecified and collecting from this device requires\nthis kind of credential.", "examples": [ "EM-6" ] }, "httpCredentialId": { "type": "string", "description": "The `id` of an HttpCredential of type `LOGIN` or `API_KEY`. Relevant for devices collected via HTTPS or\nHTTP. Credential auto-association will be attempted using credentials configured to allow it if this\nproperty is unspecified and collecting from this device requires this kind of credential.", "examples": [ "H-5" ] }, "snmpCredentialId": { "type": "string", "description": "The `id` of an SnmpCredential. Used to collect performance data (counters) if `enableSnmpCollection` is\ntrue. Credential auto-association will be attempted using credentials configured to allow it if this\nproperty is unspecified and collecting from this device requires this kind of credential.", "examples": [ "S-4" ] }, "jumpServerId": { "type": "string", "description": "The `id` of the JumpServer that should be used to collect from this device.", "examples": [ "J-0" ] }, "disableIpv6Collection": { "type": "boolean", "description": "Disables collection of any IPv6 forwarding state on the device. Defaults to false.", "examples": [ false ] }, "fullCollectionLog": { "type": "boolean", "description": "Enables more detailed logging during collection. Defaults to false.", "examples": [ false ] }, "paginationMode": { "$ref": "#/components/schemas/PaginationMode", "description": "The pagination mode to use during collection. Relevant for devices collected via SSH or Telnet. Defaults to\n`DISABLE_PAGINATION`. Per-command pagination (such as appending `| more`) may be used if set to\n`ENABLE_PAGINATION` for a device that doesn’t have a per-session pagination mode setting.", "examples": [ "KEEP_UNCHANGED" ] }, "terminalWidth": { "type": "integer", "format": "int32", "minimum": 80, "maximum": 500, "description": "Width of pseudo-terminal in characters. A high value can prevent long lines from wrapping. Defaults to 500.\nRelevant for devices collected via SSH or Telnet.", "examples": [ 500 ] }, "largeRtt": { "type": "boolean", "description": "Whether the device has a large round-trip time (requires a longer response timeout).", "examples": [ false ] }, "minBytesReadPerSec": { "type": "integer", "format": "int64", "description": "The minimum read rate in bytes/sec required to prevent collection from failing with a\n`SLOW_READ_RATE_DETECTED` error. Defaults to 500.", "examples": [ 1000 ] }, "maxConnectionsPerMin": { "type": "integer", "format": "int32", "description": "The maximum number of connections to this device that should be attempted per minute. Setting this property\ncan prevent spurious connectivity test failures if the device’s SSH server is configured with a connection\nrate limit.", "examples": [ 10 ] }, "useFileTransferForLargeOutput": { "type": "boolean", "description": "Whether to use file transfer instead of printing large command output directly to the shell. This is\ncurrently only supported for Juniper devices when executing routing table commands. The primary purpose is\nto avoid printing large outputs directly to the shell, which on Juniper devices can interfere with packet\nforwarding performance. Instead, the command output is written to a temporary file on the device and then\ntransferred over a separate connection. After the transfer is complete, the temporary file is deleted to\nprevent unnecessary disk usage on the device.", "examples": [ false ] }, "bmpStationHost": { "type": "string", "description": "IP address or hostname of the BMP station from which BMP collection should be performed for this device. If\nset, a jump server won’t be used for BMP collection.", "examples": [ "10.121.7.33" ] }, "bgpAndBmpFailureHandling": { "type": "string", "description": "How to handle BGP or BMP collection failure. Defaults to `FAIL_DEVICE`.", "examples": [ "SWITCH_TO_CLI" ], "enum": [ "FAIL_DEVICE", "SWITCH_TO_CLI", "ALWAYS_USE_CLI", "ALWAYS_USE_BMP", "CONTINUE_WITHOUT_BGP_DATA" ] }, "collectBgpAdvertisements": { "type": "boolean", "description": "Whether BGP advertisements should be collected. Defaults to `false` unless advertisement collection is\nrequired to model a [synthetic device](https://docs.fwd.app/latest/api/synthetic-devices/) connected to this\ndevice.", "examples": [ false ] }, "bgpTableType": { "type": "string", "description": "The BGP route types to collect. Honored only if `collectBgpAdvertisements` is true. Defaults\nto `BOTH`.", "examples": [ "BOTH" ], "enum": [ "BOTH", "ADJ_RIB_IN", "ADJ_RIB_OUT" ] }, "bgpPeerType": { "type": "string", "description": "The BGP peer types from which to collect routes. Honored only if `collectBgpAdvertisements` is true.\nDefaults to `BOTH`.", "examples": [ "BOTH" ], "enum": [ "BOTH", "EBGP", "IBGP" ] }, "bgpSubnetsToCollect": { "type": "array", "items": { "type": "string" }, "description": "Restricts collection of BGP advertisements to specific subnets if the device supports it. Honored only if\n`collectBgpAdvertisements` is `true`.", "examples": [ [ "123.223.47.0/24" ] ] }, "prompt": { "type": "string", "description": "A case-insensitive glob pattern used to identify an interactive prompt. When this pattern matches the end of\nthe prompt, ignoring any trailing whitespace, the Collector will enter the configured `promptResponse`.\nRelevant for devices collected via SSH or Telnet.", "examples": [ "y/n" ] }, "promptResponse": { "type": "string", "description": "What the Collector should enter in response to a device prompt matching `prompt` in order to proceed.\nRelevant for devices collected via SSH or Telnet. Required if `prompt` is set.", "examples": [ "y" ] }, "collect": { "type": "boolean", "description": "Whether to collect from the device. Defaults to true.", "examples": [ false ] }, "note": { "type": "string", "description": "An optional description or note about the device." }, "enableSnmpCollection": { "type": "boolean", "description": "Whether to collect performance data (counters) via SNMP. Defaults to false.", "examples": [ false ] }, "highCpuUsage": { "type": "number", "format": "float", "minimum": 0.75, "maximum": 1, "description": "Threshold at or above which CPU usage is considered high. Defaults to 0.8 (80.0%).", "examples": [ 0.85 ] }, "highMemoryUsage": { "type": "number", "format": "float", "minimum": 0.75, "maximum": 1, "description": "Threshold at or above which memory usage is considered high. Defaults to 0.9 (90.0%).", "examples": [ 0.92 ] }, "highInputUtilization": { "type": "number", "format": "float", "minimum": 0.75, "maximum": 1, "description": "Threshold at or above which input interface utilization is considered high. Defaults to 0.9\n(90.0%).", "examples": [ 0.8 ] }, "highOutputUtilization": { "type": "number", "format": "float", "minimum": 0.75, "maximum": 1, "description": "Threshold at or above which output interface utilization is considered high. Defaults to 0.9\n(90.0%).", "examples": [ 0.88 ] }, "mediumCpuUsage": { "type": "number", "format": "float", "minimum": 0.5, "maximum": 1, "description": "Threshold at or above which CPU usage is considered medium high. Has no default value.", "examples": [ 0.7 ] }, "mediumMemoryUsage": { "type": "number", "format": "float", "minimum": 0.5, "maximum": 1, "description": "Threshold at or above which memory usage is considered medium high. Has no default value.", "examples": [ 0.71 ] }, "mediumInputUtilization": { "type": "number", "format": "float", "minimum": 0.5, "maximum": 1, "description": "Threshold at or above which input interface utilization is considered medium high. Has no\ndefault value.", "examples": [ 0.72 ] }, "mediumOutputUtilization": { "type": "number", "format": "float", "minimum": 0.5, "maximum": 1, "description": "Threshold at or above which output interface utilization is considered medium high. Has no\ndefault value.", "examples": [ 0.73 ] }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags assigned to the device. Present only if specifically requested." }, "locationId": { "type": "string", "description": "The `id` of the device’s assigned Location (see\n[Network Locations](https://docs.fwd.app/latest/api/network-locations/)). Present only if specifically\nrequested. Defaults to \"default\" (the Unassigned location).", "examples": [ "atl" ] }, "testResult": { "$ref": "#/components/schemas/SourceConnectivityResult", "description": "The device’s most recent connectivity test result. Present only if specifically requested. Absent if the\ndevice’s connectivity hasn’t been tested since the last substantial edit to the device." } } }, { "$ref": "#/components/schemas/Attribution" } ] }, "ControllerManagedDevicesBulkPatch": { "allOf": [ { "$ref": "#/components/schemas/ControllerAndManagedDeviceSelection" }, { "type": "object", "required": [ "update" ], "properties": { "update": { "$ref": "#/components/schemas/ControllerManagedDevicesUpdate", "description": "The changes to apply to every selected device." } } } ] }, "ControllerManagedSetup": { "allOf": [ { "type": "object", "required": [ "name", "controllers", "type" ], "properties": { "name": { "type": "string", "description": "A name that’s unique (ignoring case) among all of the network’s collection source names, including the names\nof all controllers and managed devices. May consist of letters, digits, dots, hyphens, and underscores. Stored\nin lowercase.", "examples": [ "my-aci-fabric" ] }, "controllers": { "type": "array", "items": { "$ref": "#/components/schemas/ControllerDevice" }, "description": "The setup’s controllers (a primary and any peers). Must not be empty." }, "managedDevices": { "type": "array", "items": { "$ref": "#/components/schemas/ControllerManagedDevice" }, "description": "The devices the controllers manage. Absent for setup types that don’t collect from them directly." }, "collectorId": { "type": "string", "description": "The `id` of the Collector that collects from this setup’s devices. Absent if it’s the network’s default." }, "type": { "$ref": "#/components/schemas/ControllerManagedSetupType", "description": "The kind of setup, determined by the `type` of its controllers.", "examples": [ "CISCO_ACI" ] } } }, { "$ref": "#/components/schemas/Attribution" } ] }, "ControllerManagedSetupConnectivityTestRequest": { "type": "object", "required": [ "id", "host" ], "properties": { "id": { "type": "string", "description": "A caller-chosen identifier for this test. It stands in for the device name, since the controller hasn’t been saved\nyet.", "examples": [ "test-apic1" ] }, "host": { "type": "string", "description": "IP address or hostname of the controller.", "examples": [ "10.121.7.13" ] }, "type": { "$ref": "#/components/schemas/ControllerDeviceType", "description": "The controller’s type. Auto-detected if unspecified.", "examples": [ "cisco_apic_api" ] }, "cliCredentialId": { "type": "string", "description": "The `id` of a CliCredential of type `LOGIN`. Auto-associated if unspecified.", "examples": [ "L-3" ] }, "httpCredentialId": { "type": "string", "description": "The `id` of an HttpCredential of type `LOGIN` or `API_KEY`. Auto-associated if unspecified.", "examples": [ "H-2" ] }, "jumpServerId": { "type": "string", "description": "The `id` of a jump server to reach the controller through, if one is needed.", "examples": [ "J-0" ] }, "collectorId": { "type": "string", "description": "The `id` of the Collector to run the test on. Omit to use the network’s default Collector." } } }, "ControllerManagedSetupPatch": { "type": "object", "properties": { "name": { "type": "string", "description": "A name that’s unique (ignoring case) among all of the network’s collection source names, including the names of\nall controllers and managed devices. May consist of letters, digits, dots, hyphens, and underscores. Stored in\nlowercase. Omit to leave alone.", "examples": [ "my-aci-fabric" ] }, "controllers": { "type": "array", "items": { "$ref": "#/components/schemas/ControllerDeviceWithMeta" }, "description": "Replaces the setup’s controllers. Must not be empty. Attribution is preserved for controllers whose properties are\nunchanged. Omit to leave alone." }, "managedDevices": { "type": "array", "items": { "$ref": "#/components/schemas/ControllerManagedDeviceWithMeta" }, "description": "Replaces the setup’s managed devices. Attribution is preserved for devices whose properties are unchanged. Use\n`null` to clear. Omit to leave alone." }, "collectorId": { "type": "string", "description": "The `id` of the Collector to collect from this setup’s devices. Use `null` to use the network’s default Collector.\nOmit to leave alone." } } }, "ControllerManagedSetupType": { "type": "string", "enum": [ "CISCO_ACI", "SD_WAN" ] }, "ControllerManagedSetups": { "type": "object", "required": [ "setups" ], "properties": { "setups": { "type": "array", "items": { "$ref": "#/components/schemas/ControllerManagedSetup" }, "description": "The network’s controller-managed setups." } } }, "ManagedDevicePatch": { "type": "object", "properties": { "name": { "type": "string", "description": "A name that’s unique (ignoring case) among all of the network’s collection source names. May consist of\nletters, digits, dots, hyphens, and underscores. Use `null` to clear. Omit to leave the property alone.", "examples": [ "leaf-101" ] }, "type": { "$ref": "#/components/schemas/ControllerManagedDeviceType", "description": "Auto-detected during connectivity testing if unspecified. Use `null` to clear. Omit to leave the property\nalone.", "examples": [ "cisco_nxos_aci_ssh" ] }, "host": { "type": "string", "description": "IP address or hostname used to connect to the device. Use `null` to clear. Omit to leave the\nproperty alone.", "examples": [ "10.121.7.13" ] }, "port": { "type": "integer", "format": "int32", "description": "Port used to connect to the device. The default value depends on the collection protocol: 22 for SSH, 443\nfor HTTPS, etc. Use `null` to clear. Omit to leave the property alone.", "examples": [ 22 ] }, "cliCredentialId": { "type": "string", "description": "The `id` of a CliCredential of type `LOGIN`. Relevant for devices collected via SSH or Telnet. Credential\nauto-association will be attempted using credentials configured to allow it if this property is unspecified\nand collecting from this device requires this kind of credential. Use `null` to clear. Omit to leave the\nproperty alone.", "examples": [ "L-3" ] }, "cliCredential2Id": { "type": "string", "description": "The `id` of a CliCredential of type `PRIVILEGED_MODE` (for Cisco-like or Checkpoint devices) or `SHELL` (for\nAvi controllers). On Checkpoint, this credential is used for TACACS privilege escalation. Credential\nauto-association will be attempted using credentials configured to allow it if this property is unspecified\nand collecting from this device requires this kind of credential. Use `null` to clear. Omit to leave the\nproperty alone.", "examples": [ "PM-2" ] }, "cliCredential3Id": { "type": "string", "description": "The `id` of a CliCredential of type `EXPERT_MODE` (for Checkpoint devices). Can be set with or without a\n`PRIVILEGED_MODE` credential for `cliCredential2Id`. Credential auto-association will be attempted using\ncredentials configured to allow it if this property is unspecified and collecting from this device requires\nthis kind of credential. Use `null` to clear. Omit to leave the property alone.", "examples": [ "EM-6" ] }, "httpCredentialId": { "type": "string", "description": "The `id` of an HttpCredential of type `LOGIN` or `API_KEY`. Relevant for devices collected via HTTPS or\nHTTP. Credential auto-association will be attempted using credentials configured to allow it if this\nproperty is unspecified and collecting from this device requires this kind of credential. Use `null` to\nclear. Omit to leave the property alone.", "examples": [ "H-5" ] }, "snmpCredentialId": { "type": "string", "description": "The `id` of an SnmpCredential. Used to collect performance data (counters) if `enableSnmpCollection` is\ntrue. Credential auto-association will be attempted using credentials configured to allow it if this\nproperty is unspecified and collecting from this device requires this kind of credential. Use `null` to\nclear. Omit to leave the property alone.", "examples": [ "S-4" ] }, "jumpServerId": { "type": "string", "description": "The `id` of the JumpServer that should be used to collect from this device. Use `null` to clear. Omit to\nleave the property alone.", "examples": [ "J-0" ] }, "disableIpv6Collection": { "type": "boolean", "description": "Disables collection of any IPv6 forwarding state on the device. Defaults to false. Use `null` to clear. Omit\nto leave the property alone.", "examples": [ false ] }, "fullCollectionLog": { "type": "boolean", "description": "Enables more detailed logging during collection. Defaults to false. Use `null` to clear. Omit to leave the\nproperty alone.", "examples": [ false ] }, "paginationMode": { "$ref": "#/components/schemas/PaginationMode", "description": "The pagination mode to use during collection. Relevant for devices collected via SSH or Telnet. Defaults to\n`DISABLE_PAGINATION`. Per-command pagination (such as appending `| more`) may be used if set to\n`ENABLE_PAGINATION` for a device that doesn’t have a per-session pagination mode setting. Use `null` to\nclear. Omit to leave the property alone.", "examples": [ "KEEP_UNCHANGED" ] }, "terminalWidth": { "type": "integer", "format": "int32", "description": "Width of pseudo-terminal in characters. A high value can prevent long lines from wrapping. Defaults to 500.\nRelevant for devices collected via SSH or Telnet. Use `null` to clear. Omit to leave the property alone.", "examples": [ 500 ] }, "largeRtt": { "type": "boolean", "description": "Whether the device has a large round-trip time (requires a longer response timeout). Use `null` to clear.\nOmit to leave the property alone.", "examples": [ false ] }, "minBytesReadPerSec": { "type": "integer", "format": "int64", "description": "The minimum read rate in bytes/sec required to prevent collection from failing with a\n`SLOW_READ_RATE_DETECTED` error. Defaults to 500. Use `null` to clear. Omit to leave the property alone.", "examples": [ 1000 ] }, "maxConnectionsPerMin": { "type": "integer", "format": "int32", "description": "The maximum number of connections to this device that should be attempted per minute. Setting this property\ncan prevent spurious connectivity test failures if the device’s SSH server is configured with a connection\nrate limit. Use `null` to clear. Omit to leave the property alone.", "examples": [ 10 ] }, "useFileTransferForLargeOutput": { "type": "boolean", "description": "Whether to use file transfer instead of printing large command output directly to the shell. This is\ncurrently only supported for Juniper devices when executing routing table commands. The primary purpose is\nto avoid printing large outputs directly to the shell, which on Juniper devices can interfere with packet\nforwarding performance. Instead, the command output is written to a temporary file on the device and then\ntransferred over a separate connection. After the transfer is complete, the temporary file is deleted to\nprevent unnecessary disk usage on the device. Use `null` to clear. Omit to leave the property alone.", "examples": [ false ] }, "bmpStationHost": { "type": "string", "description": "IP address or hostname of the BMP station from which BMP collection should be performed for this device. If\nset, a jump server won’t be used for BMP collection. Use `null` to clear. Omit to leave the property alone.", "examples": [ "10.121.7.33" ] }, "bgpAndBmpFailureHandling": { "type": "string", "description": "How to handle BGP or BMP collection failure. Defaults to `FAIL_DEVICE`. Use `null` to clear. Omit to leave\nthe property alone.", "examples": [ "SWITCH_TO_CLI" ], "enum": [ "FAIL_DEVICE", "SWITCH_TO_CLI", "ALWAYS_USE_CLI", "ALWAYS_USE_BMP", "CONTINUE_WITHOUT_BGP_DATA" ] }, "collectBgpAdvertisements": { "type": "boolean", "description": "Whether BGP advertisements should be collected. Defaults to `false` unless advertisement collection is\nrequired to model a [synthetic device](https://docs.fwd.app/latest/api/synthetic-devices/) connected to this\ndevice. Use `null` to clear. Omit to leave the property alone.", "examples": [ false ] }, "bgpTableType": { "type": "string", "description": "The BGP route types to collect. Honored only if `collectBgpAdvertisements` is true. Defaults to `BOTH`.\nUse `null` to clear. Omit to leave the property alone.", "examples": [ "BOTH" ], "enum": [ "BOTH", "ADJ_RIB_IN", "ADJ_RIB_OUT" ] }, "bgpPeerType": { "type": "string", "description": "The BGP peer types from which to collect routes. Honored only if `collectBgpAdvertisements` is true.\nDefaults to `BOTH`. Use `null` to clear. Omit to leave the property alone.", "examples": [ "BOTH" ], "enum": [ "BOTH", "EBGP", "IBGP" ] }, "bgpSubnetsToCollect": { "type": "array", "items": { "type": "string" }, "description": "Restricts collection of BGP advertisements to specific subnets if the device supports it. Honored only if\n`collectBgpAdvertisements` is `true`. Use `null` to clear. Omit to leave the property alone.", "examples": [ [ "123.223.47.0/24" ] ] }, "prompt": { "type": "string", "description": "A case-insensitive glob pattern used to identify an interactive prompt. When this pattern matches the end of\nthe prompt, ignoring any trailing whitespace, the Collector will enter the configured `promptResponse`.\nRelevant for devices collected via SSH or Telnet. Use `null` to clear. Omit to leave the property alone.", "examples": [ "y/n" ] }, "promptResponse": { "type": "string", "description": "What the Collector should enter in response to a device prompt matching `prompt` in order to proceed.\nRelevant for devices collected via SSH or Telnet. Required if `prompt` is set. Use `null` to clear. Omit to\nleave the property alone.", "examples": [ "y" ] }, "collect": { "type": "boolean", "description": "Whether to collect from the device. Defaults to true. Use `null` to clear. Omit to leave the\nproperty alone.", "examples": [ false ] }, "note": { "type": "string", "description": "An optional description or note about the device. Use `null` to clear. Omit to leave the\nproperty alone." }, "enableSnmpCollection": { "type": "boolean", "description": "Whether to collect performance data (counters) via SNMP. Defaults to false. Use `null` to clear. Omit to\nleave the property alone.", "examples": [ false ] }, "highCpuUsage": { "type": "number", "format": "float", "description": "Threshold at or above which CPU usage is considered high. Defaults to 0.8 (80.0%). Use `null` to clear. Omit\nto leave the property alone.", "examples": [ 0.85 ] }, "highMemoryUsage": { "type": "number", "format": "float", "description": "Threshold at or above which memory usage is considered high. Defaults to 0.9 (90.0%). Use `null` to clear.\nOmit to leave the property alone.", "examples": [ 0.92 ] }, "highInputUtilization": { "type": "number", "format": "float", "description": "Threshold at or above which input interface utilization is considered high. Defaults to 0.9 (90.0%). Use\n`null` to clear. Omit to leave the property alone.", "examples": [ 0.8 ] }, "highOutputUtilization": { "type": "number", "format": "float", "description": "Threshold at or above which output interface utilization is considered high. Defaults to 0.9 (90.0%). Use\n`null` to clear. Omit to leave the property alone.", "examples": [ 0.88 ] }, "mediumCpuUsage": { "type": "number", "format": "float", "description": "Threshold at or above which CPU usage is considered medium high. Has no default value. Use `null` to clear.\nOmit to leave the property alone.", "examples": [ 0.7 ] }, "mediumMemoryUsage": { "type": "number", "format": "float", "description": "Threshold at or above which memory usage is considered medium high. Has no default value. Use `null` to\nclear. Omit to leave the property alone.", "examples": [ 0.71 ] }, "mediumInputUtilization": { "type": "number", "format": "float", "description": "Threshold at or above which input interface utilization is considered medium high. Has no default value. Use\n`null` to clear. Omit to leave the property alone.", "examples": [ 0.72 ] }, "mediumOutputUtilization": { "type": "number", "format": "float", "description": "Threshold at or above which output interface utilization is considered medium high. Has no default value.\nUse `null` to clear. Omit to leave the property alone.", "examples": [ 0.73 ] } } }, "NewControllerManagedSetup": { "type": "object", "required": [ "name", "controllers" ], "properties": { "name": { "type": "string", "description": "A name that’s unique (ignoring case) among all of the network’s collection source names, including the names of\nall controllers and managed devices. May consist of letters, digits, dots, hyphens, and underscores. Stored in\nlowercase.", "examples": [ "my-aci-fabric" ] }, "controllers": { "type": "array", "items": { "$ref": "#/components/schemas/ControllerDeviceWithMeta" }, "description": "The setup’s controllers (a primary and any peers). Must not be empty." }, "managedDevices": { "type": "array", "items": { "$ref": "#/components/schemas/ControllerManagedDeviceWithMeta" }, "description": "The devices the controllers manage. Omit for setup types that don’t collect from them directly." }, "collectorId": { "type": "string", "description": "The `id` of the Collector to collect from this setup’s devices. Omit to use the network’s default Collector." } } }, "SourceConnectivityResult": { "type": "object", "required": [ "startTime", "endTime", "savedAt" ], "properties": { "startTime": { "type": "string", "description": "When this connectivity test began, according to the Collector’s system clock.", "examples": [ "2025-05-28T12:33:00.000Z" ] }, "endTime": { "type": "string", "description": "When this connectivity test ended, according to the Collector’s system clock.", "examples": [ "2025-05-28T12:33:33.333Z" ] }, "savedAt": { "type": "string", "description": "When this connectivity test result was saved to the database, according to the server’s system\nclock.", "examples": [ "2025-05-28T12:34:56.789Z" ] }, "error": { "$ref": "#/components/schemas/ConnectivityTestError", "description": "The error encountered during the test. Present if the test failed. Absent if the test passed.", "examples": [ "PING_FAILED" ] }, "errorPhase": { "type": "string", "description": "The test phase during which `error` was encountered. Present if `error` is present.", "examples": [ "CONNECTION" ], "enum": [ "CONNECTION", "AUTHENTICATION", "TYPE_DISCOVERY", "SETUP", "AUTHORIZATION", "QUERY" ] }, "discoveredType": { "$ref": "#/components/schemas/ClassicDeviceType", "description": "The device type auto-discovered during the connectivity test.", "examples": [ "arista_eos_ssh" ] }, "discoveredCliCredentialId": { "type": "string", "description": "The `id` of the working CliCredential of type `LOGIN` auto-discovered during the connectivity test. Can only\nbe present for device types collected via SSH.", "examples": [ "L-3" ] }, "discoveredCliCredential2Id": { "type": "string", "description": "The `id` of the working CliCredential of type `PRIVILEGED_MODE` (for Cisco-like and Checkpoint devices) or\n`SHELL` (for Avi controllers) auto-discovered during the connectivity test. Can only be present for device\ntypes collected via SSH or Telnet.", "examples": [ "PM-2" ] }, "discoveredCliCredential3Id": { "type": "string", "description": "The `id` of the working CliCredential of type `EXPERT_MODE` (for Checkpoint devices) auto-discovered during\nthe connectivity test. Can only be present for device types collected via SSH.", "examples": [ "EM-3" ] }, "discoveredHttpCredentialId": { "type": "string", "description": "The `id` of the working HttpCredential of type `LOGIN` or `API_KEY` auto-discovered during the connectivity\ntest. Can only be present for device types collected via HTTPS.", "examples": [ "H-5" ] }, "discoveredSnmpCredentialId": { "type": "string", "description": "The `id` of the working SnmpCredential auto-discovered during the connectivity test.", "examples": [ "S-1" ] }, "hostIps": { "type": "array", "items": { "type": "string" }, "description": "The IP addresses to which `host` resolves if it’s a hostname. Contains just `host` itself if it’s an IP\naddress.", "examples": [ [ "10.121.7.13" ] ] }, "unauthorizedCommands": { "type": "array", "items": { "type": "string" }, "description": "Commands that failed with an authorization (permission) error during the connectivity test.", "examples": [ [ "show config", "show interfaces status" ] ] } } }, "ControllerDeviceType": { "type": "string", "enum": [ "128t_conductor", "cisco_apic_api", "silver_peak_orchestrator_api", "prisma_sdwan_unified_api", "cisco_sdwan_vsmart_ssh", "versa_director_api" ] }, "ConnectivityTestError": { "type": "string", "enum": [ "PING_FAILED", "PORT_REACHABILITY_FAILED", "UNSUPPORTED_SSH_PROTOCOL", "CONNECTION_FAILED", "PROMPT_DISCOVERY_FAILED", "AUTHENTICATION_FAILED", "TWO_FACTOR_AUTHENTICATION_FAILED", "KEY_EXCHANGE_FAILED", "UNEXPECTED_KEY_EXCHANGE_MESSAGE", "CERTIFICATE_CHECK_FAILED", "PASSWORD_EXPIRED", "JUMP_SERVER_PING_FAILED", "JUMP_SERVER_PORT_REACHABILITY_FAILED", "JUMP_SERVER_CONNECTION_FAILED", "JUMP_SERVER_AUTHENTICATION_FAILED", "JUMP_SERVER_KEY_EXCHANGE_FAILED", "JUMP_SERVER_PASSWORD_EXPIRED", "PROXY_SERVER_PING_FAILED", "PROXY_SERVER_PORT_REACHABILITY_FAILED", "PROXY_SERVER_CONNECTION_FAILED", "PROXY_SERVER_AUTHENTICATION_FAILED", "SERVER_FINGERPRINT_CHECK_FAILED", "SESSION_LIMIT_REACHED", "DEVICE_TYPE_MISMATCH", "DEVICE_TYPE_UNDETECTED", "SESSION_CLOSED", "PRIV_PASSWORD_ERROR", "EXPERT_PASSWORD_ERROR", "DEVICE_IS_CHILD_CONTEXT", "GUEST_MISSING_HOST_RESULTS", "HOST_MISSING_GUEST_RESULTS", "HOST_NOT_REPORTING_ANY_GUEST", "GUEST_NOT_REPORTING_ANY_NAME", "UNSUPPORTED_VERSION", "AVI_SHELL_AUTH_FAILED", "KEY_BASED_ACCESS_TO_AVI_CONTAINER_FAILED", "AVI_SERVICE_ENGINE_DISCOVERED", "AVI_VIA_LINUX_OVER_JUMP_SERVER_UNSUPPORTED", "AVI_CONTROLLER_WITHOUT_HEALTHY_SERVICE_ENGINES", "T128_CONDUCTOR_WITHOUT_HEALTHY_ROUTERS", "API_CALL_FAILED", "CHECKPOINT_MANAGER_FOUND", "AUTHORIZATION_FAILED", "VSH_AUTHORIZATION_FAILED", "INCOMPLETE_AUTHORIZATION_CHECK", "CUSTOM_COMMAND_AUTHORIZATION_FAILED", "TACACS_SESSION_EXPIRED", "AZURE_SUBSCRIPTION_NOT_FOUND", "TIMED_OUT", "DEVICE_IN_BAD_STATE", "PROJECT_VIEW_PERMISSION_MISSING", "UNSUPPORTED_DEVICE_TYPE", "LIMITED_DEVICE_SUPPORT", "SLOW_READ_RATE", "TRANSIENT_SLOW_READ_RATE_DETECTED", "NO_SPACE_LEFT_ON_COLLECTOR", "NO_SPACE_LEFT_ON_COLLECTED_DEVICE", "VERSA_DIRECTOR_DISCOVERED", "DEVICE_PROTOCOL_MISMATCH", "API_SERVER_FAILED_TO_RESPOND", "UNRESOLVABLE_HOSTNAME", "UNSUPPORTED_SSL_CONNECTION", "PASSWD_DISCOVERY_ON_INSECURE_PROTOCOL", "INCOMPLETE_SETUP", "CONFIG_COLLECTION_UNAUTHORIZED", "FILE_TRANSFER_FAILED", "VELOS_CONTROLLER_DISCOVERED", "CANCELED", "OTHER" ] }, "ClassicDeviceType": { "type": "string", "enum": [ "aruba_controller_ssh", "aruba_switch_ssh", "aruba_aos_cx_ssh", "128t_conductor_full", "128t_router", "128t_conductor", "a10_acos_ssh", "arista_eos_ssh", "avi_controller_ssh", "avi_controller_ssh_cli_user", "avi_controller_ssh_via_host", "avi_controller_https_api", "avi_controller_http_api", "bluecoat_ssh", "cisco_ios_ssh", "cisco_ios_telnet", "cisco_ios_xe_ssh", "cisco_ios_xe_telnet", "cisco_ios_xr_ssh", "cisco_nxos_ssh", "cisco_nxos_telnet", "cisco_asa_ssh", "cisco_asa_telnet", "cisco_asa_admin_ssh", "cisco_asa_child_ssh", "cisco_ftd_ssh", "cisco_fxos_ssh", "cisco_firewalls_on_firepower_ssh", "cisco_fmc_api", "cisco_nxos_aci_ssh", "cisco_ndo_api", "cisco_apic_api", "cisco_apic_only_ssh", "cisco_sg_ssh", "juniper_junos_ssh", "juniper_srx_ssh", "juniper_netscreen_ssh", "pica8_ovs_ofctl_ssh", "linux_ovs_ofctl_ssh", "f5_ssh", "f5_os_hypervisor_ssh", "checkpoint_ssh", "checkpoint_ssh_nonexpert", "checkpoint_ssh_with_manager", "checkpoint_spark_ssh_with_manager", "checkpoint_mgmt_api", "fortinet_ssh", "hp_comware_ssh", "hp_comware_telnet", "hp_provision_ssh", "huawei_switch_ssh", "panos_ssh", "viasat_encryptor_snmp3", "vine_api", "netscaler_ssh", "cumulus_ssh", "riverbed_steelhead_ssh", "riverbed_interceptor_ssh", "cisco_ucs_ssh", "avaya_sr_ssh", "avaya_sr_telnet", "avaya_ers_ssh", "avaya_ers_telnet", "silver_peak_edgeconnect_ssh", "silver_peak_orchestrator_api", "prisma_sdwan_ssh", "prisma_sdwan_api", "prisma_sdwan_unified_api", "pensando_api", "forcepoint_https_api", "forcepoint_http_api", "forcepoint_ssh", "cisco_sdwan_ssh", "cisco_sdwan_vsmart_ssh", "bluecat_http", "bluecat_https", "bluecat_v2_http", "bluecat_v2_https", "nokia_ssh", "brocade_switch_ssh", "versa_flexvnf_ssh", "versa_switch_ssh", "versa_director_api", "cisco_encs_nfv_ssh", "extreme_switch_ssh", "dell_os6_switch_ssh", "dell_os6_switch_telnet", "dell_os9_switch_ssh", "dell_os9_switch_telnet", "dell_os10_switch_ssh", "dell_os10_switch_telnet", "sonic_dell_enterprise_ssh", "gem1_api", "taclane_encryptor_snmp", "sonic_edge_core_ssh" ] }, "PaginationMode": { "type": "string", "enum": [ "KEEP_UNCHANGED", "DISABLE_PAGINATION", "ENABLE_PAGINATION" ] }, "Attribution": { "type": "object", "properties": { "createdById": { "type": "string", "description": "The ID of the user who created this entity, if known. *Note*: The referenced user account might no longer\nexist since an administrator can delete accounts.", "examples": [ "456" ] }, "createdAt": { "type": "string", "description": "When this entity was created, if known.", "examples": [ "2021-12-29T16:30:45.111Z" ] }, "createdBy": { "type": "string", "description": "The username of the user who created this entity, if known. Absent if the user account has been\ndeleted.", "examples": [ "me@example.com" ] }, "updatedById": { "type": "string", "description": "The ID of the user who most recently updated this entity, if known. *Note*: The referenced user account\nmight no longer exist since an administrator can delete accounts.", "examples": [ "789" ] }, "updatedAt": { "type": "string", "description": "When this entity was most recently updated, if known.", "examples": [ "2024-10-27T21:44:51.345Z" ] }, "updatedBy": { "type": "string", "description": "The username of the user who most recently updated this entity, if known. Absent if the user account has\nbeen deleted.", "examples": [ "you@example.com" ] } } }, "ControllerManagedDeviceType": { "type": "string", "enum": [ "128t_router", "cisco_ios_xe_ssh", "cisco_ios_xe_telnet", "cisco_nxos_aci_ssh", "cisco_ndo_api", "silver_peak_edgeconnect_ssh", "prisma_sdwan_ssh", "cisco_sdwan_ssh", "versa_flexvnf_ssh", "versa_switch_ssh" ] }, "ControllerDeviceWithMeta": { "type": "object", "required": [ "name", "host" ], "properties": { "collect": { "type": "boolean", "description": "Whether to collect from the device. Defaults to true.", "examples": [ false ] }, "note": { "type": "string", "description": "An optional description or note about the device." }, "enableSnmpCollection": { "type": "boolean", "description": "Whether to collect performance data (counters) via SNMP. Defaults to false.", "examples": [ false ] }, "highCpuUsage": { "type": "number", "format": "float", "minimum": 0.75, "maximum": 1, "description": "Threshold at or above which CPU usage is considered high. Defaults to 0.8 (80.0%).", "examples": [ 0.85 ] }, "highMemoryUsage": { "type": "number", "format": "float", "minimum": 0.75, "maximum": 1, "description": "Threshold at or above which memory usage is considered high. Defaults to 0.9 (90.0%).", "examples": [ 0.92 ] }, "highInputUtilization": { "type": "number", "format": "float", "minimum": 0.75, "maximum": 1, "description": "Threshold at or above which input interface utilization is considered high. Defaults to 0.9\n(90.0%).", "examples": [ 0.8 ] }, "highOutputUtilization": { "type": "number", "format": "float", "minimum": 0.75, "maximum": 1, "description": "Threshold at or above which output interface utilization is considered high. Defaults to 0.9\n(90.0%).", "examples": [ 0.88 ] }, "mediumCpuUsage": { "type": "number", "format": "float", "minimum": 0.5, "maximum": 1, "description": "Threshold at or above which CPU usage is considered medium high. Has no default value.", "examples": [ 0.7 ] }, "mediumMemoryUsage": { "type": "number", "format": "float", "minimum": 0.5, "maximum": 1, "description": "Threshold at or above which memory usage is considered medium high. Has no default value.", "examples": [ 0.71 ] }, "mediumInputUtilization": { "type": "number", "format": "float", "minimum": 0.5, "maximum": 1, "description": "Threshold at or above which input interface utilization is considered medium high. Has no\ndefault value.", "examples": [ 0.72 ] }, "mediumOutputUtilization": { "type": "number", "format": "float", "minimum": 0.5, "maximum": 1, "description": "Threshold at or above which output interface utilization is considered medium high. Has no\ndefault value.", "examples": [ 0.73 ] }, "ndoName": { "type": "string", "description": "The `name` of the Cisco Nexus Dashboard Orchestrator (NDO) host linked to this APIC, if any." }, "name": { "type": "string", "description": "A name that’s unique (ignoring case) among all of the network’s collection source names. May consist of\nletters, digits, dots, hyphens, and underscores.", "examples": [ "apic1" ] }, "type": { "$ref": "#/components/schemas/ControllerDeviceType", "description": "Auto-detected during connectivity testing if unspecified.", "examples": [ "cisco_apic_api" ] }, "host": { "type": "string", "description": "IP address or hostname used to connect to the device.", "examples": [ "10.121.7.13" ] }, "port": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 65535, "description": "Port used to connect to the device. The default value depends on the collection protocol: 22 for SSH, 443\nfor HTTPS, etc.", "examples": [ 22 ] }, "cliCredentialId": { "type": "string", "description": "The `id` of a CliCredential of type `LOGIN`. Relevant for devices collected via SSH or Telnet. Credential\nauto-association will be attempted using credentials configured to allow it if this property is unspecified\nand collecting from this device requires this kind of credential.", "examples": [ "L-3" ] }, "cliCredential2Id": { "type": "string", "description": "The `id` of a CliCredential of type `PRIVILEGED_MODE` (for Cisco-like or Checkpoint devices) or `SHELL` (for\nAvi controllers). On Checkpoint, this credential is used for TACACS privilege escalation. Credential\nauto-association will be attempted using credentials configured to allow it if this property is unspecified\nand collecting from this device requires this kind of credential.", "examples": [ "PM-2" ] }, "cliCredential3Id": { "type": "string", "description": "The `id` of a CliCredential of type `EXPERT_MODE` (for Checkpoint devices). Can be set with or without a\n`PRIVILEGED_MODE` credential for `cliCredential2Id`. Credential auto-association will be attempted using\ncredentials configured to allow it if this property is unspecified and collecting from this device requires\nthis kind of credential.", "examples": [ "EM-6" ] }, "httpCredentialId": { "type": "string", "description": "The `id` of an HttpCredential of type `LOGIN` or `API_KEY`. Relevant for devices collected via HTTPS or\nHTTP. Credential auto-association will be attempted using credentials configured to allow it if this\nproperty is unspecified and collecting from this device requires this kind of credential.", "examples": [ "H-5" ] }, "snmpCredentialId": { "type": "string", "description": "The `id` of an SnmpCredential. Used to collect performance data (counters) if `enableSnmpCollection` is\ntrue. Credential auto-association will be attempted using credentials configured to allow it if this\nproperty is unspecified and collecting from this device requires this kind of credential.", "examples": [ "S-4" ] }, "jumpServerId": { "type": "string", "description": "The `id` of the JumpServer that should be used to collect from this device.", "examples": [ "J-0" ] }, "disableIpv6Collection": { "type": "boolean", "description": "Disables collection of any IPv6 forwarding state on the device. Defaults to false.", "examples": [ false ] }, "fullCollectionLog": { "type": "boolean", "description": "Enables more detailed logging during collection. Defaults to false.", "examples": [ false ] }, "paginationMode": { "$ref": "#/components/schemas/PaginationMode", "description": "The pagination mode to use during collection. Relevant for devices collected via SSH or Telnet. Defaults to\n`DISABLE_PAGINATION`. Per-command pagination (such as appending `| more`) may be used if set to\n`ENABLE_PAGINATION` for a device that doesn’t have a per-session pagination mode setting.", "examples": [ "KEEP_UNCHANGED" ] }, "terminalWidth": { "type": "integer", "format": "int32", "minimum": 80, "maximum": 500, "description": "Width of pseudo-terminal in characters. A high value can prevent long lines from wrapping. Defaults to 500.\nRelevant for devices collected via SSH or Telnet.", "examples": [ 500 ] }, "largeRtt": { "type": "boolean", "description": "Whether the device has a large round-trip time (requires a longer response timeout).", "examples": [ false ] }, "minBytesReadPerSec": { "type": "integer", "format": "int64", "description": "The minimum read rate in bytes/sec required to prevent collection from failing with a\n`SLOW_READ_RATE_DETECTED` error. Defaults to 500.", "examples": [ 1000 ] }, "maxConnectionsPerMin": { "type": "integer", "format": "int32", "description": "The maximum number of connections to this device that should be attempted per minute. Setting this property\ncan prevent spurious connectivity test failures if the device’s SSH server is configured with a connection\nrate limit.", "examples": [ 10 ] }, "useFileTransferForLargeOutput": { "type": "boolean", "description": "Whether to use file transfer instead of printing large command output directly to the shell. This is\ncurrently only supported for Juniper devices when executing routing table commands. The primary purpose is\nto avoid printing large outputs directly to the shell, which on Juniper devices can interfere with packet\nforwarding performance. Instead, the command output is written to a temporary file on the device and then\ntransferred over a separate connection. After the transfer is complete, the temporary file is deleted to\nprevent unnecessary disk usage on the device.", "examples": [ false ] }, "bmpStationHost": { "type": "string", "description": "IP address or hostname of the BMP station from which BMP collection should be performed for this device. If\nset, a jump server won’t be used for BMP collection.", "examples": [ "10.121.7.33" ] }, "bgpAndBmpFailureHandling": { "type": "string", "description": "How to handle BGP or BMP collection failure. Defaults to `FAIL_DEVICE`.", "examples": [ "SWITCH_TO_CLI" ], "enum": [ "FAIL_DEVICE", "SWITCH_TO_CLI", "ALWAYS_USE_CLI", "ALWAYS_USE_BMP", "CONTINUE_WITHOUT_BGP_DATA" ] }, "collectBgpAdvertisements": { "type": "boolean", "description": "Whether BGP advertisements should be collected. Defaults to `false` unless advertisement collection is\nrequired to model a [synthetic device](https://docs.fwd.app/latest/api/synthetic-devices/) connected to this\ndevice.", "examples": [ false ] }, "bgpTableType": { "type": "string", "description": "The BGP route types to collect. Honored only if `collectBgpAdvertisements` is true. Defaults\nto `BOTH`.", "examples": [ "BOTH" ], "enum": [ "BOTH", "ADJ_RIB_IN", "ADJ_RIB_OUT" ] }, "bgpPeerType": { "type": "string", "description": "The BGP peer types from which to collect routes. Honored only if `collectBgpAdvertisements` is true.\nDefaults to `BOTH`.", "examples": [ "BOTH" ], "enum": [ "BOTH", "EBGP", "IBGP" ] }, "bgpSubnetsToCollect": { "type": "array", "items": { "type": "string" }, "description": "Restricts collection of BGP advertisements to specific subnets if the device supports it. Honored only if\n`collectBgpAdvertisements` is `true`.", "examples": [ [ "123.223.47.0/24" ] ] }, "prompt": { "type": "string", "description": "A case-insensitive glob pattern used to identify an interactive prompt. When this pattern matches the end of\nthe prompt, ignoring any trailing whitespace, the Collector will enter the configured `promptResponse`.\nRelevant for devices collected via SSH or Telnet.", "examples": [ "y/n" ] }, "promptResponse": { "type": "string", "description": "What the Collector should enter in response to a device prompt matching `prompt` in order to proceed.\nRelevant for devices collected via SSH or Telnet. Required if `prompt` is set.", "examples": [ "y" ] } } }, "ControllerManagedDeviceWithMeta": { "type": "object", "required": [ "name", "host" ], "properties": { "collect": { "type": "boolean", "description": "Whether to collect from the device. Defaults to true.", "examples": [ false ] }, "note": { "type": "string", "description": "An optional description or note about the device." }, "enableSnmpCollection": { "type": "boolean", "description": "Whether to collect performance data (counters) via SNMP. Defaults to false.", "examples": [ false ] }, "highCpuUsage": { "type": "number", "format": "float", "minimum": 0.75, "maximum": 1, "description": "Threshold at or above which CPU usage is considered high. Defaults to 0.8 (80.0%).", "examples": [ 0.85 ] }, "highMemoryUsage": { "type": "number", "format": "float", "minimum": 0.75, "maximum": 1, "description": "Threshold at or above which memory usage is considered high. Defaults to 0.9 (90.0%).", "examples": [ 0.92 ] }, "highInputUtilization": { "type": "number", "format": "float", "minimum": 0.75, "maximum": 1, "description": "Threshold at or above which input interface utilization is considered high. Defaults to 0.9\n(90.0%).", "examples": [ 0.8 ] }, "highOutputUtilization": { "type": "number", "format": "float", "minimum": 0.75, "maximum": 1, "description": "Threshold at or above which output interface utilization is considered high. Defaults to 0.9\n(90.0%).", "examples": [ 0.88 ] }, "mediumCpuUsage": { "type": "number", "format": "float", "minimum": 0.5, "maximum": 1, "description": "Threshold at or above which CPU usage is considered medium high. Has no default value.", "examples": [ 0.7 ] }, "mediumMemoryUsage": { "type": "number", "format": "float", "minimum": 0.5, "maximum": 1, "description": "Threshold at or above which memory usage is considered medium high. Has no default value.", "examples": [ 0.71 ] }, "mediumInputUtilization": { "type": "number", "format": "float", "minimum": 0.5, "maximum": 1, "description": "Threshold at or above which input interface utilization is considered medium high. Has no\ndefault value.", "examples": [ 0.72 ] }, "mediumOutputUtilization": { "type": "number", "format": "float", "minimum": 0.5, "maximum": 1, "description": "Threshold at or above which output interface utilization is considered medium high. Has no\ndefault value.", "examples": [ 0.73 ] }, "name": { "type": "string", "description": "A name that’s unique (ignoring case) among all of the network’s collection source names. May consist of\nletters, digits, dots, hyphens, and underscores.", "examples": [ "leaf-101" ] }, "type": { "$ref": "#/components/schemas/ControllerManagedDeviceType", "description": "Auto-detected during connectivity testing if unspecified.", "examples": [ "cisco_nxos_aci_ssh" ] }, "host": { "type": "string", "description": "IP address or hostname used to connect to the device.", "examples": [ "10.121.7.13" ] }, "port": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 65535, "description": "Port used to connect to the device. The default value depends on the collection protocol: 22 for SSH, 443\nfor HTTPS, etc.", "examples": [ 22 ] }, "cliCredentialId": { "type": "string", "description": "The `id` of a CliCredential of type `LOGIN`. Relevant for devices collected via SSH or Telnet. Credential\nauto-association will be attempted using credentials configured to allow it if this property is unspecified\nand collecting from this device requires this kind of credential.", "examples": [ "L-3" ] }, "cliCredential2Id": { "type": "string", "description": "The `id` of a CliCredential of type `PRIVILEGED_MODE` (for Cisco-like or Checkpoint devices) or `SHELL` (for\nAvi controllers). On Checkpoint, this credential is used for TACACS privilege escalation. Credential\nauto-association will be attempted using credentials configured to allow it if this property is unspecified\nand collecting from this device requires this kind of credential.", "examples": [ "PM-2" ] }, "cliCredential3Id": { "type": "string", "description": "The `id` of a CliCredential of type `EXPERT_MODE` (for Checkpoint devices). Can be set with or without a\n`PRIVILEGED_MODE` credential for `cliCredential2Id`. Credential auto-association will be attempted using\ncredentials configured to allow it if this property is unspecified and collecting from this device requires\nthis kind of credential.", "examples": [ "EM-6" ] }, "httpCredentialId": { "type": "string", "description": "The `id` of an HttpCredential of type `LOGIN` or `API_KEY`. Relevant for devices collected via HTTPS or\nHTTP. Credential auto-association will be attempted using credentials configured to allow it if this\nproperty is unspecified and collecting from this device requires this kind of credential.", "examples": [ "H-5" ] }, "snmpCredentialId": { "type": "string", "description": "The `id` of an SnmpCredential. Used to collect performance data (counters) if `enableSnmpCollection` is\ntrue. Credential auto-association will be attempted using credentials configured to allow it if this\nproperty is unspecified and collecting from this device requires this kind of credential.", "examples": [ "S-4" ] }, "jumpServerId": { "type": "string", "description": "The `id` of the JumpServer that should be used to collect from this device.", "examples": [ "J-0" ] }, "disableIpv6Collection": { "type": "boolean", "description": "Disables collection of any IPv6 forwarding state on the device. Defaults to false.", "examples": [ false ] }, "fullCollectionLog": { "type": "boolean", "description": "Enables more detailed logging during collection. Defaults to false.", "examples": [ false ] }, "paginationMode": { "$ref": "#/components/schemas/PaginationMode", "description": "The pagination mode to use during collection. Relevant for devices collected via SSH or Telnet. Defaults to\n`DISABLE_PAGINATION`. Per-command pagination (such as appending `| more`) may be used if set to\n`ENABLE_PAGINATION` for a device that doesn’t have a per-session pagination mode setting.", "examples": [ "KEEP_UNCHANGED" ] }, "terminalWidth": { "type": "integer", "format": "int32", "minimum": 80, "maximum": 500, "description": "Width of pseudo-terminal in characters. A high value can prevent long lines from wrapping. Defaults to 500.\nRelevant for devices collected via SSH or Telnet.", "examples": [ 500 ] }, "largeRtt": { "type": "boolean", "description": "Whether the device has a large round-trip time (requires a longer response timeout).", "examples": [ false ] }, "minBytesReadPerSec": { "type": "integer", "format": "int64", "description": "The minimum read rate in bytes/sec required to prevent collection from failing with a\n`SLOW_READ_RATE_DETECTED` error. Defaults to 500.", "examples": [ 1000 ] }, "maxConnectionsPerMin": { "type": "integer", "format": "int32", "description": "The maximum number of connections to this device that should be attempted per minute. Setting this property\ncan prevent spurious connectivity test failures if the device’s SSH server is configured with a connection\nrate limit.", "examples": [ 10 ] }, "useFileTransferForLargeOutput": { "type": "boolean", "description": "Whether to use file transfer instead of printing large command output directly to the shell. This is\ncurrently only supported for Juniper devices when executing routing table commands. The primary purpose is\nto avoid printing large outputs directly to the shell, which on Juniper devices can interfere with packet\nforwarding performance. Instead, the command output is written to a temporary file on the device and then\ntransferred over a separate connection. After the transfer is complete, the temporary file is deleted to\nprevent unnecessary disk usage on the device.", "examples": [ false ] }, "bmpStationHost": { "type": "string", "description": "IP address or hostname of the BMP station from which BMP collection should be performed for this device. If\nset, a jump server won’t be used for BMP collection.", "examples": [ "10.121.7.33" ] }, "bgpAndBmpFailureHandling": { "type": "string", "description": "How to handle BGP or BMP collection failure. Defaults to `FAIL_DEVICE`.", "examples": [ "SWITCH_TO_CLI" ], "enum": [ "FAIL_DEVICE", "SWITCH_TO_CLI", "ALWAYS_USE_CLI", "ALWAYS_USE_BMP", "CONTINUE_WITHOUT_BGP_DATA" ] }, "collectBgpAdvertisements": { "type": "boolean", "description": "Whether BGP advertisements should be collected. Defaults to `false` unless advertisement collection is\nrequired to model a [synthetic device](https://docs.fwd.app/latest/api/synthetic-devices/) connected to this\ndevice.", "examples": [ false ] }, "bgpTableType": { "type": "string", "description": "The BGP route types to collect. Honored only if `collectBgpAdvertisements` is true. Defaults\nto `BOTH`.", "examples": [ "BOTH" ], "enum": [ "BOTH", "ADJ_RIB_IN", "ADJ_RIB_OUT" ] }, "bgpPeerType": { "type": "string", "description": "The BGP peer types from which to collect routes. Honored only if `collectBgpAdvertisements` is true.\nDefaults to `BOTH`.", "examples": [ "BOTH" ], "enum": [ "BOTH", "EBGP", "IBGP" ] }, "bgpSubnetsToCollect": { "type": "array", "items": { "type": "string" }, "description": "Restricts collection of BGP advertisements to specific subnets if the device supports it. Honored only if\n`collectBgpAdvertisements` is `true`.", "examples": [ [ "123.223.47.0/24" ] ] }, "prompt": { "type": "string", "description": "A case-insensitive glob pattern used to identify an interactive prompt. When this pattern matches the end of\nthe prompt, ignoring any trailing whitespace, the Collector will enter the configured `promptResponse`.\nRelevant for devices collected via SSH or Telnet.", "examples": [ "y/n" ] }, "promptResponse": { "type": "string", "description": "What the Collector should enter in response to a device prompt matching `prompt` in order to proceed.\nRelevant for devices collected via SSH or Telnet. Required if `prompt` is set.", "examples": [ "y" ] } } }, "ControllerManagedDevicesUpdate": { "type": "object", "properties": { "collect": { "type": "boolean", "description": "Whether to collect from the device. Use `null` to clear. Omit to leave alone.", "examples": [ false ] }, "note": { "type": "string", "description": "An optional description or note about the device. Use `null` to clear. Omit to leave alone." }, "enableSnmpCollection": { "type": "boolean", "description": "Whether to collect performance data (counters) via SNMP. Use `null` to clear. Omit to leave alone.", "examples": [ false ] } } } }, "securitySchemes": { "api_token": { "type": "http", "scheme": "basic" } } } }