PLEASE NOTE: You must have Crimson version 3.2.1055 or newer installed.
APPLICABLE PRODUCTS
FlexEdge
Graphite Plus
Graphite/CR series device (requires SD card)
PRE-REQUISITES
Crimson 3.2.1055 or newer
FlexEdge, Graphite Plus, Graphite/CR series device with SD card installed
IN THIS ARTICLE (Mandatory)
Crimson’s Device Configuration consists of four types:
- Hardware Configuration
- System Configuration
- Device Personality
- User Configuration
In each of these configuration types, users are offered the ability to upload their configuration settings using the Crimson Windows application or the Runtime System Webserver via a JSON file. This feature is limited, however, in that users are required to upload a complete and valid configuration file including all configurable parameters for its relevant configuration type. For users who require that a change be made to a batch of devices, devices which could have different settings in other areas of the same configuration, this process can become rather redundant and tedious.
Patching (as it will be referred to in this document), aims to provide users with the opportunity to send the system only the exact parameters which need modified, ensuring that irrelevant settings are unchanged. With this feature, a single JSON configuration file can be used to modify settings of any number of devices. This document aims to describe the guidelines and best practices for utilizing this feature to update a device’s configuration.
Creating a Patch File
The process for creating a patch file is rather simple. The process can be summarized as; download the configuration where the properties you want to patch are located, append a “p” to the “atype” key object defined at the beginning of the configuration file, delete all irrelevant objects and modify the objects which the user wants to patch. I will break these steps down into more detail now.
Download Configuration
From the Crimson configuration desktop tool, or the Runtime System Webserver, download the desired device configuration in JSON format from the Utilities page.
Identify File as Patch
In the user’s preferred text editor, append the letter ‘p’ to the value of the “atype” object in the configuration file. This appended ‘p’ will identify the configuration file on the system as a patch file.
{
"atype": "sp",
"net": {
"faces": {
"eth1": {
"address": "192.168.222.232"
}
}
}
}
Modify Configuration Objects
Next, the user should strip out all irrelevant JSON objects present in the configuration file except for the object the user wants to modify. It is imperative that the paths to these objects as they existed in the downloaded configuration remain unchanged. This path is how the objects to be modified will be identified. The image above is demonstrating what patching the “eth1” interface’s IP address looks like.
Some configuration properties utilize arrays to structure data. In order to modify single array elements, the user needs to explicitly identify which array index they want to modify.
Unnamed Array Indexes
All existing array objects in a configuration can be identified with a numeric representation of where it is stored in the array. This is possible by adding an “index” key to the array object. The “index” key can exist anywhere inside of the array object, and requires only that a valid integer be entered as the value. The desired objects to be modified are the only other required pieces of data within the array object.
{
"atype": "sp",
"services": {
"tlsServer": {
"cons": [
{
"index": 3,
"locip": "192.168.1.10",
"remhost": "192.168.1.20"
}
]
}
}
}
In the provided example, this patch to the system configuration will modify the local and remote IP addresses of the third entry of the TLS Server connections array.
Note that the indexes are not indexed beginning at 0 and rather begin at 1. The purpose of this is to match the entry number as it displays in the tables of the configuration tool and the system webserver. Therefore, 0 should never be an array entry.
Named Array Indexes
Some, but not all, array objects have a “name” property as a unique identifier for the element. Users can utilize this “name” property to identify which array object should be updated. Array objects identified in this fashion have the advantage of existing in different locations within an array across multiple devices. Therefore, a difference in array positioning will not limit a patch of this type across the devices. Users cannot modify the “name” value of an array object. If a user wants to change the name of an array object, they will be required to delete the object and add it once more with a different name. This functionality will be reviewed later in this document.
{
"atype": "sp",
"net": {
"firewall": {
"lists": {
"wlist": [
{
"ip": "192.168.1.20",
"name": "Test"
}
]
}
}
}
}
Patching Multiple Configuration Types
With this feature, the user has the option to patch objects across different configuration files in the same patch file. For example, a user that wants to change the username of a guest account in the user configuration, as well as modify a whitelist entry in the system configuration, can load both patches in the same file. To accomplish this, format the patch file in the same way as specified by a “devcon.json” configuration file. Each of the respective configuration patches follow the same format as previously discussed.
{
"sconfig": {
"atype": "sp",
"net": {
"firewall": {
"lists": {
"wlist": [
{
"ip": "192.168.80.125",
"name": "TestName"
}
]
}
}
}
},
"uconfig": {
"atype": "up",
"set": {
"users": [
{
"name": "Guest",
"user": "Guest5"
}
]
}
}
}
This example demonstrates the exact patching scenario described earlier.
Adding and Deleting Array Objects
The patching feature not only provides the ability to modify existing configuration objects, but also provides the ability to add and delete specific elements within the configuration file. This functionality specifically extends to array objects only. Identifying an add or delete action is accomplished with the “paction” key inside of the array element.
Adding Array Objects
To add an array object, users can utilize the “add” value within the object they want to add. Adding an array object will append it to the end of the array, and cannot be inserted into a specific index.
It is recommended that an array object which will be added or deleted contain all properties present for an element of a particular type, with a corresponding value for each property. As with the “index” key that was discussed previously, the “paction” key can exist anywhere within the array object.
{
"atype": "sp",
"net": {
"firewall": {
"lists": {
"blist": [
{
"ip": "10.10.10.200",
"key": "100",
"mask": "255.255.255.128",
"paction": “add”
}
],
"wlist": [
{
"paction": “add”,
"ip": "192.168.130.99",
"key": "100",
"mask": "255.255.255.255",
"name": "TestAdd"
}
]
}
}
}
}
Deleting Array Objects
To delete an array object, the user is required to utilize the “delete” value within the array object, along with the named or unnamed index of the object they want to delete.
{
"atype": "sp",
"net": {
"firewall": {
"lists": {
"wlist": [
{
"index": 3,
"paction": “delete”
},
{
"name": "TestDelete",
"paction": “delete”
}
]
}
}
}
}
Appendix
- For patching to work on a Graphite/CR series device, a memory card is required for the patch file to be received. This is consistent with traditional system update methods with JSON files that already exists.
- Performing “paction” commands in a synchronous nature will update objects as they exist in the array before the action was performed, and their indices will not be updated until the entire patch is completed. This means an attempt to delete “index”: 2 and proceeding with an attempt to modify “index”: 2 will delete the object but fail to update what would have been “index”: 3, as “index”: 3 does not become “index”: 2 until after the entire patch is completed.
© HMS Networks AB 2025