NetCloud API

Configuration in API V2

This document describes the conventions for using the configuration-related endpoints and how to extend those conventions.

There are two endpoints for working with device configurations. One endpoint is for individual-device configs, the other is for group configs.

Endpoints:

https://www.cradlepointecm.com/api/v2/configuration_managers/
https://www.cradlepointecm.com/api/v2/groups/

Individual Device Configurations

Individual device configs are managed by the configuration_managers endpoint

https://www.cradlepointecm.com/api/v2/configuration_managers/[id/]

A configuration manager is an abstract resource for controlling and monitoring configuration sync on a single device. Each device has its own corresponding configuration manager.

Schema

account         # URL to account that owns the config (readonly)
actual          # JSON diff of router's actual config (readonly) [1]
pending         # JSON diff of pending updates to device (readonly) [1]
target          # JSON diff of target config (readonly) [1]
resource_url    # URL to this endpoint (readonly)
version_number  # integer count of config changes (readonly)
router          # URL to device endpoint (readonly, expandable) 
id              # integer ID of this resource (readonly, sortable)
synched         # true if device config is synced (readonly)
suspended       # false unless config sync is paused (read/write)
configuration   # JSON diff of individual config (read/write) [1]

[1] See the discussion of config diffs in the Appendix of this document.

The account is a link to the same account that the device links to.

The actual config shows the last diff received from the router. It is only valid for Series 3 routers (see differences between series 2 and series 3 routers). Routers send diffs when they connect to NetCloud Manager (NCM) and whenever the config changes while they are connected. This config is always formatted to match the router's current actual firmware.

The pending config is empty except for unsynced devices, and then it shows the changes waiting to be synced to the device when it connects or resumes config sync. If the device's actual firmware and target firmware are different, the pending field appears empty even if there are pending changes. This is because the changes cannot be comuputed until the device syncs its firmware version. (Comparing configs for different firmware versions is not well-defined.)

The target config is the result of layering an individual config over the group config. It is the final desired configuration of the device. When the target and actual fields are the same, the device is in sync. This config is always formatted to match the device's target firmware. If the device has no target firmware, it matches the actual firmware.

The resource_url is a self-referential link to the resource. It is not generally useful for anything.

The version_number starts at zero and increments any time the target config changes. This is used as part of the sync protocol with the device client. The device stores a copy of the last version_number it synced to in its own config, as ecm.config_version. When the device sends a config diff to NCM, NCM checks if the device has the latest version_number. If and only if it does, then NCM considers the device to be in-sync and accepts any local changes. If it does not match, NCM ignores and even wipes local changes to force the device to sync. The API shows this number for informational purposes only. It automatically increments any time a change is made via the NCM UI, or the NetCloud API, or a local change is accepted, or if the config is migrated to a different firmware version.

The router is a reference to the device.

The id is the identifier for the resource. It sometimes matches the device id, but not necessarily, so do not assume they are the same.

The synched flag is true if the device is synced and false if there are pending changes.

The suspended flag is true if config sync has been stopped. This happens when the device rejects a configuration change from NCM. If the Configuration Rejected alert is enabled, this event generates an alert with information from the device about why it rejected the config. After fixing the config, sync can be resumed by setting suspended to false via the API (or via the Resume Updates button in the UI).

The configuration field shows the individual configuration for the device. The API can be used to change values in the config via PUT or PATCH, see the examples below. This config is formatted to match the device's target firmware (or actual, if there is no target). When the device's target firmware changes, NCM automatically migrates this config to be compatible with the new firmware.

Allowed HTTP methods are GET, PUT and PATCH. The user must have at least a full-access role for PUT and PATCH. Any attempt to PUT or PATCH the config is validated using static validators. The validator checks the format of the config, verifying that the keys are valid and the values conform to the correct types and ranges.

GET

GET works as described in the the API V2 documentation for all endpoints.

Possible HTTP status codes:

200 Ok            # Success
401 Unauthorized  # Incorrect or missing X-ECM-API-ID or X-ECM-API-KEY headers
403 Forbidden     # Invalid URL or resource not visible

Supported filters:

Field           Filters   Right-hand side
=====           =======   ===============
version_number  =,gt,lt   any non-negative integer
router          =,in      device ID
id              =,in      resource ID
synched         =         true or false
suspended       =         true or false

Other supported URL parameters:

offset  # first object to return (for paging)
limit   # max objects to return (for paging)
fields  # list of fields to return (for partial returns)
expand  # convert a url field to an embedded object (only supported on some fields)

See here for an explanation of the example format.

GET Example: A Specific Manager

