Skip to main content
Version: master

Storage

Pantavisor needs some persistent artifacts on disk to perform several operations such as storing revisions, updates, disks, logs and other RW operations.

These artifacts are stored in the PVROOT partition, which is mounted to /storage by Pantavisor during initialization.

Its structure is as follows:

.
├── boot # bootloader files
│   ├── boot.scr
│   └── uboot.txt
├── cache # metadata
│   ├── devmeta
│   ├── dropbear
│   └── usrmeta
├── config # Pantacor Hub RW configuration
│   ├── pantahub.config
│   └── unclaimed.config
├── disks # persistent container and Pantavisor storage
├── logs # container and Pantavisor logs are centralized here
├── objects # general revision artifacts
│   ├── 1dc4107c036a14aac38b5218fe50a8c5fa9e73d92a1d24337a57cd833c0a8797
│   ├── 2c0236e022c8bed4af695a96504ee7ece2b43e0d57f5a4d4181edb028539f061
│   ├── 8debde333d3885abf03cb7f954017744c8e2fc6708f89f0a4771b0bf367fd2a6
│   ├── 97bf54227c91cd93b540785942e4884ac6a7352fcea84afc3e0b8d174c7e4825
│   ├── ac1a09142f25a8df6742a3da290008f99c05c7b83d2754d9928f1a081714eaed
│   ├── b236948bd3caaf31c00af82fbeeb0816962e39a96ad6c5cf9bfc1a547cdbe005
│   ├── b6959af6ef61ae8ff729a9e5e41a8fdf5f318bd6ef1d21d38dc796d0db7e7627
│   └── f4b9d24c631cd1bcc303cedd3b9b3c6d32556b1975ac4262e823bf5d9affbc9f
├── trails # state JSON of each revision with objects hardlinks
│   └── 0 # Pantavisor checkout for revision 0
│   ├── _sigs
│   │   └── bsp.json # .json files are shipped inline, no hardlink
│   ├── bsp
│   │   ├── drivers.json
│   │   ├── firmware.squashfs # this is a hardlink to an object
│   │   ├── modules_6.1.77+.squashfs
│   │   ├── modules_6.1.77-v7+.squashfs
│   │   ├── modules_6.1.77-v7l+.squashfs
│   │   ├── modules_6.1.77-v8+.squashfs
│   │   ├── modules_6.1.77-v8-16k+.squashfs
│   │   ├── pantavisor-rpi.img.gz
│   │   ├── run.json
│   │   └── trail.config
│   ├── device.json
│   ├── .pvr/json # full revision state JSON
│   ├── <container-1-name>
│   ├── <container-2-name>
│ └── ...
...

Boot​

Contains revision number information written by Pantavisor and consumed by the bootloader so it can run the proper revision after powering off and rebooting.

This directory is managed entirely by Pantavisor; there is no direct user action here. It is updated as a side effect of committing a revision with pvcontrol cmd run-commit locals/<rev> (see Commands).

Cache​

Mainly to store information that is not fixed to any given revision.

Metadata​

Metadata is the information that is exchanged between Pantavisor and the outside world, either remotely or locally, that is not attached to a revision itself.

Metadata is just a list of key-value pairs of string type. This list is persistent and stored on disk. By default, it is saved in plain text, but this can be changed in favour of volumes on a crypt disk.

Device metadata​

This type of metadata is meant to be generated by Pantavisor or any of the running containers to expose internal information.

The list of device metadata is persistent on disk and can be managed locally by mgmt containers. Their values will be uploaded to the cloud in remote mode.

To list, set or remove device metadata by hand, use pvcontrol:

pvcontrol devmeta ls
pvcontrol devmeta save my-key "my-value"
pvcontrol devmeta delete my-key

Check the list of default key-value pairs that Pantavisor sends.

User metadata​

This type of metadata is meant to be generated by the user so Pantavisor or any of the containers can consume it.

The list of user metadata is persistent on disk, can be managed locally by mgmt containers. Their values will be deleted or overwritten by the list stored in the cloud in remote mode.

