LGM-OS administration guide

This document is the day-to-day manual: it covers everything you do from the panel, from start to finish. When a subject needs more detail than fits here, it has its own guide:

Full documentation index: index.md.

The first ten minutes

This is the whole path from switching the machine on to having the NAS doing something useful. It is meant to be done in one go, in order, and every step says why it matters —the ones people skip because they do not understand them are exactly the ones they miss on the bad day—.

1. Signing in (1 min)

Open https://<nas-ip>:5000. The machine's own console shows the IP when it boots.

The certificate is self-signed and the browser warns you: that is normal on a machine in your house —accept it—. If it bothers you, it is replaced with a real one later (see Access from the internet).

The first-run wizard asks you to create the administrator: a lowercase name and a password of at least 8 characters. There is no factory username or password, so nobody can get in before you.

2. Preparing the disks (2 min)

Storage → Create pool. It only offers disks that can be used: the system disk never appears, and one with data on it is flagged so you do not format it by accident.

• A single disk: it works, but it protects you from nothing. Fine to start with.
• Two or more: choose mirror. If one dies, nothing is lost and you swap it from the panel. It is the difference between a scare and a loss.
• Btrfs or ZFS: Btrfs if you are not sure (it asks for the least memory); ZFS if you are going to fit plenty of RAM and want the most integrity.

When it finishes, the NAS creates the system folders on its own (docker, vm) and a shared folder Galeria for the photos.

3. One folder and one account per person (3 min)

Control Panel → Shared folders → "Create". Give it a short name with no accents (it travels to Windows, to a Mac and to phones).

Control Panel → Users → one account per person, not a shared one. That is what lets you give different permissions, see who has signed in and take one person's access away without changing the password for the whole house.

On each folder, the SMB switch publishes it on the network. From Windows you open it with \\<nas-ip>; from a Mac, with Cmd+K → smb://<nas-ip>.

4. The backup (3 min)

This is the step nobody does and everybody regrets. A NAS with a mirror protects you from a disk breaking; it does not protect you from deleting something by mistake, from ransomware or from the house burning down. For that you need a copy OUTSIDE.

Backups → "New" → choose which folders and where to (a USB disk, another machine over SSH or your cloud). Full guide: Backups.

And the one thing that is not optional: restore any file at all to check the backup works. A backup you have not restored is not a backup, it is a big folder.

5. Closing the door (1 min)

• Control Panel → Security → turn two-step verification on.
• Control Panel → Firewall → enable it. The panel and SSH are always allowed, so you cannot lock yourself out.
• Control Panel → Alerts → set up email or a webhook and press "Send test". Without this, the NAS has no way of telling you a disk is failing.

And that is it

From here on, everything else gets added when needed: apps, cameras, access from outside or VPN. The rest of this guide is the reference, subject by subject.

Storage

• Create pool: Storage → "Create pool". The wizard only offers eligible disks (never the system disk). ZFS for maximum integrity (RAID-Z1/Z2), Btrfs for flexibility (RAID1/10). Formatting destroys the data on the disks.
• Datasets: subdivisions with their own quota and compression (Datasets tab).
• Snapshots: the Snapshots tab for manual ones; Control Panel → Scheduled tasks for automatic ones with retention. Restoring on ZFS uses rollback (it deletes later snapshots); on Btrfs it creates a writable copy restaurado-<date> to review first.
• Health: the Health tab shows SMART and lets you launch scrubs. Schedule a monthly scrub with a task. A disk with SMART reading "FAILING" must be replaced now: in "Pool disks" on that same tab you replace the failed disk with the new one (and enlarge the pool with extra disks) without dropping to the console.

Backups

Snapshots and RAID live inside the machine: they do not protect you from a fire, a theft or ransomware. That is what the Backups app is for, which takes the data out of the NAS.

