Guía de administración de LGM-OS

Este documento es el manual del día a día: cubre de principio a fin lo que se hace desde el panel. Cuando un tema necesita más detalle del que cabe aquí, tiene guía propia:

Índice completo de la documentación: index.md.

Los primeros diez minutos

Este es el camino completo desde que enciendes el equipo hasta tener el NAS haciendo algo útil. Está pensado para hacerse seguido, en orden, y cada paso dice por qué importa —los que se saltan por no entenderlos son justo los que se echan de menos el día malo—.

1. Entrar (1 min)

Abre https://<ip-del-nas>:5000. La IP la enseña la propia consola del equipo al arrancar.

El certificado es autofirmado y el navegador avisa: es normal en una máquina de tu casa —acéptalo—. Si te molesta, se sustituye por uno de verdad más adelante (ver Acceso desde internet).

El asistente de primer acceso te pide crear el administrador: nombre en minúsculas y contraseña de al menos 8 caracteres. No hay usuario ni contraseña de fábrica, así que nadie puede entrar antes que tú.

2. Preparar los discos (2 min)

Almacenamiento → Crear pool. Solo te ofrece discos que se pueden usar: el del sistema nunca aparece, y uno con datos dentro se marca para que no lo formatees sin querer.

• Un solo disco: sirve, pero no protege de nada. Vale para empezar.
• Dos o más: elige espejo. Si uno muere, no se pierde nada y se cambia desde el panel. Es la diferencia entre un susto y una pérdida.
• Btrfs o ZFS: Btrfs si no tienes claro cuál (es el que menos memoria pide); ZFS si vas a poner mucha RAM y quieres lo máximo en integridad.

Al terminar, el NAS crea solo las carpetas del sistema (docker, vm) y una compartida Galeria para las fotos.

3. Una carpeta y una cuenta por persona (3 min)

Panel de Control → Carpetas compartidas → «Crear». Ponle un nombre corto y sin tildes (viaja a Windows, a Mac y al móvil).

Panel de Control → Usuarios → una cuenta por persona, no una compartida. Es lo que permite dar permisos distintos, ver quién ha entrado y quitarle el acceso a uno solo sin cambiarle la contraseña a toda la casa.

En cada carpeta, el interruptor SMB la publica en la red. Desde Windows se abre con \\<ip-del-nas>; desde un Mac, con Cmd+K → smb://<ip-del-nas>.

4. La copia de seguridad (3 min)

Este es el paso que nadie hace y todo el mundo lamenta. Un NAS con espejo protege de que se rompa un disco; no protege de un borrado por error, de un ransomware ni de que se incendie la casa. Para eso hace falta una copia FUERA.

Copias de seguridad → «Nueva» → elige qué carpetas y a dónde (un disco USB, otro equipo por SSH o tu nube). Guía completa: Copias de seguridad.

Y lo único que no es opcional: restaura un archivo cualquiera para comprobar que la copia sirve. Una copia sin restaurar no es una copia, es una carpeta grande.

5. Cerrar la puerta (1 min)

• Panel de Control → Seguridad → activa la verificación en dos pasos.
• Panel de Control → Firewall → actívalo. El panel y SSH quedan siempre permitidos, así que no puedes quedarte fuera.
• Panel de control → Alertas → configura el correo o el webhook y pulsa «Enviar prueba». Sin esto, el NAS no tiene forma de avisarte de que un disco está fallando.

Y ya está

A partir de aquí, lo demás se añade cuando haga falta: aplicaciones, cámaras, acceso desde fuera o VPN. El resto de esta guía es la referencia, tema por tema.

Almacenamiento

