Send vCons to vcon store - NormB/sipnab GitHub Wiki
vcon.store is a hosted store for
vCons. This page sends the containers sipnab writes to it.
It uses sipnab --vcon-forward, the forwarder that
Deliver the spool to a store
describes.
The forwarder sends each container byte for byte: it does not change what sipnab wrote.
-
A sipnab binary that carries the
vconfeature. The exporter, the forwarder and the fetcher are part of it.sipnab --versionlists the features of a binary.- The
-noaudiopackages carry it from 0.5.253. - The static musl build does not carry it.
- The
- A capture file that holds the calls to send.
-
A token from the other system, vcon.store. The steps call it
$VCON_STORE_TOKEN. Nothing else changes on vcon.store until the forwarder sends a container. - HTTPS from this machine to
api.vcon.store. - A decision on what may leave the machine. Before you send anything lists what a container carries.
The hosted vcon.store service was not used to check this page. On 2026-11-03
the sipnab commands on it ran with sipnab 0.5.232, built from source, on
Ubuntu 24.04.5 (aarch64), against a local stand-in on 127.0.0.1:18777. The
stand-in is a short test server that answers the four routes this page uses
the way it describes vcon.store doing: POST /v1/vcons (201, or 409 for a
uuid it holds), PUT /v1/vcons/{uuid}, GET /v1/vcons/{uuid} with a _meta
member, and 401 for a wrong token. The log lines on this page have the form that run
printed, and name 127.0.0.1:18777. The response bodies quoted in them, such
as {"error":"unauthorized"} and {"error": "vCon already exists"}, are a
test server's, not the hosted service's. Against the hosted service the lines
name https://api.vcon.store.
What that run checked is sipnab's side:
- the
vcon-storekind adds/v1/vconsto the base URL and sends the token asAuthorization: Bearer <token>; - the forwarder refuses a token file other users can read, and exits
2; - the exit status for each answer, and where each container goes;
-
--vcon-forward-replace-urlsends aPUTafter a409; - the fetcher removes
_meta.
What it did not check is the hosted service's side: its real answers, its
error bodies, and the Cloudflare 403 with error code: 1010 under
When something does not work. Those come
from the service and were not observed in this check. The routes and the
container shape the service documents are in its OpenAPI document, vendored
as tests/schemas/vcon-store-openapi.json (vcon.store API 0.1.0), and
tests/vcon_ingest_contract_test.rs checks sipnab's containers against the
VCon schema in it. That document lists no 409 and no 401.
A capture carries personal data:
- telephone numbers,
- addresses,
- the headers your platform sets,
- with
--retain-audio, the call audio.
vcon.store is another party's system. Decide what may leave the machine first:
-
--redactreplaces identities, addresses and correlation identifiers with keyed tokens. It also withholds the audio.- It works on a capture file (
-I), not on a live capture.
- It works on a capture file (
- A redacted container carries no audio. Its
recordingDialog Object names the parties and has nobody. - A container exported without
--redactand with--retain-audiocarries the call audio and the identifiers the signaling carried, as captured. - What may you conclude lists what a container carries.
Export the calls from a capture file with their audio.
-
--retain-audiokeeps each call's audio whole, from the first frame. - It makes sipnab put the audio in its
recordingDialog Object. - The object names the parties when each audio channel came from the media
address and port that one party advertised in its own SDP.
- Otherwise the object has no
parties. That is the usual case when a media relay carries the audio.
- Otherwise the object has no
- This container is not redacted. It carries the audio and the identifiers as captured.
sipnab -N --no-cli-print -I calls.pcap --retain-audio \
--export-vcon-when "state == 'Completed'" --export-vcon-dir spoolsipnab prints one line for the directory:
Wrote 1 vCon container(s) to 'spool'.
Add --redact and remove --retain-audio. The same command then writes
redacted containers without audio.
vcon.store authenticates with a bearer token.
- Put the token alone in a file only you can read.
- The
vcon-storekind sends it asAuthorization: Bearer <token>.
# Run all of these, in order.
umask 077
printf '%s\n' "$VCON_STORE_TOKEN" > vcon-store.key$VCON_STORE_TOKEN is the token vcon.store issued you.
- The forwarder never prints it.
- The forwarder removes it from any answer it keeps.
- Instead of a file, the
SIPNAB_VCON_FORWARD_AUTHenvironment variable can hold the token.
The forwarder refuses a file that other users can read or write, and exits
2:
--vcon-forward-auth-file 'vcon-store.key' can be read or written by other users (mode 0644); chmod 600 it
Run chmod 600 vcon-store.key and start the forwarder again.
# Run all of these, in order.
STORE_URL=https://api.vcon.store
sipnab --vcon-forward spool --vcon-forward-kind vcon-store \
--vcon-forward-url "$STORE_URL" --vcon-forward-auth-file vcon-store.key \
--vcon-forward-once
echo "exit $?"--vcon-forward-kind vcon-store does two things:
- It adds
/v1/vconsto the base URL. - It forms the header from the token.
It does not change the container. The same settings can live in sipnab.toml:
[vcon_forward]
kind = "vcon-store"
url = "https://api.vcon.store"
auth_file = "/etc/sipnab/vcon-store.key"For each container the forwarder logs a delivered line with the store's
status and moves the file to spool/delivered. The log line has this form
(here from the local stand-in on 127.0.0.1:18777, not the hosted store):
INFO sipnab::app::vcon_forward: vCon forwarder watching 'spool', delivering to http://127.0.0.1:18777/v1/vcons
INFO sipnab::app::vcon_forward: delivered 1-1966_10.0.2.20-1cc03f180ff8a774.vcon.json: POST http://127.0.0.1:18777/v1/vcons answered 201; moved to 'spool/delivered'
With --vcon-forward-once, the exit status is:
-
0when the store accepted every container, or there was none; -
1when the store refused any container, or any is still waiting; -
3when the store answered401or403.
Without --vcon-forward-once, the forwarder polls the spool until you stop it.
A container the store refused is in spool/failed, with a .error.json
record beside it that holds the store's answer. To read the counts and those
answers without sending anything:
sipnab --vcon-spool-status spoolIt prints one JSON document. The delivery worked when:
-
pendingis0: no container is still waiting inspool, -
failedis0: the store refused none, -
deliveredis the number of containers the export wrote.
Before the forwarder runs, the same command shows each written container
under pending.
After one delivery and one refusal, it reads:
{
"schema_version": 1,
"as_of": "2026-10-18T15:40:37.928Z",
"note": "A snapshot of files on disk at as_of. The vCon forwarder (sipnab --vcon-forward) is a separate process that moves files out of the spool; whatever produced this answer sends, fetches, moves and deletes nothing. The delivered and failed directories are the forwarder's defaults beside the spool; a forwarder started with --vcon-forward-done or --vcon-forward-failed moves files elsewhere, and those are not counted.",
"spool": {
"path": "spool",
"exists": true
},
"delivered_dir": {
"path": "spool/delivered",
"exists": true
},
"failed_dir": {
"path": "spool/failed",
"exists": true
},
"pending": 0,
"delivered": 1,
"failed": 1,
"failures": [
{
"file": "1-1966_10.0.2.20-1cc03f180ff8a774.vcon.json",
"record": {
"at": "2026-10-18T15:40:29Z",
"body": "{\"error\": \"vCon already exists\"}",
"body_truncated": false,
"file": "1-1966_10.0.2.20-1cc03f180ff8a774.vcon.json",
"method": "POST",
"reason": null,
"status": 409,
"url": "http://127.0.0.1:18777/v1/vcons"
}
}
],
"returned": 1,
"truncated": false,
"next_cursor": null
}A capture run with --mcp or --api answers the same through:
- the MCP tool
vcon_spool_status, -
GET /v1/vcon/spool.
vcon.store answers 409 to a POST of a uuid it already holds. By default
the forwarder treats that as a refusal:
- The container goes to
spool/failed. - The store's answer is in its
.error.jsonrecord. -
--vcon-forward-onceexits1.
The log line reads:
WARN sipnab::app::vcon_forward: refused 1-1966_10.0.2.20-1cc03f180ff8a774.vcon.json: POST http://127.0.0.1:18777/v1/vcons answered 409; moved to 'spool/failed' beside 1-1966_10.0.2.20-1cc03f180ff8a774.vcon.json.error.json
To replace the held copy instead, name the store's PUT endpoint with
--vcon-forward-replace-url. The forwarder then sends the container there
after the 409. {uuid} in the template becomes the container's uuid:
sipnab --vcon-forward spool --vcon-forward-kind vcon-store --vcon-forward-url https://api.vcon.store --vcon-forward-auth-file vcon-store.key --vcon-forward-replace-url 'https://api.vcon.store/v1/vcons/{uuid}'Replacing is off by default, because it overwrites what the store holds.
To send a container that is already in spool/failed again, move it back into
spool and run the forwarder with --vcon-forward-replace-url.
The forwarder retries every 5xx answer after a back-off and keeps the
container in spool meanwhile.
sipnab signs a container only when a [[vcon.rule]] asks it to:
-
sign_only = truewrites the signed form alone, a JWS with no encryption. See Sign without encrypting. -
encrypt_towrites a signed container, encrypted. See Encrypt what a rule writes.
The containers --export-vcon-dir writes, as on this page, carry no
signature. A signature that the store adds covers what the store received. It
is not sipnab's, and it does not make an observation from a tap a recording.
sipnab records no consent, and a container carries none.
sipnab --vcon-fetch reads a container back by its uuid, with the same key
file. The vcon-store kind:
- reads
/v1/vcons/{uuid}, - sends the key as
Authorization: Bearer <key>, - removes the
_metamember the store adds.
So the file holds the container alone:
sipnab --vcon-fetch 018bcfe5-6800-8a6b-a667-78f1c5213800 --vcon-fetch-kind vcon-store --vcon-fetch-url https://api.vcon.store --vcon-fetch-auth-file vcon-store.key --vcon-fetch-out fetchedThe fetcher writes fetched/<uuid>.vcon.json, mode 0600. When a file of that
name already exists, the fetcher skips that uuid and the run exits 1. Add
--vcon-fetch-overwrite to replace the file.
More: Fetch a stored vCon.
Since 0.5.256 a forwarder or a fetcher that root starts does not stay root. One that an ordinary user starts changes in nothing.
-
It reads the key file, and a CA file when you name one, as root. The key file can stay
rootmode 0600. -
Then it runs as
--user, else[privilege] user, elsenobody, before it creates a directory or connects to the store. -
That user must own what the command writes:
- the forwarder's spool, where it makes
deliveredandfailed, - the directory that holds
--vcon-fetch-out.
- the forwarder's spool, where it makes
-
Give the spool to the user the forwarder runs as, once:
sudo chown -R nobody spool
-
Check which user it became. The log line is the capture run's:
INFO sipnab::privilege: Dropped privileges to user 'nobody' (uid=65534, gid=65534) -
--no-priv-dropkeeps root and logs one warning line.
More: Commands that do not capture.
-
The forwarder or the fetcher exits
2and logsstarted as root, this command runs as user 'nobody'.- Root started it, and the user it runs as cannot write the path the message names. It created nothing and sent nothing.
- Use one of the three ways the message lists:
chownthe path to that user, name a user who can write it with--user, or keep root with--no-priv-drop.
-
The forwarder exits
3and logsanswered 401.-
The token in
vcon-store.keyis wrong or expired. -
The forwarder moved no file. Every container is still in
spool. -
Fix the token and run it again. The log line reads:
ERROR sipnab::app::vcon_forward: vCon forwarder stopped: POST http://127.0.0.1:18777/v1/vcons answered 401 for 1-1966_10.0.2.20-1cc03f180ff8a774.vcon.json: "{"error":"unauthorized"}". A 401 refuses the credentials or the client for every container alike, so nothing more is sent and every container stays in the spool. Check the credential, and that nothing replaces the User-Agent: a Cloudflare front refuses some clients with a 403 whose body names error code 1010
-
-
The forwarder exits
3and logs403witherror code: 1010.- The Cloudflare front of the store refused the request's client.
- The forwarder sends
User-Agent: sipnab/<version>. Check that nothing between it and the store replaces that header. - It moved no file, so run it again once you fix that.
-
A container lands in
spool/failedwith status409andvCon already exists.- The store already holds that uuid (
--vcon-fetchreads it back). - Follow Replace a container the store already holds.
- The store already holds that uuid (
-
Every container lands in
spool/failedwith status400andextensions: Expected object, received array.- The store refuses
extensionsas the array of strings both vCon drafts define. - sipnab writes the array and the forwarder does not change it, so such a store does not accept sipnab's containers.
- The store refuses
-
A container stays in
spool, and the log saysanswered 500; will retry.- The store failed to process the request.
- The forwarder tries again after its back-off.