To list, set or remove user metadata by hand, use pvcontrol:

pvcontrol usrmeta ls
pvcontrol usrmeta save my-key "my-value"
pvcontrol usrmeta delete my-key

Check out the list of default user metadata consumed by Pantavisor.

Config​

Stores the PH_ prefixed keys of the configuration. This includes the Pantacor Hub client credentials. During an identity reset, it also holds parent.config, the PH_ keys of the previous Hub device, until the new one confirms the reset.

These configuration keys are persistent. By default, they are saved in plain text, but this can be changed if set to a volume assigned to a crypt disk.

These credentials are written automatically when the device registers with and is claimed by Pantacor Hub. A registered device keeps its credentials in unclaimed.config until it is claimed, then in pantahub.config. To wipe them and force the device to register a new identity (e.g. to re-claim it), run:

pvcontrol cmd reset-identity

The device must be running a DONE local revision with remote control enabled (PV_CONTROL_REMOTE). The device owner can also trigger this from Pantacor Hub. Resetting the identity also runs the garbage collector, so the revisions of the previous Hub device are removed.

See Commands.

Disks​

Pantavisor manages persistent disk definitions inside device.json. Supported types include dm-crypt volumes with hardware-backed keys (CAAM, DCP, versatile), swap devices, plain ext4/ext3 volumes, and composite dual disks for key migration. See the full Disks overview for type details and examples.

Each disk, with the exception of swap disks, can be privately used by containers or internally by Pantavisor volumes, as in the case of metadata.

Volumes​

Additional volumes can be specified to be used internally by Pantavisor. These are some special cases that can be configured as volumes:

  • pv--devmeta: if defined, Pantavisor will use this volume to save and load device metadata.
  • pv--usrmeta: if defined, Pantavisor will use this volume to save and load user metadata.
  • pv--phconfig: when defined, Pantavisor will reserve this volume to save and load Pantacor Hub credentials. To make Pantavisor use it, it has to be forced from configuration with the key PV_STORAGE_PHCONFIG_VOL.
  • pv--firmware: when defined, Pantavisor will publish this volume's mount-point to the kernel firmware loader by writing it to /sys/module/firmware_class/parameters/path. The kernel will then search this directory first before falling through to the defaults under /lib/firmware. The volume is intended as a writable drop-zone where management containers can place customized firmware (e.g. board-specific NVRAM or calibration blobs) for the kernel to pick up — without modifying the rootfs. To make Pantavisor use it, it has to be forced from configuration with the key PV_STORAGE_FIRMWARE_VOL; if the flag is set but the volume is missing from device.json, state-start fails and the standard tryboot rollback is triggered.

Logs​

Pantavisor can centralize all of your container logs, separated by revision, in one place on-disk. It does so by running a small server (Log Server) which offers a set of sockets to the containers.

To check the Log Server's current configuration on a running device, use pvcontrol:

pvcontrol conf ls | grep -i log # e.g. PV_LOG_SERVER_OUTPUTS, PV_LOG_LEVEL, PV_LOG_DIR

Log sockets​

The Log Server listens on three kinds of socket:

  • pv-ctrl-log: to send log traces.
  • pv-fd-log: to subscribe file descriptors, which Pantavisor then polls and logs on the container's behalf.
  • /dev/log: one datagram socket per container, for standard syslog clients.

/dev/log​

Most applications already know how to log: they write syslog messages to /dev/log. Pantavisor takes advantage of that by giving every container its own datagram socket, created at <PV_SYSTEM_RUNDIR>/pv-plat-log/<container>/log.sock when the container starts and bind-mounted at /dev/log inside it. The socket is removed when the container stops or fails to start, so /dev/log exists for exactly as long as the container runs.

Two properties follow from this design:

  • Nothing is lost. The sockets are SOCK_DGRAM, which is what datagram-only syslog clients such as glibc's syslog() expect, so every message they send is captured. The two long-lived sockets, pv-ctrl-log and pv-fd-log, stay SOCK_STREAM.
  • The origin is known, not guessed. Because each container writes to a socket of its own, the container a message came from is the owner of the socket it arrived on. Nothing in the message, such as the syslog HOSTNAME, is trusted for this, and no cgroup lookup is needed. The complete rules are in Platform attribution.

