Skip to content

Pantavisor State Format

Pantavisor state format describes the json format to configure the Pantavisor run-time state. In this page, we are going to go through the System State Format v2, which is the version we currently use.

NOTE: This reference is for advanced users. Before manually editing these values in your device, check if what you intend to do can be achieved with the help of pvr.

Spec Format

A complete system is made up of one BSP as well as one to many containers. The state allows this following this format:

{
    "#spec": "pantavisor-service-system@1",

    "README.md": "xxx",

    "bsp/run.json": {..},
    "bsp/file1....": {..},

    "<container1>/run.json": {..},
    "<container1>/file1...": "xxx",

    "disks.json": {..},

    "_sigs/<container1>.json": {..},

    "_config/<container1>/file1...": "xxx"
}

This table defines all possible keys for the state format:

Key Value Default Description
#spec pantavisor-service-system@1 mandatory version of the state format
README.md string empty readme file in markdown format
bsp/run.json bsp/run.json mandatory bsp run-time configuration file
\<container>/run.json container/run.json mandatory container run-time configuration file
disks.json disks.json empty definition of physical store medium
_sigs/container.json _sigs/container.json empty signature file
_config/\<container>/ _config/container/ empty configuration files

bsp/run.json

This file allows to configure the BSP. The JSON follows this format:

{
    "addons": [
        "addon-plymouth.cpio.xz4"
    ],
    "firmware": "firmware.squashfs",
    "initrd": "pantavisor",
    "initrd_config": "",
    "linux": "kernel.img",
    "modules": "modules.squashfs"
}

This table defines all possible keys for the BSP run.json:

Key Value Default Description
addons list of paths mandatory list of relative paths to the initrd rootfs addons
firmware path mandatory relative path to Linux firmware file
initrd path mandatory relative path to Pantavisor binary file
linux path mandatory relative path to Linux kernel file
modules path mandatory relative path to Linux modules file

container/run.json

This file allows to individually configure each container. This JSON follows this format:

{
    "#spec": "service-manifest-run@1",
    "config": "lxc.container.conf",
    "name": "awconnect",
    "root-volume": "root.squashfs",
    "storage": {
        "docker--etc-NetworkManager-system-connections": {
            "persistence": "permanent"
        },
        "lxc-overlay": {
            "persistence": "boot"
        }
    },
    "type": "lxc",
    "volumes": []
}

This table defines all possible keys for the container run.json:

Key Value Default Description
#spec service-manifest-run@1 mandatory version of the state format
config path mandatory relative path to the container configuration file
name string mandatory name of the container
root-volume path mandatory relative path to the container rootfs file
storage storage mandatory container storage configuration
type lxc mandatory type of container
volumes list of paths mandatory relative paths to the additional container volumes
logs list of loggers empty list of log configuration JSONS
group string empty name of group
conditions list of conditions empty conditions that have to be met to start the container
runlevel data, root, platform or app root or _platform _DEPRECATED: use group instead
roles mgmt empty list of roles for the container

storage

This JSON allows to configure the storage of a container. It is important to notice that you can configure the overlay or any of the container rootfs paths:

{
    "lxc-overlay":{
        "persistence":"boot"
    },
    "etc/example/": {
        "persistence": "permanent"
    },
    "docker--etc-modules-load.d": {
        "disk": "built-in",
        "persistence": "permanent"
    },
    "docker--var-pv": {
        "disk": "dm-versatile",
        "persistence": "permanent"
    },
    ...
}

This table defines all possible keys for the container storage JSON:

Key Value Default Description
persistence permanent, revision or boot mandatory
disk string empty name of disk defined in [disks.json]

logger

This allows to configure a logger inside of a container. It looks like this:

{
    "file":"/var/log/syslog",
    "maxsize":102485760,
    "truncate":true,
    "name":"alpine-logger"
}

This table defines all possible keys for the container logger JSON:

Key Value Default Description
file, lxc or console string mandatory path of a file in the rootfs in case of file key. enable in case of lxc or console key
maxsize integer mandatory max file size in bytes before truncating
truncate true or false mandatory truncate the file when reaching maxsize
name string mandatory logger daemon name

condition

This JSON allows to configure a condition. An example of this looks like:

{
    "key": "one_condition",
    "value": "true"
}

This table defines the keys for each condition:

Key Value Default Description
container string * (any container) name of the container that must report the condition
key string mandatory name of the condition
value string mandatory expected value

Special key status attached to a container can be used to create a condition that is automatically reported by Pantavisor when the status of that container changes.

disks.json

This JSON allows to add new disks. An example of this JSON shows it is just a list of JSONs with the following format:

[
    {
        "default": "yes",
        "name": "built-in",
        "path": "/storage/disks/",
        "type": "directory"
    },
    {
        "name": "dm-versatile",
        "options": "....",
        "path": "/storage/dm-crypt-file/disk1/versatile.img,8,versatile_key",
        "type": "dm-crypt-versatile"
    },
    {
        "name": "dm-caam",
        "options": "....",
        "path": "/storage/dm-crypt-file/disk1/caam.img,8,caam_key",
        "type": "dm-crypt-caam"
    },
    {
        "name": "dm-dcp",
        "options": "....",
        "path": "/storage/dm-crypt-file/disk1/dcp.img,8,dcp_key",
        "type": "dm-crypt-dcp"
    }
]

This table defines the keys for each condition:

Key Value Default Description
default yes or no no all volumes without specific disk name will use this disk
name string mandatory unique name of the disk to be used in container storage
path path mandatory destination mount path in case of directory. For crypt disk, please refer below
type directory, dm-crypt-versatile, dm-crypt-caam or dm-crypt-dcp mandatory type of disk
options string empty options to be passed for mount command -o

Device mapper crypt disk follows a special pattern in path:

image,size,key

image: disk path which will be encrypted (created during first boot if not present) size: size in MB used to create the disk file key: name of the key file which needs to be created using respective tools (e.g. caam-keygen for i.Mx CAAM)

For example:

"path": "/storage/dm-crypt-file/disk1/file.img,8,key"

_sigs/container.json

This JSON allows to sign a group of artifacts from the state. It must follow the standard JWS format:

{
    "#spec": "pvs@2",
    "protected": "XXXX",
    "signature": "XXXX"
}

This table defines the keys for the signature JSON:

Key Value Default Description
#spec pvs@2 mandatory version of the signature JSON
protected base64 encoded protected mandatory information about how the signature was created
signature base64 encoded hash mandatory the signature itself

protected

This JSON allows to reproduce the signature hash from _sigs/container.json. It must follow the standard JWS format:

{
    "alg":"RS256",
    "typ":"PVS",
    "pvs": {
        "include":["pv-avahi/**","_config/pv-avahi/**"],
        "exclude":["pv-avahi/src.json"]
    },
    "x5c": [
        "XXXX",
        "XXXX"
    ]
}
Key Value Default Description
alg RS256, ES256, ES384 or ES512 mandatory cryptography algorithm to generate the signature
typ PVS mandatory type of signature
pvs lists of included and excluded paths mandatory relative paths to the files that were used to generate the signature
x5c list of certificate strings empty certificate that contains the public key plus more certificates from the chain of trust

_config/container/

This directory can be used to attach additional files to the container rootfs.

For example, if we wanted to overwrite the main pvr-sdk configuration file, we would do it by adding the desired file to the _config directory in the JSON state:

_config/pvr-sdk/etc/pvr-sdk/config.json

Which would set that file in the pvr-sdk container rootfs like this:

/etc/pvr-sdk/config.json

Format Exceptions

The files in this section are meant to be used for tooling (like pvr) and thus ignored by Pantavisor.

bsp/src.json

{
  "#spec": "bsp-manifest-src@1",
  "pvr": "https://pvr.pantahub.com/pantahub-ci/arm_rpi64_bsp_latest#bsp"
}

bsp/build.json

{
  "altrepogroups": "",
  "branch": "master",
  "commit": "e2a4911eb35de2032e85f74c8f239de81c6f622b",
  "gitdescribe": "014-rc14-18-ge2a4911",
  "pipeline": "436189414",
  "platform": "rpi64",
  "project": "pantacor/pv-manifest",
  "pvrversion": "pvr version 026-52-gbf3bd5d6",
  "target": "arm-rpi64",
  "time": "2021-12-24 01:25:27 +0000"
}

container/src.json

{
  "#spec": "service-manifest-src@1",
  "docker_config": {
    "AttachStderr": false,
    "AttachStdin": false,
    "AttachStdout": false,
    "Cmd": [
      "/sbin/init"
    ],
    "Domainname": "",
    "Env": [
      "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
    ],
    "Hostname": "",
    "Image": "sha256:701f4bbc1d5b707fc7daabf637cb2fa12532d05ceea6be24f8bb15a55805843b",
    "OpenStdin": false,
    "StdinOnce": false,
    "Tty": false,
    "User": "",
    "WorkingDir": ""
  },
  "docker_digest": "registry.gitlab.com/pantacor/pv-platforms/pv-avahi@sha256:895b2af2b5d407235f2b8c7c568532108a44946898694282340ef0315e2afb28",
  "docker_name": "registry.gitlab.com/pantacor/pv-platforms/pv-avahi",
  "docker_source": "remote,local",
  "docker_tag": "arm32v6",
  "persistence": {},
  "template": "builtin-lxc-docker"
}