Scripts guide¶

A script is a small folder of files: a file that runs (say run.sh) plus anything it needs, such as config files, .deb packages, firmware or images. Write it once, run it on one device or a hundred, and watch the output come back live.

Start from a template¶

Scripts → New script → a Name → Template. Each template becomes an ordinary script you can change. Every script runs as root, in a folder holding its files.

Update packages

apt update and upgrade, then autoremove. Reboots only if a package needs it and you allow it.

Parameter: REBOOT (yes / no, default no)
Collect diagnostics

System, disk, memory, network, failed services, kernel messages and the journal's warnings, in one report you can download.

Parameter: SINCE (1h, 24h, 7d)
Restart a service

systemctl restart, then the service's status.

Parameter: SERVICE (for example nginx)
Install a .deb

Upload one or more .deb files into the script; it installs them all with apt.

No parameters.

What's inside: Update packages (run.sh)

#!/usr/bin/env bash
# Update all packages with apt. Reboots afterwards only if a package requires it and REBOOT is true.
set -euo pipefail
export DEBIAN_FRONTEND=noninteractive
apt-get update
apt-get -y -o Dpkg::Options::=--force-confold upgrade
apt-get -y autoremove
if [ -f /var/run/reboot-required ]; then
  echo "A reboot is required by: $(cat /var/run/reboot-required.pkgs 2>/dev/null | tr '\n' ' ')"
  if [ "${REBOOT:-false}" = "true" ]; then
    echo "Rebooting in 1 minute"
    shutdown -r +1
  fi
else
  echo "No reboot needed"
fi

What's inside: Restart a service (run.sh)

#!/usr/bin/env bash
set -euo pipefail
systemctl restart "$SERVICE"
sleep 2
systemctl status "$SERVICE" --no-pager

What's inside: Install a .deb (run.sh)

#!/usr/bin/env bash
# Upload one or more .deb files next to this script, then run it.
set -euo pipefail
export DEBIAN_FRONTEND=noninteractive
shopt -s nullglob
packages=(./*.deb)
if [ ${#packages[@]} -eq 0 ]; then
  echo "No .deb files: upload them into this script first" >&2
  exit 1
fi
apt-get update
apt-get install -y "${packages[@]}"

Other ways to start: Blank (a run.sh that says hello from the device), or Upload files or a folder: pick them from your computer, click Upload a folder on the Scripts page, or just drop a folder onto it. Any file type; folders are kept.

The file that runs first (the entry file) is found in this order: run.sh, main.sh, install.sh, start.sh. Change it with Run this file first in a file's menu.

Edit a script¶

The script page shows its files, an editor and its parameters. Changes are saved automatically ("Saved · version N"); every save is a new version. If the script changed in another window, the page says so.

Files: create a file (use / for folders, for example config/app.yaml), drop files or folders onto the tree, and use a file's menu: Run this file first, Rename or move, Make executable, Unpack here (a .zip), Download, Delete. The editor opens files up to 1 MB.
Names can contain anything except / \ : * ? " < > | and control characters.
Limits: 500 files and 250 MB per script, 1 GB of script files per account. Under the file tree the page shows the script's file count and size against its limits.
Download .zip downloads the whole script; the menu has Duplicate and Delete script.

Parameters¶

Parameters are values you fill in each time you run, so you do not edit the script to change them. Each has a name, a type (Text, Number, Yes / no, Choice or Secret), a default and whether it is required. The script reads them as environment variables:

#!/bin/bash
echo "Installing version $APP_VERSION"
if [ "$RESTART" = "true" ]; then systemctl restart my-app; fi

Names: capital letters, digits and _, starting with a letter or _, up to 64 characters. Not allowed: PATH, HOME, SHELL, USER, LOGNAME, PWD, IFS, TERM, ENV, BASH_ENV, and names starting with LD_, BASH_FUNC_ or KINUXOTA_.
Up to 50 parameters; a value can have up to 4096 characters.
Secret values have no default, are replaced by ****** in the output and are not kept once the devices have received them. A run that used a secret cannot be re-run with Re-run failed.
Every run also sets KINUXOTA_DEVICE_NAME, KINUXOTA_DEVICE_ID, KINUXOTA_RUN_ID and KINUXOTA_SCRIPT_NAME.

Run a script¶

Click Run (in the script list, on the script page, or on a device's Scripts tab):

Devices: tick the devices (up to 100); Online only and Select all online help.
Parameters: fill them in.
Advanced (optional): Stop the script after (minutes) (default 60, up to 1440), Offline devices: wait for them up to 1 hour, 1 day (default) or 7 days, and Only copy the files now, start later.
Click Run on N devices (or Stage on N devices).

The run page (Run #N on X devices) shows each device's status, exit code and output as it arrives, with Cancel all, a Cancel per device, Re-run failed and Run again.... Download saves a device's output.

How a script runs on the device:

As root, in a private folder that holds the script's files; the folder is removed afterwards.
The entry file is executed directly when it starts with #! (any interpreter), otherwise with bash. Files marked executable can be run by it (for example ./helper.sh).
Every file's checksum is verified before anything runs.
Exit code 0 is Completed, anything else Failed. Cancel stops the script and everything it started.
Output (stdout and stderr) is kept up to 10 MB per device per run.

Offline devices do not fail the run: they show Waiting for device and run the script when they come online within the wait time; after it they show Expired.

Only copy the files now, start later copies the files to the devices first (Staged); the run then waits until you click Start on N devices.

History¶

Runs (in the menu): every run, filtered by script, device, status and date.
A script's Runs section and a device's Scripts tab show their own history.
Deleting a script keeps its runs and their output.