Time-Travel Mounting

The --atTime flag allows you to mount a flexFS volume as it existed at a specific point in the past. The mount is read-only, providing a consistent snapshot of the filesystem at the requested timestamp.

Usage

mount.flexfs start my-volume /mnt/snapshot \
  --atTime 2025-06-15T14:30:00Z

The --atTime value must be in RFC 3339 format (e.g. 2025-06-15T14:30:00Z or 2025-06-15T14:30:00-04:00). The mount is automatically set to read-only (--ro is implied).

How it works

When --atTime is provided:

1. The mount client parses the RFC 3339 timestamp and converts it to nanoseconds since epoch.
2. The mount is forced to read-only mode.
3. The metadata server returns the filesystem state as it existed at the requested point in time, using its retained metadata history.
4. Block data is read from object storage (blocks are immutable and retained for the configured retention period).

Retention window

Time-travel mounts are only possible within the volume’s configured retention window. If you request a point in time that falls outside the retention window, the mount will fail with an error indicating the earliest allowed time.

The retention window is set during volume creation or via configure.flexfs:

• A positive value (in seconds) defines a rolling retention window — for example, 604800 retains 7 days of history.
• A value of -1 means blocks are retained forever, enabling time-travel to any point since the volume was created.
• A value of 0 means no retention beyond the current state, effectively disabling time-travel.

Caution

The mount client applies a 5-minute safety buffer to the retention window to account for cleanup timing. If your retention is 3600 seconds (1 hour), the earliest allowed --atTime value is approximately 55 minutes ago.

Use cases

Data recovery

Recover accidentally deleted or overwritten files by mounting the volume at a point before the deletion:

mount.flexfs start my-volume /mnt/recovery \
  --atTime 2025-06-14T10:00:00Z

# Copy the needed files
cp /mnt/recovery/important-data.csv /home/user/restored/

Auditing and compliance

Provide auditors with a verifiable, read-only view of filesystem state at a specific date:

mount.flexfs start audit-volume /mnt/audit \
  --atTime 2025-01-01T00:00:00Z

Debugging

Compare the current state of a volume with a historical state to understand what changed:

# Mount the current state
mount.flexfs start my-volume /mnt/current

# Mount a historical state
mount.flexfs start my-volume /mnt/yesterday \
  --atTime 2025-06-14T00:00:00Z

# Compare
diff -r /mnt/current/config/ /mnt/yesterday/config/

Note

Multiple time-travel mounts of the same volume (at different timestamps) can be active simultaneously, each on its own mount point.

Limitations

• Time-travel mounts are read-only. Write operations will return EROFS.
• The available history depends on the volume’s retention configuration. Blocks that have been garbage-collected are no longer accessible.
• Time-travel mounts still consume a metadata server session and count toward active mount limits.