========================================= Manual de Operación para Nodos Guardianes ========================================= --------------------------------------------------------------------------- Despliegue, Enclavillado Granular y Mantenimiento de Nodos de la Red MxOS --------------------------------------------------------------------------- :Autores: - Rénich Bon Ćirić - Equipo de Infraestructura de Fundación MxOS :Organización: Fundación MxOS, A.C. :Fecha: Octubre 2026 :Estado: Estándar Activo Propósito y Filosofía Operativa =============================== La Red de Espejos Comunitarios de Fundación MxOS sustituye los modelos centralizados de distribución por una infraestructura entre pares (P2P) sobre el Sistema de Archivos Interplanetario (IPFS). En este paradigma, cada participante puede actuar como **nodo guardián**, custodiando y compartiendo localmente los paquetes que decida respaldar. El ecosistema opera mediante dos dominios públicos con funciones diferenciadas: * **ipfs.mx-os.mx ("Úsanos de gateway de IPFS"):** Pasarela pública y neutral en HOBOPS.IO para que cualquier usuario o desarrollador resuelva CIDs o registros IPNS sin necesidad de contar con un demonio local. * **mirrors.mx-os.mx ("El espejo de software libre de Fundación MxOS"):** Portal oficial y catálogo curado de distribución de paquetes, notas de liberación, guías de enclavillado y observatorio de red. El enclavillado (*pinning*) de datos garantiza que los bloques permanezcan residentes en el almacenamiento local del nodo guardián, disponibles para su entrega tanto en la red de área local como a través del enjambre global hacia cualquier cliente que los requiera. Requisitos del Sistema ====================== * Sistema operativo Linux: Fedora 43, 44, 45, Rawhide o CentOS Stream 10. * Privilegios administrativos locales vía ``sudo`` (o permisos de montaje Btrfs con ``user_subvol_rm_allowed``). * Conectividad a internet y puerto 4001 TCP/UDP accesible para tráfico entrante del enjambre libp2p. * Almacenamiento en disco acorde a los módulos seleccionados (desde 3.5 GB para medios de instalación hasta 450 GB para el catálogo completo). Paso 1: Instalación de Kubo =========================== Kubo se distribuye empaquetado para Fedora y CentOS Stream a través del repositorio Copr oficial: .. code-block:: bash # Habilitar repositorio Copr e instalar el demonio Kubo sudo dnf copr enable renich/kubo sudo dnf install kubo Paso 2: Inicialización del Almacén y Servicio de Usuario ======================================================== Por directriz de seguridad de Fundación MxOS, el demonio Kubo debe ejecutarse bajo el perfil de usuario sin privilegios elevados (rootless): .. code-block:: bash # Inicializar el almacén local en ~/.ipfs ipfs init # Habilitar e iniciar la unidad de servicio persistente de systemd systemctl --user enable --now ipfs.service # Comprobar el estado del demonio systemctl --user status ipfs.service Paso 3: Configuración del Cortafuegos ===================================== Para permitir la transferencia bidireccional de bloques en Bitswap, abre el puerto del enjambre en firewalld: .. code-block:: bash sudo firewall-cmd --permanent --add-port=4001/tcp sudo firewall-cmd --permanent --add-port=4001/udp sudo firewall-cmd --reload Paso 4: Configuración de Resolución DoH Directa para DNSLink ============================================================ Los enrutadores locales y corporativos suelen retener en caché los registros TXT de DNSLink de acuerdo a sus tiempos internos. Para asegurar que tu nodo resuelva los nuevos CIDs en el instante exacto en que se publican, configura el resolvedor interno de Kubo para consultar directamente Cloudflare DoH en la zona ``mx-os.mx``: .. code-block:: bash # Configurar resolvedor DoH directo para el dominio canónico ipfs config --json DNS.Resolvers '{"mx-os.mx.": "https://cloudflare-dns.com/dns-query", ".": "auto"}' # Reiniciar el demonio para aplicar el cambio systemctl --user restart ipfs.service Paso 5: Exploración Previa de Módulos con ipfs ls ================================================= Antes de enclavillar, cualquier usuario u operador puede listar en tiempo real la estructura y los módulos publicados en el catálogo maestro mediante la herramienta nativa ``ipfs ls``: .. code-block:: bash # Explorar la raíz del catálogo comunitario ipfs ls /ipns/mirrors.mx-os.mx # Listar versiones de Fedora disponibles (43, 44, 45) ipfs ls /ipns/mirrors.mx-os.mx/fedora/releases # Listar medios de instalación ISO ipfs ls /ipns/mirrors.mx-os.mx/fedora/iso # Listar CentOS Stream 10 ipfs ls /ipns/mirrors.mx-os.mx/centos-stream/10-stream Paso 6: Selección y Enclavillado Granular de Módulos ==================================================== El catálogo se organiza de forma modular para adaptarse a la cuota de disco disponible en cada instalación: .. list-table:: :header-rows: 1 :widths: 28 42 15 15 * - Módulo - Comando de Enclavillado - Tamaño en Red - Espacio Estimado * - **Imágenes ISO Fedora 43** - ``ipfs pin add /ipns/mirrors.mx-os.mx/fedora/iso/43`` - 1.2G - ~3.5 GB * - **Imágenes ISO Fedora 44** - ``ipfs pin add /ipns/mirrors.mx-os.mx/fedora/iso/44`` - 0B - ~3.5 GB * - **Imágenes ISO Fedora 45** - ``ipfs pin add /ipns/mirrors.mx-os.mx/fedora/iso/45`` - 0B - ~3.5 GB * - **Todas las Imágenes ISO (43, 44, 45)** - ``ipfs pin add /ipns/mirrors.mx-os.mx/fedora/iso`` - 1.2G - ~10 GB * - **CentOS 10 BaseOS** - ``ipfs pin add /ipns/mirrors.mx-os.mx/centos-stream/10-stream/BaseOS`` - 7.0G - ~15 GB * - **CentOS 10 AppStream** - ``ipfs pin add /ipns/mirrors.mx-os.mx/centos-stream/10-stream/AppStream`` - 29G - ~45 GB * - **CentOS 10 CRB (CodeReady Linux Builder)** - ``ipfs pin add /ipns/mirrors.mx-os.mx/centos-stream/10-stream/CRB`` - 26G - ~30 GB * - **CentOS 10 HighAvailability** - ``ipfs pin add /ipns/mirrors.mx-os.mx/centos-stream/10-stream/HighAvailability`` - 166M - ~500 MB * - **CentOS 10 NFV y RT (Redes y Tiempo Real)** - ``ipfs pin add /ipns/mirrors.mx-os.mx/centos-stream/10-stream/RT`` - 4.2G - ~5.0 GB * - **CentOS 10 SIG Extras (extras-common)** - ``ipfs pin add /ipns/mirrors.mx-os.mx/centos-stream/SIGs/10-stream/extras`` - 948K - ~50 MB * - **CentOS 10 Stream Completo** - ``ipfs pin add /ipns/mirrors.mx-os.mx/centos-stream`` - 67G - ~95 GB * - **Paquetería Fedora 43 Everything** - ``ipfs pin add /ipns/mirrors.mx-os.mx/fedora/releases/43/Everything`` - 118G - ~125 GB * - **Paquetería Fedora 44 Everything** - ``ipfs pin add /ipns/mirrors.mx-os.mx/fedora/releases/44/Everything`` - 0B - ~125 GB * - **Paquetería Fedora 45 Everything (Desarrollo)** - ``ipfs pin add /ipns/mirrors.mx-os.mx/fedora/releases/45/Everything`` - 0B - ~125 GB * - **Catálogo Canónico Completo** - ``ipfs pin add /ipns/mirrors.mx-os.mx`` - 186G - ~450 GB Paso 7: Automatización, Btrfs y Mantenimiento de Almacenamiento =============================================================== Los repositorios de upstream se actualizan continuamente. Para gestionar el ciclo de vida y optimizar el almacenamiento: 1. **Actualización de pines:** Vuelve a ejecutar periódicamente el comando ``ipfs pin add`` sobre la ruta canónica en IPNS. Kubo descargará únicamente los bloques modificados o agregados. 2. **Gestión de módulos con Btrfs y subvolúmenes:** En nodos con almacenamiento formateado en Btrfs, se recomienda estructurar cada módulo como un subvolumen independiente: * **Eliminación atómica e instantánea:** Para borrar un módulo completo (por ejemplo, al liberar espacio), ejecuta ``btrfs subvolume delete `` (o ``./bin/mxos-btrfs.bash delete ``). La operación es instantánea y evita sobrecargar el disco desvinculando decenas de miles de archivos. * **Instantáneas con costo cero (CoW):** Genera instantáneas de respaldo previas a una sincronización con ``btrfs subvolume snapshot -r``. * **Operación sin privilegios de superusuario:** Añade la opción ``user_subvol_rm_allowed`` en ``/etc/fstab`` para el punto de montaje de IPFS, permitiendo administrar subvolúmenes sin requerir ``sudo``. 3. **Recolección de basura (GC):** Para purgar bloques desvinculados que hayan quedado huérfanos tras una actualización: .. code-block:: bash ipfs repo gc Los bloques enclavillados explícitamente se encuentran totalmente protegidos contra eliminación. 3. **Temporizador de sincronización de cuatro ciclos diarios:** En los nodos maestros de sincronización, la actualización se encuentra programada cuatro veces al día mediante temporizadores de systemd: .. code-block:: ini # ~/.config/systemd/user/mxos-mirror.timer [Unit] Description=Temporizador de sincronización periódica de espejos MxOS (4 veces al día) [Timer] OnCalendar=*-*-* 00,06,12,18:00:00 RandomizedDelaySec=900 Persistent=true [Install] WantedBy=timers.target Custodia Anónima: Participación Plena sin Registro ================================================== En la Red de Espejos Comunitarios de Fundación MxOS, **la custodia anónima es totalmente válida, bienvenida y considerada de primera clase**. No se requiere ningún tipo de registro para participar como nodo guardián. Al iniciar tu demonio Kubo y enclavillar uno o más módulos, tu nodo comparte bloques directamente en el enjambre de Bitswap y la DHT de libp2p, identificado únicamente por su hash criptográfico infalsificable (``PeerID``). Los bloques servidos por custodios anónimos fortalecen la infraestructura comunitaria con exactamente la misma soberanía, prioridad y velocidad que los de cualquier nodo registrado. Paso 8: Registro Voluntario en el Tablero Vigía =============================================== Para aquellos operadores, colectivos o instituciones que deseen visibilizar formalmente su nodo en el observatorio público `https://mirrors.mx-os.mx/vigia/ `_, pueden solicitar su inclusión en ``guardianes.json``: 1. **Obtén tu identificador de par (PeerID):** .. code-block:: bash ipfs id -f="\n" 2. **Prepara tu entrada en guardianes.json:** .. code-block:: json "12D3KooWBVZfAQyPExhScDpiG4Hahh3e6QmwRZRVopib1ThgUo2g": { "alias": "renich", "nombre": "Rénich Bon Ćirić", "organizacion": "EVALinux", "ubicacion": "Ixtlahuacán de los Membrillos, Jalisco, México", "sitio": "https://evalinux.com", "contacto": "renich@evalinux.com", "rol": "guardian", "insignia": "🛡️ Guardián Pionero", "verificacion": "gitlab" } 3. **Criterios de formato:** * Nombre de estado federativo completo sin abreviaturas (por ejemplo, ``Jalisco`` o ``Querétaro``). * Redacción directa sin espacios alrededor de barras diagonales. * Dirección HTTPS válida y comprobable en el campo ``sitio``. * El campo ``organizacion`` se refleja bajo la columna ``Afiliación`` en el tablero. 4. **Publicación:** Abre una solicitud de incorporación (Merge Request) en el repositorio canónico `https://git.mx-os.mx/MxOS/mirrors `_. Una vez revisada y aprobada, tu nodo lucirá sus distintivos en la cartografía de la red.