Skip to content

Storage, destinations and retention

Aperture records to the server’s own disk by default. You can add more destinations (another local disk, an SMB share on a NAS, an SFTP server), point each camera at one or several of them, give each a space allocation, and let Aperture delete the oldest footage when space or retention runs out. This page covers all of it, from the default folders to the rules the retention janitor follows.

Everything here is under Settings › Recording & Storage, which only administrators see.

A fresh install keeps two folders:

Folder Holds Set by
/var/lib/aperture/recordings Footage of every camera recording to Primary storage, one folder per camera, plus event thumbnails APERTURE_RECORDINGS_DIR
/var/lib/aperture/data The database, keys, caches, extensions and the upload spool for network destinations APERTURE_DATA_DIR

Both are set in /etc/aperture/aperture.env (see Configuration). In the app, the recordings folder appears as the destination Primary storage, marked Default. The data folder is shown as App & database, fixed with the install.

Footage is a series of 10-second .ts files per camera. How it is recorded is on Recording modes and schedules.

Settings › Recording & Storage has three parts.

  • Overview: space used across all destinations against what is allocated, a bar of footage per camera plus App & database, the free space left in the allocation, and “Holds ≈ … more at the current rate”, an estimate from the current recording bitrate. Below it, each destination as a chip and the Re-scan button (see Re-scan).
  • Recording destinations: one row per destination with its usage, its cameras, an edit button and a remove button. Add destination opens the setup wizard.
  • Delete footage: removes recordings in a time range (see Delete footage).

The most direct way to give Aperture more room is to mount a disk at the recordings folder, so Primary storage lives on it. Footage keeps its paths, so recordings you copy over stay playable.

  1. Stop Aperture:

    Terminal window
    sudo systemctl stop aperture
  2. Mount the new disk at /var/lib/aperture/recordings, with an entry in /etc/fstab so it comes back after a reboot. Anything already in that folder is hidden under the mount; copy it onto the new disk first if you want to keep the footage you have.

  3. Optionally, make Aperture refuse to start when the disk is not mounted, instead of recording onto the system disk. Add this line to /etc/aperture/aperture.env:

    APERTURE_REQUIRE_REC_MOUNT=1
  4. Start Aperture again:

    Terminal window
    sudo systemctl start aperture

A destination is a place footage is written: a local folder, an SMB share or an SFTP server. The wizard tests the connection before anything is saved.

  1. Open Settings › Recording & Storage and choose Add destination.
  2. Under Choose a destination type, pick Local folder, SMB / Windows share or SFTP / SSH and choose Continue.
  3. Give it a Name and fill in the connection details (below). Choose Test connection.
  4. Testing the connection runs a checklist: it connects, writes a small test file, reads it back, deletes it and reads the free space. Each step shows what happened. When it ends with “Connection verified — this destination is ready.”, choose Continue. If a step fails, go Back, fix the details and test again.
  5. Under Cameras & space, set the Allocation (see Allocations) and tick the Cameras to record here. The wizard estimates how long the allocation holds for the ticked cameras. A ticked camera moves here: its new recordings go here instead of its current destination, and that destination stops receiving them. What the camera already recorded stays where it is until retention removes it, and its mirrors stay as they are.
  6. Choose Save destination.

The test never touches existing footage; it only creates and removes a file named .aperture-connect-test.

Field Notes
Folder path An absolute path. The folder is created if it does not exist.

The folder must be under /var/lib/aperture. The service runs in a systemd sandbox (ProtectSystem=strict with ReadWritePaths=/var/lib/aperture): every other path on the machine is read-only to it, and /home is hidden. A folder such as /mnt/disk2 therefore fails the test with “read-only file system”. Mount a second disk under it instead, for example at /var/lib/aperture/disks/disk2, and use that path. The wizard suggests the same.

  • The folder cannot be, sit inside or contain the data folder or the Primary storage folder. Such a path fails the test with “This folder overlaps …, which Aperture already uses.” So /var/lib/aperture itself is refused, and /var/lib/aperture/disks/disk2 works.
  • The path cannot be changed later, because recorded segments are indexed by their full path. To move, add a new destination and point the cameras at it.
  • If the disk is not mounted when Aperture records, footage lands in the empty mount-point folder on the system disk. Mount it at boot, before Aperture starts.
