Fioctl

This section provides details on using Fioctl® by way of example.

Prerequisites

  • Completion of the getting started guide.

Auto Updating

fioctl version --update-to <version>
Fioctl v0.36 and later can be updated—rather securely, via TUF—without the need to manually reinstall the binary.
# check if an update is available:
host:~$ fioctl version
v0.37-24-gd450f5b
Update available: 0.38.0
      https://github.com/foundriesio/fioctl/releases/download/v0.38/fioctl-linux-amd64

# update by running:
host:~$ fioctl version --update-to 0.38.0
v0.37-24-gd450f5b
Downloading update: https://github.com/foundriesio/fioctl/releases/download/v0.38/fioctl-linux-amd64
Saving new version to /var/code/vs-code-server-config/fioctl/bin/fioctl-linux-amd64

Important

A note about write permissions:

It is likely that you will need to gain write privilege to update. This can be done via sudo, assuming it is not a read-only partition. However, also consider running sudo su within a new terminal. This is to avoid having sudo holding a session, and some privilege escalation risks.

See also

Updating Fioctl version for writing to TUF Root

Enabling/Disabling Apps

All apps defined in containers.git for any given tag are enabled by default. To change this behavior, allowed apps can be set per device, enabling only those in a comma-separated list.

Via Fioctl

fioctl devices config updates <device_name> --apps <app_name1>,<app_name2>
Set the app(s) a device will run.
# First, list Targets and ensure app(s) are available in the latest Target.

$ fioctl targets list -f cowboy

# Find a device to instruct by name.

$ fioctl devices list -f cowboy

# Enable only the desired app(s) on the device.

$ fioctl devices config updates cowboy-device-1 --apps netdata,shellhttpd

# Now only the app(s) supplied in the list will run on the device.

Via the LmP Device Register Script

When registering a device, lmp-device-register can set a list of apps to enable.

lmp-device-register --api-token=<token> --apps <app_name1>,<app_name2>
Set the app(s) a device will run, during registration.

Inspecting Targets

Hint

A Factory produces Targets when a change is pushed to the Factory Source Code. A Target is a description of the software a device should run. It is defined by a list of metadata which includes an OSTree Hash and one or more Docker-Compose App URIs.

This metadata is recorded upon Target creation, making the Target an immutable description of the Factory at a point in time.

Fioctl provides many methods of viewing Target metadata, which can reveal:

  • The available apps inside a Target.
  • Which tag a Target has.
  • What MACHINE a Target has been produced for (HARDWARE ID).
  • What git commits triggered the Target to be built.

Target metadata can be inspected by using 3 primary commands:

fioctl targets list

Lists the Targets a Factory has produced so far.

Click to show command output
fioctl targets list -r

Lists the Targets a Factory has produced in -r (raw) json format. This is often piped into jq in order to format the json neatly.

The command output below highlights the docker_compose_apps section. This contains the names of apps available for the Target, as well as their Docker-Compose App URIs.

Additionally, the OSTree Hash for the Target has been highlighted.

Click to show command output
fioctl targets show <target>

Prints detail about a specific Target, (e.g fioctl targets show 58).

These details include:

  • A link to the CI build for the Target, where you can view the console.log or download artifacts.

  • The hashes for each repo in the Factory Source Code at the time the Target was produced.

  • The OSTree Hash for the Target.

  • The Docker-Compose App URI for each available app at the time the Target was produced.

    Click to show command output

Common Commands

View Targets
fioctl targets list -f <factory>

Lists the Targets a Factory has produced so far:

$ fioctl targets list -f bebop
VERSION  TAGS    APPS        HARDWARE IDs
-------  ----    ----        ------------
2        devel               raspberrypi3-64
3        main                raspberrypi3-64
4        main    shellhttpd  raspberrypi3-64
5        main    shellhttpd  raspberrypi3-64
6        main                raspberrypi3-64
7        main                raspberrypi3-64
8        main    httpd       raspberrypi3-64
11       main    octofio     raspberrypi3-64
List devices
fioctl devices list -f <factory>
Lists the devices connected to a Factory and metadata, such as device name, status, Target, and enabled apps.
$ fioctl devices list -f bebop
NAME  FACTORY  OWNER           TARGET                  STATUS  APPS     UP TO DATE
----  -------  -----           ------                  ------  ----     ----------
ein   bebop    <unconfigured>  raspberrypi3-64-lmp-49  OK      netdata  true
Set device tag
fioctl devices config updates <device_name> --tag <tag>
Filter the Targets a device will accept by tag. For example, to move a device from accepting ‘devel’ builds to ‘main’ builds. See Advanced Tagging for more examples.
$ fioctl devices config updates ein --tag devel
Changing tag from: main -> devel
Set app(s) to be enabled
fioctl devices config updates <device_name> --apps <app_name1>,<app_name2>

Set the app(s) a device will run.

$ fioctl devices config updates ein --apps simple-app
Changing apps from: [netdata] -> [simple-app]
Enable WireGuard VPN
fioctl devices config wireguard <device_name> <enable|disable>
Enable or disable the Wireguard systemd service on a LmP device. This requires a Factory configured to use a Wireguard instance you have set up on your own server as described in the WireGuard VPN guide.
$ fioctl devices config wireguard ein enable
Finding a unique VPN address ...