LGM-OS administration guide

46 min · 19 sections

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>:5001. 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 three shared folders: Galeria for the photos, Musica for the songs and Peliculas for the video library.

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 and groups → 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.

Who sees what

Deny by default, and it holds for every door. A shared folder with no permission list belongs to the administrators and to nobody else: it does not show up when you connect to \\NAS, it does not open, and it cannot be reached over NFS or from the console either. To let somebody in, grant it in the Folders tab of their account.

Administrators always get into every folder, on top of whatever each list says. That is the second turn of the key: if some panel check is bypassed, you still have to be an administrator. The exception is a deliberate "no access" on a specific person, which overrides everything else — including for an administrator.

My Drive. Every account has its own private folder, at <volume>/homes/<account>/archivos. It shows up in Files, when connecting to \\NAS —where each person sees theirs and only theirs— and it is also where their SFTP lands: all three doors lead to the same folder. It is where you leave your own things without setting up a shared folder. Nobody else gets in: not other accounts over the network, not by typing the path into the panel.

What is not yours is not shown. Neither in the panel nor in the Windows folder list: only the ones that account can open are listed, so not even the names are readable. An administrator sees everything, as always.

The Control Panel, by role. An ordinary account finds three things there: the system information, their password and second factor, and the region and appearance. The rest are administration screens and are not offered; if they reach one through a direct link, it says so.

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.

On the same record, "Child account" (only for people who sign in to the panel, and only an administrator can set it): that person will see in Movies and series only what is rated suitable up to age 12, and nothing that has no rating at all. The trimming is done by the NAS and not by the screen, so it cannot be worked around by pasting a movie's address. See "Movies and series".

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 the ones the NAS creates itself: docker (the apps' data), vm (the virtual machines' disks), camaras (the recordings), Galeria (the photos and videos), Musica (the songs) and Peliculas (the video library). They can be shared over the network, given a recycle bin and permissions, but they cannot be renamed, moved or deleted: pulling them out leaves the cameras, the Gallery, Music and Movies pointing at a folder that no longer exists. They carry a SYSTEM badge in the list, and the ones already on your NAS get it when updating. Inside your My Drive you can create folders with those same names: they reserve nothing there. 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 a system folder, so it cannot be renamed or deleted from the panel. 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.

Music