• Destinations: local (a USB disk attached to the NAS or another pool) or remote over rsync over SSH (another NAS or server: a relative's house, the office, a VPS). The NAS generates its own SSH key and you only have to authorise the public part on the destination machine. Every destination is tested by really writing to it before you trust it with anything. The panel also lists S3 as unavailable, with the reason: uploading to S3 requires signing every request from the privileged process, and that process only runs binaries from the allowlist. It is declared in the API contract so it does not break the day it gets implemented, but today the API rejects an S3 destination instead of pretending it works.
• Tasks: source folders, destination, schedule and how many versions (or how many days) are kept. Every copy is incremental: only what changed travels, and previous versions stay complete through hard links (rsync --link-dest), so they take up little. They run with progress like the rest of the long tasks and warn through the alerts if they fail (set up Control Panel → Alerts: a backup that fails silently is not a backup). **Encrypting the destination is not available yet** and the API rejects it explicitly: if the destination is a disk that leaves the house, encrypt it yourself on the destination machine (LUKS) or keep it somewhere you trust.
• Restoring from the app itself: you pick the version and the destination folder. The history keeps every run with its size and its exact error.

What to copy, how often, how to authorise the key step by step and —most importantly— how to check the backup works by really restoring it: backups.md.

File sharing

Folders are shared from Shared folders, and each one's SMB and NFS badges are clickable to turn that protocol on or off without opening the editor.

The NAS shows up on the network by itself. With SMB on there is no need to know the IP or configure anything on the machines: it appears in Windows "Network", in the macOS Finder sidebar and in the Linux file manager. Sharing and announcing yourself are different things, and that is why the firewall opens five ports, not two:

The last three only announce that this machine exists; they give access to nothing. They open and close with the SMB switch, so turning it off withdraws them all.

About the protocol: the highest one both sides support is negotiated, and with modern Windows 10/11, macOS and Linux that means SMB 3.1.1 with encryption. The minimum is left at SMB2 on purpose, so as not to shut out a television or a scanner that only speaks that version.

One person, one account

Everything is managed in Users and groups. Each person has one password and four capabilities ticked on their record:

Unticking a capability really withdraws it (before, permissions were only granted, and unticking did nothing). The Folders tab on their record hands out access folder by folder: no access, read and write, or read only, and it also shows what they inherit from their groups. Saving without typing a password keeps the one they had; a new one is only needed to enrol them in a service they did not have yet.

The panel will not let you end up without an administrator: not by removing your own access, nor by demoting or deleting the last one left.

Finding files

• The Files search rests on a name index the NAS maintains on its own: a pass every two minutes that only looks at folders whose date has changed, so it does not reread the whole disk and you do not notice it. Searching becomes instant and, above all, complete: the live walk gave up at 60,000 entries and returned "there is more than what is shown".
• The index lives in the system state (/var/nas/state/indice.db), not next to your data, and only stores paths: who can see what is still decided by the shared folder on every search. It takes up little —about 20 MB per 150,000 files— and if it is deleted, it rebuilds itself.
• The first time it takes as long as it takes to read the tree —from seconds to a night, depending on how many files there are— and meanwhile searching works as before, by walking.
• Whatever you create, upload, move or delete from the panel is recorded straight away; whatever arrives over SMB or NFS shows up on the next pass.
• Refining the search does not need another Enter: once inside the results, changing the word redoes them on its own. Only when the index is ready; if it is not, searching still happens on Enter, so the NAS is not sent walking the disk on every keystroke.
• Searching inside the contents (the checkbox in the search box) also rests on the index —it asks which documents there are and in what order, newest first— but it opens and reads them at that moment, with its limits: indexing the text of everything really would cost disk and CPU.

The system folders

"Shared folders" also lists docker (the apps' data) and vm (the virtual machines' disks), like the "docker" folder in DSM: they can be shared over the network, given a recycle bin and permissions, but they cannot be renamed, moved, or have their data deleted. They only appear when the volume is prepared —it has its docker, vm and appstore folders—, which until now only happened on volumes created from the panel: an adopted one or one coming from a reinstall was left without them. The NAS now checks every ten minutes and creates them if they are missing.

Photos and videos (Gallery)

• The NAS creates a shared folder "Galeria" the first time there is a volume: it is the obvious place to leave the photos (it shows in Files, it is shared over the network and a phone can copy the camera roll there), and the Gallery always indexes it. It is created once: if you delete it, it does not come back. Without an accent because a shared folder's name travels to SMB, to NFS and to a path on disk.
• The Gallery copies and moves nothing: it reads the photos and videos already in your shared folders and lays them out on a timeline by month.
• It keeps itself up to date, every half hour. Whatever arrives over SMB —the phone's camera roll copy, which is how almost everything arrives— shows up without anyone pressing anything; "Index now" is still there for when you do not want to wait. If you pick no folders, it indexes "Galeria" and any shared folders whose name sounds like photos or videos (Fotos, Photos, Imágenes, DCIM, Vídeos); from the app itself you can pick them by hand. Neither the surveillance camera folder nor a film library get in: those are not memories.
• The index is a separate SQLite database filled in the background: the first pass over a big folder takes a while, and the app says it is scanning meanwhile. Unsharing a folder takes it out of the index on the next pass.
• Albums are lists, not folders: a photo can be in several and creating, renaming or deleting an album does not touch a single file on disk. Downloading one gives you a zip.
• Videos are served by ranges, so you can jump to a particular minute without downloading the whole file, and their thumbnail is a frame from second 1.
• Which formats get in: JPEG (including .jfif), PNG, WebP, AVIF, GIF, BMP, TIFF, HEIC/HEIF (iPhone) and camera RAW —.cr2, .cr3, .nef, .nrw, .arw, .sr2, .rw2, .orf, .raf, .pef, .srw, .rwl, .3fr, .erf— including the iPhone's ProRAW, which is a .dng. For video: .mp4, .mov, .m4v, .mkv, .webm, .avi, .3gp, .mts and .m2ts.
• RAW is not developed (that needs a whole image processor and seconds per photo): what is shown is the preview the camera left inside the file, which is a nearly full-size JPEG and is what every gallery does. exiftool extracts it; HEICs are opened by heif-convert. LGM-OS installs both; if they are missing, those photos are still indexed but end up without a thumbnail and the panel says so.
• Live Photos: the iPhone saves each one as two files (IMG_0042.HEIC and IMG_0042.MOV). The Gallery recognises them by name and shows a single item, with a "Live" badge and a button in the viewer to play the motion. Before, both things showed up and downloading a folder from the phone doubled the grid.
• Deleting from the Gallery sends things to the NAS recycle bin: you get them back from Files.
• The duplicate finder groups by size and start of file, and never lets you delete the last remaining copy of a photo.

Apps (Docker)

• Package Centre: installs local recipes (/var/nas/appstore/templates/) or synchronises catalogue sources (the "Catalogue sources" button). Besides our own https index with checksums, you can add community catalogues that the NAS converts into recipes when synchronising: Unraid's Community Applications (about 2000 apps with categories and icons) and CasaOS/ZimaOS stores. The sync runs as a task with progress; whatever a source brought in is withdrawn on its own if you later remove it, and hand-made local recipes are never touched.
• A search box, category chips with counters and an "Installed" filter to move around a catalogue of thousands of apps.
• The "⟳" button on an installed app downloads the new image and recreates the containers.
• The Docker app shows live logs, CPU/RAM and controls individual containers. A container created by hand (from the terminal, say) that publishes a TCP port gets its own "Open" button and appears in the Launchpad like any other app.

Updating LGM-OS without reinstalling

From the panel: Control Panel → Update LGM-OS → "Update now". Nothing else. There is no need to run the ISO again for every version, no need for access to the code and no repository to configure: the NAS asks the vendor's server which the latest version is, downloads it and installs it.

What happens underneath, in case it ever needs looking at:

1. The NAS asks for the latest published version and compares it with its own. It compares numbers, not text: 1.10.0 comes after 1.9.0.
2. It downloads the package and checks its SHA-256 against the one the server announced. If they do not match, it installs nothing and says so in those words: what arrived is not what the server said would arrive, which is very different from "the download failed".
3. It applies the update with the usual procedure: build, validate and only then promote. If the panel does not answer afterwards, it rolls itself back to the previous version.

From the console: sudo lgm update.

Options

• Automatic: "Check for updates automatically" notifies you in Notifications when there is a new version; "Install them without asking" applies them on their own every 6/12/24 hours or every 7 days.
• From your own code (only if you cloned the repository): if the machine has a git checkout with a remote, the panel uses it instead of the version server. That is the developer's route; for a NAS installed from the ISO none of this is needed.

While it updates

You will see a bar with the stage and an approximate percentage —backup, system packages, build the interface, backend, restart services—. The two long steps are installing the packages and building the interface: each takes several minutes without any sign of life, and that is normal. The panel restarts halfway: the bar says so and carries on counting as soon as it is back.

When it finishes, the updater checks that everything that was running is still running (Docker, Samba, libvirt, NFS…) and, if something was left stopped, it starts it and names it. The same if the update fails: a version that gives up halfway cannot leave you without containers or without shared folders.

If it fails

The red notice carries the last lines of the log —which is where the error is— and a dropdown with the full log. From the console:

sudo tail -n 40 /var/log/lgm-update.log

Since the update rolls itself back, the NAS carries on running the previous version: there is no rush to fix it. The two usual causes are running out of memory while building the interface (add 2 GiB of permanent swap) and running out of space; the panel tells the two apart and says so in those words.

Service check

Control Panel → System check reviews, one by one, the panel, storage, SMB, NFS, WebDAV, SSH, Docker, the backups and the cameras. It does not look at what the panel has saved as what should be happening: it looks at the system —whether the systemd unit is alive, whether something is listening on the port, whether the firewall lets it through, whether the configuration matches what was asked for— and every problem comes with what to do about it.

It is the first thing to open when something "does not work" from another machine: it says whether the fault is in the NAS or outside it, which is half the job.

Web terminal

A real shell in the browser, administrators only. It starts as the service user (nas, unprivileged). The "Root session" button opens an administrator shell after asking for your password again —and the TOTP code if you have it on—: the permission is a one-time token that expires in 60 seconds, the elevation is created by the privileged helper (the panel service runs with NoNewPrivileges=yes, where sudo cannot work) and every opening goes into the audit log. From there you can install whatever you like (docker run …, apt install …); if what you launch publishes a web port, it will show up in Docker and in the Launchpad.

System

• Network: static IP/DHCP per interface via systemd-networkd. ⚠️ A mistake here can leave the NAS unreachable; keep a physical console at hand.
• The server's screen (kiosk mode): if the machine has a monitor connected (or its virtual machine's console), it boots showing this same panel full screen, like any other operating system, and it is still administered over the web from the rest of the network as before. It is installed only when there is a screen and it is turned off with a switch in Control Panel → Machine information.

