Skip to main content

Local Files

The file driver writes to the local filesystem on each Auth host. It is a valid driver for audit events (name: audit-*) and for session recordings (name: recordings). It is not a state driver.

Storage concernSupported
Cluster state (name: state)no
Audit events (name: audit-*)yes
Session recordings (name: recordings)yes

TL;DR​

  1. Use the file driver for single-node, dev, evaluation, air-gapped, or backup-style deployments.
  2. Write separate StorageConfig resources for audit-* and recordings paths.
  3. Do not treat local files as a shared HA store. Every Auth host writes to its own filesystem.

Prerequisites​

Before you start, make sure you have:

  • A local filesystem path on every Auth host that the Auth Service process user can write to.
  • Separate directories for audit events and recordings.
  • A backup and retention plan if the data matters.

For a single Auth host that is not part of an HA pool, the file driver is fine for both audit and recordings. For HA pools, the per-host filesystem becomes a fragmentation point.

Configuration​

Step 1. Pick the filesystem paths​

Use the file driver for single-node clusters, dev, evaluation, and air-gapped environments where an external object store is not available.

Use /var/lib/almaforge/log/audit for audit events and /var/lib/almaforge/log/records for session recordings. Pointing both at the same directory mixes file types and breaks tooling that expects one or the other.

Step 2. Write any audit-events resources​

audit.yaml:

examples/storage/local/audit.yaml
# Local file destination for audit events on each Auth host.
apiVersion: almaforge.com/v1
kind: StorageConfig
metadata:
  name: audit-local
spec:
  file:
    path: /var/lib/almaforge/log/audit

Combine it with an external audit-* instance for fan-out:

audit-fanout.yaml:

examples/storage/local/audit-fanout.yaml
# DynamoDB audit storage plus a local file copy on each Auth host.
apiVersion: almaforge.com/v1
kind: StorageConfig
metadata:
  name: audit-primary
spec:
  dynamo:
    region: us-east-1
    tableName: cluster-audit
---
apiVersion: almaforge.com/v1
kind: StorageConfig
metadata:
  name: audit-local
spec:
  file:
    path: /var/lib/almaforge/log/audit

The audit-primary instance writes to DynamoDB. Each Auth host also writes the events it handles to audit-local on its own disk. This provides a second copy for investigation when the external sink is unavailable. It does not automatically import missing events back into DynamoDB after an outage.

Step 3. Write the recordings resource​

recordings.yaml:

examples/storage/local/recordings.yaml
# Local file destination for session recordings on each Auth host.
apiVersion: almaforge.com/v1
kind: StorageConfig
metadata:
  name: recordings
spec:
  file:
    path: /var/lib/almaforge/log/records

Recordings written to local disk live on whichever Auth host happened to terminate the session upload. There is no automatic redistribution across hosts.

FieldRequiredDefaultNotes
pathyesnoneFilesystem path on every Auth host. The directory must be writable by the Auth Service process user.

Step 4. Restart and verify​

Restart the Auth Service after updating the bootstrap file, then verify the active resources:

Terminal
sudo systemctl restart almadalma get storageconfig/audit-local -o yamlalma get storageconfig/recordings -o yaml

Open and end a recorded terminal session, then confirm that audit files and a recording appear in their separate directories. Resource output confirms configuration, while this session checks the write path.

URI form​

Equivalent URI strings, suitable for an environment variable or a CLI flag. Use three slashes (file:///) so the path starts at the filesystem root:

text
file:///var/log/almaforge/audit
file:///var/lib/almaforge/recordings

Troubleshooting​

The Auth Service cannot write files​

Check that the configured directory is on a writable filesystem with enough free space. AlmaForge creates missing directories, but does not repair the ownership or permissions of existing paths. On Linux hosts, keep private storage directories owned by root:root with mode 0700.

An HA pool shows only partial audit or recording data on each host​

That is expected. Each Auth instance writes audit events and recordings to its own local filesystem. They do not share a single recording or audit view.

Audit events and recordings share one directory​

Split them. Mixed file types break tooling that expects one or the other.

Operations​

Durability​

AlmaForge rotates local audit log files, but does not delete old files to enforce retention. It does not replicate or back up local audit files or recordings. Arrange backups, retention, and disk-space monitoring. See Backups.

HA usage​

For HA, you almost always want an external store as the primary audit-* or recordings instance, with the file driver as an optional secondary audit-* instance for forensic backup.

References​