No description
  • Go 45%
  • TypeScript 32.5%
  • Shell 20%
  • CSS 1.3%
  • Makefile 0.9%
  • Other 0.1%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Michael J. Manley c603a8dddd Storage, file manager, depots and LTS, containers from the web, share permissions
Work that accumulated uncommitted on top of the LDAP/AD commit; its pieces
share files line by line, so they land together. CHANGELOG "Unreleased" has
each entry.

Storage and files
- Storage volumes (docs/storage.md): data disks formatted, attached and
  mounted from the API and web console; virtiofs volumes; virtiofs and xfs
  mounted with acl; firenas-storage service.
- Shares on volumes (share location), reported once when the filesystem has
  no POSIX ACLs.
- File manager in the web console, limited to mounted volumes.

Share permissions
- Every share has an Everyone setting (read and write, read, or none) that
  also sets the folder's "other" ACL entry.
- Share ACLs shown in the web console, with hand-added u:/g: entries
  (extra_acl) kept in nas.json.
- A share's owner and owning group (a user, a group or a numeric id), the
  owning group's access, and optionally forcing new files to them (SMB force
  user/group, NFS all_squash, FTP UserOwner/GroupOwner).
- SMB names group grants as groups (+group) and refuses users denied SMB.
- Saving a share can reapply its permissions to what is already in it.
- Home folders can live on a storage volume (settings.homes.location).

Directory and security
- Active Directory ids from RFC 2307, trusted domains.
- Auto block of addresses that fail to sign in, covering Docker containers.
- Containers may not publish file sharing ports.

Updates and depots
- Updates from the depot, the depot URL no longer configurable, the LTS
  channel and lines; the channel's buttons are in the depot toolbar.
- make depot back without Alloy (docs/depots.md); Alloy support removed.

Containers, deployment, docs
- Containers and Compose stacks created from the web console, as in Iron.
- No OVA: the installer ISO and the update bundle (docs/deployment.md).
- Boot menu shows the slots; SSH on 2222 and SFTP on 22; FireNAS's icon.
- docs/building.md (Makefile reference) and docs/features.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 00:08:31 -08:00
build Storage, file manager, depots and LTS, containers from the web, share permissions 2026-11-03 00:08:31 -08:00
cmd Storage, file manager, depots and LTS, containers from the web, share permissions 2026-11-03 00:08:31 -08:00
docs Storage, file manager, depots and LTS, containers from the web, share permissions 2026-11-03 00:08:31 -08:00
initramfs Rename Wise Foundry Bronze to Wise FireNAS 2026-11-03 00:07:16 -08:00
internal Storage, file manager, depots and LTS, containers from the web, share permissions 2026-11-03 00:08:31 -08:00
locales Storage, file manager, depots and LTS, containers from the web, share permissions 2026-11-03 00:08:31 -08:00
pluginsdk Rename Wise Foundry Bronze to Wise FireNAS 2026-11-03 00:07:16 -08:00
rootfs Storage, file manager, depots and LTS, containers from the web, share permissions 2026-11-03 00:08:31 -08:00
sdk Rename Wise Foundry Bronze to Wise FireNAS 2026-11-03 00:07:16 -08:00
test Storage, file manager, depots and LTS, containers from the web, share permissions 2026-11-03 00:08:31 -08:00
tools Storage, file manager, depots and LTS, containers from the web, share permissions 2026-11-03 00:08:31 -08:00
web Storage, file manager, depots and LTS, containers from the web, share permissions 2026-11-03 00:08:31 -08:00
.gitignore Rename Wise Foundry Bronze to Wise FireNAS 2026-11-03 00:07:16 -08:00
CHANGELOG.md Storage, file manager, depots and LTS, containers from the web, share permissions 2026-11-03 00:08:31 -08:00
CLAUDE.md Storage, file manager, depots and LTS, containers from the web, share permissions 2026-11-03 00:08:31 -08:00
firenas-icon.png Storage, file manager, depots and LTS, containers from the web, share permissions 2026-11-03 00:08:31 -08:00
firenas-product-logo-white.png Storage, file manager, depots and LTS, containers from the web, share permissions 2026-11-03 00:08:31 -08:00
firenas-product-logo.png Storage, file manager, depots and LTS, containers from the web, share permissions 2026-11-03 00:08:31 -08:00
go.mod Rename Wise Foundry Bronze to Wise FireNAS 2026-11-03 00:07:16 -08:00
go.sum File sharing: LDAP and Active Directory users and groups 2026-10-31 16:21:28 -07:00
LICENSE.md Bronze: start from Wise Foundry Steel 26.10 (7dcaeaa), renamed 2026-10-31 12:24:04 -07:00
Makefile Storage, file manager, depots and LTS, containers from the web, share permissions 2026-11-03 00:08:31 -08:00
NOTICE.md Storage, file manager, depots and LTS, containers from the web, share permissions 2026-11-03 00:08:31 -08:00
README.md Storage, file manager, depots and LTS, containers from the web, share permissions 2026-11-03 00:08:31 -08:00