Field Notes
Host The NAS or server, for example 192.168.1.30.
Port Default 445.
Share The share name, for example recordings.
Subfolder Optional folder inside the share. Created if missing.
Username, Domain, Password The account Aperture signs in with. The domain is usually empty.

Aperture connects to the share itself. You do not mount it on the server, and the sandbox does not get in the way. Give Aperture its own account on the NAS with access to this one share only.

Field Notes
Host, Port The server; default port 22.
Username The account Aperture signs in with.
Remote path The folder on the server, for example /srv/aperture. Created if missing.
Authentication Password, or Private key pasted as PEM text.

The first successful test records the server’s SSH host key fingerprint (shown in the checklist as “Host key SHA256:…”), and saving the destination pins it. From then on Aperture refuses to connect to a server presenting a different key, so a machine that impersonates the server gets nothing.

To trust a new host key:

  1. Open the destination’s Edit dialog and choose Reconfigure…, enter the password or key again and test.
  2. The test stops before signing in and shows “The server’s host key has changed”, with the key Trusted until now and the key Offered now.
  3. Read the fingerprint on the server itself, at its console or in its admin page, with the command the dialog shows, for example ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub.
  4. If it matches, tick “I checked on the server: its fingerprint matches the new key.” and choose Trust the new key and test again. The test runs against the new key.
  5. Choose Apply changes. Only then is the new key pinned, and the activity log records “host key re-pinned”.

Some SFTP servers do not report free space. The checklist then says “Server doesn’t report capacity (soft cap only)”, and the free-space safety net cannot protect that server; set an allocation for it.

SMB passwords and SFTP passwords or keys are encrypted at rest with AES-256-GCM before they are stored, separately from the rest of the destination’s settings. They are never sent back to the browser: testing an existing destination decrypts the stored credential on the server. A lock icon on the destination’s row shows that a credential is stored. To change one, use Reconfigure… (see Change a destination).

The encryption key lives in /var/lib/aperture/data/secrets.json. Without it, stored credentials cannot be decrypted, so the service refuses to start when a database exists but that file is missing. Keep a copy of it as carefully as the passwords themselves. See Backup and restore.

Every camera writes its new footage to exactly one destination and can keep extra copies on others. There are three places to set this:

  • The camera editor. Under Recording, Storage is where new footage is written. With more than one destination, Also record to lists the others with a checkbox and a number of days for each.
  • A destination’s row. Click the Cameras cell of a row and tick the cameras that record there. A camera ticked on several destinations records to all of them at the same time.
  • The setup wizard, when you add a destination. Unlike the row, the wizard moves each camera you tick: the new destination becomes where it writes, and its old destination stops receiving its footage. Mirrors it had elsewhere stay as they are.

Changes affect new footage only. Existing recordings stay where they are and remain playable. Changing where a camera writes restarts that camera’s recorder, which takes a few seconds.

A camera with more than one destination records once, to the destination in its Storage field, and Aperture copies each finished segment to every other destination ticked under Also record to. Those copies are mirrors.

  • Recording never waits for a mirror. The copies are made by a background pass every 8 seconds, from the finished file. A slow or dead mirror falls behind; it cannot stop or slow the recording.
  • Each destination has its own retention. The days field next to a mirror overrides the camera’s Retention (days) for that destination only. Leave it blank to use the camera’s value.
  • Catch-up after an outage. A copy is recorded as done only after it succeeded, so anything missing is retried on later passes. When a destination comes back, its backlog is filled in, newest footage first, in batches of 12 segments per pass. A new mirror also receives the existing footage that falls inside its retention.
  • The surviving copy takes over. A segment disappears for good only once it is older than the retention of every destination that holds it. Until then, each destination drops its own copy when its own retention runs out. If the copy being dropped is the one playback reads, a surviving mirror is promoted to take its place first (a local copy is preferred over a network one). Footage stays watchable as long as any copy survives.

A common setup keeps a short local history and a long one on a NAS. Set the camera’s Storage to Primary storage and its Retention (days) to 2, then tick the NAS under Also record to and enter 30 days for it. Primary storage then keeps two days and the NAS thirty; footage older than two days plays from the NAS. Each destination’s allocation still applies on top.

