This guide dives into the routine operations of administering a Caelum appliance. It complements the administration guide (which describes each screen) by focusing on the "how to" of the most frequent tasks, end to end. The basic notions (volume, share, S3 target, tiering, snapshot) are explained in the product overview.
Create and manage volumes and shares#
Create a volume#
A volume groups shares that share the same rules (quota, snapshots, default S3 target). To create one:
- Go to Storage → Volumes → New volume.
- Give it a name (lowercase, digits, hyphen, underscore — it is used as the internal dataset name).
- Choose the target pool (primary by default, or an additional pool).
- Set a quota (in GiB) or leave it empty to allow the whole pool.
- Optional: choose a default archiving destination and, under Archiving — advanced settings, the cloud retention (how long files deleted on the share side are kept in S3; 30 days by default, empty = never purged).
- Enable Previous versions (Windows) if you want to expose snapshots as "Previous Versions" (see the dedicated procedure below).
Good practice: one volume per team or per project, which lets you apply distinct quotas and snapshot policies.
Create a share#
- Go to Storage → Shares → New share.
- Give it a name and choose the volume: the name becomes the SMB access
path
\\<appliance>\<name>. - Choose the served protocols: SMB and/or NFS, with a read-only option.
- Restrict access if needed:
- SMB: allowed accounts / groups (Active Directory or LDAP;
g:group,u:user). Left empty, the share is served to local accounts; if the appliance is joined to a domain, all domain users have access by default. - NFS: allowed NFS clients (IP addresses / CIDR) and NFS identity (squash by default, or sys).
- SMB: allowed accounts / groups (Active Directory or LDAP;
- Optional: a quota specific to the share, and cloud tiering (S3 cache) with a specific S3 destination.
- Click Create the share.
The share then appears in the list with its path, protocols, tiering state, quota and state.
Manage an existing share#
Click a row in the share list to open its detail, organized in cards:
- Configuration: protocols, access, quota, state (read-only; changes go through Edit).
- S3 cache: the share's tiering status (archiving is driven through the archive policies).
- File browser: browse the tree, play a media file, recall or upload files.
- Previous versions: browse a snapshot and restore a file.
- User quotas, Per-user NTFS permissions, Bulk actions.
The share's Access & security section also exposes advanced SMB options (enterprise / AD): NTFS ACLs, Access-Based Enumeration, Hide the share, Log accesses (activity trail, SIEM) and SMB encryption required. Deleting a share removes it from the SMB/NFS configuration; the number of objects already archived on S3 is shown before confirmation.
To modify protocols, access or quotas, use the share's Edit button. SMB/NFS access changes take effect without interrupting current sessions.
Advanced storage: pools, iSCSI and role-based networks#
Add an additional storage pool#
Beyond the primary pool (galilopool, mounted under /galilo/data), you can
create additional pools (mounted under /galilo/pools/<name>) to place
certain volumes on separate storage.
- Go to Storage → Pools → New pool.
- Give it a name, choose the layout — No redundancy, Mirror, RAIDZ1, RAIDZ2 or RAIDZ3 — then select the disks.
- Confirm. When creating a volume, then choose this pool as the target.
You can also import a foreign pool or add disks to a pool. To replace a disk, click Replace a disk and choose the failed disk and the new one: the rebuild (resilver) happens without interruption.
Additional pools are outside high availability (standalone): they do not follow an HA failover.
Attach an iSCSI LUN#
To use a LUN from a remote array (e.g. Synology) as a pool disk:
- Go to Storage → iSCSI.
- Enter the portal (
host:port,3260by default) and click Discover. - On the target found, click Log in and enter, if needed, the CHAP user and CHAP secret.
- The LUN appears as a disk to create or extend a pool.
Logging out is refused if the LUN belongs to an imported pool. Multipath (MPIO) is configured in the Multipath section (Edit multipath.conf), without SSH.
Assign role-based networks#
To dedicate network cards to uses (Settings → Network → Interface roles):
- Assign each card a role: Management (UI / SSH), Data (SMB / NFS), Cluster (corosync heartbeat), Replication, Cloud / S3 or iSCSI storage. A preset (all-in-one or separate networks) can be pre-computed with Compute this preset.
- Click Check, then Apply: the assignment sets the services' listening addresses.
- A risky configuration is applied in test mode: it rolls back on its own unless you click Confirm the configuration (anti-lockout). Bonds (LACP 802.3ad) and 802.1Q VLANs are described in Advanced network (validate, test on the appliance, then apply).
If an assignment locked you out, Restore the administration binding reopens the console on all interfaces.
Configure a cloud destination and archiving#
Declare a cloud destination#
- Go to Archiving → Cloud destinations → New destination.
- Fill in:
- Name: label, and Region.
- Endpoint (e.g.
https://s3.eu-west-3.amazonaws.com) and port. - Verify the certificate: leave enabled in production (only disable it in a lab).
- Access key / Secret key: the secret is never shown again after saving.
- Default bucket: the bucket must exist (it can be listed or created from the screen with List buckets / Create a bucket).
- Cost (€ / GiB / month): optional simulation input entered by the administrator; not a Caelum price or verified savings.
- Save, then click Test the connection (and, if needed, Measure throughput). The destination becomes selectable as the default target of a volume or a share, and in archive policies.
Make sure the credentials can read/write/delete in the bucket. A misconfigured destination results in failed archiving tasks (see troubleshooting). Plan for a sustained S3 throughput of 5 MB/s or more.
Create an archive policy#
Archiving is driven from the Archiving → Policies screen. A policy is a named, reusable task = filter + destination + time + scope.
- Click New policy (or, more simply, Open the assistant in the Archiving assistant card at the bottom of the screen).
- Which files: eligibility criteria (modified more than N days ago, minimum size, extensions, paths).
- Cloud destination and, if needed, location (bucket, prefix).
- Scope: all shares or selected shares; Attach a scope then lets you target a volume or a share.
- Run time, Free up space after upload (files become stubs) and Task enabled. The preview counts the matching files.
The first run of a new task is a dry run: nothing is uploaded until you run it again for real (Lancer pour de bon, labelled in French in this version). Age is measured on the modification date: the last-read date is not tracked on pools created by the product.
Once archived, a file becomes a stub (offline file): it stays visible and clickable, marked offline in Windows (cloud badge), but takes up almost no local space anymore. When opened, Caelum recalls it from the cloud, transparently (allow 1 to 5 s, then the target's sustained throughput). A recalled file that has become cold again can be re-archived. For large media files, partial streaming lets you read a stub without recalling all of it, over SMB as well as NFS (NFS-Ganesha engine, the default for new installations), provided the share or its volume has a cloud destination (Play button in the browser for audio/video).
Known limitation (0.65.5): over NFS, the first read of an archived file can fail if the S3 target is very slow; prefer SMB in that case, and aim for an S3 throughput of 5 MB/s or more.
Uploads are tracked in Archiving → Archiving tasks (run again, recall, leave stubs).
"S3 cache" mode (automatic share tiering)#
A share can run in S3 cache mode: its cold files automatically go to the S3 bucket and are replaced by stubs; the local disk only keeps a buffer of recently used files, bounded by a local cache threshold (GiB). In the share's window (Edit), Cloud tiering (S3 cache) section, enable Automatic archiving, choose the S3 destination (or inherit the volume's) and the threshold.
Snapshots and "Previous Versions"#
Schedule snapshots#
- Go to Storage → Snapshots, Schedules tab → New schedule.
- Choose the target dataset (volume).
- Set the frequency (hourly, daily…), the retention (number of snapshots kept, automatic rotation) and the Recursive option (includes child datasets).
- Tick Windows Previous Versions so that snapshots appear on the Windows side.
A volume snapshot covers all of its shares. It is near-instantaneous and only takes up the space of subsequent changes.
Enable "Previous Versions" (a single checkbox)#
Windows exposure of earlier versions is managed with a single switch on the volume:
- In Storage → Volumes, click Edit for the volume and enable "Previous versions (Windows)".
- Caelum provisions the whole chain (Samba exposure + a snapshot schedule managed by the volume). Nothing else to configure.
- Optional: adjust the frequency (hourly / daily / weekly) and the retention (default 24 snapshots).
Unticking the box cleans up the configuration. If the schedule exists but its runs fail, the volume window says so.
The schedule targets the volume's dataset: all of the volume's shares are covered.
Restore via "Previous Versions"#
Once the option is active, a Windows user can, from the Explorer:
- Right-click a file or folder → Properties.
- Previous Versions tab.
- Select an earlier version and restore or open it.
On the administrator side, snapshots are managed from the Snapshots screen; a file is restored from the Previous versions card of the share detail (next to the current file or in its place).
The previous version of an archived file cannot be read from Windows: restore it from the share's Previous versions card.
Replication and disaster recovery (DR)#
Replication copies your volumes to a second Caelum appliance (remote site), for disaster recovery. Transfers are incremental (only changes travel) and are done per volume. The full details (pairing, frequencies, continuous mode, ACL fidelity) are in the replication guide.
In 0.65.5, replication is labelled "Beta — not qualified". Creating
targets and jobs is done in the previous interface,
https://<appliance-ip>/legacy, Replication screen; the new console
(Storage → Replication) is used for monitoring, immediate sends and
failover.
Set up a replication target#
- Open
https://<appliance-ip>/legacy→ Replication → Add appliance. - Enter the name, the address (IP or DNS) of the remote appliance, the SSH user and the port.
- Click Test & detect: the appliance checks connectivity and offers pairing (SSH key authorization via an HTTPS 443 admin session, without storing any password).
- Optional: network compression (useful on a slow WAN link) and a forced source IP if you have a dedicated replication network.
- Create one job per volume to replicate (New job), with its frequency (from 15 min to weekly, or Continuous mode ~15 s / real-time RPO).
In the new console, the Storage → Replication screen then shows the state and copy lag (RPO), the jobs (Send now) and the destinations; Pair a target also registers a peer there, checking both channels (HTTPS for pairing, SSH for transfer).
Test a replica#
On the destination side, received datasets appear under Incoming replication (new console) or "Incoming replications" (previous interface). Mount for recovery mounts a received dataset read-only to check its content, without promoting the node. In the previous interface, "Verify replica" clones the latest snapshot read-only, attached to a dedicated DR volume; "Stop test" destroys the clone. To actually serve users from the recovery site, see failover below.
Fail over for disaster recovery (HA by replication)#
When replication is set up as continuity by replication (high availability, Replication mode), failover is done in one move:
- Check that the last replication received is recent (acceptable RPO) and look at Recovery readiness on the Replication screen.
- On the secondary node, click Switch over to this node and confirm the acknowledgements (accept losing what has not been copied yet; check that the other node no longer serves).
- The node is promoted to primary: its datasets become writable, the shares are regenerated and the peer is demoted.
In replication mode, the cloud destinations' secret is not replicated (by design, so that it never travels). After a failover, you must re-enter the S3 secret on the promoted node, otherwise archiving and the S3 cache stay blocked. In addition, for AD account authentication to work after failover, both nodes must be joined to the domain. Files archived by a version earlier than 0.64.1 cannot be read on the promoted node until they have been re-archived.
Failover in replication mode is manual, RPO = replication interval, and a split-brain is possible without fencing. Zero RPO and transparent automatic failover only apply to the shared storage mode (see below). Document and test your DR procedure cold, outside production.
Active Directory / LDAP join#
To authenticate SMB users with the company's accounts.
Join an Active Directory domain#
- Access → Identities screen, Domain section.
- Click Check DNS: the domain must resolve through the controller (otherwise, set the appliance's DNS to the domain controller).
- Click Join the domain and enter the realm (e.g.
CORP.EXAMPLE.COM), a domain administrator and their password (used only for the join, never kept), and optionally the organizational unit and NetBIOS name (left empty, it is requested from the controller). - Confirm: the screen shows Domain member.
Once joined, AD users and groups become usable in share access lists. To leave the domain, use Leave the domain (domain accounts immediately lose access to the shares).
The appliance's short name must be 15 characters or fewer (NetBIOS constraint), and its clock must be on time (Settings → Advanced settings → Time servers).
LDAP (without Active Directory)#
Two options, in Access → Identities:
- Built-in LDAP directory: a directory internal to the appliance to manage SMB users and groups without external infrastructure.
- External LDAP directory: connection to an existing directory (OpenLDAP, 389DS, FreeIPA…). Enter the host, port, base DN, bind account and its password; TLS (LDAPS/StartTLS) available.
High availability (HA)#
HA lets two appliances take over from each other, in two modes. In 0.65.5, both ship as beta, not qualified: test them outside production before relying on them.
Mode 1 — Shared storage#
- Prerequisites: a single ZFS pool on a LUN/SAN (iSCSI/FC) reachable by both nodes.
- Pacemaker imports/exports the pool on the active node; SMB/NFS services and the virtual address are managed by the cluster.
- Near-instant failover, no data loss: when the active node fails, clients reconnect on the same virtual address.
- Setup: Storage → High availability → Create a cluster (Create a shared-storage cluster wizard: nodes, cluster service password — the same on both nodes —, pool, virtual address). Fencing (STONITH) cannot be configured in this version: the acknowledgement "I accept the split-brain risk (no fencing)" is mandatory.
Mode 2 — Replication#
- Each appliance keeps its own local pool; an asynchronous ZFS replication keeps the passive node as a read-only mirror.
- Manual failover via Switch over to this node (Replication screen); RPO = replication interval.
- Setup: Storage → High availability → Continuity by replication card → Set up replication (peer appliance, administrator account, dataset to replicate, resynchronisation frequency, SSH user and port). See the replication guide and the DR section above.
Setup#
Common prerequisites: two Caelum appliances on the same version, joined to the same domain if your shares use AD accounts.
In shared storage mode, without fencing, nothing physically prevents both nodes from serving at the same time. In replication mode, failover is manual and the RPO depends on the interval.
Test a failover outside production before relying on it. Check that both nodes are on the same version and properly see the expected storage.
Updates, channels and rollback#
The two update channels: stable and beta#
Caelum offers two update channels, set in Settings → Updates → Release channel:
- stable (recommended in production): only offers proven versions. This is the default channel.
- beta: offers release candidates early, to test new features. Reserve it for a test environment or a non-critical node.
A box already on a release candidate (-rc) automatically switches to the
effective beta channel; conversely, a stable box is never offered a beta
version.
Update#
- Link your galilo.io portal account in Diagnostics → Support → Link an account (Link the Caelum portal account window: email address and password; the password is not stored). This account is what lets the appliance check and download updates.
- In Settings → Updates, check the proposed version (Update available: vX.Y.Z; Check again reruns the check).
- Click Installer vX.Y.Z (labelled in French in this version) and confirm: a system snapshot is taken before installing, then the interface restarts.
Without Internet (air-gap), use Install from a file: choose the
galilo-update-*.tar.gz archive and its .sig signature file (required;
without a valid signature, the appliance refuses to install).
The update does not touch your data; it updates the appliance software. Shares stay served during the operation; no new archiving task starts before it finishes.
Roll back#
If an update causes a problem, the Settings → Updates screen offers two ways back:
- Code versions: Roll back to vX.Y.Z switches back to the previous version, installed side by side, then restarts the console. Your data is kept: this is the right way to undo an update.
- Rollback points: Roll back restores the data pool snapshot taken before the update, then restarts. Everything written since is lost, on every share, and the code version does not change: keep it for the case where data was damaged.
You can also download a configuration backup (Settings → Maintenance — configuration, without user data, secrets not included in clear text) for archiving.
For each major update, plan a maintenance window and check that the shares work properly after restart.
Security and routine maintenance#
- Hardening: the Settings → Security screen provides a read-only audit (updates, ports, SSH, accounts…), two-factor authentication (TOTP) and API tokens. The local firewall is not shipped in this version: filter the network upstream of the appliance. Pinning NFS ports is set in Advanced settings.
- TLS certificate (Settings → TLS): obtain a trusted certificate (ACME), import a certificate from your authority, or generate a signing request (CSR) — the private key never leaves the appliance.
- Support bundle: in case of an incident, download the support bundle (Diagnostics → Support or Settings → Maintenance; logs and system state, secrets masked) to send to support.
- S3 purge: Settings → Maintenance → Purge orphaned cloud objects deletes from the cloud old versions and files deleted beyond the retention (run a Dry run first).
Going further#
- Understand the concepts: product overview.
- Screen by screen: administration guide.
- Solve a problem: troubleshooting and FAQ.