• Crear pool: Almacenamiento → «Crear pool». El asistente solo ofrece discos elegibles (nunca el disco del sistema). ZFS para máxima integridad (RAID-Z1/Z2), Btrfs para flexibilidad (RAID1/10). Formatear destruye los datos de los discos.
• Datasets: subdivisiones con cuota y compresión propias (pestaña Datasets).
• Snapshots: pestaña Snapshots para manuales; Panel de control → Tareas programadas para automáticos con retención. La restauración ZFS usa rollback (elimina snapshots posteriores); la de Btrfs crea una copia escribible restaurado-<fecha> para revisar antes.
• Salud: pestaña Salud muestra SMART y permite lanzar scrubs. Programa un scrub mensual con una tarea. Un disco con SMART «FALLANDO» debe sustituirse ya: en «Discos de los pools» de esa misma pestaña se reemplaza el disco averiado por el nuevo (y se amplía el pool con discos adicionales) sin bajar a la consola.

Copias de seguridad

Snapshots y RAID viven dentro del equipo: no protegen de un incendio, un robo ni de un ransomware. Para eso está la app Copias de seguridad, que saca los datos del NAS.

• Destinos: local (un disco USB conectado al NAS u otro pool) o remoto por **rsync sobre SSH** (otro NAS o servidor: casa de un familiar, la oficina, un VPS). El NAS genera su propia clave SSH y basta con autorizar la parte pública en el equipo de destino. Cada destino se prueba escribiendo de verdad en él antes de confiarle nada. El panel lista además S3 como no disponible, con el motivo: subir a S3 exige firmar cada petición desde el proceso privilegiado, y ese proceso solo ejecuta binarios de la allowlist. Está declarado en el contrato de la API para no romperlo el día que se implemente, pero hoy la API rechaza un destino S3 en lugar de fingir que funciona.
• Tareas: carpetas de origen, destino, horario y cuántas versiones (o cuántos días) se conservan. Cada copia es incremental: solo viaja lo que cambió, y las versiones anteriores se mantienen completas mediante enlaces duros (rsync --link-dest), así que ocupan poco. Corren con progreso como el resto de tareas largas y avisan por las alertas si fallan (configura Panel de control → Alertas: una copia que falla en silencio no es una copia). El cifrado del destino todavía no está disponible y la API lo rechaza explícitamente: si el destino es un disco que sale de casa, cífralo tú en el equipo de destino (LUKS) o guárdalo en un sitio de confianza.
• Restauración desde la propia app: eliges la versión y la carpeta de destino. El historial guarda cada ejecución con su tamaño y su error exacto.

Qué copiar, cada cuánto, cómo autorizar la clave paso a paso y —lo más importante— cómo comprobar que la copia sirve restaurándola de verdad: backups.md.

Compartición de archivos

Las carpetas se comparten desde Carpetas compartidas, y los distintivos SMB y NFS de cada una se pulsan para encender o apagar ese protocolo sin abrir el editor.

El NAS aparece solo en la red. Con SMB encendido no hay que saberse la IP ni configurar nada en los equipos: sale en «Red» de Windows, en la barra lateral del Finder de macOS y en el explorador de archivos de Linux. Compartir y anunciarse son cosas distintas, y por eso el cortafuegos abre cinco puertos, no dos:

Los tres últimos solo anuncian que este equipo existe; no dan acceso a nada. Se abren y se cierran con el interruptor de SMB, así que apagarlo los retira todos.

Sobre el protocolo: se negocia el más alto que admitan las dos partes, y con Windows 10/11, macOS y Linux modernos eso es SMB 3.1.1 con cifrado. El mínimo se deja en SMB2 a propósito, para no dejar fuera a un televisor o a un escáner que solo hablen esa versión.

Una persona, una cuenta

Todo se gestiona en Usuarios y grupos. Cada persona tiene una contraseña y cuatro capacidades que se marcan en su ficha:

Desmarcar una capacidad la retira de verdad (antes solo se daban permisos, y desmarcar no hacía nada). La pestaña Carpetas de su ficha reparte el acceso carpeta por carpeta: sin acceso, lectura y escritura, o solo lectura, y enseña además lo que hereda de sus grupos. Al guardar sin escribir contraseña se conserva la que ya tenía; solo hace falta una nueva para darle de alta en un servicio que todavía no tenía.

El panel no deja quedarse sin administrador: ni quitándose uno mismo el acceso, ni degradando o eliminando al último que queda.

Buscar archivos