• The NAS creates a shared folder "Musica" the first time there is a volume: it is the obvious place to leave the songs —it shows in Files and it is shared over the network, so you can drag your record collection across from the computer—, and Music always looks in it. It is a system folder: it cannot be renamed or deleted from the panel. Without an accent because a shared folder's name travels to SMB, to NFS and to a path on disk.
• It copies and moves nothing: it reads the audio files already in your shared folders and arranges them by artist, by album and by folder. The index is a separate SQLite file; deleting it does not touch a single song, and the next scan rebuilds it.
• It keeps itself up to date. It checks for changes every ten minutes and does a full pass every hour; "Scan for music" is still there for when you do not want to wait.
• If you pick no folders, it looks in every shared folder. A household's music lives in "Music", in "Discs", in "CDs" and inside each person's own folder, so guessing by name would leave the app empty without saying why; filtering by extension costs nothing. You can narrow it down from the screen itself (an administrator decides: it applies to the whole household).
• Formats: .mp3, .flac, .m4a, .aac, .ogg, .opus and .wav.
• Titles show up before the details do. While indexing, the file name stands in for the title and the folder name for the album, so you can listen straight away; artist, year, track and length are read afterwards, in batches and in the background. On a machine without ffmpeg it stops at the first part, and the screen says so in one line.
• Cover art: the cover.jpg (or folder.jpg, or front.jpg) in the album's folder. If there is none, the one embedded in the file itself is pulled out, copied without re-encoding. An album with neither is drawn with its initial: that is not an error.
• Fill in from the internet (off by default, switched on by an administrator). The NAS sends the names of your artists, albums and songs to seven free, key-less catalogues —MusicBrainz, Cover Art Archive, Deezer, iTunes, TheAudioDB, Wikipedia and LRCLIB— and brings back cover art, release date, genres, the artist's proper name, their photo, their biography and song lyrics. **No file and no personal data is sent, and not a single song is touched.** What you have at home always wins: the year in your own tags beats the catalogue's, and both cover.jpg and embedded art beat the one from the internet. It fills in bit by bit in the background —the catalogues accept few requests per second and the NAS respects that—; "Fill in now" does a long batch without waiting.
• Correct by hand (with "Fill in from the internet" on, and administrators only). The automatic matcher would rather leave an album without cover art than give it someone else's, so a folder called "Disco 1" matches nothing. The Correct button on an album's header, on an artist's header and in each song's menu searches that name in the catalogue and shows the matches with their cover art: choosing one applies its details, and **the album's artist goes to every song of that album that has none** —which is what removes the "No artist" from half a CD-ripped library—. What you choose by hand is never re-matched on its own, and on a song it can be undone to put back what its own file said.
• Identify untagged songs (off by default, switched on by an administrator). Songs that arrived as Track01.mp3 —ripped from a CD without looking anything up— are identified by their sound: the NAS computes an acoustic summary of the first two minutes, asks the free AcoustID catalogue and gives them title, artist and album. No file is sent, only that summary, and not a single song is touched: what comes back is written into the library. Every row has a button to identify that song right away and, on the ones already identified, to put them back to what their own file said. Only what looks untagged is looked at (no artist, or titles like "Pista 3" or "AudioTrack 07"); anything already correct is left alone. Identified songs then go through "Fill in from the internet" like any other, which is how they get cover art and a release date.
• A free key is needed: sign up at acoustid.org/new-application and paste it into Music's settings. Without a key the feature is explained and stays off; the key is checked against AcoustID before it is stored and never travels in the backup.
• Lyrics: fetched when you open a song, not while indexing, and then stored. If the lyrics are synced, the line being sung is highlighted and tapping a line jumps to that moment. An .lrc or .txt file with the same name next to the song wins over the internet and works even with "Fill in from the internet" switched off.
• Music is served in ranges, so you can jump to a given minute without downloading the whole song. It keeps playing when you switch tabs and with the window minimised.
• Playlists and favourites belong to each person: nobody else sees them, and deleting a playlist does not touch a single file on disk.
• The boundary is the usual one: what you cannot open in Files does not appear here, neither its name nor its cover.

Radio

• Thousands of internet stations, in the "Radio" tab. They come from the free radio-browser.info catalogue: no account to create and no key to paste.
• Search by name, by country (yours comes preset) and by topic. With nothing searched you get the most listened to stations in your country.
• The sound goes through the NAS, not through your browser. That is what makes stations that still broadcast unencrypted play at all — a browser blocks them inside a secure page, silently — and, along the way, the station sees a single connection instead of one per phone and computer in the house.
• The station is checked before it starts. An open catalogue has stations that have been off for years: that is why pressing takes a second longer and, when something is wrong, it says what ("it did not start playing within 10 seconds") instead of leaving a silent player.
• Your stations are yours: the saved ones and the recently played ones are seen by nobody else, not even by whoever administers. They travel in the configuration backup.
• It plays in the usual player: it stays on when you switch tabs and it is controlled from the media keys on the keyboard and from the phone's lock screen.

Podcasts

• Subscribe by name or by pasting its RSS address, in the same box. Names are searched in the public iTunes catalogue; from then on the NAS talks directly to whoever publishes the podcast.
• Everyone follows their own. Nobody sees what you subscribe to or where you left off, not even whoever administers. A show is downloaded ONCE even if three people in the house follow it.
• It refreshes on its own every six hours, and "Refresh" does it right away. If a show stops answering, its record says so and its episodes stay where they were.
• Tell me about new episodes: a switch per person. One notice per show and per pass, never one per episode.
• Where you left off is remembered for each episode, as in Movies and series, and you can mark one as played by hand. Here too the audio goes through the NAS, and jumping to a given minute still works.
• What is downloaded is the episode listing, not the audio: **episodes take up no space on the NAS**.

Movies and series