Both RFC 3164 and RFC 5424 are auto-detected per message, so no configuration is needed. Applications can also send a JSON-formatted message or a key-value formatted message, to /dev/log or directly to pv-ctrl-log.

logger -t myapp "hello from myapp"
tail -f /storage/logs/0/my-container/syslog/myapp

Processes Pantavisor runs outside any container log to a separate /dev/log of Pantavisor's own, and their messages land in pantavisor/pantavisor.log.

Which containers get a socket is set globally by PV_LOG_AUTO_DEVLOG (enabled by default) and can be overridden per container with dev-log in its run.json: "dev-log": false opts one container out, and "dev-log": true opts one in while the global setting is off. The full matrix is in Per-container control.

Any standard syslog library works without modification. Use the LOCAL0 facility for container applications:

C / C++ (syslog.h), where openlog targets /dev/log by default on Linux:

#include <syslog.h>

int main(void) {
openlog("myapp", LOG_PID, LOG_LOCAL0);
syslog(LOG_INFO, "Container started");
closelog();
return 0;
}

Python (logging.handlers.SysLogHandler)

import logging
import logging.handlers

handler = logging.handlers.SysLogHandler(address="/dev/log")
logger = logging.getLogger("myapp")
logger.addHandler(handler)
logger.setLevel(logging.DEBUG)
logger.info("Container started")

Go (log/syslog)

package main

import "log/syslog"

func main() {
w, err := syslog.New(syslog.LOG_INFO|syslog.LOG_LOCAL0, "myapp")
if err != nil {
panic(err)
}
defer w.Close()
w.Info("Container started")
}

Output types​

There are a number of parameters that can be tweaked from the configuration that will affect Log Server, such as PV_LOG_CAPTURE, PV_LOG_DIR_MAXSIZE, PV_LOG_LEVEL, etc. Between those, there is an important parameter called PV_LOG_SERVER_OUTPUTS that allows to change how the logs will be stored. It is set like any other configuration key, e.g. as an environment variable at boot time:

PV_LOG_SERVER_OUTPUTS=filetree,stdout

Multiple outputs are comma-separated and combined, not mutually exclusive. The complete list of accepted values is in the log server outputs reference; the sections below explain what each one is useful for.

File tree​

This is the default option. In this case the log output will be delivered in different files by containers. Pantavisor logs will also be stored in its own directory.

Inside a container's directory the log's source becomes its path: a plain source name is filed under syslog/, while a source that already looks like a path keeps its shape, which is how the lxc logs end up under lxc/. This holds whatever protocol delivered the message, so a JSON message sent to pv-ctrl-log lands under syslog/ too, not only syslog text from /dev/log:

logs/<revision>/<container>/
├── syslog/
│ ├── myapp <- RFC 3164 via /dev/log
│ ├── jsonapp <- JSON via pv-ctrl-log
│ └── messages
└── lxc/
├── lxc.log
└── console.log

A source that would climb out of the container's directory (anything with ..) is filed as syslog/unknown-src instead, so a container can never write outside its own directory. The complete rule is in Filetree paths.

Browse and tail these files directly under /storage/logs/<revision>/<container>/:

ls /storage/logs/0/ # containers logged for revision 0
ls /storage/logs/0/my-container/syslog/ # sources logged by my-container
tail -f /storage/logs/0/my-container/syslog/myapp
tail -f /storage/logs/0/my-container/lxc/console.log
tail -f /storage/logs/0/pantavisor/pantavisor.log

Single file​

With this option, all logs will be centralized in one file. These logs are delivered in a JSON following this structure:

{
"tsec":9,
"tnano":0,
"plat":"pantavisor",
"lvl":"DEBUG",
"src":"logserver",
"msg": "starting logserver loop"
}

