Modifications described here do not apply to a AX-3.8 system, but only on a system running an update release (AX-3.7u1 or
later, AX-3.6u4 or later, AX-3.5u4 or later). See Station archive portablility improvements in AX-3.8.
The BackupService includes contents in a backup distribution file that are appropriate for restoring the original source system
to its current state. However, some contents are inappropriate for “system images” used to replicate the same station to many
different hosts. You can modify the backup .dist file to remove or replace those contents.
Be sure to keep unmodified copies of saved backup .dist files or config.bog files (from Station Copier) before making modifications. Work from copies of these files.Test your changes — be sure your modifications accomplish what you intend. This is especially important if
you will be relying on them for jobs or sharing with customers or clients.
Each distribution file is zip archive that contains certain system files and a manifest file that describes system and software dependencies, with rules for installing the system files. Because it is a zip archive, you can modify it with common tools such as 7-Zip, WinZip, and recent versions of Microsoft Windows.
To modify a backup .dist file to be suitable for use as a system image, you need to remove the (encryption) key files, and typically also make edits
to its manifest file and modify its station database (config.bog) file.
The following .dist file modifications are typical:
-
Remove the security folder (recommended)
-
Edit the distribution manifest (optional)
In the backup .dist file, the security folder contains encryption key data that is unique to this device. If the same folder was copied to many different hosts,
overall system security would be weakened.
This underscores the importance of properly securing backup dist files! If someone obtains a copy of the backup dist file,
they would have this encryption key data. See the related Caution.
Delete the security folder. Figure 6 shows this being done using 7-Zip.
Note this also underscores the importance of saving unmodified copies of backup .dist files, again in a secure location. Once the folder shown above is deleted, all the client (encrypted) passwords in the associated station database file (config.bog) will no longer work.
The distribution manifest is an XML file, stored as meta-inf/dist.xml in the distribution. Its format is documented in the Niagara Developer Guide (docDeveloper) in a “Distributions” section.
Some zip editing tools don’t support editing files in place very well. To use these, you will need to extract the dist.xml file to your system, make your edits, then add the file back to the dist with the zip tool.
The manifest in a backup .dist file contains elements or attributes you may wish to delete in many cases, including the following:
The platform element in the dist.xml file will not be appropriate if the target hosts can have different hardware configurations. If this is the case, remove
that element.
As shown in Figure 8 above, all lines from <platform merge=”false”> to </platform> at the end should be marked for deletion.
The tcpIpSettings element in the dist.xml file is not appropriate for system images. Although not critical (as the Distribution File Installer prompts if you want to install using these settings, and a Supervisor’s Provisioning extension ignores it), you can still
remove it while you are already editing this file.
As shown in Figure 9 above, all lines between <tcpIpSettings hostname=”value”(etc)> to the ending </tcpIpSettings> should be marked for deletion.
The rel element in various dependency elements in the dist.xml all state rel=”exact”. This can be a bit unforgiving when used as a “system image”, as a backup .dist install will fail if the exact version of a dependency isn’t available to install.
Figure 10. Searching for rel attributes to delete in a backup .dist file’s mainfest (dist.xml), if necessary
Figure 10 above shows a search and replace being used to remove the rel attribute from selected lines.
This is an advanced modification—note that all listed core, config, and QNX OS distributions listed include this rel=”exact” attribute, in addition to all listed software modules (.jar files).
The station database (config.bog file) is included in a backup .dist file, stored at:
stations/stationName/config.bog
If changes are needed, you need to extract it using a zip tool, and modify it offline using Workbench.
Figure 11 above shows the config.bog file being extracted (using 7-Zip) to the same folder used to modify the backup .dist file.
See Editing the station database (config.bog) file for details on using Workbench to modify this file.
When you are finished modifying config.bog with Workbench (making sure to save it), you now need to replace the original one in the backup .dist file.
As shown in Figure 12, one way to do this (for example, using a zip tool like 7-Zip):
-
Delete the existing
config.bogfile in the backup.distfile. -
Drag and drop the modified
config.boginto thestationsfolder of the backup.dist. At the confirm file copy prompt answer .
After saving, your modified backup .dist file should now be ready to use as a “system image”, usable to install to multiple hosts that need a replicated station.