• The NAS creates a shared folder "Peliculas" the first time there is a volume: it is the obvious place to leave movies and series —it shows in Files and it is shared over the network, so you can drag them across from the computer—, and the app always looks in it. It is a system folder: it cannot be renamed or deleted from the panel. Without an accent or spaces because a shared folder's name travels to SMB, to NFS and to a path on disk.
• It copies and moves nothing: it reads the videos already in your shared folders and sorts them into movies and series. The index is a separate SQLite; deleting it does not touch a single file.
• You pick the folders (an administrator's decision: it applies to the whole household). If you pick none, it looks in "Peliculas" and in the shared folders whose name sounds like a video library ("Movies", "Series", "Cine"). Camera recordings never get in.
• The file name is the record. From "Inception (2010).mkv" it takes the title and the year; from "Show.S01E02.mkv" or "Show - 1x02.mkv", the series, the season and the episode, and it groups them. Out of the box nothing outside is consulted, so what you see is what is in the file: a well-named file makes all the difference.
• Fill in from the internet (Settings, an administrator's decision). Off out of the box, and while it is off the NAS tells nobody what movies you have. Turned on, it sends **the title and the year of each movie and series to Wikidata, Wikipedia and TVmaze**, and fetches cover art, synopsis, genres, release date and the episode titles. Nothing else leaves: no paths, no file names, no who watches what.
• Two optional, free keys. With the themoviedb.org one (either the "API Key (v3)" or the v4 token) the covers are better and you also get the trailer, the cast and the collection; with the omdbapi.com one, the IMDb rating. Without either it works just the same, with what Wikipedia and TVmaze give. Each key is tested when you save it: if the catalogue does not recognise it, it is not saved and you are told why. Keys never leave the NAS and do not travel in the configuration backup.
• What is at home wins. If there is a .nfo next to the movie (the one Kodi, Jellyfin and library organisers leave), the title and synopsis come from it; and if the file or folder name carries an IMDb id (tt1375666), the record is fetched exactly instead of being searched by title.
• It fills itself in little by little after each scan; "Fill in now" does a long batch without waiting. Whatever no catalogue recognises is left alone and not asked about again; whatever failed because of the network is retried a few hours later.
• "Fix match", in the record, pairs it by hand: it searches by title and year and shows the candidate records with their covers so you can pick the right one.
• The trailer opens outside, in a new tab: no third-party player is embedded in the panel.
• "You might like" and "For you". A movie's or a series' record shows a row of up to eight similar titles, and the home tab shows another one built from what you have watched lately (nobody sees anyone else's). Only what is ON the NAS is recommended, and only inside your folders: there is nothing to go and look for elsewhere. With a themoviedb.org key its own recommendations are used and crossed with your library; without a key the comparison is by collection, genres and decade, which is what "Fill in from the internet" brings. With that feature off there is nothing to compare against and the rows do not show. What is worked out is kept for a week; fixing a match by hand rebuilds it.
• Tell me about new episodes (Settings, under "Fill in from the internet" and inside it: with that one off, this asks nothing). Once a day the catalogue is asked, for every series on the NAS, which was its last aired episode; if that one is not here, a panel alert arrives with the season, the number, the title and the date it aired. Each episode is announced only once, even if it stays missing. With a themoviedb.org key it is asked there; without any key, TVmaze. A series matched to Wikidata or OMDb gives no such alert: those catalogues do not list episodes with their dates.
• Cover art: the image next to the file always wins (Inception (2010).jpg, poster.jpg, folder.jpg); then the one downloaded from the catalogue; and if there is none, the NAS grabs a frame from 10 % into the movie. A movie with none of the three is drawn with its initial: that is not an error.
• It keeps itself up to date. It checks for changes every ten minutes and does a full pass every hour; "Scan for movies" is still there for when you do not want to wait.
• It plays in the panel. What the browser opens as-is is served in ranges (with its own seeking); what it cannot —a movie with Dolby Digital sound, an MKV on an iPhone— the NAS converts on the fly, copying the video when changing the sound is enough. The screen says when it is converting and why.
• Quality: next to the subtitles, while you are watching. "Original" is the usual one; 1080p, 720p and 480p ask the NAS to scale the picture down, which is what you need when you watch away from home or on a phone and it stutters. Only the qualities smaller than the movie are offered. Changing it keeps your minute, and it stays chosen on that device for the next ones.
• Subtitles: the .srt or .vtt files next to the video, with the language in the name if they carry one (Inception (2010).en.srt). They are converted on the fly to what the browser understands.
• Fetching them from the internet. Every movie's record has a "Find subtitles" button: it shows what the catalogue has for that title in the panel's language and downloads the one you pick. The file is left next to the movie (Inception (2010).en.srt), so from then on the whole household has it; if that folder cannot be written to, it stays on the NAS and shows up all the same.
• The ones marked "For this file" are the ones in sync with your exact copy: the catalogue matched them by a fingerprint of the file, not by the title. The rest may run early or late against your particular cut.
• "Automatic subtitles" (Settings, under "Fill in from the internet", off by default): with it on, opening a movie that has no subtitles in your language makes the NAS look for them once and put them in place. What it does not find is not asked for again on its own; the manual button does try again every time you press it.
• What leaves the house is the title, the year and that file fingerprint; never its path nor who is watching. The source is opensubtitles.org, and it works without registering anywhere.
• opensubtitles.com account, optional. Without it subtitles are still searched and downloaded, using the daily quota everyone shares; with your own free account (key, user and password) the quota is yours. It is tested when saved: if it is not recognised, it is not stored and you are told why. It never leaves the NAS and does not travel in the configuration backup.
• It picks up where you left off. Each account keeps its own minute and nobody sees anyone else's; at 95 % the movie counts as finished and drops out of "Keep watching". In a series the next episode is offered.
• "Keep watching" on the desktop too. The "+" button on the widget panel (top right) turns on the "Keep watching" widget: up to six half-watched movies or episodes with their cover and how far in they are, and one click opens the app on that movie. It is only offered to accounts that have Movies and series.
• Child accounts. Ticking "Child account" on a person's record (Control Panel → Users and groups) makes that account see here only what is rated suitable up to age 12: the catalogue, the series, the search, "Keep watching" and the player. The trimming is done by the NAS, not by the screen, so pasting them the address of an unsuitable movie does not open it either. Anything without a rating does not show up either, so turn on "Fill in from the internet" —that is where ratings come from— or their library will stay almost empty. The app says so in one line, so it does not look broken.
• The boundary is the usual one: what you cannot open in Files does not appear here, neither its name nor its cover.

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 (more than 3,000 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, and only inside the window you choose (03:00 to 06:00 by default): an update restarts the services and the camera recorders, and in the small hours that bothers nobody. Outside the window the notice still arrives.
• 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.

What the NAS tells the web

Every twelve hours the NAS asks the version server whether its licence —or its trial— is still valid, and in the same call it reports its name, the version it runs, how much space it has left and whether it has pending alerts: that is what you see on your NAS's card in your account on the web. The fingerprint of the panel's certificate and its addresses inside your home network travel too: that is how the LGM Connect app finds the NAS without going out to the internet.

The same report carries the machine's technical details, so that we can help you if something fails: board maker and model, processor, memory, the disks (model, size, type and health), how the volumes are laid out, the kind of network and graphics cards, and how many apps, virtual machines and cameras there are. No serial numbers, no network addresses and nothing of yours inside (no file names, no accounts). Switch them off in Control panel → Licence → Technical details and support; See what gets sent —inside "Did something go wrong?"— shows exactly what goes out. New versions arrive in waves: each machine gets its turn on a different one of the first days, and "Install anyway" brings it forward.

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.

Resource monitor

What the NAS has been doing while you were not looking. The Monitor app records processor, memory, disk and network usage and draws it in four charts, with the range of your choice: last hour, day, week or month.

It answers the three questions an instant number cannot:

• "It feels slow... since when?" - a step in the CPU or memory chart gives the day and almost the hour it started, which usually matches an app you installed or a new backup.
• "Is it running out of memory?" - a flat ceiling at 100% for hours is exactly that; short spikes while copying files are normal.
• "Am I using the network well?" - the network chart during a big copy tells you whether the bottleneck is the disk or the cable.

The history is written by the NAS itself every few minutes and takes very little space: nothing to switch on, it is already running. Reinstalling or destroying the volume starts it over, because it is history, not data.

Web terminal

A real shell in the browser, administrators only. It starts as the service user (nas, unprivileged), and the "Root session" button opens an administrator shell. Both —and a container console in Docker too— first ask you to confirm your password and the second-factor code if you have it on (or a passkey): the permission is a one-time token that expires in 60 seconds and only opens the console it was asked for. The root session 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.

Licence and trial

LGM-OS is a one-off purchase: a lifetime licence with updates included. Everything happens in Control panel → Licence.

• Linking your account. Press Link my account: the panel shows a code and an lgm-os.com address. Open it on any device —your phone will do—, sign in with your free account and choose what to do with that NAS: start the trial or use a licence of yours. The panel finds out by itself within seconds; there is no key to copy.
• The trial lasts 60 days and opens everything except the LGM Connect address, which comes with the licence. It is one per machine and belongs to the account that started it: reinstalling carries on with the same trial and the same end date.
• A freshly installed NAS has 7 days to be linked. Until then it works in full and the panel reminds you.
• If you own several licences, when linking you choose which one goes on that machine and give it a name ("Home", "Office") to tell them apart in your account.
• With a purchased licence there is nothing to link: I have a key → Paste a key works just as it always did.

When the trial ends: "data only"

Without a licence, once the trial —or the 7 days without linking— is over, the NAS goes into data only. Your data is never held back:

• What keeps working is whatever lets you take it with you: signing in to the panel, browsing and downloading all your files, the shared folders read-only from your devices, disk status and its alerts, updating the system, shutting down and restarting.
• Everything else is paused: apps and virtual machines stop, cameras stop recording, and backups and scheduled tasks do not run. The VPN and your home name keep working: if you are away, you can still get in for your files and to activate the licence.
• Nothing is deleted. When you activate a licence, whatever was running starts again just as you left it.

Did something go wrong?

Did something go wrong? sits on the desktop's top bar —on a phone, first thing in the control centre— and in Control panel → Licence. It sends a report to support: what you write, the version and the app that failed. If you leave the box ticked, it carries the machine's technical details and the last error lines of the panel, from which the NAS first strips passwords, addresses carrying credentials, email addresses and personal folder paths. Nobody gets into your NAS: the report is the only thing that leaves it.

System

• Machine name: the one you set when installing is changed in **Control Panel → System information, with the Change** button next to the name. Only lowercase letters, numbers and hyphens (1 to 63, and it cannot start or end with a hyphen): it is a machine name, not a title. It is the address the NAS is reached at (https://<name>.local:5001), so after changing it you have to update the bookmarks around the house. The NAS announces itself on the network again on its own (the Mac Finder and Windows "Network"); the panel certificate carries the name inside and is reissued on the next restart, so until then the browser warns when you come in through the new name.
• Network: static IP/DHCP per interface via systemd-networkd. ⚠️ A mistake here can leave the NAS unreachable; keep a physical console at hand.
• Time: the time zone and NTP synchronisation live in Control Panel → Region & language. Below them, Time servers lets you write your own, one per line (pool.ntp.org, or your router's address, which almost always serves the time). Empty = the ones the system brings, which is the normal case; you change them when the network has no way out to the internet or has 123/UDP closed, because a clock that drifts expires certificates early and fires scheduled tasks at the wrong time.
• 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 → System 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.
• Send the logs to another device (syslog): Control Panel → Log center → *Send the logs to another device*. Sends a copy of everything the NAS writes to a log server on your network (device, port —514 by default— and UDP or TCP). Useful to keep everything together and, above all, to keep the trail outside the NAS if someone breaks in. Saving tests the destination: with TCP the answer is real, and with UDP only that the device exists on the network, because nobody confirms a datagram. It is done by rsyslog, which LGM-OS installs and leaves switched off until you turn this on; a NAS installed before 1.65 may not have it and the screen tells you how to add it.

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, with the machine's addresses inside it and a validity of 396 days —under the 398-day limit iOS and iPadOS accept; beyond that, an iPhone will not let you into the panel even past the warning—. It is checked at every boot and reissued on its own if it is about to expire or the NAS changes IP; your own certificate, or a Let's Encrypt one, is never touched. 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.
• Session length: out of the box the panel signs you out after **30 minutes without using it, and it is changed under Control Panel → Security → Password rules → Session length** (5 to 1440 minutes). It is not a hard deadline: everything you do extends the session, so it never cuts you off while you are working and what expires is a panel left open and forgotten. Anyone who ticks «keep me signed in» still gets 30 days, and sessions already open last as long as they were given: the new limit applies from the next sign-in.
• Roles: admin (full) and viewer (read only), managed under Security.
• Never open port 5001 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 → 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 5001 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 → VPN, DNS and DHCP. 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. Every port the app publishes (and, if it shares the NAS network, the ones its recipe declares) gets a firewall rule named after the app when it is installed, open to the home network. In Security → Firewall it can be closed or opened to any source; that choice comes back if the app is reinstalled, and the rule goes away when it is uninstalled.

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>"
    }
  ]
}