Manual de Operación para Nodos Guardianes¶

Despliegue, Enclavillado Granular y Mantenimiento de Nodos de la Red MxOS¶

Autores:

Rénich Bon Ćirić <renich@mx-os.mx>
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:

# 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):

# 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:

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:

# 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:

# 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:

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:

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.
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 <ruta-modulo> (o ./bin/mxos-btrfs.bash delete <modulo>). 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.
Recolección de basura (GC): Para purgar bloques desvinculados que hayan quedado huérfanos tras una actualización:
```
ipfs repo gc
```
Los bloques enclavillados explícitamente se encuentran totalmente protegidos contra eliminación.

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:

# ~/.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:

Obtén tu identificador de par (PeerID):
```
ipfs id -f="<id>\n"
```

Prepara tu entrada en guardianes.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"
}

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.
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.