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.

Primer arranque

1. Accede a https://<ip-del-nas>:5000 (el certificado es autofirmado: acéptalo o sustitúyelo — ver Seguridad).
2. El asistente de primer acceso te pide crear el usuario administrador (nombre en minúsculas y contraseña de al menos 8 caracteres). No existen credenciales por defecto.
3. Recomendado inmediatamente después:
• Panel de Control → Seguridad → Activar 2FA.
• Panel de control → Alertas → configura SMTP o webhook y pulsa «Enviar prueba».
• Panel de Control → Firewall → actívalo (la web UI y SSH quedan siempre permitidos).

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.

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 la consola basta con `sudo lgm update`: descarga los cambios y lanza el actualizador. Con un repositorio privado usa el token guardado en el panel, sin escribirlo en ningún archivo.

Panel de control → Actualizar LGM-OS actualiza desde el propio checkout de git, así que no hay que volver a pasar la ISO por cada versión. Requisitos y opciones:

• Repositorio de origen: si la instalación vino de la ISO, el checkout puede no tener remoto configurado; en ese caso el panel lo dice claramente y ofrece el campo para ponerlo (https:// o SSH). Sin remoto no se puede comprobar nada — antes esto se veía, engañosamente, como «LGM-OS está al día».
• Repositorio privado: añade un token de solo lectura, o usa una clave SSH de despliegue.
• Automático: activa «Buscar actualizaciones automáticamente» para que el NAS avise en Notificaciones, y «Instalarlas sin preguntar» para que se apliquen solas cada 6/12/24 h o cada 7 días. La actualización es atómica: compila y valida antes de promover, y si el panel no responde después, revierte sola a la versión anterior.

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—, que se calcula leyendo el registro del actualizador. 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.

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