Wise FireNAS

Wise FireNAS is the file server appliance of Wise Foundry: Wise Foundry Steel's immutable Alpine Linux system (signed dm-verity root in A/B slots, signed updates, Docker, plugins) with a file server in the image.

  • File sharing (docs/nas.md): one set of users, groups and shares served over SMB, NFS, FTP/FTPS and SFTP, with POSIX ACLs as the one permission model. FTP and SFTP users start in their home folder and find a folder there for each share they are granted. Block storage over iSCSI; users and groups also from LDAP or Active Directory (with RFC 2307 ids and trusted domains); an address that keeps failing to sign in is blocked from every service. It is managed from the web console's File sharing pages, /api/v1/nas, and the FireNAS Console. Features and their status: docs/features.md.

Everything else is Steel's, a Docker-only sibling of Wise Foundry Iron (no libvirt, VMs or LXC):

  • Containers are created from the web console or the API. The web console and any client with an API token create, recreate and remove containers, pull images, manage volumes and networks and deploy Compose stacks over https://<appliance>:8443/api/v1, with the same validation; loading an image archive is API-only.
  • The web console (https://<appliance>:8443/; port 8080 redirects) manages containers (a creation wizard with published ports, details with logs and statistics, images, volumes, networks and stacks with a Compose editor), installs updates and rolls them back, changes the host name, management network and time settings, restarts or shuts down the appliance, and manages SSH and the emergency shell.
  • Storage volumes on the other disks: the web console's Storage pages format one disk (ext4, xfs, exFAT, FAT32) or several with btrfs, or attach a filesystem a disk already holds, and mount it beneath /mnt, /media or /srv; shares can live on ext4, xfs and btrfs volumes (docs/storage.md).
  • The console (VM console, monitor or serial port) configures the management network and time, and offers Troubleshooting Options (emergency shell, SSH, agent restart) and Shut Down/Restart. When no administrator password exists yet, it asks for one first.
  • Backup, restore and diagnostics: encrypted configuration backups (with optional container data) that restore at the next boot, support bundles without secrets, host metrics, logs, audit events and remote syslog — all through the API and the web console.
  • SSH and the emergency shell are disabled by default, as in Iron: enabled by an administrator (web console, API or console) for troubleshooting, SSH accepts only root with authorized keys, on port 2222 (22 is SFTP's).
  • Upgrades use Iron's mechanism. A/B root slots, Ed25519-signed update bundles (.firenasupd), systemd-boot boot counting with a post-boot health check, automatic fallback and rollback — driven through the API, firenas-update, or the installer ISO.

The root filesystem is a read-only dm-verity verified EROFS image booted from a signed unified kernel image; configuration lives on /persist and container data on /var. An update or rollback never touches either.

Design and contracts: docs/architecture.md. Installing and deployment properties: docs/deployment.md. API: docs/web-api.md. Console and installer: docs/console-ui.md.

Building

Requirements: podman, make. Builds run rootless in an Alpine 3.24 builder container, which also supplies openssl and sbsigntool for make keys.

make             # = make help: every target and variable; builds nothing
                 # (the full reference: docs/building.md)
make keys        # development signing keys in ./keys (never commit)
make image       # development (debug) images -> out/firenas-<v>-dev.{iso,firenasupd}
make release     # release images             -> out/firenas-<v>.{iso,firenasupd}
make depot VARIANT=release FIRENAS_SIGNING_KEYS=DIR DEPOT_ROOT=/mnt/share
                 # the update share: PRODUCTION/rolling/firenas(-plugins) and
                 # PRODUCTION/firenas.rolling.xml (docs/depots.md)

There are two build variants: dev, the debug build (the default), and release, the production build.

<v> is YY.MM.PATCH (build/version.sh): YY.MM is this repository's branch when it is release/YY.MM, else (dev, any other branch, a detached HEAD, no git) the year and month of the build (UTC); PATCH is 0 unless given (make release PATCH=1); VERSION=YY.MM.PATCH overrides both. On dev, a later QEMU test run in another month needs VERSION=YY.MM.PATCH to find the build.

File Use
firenas-<v>.iso Hybrid UEFI installer (CD or USB): installs on a disk, or upgrades a disk that holds FireNAS
firenas-<v>.firenasupd Signed update bundle for POST /api/v1/updates/* or firenas-update apply
firenas-<v>.txt Build ID, kernel, root hash, checksums

Development images add a root shell on tty2 and ttyS1 (used by the QEMU tests) and are labelled "development" everywhere; release images have no login shell at all.

Upgrading

Every FireNAS release upgrades any earlier installation: the bundle format and disk layout are stable, the new version goes to the unused slot, and the previous version stays installed for rollback. A newer build of the same version also counts as an upgrade; anything else needs allow downgrade.

Through the API:

H="Authorization: Bearer $TOKEN"
curl -k -H "$H" -H 'X-FireNAS-Filename: firenas-1.1.0.firenasupd' --data-binary @firenas-1.1.0.firenasupd \
  -X POST https://firenas01:8443/api/v1/updates/upload                # -> {"path": ".../staging/firenas-1.1.0.firenasupd"}
curl -k -H "$H" -d '{"path":"/var/lib/firenas/staging/firenas-1.1.0.firenasupd"}' https://firenas01:8443/api/v1/updates/verify
curl -k -H "$H" -d '{"path":"/var/lib/firenas/staging/firenas-1.1.0.firenasupd"}' https://firenas01:8443/api/v1/updates/apply  # job
curl -k -H "$H" -d '{"action":"reboot"}' https://firenas01:8443/api/v1/host/power

The new deployment boots with three tries. firenas-health confirms it once firenas-agent and Docker are healthy; otherwise the appliance restarts until systemd-boot falls back to the previous deployment, and GET /api/v1/updates/status reports rolled_back. POST /api/v1/updates/rollback (then a reboot) returns to the previous deployment on request.

From installer media: boot the newer ISO, select the disk marked *, choose Upgrade Wise FireNAS, preserve configuration and data and confirm with F11. Unattended: MODE=upgrade and DISK=/dev/… in firenas-answers.conf on media labelled FNASANSWER.

From a shell: firenas-update fetch|verify|apply [--reboot]|status|rollback.

The appliance does not look for updates on its own: an administrator, or automation driving the API above, decides when and what to install.

Installing from the ISO

Boot the ISO on a UEFI machine or VM, pick a disk (at least 8 GiB) and confirm. After the first start, set the administrator password and the management network on the console. For unattended installs put firenas-answers.conf on a FAT or ISO volume labelled FNASANSWER:

MODE=install
DISK=/dev/sda
WIPE_CONFIRM=yes
HOSTNAME=firenas-edge01
NET_MODE=static
NET_ADDRESS=10.20.0.15/24
NET_GATEWAY=10.20.0.1
NET_DNS="10.20.0.2"
ADMIN_PASSWORD_HASH='$2a$12$...'
API_TOKEN=fns_...
POWEROFF=yes

Testing

make test-go       # Go vet and unit tests (API, updates, tokens, console and installer screens, ...)
make test-web      # web console typecheck, lint and tests
make test-unit     # firenas-update, firenas-install, firenas-health, firenas-config against fixtures (+ shellcheck)
make test-images   # out/test: base ISO/bundle and installed test disk (qcow2), a newer good bundle/ISO, a fault-injected bundle
make test-qemu     # deploy from the test disk, backup/restore + support bundle, Compose stack, API update + automatic rollback, ISO install, ISO upgrade, plugins (after make test-plugins) under QEMU/KVM

make test-qemu needs /dev/kvm, qemu-system-x86_64, qemu-img, OVMF (edk2-ovmf), socat, python3 and curl on the host, and internet access from the VM (it pulls busybox).

Using the API

TOKEN=fns_...   # the firenas.api.token deployment property, or: firenas-agent token create automation
curl -k -H "Authorization: Bearer $TOKEN" https://firenas01:8443/api/v1/containers
curl -k -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -X POST https://firenas01:8443/api/v1/containers \
  -d '{"name":"dns","image":"coredns/coredns:1.12.1","network":"host","restart_policy":"unless-stopped",
       "volumes":[{"type":"data","path":"/dns","destination":"/etc/coredns"}]}'
# Without a registry: load a `docker save` archive (a job; its result lists the loaded tags)
curl -k -H "Authorization: Bearer $TOKEN" -H 'X-FireNAS-Filename: app-images-0.1.0.tar.gz' \
  -T app-images-0.1.0.tar.gz -X POST https://firenas01:8443/api/v1/containers/images/load

Deploying stacks

Compose stacks are deployed from the web console (Docker containers › Stacks › Create stack, from a template or an empty file, with Validate before deploying) or through the API as YAML (docs/compose.md); they also appear as expandable sections on the Containers tab:

python3 -c 'import json; print(json.dumps({"name": "web", "compose": open("compose.yaml").read(),
  "env": [{"key": "TZ", "value": "UTC"}], "deploy": True}))' |
  curl -k -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
    --data-binary @- https://firenas01:8443/api/v1/stacks          # -> 202 {"job": {...}}
curl -k -H "Authorization: Bearer $TOKEN" https://firenas01:8443/api/v1/stacks/web

Bind mounts must be data directories /var/lib/firenas/data/<name>; privileged services, host devices and the host network (except for administrators) are refused.

Accounts

The built-in admin account (password from the deployment properties, the installer answers, or set on the console) signs in to the web console and the console. Additional accounts are managed from a shell with firenas-agent user ...; API tokens with firenas-agent token ... or /api/v1/tokens. Accounts are also managed through /api/v1/users (docs/web-api.md "Accounts").

Role Can
Administrator everything: containers, tokens, updates, power, host name, network, time, services, SSH, emergency shell
Operator view, start/stop and create/remove containers
Read-only view the appliance and its containers

Secure Boot and signing keys

FireNAS uses Wise Foundry Iron's key scheme (docs/release-keys.md): key sets dev (keys/, make keys), test (under out/test/) and release (outside the repository, FIRENAS_SIGNING_KEYS). The build variants are dev (the debug build) and release (production). Each set has Secure Boot PK, KEK and db keys (RSA-2048, with .esl/.auth enrollment files) and an Ed25519 update key; db signs systemd-boot and the UKIs, update signs bundle manifests, and its public key is in every image at /usr/share/firenas/keys/update.pub.

make keys                                                   # dev set in keys/
make keys KEYSET=release FIRENAS_SIGNING_KEYS=/secure/firenas-release
make release FIRENAS_SIGNING_KEYS=/secure/firenas-release       # out/firenas-<v>.*

build/keyguard.sh refuses a key set that does not match the variant; images never contain private keys, and appliances cannot move between key sets.