> GET https://www.cradlepointecm.com/api/v2/configuration_manager/123/
< 200 Ok
< {
<     "success": true,
<     "data": {
<         "pending" : [
<            {},
<            []
<         ],
<         "account" : "https://www.cradlepointecm.com/api/v2/accounts/1/",
<         "target" : [
<            {
<               "system" : {
<                  "logging" : {
<                     "level" : "debug"
<                  }
<               },
<               "lan" : {
<                  "00000000-0d93-319d-8220-4a1fb0372b51" : {
<                     "ip_address" : "192.168.30.1",
<                     "_id_" : "00000000-0d93-319d-8220-4a1fb0372b51",
<                     "name" : "LAN0"
<                  }
<               },
<               "ecm" : {
<                  "config_version" : 18
<               }
<            },
<            []
<         ],
<         "actual" : [
<            {
<               "ecm" : {
<                  "config_version" : 18
<               },
<               "lan" : {
<                  "0" : {
<                     "name" : "LAN0",
<                     "ip_address" : "192.168.30.1"
<                  }
<               },
<               "system" : {
<                  "logging" : {
<                     "level" : "debug"
<                  }
<               }
<            },
<            []
<         ],
<         "resource_url" : "https://www.cradlepointecm.com/api/v2/configuration_managers/1/",
<         "version_number" : 18,
<         "router" : "https://www.cradlepointecm.com/api/v2/routers/1/",
<         "id" : "1",
<         "synched" : true,
<         "suspended" : false,
<         "configuration" : [
<            {
<               "system" : {
<                  "logging" : {
<                     "level" : "debug"
<                  }
<               },
<               "lan" : {
<                  "00000000-0d93-319d-8220-4a1fb0372b51" : {
<                     "name" : "LAN0",
<                     "ip_address" : "192.168.30.1",
<                     "_id_" : "00000000-0d93-319d-8220-4a1fb0372b51"
<                  }
<               }
<            },
<            []
<         ]
<     }
< }

The device is synced in the previous example. This is indicated by the following:

• the pending field is an empty diff ([{}, []])
• the actual and target fields have the same content, and
• synched is true

You may have noticed that the target and actual fields do not look identical. In the lan section, the target has this:

< "00000000-0d93-319d-8220-4a1fb0372b51" : {
<	"ip_address" : "192.168.30.1",
<    "_id_" : "00000000-0d93-319d-8220-4a1fb0372b51",
<    "name" : "LAN0"
< }

But the actual has this:

< "0" : {
<	"name" : "LAN0",
<    "ip_address" : "192.168.30.1"
< }

This difference is because the lan array has an _id_ field, and the device and NCM express these kind of arrays differently. This is an unfortunate legacy of the way the _id_ fields were first introduced into device firmware. NCM can understand both representations, and it recognizes that they are saying the same thing, so it knows the device is actually synced. See the section on _id_ fields for more details.

PUT

PUT replaces an entire individual config with the given payload. It can also be used to resume the sync on a suspended device.

As indicated in the schema, only two fields are writable: configuration (the individual config) and suspended. It is not necessary to provide both with PUT. You can PUT just the configuration to change the indie config, or just the suspended field to resume sync. If you include any other field in your PUT request payload you will get a 409 Conflict.

HTTP status codes:

202 Accepted            # Success
401 Unauthorized        # Incorrect or missing X-ECM-API-ID or X-ECM-API-KEY headers
403 Forbidden           # Invalid URL or resource not visible
405 Method Not Allowed  # URL did not include an /<id>/ in the path
409 Conflict            # Invalid API or config request

You cannot PUT to more than one configuration manager at a time. This is ok:

> PUT https://www.cradlepointecm.com/api/v2/configuration_managers/34365/

These are not, and return a 405 Method Not Allowed:

> PUT https://www.cradlepointecm.com/api/v2/configuration_managers/
> PUT https://www.cradlepointecm.com/api/v2/configuration_managers/?synched=false
> PUT https://www.cradlepointecm.com/api/v2/configuration_managers/56/

A 409 Bad Request can mean that the request is trying to set an invalid config, and the problem is something inside the config body. The response includes the validation error. For example:

> PUT https://www.cradlepointecm.com/api/v2/configuration_managers/2/
> {"configuration": [{"foo": "bar"}, []]}
< 409 Bad Request
< {
<    "errors" : [
<       {
<          "configuration" : {
<             "message" : "cannot set foo to bar: invalid path",
<             "reason" : "invalid path",
<             "value" : "bar",
<             "path" : [
<                "foo"
<             ]
<          }
<       }
<    ],
<    "exception" : {
<       "message" : "bad or missing data",
<       "type" : "validation"
<    }
< }

See here for a complete catalog of config validation errors.

Other URL parameters:

fields  # list of fields to return (for partial returns)

Because PUT is only supported on one configuration manager at a time, the standard filter and paging options do not apply.

See here for an explanation of the example format.

PUT Example: A Simple Config

This enables GPS in the individual config:

> PUT https://www.cradlepointecm.com/api/v2/configuration_managers/17/?fields=configuration
> {
>     "configuration": [
>         {
>             "system": {
>                 "gps": {
>                     "enabled": true
>                 }
>             }
>         },
>         []
>     ]
> }
< 202 Accepted
< {
<     "configuration": [
<         {
<             "system": {
<                 "gps": {
<                     "enabled": true
<                 }
<             }
<         },
<         []
<     ]
< }

(The fields=configuration URL option is telling NCM to reply with only the configuration field, otherwise it would return the entire config manager object. For brevity, the PUT examples always use this technique.)

If the request actually changes the config -- which is usually the intent -- the following changes take place:

• the target field is updated
• the version_number field is incremented
• the synched field is set to false, and
• the pending field shows the changes that will be (or already have been) sent to sync the device

If the request does not change the config (meaning it already matches the request payload) then nothing changes.

Since only system.gps.enabled is set, all other individual config settings will be unassigned. That means they will be determined by the group config. If there is no group config, or if the group config also leaves a setting unassigned, then the default value will apply.

