Please review these concept articles before moving devices to production:

• Assemble vs Build
• Software Security and Device Customization
• Device Updates and Agents
• Authority and Mode

Preparing Your Image

As you near the time of creating your production release, there are a few factors that will make it easier to recreate the items in the manifest at a later time if ever the production release needs to be reassembled.

Publish All Required KABs

When it comes time to recreate a release for testing or support purposes, finding the exact KAB UUID listed in a manifest is essential. Releases created from local files make assets difficult to find, use, or share during the next build cycle.

Publishing KABs to an Artifact Store ensures that KOS Studio will be able to reassemble the build even when employees are away, computers have been replaced, or local storage has been wiped.

To remove or disable an Artifact in the disk image, open the Image from My Images, by clicking on the gear to the right of the Image name.

To remove or disable an Artifact, click on the overflow menu to the right of the Artifact name. Disabling an Artifact leaves it in the section in case it needs to be available in the future but no longer uses the Artifact in builds or simulations of the device, while deleting the Artifact permanently removes it from the device. 

To remove a Local Artifact Completely from the image, click on the Local Files section of your Image stack and make sure all Local files have been removed to ensure.

Ensure "Production Ready" Version have been Selected

Publishers can provide many tools via the Studio Marketplace to help customers troubleshoot devices, develop code, or even test future features and upcoming versions. 

To help ensure these helpers’ KABs are not installed on devices, Marketplace Publishers mark their KABs "Production Ready" or "Not Production Ready." KABs that are not production-ready are marked. 

Verify that all of the Marketplace KABs being installed on the device are Production Ready. This ensures these companies can support this device when the time comes.

Disable All Virtual Artifacts

A useful feature within the KOS Studio toolbox is the ability to create Virtual Artifacts. Since KOS Studio tracks all versions that have been published, if a developer wants to test with the previous version, they simply select the older version and hit run. Virtual Artifacts enables the engineer to select a range of versions, including versions which contain wildcards, allowing manifests to a utomatically include the newest version, or the latest version in a series such as 1.x.

While this is incredibly useful during the development cycle, again in the hopes that this release can be reassembled in the future, we recommend disabling all virtual artifacts, replacing them with the most resents tested instance of the Artifact.

Disable Snapshot Versions

Where some developers are rigorous about publishing each new Artifact with a new version number, other developers prefer to override the last version, using snapshots to manage the various stages of their software development.

To guarantee that the release being assembled today, is the same as when this release is assembled next week, removing snapshots replacing them with active versions guarantees success. 

Remove any File Mappings

File Mappings, used to develop code while using a simulator are not added to a manifest. If the functionality developed via these file mappings are required for the device, publish the file mappings as a Layer KAB, and include that Layer during the next release.

Verify Correct Hardware is Selected

While KOS Studio can install a disk image onto any KOS Node, by pinging the node before installation, receiving data that defines that node, enabling Studio to select the correct instances of each Artifact for the hardware being installed, during the release process, KOS Studio does not have to be attached to the actual device.

For KOS Studio to pick not only the correct version of each Artifact, but the correct instance of each version for the hardware, information about that hardware must be defined in the hardware section of the image stack.

Select a "Production Release" Version of KOS

KOS offers its customers an opportunity to work with the versions of the operating system that are still in development. This can help troubleshooting, provide the developer with a head start accessing a new feature or just enabled the developer to have access to some of the latest code. However, only the Production Release version’s of KOS have been thoroughly vetted. The team cannot ensure, rollback, or OTA works with the operating system that is being developed.

This is why we ask all customers to ONLY use production released of KOS for production releases. Rollback, OTA and many other important infrastructure features are tested before a release is marked Production Ready.

Accessing Production Keys

To get access to the organization’s production keys, the owner of the KOS studio organization must contact their KOS account manager and ask for the keys. The keys will only be sent to the email address on file for the Production Owner.

Once you have received the file, store it in a safe place and do not share it.

Installing Production Keys

Installing the organization’s production keyset is easy. Click on the KOS Studio Settings Menu. Once selected, choose "Keyset Manager".

The tool opens with a list of already installed keysets for this machine. Click on the blue button "Import Keyset."

Use the File Picker to select the Keyset file that was sent via email.

Click OK.

Production Keys are now installed on this computer for this user.

Creating a Production Release

Now that the Keyset is installed and your Disk Image is ready to go, click on the overflow button to the right of the Image name on the main Studio window. After importing the organization Keyset, a new option is available: "Create Production Release," followed by the name of the organization.

Use the File Picker to select the folder to store the release. The created release is a production-signed release.

Locking the Device

Locking the device can only be undone by reformatting the board – it is a very difficult process to undo.

Once you lock the device, KOS Studio will no longer have the authorization to access the device and, therefore, is unavailable for troubleshooting. We recommend that the developers have a planned method of accessing the device via a third-party agent like SnakeBite or a device management system that was tested while the device was running production software but not yet locked.

KOS determines whether it is in test or prod mode in the bootloader prior to selecting a KMF to launch. The Kyanite hook script, /kyanite/hooks/pre_find_manifest.d/90-KOS-testmode.sh is responsible for setting the mode flag at /run/KOS/testMode. The script sets the testMode flag under the following conditions:

The file /mnt/images/KOS/testMode exists; or

The kernel command-line contains the argument, KOS.mode=test

All installers pre-install the testMode flag when creating the initial ImageFS, resulting in dispensers initially starting in test mode.

Switching to Prod Mode

To switch to prod mode, mount the ImageFS as writable and then delete the /mnt/imagefs/KOS/testMode file. On the next reboot, the dispenser will start in prod mode.

When the bootloader kexecs into the system initrd, it wraps the current contents of the /run/KOS directory into a CPIO and appends it to the initramfs for the next stage. The system initrd runs a hook script, /kyanite/hooks/top.d/03-KOS-loadflags.sh to place the flags back into the /run/KOS directory, so that it can reuse the bootloader’s flag determinations. This allows all logic for checking testmode to reside in a single early boot stage.

Many corporations have a station at the end of the line after both the hardware and the software have been tested thoroughly, where they press a single button in their EOL software. This button removes the testMode file and reboots the dispenser, guaranteeing that the device leaves the factory line locked, safe, and secure.