Network destinations: the spool and the uploader

Section titled “Network destinations: the spool and the uploader”

Footage for a camera that writes to an SMB or SFTP destination does not go over the network directly. The recorder writes it into a local spool, /var/lib/aperture/data/spool/<camera>, and an uploader moves each finished segment to the share every few seconds: it uploads to a temporary name, renames it into place, adds it to the index and only then deletes the local copy. A network drop or a crash does not lose a segment; it is uploaded on a later try.

While a share is unreachable:

  • Footage collects in the spool, up to 4 GiB per camera (about two hours at 4 Mbit/s). Beyond that, the oldest spooled segments are dropped so the system disk cannot fill, and the log says recorder: spool over cap, dropped oldest un-uploaded segments. The camera keeps recording the newest footage.
  • Spooled footage is not in playback yet; it appears once uploaded.
  • The camera shows Not recording, because nothing new reaches its destination (see Recording states).

The spool sits in the data folder, so it counts toward Primary storage’s app data, and the system disk needs room for up to 4 GiB per network camera. Playback and exports of network footage read it back over the network.

Turning a network destination’s Enabled switch off pauses it: nothing is uploaded or mirrored to it, and its allocation is not enforced. Cameras that write to a paused destination switch to Primary storage when their recorder restarts, which the watchdog does within a few minutes; until then their footage waits in the spool. Use a pause for short maintenance, and move the cameras elsewhere first for anything longer.

An allocation is how much space Aperture may use on a destination. When footage reaches it, the oldest footage on that destination is deleted to make room; where a mirror still holds a copy, only this destination’s copy goes. Recording never stops because an allocation is full.

Destination Kind of allocation What counts toward it
Primary storage Hard-reserved (see below) Footage, plus app & database (data folder and event thumbnails)
Local folder Hard-reserved Footage on that folder
SMB or SFTP Soft cap Footage Aperture has indexed on that share

On Primary storage the app & database count toward the allocation, but only footage is ever deleted to stay under it.

To set or change an allocation, choose the edit button on the destination’s row (Edit primary storage for Primary storage), move the Allocation slider (Reserved for Aperture on Primary storage) and choose Save changes. Off, or 0, means no limit. The change applies immediately, without a restart.

Lowering an allocation below what is stored deletes footage straight away. Aperture asks first: Delete footage to shrink this destination? lists exactly how much would go, how many recordings, which cameras and from when to when. Choose Keep my footage to back out.

A per-camera storage quota also exists in the API (storageQuotaBytes on a camera; oldest footage of that camera goes first when it is exceeded). The web app does not show it.

On Primary storage and on local folders, an allocation is backed by a real reservation. Aperture keeps a preallocated file named .aperture-reservation in the destination’s folder and sizes it so that footage (plus app data on Primary storage) plus the file always equals the allocation. The file’s blocks are really allocated, so other programs cannot take that space, even while Aperture is stopped. As footage grows, the file shrinks by the same amount; at the ceiling, the oldest footage is trimmed.

  • The janitor resizes the file on every pass (every 5 minutes) and right after an allocation changes.
  • Aperture always leaves 3 GiB free on the filesystem, so a reservation can never fill the disk completely. The slider’s maximum is the disk size minus other programs’ data minus those 3 GiB.
  • Setting the allocation to Off removes the file. Deleting it by hand does nothing lasting: the next pass creates it again.
  • The filesystem must support preallocation; ext4 and XFS do.

Network shares cannot be reserved this way; their allocation is a soft cap that Aperture enforces by deleting its own oldest footage.

The retention janitor runs when Aperture starts and every 5 minutes after. Each pass, per camera and then per destination:

  1. Motion-only cameras: deletes segments at least 2 minutes old that overlap no event (see Motion only).
  2. Age: deletes footage older than the camera’s Retention (days), or a destination’s own days for its copies.
  3. Per-camera quota, if one is set through the API.
  4. Allocations: brings each destination under its allocation, oldest footage first.
  5. Free-space safety nets (next section).
  6. Reservations: resizes each reservation file.

