COP Software Updates

VIRGO supports upgrades to new versions and also downgrades to older versions. An upgrade or downgrade is triggered by including an update section in the status reply (configuration message). VIRGO triggers an upgrade if the version number listed in the update section is greater than the version of the currently running VIRGO and it triggers a downgrade if the version number listed in the update section is smaller than the version of the currently running VIRGO. The update section is ignored if the version number listed in that section is equal to VIRGO’s current version number. VIRGO will preserve the existing configuration in the case of an upgrade and it will automatically migrate the existing configuration if the storage format has changed. Note however that configuration information is not preserved in the case of a downgrade because VIRGO does not support backward migration. Instead VIRGO will initially run with the factor configuration after the downgrade and it expects to receive the version-appropriate configuration information in response to the first status message that VIRGO sends to VIRGA.

VIRGO downloads the update archive from the provided download URL. The download URL may be a HTTP, HTTPS, or file URL. The archive must be a tar.gz file.

VIRGO is able to continuously send update progress events to the progress URL mentioned in the update section. One update progress event is sent every “progress-interval” milliseconds. These events represent the current update progress and they provide additional information about the currently active update stage. If an update fails then an event is sent which includes information about the cause of the update failure.

An update is a multi stage process. VIRGO executes the following stages one after the other to install an update bundle.

Stage Update Event Status Description
Downloading downloading The update archive is being downloaded to the machine on which VIRGO is running.
Dearchiving dearchiving The downloaded update archive is expanded into the update bundle. The bundle is then validated to ensure that it is a well-formed update bundle.
Migration migrating The existing VIRGO configuration data is converted to the format expected by the new virgo version. This stage is skipped for downgrades.
Completed completed The update has completed successfully.
Failure failed VIRGO was unable to complete the update successfully. Note that in this case VIRGO automatically rolls the update back to the previous version.

Once the update process has completed the VIRGO daemon is automatically restarted and it reloads the configuration and it automatically restarts all feeds that are marked as enabled. If on the other hand the update process could not be completed successfully because of some problem then VIRGO is automatically rolled back to the previous version and the VIRGO daemon is restarted.

The following code block shows an example of a update section:

{
   ...
   "update": {
      "version": "1.0.240",
      "download-url": "http://virga.real.com/virgo-updates/1.0.240.tar.gz",
      "progress-url": "http://virga.real.com/virgo-updates/progress-1-0-240",
      "progress-interval": 500
   },
   ...
}

This update section will cause VIRGO to be updated to version 1.0.240. Progress events with information about the current state of the update will be sent every half second to the provided progress URL.

Update Events

VIRGO continuously sends update progress events to the provided progress URL to provide information on the current progress of an ongoing upgrade or downgrade operation. The following code block shows the structure of an update progress event:

{
   "from-version": "1.0.0",       // [required][semantic version]
   "to-version": "1.0.140",       // [required][semantic version]
   "status": "downloading",       // [required][string]
   "progress": 15,                // [required][int]
   "log": [                       // [optional][array of strings]
      "576567\td\tupdates\t...\n",
      ...
   ],
   "error": {                     // [optional][dictionary] only provided if "status" == "failed"
      "code": 4,
      "message"..."
   }
}

The following table lists the properties that may appear inside an update progress event:

Property Type Description
from-version Version The version from which the update was started.
to-version Version The version to which VIRGO is being upgraded or downgraded.
status String The current update status. See the table listing the “stages” above.
progress Int The current progress as a percentage value in the range 0% to 100%
error Dictionary The error code and message if the update has failed. Note that this property only exists if the “status” == “failed”.
log Array<String>? The log statements that have been recorded since the previous update event. See Logging for a description of how log statements are encoded.

Update progress events are sent whenever VIRGO transitions from one update stage to the next stage and after every “progress-interval” milliseconds.

The following HTTP custom headers are included with every update event:

Header Description
X-CLIENT-ID The client id of the virgod instance. This is immutable, factory configured, unique, and descriptive vrgo instance identifier.
For example:
VIRGO-LNX-TRPR-16-123
X-CLIENT-TYPE The type of the client. This is a combination of the client name and the platform name.
For example:
Virgo-Linux

See Also