• El buscador de Archivos se apoya en un índice de nombres que el NAS mantiene solo: una pasada cada dos minutos que solo mira las carpetas cuya fecha ha cambiado, así que no relee el disco entero ni se nota. Buscar pasa a ser instantáneo y, sobre todo, completo: el recorrido en vivo se rendía a las 60 000 entradas y devolvía «hay más de lo que se enseña».
• El índice vive en el estado del sistema (/var/nas/state/indice.db), no junto a tus datos, y solo guarda rutas: quién puede ver qué lo sigue decidiendo la carpeta compartida en cada búsqueda. Ocupa poco —unos 20 MB por cada 150 000 archivos— y si se borra, se vuelve a construir solo.
• La primera vez tarda lo que tarde en leer el árbol —de unos segundos a una noche, según cuántos archivos haya—, y mientras tanto la búsqueda funciona como antes, recorriendo.
• Lo que creas, subas, muevas o borres desde el panel se apunta al momento; lo que llegue por SMB o NFS aparece en la pasada siguiente.
• Afinar la búsqueda no pide volver a pulsar Intro: una vez dentro de los resultados, cambiar la palabra los rehace sola. Solo cuando el índice está listo; si no, se sigue buscando al pulsar Intro, para no mandar al NAS a recorrer el disco con cada tecla.
• Buscar dentro del contenido (la casilla del buscador) también se apoya en el índice —le pregunta qué documentos hay y en qué orden, del más reciente al más antiguo— pero los abre y los lee en ese momento, con sus topes: indexar el texto de todo sí costaría disco y CPU de verdad.

Las carpetas del sistema

En «Carpetas compartidas» aparecen también docker (los datos de las aplicaciones) y vm (los discos de las máquinas virtuales), como la carpeta «docker» de DSM: se pueden compartir por red, darles papelera y permisos, pero no se renombran, ni se mueven, ni se borran sus datos. Solo salen cuando el volumen está preparado —tiene sus carpetas docker, vm y appstore—, cosa que hasta ahora únicamente pasaba en los volúmenes creados desde el panel: uno adoptado o venido de una reinstalación se quedaba sin ellas. El NAS lo repasa ahora cada diez minutos y las crea si faltan.

Fotos y vídeos (Galería)

• El NAS crea una carpeta compartida «Galeria» la primera vez que hay un volumen: es el sitio evidente donde dejar las fotos (se ve en Archivos, se comparte por red y el móvil puede copiar ahí el carrete), y la Galería la indexa siempre. Se crea una sola vez: si la borras, no vuelve. Sin tilde porque el nombre de una carpeta compartida viaja a SMB, a NFS y a una ruta del disco.
• La Galería no copia ni mueve nada: lee las fotos y los vídeos que ya están en tus carpetas compartidas y los ordena en una línea de tiempo por meses.
• Se pone al día sola, cada media hora. Lo que llega por SMB —la copia del carrete del móvil, que es como llegan casi todas— aparece sin que nadie pulse nada; «Indexar ahora» sigue estando para cuando no quieres esperar. Si no eliges carpetas, indexa «Galeria» y las compartidas cuyo nombre suene a fotos o a vídeos (Fotos, Photos, Imágenes, DCIM, Vídeos); desde la propia app se pueden elegir a mano. No entran ni la carpeta de las cámaras de vigilancia ni una videoteca de películas: eso no son recuerdos.
• El índice es un SQLite aparte y se rellena en segundo plano: la primera pasada de una carpeta grande tarda, y la app dice que está escaneando mientras tanto. Dejar de compartir una carpeta la saca del índice en la pasada siguiente.
• Los álbumes son listas, no carpetas: una foto puede estar en varios y crear, renombrar o borrar un álbum no toca un solo archivo del disco. Descargar uno da un zip.
• Los vídeos se sirven por rangos, así que se puede saltar a un minuto concreto sin descargar el archivo entero, y su miniatura es un fotograma del segundo 1.
• Qué formatos entran: JPEG (incluido .jfif), PNG, WebP, AVIF, GIF, BMP, TIFF, HEIC/HEIF (iPhone) y RAW de cámara —.cr2, .cr3, .nef, .nrw, .arw, .sr2, .rw2, .orf, .raf, .pef, .srw, .rwl, .3fr, .erf— incluido el ProRAW del iPhone, que es un .dng. En vídeo: .mp4, .mov, .m4v, .mkv, .webm, .avi, .3gp, .mts y .m2ts.
• El RAW no se revela (eso pide un procesador de imagen entero y segundos por foto): se enseña la vista previa que la cámara dejó dentro del archivo, que es un JPEG casi a tamaño completo y es lo que hacen todas las galerías. Lo saca exiftool; los HEIC los abre heif-convert. Los instala LGM-OS; si faltan, esas fotos se indexan igual pero se quedan sin miniatura y el panel lo dice.
• Live Photos: el iPhone guarda cada una como dos archivos (IMG_0042.HEIC y IMG_0042.MOV). La Galería los reconoce por el nombre y enseña un solo elemento, con la etiqueta «Live» y un botón en el visor para ver el movimiento. Antes salían las dos cosas y bajar una carpeta del móvil duplicaba la cuadrícula.
• Borrar desde la Galería manda a la papelera del NAS: se recupera desde Archivos.
• El buscador de duplicados agrupa por tamaño y principio de archivo, y nunca deja borrar la última copia que queda de una foto.