tsec is seconds since boot by default (tnano is currently always 0). Setting PV_LOG_TIMESTAMP to absolute switches every sink to Unix epoch instead.

Enable it with PV_LOG_SERVER_OUTPUTS=singlefile and tail the result with jq for readable output:

tail -f /storage/logs/0/pv.log | jq -c '{tsec, plat, lvl, msg}'

Standard Output​

Outputs logs into stdout, which can be useful for debugging. Unlike stdout_direct, this sink is processed by the log server. This will provide more control on the output than its direct counterpart and a way of working that is more similar to the other sinks.

note

In embedded mode, this is the same as sending the logs to dmesg. You can set ignore_loglevel and printk.devkmsg=on in cmdline to get all messages on console.

Standard Output Pantavisor​

Same as Standard Ouput but filtering all messages except Pantavisor ones.

Standard Output Containers​

Same as Standard Ouput but filtering all messages except container ones.

Standard Output Direct​

Outputs logs into stdout. Unlinke stdout, this sink is not processed by the log server. This means the logs will be directly printed without going through the server. It will have a faster response and will provide logs during device initialization and teardown, when plain stdout would not be available.

This sink will be automatically enabled when stdout is enabled and log server is not available. That is, before its initialization and after its shutdown. Furthermore, it will always let pass all FATAL level log messages through.

NULL Sink​

Send logs to /dev/null.

Timestamp format​

Every output except the NULL Sink prefixes each line with a timestamp. The format is configurable per sink, either as one of the Go time layout constants or as an arbitrary strftime format string. See timestamp formats for the accepted values and the keys that set them.

Console alerts​

Some events are worth seeing live, as they happen, not only in the logs afterwards — a container starting during boot, for example. Pantavisor writes those events to /dev/console as console alerts: one line per event, in addition to the normal log entry. Only someone watching the serial console sees them; they are never sent to SSH or other remote sessions:

[ 6.217276] [PANTAVISOR] [platforms] WALL: platform 'awconnect' status is now STARTING
[ 6.341446] [PANTAVISOR] [platforms] WALL: platform 'awconnect' status is now STARTED

The timestamp is seconds since boot, the same way dmesg prints one, so alerts line up with kernel messages on the same console.

Alerts cover container status changes and every ERROR and FATAL that Pantavisor itself logs; container logs are not mirrored. An alert reaches the console even when PV_LOG_LEVEL keeps it out of the logs. When a stdout output type is configured, Pantavisor enables the kernel's ignore_loglevel so that copy of the message reaches the console too, and sets it back to its previous value once no stdout output is left; the alert is then skipped so the line does not appear twice. stdout.containers never carries Pantavisor's own messages, so it does not count.

Alerts are on by default, and can be turned off with PV_LOG_CONSOLE_ALERTS, either at boot or at runtime through user metadata:

PV_LOG_CONSOLE_ALERTS=0 # at boot
pvcontrol usrmeta save PV_LOG_CONSOLE_ALERTS 0 # at runtime, from the next message
pvcontrol usrmeta delete PV_LOG_CONSOLE_ALERTS # back to the boot value

Disabling them only silences the console; logging still follows PV_LOG_LEVEL. See console alerts for the line format, the complete list of what emits them and how they relate to the log level — today, container status changes and Pantavisor errors.

Liveness lines​

Per-poll lines for Hub requests are logged at TRACE, so a device at the default level can look silent for hours. Two lines show Pantavisor is still running:

LineLevelIntervalSays
alive: ...INFOPV_LOG_HEARTBEAT_INTERVAL, 10min by defaultrevision, state, Hub status, containers started and how long Pantavisor has been running
hub: ...DEBUGPH_LOG_SUMMARY_INTERVAL, 60 s by defaultHub requests and failures since the previous line

The alive: line is the local sign of life and is logged in every mode. The first one comes one interval after Pantavisor settles into its wait state, not at boot. The running time is measured with the boot clock, so it keeps counting while the system is suspended:

alive: revision 42, state WAIT, hub online, 5/5 containers started, running for 3h12m