Two things hold footage back from deletion:

  • Exports. Footage overlapping a queued or running export is not deleted, for up to 2 hours per export, so a render is never pruned out from under itself.
  • Leases. A script or extension reading old footage through the API can take a lease on a time range of one camera (POST /api/v1/cameras/{id}/lease), for at most 2 hours.

A recording’s index entry outlives its file. The janitor deletes the file first and the entry only after the delete succeeded. If a delete fails (a share is down, a permission is wrong), the entry stays and the next pass tries again, so no footage ever becomes untracked and impossible to clean up. The log then shows one line per destination per pass: retention: could not delete footage, keeping it to retry next pass. A destination that loses more than 30 seconds to failing deletes in one pass is skipped for the rest of that pass, so one dead share cannot hold up every other camera.

Allocations are the main limit. The safety nets catch a disk that fills anyway, deleting the oldest footage on that destination (mirror copies first, since another copy exists).

Destination Net
Primary storage without an allocation Keeps 7% of the disk free, at least 5 GiB (at most a quarter of a small disk)
Primary storage with an allocation None needed: the allocation and the reservation bound it
Local folder without an allocation Same 7% and 5 GiB rule for its disk
Local folder with an allocation None needed
SMB or SFTP Always keeps 5 GiB free on the share (at most a quarter of a small share), with no percentage: the NAS’s disk holds more than Aperture’s footage

The share’s net works only when the share reports its free space.

Delete footage at the bottom of Settings › Recording & Storage permanently removes recordings and their events in a time range.

  1. Choose a Camera, or All cameras.
  2. Choose a Range: Last 24 hours, Last 7 days, This month, All footage or Custom range (with From – to).
  3. Choose Delete footage and confirm.

The result shows how much was freed and how many segments and events were removed. It cannot be undone, it is recorded in the activity log, and it only works in a signed-in admin session, not with an API token.

It removes every copy: each recording on its main destination and on every mirror destination, with its thumbnails and snapshots. A copy that can’t be deleted, for example on a share that is offline, is kept together with its index entry and counted as not removed; the next delete or retention pass tries it again. A destination that keeps failing gets at most 30 seconds per request, so one dead share doesn’t hold up the rest.

Re-scan in the overview looks through each camera’s folder on Primary storage or its local destination and adds any footage file the database does not know about, so it shows up in playback and is managed by retention again. It reports “Recovered … orphaned segments.” or “Everything on disk is already indexed.” Network destinations are not re-scanned. Durations of recovered segments are estimated from the gaps between files.

  • Edit (the pencil on a row) changes the name, the allocation, the cameras that record there and, for network destinations, Enabled.
  • Reconfigure… in that dialog changes a network destination’s host, share or credentials. It goes through the wizard, so the new settings are tested before they apply. For SMB, leave the password empty to keep the stored one; for SFTP, enter the password or key again.
  • Remove (the bin icon) asks Remove destination. Aperture refuses while cameras still record there or footage is stored there, and then offers Force-remove destination: it moves those cameras back to Primary storage and permanently deletes the footage stored on that destination. Copies it held only as a mirror are dropped from the index; their files stay on the disk or share.
  • A local folder fails the test with “read-only file system”. The folder is outside /var/lib/aperture. See Local folder.
  • An SMB test fails at “Connect & sign in”. Check the host, the port (445), the account and its password, and that the NAS allows SMB from the server. A failure at “Open the share” means the share name is wrong or the account has no access to it.
  • Footage disappears sooner than the retention. An allocation or a safety net removed it. The log names which: retention: over storage cap, removed oldest, retention: low disk space, removed oldest on default location or retention: network share is nearly full. Raise the allocation, keep fewer days on other cameras sharing the destination, or add a destination.
  • A camera on a NAS shows Not recording. Check that the NAS is reachable and has room. journalctl -u aperture | grep upload shows the upload errors.
  • Before starting Aperture after moving folders, run sudo deploy/check-retention.sh /var/lib/aperture/data/aperture.db from your checkout of the repository. It predicts what the janitor’s first pass would delete and fails loudly if that would be most of the archive. It needs sqlite3.

Related: Recording modes and schedules · Camera capacity · Backup and restore · The recording pipeline