It is important to understand that for PUT, not specifying a config value is equivalent to removing it from the individual config, if it was there. PATCH is different, as discussed below.

PUT Example: A Complicated Config

The following example config removes the default Guest LAN and sets up LAN port 4 on a VLAN to pass traffic to the WAN. It does this by performing the following actions:

1. Removes the default Guest LAN
2. Moves port 4 from the set of normal LAN ports to a new VLAN called "aleph"
3. Assigns the aleph VLAN to a new LAN interface called "Aleph LAN"
4. Adds a new firewall zone for the Aleph LAN
5. Adds a forwarding rule from the aleph zone to the WAN zone

The request:

> PUT https://www.cradlepointecm.com/api/v2/configuration_managers/2/?fields=version_number
> {
>     "configuration": [
>         {
>             "lan": {
>                 "00000001-2a38-3724-a6fa-02dfdfbc129e": {
>                     "_id_": "00000001-2a38-3724-a6fa-02dfdfbc129e",
>                     "devices": [
>                         {
>                             "type": "ethernet",
>                             "uid": "aleph"
>                         }
>                     ],
>                     "dhcpcd": {},
>                     "enabled": true,
>                     "ip_address": "192.168.20.1",
>                     "name": "Aleph LAN",
>                     "netmask": "255.255.255.0"
>                 }
>             },
>             "security": {
>                 "zfw": {
>                     "forwardings": {
>                         "00000004-356d-30f0-962f-bb705dfddfc9": {
>                             "_id_": "00000004-356d-30f0-962f-bb705dfddfc9",
>                             "dst_zone_id": "00000002-695c-3d87-95cb-d0ee2029d0b5",
>                             "enabled": true,
>                             "filter_policy_id": "00000000-77db-3b20-980e-2de482869073",
>                             "src_zone_id": "00000005-e091-3d73-80d1-9a51d6143759"
>                         }
>                     },
>                     "zones": {
>                         "00000005-e091-3d73-80d1-9a51d6143759": {
>                             "_id_": "00000005-e091-3d73-80d1-9a51d6143759",
>                             "devices": [
>                                 {
>                                     "trigger_field": "config_id",
>                                     "trigger_group": "lan",
>                                     "trigger_neg": false,
>                                     "trigger_predicate": "is",
>                                     "trigger_value": "00000001-2a38-3724-a6fa-02dfdfbc129e"
>                                 }
>                             ],
>                             "name": "aleph"
>                         }
>                     }
>                 }
>             },
>             "vlan": {
>                 "2": {
>                     "mode": "lan",
>                     "ports": [
>                         {
>                             "mode": "tagged",
>                             "port": 4
>                         }
>                     ],
>                     "uid": "aleph",
>                     "vid": 3
>                 }
>             }
>         },
>         [
>             ["vlan", 1, "ports", 3],
>             ["lan", "00000001-0d93-319d-8220-4a1fb0372b51"]
>         ]
>     ]
> }
< 202 Accepted
< {
<    "version_number" : 29
< }

The removals are processed by the device first. Removals must refer to elements which exist in the device's default config. Thefollowing elments exist in the default config:

[
	["vlan", 1, "ports", 3],
    ["lan", "00000001-0d93-319d-8220-4a1fb0372b51"]
]

To understand these examples it is necessary to understand what the default config looks like. In this case the device is an MBR1400 router running 5.4.0 firmware. The default vlan array looks like this:

[
    {
       "uid" : "wan",
       "mode" : "wan",
       "vid" : 1,
       "ports" : [
          {
             "port" : 0,
             "mode" : "untagged"
          }
       ]
    },
    {
       "mode" : "lan",
       "uid" : "lan",
       "ports" : [
          {
             "mode" : "untagged",
             "port" : 1
          },
          {
             "port" : 2,
             "mode" : "untagged"
          },
          {
             "port" : 3,
             "mode" : "untagged"
          },
          {                          \
             "port" : 4,              \ This is vlan.1.port.3
             "mode" : "untagged"      /
          }                          /
       ],
       "vid" : 2
    }
]

vlan is an array, and ["vlan", 1, ...] refers to the entry at offset 1. Offsets start at 0, so 1 means the second entry. Within each vlan entry there is another array for the ports. So ["vlan", 1, "ports", 3] means "The port at offset 3 in the vlan at offset 1". In this default config, that is port 4, and it is "untagged". That is what will be removed first.

The next removal looks very different: ["lan", "00000001-0d93-319d-8220-4a1fb0372b51"]. It is obviously trying to remove something from the default lan array, but it is referring to the LAN it wants to remove not by its offset in the array, but by it's unique _id_ field value. "00000001-0d93-319d-8220-4a1fb0372b51" is the _id_ for the Guest LAN, as indicated by the default config, shown here in part:

"lan": [
    {
        "name": "Primary LAN",
        "_id_": 00000000-0d93-319d-8220-4a1fb0372b51"
    },
    {
        "name": "Guest LAN",
        "_id_": 00000001-0d93-319d-8220-4a1fb0372b51"
    }
]

If an array contains elements with an _id_ field then removals can refer to them by this instead of using the offset. Whenever a config is generated by the NCM UI, it uses the _id_ in its removals whenever possible.