Aplicaciones (Docker)

• Centro de Paquetes: instala recetas locales (/var/nas/appstore/templates/) o sincroniza fuentes de catálogo (botón «Fuentes del catálogo»). Además del índice propio https con checksums, se pueden añadir catálogos comunitarios que el NAS convierte a recetas al sincronizar: Community Applications de Unraid (unas 2000 aplicaciones con categorías e iconos) y tiendas CasaOS/ZimaOS. La sincronización corre como tarea con progreso; lo que trajo una fuente que luego quitas se retira solo, y las recetas locales hechas a mano nunca se tocan.
• Buscador, chips de categoría con contadores y filtro «Instaladas» para moverse por un catálogo de miles de aplicaciones.
• El botón «⟳» de una app instalada descarga la imagen nueva y recrea contenedores.
• La app Docker muestra logs en vivo, CPU/RAM y controla contenedores individuales. Un contenedor creado a mano (desde el terminal, por ejemplo) que publique un puerto TCP tiene su botón «Abrir» y aparece en el Launchpad como una aplicación más.

Actualizar LGM-OS sin reinstalar

Desde el panel: Panel de control → Actualizar LGM-OS → «Actualizar ahora». Nada más. No hace falta volver a pasar la ISO por cada versión, ni tener acceso al código, ni configurar un repositorio: el NAS pregunta al servidor del fabricante cuál es la última versión, se la descarga y la instala.

Lo que ocurre por dentro, por si alguna vez hay que mirarlo:

1. El NAS pide la última versión publicada y la compara con la suya. Compara números, no texto: la 1.10.0 es posterior a la 1.9.0.
2. Descarga el paquete y comprueba su SHA-256 contra el que anunció el servidor. Si no coincide, no instala nada y lo dice con esas palabras: lo que llegó no es lo que el servidor dijo que iba a llegar, que es muy distinto de «falló la descarga».
3. Aplica la actualización con el mismo procedimiento de siempre: compila, valida y solo entonces promueve. Si el panel no responde después, revierte solo a la versión anterior.

Desde la consola: sudo lgm update.

Opciones

• Automático: «Buscar actualizaciones automáticamente» avisa en Notificaciones cuando hay una versión nueva; «Instalarlas sin preguntar» las aplica solas cada 6/12/24 horas o cada 7 días.
• Desde tu propio código (solo si has clonado el repositorio): si el equipo tiene un checkout de git con remoto, el panel lo usa en vez del servidor de versiones. Es el camino de quien desarrolla; para un NAS instalado desde la ISO no hace falta nada de esto.

Mientras actualiza

