VXG Knowledge Base

Hybrid VMS Gateways: Connecting and Managing Cameras with CloudTwo

Hybrid gateway integration uses the cloud VMS and the on-prem VMS directly. The curls below are the calls to make.

These are the variables you will need to connect the gateways and cameras to those gateways:

VMS_HOST="https://your-tenant.cloud-vms.com"
LKEY="your-lkey"
SITE_GROUP_TOKEN="site-group-token"
RESOLVER_URL="https://resolver.example/path"
RESOLVER_USER="resolver-user"
RESOLVER_PASS="resolver-pass"
HUB_URL="https://hub.example"
HUB_API_KEY="hub-api-key"
GATEWAY_ENDPOINT="https://gateway.site-a.customer.cloud-vms.com"

Writes to the cloud VMS use api/v3 and Authorization: LKey. The cloud playback token is read from api/v5 with Authorization: SI and the site group token. That token is the token field on the channel group named Site{siteId}.

The on-prem host, or gateway_endpoint follows the pattern

https://gateway.{instanceName}.{customerName}.{domain}/.

instanceName: this can be set by the customer

customerName: this is set in the environment variables as one instance of CloudTwo will only use one customer Name

domain: is cloud-vms.com by default unless HUB_DOMAIN_NAME is set.

Register a Gateway

The user should provide:

site - siteId corresponding with an existing site on the instance
gateway name - string, can be anything will be shown to the user to identify the gateway
gateway username - string, username set for this gateway
gateway password - string, password set for this gateway
instance name - will be used to formulate the URL for this gateway. You can get this when the hybrid gateway is delpoyed
retention - int, retention time by default set in days. Should be between 1 - 3.

  1. Ensure this gateway isn’t already registered on the service. Authorization is the gateway ID:

Bash
curl "$RESOLVER_URL?serial_id=GATEWAY-ID" \
  -H "Accept: application/json" \
  -H "Authorization: GATEWAY-ID"

A response that contains an id means this gateway ID is already registered. This is the same as our other gateway implementations

  1. Create a gateway channel. You will also use the existing gateways method to do this ie v3/channels and setting the following meta. You will also need to attach this to this sites group token.

Bash
curl -X POST "$VMS_HOST/api/v3/channels/" \
-H "Authorization: LKey $LKEY" \
-H "Content-Type: application/json" \
-d '{
    "name": "Site A hybrid",
    "timezone": "UTC",
    "rec_mode": "off",
    "hosting_mode": "off",
    "source": { "url": "https://camera-proxy.example/uplink_camera/" },
    "meta": {
      "gateway": "gateway",
      "gateway_id": "GATEWAY-ID",
      "GATEWAY-ID": "gateway_id",
      "gateway_username": "admin",
      "gateway_password": "secret",
      "max_num_cameras": 64,
      "rsid": "GATEWAY-ID",
      "planId": "NOPLAN",
      "siteId": 123,
      "123": "siteId",
      "retention_time": 3,
      "hybridvms": "hybridvms",
      "instance_name": "site-a",
      "gateway_endpoint": "https://gateway.site-a.customer.cloud-vms.com/"
    }
}'
  1. Regsiter the gateway with the resolver service. Save the access_token.all from the created gateway channel response to use as the access_token.

Bash
curl -X POST "$RESOLVER_URL" \
  -u "$RESOLVER_USER:$RESOLVER_PASS" \
  -H "Content-Type: application/json" \
  -d '{
    "serial_id": "GATEWAY-ID",
    "password": "GATEWAY-ID",
    "access_token": "CHANNEL_ACCESS_TOKEN_ALL"
  }'
  1. Register the gateway with the uplink hub. This call will register the hostname

Bash
curl -X POST "$HUB_URL/api/v1/groups/" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $HUB_API_KEY" \
  -d '{
    "name": "Site A hybrid",
    "site_name": "site-a",
    "customer_name": "customer",
    "domain_name": "cloud-vms.com",
    "channel_id": 456,
    "forward_name": "camera-gateway-http"
  }'
  1. Update gateway meta with the hub group id. The previous call (step 4) will return an id. You will need to save it to the newly created gateway channel as meta.hub_group_id

Bash
curl -X PUT "$VMS_HOST/api/v3/channels/456/" \
  -H "Authorization: LKey $LKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "meta": {
      "gateway": "gateway",
      "gateway_id": "GATEWAY-ID",
      "GATEWAY-ID": "gateway_id",
      "gateway_username": "admin",
      "gateway_password": "secret",
      "max_num_cameras": 64,
      "rsid": "GATEWAY-ID",
      "planId": "NOPLAN",
      "siteId": 123,
      "123": "siteId",
      "retention_time": 30,
      "hybridvms": "hybridvms",
      "instance_name": "site-a",
      "gateway_endpoint": "https://gateway.site-a.customer.cloud-vms.com/",
      "hub_group_id": "group-abc-123" // new id from hub url
    }
  }'

Add a camera to the gateway

  1. Create the camera channel. gatewayChannelId is the gateway channel id from the previous step. This is also using the same method as the existing gateways, ip, http and rtsp coming from the user input when adding the camera. Add this channel to Site123 the same way as the gateway.

