- Go 45%
- TypeScript 32.5%
- Shell 20%
- CSS 1.3%
- Makefile 0.9%
- Other 0.1%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
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> |
||
| build | ||
| cmd | ||
| docs | ||
| initramfs | ||
| internal | ||
| locales | ||
| pluginsdk | ||
| rootfs | ||
| sdk | ||
| test | ||
| tools | ||
| web | ||
| .gitignore | ||
| CHANGELOG.md | ||
| CLAUDE.md | ||
| firenas-icon.png | ||
| firenas-product-logo-white.png | ||
| firenas-product-logo.png | ||
| go.mod | ||
| go.sum | ||
| LICENSE.md | ||
| Makefile | ||
| NOTICE.md | ||
| README.md | ||
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,/mediaor/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.