Verás una barra con la fase y un porcentaje aproximado —copia de seguridad, paquetes del sistema, compilar la interfaz, backend, reiniciar servicios—. Los dos pasos largos son instalar los paquetes y compilar la interfaz: cada uno tarda varios minutos sin dar señales, y eso es normal. El panel se reinicia a mitad: la barra lo dice y sigue contando en cuanto vuelve.

Al terminar, el actualizador comprueba que todo lo que estaba encendido sigue encendido (Docker, Samba, libvirt, NFS…) y, si algo se quedó parado, lo arranca y lo dice por su nombre. También si falla la actualización: una versión que se rinde a mitad no puede dejarte sin contenedores ni sin carpetas compartidas.

Si falla

El aviso rojo trae las últimas líneas del registro —que es donde está el error— y un desplegable con el registro completo. Desde la consola:

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

Como la actualización revierte sola, el NAS se queda funcionando con la versión anterior: no hay prisa por arreglarlo. Las dos causas habituales son quedarse sin memoria al compilar la interfaz (añade 2 GiB de intercambio permanente) y quedarse sin espacio; el panel distingue las dos y lo dice con esas palabras.

Comprobación de los servicios

Panel de control → Comprobación del sistema revisa uno por uno el panel, el almacenamiento, SMB, NFS, WebDAV, SSH, Docker, las copias de seguridad y las cámaras. No mira lo que el panel tiene guardado que debería pasar: mira el sistema —si la unidad de systemd está viva, si hay algo escuchando en el puerto, si el cortafuegos lo deja pasar, si la configuración cuadra con lo que se pidió— y cada problema viene con qué hacer.

Es lo primero que hay que abrir cuando algo «no va» desde otro equipo: dice si el fallo está en el NAS o fuera de él, que es la mitad del trabajo.

Terminal web

Shell real en el navegador, solo para administradores. Arranca como el usuario del servicio (nas, sin privilegios). El botón «Sesión root» abre una shell de administrador tras re-pedir la contraseña —y el código TOTP si lo tienes activo—: el permiso es un token de un solo uso que caduca en 60 segundos, la elevación la crea el helper privilegiado (el servicio del panel corre con NoNewPrivileges=yes, donde sudo no puede funcionar) y cada apertura queda en la auditoría. Desde ahí puedes instalar lo que quieras (docker run …, apt install …); si lo que lances publica un puerto web, saldrá en Docker y en el Launchpad.

Sistema

• Red: IP estática/DHCP por interfaz vía systemd-networkd. ⚠️ Un error aquí puede dejar el NAS inaccesible; ten consola física a mano.
• Pantalla del servidor (modo quiosco): si el equipo tiene un monitor conectado (o la consola de su máquina virtual), arranca enseñando este mismo panel a pantalla completa, como cualquier otro sistema operativo, y se sigue administrando por la web desde el resto de la red igual que antes. Se instala solo cuando hay pantalla y se apaga con un interruptor en Panel de control → Información del equipo.

La consola nunca desaparece: el panel ocupa el terminal 7 y el inicio de sesión de siempre se queda en el 1. Si la pantalla se rompe —X no arranca, el navegador se cierra, el panel no responde— con Ctrl+Alt+F1 tienes una consola de verdad, y Ctrl+Alt+F7 vuelve al panel. Desde la consola, lgm kiosk off la apaga, lgm kiosk log dice por qué falla y lgm kiosk on la vuelve a encender.

• Actualizaciones del sistema operativo: no se hacen desde el panel. Un apt upgrade desatendido puede reiniciar servicios o dejarlos a medias sin nadie delante; quien quiera actualizar Debian tiene el terminal. Lo que sí se actualiza desde el panel es LGM-OS, que es código propio y sabe reiniciarse solo.
• Copia de la configuración: descarga puntual o tarea programada tipo «backup» hacia un pool. Lleva todo el estado del panel (usuarios, grupos, carpetas compartidas con sus permisos, servicios, firewall, red, tareas…) menos los secretos del equipo, que se regeneran. No incluye tus datos (para eso, la app Copias de seguridad); guárdala dentro de la copia externa, porque es lo primero que necesitarás al reconstruir el equipo. Detalle y restauración en disaster-recovery.md.
• Registros: journald por unidad; Auditoría: quién hizo qué y desde qué IP.

