Pantavisor Metadata

This page contains reference information about Pantavisor metadata.

Device metadata

This is the device metadata created by Pantavisor that will give you useful information about your device:

Key	Value	Description
interfaces	json	network interfaces of the device, keyed by <iface>.<family> where family is ipv4, ipv6 or mac (see below)
pantahub.address	IP:port	Pantacor Hub address the client is communicating with
pantahub.claimed	0 or 1	1 if claimed in Pantacor Hub
pantahub.online	0 or 1	1 if connection to Pantacor Hub was established
pantahub.state	string	see Pantacor Hub states (init, register, claim, sync, login, wait hub, report, idle, prep download or download)
pantavisor.arch	string	CPU architecture
pantavisor.claimed	0 or 1	1 if device has ever been claimed (local or remote)
pantavisor.cpumodel	string	CPU model name
pantavisor.dtmodel	string	Device Tree model name
pantavisor.mode	local or remote	see operation modes
pantavisor.revision	string	revision number
pantavisor.status	string	revision status
pantavisor.uname	json	uname output
pantavisor.version	string	Pantavisor build version
storage	json	disk usage of the device (see refreshed on read)
sysinfo	json	sysinfo plus uptime and idle (see sysinfo format)
time	json	time information (see refreshed on read)

Refreshed on read

sysinfo, storage and time are measurements, not state: they are re-read every time the device metadata is serialized, so a read always answers with the current value rather than one captured at boot. Because they change on every read they are never written to the persistent device metadata directory (PV_CACHE_DEVMETADIR); an older copy left there by a previous Pantavisor version is removed on start.

Every other key keeps its existing behaviour: its producer publishes it when it changes, and the value is persisted.

# both reads report the current uptime, not the boot-time one
pvcontrol devmeta ls | jq .sysinfo.uptime
sleep 5
pvcontrol devmeta ls | jq .sysinfo.uptime

sysinfo format

sysinfo carries the fields of sysinfo(2) plus two taken from /proc/uptime:

Field	Description
uptime	seconds since boot, with the centisecond precision /proc/uptime provides
idle	seconds all CPUs spent idle, summed over every CPU, so on an SMP machine it can exceed uptime. Absent when /proc/uptime cannot be read

When /proc/uptime is unavailable, uptime falls back to the whole-second value from sysinfo(2) and idle is omitted.

Change thresholds

Device metadata is pushed to Pantacor Hub every PH_METADATA_DEVMETA_INTERVAL seconds, but a push only happens when the payload actually changed in a way worth reporting:

• Most keys are compared verbatim: any change is pushed.
• Numeric fields inside sysinfo and storage need a relative change of at least PH_METADATA_DEVMETA_THRESHOLD percent (loads.* need 10%, procs 5%). Fields describing the machine itself — totalram, totalswap, totalhigh, mem_unit, storage.total, storage.reserved — are compared verbatim.
• sysinfo.uptime, sysinfo.idle and time never trigger a push on their own: they only ever move forward and Hub can derive them from the moment it received the push. They are still included in whatever gets pushed.

Regardless of the above, a push always happens at least every PH_METADATA_DEVMETA_HEARTBEAT seconds, after re-authenticating with Hub, and whenever a container wrote device metadata through pv-ctrl that has not reached Hub yet.

interfaces format

The interfaces device metadata is a JSON object keyed by <iface>.<family>. Each value is an array, since an interface can hold multiple addresses of the same family. The mac family carries the interface hardware (MAC) address; interfaces without a hardware address (e.g. lo) have no mac entry.

{
  "eth0.mac": ["b8:27:eb:00:11:22"],
  "eth0.ipv4": ["192.168.1.10"],
  "eth0.ipv6": ["fe80::ba27:ebff:fe00:1122"],
  "lo.ipv4": ["127.0.0.1"],
  "lo.ipv6": ["::1"]
}

User metadata

This is the user metadata that can be set by the user which is parsed and have some actions on Pantavisor:

Key	Value	Description
pvr-sdk.authorized_keys	SSH pub key	set public key to get SSH access
pvr-auto-follow.url	URL	device will automatically pull every change in the device associated to that clone URL
pantahub.log.push	0 or 1	disable/enable log pushing to Pantacor Hub. Overrides PV_LOG_PUSH
<config-key>	config-value	override any configuration keys that allow RUN level
<container>/<key>	value	send user metadata that can be consumed by one of the containers