Updating Router Card Firmware

Introduction

The Captive Server manages firmware updates for the Xaptum Router Card. To accomodate customer scheduling needs, the Captive Server has flexible scheduling capabilities.

The Xaptum engineering team will make the new firmware release available to the ENF. At that point, the customer follows three steps to install the firmware.

  • Create a schedule for the installation.
  • Create a firmware-update task.
  • Assign the firmware-update task to a device profile.

Before applying any update, the Captive Server will check to ensure that the currently running firmware is older than the requested update.

Prerequisites

  • enfcli needs to be installed. For help, see the Getting Started Tutorial
  • User has DOMAIN_ADMIN account
  • Commands are issued from enfcli
    > enfcli --host <client-domain>.xaptum.io --user <admin@account>
    

Create an Installation Schedule

The Captive Server scheduling is defined in a JSON file and is similar to a Unix cron schedule. The user defines the year, month, day of the month, hour, minute, and day of the week for the schedule to become active. The installation schedule has two additional fields: the domain and a description. Schedules only apply to a single domain – if the same timing is desired for a different domain, you must create a new schedule. Note that in the installation schedule, the domain field may refer to a /48 domain or a /64 network.

  1. Using your favorite text editor, create a schedule JSON file that looks like:
    {
     "name" : "Weekend_update",
     "domain" : "2607:8F80:8080:0009::/64",
     "times" : [
         {
             "minute" : "*",
             "hour" : "23,0-2",
             "day_of_month" : "*",
             "month" : "*",
             "year" : "*",
             "day_of_week" : "0"
         },
         {
             "minute" : "*",
             "hour" : "23",
             "day_of_month" : "*",
             "month" : "*",
             "year" : "*",
             "day_of_week" : "6"
         },
         {
             "minute" : "*",
             "hour" : "0-2",
             "day_of_month" : "*",
             "month" : "*",
             "year" : "*",
             "day_of_week" : "1"
         }
     ]
    }
    

The schedule JSON is an object with three elements:

  • name - a user-defined string
  • domain - a string containing the /48 or /64 domain.
  • times - an array of timing objects.

The times objects contain the following string elements:

  • minute
  • hour
  • day_of_month
  • month
  • year
  • day_of_week - where 0 is Sunday

The example above schedules an update on domain 2607:8F80:8080:0009::/64 for Saturday and Sunday nights from 1 1PM until 2 AM.

  1. Create the update
    > captive create-schedule --schedule=/Users/jqpublic/schedule-weekend.json
    Schedule Name    : Weekend_update
    Shedule ID       : dc8a7576-51c9-4854-ac12-cac13024d836
    domain           : 2607:8f80:8080:9::/64
    Times:
    +------+------+-------+------+---------+--------+--------+--------------------------------------+
    | Name | year | Month | Date | Weekday | Hour   | Minute | id                                   |
    +------+------+-------+------+---------+--------+--------+--------------------------------------+
    |      | *    | *     | *    | 0       | 23,0-2 | *      | 55da6480-a0e0-4f4a-9057-dd9ee516c343 |
    |      | *    | *     | *    | 6       | 23     | *      | 6e94a908-aa00-4cda-99ee-4a1e49a445be |
    |      | *    | *     | *    | 1       | 0-2    | *      | 0ebf132e-a65b-4028-828f-c03c379f5ad6 |
    +------+------+-------+------+---------+--------+--------+--------------------------------------+
    
  2. List existing schedules
    > captive list-schedules
    +----------------+--------------------------------------+
    | Name           | ID                                   |
    +----------------+--------------------------------------+
    | Weekend_update | dc8a7576-51c9-4854-ac12-cac13024d836 |
    +----------------+--------------------------------------+
    
  3. Get details on a specific schedule
    > captive get-schedule --schedule-id=dc8a7576-51c9-4854-ac12-cac13024d836
    Schedule Name    : Weekend_update
    Shedule ID       : dc8a7576-51c9-4854-ac12-cac13024d836
    domain           : 2607:8f80:8080:9::/64
    Times:
    +------+------+-------+------+---------+--------+--------+--------------------------------------+
    | Name | year | Month | Date | Weekday | Hour   | Minute | id                                   |
    +------+------+-------+------+---------+--------+--------+--------------------------------------+
    |      | *    | *     | *    | 0       | 23,0-2 | *      | 55da6480-a0e0-4f4a-9057-dd9ee516c343 |
    |      | *    | *     | *    | 6       | 23     | *      | 6e94a908-aa00-4cda-99ee-4a1e49a445be |
    |      | *    | *     | *    | 1       | 0-2    | *      | 0ebf132e-a65b-4028-828f-c03c379f5ad6 |
    +------+------+-------+------+---------+--------+--------+--------------------------------------+
    