The Hub status is local mode, device not claimed, not logged in, offline or online; the alive: line prints it as hub <status>.

The hub: line only exists while the Hub client is running, so there is none in local mode. It counts every request to the Hub (registration, claim, login, sync, polls, uploads and downloads) and the ones that failed, over the time since the previous line. The status in parentheses is the same as above, without local mode. When nothing was requested it says so:

hub: 12 requests, 0 failures in 60s (online)
hub: no requests in 60s (offline)

The hub: line needs PV_LOG_LEVEL=5 or higher.

PV_LOG_HEARTBEAT_INTERVAL goes in pantavisor.config and PH_LOG_SUMMARY_INTERVAL in pantahub.config; either can also be set in the OEM config. To change or turn them off from the device:

pvcontrol usrmeta save PV_LOG_HEARTBEAT_INTERVAL 5min # every 5 minutes
pvcontrol usrmeta save PV_LOG_HEARTBEAT_INTERVAL 0 # off
pvcontrol usrmeta delete PV_LOG_HEARTBEAT_INTERVAL # back to the default
pvcontrol usrmeta save PH_LOG_SUMMARY_INTERVAL 0 # no hub: lines

A change takes effect the next time the interval is checked:

LineCheckedTypical delay
alive:on every pass of the wait stateabout 2 seconds
hub:every time the Hub client handles an answer from the Hub or changes statea few seconds while the Hub answers (the update poll runs every PH_UPDATER_INTERVAL, 5 s by default), longer when the Hub is slow to answer

While PH_LOG_SUMMARY_INTERVAL is 0 the counts are dropped, so the first hub: line after turning it back on covers only the time since then.

Log Directory Size Management​

Pantavisor manages log storage at two levels:

  1. Per-file rotation — individual log files are compressed in place once they reach the per-file rotation threshold (derived from PV_LOG_DIR_MAXSIZE and PV_LOG_ROTATE_FACTOR).
  2. Directory-level management — the total size of the log directory is kept within a configurable budget using a watermark-based cleanup algorithm.

Auto-sizing (zero-config)​

When PV_LOG_DIR_MAXSIZE is set to 0 (the default), Pantavisor automatically determines the log budget at startup by inspecting /proc/mounts to identify the filesystem backing the log directory:

  • tmpfs: budget = 100% of the partition size (the log partition is in RAM, so all of it can be used for logs)
  • Block device: budget = 10% of the partition size (conservative default to share storage with other data)

Partition size is read from /sys/class/block/<dev>/size (kernel sectors × 512 B) with a statvfs() fallback.

Manual sizing​

Set PV_LOG_DIR_MAXSIZE to an explicit value: a plain byte count, a size with a unit suffix (256MB, 1GB, 512K), or a percentage of the underlying partition (20%).

Values exceeding the available partition capacity are rejected and fall back to the auto-calculated default.

Watermark-based cleanup​

Pantavisor tracks the total size of the log directory and applies a high/low watermark algorithm to keep disk usage in check without constant thrashing:

hysteresis_gap = PV_LOG_DIR_MAXSIZE / PV_LOG_HYSTERESIS_FACTOR
high_watermark = PV_LOG_DIR_MAXSIZE × 0.90
low_watermark = PV_LOG_DIR_MAXSIZE - hysteresis_gap
rotation_size = hysteresis_gap / PV_LOG_ROTATE_FACTOR

How cleanup works:

  1. Every 100 log messages the current log directory size is recalculated.
  2. If current_size > high_watermark, deletion is triggered.
  3. The oldest compressed log files are deleted from the largest subdirectories first.
  4. Deletion continues until current_size < low_watermark.

Example with defaults and an auto-calculated budget of 512 MB:

hysteresis_gap = 512 MB / 4 = 128 MB
high_watermark = 512 MB × 0.90 ≈ 460 MB → cleanup starts here
low_watermark = 512 MB - 128 MB = 384 MB → cleanup stops here
rotation_size = 128 MB / 5 ≈ 25 MB → per-file size before rotation

