Use WebSockets to listen to element notifications

You can use WebSockets to listen to notifications about elements stored in the Management Server database.

To monitor elements, you subscribe to status notifications. When the Management Server receives new information about the elements to which you have subscribed, you receive new status entries.

Steps

  1. Login to the SMC API with the login method.
  2. Transfer the session cookie to the WebSocket session or share the socket itself.
  3. Connect to the WebSocket using the following URL: 
    ws://[server]:[port]/[version]/status/socket
  4. Send one of the following types of commands to subscribe to status notifications:
    • To open a channel to subscribe to notifications from all elements that belong to the same element family type, enter:
      {"context":filter_context_value}

      Replace filter_context_value with the element family type, such as fw_single or virtual_fw.

    • To open a channel to subscribe to notifications from specific individual elements, such as a virtual engine node or a route-base VPN tunnel endpoint, enter:
      {"element":element_uri}

      Replace element_uri with the URI of the element.

      For example:
      http://[server]:[port]/[version]//elements/vpn/{id}/tunnels/{tunnel_id}/endpoints/{end_point_id}
    You receive this type of response:
    {"success":"Subscribed for status", "subscription_id":{id}}
  5. To unsubscribe from status notifications, send the following query: 
    {"unsubscribe":{id_of_the_previous_subscription}}

Example

For example, when you send this command to subscribe to notifications about a policy-based VPN tunnel endpoint:

{"element":"https://http://localhost:8082/7.2.1/elements/vpn/5/tunnels/MiM1OQ==/endpoints/MSMxMTQ="}

You receive this response:

{"success":"Subscribed for status","subscription_id":0}
{"status":{"status":{"health_in_percent":71,"jitter_in_ms":3,"latency_in_ms":71,"monitoring_state":"READY",
"monitoring_status":"OK","name":"Corporate VPN","packet_loss_in_permyriad":361,
"result":[{"href":"http://localhost:8082/7.2.1/elements/vpn/5/tunnels/NTkjNjU=",
"name":"Gateway Tunnel Helsinki VPN Gateway-Paris VPN Gateway","type":"gateway_tunnel"},
{"href":"http://localhost:8082/7.2.1/elements/vpn/5/tunnels/NTkjNjc=","name":"Gateway Tunnel Helsinki VPN Gateway-Tunis VPN Gateway",
"type":"gateway_tunnel"},{"href":"http://localhost:8082/7.2.1/elements/vpn/5/tunnels/NTkjNjQ=",
"name":"Gateway Tunnel Helsinki VPN Gateway-Moscow VPN Gateway","type":"gateway_tunnel"},
{"href":"http://localhost:8082/7.2.1/elements/vpn/5/tunnels/NTkjNjA=","name":"Gateway Tunnel Helsinki VPN Gateway-London VPN Gateway",
"type":"gateway_tunnel"},{"href":"http://localhost:8082/7.2.1/elements/vpn/5/tunnels/NTgjNTk=",
"name":"Gateway Tunnel Beijing VPN Gateway-Helsinki VPN Gateway","type":"gateway_tunnel"},
{"href":"http://localhost:8082/7.2.1/elements/vpn/5/tunnels/NTkjNjM=","name":"Gateway Tunnel Helsinki VPN Gateway-Milan VPN Gateway",
"type":"gateway_tunnel"},{"href":"http://localhost:8082/7.2.1/elements/vpn/5/tunnels/NTYjNTk=",
"name":"Gateway Tunnel Atlanta VPN Gateway-Helsinki VPN Gateway","type":"gateway_tunnel"},
{"href":"http://localhost:8082/7.2.1/elements/vpn/5/tunnels/MiM1OQ==","name":"Gateway Tunnel VPN Client-Helsinki VPN Gateway",
"type":"gateway_tunnel"},{"href":"http://localhost:8082/7.2.1/elements/vpn/5/tunnels/NTUjNTk=",
"name":"Gateway Tunnel Algiers VPN Gateway-Helsinki VPN Gateway","type":"gateway_tunnel"},
{"href":"http://localhost:8082/7.2.1/elements/vpn/5/tunnels/NTkjNjI=","name":"Gateway Tunnel Helsinki VPN Gateway-Mexico City VPN Gateway",
"type":"gateway_tunnel"},{"href":"http://localhost:8082/7.2.1/elements/vpn/5/tunnels/NTkjNjY=",
"name":"Gateway Tunnel Helsinki VPN Gateway-Riyadh VPN Gateway","type":"gateway_tunnel"},
{"href":"http://localhost:8082/7.2.1/elements/vpn/5/tunnels/NTkjNjE=","name":"Gateway Tunnel Helsinki VPN Gateway-Madrid VPN Gateway",
"type":"gateway_tunnel"}],"traffic_in_bits_per_sec":1881231412,"vpn_status_code":"Idle"}},
"subscription_id":0}

When you send this command to subscribe to notifications about a engine node:

{"element":"http://localhost:8082/7.2.1/elements/single_fw/1649/firewall_node/1650"}

You receive this response:

{"success":"Subscribed for status","subscription_id":5}
{"status":{"status":{"monitoring_state":"READY","monitoring_status":"OK","name":"Plano node 1"}},"subscription_id":5}