Seguridad

• Arquitectura de dos procesos: la API corre como usuario nas sin privilegios y delega en nas-helper (root) a través de un socket Unix; el helper solo acepta una lista cerrada de comandos y rutas (backend/app/core/allowlist.py).
• TLS: autofirmado generado en el primer arranque. Lo normal es sustituirlo por uno de Let's Encrypt al publicar el NAS (ver Acceso desde internet); para poner uno tuyo a mano: ```bash cp tucert.pem /etc/nas/tls/cert.pem && cp tuclave.pem /etc/nas/tls/key.pem chgrp nas /etc/nas/tls/key.pem && chmod 640 /etc/nas/tls/key.pem systemctl restart nas-backend ```
• Protección de login: 10 intentos/minuto por IP; 5 fallos seguidos bloquean la cuenta 5 minutos. Todo queda en la auditoría.
• Roles: admin (total) y viewer (solo lectura), gestionados en Seguridad.
• Nunca abras el puerto 5000 en el router: sirve el panel con certificado autofirmado y expone la API de administración sin nada delante. Ya no hace falta ese apaño, porque hay dos formas mejores de llegar desde fuera y el NAS trae las dos: la VPN WireGuard (no publica ningún servicio en internet) o el acceso externo con Apache en 80/443 y certificado válido de Let's Encrypt. Las dos secciones siguientes.

Acceso desde internet

Panel de Control → Acceso remoto → Acceso externo: dominio dinámico (DDNS), certificado de Let's Encrypt y proxy inverso para publicar el panel y las apps por subdominio. Apache queda como único servicio expuesto (80 y 443) y reenvía a 127.0.0.1; el puerto 5000 y los de las apps no salen del NAS. Con un certificado válido, además, la interfaz se puede instalar como aplicación (PWA).

El procedimiento completo —puertos del router, DuckDNS paso a paso, emisión y renovación del certificado, subdominios y la lista de seguridad previa (2FA, Asesor de seguridad, bloqueo de IPs)— está en external-access.md. Alternativa más conservadora si no necesitas compartir con terceros: la VPN del propio NAS (sección siguiente), sin exponer ningún servicio.

Servicios de red (VPN, DNS y DHCP)

Panel de Control → Servicios de red. Las tres piezas que convierten el NAS en el centro de la red de casa, ordenadas por riesgo:

• La VPN es la forma más segura de llegar al NAS desde fuera: no publica ningún servicio en internet y da acceso a toda la red local, no solo al panel.
• El DNS y el DHCP son el mismo servicio (dnsmasq), así que pararlo detiene los dos: es justo lo que se necesita en una emergencia (sudo systemctl stop dnsmasq).
• dnsmasq se instala desactivado y solo arranca cuando activas DNS o DHCP desde el panel.

Puertos del router, instalación del cliente de VPN paso a paso, cómo apuntar los equipos al DNS y —lo más importante— cómo recuperar la red si el DHCP te deja sin conexión: network-services.md. Léela antes de activar el DHCP, y guárdala en el móvil: si te quedas sin red, no podrás consultarla desde el NAS.

Publicar apps en el catálogo

Cada app es un directorio /var/nas/appstore/templates/<id>/ con:

• manifest.json — id, nombre, descripción, images (pre-descargadas con progreso), web_port y env (variables que el instalador pide al usuario; secret las oculta).
• docker-compose.yml — consume esas variables más NAS_APP_DATA (ruta de datos que inyecta el backend).

Instalar exige un pool: los datos de cada app viven en <pool>/docker/<id>/ (las instalaciones anteriores a esta política siguen en /var/nas/apps/ y no se mueven). Esa carpeta docker no es una carpeta compartida —el gestor de archivos y SMB/NFS no la enseñan— y su nombre está reservado al crear carpetas compartidas. Si el manifiesto trae web_port, al instalar se abre ese puerto en el cortafuegos gestionado (regla nas-app-<id>) y se retira al desinstalar.

Para un repositorio remoto sirve por https un index.json:

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