The three keys behind this (PV_LOG_DIR_MAXSIZE, PV_LOG_HYSTERESIS_FACTOR and PV_LOG_ROTATE_FACTOR) are documented with their defaults and levels in the configuration reference.

Log persistence and flash wear​

Syncing every log line to disk turns each line into a full flash page write plus a journal commit, which wears flash storage quickly. With the default PV_LOG_SYNC=smart, the filetree and singlefile outputs use plain buffered writes and the kernel decides when to write them back. Writes are synced immediately only in these cases:

  • ERROR and FATAL messages.
  • The boot window: it lasts at least PV_LOG_SYNC_BOOT_WINDOW seconds (default 120) after the log server starts and is extended until Pantavisor reaches READY, so boot problems are not lost. If a revision never reaches READY, the window stays open and every write stays synced, which keeps the logs of the failing boot. PV_LOG_SYNC_BOOT_WINDOW=0 disables the boot window altogether.
  • While an update is being installed or a new revision is being tested, until it is committed or rolled back.

Buffered logs can be lost on sudden power loss. They are not held back indefinitely: ext4 with the default data=ordered mode commits its journal every 5 seconds and flushes appended data with it, so steady-state writes are bounded by the filesystem commit interval, not zero. Pantavisor also calls sync() before reboot and shutdown. These keys are read when the log server starts, so set them in pantavisor.config, an OEM config or on the kernel command line; user metadata and pvcontrol conf changes do not reach it. Set always to sync every write:

PV_LOG_SYNC=always # sync every write (more flash wear)
PV_LOG_SYNC_BOOT_WINDOW=0 # no synchronous boot window

Trails and objects​

Pantavisor trails, with their state JSONs are stored for each installed revision. The rest of artifacts that can be shared between revisions, are called objects and are stored separately so objects can belong to different revisions at the same time.

Trails (steps) and objects can be inspected and managed locally with pvcontrol:

pvcontrol steps ls # list installed revisions
pvcontrol steps get current # state.json of the running revision
pvcontrol objects ls # list content-addressed objects on disk

See Steps and Objects for the full command set, including uploading/downloading objects and installing packaged revisions.

Update progress​

A progress JSON is stored with update info relevant to each revision. This JSON contains persistent information useful for remote experience reporting but also for local experience debugging of failed updates:

