{"type":"api","title":"Get Tunnel State","meta":{"id":"/apps/pubhub/media/cloud-security-apis-in-eft/83e8a10367d157243cd1c3e478b807cb81262a3d/6de27b83-cd76-3f18-9e4a-e121ea0a8b86","info":{"title":"Cisco Umbrella Network Tunnels API","description":"Manage the network tunnels in the organization.","version":"2.0.0","contact":{"name":"Cloud Security Developer Community"}},"security":[{"oauthFlow":[]}],"tags":[{"name":"Data Center"},{"name":"Organization Tunnel"},{"name":"Debugging"},{"name":"Umbrella"}],"x-parser-conf":{"overview":{"markdownPath":"reference/deployments/network-tunnels-overview.md","uri":"umbrella-api-reference-network-tunnels-overview"}},"openapi":"3.0.1","servers":[{"url":"https://api.umbrella.com/{basePath}","variables":{"basePath":{"default":"deployments/v2"}}}],"securitySchemes":{"oauthFlow":{"type":"oauth2","description":"client credential flow","flows":{"clientCredentials":{"tokenUrl":"https://api.umbrella.com/auth/v2/token","scopes":{"deployments.tunnels:write":"Write deployments tunnels","deployments.tunnels:read":"Read deployments tunnels","deployments.datacenters:read":"Read deployments datacenters"}}}}}},"spec":{"tags":["Debugging","Umbrella"],"summary":"Get Tunnel State","operationId":"getTunnelState","security":[{"oauthFlow":["deployments.tunnels:read"]}],"description":"Get the tunnel state information.","parameters":[{"in":"path","name":"id","description":"The ID of the tunnel.","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","headers":{"Content-Type":{"schema":{"type":"string"},"description":"The MIME content type of the response body.","example":"application/json","$$ref":"#/components/headers/Content-Type"},"Date":{"schema":{"type":"string","pattern":"^[0-90-90-90-9-0-90-9-0-90-9T0-90-9:0-90-9:0-90-9Z]+$"},"description":"The timestamp of the response.","example":"2023-03-14T18:34:25Z","$$ref":"#/components/headers/Date"}},"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","description":"Tunnel State Information","properties":{"tunnelId":{"type":"string","readOnly":true,"description":"The tunnel ID","example":"163367136"},"status":{"type":"string","readOnly":true,"description":"The high-level tunnel status:\n\n* up - the tunnel is active\n* down - the tunnel is inactive\n* failed - the tunnel is in a failed state\n* unknown - the status is unknown and pending updated information","enum":["UP","DOWN","FAILED","UNKNOWN"],"example":"UP"},"dc":{"type":"string","readOnly":true,"description":"The domain name of the data center.","example":"chi1.edc"},"dcName":{"type":"string","readOnly":true,"description":"The name of the data center.","example":"Equinix Chicago"},"dcDesc":{"type":"string","readOnly":true,"description":"The city and country of region of the data center.","example":"Chicago, Illinois - US"},"ikeState":{"type":"string","readOnly":true,"description":"IKE SA State:\n * CREATED\n * CONNECTING\n * ESTABLISHED\n * PASSIVE\n * REKEYING\n * REKEYED\n * DELETING\n * DESTROYING\n","enum":["CREATED","CONNECTING","ESTABLISHED","PASSIVE","REKEYING","REKEYED","DELETING","DESTROYING"],"example":"ESTABLISHED","$$ref":"#/components/schemas/ikeState"},"ipsecState":{"type":"string","readOnly":true,"description":"IPSec/Child SA State:\n * CREATED\n * ROUTED\n * INSTALLING\n * INSTALLED\n * UPDATING\n * REKEYING\n * REKEYED\n * RETRYING\n * DELETING\n * DELETED\n * DESTROYING\n","enum":["CREATED","ROUTED","INSTALLING","INSTALLED","UPDATING","REKEYING","REKEYED","RETRYING","DELETING","DELETED","DESTROYING"],"example":"INSTALLED","$$ref":"#/components/schemas/ipsecState"},"peerId":{"type":"string","readOnly":true,"description":"The remote peer IKE ID.","example":"unique-value@1234567-234567812-umbrella.com"},"peerIp":{"type":"string","readOnly":true,"description":"The remote peer IP.","example":"198.18.195.1"},"localIp":{"type":"string","readOnly":true,"description":"The public IP address, which is assigned to an endpoint device (ISR, Viptela).","example":"198.25.43.19"},"peerPort":{"type":"string","readOnly":true,"description":"The port of the remote peer.","example":"4500"},"ike":{"title":"tunnelIKEState","type":"object","description":"The tunnel IKE session state.","properties":{"age":{"type":"string","readOnly":true,"description":"The age of the established state in seconds.","example":"6194"},"dhGroup":{"type":"string","readOnly":true,"description":"The IKE Diffie-Hellman group.","example":"MODP_2048"},"prfAlgo":{"type":"string","readOnly":true,"description":"The IKE pseudo random function.","example":"PRF_HMAC_SHA1"},"encAlgo":{"type":"string","readOnly":true,"description":"The IKE encryption algorithm.","example":"AES_CBC"},"initiatorSpi":{"type":"string","readOnly":true,"description":"The hex encoded initiator SPI or cookie.","example":"cf065c564a511834"},"responderSpi":{"type":"string","readOnly":true,"description":"The hex encoded responder SPI or cookie.","example":"a3cd5c8533c80069"}}},"ipsec":{"title":"tunnelIPSecState","type":"object","description":"The tunnel IPSec session state.","properties":{"age":{"type":"string","readOnly":true,"description":"The age of the installed state in seconds.","example":"6194"},"integrityAlgo":{"type":"string","readOnly":true,"description":"The ESP or AH integrity algorithm name.","example":"HMAC_SHA1_96"},"encAlgo":{"type":"string","readOnly":true,"description":"The ESP encryption algorithm name.","example":"NULL"},"encKeySize":{"type":"string","readOnly":true,"description":"The ESP encryption key size (optional field, not available with NULL encryption).","example":"128"},"spiIn":{"type":"string","readOnly":true,"description":"The hex encoded inbound SPI.","example":"c6ef7503"},"spiOut":{"type":"string","readOnly":true,"description":"The hex encoded outbound SPI.","example":"00010102"},"peerSelectors":{"type":"array","readOnly":true,"description":"The peer traffic selectors.","items":{"type":"string","description":"The selector expression.","example":"0.0.0.0/0"}}}},"data":{"title":"tunnelDataState","description":"The state of the network tunnel data plane.","type":"object","properties":{"packetsIn":{"type":"string","readOnly":true,"description":"The number of processed input packets (tunnel ingress).","example":"10"},"bytesIn":{"type":"string","readOnly":true,"description":"The number of processed input bytes (tunnel ingress).","example":"1000"},"idleTimeIn":{"type":"string","readOnly":true,"description":"The idle time (seconds since last inbound packet).","example":"100"},"packetsOut":{"type":"string","readOnly":true,"description":"The number of processed output packets (tunnel egress).","example":"10"},"bytesOut":{"type":"string","readOnly":true,"description":"The number of processed output bytes (tunnel egress).","example":"1000"},"idleTimeOut":{"type":"string","readOnly":true,"description":"The idle time (seconds since last outbound packet).","example":"100"},"initialized":{"type":"string","readOnly":true,"description":"The time when the packet and byte counters were initialized to 0.","example":"2023-10-19T22:15:12.765623734Z"}}},"modifiedAt":{"type":"string","readOnly":true,"format":"date-time","description":"The date and time (UTC time with milliseconds) when the tunnel's state was last updated.","example":"2018-06-13T16:07:07.222Z"}},"example":{"tunnelId":"163367136","status":"UP","dc":"chi1.edc","dcName":"Equinix Chicago","dcDesc":"Chicago, Illinois - US","ikeState":"ESTABLISHED","ipsecState":"INSTALLED","peerId":"unique-value@1234567-234567812-umbrella.com","peerIp":"198.18.195.1","localIp":"198.25.43.19","peerPort":"4500","ike":{"age":"6194","dhGroup":"MODP_2048","prfAlgo":"PRF_HMAC_SHA1","encAlgo":"AES_CBC","initiatorSpi":"cf065c564a511834","responderSpi":"a3cd5c8533c80069"},"ipsec":{"age":"6194","integrityAlgo":"HMAC_SHA1_96","encAlgo":"NULL","encKeySize":"128","spiIn":"c6ef7503","spiOut":"00010102","peerSelectors":["0.0.0.0/0"]},"data":{"packetsIn":"10","bytesIn":"1000","idleTimeIn":"100","packetsOut":"10","bytesOut":"1000","idleTimeOut":"100","initialized":"2023-10-19T22:15:12.765623734Z"},"modifiedAt":"2018-06-13T16:07:07.222Z"},"$$ref":"#/components/schemas/TunnelStateInformation"}},"example":[{"tunnelId":"163367136","status":"UP","dc":"chi1.edc","dcName":"Equinix Chicago","dcDesc":"Chicago, Illinois - US","ikeState":"ESTABLISHED","ipsecState":"INSTALLED","peerId":"unique-value@1234567-234567812-umbrella.com","peerIp":"198.18.195.1","localIp":"198.25.43.19","peerPort":"4500","ike":{"age":"6194","dhGroup":"MODP_2048","prfAlgo":"PRF_HMAC_SHA1","encAlgo":"AES_CBC","initiatorSpi":"cf065c564a511834","responderSpi":"a3cd5c8533c80069"},"ipsec":{"age":"6194","integrityAlgo":"HMAC_SHA1_96","encAlgo":"NULL","encKeySize":"128","spiIn":"c6ef7503","spiOut":"00010102","peerSelectors":["0.0.0.0/0"]},"data":{"packetsIn":"10","bytesIn":"1000","idleTimeIn":"100","packetsOut":"10","bytesOut":"1000","idleTimeOut":"100","initialized":"2023-10-19T22:15:12.765623734Z"},"modifiedAt":"2018-06-13T16:07:07.222Z"}]}}},"400":{"description":"Bad Request","headers":{"Content-Type":{"schema":{"type":"string"},"description":"The MIME content type of the response body.","example":"application/json","$$ref":"#/components/headers/Content-Type"},"Date":{"schema":{"type":"string","pattern":"^[0-90-90-90-9-0-90-9-0-90-9T0-90-9:0-90-9:0-90-9Z]+$"},"description":"The timestamp of the response.","example":"2023-03-14T18:34:25Z","$$ref":"#/components/headers/Date"}},"content":{"application/json":{"schema":{"type":"object","minProperties":3,"required":["statusCode","error","txId"],"properties":{"statusCode":{"type":"integer","example":400,"description":"HTTP status code"},"error":{"type":"string","example":"Validation Error","description":"a brief description of the error"},"txId":{"type":"string","example":"86e189a6-0124-47d3-a32c-25ff3f07deaf","description":"a unique hex number that can be used for debugging"},"validationErrors":{"type":"object","properties":{"someProperty":{"type":"string","example":"must not be empty","description":"the name of the property failing validation."}}}}}}},"$$ref":"#/components/responses/BadRequest"},"401":{"description":"Unauthorized","headers":{"Content-Type":{"schema":{"type":"string"},"description":"The MIME content type of the response body.","example":"application/json","$$ref":"#/components/headers/Content-Type"},"Date":{"schema":{"type":"string","pattern":"^[0-90-90-90-9-0-90-9-0-90-9T0-90-9:0-90-9:0-90-9Z]+$"},"description":"The timestamp of the response.","example":"2023-03-14T18:34:25Z","$$ref":"#/components/headers/Date"}},"content":{"application/json":{"schema":{"type":"object","minProperties":3,"required":["statusCode","error","txId"],"properties":{"statusCode":{"type":"integer","example":401,"description":"HTTP status code"},"error":{"type":"string","example":"Unauthorized","description":"A brief description of the error"},"txId":{"type":"string","example":"86e189a6-0124-47d3-a32c-25ff3f07deaf","description":"a unique hex number that can be used for debugging"}}}}},"$$ref":"#/components/responses/Unauthorized"},"403":{"description":"Forbidden","headers":{"Content-Type":{"schema":{"type":"string"},"description":"The MIME content type of the response body.","example":"application/json","$$ref":"#/components/headers/Content-Type"},"Date":{"schema":{"type":"string","pattern":"^[0-90-90-90-9-0-90-9-0-90-9T0-90-9:0-90-9:0-90-9Z]+$"},"description":"The timestamp of the response.","example":"2023-03-14T18:34:25Z","$$ref":"#/components/headers/Date"}},"content":{"application/json":{"schema":{"type":"object","minProperties":1,"required":["message"],"properties":{"statusCode":{"type":"integer","example":403,"description":"HTTP status code"},"message":{"type":"string","example":"SIG is not enabled, please check with Cisco Support.\nYou have reached the maximum number of network tunnels for this organization.\nTo increase the limit, contact your administrator.\n","description":"Error message explaining the reason for failure"}}}}},"$$ref":"#/components/responses/Forbidden"},"404":{"description":"Not Found","headers":{"Content-Type":{"schema":{"type":"string"},"description":"The MIME content type of the response body.","example":"application/json","$$ref":"#/components/headers/Content-Type"},"Date":{"schema":{"type":"string","pattern":"^[0-90-90-90-9-0-90-9-0-90-9T0-90-9:0-90-9:0-90-9Z]+$"},"description":"The timestamp of the response.","example":"2023-03-14T18:34:25Z","$$ref":"#/components/headers/Date"}},"content":{"application/json":{"schema":{"type":"object","minProperties":3,"required":["statusCode","error","txId"],"properties":{"statusCode":{"type":"integer","example":404,"description":"HTTP status code"},"error":{"type":"string","example":"Not Found","description":"A brief description of the error"},"txId":{"type":"string","example":"86e189a6-0124-47d3-a32c-25ff3f07deaf","description":"a unique hex number that can be used for debugging"}}}}},"$$ref":"#/components/responses/NotFound"},"500":{"description":"Internal Server Error","headers":{"Content-Type":{"schema":{"type":"string"},"description":"The MIME content type of the response body.","example":"application/json","$$ref":"#/components/headers/Content-Type"},"Date":{"schema":{"type":"string","pattern":"^[0-90-90-90-9-0-90-9-0-90-9T0-90-9:0-90-9:0-90-9Z]+$"},"description":"The timestamp of the response.","example":"2023-03-14T18:34:25Z","$$ref":"#/components/headers/Date"}},"content":{"application/json":{"schema":{"type":"object","minProperties":3,"required":["statusCode","error","txId"],"properties":{"statusCode":{"type":"integer","example":500,"description":"HTTP status code"},"error":{"type":"string","example":"Internal Server Error","description":"a brief description of the error"},"txId":{"type":"string","example":"86e189a6-0124-47d3-a32c-25ff3f07deaf","description":"a unique hex number that can be used for debugging"}}}}},"$$ref":"#/components/responses/ServerError"}},"__originalOperationId":"getTunnelState","method":"get","path":"/tunnels/{id}/state"}}