v1/configs
Use the v1/configs API to create, update, or retrieve managed device configurations.
A managed configuration is a set of rules that define how devices are configured and how they are kept in compliance. A managed configuration can be applied to groups of devices. The configuration is applied to all devices in the group that match the type and vendor ID specified in the configuration.
A managed configuration can be applied to multiple groups, but a group can have only one active (enabled) configuration for a given type and vendor ID.
Scanning occurs when a device in the group is first connected to Remote Manager and when the configuration is scheduled to scan the device. A scan can be done manually and other events in the system can also trigger a scan. See the scan_frequency field for more information about conditions that trigger a scan.
See the Automations and Firmware APIs for more information about creating and managing automations and firmware.
URI
https://<hostname>/ws/v1/configs
Formats
HTTP method | Format | Description | Parameters |
---|---|---|---|
GET | /ws/v1/configs | Get a summary of the /ws/v1/configs APIs. | |
GET | /ws/v1/configs/compliance | Get a summary of configuration compliance. | group orderby cursor size query |
GET | /ws/v1/configs/compliance/{id} | Get configuration compliance for a device. | |
GET, PUT, DELETE | /ws/v1/configs/inventory/{id}/settings | Get, update, or delete settings for a managed configuration. | |
GET, PUT, DELETE | /ws/v1/configs/inventory/{id}/settings/device | Get, update, or delete site-specific managed configuration settings for a device or all devices. | device_id, device_name |
GET, POST | /ws/v1/configs/inventory/{id}/settings/device/bulk | Get or update site-specific managed configuration settings for all devices. | |
GET, POST | /ws/v1/configs/inventory | Get or create a managed configuration. | group orderby cursor size query |
GET, PUT, DELETE | /ws/v1/configs/inventory/{id} | Get, update, or delete a managed configuration. | |
GET | /ws/v1/configs/scan/bulk/history/{device_id} | Get the managed configuration scan history for a device in CSV format. | |
GET, DELETE | /ws/v1/configs/scan/history/{device_id} | Get or clear the managed configuration scan history for a device. | cursor size |
POST | /ws/v1/configs/scan_now | Initiate a configuration scan. |
Configuration JSON Object
An example configuration is shown below.
{
"alert": true,
"created": "2023-06-21T17:39:20.290Z",
"customer_id": 57639,
"description": "Configuration for storefront cellular backup routers",
"device_fileset": "configuration-6748-fileset",
"enabled": true,
"firmware_version": "23.6.1.46",
"groups": [
"Stores"
],
"id": 6415,
"images": [
{
"name": "Network Safety Scanner",
"version": "1.0.0"
}
],
"last_scan": "2023-06-22T08:00:03.233Z",
"last_update": "2023-06-21T17:43:18.163Z",
"maintenance_window_handling": "cancel",
"name": "Store Routers",
"on_remediate": {
"automation_name": "Set Update Tags",
"reboot": true
},
"on_scan": {
"automation_name": "Start LEDs Flashing"
},
"on_success": {
"automation_name": "Stop LEDs Flashing"
},
"remediate": true,
"scan_files": true,
"scan_frequency": "daily",
"scan_python": false,
"scan_settings": true,
"type": "Digi TX64",
"vendor_id": 4261412874
}
Configuration Fields
alert
Indicates whether the managed configuration sends alerts when devices are detected as not in compliance.
created
Timestamp that indicates when the managed configuration was created.
customer_id
Unique customer ID for the Remote Manager customer.
description
Optional description of the managed configuration.
device_fileset
The name of the fileset used by the configuration to load files on to the scanned devices. See the Files API for more information about creating, uploading and removing files from filesets.
enabled
Boolean that indicates whether the managed configuration is enabled.
firmware_version
Firmware version for the managed configuration.
flash_firmware_policy
This value is only valid if the configuration applies to XBee devices, more specifically, devices with the XBee vendor ID (0xFE000006).
Whether the configuration should flash the firmware or not. It has three possible values:
- ‘always’: always flash firmware.
- ‘if_different’: flash firmware only if the device’s firmware version is different from the one in the
xbee_profile
. - ’never’: never flash firmware.
groups
The list of groups that the managed configuration applies to. The configuration applies to all devices matching the type field in the groups specified.
id
Unique ID for the managed configuration.
images
The list of Digi Accelerated Linux (DAL) images that describe Digi containers that should be initialized on the system. See the images fields below for more information.
last_scan
Timestamp that indicates when the managed configuration last scanned any devices.
last_update
Timestamp that indicates when the managed configuration was last updated.
maintenance_window_handling
Indicates how the managed configuration handles devices not being in maintenance windows. Can be one of
- ‘allow’ - Allow the configuration scan to run normally for the devices that are currently in service (not in a maintenance window)
- ‘reject’ - Reject the configuration scan of the device immediately at the beginning. If the device transitions to in-service (not in a maintenance window) during the scan, allow the scan to continue.
- ‘cancel’ - Cancel the configuration scan at any time when the device transitions to in-service during the scan.
modem_firmware_versions
The list of Modem Firmware information for the managed configuration.
name
Name of the managed configuration.
on_remediate
Set of actions to take if the scan detects a device that is not in compliance and makes it compliant. See the On Remediate Actions section below for more information.
on_scan
The set of actions to take at the beginning of a configuration scan for a device. See the On Scan Actions section below for more information.
on_success
The set of actions to take after a configuration scan for a device is successful. A successful scan occurs if the device is already in compliance or if the scan successfully makes the device compliant. See the On Success Actions section below for more information.
remediate
Boolean that indicates if the configuration should remediate (bring into compliance) devices that are detected as non-compliant.
scan_files
Boolean that indicates the configuration should scan files in the device fileset for compliance.
scan_frequency
The frequency at which the configuration scans devices for compliance.
- manual - Scanning happens manually or if new devices or existing devices move into groups managed by the configuration.
- daily - Approximately every 24 hours
- weekly - Approximately every week
- monthly - Approximately every month
If the value is ‘manual’ or any other value, devices are scanned by the system under these conditions:
- The user selects the ‘Scan Now’ option for a device in the UI or uses the scan_now API
- A device is first connected identified in a group managed by a configuration
- A device is moved to a new group managed by a different configuration than the original
If the value is ‘daily’, ‘weekly’, or ‘monthly’, devices are also scanned by the system under these conditions:
- By the configurations schedule.
- The device transitions from in-service into maintenance mode
- The device transitions from debug mode to not in debug mode
- The devices name changes and there are site-specific settings associated with the new or old name
scan_python
Boolean that indicates if python is not installed on the Digi Accelerated Linux (DAL) device that the default python for the target firmware version should be installed and made available.
scan_settings
Boolean that indicates that the configuration should scan device settings for compliance
type
Device type for devices that are managed by configuration.
vendor_id
Unique vendor ID for devices that are managed by a configuration.
xbee_profile
This value is only valid if the configuration applies to XBee devices, more specifically, devices with the XBee vendor ID (0xFE000006).
The name of the fileset used by the configuration to load the XBee profile(s) on devices that support XBee profiles. See the Files API for more information about creating, uploading and removing files from filesets. The XBee profile is snapshot of a specific radio firmware configuration, including firmware, setting values, file system and other configuration information.
Images Fields
The images
field in the configuration is a list of Digi Accelerated Linux (DAL) images that describe Digi containers that should be scanned on the device.
For example:
{
"images": [
{
"name": "digi-iot-dal",
"version": "1.0.0"
}
]
}
name
The name of the Digi Containers image to use.
version
The optional version of the Digi Containers image to use.
Modem Firmware Fields
The list that describes which firmware should be installed for modems on the target devices. Some modem’s require firmware specific to the carrier, other modems support generic firmware across carriers. You can use the Remote Manager firmware UI or API to get a list of supported firmware for a modem.
For example:
{
"modem_firmware_versions": [
{
"model": "EG25_G",
"name": "modem",
"versions": [
{
"version": "EG25GGBR07A07M2G_01.001.01.001"
}
]
}
]
}
or
{
"modem_firmware_versions": [
{
"model": "EM7411",
"name": "wwan1",
"versions": [
{
"carrier": "GENERIC",
"version": "01.14.13.00_GENERIC_002.048_000"
},
{
"carrier": "ATT",
"version": "01.14.13.00_ATT_002.062_000"
}
]
},
{
"model": "EM7411",
"name": "wwan2",
"versions": [
{
"carrier": "GENERIC",
"version": "01.14.13.00_GENERIC_002.048_000"
},
{
"carrier": "ATT",
"version": "01.14.13.00_ATT_002.062_000"
}
]
}
]
}
name
The name of the modem to apply the modem firmware on
model
The model of the modem matching the firmware to apply
versions
The list of objects with version
field and optional carrier
field of the firmware(s) to apply to the target modem.
On Remediate Action Fields
At the end of a configuration scan that detects a device that is not in compliance and makes it compliant you can reboot the device or run an automation. This step occurs before any On Success actions.
automation_name
The automation to run at the end of the scan that remediated the device. The scan waits for the automation to complete. If the automation fails the scan fails as well. The automation for the remediate action is run after the device is rebooted, if the reboot field is true.
reboot
Boolean that indicates if the device should be rebooted after the scan that remediated the device. The reboot occurs before any On Success actions. Note that a firmware update may also reboot the device, by specifying this field you can reboot again, later in the scan. For example, after the firmware update occurs, and the device reconnects, some configuration changes or installing applications or containers may require a reboot to take effect. The reboot occurs before any automation specified in the remediate action
On Scan Action Fields
At the start of a configuration scan you can run an automation. The automation could, for example, run a CLI command on the device to flash the LEDs so that you can identify the device in a rack or set a tag on the device to indicate an update is in progress.
automation_name
The automation to run at the beginning of the scan. The scan waits for the automation to complete. If the automation fails the scan fails as well.
On Successful Scan Action Fields
At the successful completion of a configuration scan you can run an automation. The automation could, for example, run a CLI command on the device to turn off the flasshing LEDs or set a tag on the device to indicate an update was completed. Successful completion occurs if the device is already in compliance or if the scan successfully makes the device compliant. This step occurs after any On Remediate actions.
automation_name
The automation to run at the successful completion of the scan. The scan waits for the automation to complete. If the automation fails the scan fails as well.