{
"status":"ERROR",
"status-msg":"Status goal not reached",
"progress":100,
"retries":0,
"logs":
"{\"tsec\":14457,\"tnano\":0,\"platform\":\"pantavisor\",\"lvl\":\"ERROR\",\"src\":\"platforms\",\"msg\":\"platform 'pvr-sdk_ready' status goal timed out after waiting for more than 30 secs\"}\n
{\"tsec\":14457,\"tnano\":0,\"platform\":\"pantavisor\",\"lvl\":\"ERROR\",\"src\":\"controller\",\"msg\":\"timed out before all goals were met. Rolling back...\"}\n"
}

Update progress can be consulted locally using the ctrl steps endpoint, or with pvcontrol:

pvcontrol steps show-progress current # progress of the running revision
pvcontrol steps show-progress <rev> # progress of a specific revision

Integrity​

Pantavisor offers secureboot, a security mechanism to ensure integrity of the artifacts that are part of a revision. As revisions are composed of a state JSON and a series of artifacts pointed by that JSON, Pantavisor can perform a double level validation: artifact checksum and state signature.

Artifact Checksum​

Objects belonging to the revision that is about to be run after boot up are checked against the checksums stored in their state JSON by default.

As running a full SHA hashsum of all artifacts can be time consuming for low spec targets and thus increase boot up time, a lazy integrity validation on container storage can be performed using handlers, which are specified at the state JSON. Handlers are scripts to mount/unmount volumes. The only supported handler so far is dm-verity. Volumes protected by dm-verity skip the boot checksum only while the handler runs, which is controlled by PV_SECUREBOOT_HANDLERS (pvcontrol conf ls shows the effective value); with it set to 0, they are checksummed like every other object.

Checksum can also be totally disabled at the configuration level if boot up speed needs to be boosted further, with the PV_SECUREBOOT_CHECKSUM key.

State Signature​

Additionally to artifact checksum, the state JSON can be signed. This can be done from your host computer or from an automated CI, and it is then validated from Pantavisor using a cryptographic hash algorithm. It can be tuned according to one of these three levels of severity:

  • disabled: no signature validation will be performed.
  • audit: all validations from lenient and strict will be performed, errors will be reflected in log but nothing will fail.
  • lenient: only the signed artifacts in the revision will be validated. Enabled by default.
  • strict: all artifacts in the revision must be signed and will be validated.

Validation is performed in Pantavisor at two points:

  • when booting up, right after Pantavisor is initialized and before the current revision is loaded. In case of failure, the update will be reported as ERROR if possible and the device will either rollback or just reset.
  • when a new remote update is received or a new local update is run. In case of failure, the update will be reported as WONTGO.

In either case, Pantavisor will parse all signatures, parse the protected JSON, calculate the hash depending on the elements included in the JSON and compare them with the signatures.

Right now, RS256, ES256, ES384 and ES512 algorithms are supported and Pantavisor must know the public key either by directly storing it on disk or by using a certificate chain.

On-disk public key​
note

We recommend to use the certificate chain of trust for your field devices.

In this option, Pantavisor will need the RSA public key to be stored on disk. You can store it during build time from the ca/ directory.

It will need the signature and information about how to generate it in the revision checkout. We offer pvr sig for convenience.

Certificate chain of trust​

In this case, the public key will travel in the revision checkout in a x509 certificate. The certificate will be validated by Pantavisor against a root certificate located on disk .

The root certificate is placed during Pantavisor build. The build system will extract the files from the ca/ directory.

Depending on the subject CN of the signature certificate, we validate it with the following criteria:

  • If the subject CN is equal to the value set in PV_OEM_NAME from your configuration and the signature does not includes any artifact in the BSP or OEM configuration directories, as those are can only be secured by the default root certificate, we validate it against the OEM root certificate.
  • For every other case, the signature is validated against the default root certificate.

It will also need the signature and information about how to generate it in the revision checkout. For this, you can use pvr sig command.

Garbage Collector​

The Pantavisor garbage collector is in charge of cleaning up the /storage by automatically removing unused Pantavisor artifacts.

It works by removing logs, trails and stored disks that belong to old revisions. After all this, all orphan objects that were linked to removed revisions are deleted too.

The garbage collector will not affect any of the files related to the running revision, the revision that is being updated or the latest DONE revision. These revisions that are not affected by the garbage collector can be expanded to the factory revision using the PV_STORAGE_GC_KEEP_FACTORY configuration parameter.

Currently, it can be triggered by three different events:

  • by a remote update that requires more disk space than available
  • if a threshold of disk usage is surpassed
  • with a command

Remote update​

If a remote update requires more disk space than available, the garbage collector will be activated. This can be adjusted with the configuration PV_STORAGE_GC_RESERVED parameter.

note

This type of trigger will not work with local updates. For those, you will need to use one of the following two options.

Threshold​

Disk usage will be checked periodically and garbage collector will be activated if that threshold is reached. By default it is disabled. This can be changed with the PV_STORAGE_GC_THRESHOLD parameter.

If an object is put using the objects endpoint, the threshold will be disabled temporarily, which is done to avoid removing objects that could be linked to the upcoming new revision. This parameter can be changed from the configuration.

On Demand​

Finally, our garbage collector can be triggered on demand issuing a command through Pantavisor control socket, or with pvcontrol:

pvcontrol cmd run-gc # queue a GC cycle on the state machine, returns immediately
pvcontrol storage gc # run GC synchronously, reports bytes reclaimed

See pvcontrol Storage for the difference between the two.

Reference​

  • Log Sockets — log socket protocols, output sinks, timestamp formats
  • Configuration — every PV_LOG_*, PV_STORAGE_* and PV_CACHE_* key
  • Metadata — every device and user metadata key
  • State Format — the state.json stored in each trail