The console never disappears: the panel takes terminal 7 and the usual login stays on terminal 1. If the screen breaks —X does not start, the browser closes, the panel does not answer— Ctrl+Alt+F1 gives you a real console, and Ctrl+Alt+F7 goes back to the panel. From the console, lgm kiosk off turns it off, lgm kiosk log says why it is failing and lgm kiosk on turns it back on.

• Operating system updates: they are not done from the panel. An unattended apt upgrade can restart services or leave them half-done with nobody watching; whoever wants to update Debian has the terminal. What does update from the panel is LGM-OS, which is our own code and knows how to restart itself.
• Configuration backup: a one-off download or a scheduled "backup" task towards a pool. It carries all the panel's state (users, groups, shared folders with their permissions, services, firewall, network, tasks…) except the machine's secrets, which are regenerated. **It does not include your data** (the Backups app is for that); keep it inside the off-site copy, because it is the first thing you will need when rebuilding the machine. Detail and restoring in disaster-recovery.md.
• Logs: journald per unit; Audit: who did what and from which IP.

Security

• A two-process architecture: the API runs as the unprivileged nas user and delegates to nas-helper (root) through a Unix socket; the helper only accepts a closed list of commands and paths (backend/app/core/allowlist.py).
• TLS: self-signed, generated on first boot. The normal thing is to replace it with a Let's Encrypt one when publishing the NAS (see Access from the internet); to put your own in by hand: ```bash cp yourcert.pem /etc/nas/tls/cert.pem && cp yourkey.pem /etc/nas/tls/key.pem chgrp nas /etc/nas/tls/key.pem && chmod 640 /etc/nas/tls/key.pem systemctl restart nas-backend ```
• Login protection: 10 attempts/minute per IP; 5 failures in a row lock the account for 5 minutes. All of it goes into the audit log.
• Roles: admin (full) and viewer (read only), managed under Security.
• Never open port 5000 on the router: it serves the panel with a self-signed certificate and exposes the administration API with nothing in front. That workaround is no longer needed, because there are two better ways in from outside and the NAS ships both: the WireGuard VPN (which publishes no service on the internet) or external access with Apache on 80/443 and a valid Let's Encrypt certificate. The next two sections.

