Archive retention

Recordings are deleted by a separate command, forgevis --retention, not by the service. The service only records: what may be deleted is decided by a schedule the administrator sets, and carried out by a process that can be stopped without touching recording.

How long recordings are kept

Archive depth is retention_days, set in cameraDefaults and, where a camera differs from the rest, on the camera itself:

cameraDefaults:
  record_path: "/rpool/%path/%Y/%m/%d/stream-%path_%Y-%m-%d_%H-%M-%S.mp4"
  retention_days: 30

cameras:
  entrance:
    source: "rtsp://192.168.1.10:554/stream"
    retention_days: 90    # the entrance is kept longer

A camera without the parameter takes the cameraDefaults value. retention_days: 0 on a camera means keep everything — that is how one camera is exempted from a default the rest follow. With the parameter nowhere, nothing is deleted: that is the default, and the shipped configuration keeps it commented out. Recordings of a camera the configuration no longer has are kept for the cameraDefaults value: they belong to a camera that was removed or moved to another server, and without a shared value they would accumulate indefinitely.

Everything older than retention_days counted from the moment the run starts is deleted — to the hour, not to the day. Two runs a day therefore split a day's work in half, four runs into quarters, with nothing else to configure.

Checking before switching it on

--dry-run reports what the command would do and deletes nothing:

forgevis --retention --dry-run

The report goes camera by camera: how many recordings there are, how many would go, how large they are, and the archive depth the camera ends with. A separate block lists what is worth a look: a camera with no recordings at all, cameras keeping everything, recordings of cameras not in the configuration, and files whose name carries no time.

The real run prints the same report, so it can be compared line for line with what --dry-run showed.

Running it on a schedule

15 4 * * *  /usr/bin/forgevis --retention

Running it several times a day spreads the load: each run takes only what has accumulated since the last one.

15 */6 * * *  /usr/bin/forgevis --retention

Two runs at once are not possible: the command holds a lock on /run/forgevis/retention.lock, and a second run exits without doing anything. The lock is its own — it never overlaps with, or waits for, recording.

If retention has not run for a long time and a large backlog has built up, take the cameras off the server, run the cleanup, and bring them back: the command is meant for daily work, not for clearing months of backlog while the node is recording.

Options

Option	Meaning
--dry-run	Report what would be deleted and delete nothing
--config <path>	Configuration file (default: the one the service uses)
--camera <id>	Restrict the run to one camera
--jobs <n>	Deletion threads (default: half the cores, 2 to 4)
--verbose	List every file, not just the per-camera summary

How recordings are found

Files are matched against the record_path template by name, not by modification time: copying, restoring from a backup and reindexing all change mtime, and none of them change when the recording was made.

The template can be anything. /rpool/%path/%Y/%m/%d/stream-%path_%Y-%m-%d_%H-%M-%S.mp4 gives each camera a tree of days; /recordings/%path/stream-%path_%Y-%m-%d_%H-%M-%S.mp4 gives it a single directory. Both are read the same way. Files written under a previous template are found too — their time is read from their name.

What is never deleted:

• files whose name yields no time (they appear in the report);
• files with an extension other than the template's;
• recordings of a camera set to retention_days: 0.

Once the files are gone the emptied directories follow — a day's directory when its last recording leaves, a camera's when its last day does. The archive root always stays.

Nodes with a database, and clusters

The command has no mode of its own: it takes the cameras from wherever the node itself takes them.

• Standalone node. Cameras from config.yaml and conf.d; the files come from the disk.
• Node with a database. Those, plus the platform's cameras with the depth set on each, and the recordings table supplies the list of files this node wrote.
• Cluster. The node has no camera list of its own, so the database answers: it asks for the rows carrying its own name and deletes nothing else. A camera that moved between nodes several times in a day needs no special handling — each node gets its own list and touches no one else's.

A file's row in the recordings table goes with the file; otherwise the platform would keep offering a recording that is no longer there. If the file turns out to be gone already, the row is still removed — that is not an error.