curl -X POST "$VMS_HOST/api/v3/channels/" \
  -H "Authorization: LKey $LKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lobby",
    "timezone": "America/New_York",
    "rec_mode": "off",
    "events_enabled": false,
    "source": {
      "login": "admin",
      "password": "secret",
      "url": "https://camera-proxy.example/uplink_camera/",
      "onvif_rtsp_port_fwd": 554
    },
    "meta": {
      "gateway_cam": "gateway_cam",
      "gateway_id": "GATEWAY-ID",
      "GATEWAY-ID": "gateway_id",
      "gateway_ip": "192.168.1.50",
      "gateway_http": 80,
      "gateway_rtsp": 554,
      "siteId": 123,
      "123": "siteId",
      "gatewayChannelId": 456,
      "hybridvms": "hybridvms",
      "instance_name": "site-a",
      "gateway_endpoint": "https://gateway.site-a.customer.cloud-vms.com/"
    }
  }'
  1. Get the gateway auth token. Log in with the gateway username and password stored on the gateway channel. The response field is token. Send it as Authorization: Token on every later on-prem call.

curl -X POST "$GATEWAY_ENDPOINT/api/auth-token/" \
  -H "Content-Type: application/json" \
  -d '{ "username": "admin", "password": "secret" }'
GATEWAY_TOKEN="token-from-auth-response"
  1. Register the camera to the gateway. access_token is access_tokens.all from the camera channel. The path id on the on-prem VMS is the cloud channel id.

curl -X POST "$GATEWAY_ENDPOINT/api/add-camera/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Token $GATEWAY_TOKEN" \
  -d '{
    "ip": "192.168.1.50",
    "http_port": "80",
    "rtsp_port": "554",
    "is_active": false,
    "pid": null,
    "access_token": "CAMERA_ACCESS_TOKEN_ALL",
    "rtsp_only": "0",
    "username": "admin",
    "password": "secret",
    "name": "Lobby",
    "retention_time": 30
  }'

Cloud and local playback

The switch only changes which token the player receives. It does not change where video is recorded.

Cloud playback uses the token field from api/v5. Pass that value to the player.

curl "$VMS_HOST/api/v5/channels/789/" \
  -H "Authorization: SI $SITE_GROUP_TOKEN"

Local playback uses the on-prem camera record. Log in first with the same gateway auth call as in step 2 of creating the camera, then:

curl "$GATEWAY_ENDPOINT/api/camera/789" \
  -H "Authorization: Token $GATEWAY_TOKEN"
{
  "local_token": "<on-site playback token>",
  "access_token": "<cloud playback token>",
  "process_mode": "none"
}

Pass local_token to the same player. access_token in this body is the cloud token stored on the gateway. Either that value or the v5 token can play through the cloud. If local_token is missing, local playback is unavailable.

5. Copy events or recordings to the cloud

Recording stays on the local VMS until you set process_mode.

curl -X POST "$GATEWAY_ENDPOINT/api/edit-camera/789/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Token $GATEWAY_TOKEN" \
  -d '{ "process_mode": "event_and_record_sync" }'

process_mode

Meaning

none

Do not copy events or recordings to the cloud.

event_sync

Copy events only.

event_and_record_sync

Copy events and recorded video.

Read the current value from process_mode on:

curl "$GATEWAY_ENDPOINT/api/camera/789/" \
  -H "Authorization: Token $GATEWAY_TOKEN"

The same edit call updates the camera when its address, ports, login, or name change. Send only the fields that changed.

curl -X POST "$GATEWAY_ENDPOINT/api/edit-camera/789/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Token $GATEWAY_TOKEN" \
  -d '{
    "ip": "192.168.1.51",
    "http_port": "80",
    "rtsp_port": "554",
    "username": "admin",
    "password": "secret",
    "name": "Lobby east"
  }'

To change retention for every camera, update the gateway channel, then edit each camera. Include the existing meta when you put the channel.

curl -X PUT "$VMS_HOST/api/v3/channels/456/" \
  -H "Authorization: LKey $LKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "meta": {
      "retention_time": 14,
      "hybridvms": "hybridvms",
      "gateway_endpoint": "https://gateway.site-a.customer.cloud-vms.com/"
    }
  }'
curl -X POST "$GATEWAY_ENDPOINT/api/edit-camera/789/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Token $GATEWAY_TOKEN" \
  -d '{ "retention_time": 14 }'

Remove

Delete each camera on the on-prem VMS first, then delete its cloud channel.

curl -X DELETE "$GATEWAY_ENDPOINT/api/cameras/789/" \
  -H "Authorization: Token $GATEWAY_TOKEN"
curl -X DELETE "$VMS_HOST/api/v3/channels/789/" \
  -H "Authorization: LKey $LKEY"

When no cameras remain, delete the hub group, the resolver registration, restart the gateway, and delete the gateway channel.

curl -X DELETE "$HUB_URL/api/v1/groups/group-abc-123" \
  -H "X-API-Key: $HUB_API_KEY"
curl -X DELETE "$RESOLVER_URL?serial_id=GATEWAY-ID" \
  -u "$RESOLVER_USER:$RESOLVER_PASS"
curl -X POST "$GATEWAY_ENDPOINT/api/restart" \
  -H "Authorization: Token $GATEWAY_TOKEN"
curl -X DELETE "$VMS_HOST/api/v3/channels/456/" \
  -H "Authorization: LKey $LKEY"