Access from the internet

Control Panel → Remote access → External access: dynamic domain (DDNS), a Let's Encrypt certificate and a reverse proxy to publish the panel and the apps by subdomain. Apache is left as the only exposed service (80 and 443) and forwards to 127.0.0.1; port 5000 and the apps' ports never leave the NAS. With a valid certificate, the interface can also be installed as an app (PWA).

The full procedure —router ports, DuckDNS step by step, issuing and renewing the certificate, subdomains and the security checklist to do first (2FA, Security advisor, IP blocking)— is in external-access.md. A more conservative alternative if you do not need to share with other people: the NAS's own VPN (next section), with no service exposed.

Network services (VPN, DNS and DHCP)

Control Panel → Network services. The three pieces that turn the NAS into the centre of the home network, ordered by risk:

• The VPN is the safest way to reach the NAS from outside: it publishes no service on the internet and gives access to the whole local network, not just the panel.
• DNS and DHCP are the same service (dnsmasq), so stopping it stops both: which is exactly what you need in an emergency (sudo systemctl stop dnsmasq).
• dnsmasq is installed disabled and only starts when you turn DNS or DHCP on from the panel.

Router ports, installing the VPN client step by step, how to point machines at the DNS and —most importantly— how to get the network back if DHCP leaves you with no connection: network-services.md. Read it before turning DHCP on, and keep it on your phone: if you lose the network, you will not be able to read it from the NAS.

Publishing apps in the catalogue

Each app is a directory /var/nas/appstore/templates/<id>/ with:

• manifest.json — id, name, description, images (pre-downloaded with progress), web_port and env (variables the installer asks the user for; secret hides them).
• docker-compose.yml — it consumes those variables plus NAS_APP_DATA (the data path the backend injects).

Installing requires a pool: each app's data lives in <pool>/docker/<id>/ (installations from before this policy stay in /var/nas/apps/ and are not moved). That docker folder is not a shared folder —the file manager and SMB/NFS do not show it— and its name is reserved when creating shared folders. If the manifest carries web_port, installing opens that port in the managed firewall (rule nas-app-<id>) and uninstalling withdraws it.

For a remote repository you serve an index.json over https:

{
  "apps": [
    {
      "id": "jellyfin",
      "manifest_url": "https://repo.example.com/jellyfin/manifest.json",
      "compose_url": "https://repo.example.com/jellyfin/docker-compose.yml",
      "sha256_manifest": "<sha256>",
      "sha256_compose": "<sha256>"
    }
  ]
}