Create Firmware Update Task

The firmware update task associates a firmware version. It also provides for selecting the percentage of devices to update. For example, it is possible to upgrade only 10% of the devices to firmware version 1.2.0, using the schedule listed above.

The update task is created as a JSON file and then uploaded to the captive server via enfcli.

  1. Examine the available firmware versions.
    > captive list-firmware-images
    +------------------+
    | Firmware Version |
    +------------------+
    | 1.0.13           |
    | 1.0.14           |
    | 1.1.1            |
    | 1.2.0            |
    +------------------+
    
  2. If desired, get detailed information on the specific firmware image.
    > captive get-firmware-info --version=1.2.0
    Release version: 1.2.0
    +-------------------------------------------------------+----------------+-------------+----------------------------------------------+
    | Image Name                                            | Hardware Model | Update Type | SHA256                                       |
    +-------------------------------------------------------+----------------+-------------+----------------------------------------------+
    | artifact-signed-xaprw001_dev-v1.2.0-0-g25a335e.mender | xaprw001_dev   | update      | 47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU= |
    +-------------------------------------------------------+----------------+-------------+----------------------------------------------+
    1 rows in set
    
  3. Using your favorite editor, create an update-task JSON file.
    {
     "version" : "1.2.0",
     "schedule_id" : "dc8a7576-51c9-4854-ac12-cac13024d836",
     "update_percentage" : 10
    }
    
  4. Create the update task.
    > captive create-firmware-update --update=/Users/jqpublic/update-test.json
    Update Task ID               : 84d2cc7f-ce3c-40f7-8694-ce74e80dc2c2
    Schedule ID                  : dc8a7576-51c9-4854-ac12-cac13024d836
    Firmware Version             : 1.2.0
    Percent of devices to update : 10.0
    

Add Update Task to a Profile

Once an updat task has been created, it must be applied to one or more profiles. Without this step, the task is not associated with any devices and the Captive Server will not act on it.

Add update task to an existing profile.

> captive update-profile --profile-id=70a82dd2-5a5a-40cb-9575-aaff5b7414dc --update-id=84d2cc7f-ce3c-40f7-8694-ce74e80dc2c2
Name                  : TEST-devices
Profile ID            : 70a82dd2-5a5a-40cb-9575-aaff5b7414dc
Configuration version : 3
Firmware Update ID    : 84d2cc7f-ce3c-40f7-8694-ce74e80dc2c2
    Update version    : 1.2.0
Mode                  : secure-host
Wifi config           :
    id                : 9e3f2a2e-e2ef-4152-8fa3-44b40ad1d258
    domain            : 2607:8f80:8080::/48
    name              : Chicago-North-Wifi
    config version    : 1

As mentioned in the Router Card Profile article, an existing update task can be added to a profile in the create-profile command.

Modify the Update Task

In the example, we updated 10% of the devices to version 1.2.0. Once these are complete and have proven reliable, we might want to update 50% of the devices. Modify the JSON file to have "update_percentage" : 50. This update percentage is cumulative. In this example, we’re updating an additional 40% of the devices – 50% in total.

> captive modify-firmware-update --update-id=84d2cc7f-ce3c-40f7-8694-ce74e80dc2c2 --update=/Users/jqpublic/update-test.json
Update Task ID               : 84d2cc7f-ce3c-40f7-8694-ce74e80dc2c2
Schedule ID                  : dc8a7576-51c9-4854-ac12-cac13024d836
Firmware Version             : 1.2.0
Percent of devices to update : 50.0

Since, in this example, the update task has already been added to an active profile, it is not neccessary to add it again.

Didn't find what you were looking for?

Contact us and we’ll get back to you as soon as possible.

Contact Us