How to Connect a System to Cloud Using the API?

Overview

There are certain instances when a developer may need to connect an Nx Witness system to the Cloud. This article explains how to automate connecting a system or systems to Nx Cloud using the Server API.

How It Works

Connecting a System to Nx Cloud involves two key steps:

1. Create System credentials for Nx Cloud:
   1. Use this method: https://nxvms.com/cdb/system/bind
   2. This method requires name and customization=default as a parameter 
   3. You'll need to use your existing Nx Cloud credentials.
2. Connect the System to Nx Cloud using credentials created in Step 1:
   1. For a new System (with a Server that is not yet configured) use the /api/setupCloudSystem method.
   2. For an existing System (with one or more Servers configured and running as a System) - use the /api/saveCloudSystemCredentials method

To Connect a New System to Cloud (example Python script)

# This script configures and adds a new system to Nx Cloud

import requests

SERVER_URL = "http://localhost:7001"
CLOUD_URL = "%CLOUD_LINk%"
SYSTEM_NAME = "Your new system"
CUSTOMIZATION = "default"
CLOUD_USER = "testuser"
CLOUD_PASS = "test123"
DEFAULT_LOGIN = "admin"
DEFAULT_PASSWORD = "admin"

# This returns the cloudAuthKey and the cloudSystemID we will need for /api/setupCloudSystem

r = requests.post(CLOUD_URL + "https://nxvms.com/cdb/system/bind",

   json = {
       "name": SYSTEM_NAME,
       "customization": CUSTOMIZATION
       },
   auth = requests.auth.HTTPDigestAuth(CLOUD_USER, CLOUD_PASS))

jsonData = r.json()

# This takes the default login of admin/admin as the server should not already be setup
# If the server is already setup, then you need to run a different command

s = requests.post(SERVER_URL + "/api/setupCloudSystem",

   json = {
       "cloudAuthKey": jsonData["authKey"],
       "systemName": jsonData["name"],
       "cloudSystemID": jsonData["id"],
       "cloudAccountName": jsonData["ownerAccountEmail"]
       },
   auth = requests.auth.HTTPDigestAuth(DEFAULT_LOGIN, DEFAULT_PASSWORD))

To Connect an Existing System to Cloud (example Python script)

# This script adds an existing System to Nx Cloud 

import requests

SERVER_URL = "http://localhost:7001"
CLOUD_URL = "https://nxvms.com"
SYSTEM_NAME = "Your new system"
CUSTOMIZATION = "default"
CLOUD_USER = "testuser"
CLOUD_PASS = "test123"
SYSTEM_LOGIN = "admin"
SYSTEM_PASSWORD = "password123"

# This returns the cloudAuthKey and the cloudSystemID we will need for /api/setupCloudSystem

r = requests.post(CLOUD_URL + "https://nxvms.com/cdb/system/bind",

   json = {
       "name": SYSTEM_NAME,
       "customization": CUSTOMIZATION
       },
   auth = requests.auth.HTTPDigestAuth(CLOUD_USER, CLOUD_PASS))

jsonData = r.json()

# This will take the above information and attach this system to the cloud

s = requests.post(SERVER_URL + "/api/saveCloudSystemCredentials",

   json = {
       "cloudAuthKey": jsonData["authKey"],
       "cloudSystemID": jsonData["id"],
       "cloudAccountName": jsonData["ownerAccountEmail"]
       },
   auth = requests.auth.HTTPDigestAuth(SYSTEM_LOGIN, SYSTEM_PASSWORD))

Note: The default port in Nx Witness is 7001, in case the port has been changed, the port used in the URL in the scripts need to be changed as well (https://localhost:<port>). The script must be launched on the same device as where the target server is located (hence the 'localhost').