After processing the removals, the device applies all the updates in one operation. This part of the config tells it to add a new entry to the vlan array at offset 2:

"vlan": {
    "2": {
        "mode": "lan",
        "ports": [
            {
                "mode": "tagged",
                "port": 4
            }
        ],
        "uid": "aleph",
        "vid": 3
    }
}

Notice that the "2" (the key to the dict) is in quotes, like a string, whereas in the removal ["vlan", 1, "ports", 3] the offsets are not quoted. This is not a mistake and is important. If the "2" is not quoted in the updates then it is not valid JSON and you will get a 400 Bad Request in resonse to your PUT.

Compare adding the vlan entry to adding the lan and security entries. Instead of using a quoted number, these use a UUID as the key. The key value corresponds exactly to the _id_ values inside the entries:

"lan": {
        "00000001-2a38-3724-a6fa-02dfdfbc129e": {
            "_id_": "00000001-2a38-3724-a6fa-02dfdfbc129e",
            <...etc...>

This may seem like senseless repitition but it is required.

When adding an entry to an array which supports _id_ fields, you must provide a UUID or the result is a validation error. The _id_ is necessary to make it clear which entry the update is referring to.

By now it is probably clear that hand-crafting a configuration is not easy. A better approach is to use the NCM UI to create a configuration to serve as a template and then to modify it as necessary for different devices. A typical workflow might be:

1. Use the NCM config editor to create a config on one device.
2. Call GET https://www.cradlepointecm.com/api/v2/configuration_managers/123/ to download the config from the device.
3. Edit the downloaded copy.
4. Call PUT https://www.cradlepointecm.com/api/v2/configuration_managers/456/ to upload the edited config to a different device.

PUT Example: Resume Sync

To restart the sync cycle on a suspended device after fixing its config:

> PUT https://www.cradlepointecm.com/api/v2/configuration_managers/2/?fields=suspended
> {
>     "suspended": false
> }
< 202 Accepted
< {
<    "suspended" : false
< }

This only works if a device is online. If the device is offline, it stays suspended.

PUT Example: Clearing the Config

To wipe the individual config back to defaults, just PUT an empty diff:

> PUT https://www.cradlepointecm.com/api/v2/configuration_managers/123/?fields=configuration
> {
>     "configuration": [{}, []]
> }
< 202 Accepted
< {
<     "configuration": [{}, []]
< }

PUT Example: Manually Suspend Sync

You can force NCM to stop syncing a device via the API. Why would you stop the syncing of a device? You might not want devices to sync until you are done making and testing configuration changes on a test device. Or you might only want to sync devices at certain times.

> PUT https://www.cradlepointecm.com/api/v2/configuration_managers/2/?fields=suspended
> {
>     "suspended": true
> }
< 202 Accepted
< {
<     "suspended" : true
< }

PATCH

PATCH also changes the config. The difference between PUT and PATCH is in how they treat the parts of the config that are not mentioned in the request. PUT replaces anything not mentioned with nothing (ie, resets it back to defaults). PATCH leaves it alone.

For example, the following PUT call resets the entire individual config back to defaults:

PUT https://www.cradlepointecm.com/api/v2/configuration_managers/123/
{"configuration": [{}, []]}

And this will do nothing at all:

PATCH https://www.cradlepointecm.com/api/v2/configuration_managers/123/
{"configuration": [{}, []]}

PATCH is the operation to use when you want to adjust an existing config. PUT is what you should use to replace an existing config.

Note that you can't remove anything with PATCH, you can only add or update changes.

HTTP status codes:

202 Accepted            # Success
400 Bad Request         # Invalid config request
401 Unauthorized        # Incorrect or missing X-ECM-API-ID or X-ECM-API-KEY headers
403 Forbidden           # Invalid URL or resource not visible
405 Method Not Allowed  # URL did not include an /<id>/ in the path
409 Conflict            # Invalid API request

Like PUT, PATCH cannot operate on more than one configuration manager at a time. For this reason it also does not support the URL options for filtering or paging.

Also like PUT, it will return a 400 Bad Request if it detects an invalid config.

Unlike PUT, PATCH never returns a payload in its reply. The fields URL option is therefore meaningless to PATCH.

See here for an explanation of the example format.

PATCH Example: Set Primary LAN IP Address

Change the IP address of the Primary LAN to 192.168.30.1, leaving the other parts of the diff the same. Note the reply contains the entire diff; in this example it shows that PUT Example 1 to add a third LAN was already done, and the PATCH is an incremental change on top of that:

> PATCH https://www.cradlepointecm.com/api/v2/configuration_managers/1234/
> {
>     "configuration": [
>         {
>             "lan": {
>                 "00000000-0d93-319d-8220-4a1fb0372b51": {
>                     "_id_": "00000000-0d93-319d-8220-4a1fb0372b51",
>                     "ip_address": "192.168.30.1"
>                 }
>             }
>         },
>         []
>     ]
> }
< 202 Accepted

This example uses the Primary LAN's _id_ value as the key, and whenever you do that you also must include the _id_ field itself as part of the request, or you will get a strange validation error:

{
   "exception" : {
      "message" : "invalid literal for int() with base 10: '00000000-0d93-319d-8220-4a1fb0372b51'",
      "type" : "error"
   },
   "errors" : [
      {
         "path" : "https://www.cradlepointecm.com/api/v2/configuration_managers/2/"
      }
   ]
}

PATCH Example: Insert A LAN

PATCH supports inserting new array elements:

{
    "configuration": [
        {
            "lan": {
                "00000002-2a38-3724-a6fa-02dfdfbc129e": {
                    "_id_": "00000002-2a38-3724-a6fa-02dfdfbc129e",
                    "ip_address": "192.168.40.1",
                    "name": "Gamma",
                    "netmask": "255.255.255.0",
                    "dhcpd": {
                        "enabled": true
                    },
                    "devices": []
                }
            }
        },
        []
    ]
}

Group Configurations

A group's config is part of the groups resource:

> GET https://www.cradlepointecm.com/api/v2/groups/35/?fields=configuration
< 200 Ok
< {
<    "configuration" : [
<       {
<          "system" : {
<             "logging" : {
<                "level" : "debug"
<             }
<          },
<          "webfilter" : {
<             "proxy" : {
<                "https_filtering" : true
<             }
<          }
<       },
<       []
<    ]
< }

GET, PUT and PATCH work the same for groups as for configuration_managers.

Use Cases

Below are some ways people have used the API.

Get the pending config on a particular device

If the configuration_manager ID is known:

GET https://www.cradlepointecm.com/api/v2/configuration_managers/1106/?field=pending

Otherwise query the configuration_managers by device ID. The result will be a list of one element, such as:

> GET https://www.cradlepointecm.com/api/v2/configuration_managers/1106/?field=pending
< 200 Ok
< {
<    "data" : [
<       {
<          "pending" : [
<             {
<                "system" : {
<                   "logging" : {
<                      "level" : "debug"
<                   }
<                },
<                "ecm" : {
<                   "config_version" : 9
<                }
<             },
<             []
<          ]
<       }
<    ],
<    "meta" : {
<       "offset" : 0,
<       "previous" : null,
<       "next" : null,
<       "limit" : 20
<    }
< }

Get the actual config on all devices on a nightly basis

Page through the configuration_managers using limit and offset. To associate each result with its device, ask for some unique identifier such as the router.id or router.mac or router.name:

GET https://www.cradlepointecm.com/api/v2/configuration_managers/?fields=actual,router.id,router.mac,router.name&limit=200&offset=0
GET https://www.cradlepointecm.com/api/v2/configuration_managers/?fields=actual,router.id,router.mac,router.name&limit=200&offset=201
... etc ...
GET https://www.cradlepointecm.com/api/v2/configuration_managers/?fields=actual,router.id,router.mac,router.name&limit=200&offset=12000

Read/modify/write a "golden" config

GET https://www.cradlepointecm.com/api/v2/groups/123/?fields=configuration
# modify it for group 456
PUT https://www.cradlepointecm.com/api/v2/groups/456/
# modify it for group 789
PUT https://www.cradlepointecm.com/api/v2/groups/789/
... etc ...

Change the WiFi SSID and WPA2/PSK Passkey On Specific Routers

PUT and PATCH require the URL of the configuration_managers ID endpoint and do not support filtering by router.id (or router.mac, router.name, etc):

> PUT https://www.cradlepointecm.com/api/v2/configuration_managers/1234/
> PATCH https://www.cradlepointecm.com/api/v2/configuration_managers/1234/
> {
>     "configuration": [
>         {
>             "wlan": {
>                 "radio": {
>                     "0": {
>                         "bss": {
>                              "0": {
>                                "ssid": "MBR1400-8c1",
>                                "wpapsk": "t311-n00ne"
>                               }
>                          }
>                      }
>                  }
>              }
>         },
>         []
>     ]
> }
< 202 Accepted

Add User

This and the following examples work the same way with PATCH or PUT as all the previous examples. For brevity, only the payload is shown.

{
    "configuration": [
        {
            "system": {
                "pci_dss": true,
                "users": {
                    "1": {
                        "group": "admin",
                        "password": "SuperDuper1",
                        "username": "super"
                    }
                }
            }
        },
        []
    ]
}

Static IP for Ethernet WAN using WAN rule

Configuring the static IP on the Ethernet WAN device requires setting the ip_override section of its corresponding WAN rule. The WAN rules changed somewhat with firmware version 6.0. The wan.rules path was replaced with wan.rules2, and the _id_ of the rule dealing with Ethernet WAN also changed as shown in the examples that follow.

5.0 <= Firmware < 6.0

{
    "configuration": [
        {
            "wan": {
                "rules": {
                    "00000001-dea3-3ccd-a78d-e0196084396f": {
                        "_id_": "00000001-dea3-3ccd-a78d-e0196084396f",
                        "ip_mode": "static",
                        "static": {
                            "dns": {
                                "0": {
                                    "ip_address": "172.21.21.50"
                                },
                                "1": {}
                            },
                            "gateway": "172.19.8.1",
                            "ip_address": "172.19.9.30",
                            "netmask": "255.255.252.0"
                        }
                    }
                }
            }
        },
        []
    ]
}

Firmware >= 6.0

Change rules to rules2 and change the _id_ field and key. The dns section is not required like it is in older versions, which will accept the config without DNS but may fail to connect, resulting in a config rollback.

{
    "configuration": [
        {
            "wan": {
                "rules2": {
                    "00000000-a81d-3590-93ca-8b1fcfeb8e14": {
                        "_id_": "00000000-a81d-3590-93ca-8b1fcfeb8e14",
                        "ip_mode": "static",
                        "static": {
                            "ip_address": "172.19.9.30",
                            "netmask": "255.255.252.0"
                        }
                    }
                }
            }
        },
        []
    ]
}

Setting the APN for modem using LTE defaults WAN rule

The APN must be set in the WAN rule corresponding to the modem it is for. For example, to set it for an LTE modem, use the WAN rule with _id_ "00000002-dea3-3ccd-a78d-e0196084396f":

5.0 <= Firmware < 6.0

{
    "configuration": [
        {
            "wan": {
                "rules": {
                    "00000002-dea3-3ccd-a78d-e0196084396f": {
                        "_id_": "00000002-dea3-3ccd-a78d-e0196084396f",
                        "modem": {
                            "apn_mode": "manual",
                            "manual_apn": "myapn"
                        }
                    }
                }
            }
        },
        []
    ]
}

Firmware >= 6.0

Change rules to rules2 and change the _id_ field and key.

{
    "configuration": [
        {
            "wan": {
                "rules2": {
                    "00000002-a81d-3590-93ca-8b1fcfeb8e14": {
                        "_id_": "00000002-a81d-3590-93ca-8b1fcfeb8e14",
                        "modem": {
                            "apn_mode": "manual",
                            "manual_apn": "myapn"
                        }
                    }
                }
            }
        },
        []
    ]
}

Appendix

Format of Examples

There are many Rest API clients available on the web or as browser plugins. They all differ slightly but provide the same common elements of method, headers, URL, payload, and status code. Rather than showing the syntax for a particular tool, this document uses the following format for all examples.

First, examples appear in monospace font. The first character of each line is either > or < and indicates the direction of travel, either client-to-server or server-to-client, respectively:

> = client to server
< = server to client

The first line is always the method and URL. If there is data to be sent (as in PUT and PATCH), this appears on the following lines going in the same direction. The reply appears on subsequent lines, beginning with the status code and followed by the reply payload (if any). Here's an annotated example, with lines numbered for discussion:

1 > GET https://www.cradlepointecm.com/api/v2/configuration_managers/1/?fields=version_number
2 < 200 Ok
3 < {
4 <     "version_number" : 19,
5 < }

Line 1 shows the method (GET) and full URL (https://www.cradlepointecm.com/api/v2/configuration_managers/1/?fields=version_number) sent from the client to the server to initiate the request. In this example the URL is asking for a specific object (with ID 1), and specifying that it only wants to see the version_number field (this is known as a "partial result").

Line 2 shows the status code from the server as 200 Ok.

Lines 3-5 are the payload of the reply from the server. For readability, the examples always show the payloads as JSON formatted with line breaks and indentations. Not all clients format the reply like this (curl won't, for example, and neither will most browsers unless you install a plugin). The payload from the server will actually be all on one line with no indentation. The meaning is the same.

The examples do not show the headers required for authentication or content-type, but they are necessary. As described in the general API v2 documentation (the Sample Code section is most succinct), all requests to the API must provide a header each for X-ECM-API-ID, X-ECM-API-KEY, X-CP-API-ID and X-CP-API-KEY to authenticate the client. Also, PUT and PATCH requests require a Content-Type header.

_id_ Fields

Many parts of the device configuration are composed of arrays. Most of these lists are treated more like sets than like arrays, where the order of the elements does not matter and elements must be unique from one another in some way. Order does not matter; as long as nothing inserts or removes elements the order remains stable.

Some of these arrays are pre-populated with entries by default. For example, if you factory reset most devices (but not all!) you will find that they have two LAN entries and maybe five WAN rules.

In a config diff arrays are always presented as dictionaries. Historically (prior to 5.0) the keys were always string numerals representing the index of the elements. For example:

{
    "lan": {
        "1" : {
            "ip_address" : "192.168.30.1",
            "name" : "Office LAN"
        }
    }
}

This refers to the LAN at index 1 which would be the second LAN. In most devices that would be the Guest LAN. But not necessarily, if the config has changed from the default. This might be a third LAN inserted before the Guest LAN. It might even be the Primary LAN, if the Guest LAN were somehow re-ordered to come first. This is an aliasing problem, where it is sometimes impossible to tell which element a config diff is referring to just by looking at it. The problem becomes worse when NCM begins to layer configs.

The solution, introduced in firmware version 5.0, was to add a unique _id_ field to the elements of lists that have default values. The _id_ is a UUID. The lists that support them include the lan, wan.rules and various others, depending on the firmware version and product.

The following example diff illustrates this by referring to the primary LAN by it's _id_: "00000000-0d93-319d-8220-4a1fb0372b51".

{
    "lan": {
        "00000000-0d93-319d-8220-4a1fb0372b51" : {
            "ip_address" : "192.168.30.1",
            "_id_" : "00000000-0d93-319d-8220-4a1fb0372b51",
            "name" : "LAN0"
        }
    }
}

For firmware versions 5.0 and greater this is the unambiguous way to refer to these array elements.

For firmware versions prior to 5.0, these UUID fields are not supported by any arrays, so you must use string numerals to reference their position in the array. The first position is always "0".

The default elements of these lists (ie, those which populate the list after a factory reset) all have pre-assigned _id_ field values. When adding a new element to such a list, you must provide your own UUID value.

Here's a list of arrays with elements that use the _id_ field from a recent firmware build (6.1.0) as of this writing:

 asavie.tunnels
 certmgmt.certs
 dns.dnsmasq_options
 gre.tunnels
 identities.ip
 identities.mac
 identities.port
 lan
 openvpn.tunnels
 routing.access_list
 routing.bgp.access_list
 routing.bgp.community_list
 routing.prefix_list
 routing.route_map
 routing.tables
 security.app_sets
 security.ips.cat_cfg
 security.ips.sig_cfg
 security.zfw.filter_policies
 security.zfw.forwardings
 security.zfw.zones
 split_dns.domain_lists
 split_dns.servers
 system.gps.connections
 vpn.tunnels
 wan.rules
 wan.rules2

Firmware Versioning And DTDs

What constitutes a valid configuration? It depends on the firmware version and product. Every version of firmware has a Document Type Definition (DTD) that specifies the configuration-tree structure, the types of the elements, any limits on the range of values of elements, and whether an element must be specified or can be left blank. If a configuration does not conform to the DTD it is invalid.

NCM checks for valid configs in the API by checking them against the DTD. But even if a config conforms to the DTD it can still be invalid. The devices check for dynamic constraints which can't be expressed in the DTD and may reject a config from NCM because one of these checks fails.

For example, currently all devices have a check that

if `firewall.remote_admin.enabled` is `true` then either
    `firewall.remote_admin.secure_only` must be `true` or
    `firewall.remote_admin.port` must be provided.

So even though this conforms to the DTD and would be accepted by NCM, the device would reject it:

{
    "firewall": {
        "remote_admin": {
            "enabled": true,
            "secure_only": false
        }
    }
}

The DTD can change from one firmware version to another. This changes what constitutes a valid config. When a device's target firmware changes, NCM automatically attempts to migrate its configuration to make it compatible with the new version.

The DTD specifies a default value for many fields, including all required fields. As noted elsewhere, it also specifies default elements for some arrays such as lan, wan.rules and firewall.zfw.filter_policies. The default elements can be altered or removed. If they are, a factory reset of the device restores them. In NCM, clearing configs has a similar effect.

Suspended Sync

If NCM tries to sync a device to an invalid config, the device rejects it. NCM stops trying to sync the device and marks it as "suspended", as shown in the config_status field of the device's endpoint (eg, https://www.cradlepointecm.com/api/v2/routers/<router-id>).

To understand why a device was suspended due to an invalid config, check the device's Configuration Rejected alert. This alert contains details about why the device rejected the config. The alert information typically references the field(s) that failed their dynamic validation checks. You can access a device's alerts through the NCM ALERTS page or via the alerts endpoint.

Once the problem is ascertained, the configuration should be changed to remove the error.

Finally, to resume sync from the API, do a PUT with the suspended field set to False:

PUT https://www.cradlepointecm.com/api/v2/configuration_managers/1234/
{
    "suspended": false
}

Supported Products

All currently available products are referred to as Series 3 products. Older series 2 products which are managed by NCM also have configuration_managers. However, their configuration format is different from series 3, and the fields and values are different. Nonetheless, one can still use this API to try and configure series 2 routers managed in NCM.

Diffs

A configuration diff describes how the configuration differs from the default for that firmware version. It is a list of two elements. The first element is called the update dictionary. The second element is called the removal list.

A diff is like a UNIX patch. It can be applied to an existing configuration. When applied, every path in the removals list is removed in the specified order. Then, every key/value pair in the update dictionary is applied. The update will try to maintain existing elements, and only update exactly what is specified.

For example, suppose a configuration looks like this:

{
    "a": {
        "b": 1,
        "c": 2
    },
    "d": {
        "e": "hi",
        "f": "there"
    }
}

And the diff being applied looks like this:

[
    {
        "a": {
            "d": 4,
            "c": 3
        }
    },
    [
        ["d", "e"]
    ]
]

When applied, the diff will first remove element d.e, then, in no particular order, it will change element a.c and insert element a.d. Element a.b and d.f will be left as they are:

{
    "a": {
        "d": 4,
        "c": 3,
        "b": 1
    },
    "d": {
        "f": "there"
    }
}

If a path in the removal list does not exist in the configuration, this is an error. If an element in the update dictionary is not described by the firmware's Document Type Definition (DTD), or if it is of the wrong type, that is also an error.

An empty configuration diff looks like this:

[{}, []]

Group / Indie Layering

Suppose the device is put into a group, and the group has a configuration like this:

# Group config
{
    "a": {
        "b": 1
        "c": 2
    }
}

If you GET the device's configuration, it will look exactly like that. Now suppose you PATCH the following to the device's configuration:

# Patch to config
{
    "a": {
        "b": 3,
        "d": 4
    }
}

NCM will save this as the device's individual configuration and update the target by layering it over the group. Now if you GET the device's configuration it will look like this:

# Target config
{
    "a": {
        "b": 3,
        "c": 2,
        "d": 4
    }
}

NCM changed a.b and inserted a.d. It left a.c alone, because the diff didn't mention it.

What would happen if you then changed your mind and PUT with an empty config to the device’s configuration endpoint? NCM would clear the individual configuration, but the group configuration would stay the same, so the device's target configuration would go back to just being the group configuration:

# Target config if indie cleared
{
    "a": {
        "b": 1
        "c": 2
    }
}

What if instead you removed the device from the group? Then only the individual configuration would remain:

# Target config if removed from group
{
    "a": {
        "b": 3,
        "d": 4
    }
}

NCM removed a.c from the target configuration, because a.c came from the group configuration.

Passwords

If you GET a config that has non-default passwords, the values are not shown. Instead, you see "*":

> GET https://www.cradlepointecm.com/api/v2/configuration_managers/2/?fields=configuration
< 200 Ok
< {
<    "configuration" : [
<       {
<          "wlan" : {
<             "radio" : {
<                "0" : {
<                   "bss" : {
<                      "0" : {
<                         "wpapsk" : "*"
<                      }
<                   }
<                }
<             }
<          }
<       },
<       []
<    ]
< }

You can still set passwords through the API by sending them as cleartext:

PATCH https://www.cradlepointecm.com/api/v2/configuration_managers/
> {
>    "configuration" : [
>       {
>          "wlan" : {
>             "radio" : {
>                "0" : {
>                   "bss" : {
>                      "0" : {
>                         "radius0nasid" : null,
>                         "wpapsk" : "2secret4Usorry"
>                      }
>                   }
>                }
>             }
>          }
>       },
>       []
>    ]
> }
< 202 Accepted

They will be automatically encrypted.

Validation Errors

An "invalid path" error is reported anytime a diff refers to something that does not exist in the DTD. It does not matter if the reference is in the updates or the removals. For instance, both updates and removals are invalid here:

[
    {
        "foo": "bar"
    },
    [
        ["baz", 6]
    ]
]

Other errors are due to a wrong type or value:

empty dict                                    # array can't be an empty dictionary
not a dict                                    # struct must be dictionary
invalid id                                    # _id_ not a UUID
not a string
url must have "http://" or "https://" prefix
invalid url
invalid ip address
invalid ip address or dns name
not a float type
invalid mac address
invalid ipv6 address
too large
negative invalid                              # ipv6_prefixlen must be >= 0
not an integer
invalid subnet mask
invalid ipv4 address
invalid ip address
invalid option                                # select value must be from the list
too large (max=n)
number precision exceeded (max bits=n)        # u8, s8, u16, etc only allow 8 or 16 bits, etc
too small(min=n)
not a boolean
bad array index
not a list or dict                            # array must be a dict or list
too short (min length=n)
incorrect padding                             # encrypted password is corrupted
too long (max length=n)
invalid dns name

Config Rollback

Sometimes the device will validate a config and apply it, but then be unable to connect the WAN with the new settings. To protect against this situation, all firmware versions support a config rollback feature. After applying a config from NCM, if the device cannot contact NCM within 15 minutes it "undoes" the config change and reverts to the previous working version. When it reconnects to NCM after a rollback it informs NCM and config sync on the device is suspended.

Differences From v1

Sample v1 resource:

"account" : "/api/v1/accounts/1/",
"actual" : "/api/v1/configuration_managers/2/actual/",
"configuration" : "/api/v1/configuration_managers/2/configuration/",
"id" : "2",
"lock" : "unlocked",
"pending" : "/api/v1/configuration_managers/2/pending/",
"pending_patch" : null,
"resource_uri" : "/api/v1/configuration_managers/2/",
"router" : "/api/v1/routers/2/",
"suspended" : false,
"synched" : true,
"target" : "/api/v1/configuration_managers/2/target/",
"version_number" : 83

Sample v2 resource:

"account" : "https://www.cradlepointecm.com/api/v2/accounts/1/",
"actual" : [{}, []],
"configuration" : [{}, []],
"id" : "1108",
"pending" : [{}, []],
"resource_url" : "https://www.cradlepointecm.com/api/v2/configuration_managers/1108/",
"router" : "https://www.cradlepointecm.com/api/v2/routers/1108/",
"suspended" : false,
"synched" : true,
"target" : [{}, []],
"version_number" : 0

*Notable differences:

• The fields which contain configuration diffs (configuration, actual, target and pending) are no longer URLs. They are contained right in the resource.
• The pending_patch field has been removed. The same information is available in pending.
• resource_uri has been renamed resource_url and is a full URL.
• The account and router fields are full URLs.
• The routers resource does not have a URL link to the corresponding configuration_managers. However, you can still find the corresponding configuration_manager by querying as in "Change the WiFi SSID and WPA2/PSK Passkey On Specific Routers" example

Zscaler Configurations

Zscaler is a cloud-based filtering and security policy application that can be configured on Cradlepoint devices. More details can be found at Zscaler Internet Security

Zscaler example code

###Zscale Username / Password
{
   "configuration": [
      {
      "dns": {"force_redir": true},
      "webfilter": {
         "cloudservice": "zsis",
		 "zsis": {
		 "dyndns": {"password": "password1", "user_name": "username1"}
       }
       },
       []
   ]
}

Hardware Requirements

• Cradlepoint AER 2100 or MBR1400v2
• ZScaler service account

Firmware Version

• The firmware version used for the preparation of this document was NCOS 5.0.0.