Introduction

The Autorun feature allows for automatic execution of Jetporch scripts delivered in a signed .tgz archive. It is designed for use cases such as firmware migrations and post-deployment automation, and supports both global scripts and device-specific scripts, with integrated signature verification and logging.

Prerequisite

Before a gateway can run scripts via USB, its public key must be present on the product. One possibility is to use the gateway's webUI and upload the key manually.

This means that if the gateway's WebUI is not accessible (for example, if the gateway is already deployed on a remote site), USB execution cannot be used until the public key has been deployed

This is where Kerlink can help: by automating the deployment of these public keys via:

• ZTP (Zero-Touch Provisioning)
• Kerlink prestaging
• Wanesy Management Cockpit (If the customer has a support contract)

Feel free to contact Kerlink for more details.

How It Works

The autorun system monitors for the presence of signed .tgz archives containing scripts and optional resources. It triggers execution in three main scenarios:

• Automatically, via a systemd.path-based file monitor.
• During a product migration, e.g., a full OS upgrade.
• On USB key insertion

Once an autorun.tgz archive is detected:

• The archive is verified using the ECDSA signature stored in content.sign.
• If the signature is valid, the archive is extracted.
• A common script (world.yaml) is executed for all devices.

A device-specific script (EUI64.yaml) is executed only if the current device’s EUI64 matches the filename.

Scripts are executed using the Jetporch engine, running as root.

File Structure

Each autorun.tgz archive must follow this format:

autorun.tgz
├── content.data      # tar archive containing scripts and optional files
├── content.sign      # ECDSA signature of content.data

Inside content.data (a .tar file), you must include:

content.data (tar)
├── world.yaml        # Common Jetporch script for all devices
├── <EUI64>.yaml      # Optional device-specific script
├── other-resources/  # Optional resources (e.g., .deb packages, binaries, configs)

The gateway knows its own EUI64. If EUI64.yaml matches, it will be executed.

Create your content.data:

tar cf content.data world.yaml <EUI64>.yaml other-resources/

Create your autorun.tgz:

tar czf autorun.tgz content.data content.sign

See how to create the content.sign file in the next section.

Signature Verification

Before execution, the system verifies the archive signature using OpenSSL:

openssl dgst -sha256 -verify /etc/autorun/*.pem -signature content.sign content.data

All public keys must be placed in: /etc/autorun/

If signature verification fails, the archive is ignored, and no script is executed.

The system logs the failure using journald.

To generate your own autorun signature, you must:

• generate a key pair
• export and copy the public part into the board in /etc/autorun/ directory
• sign autorun package using your private key

openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-384 -pkeyopt ec_param_enc:named_curve -out private.pem
openssl pkey -in private.pem -pubout -out public.pem
openssl dgst -sha256 -sign private.pem -out content.sign content.data  

The created public key (public.pem) should be placed to the gateway in the /etc/autorun directory.

Execution Environment

Scripts are executed as root.

The archive is extracted into a temporary directory.

Environment variables are injected, including:

• The path to the original .tgz file
• Other system context as required

Logging & Idempotency

Execution logs are stored via systemd-journald.

Upon successful signature verification, a log file is created next to the archive to mark execution.

This log file also prevents the script from being re-executed on future reboots or scans.

Product Migration Support

Since Keros 6.4, the autorun mechanism is also triggered during a product migration using keros6-installer.

Autorun content must be placed under /keros/keros-installer-data/migration/ directory. All those files will be packaged automatically into an autorun.tgz and thus deployed at Keros 6 first-boot.

To create the directory on Keros5:

 mount -o remount,rw /keros
 mkdir -p /keros/keros-installer-data/migration

Then place the world.yaml with all files that you need in that directory.

The mechanism ensures that post-upgrade tasks (e.g., provisioning, local package installation) can be automated.

After the migration, the log file at the end of the migration is available at cat /var/lib/keros-installer-data/autorun.tgz.<EUI>.log

USB execution

From version Keros 6.4, the system allows to execute some actions through an USB key.
To do that, you need to:

• Create your own autorun.tgz
  Follow instructions described above.
• Place the file into the root directory of the USB key and plug it to the gateway.
  The execution is automatically run once the USB key is plugged.
• Once the script execution is finished, the USB key can be unplugged from the gateway.
  For now, there is no way to identify when the execution is finished.
• A log file available in the root directory of the USB key summarising actions done in the script.

Best Practices

• Always sign your archives using a known private key and ensure the corresponding public key is deployed to /etc/autorun/.
• Test your Jetporch scripts independently before packaging.
• Include both world.yaml and (optionally) EUI64.yaml if deploying to a fleet. You can also use symbolic link.
• Use environment variables to locate additional resources during script execution.

FAQ

Q: What happens if multiple .tgz archives are placed in the watch folder?
A: All valid archives will be processed, each exactly once.

Q: What if the signature is invalid or missing?
A: The archive is ignored. The failure is logged in systemd.

Q: Can I include other files (like .deb) in the archive?
A: Yes. Any file required by the autorun logic can be included inside content.data.

Q: Is it possible to re-run a script manually?
A: Yes, by removing the log marker file that tracks execution (next to the .tgz).

Q: Can one archive target multiple devices?
A: Yes. Just include multiple EUI64.yaml files (or use symbolic link). Each device will pick the one matching its own EUI64.