==================================
Guía del Operador de Nodo Guardián
==================================

Propósito
=========
Este manual explica cómo configurar un nodo local de IPFS en Fedora o CentOS Stream para unirse al enjambre de MxOS, enlazarse directamente con el nodo semilla institucional (``web0.mx-os.mx``) y enclavillar selectivamente los módulos del catálogo según la cuota de disco que desees donar.

Requisitos Previos
==================

* Fedora 43, 44, 45, Rawhide o CentOS Stream 10.
* Acceso a privilegios administrativos mediante ``sudo``.
* Espacio en disco libre según el nivel de almacenamiento elegido (desde 10 GB en adelante).
* Conexión a internet permanente o semipermanente con puertos abiertos hacia el enjambre.

Paso 1: Instalación de Kubo desde Copr
======================================
Kubo se encuentra empaquetado para la familia de distribuciones Fedora y CentOS Stream en el repositorio Copr de MxOS:

.. code-block:: bash

   sudo dnf copr enable renich/kubo
   sudo dnf install kubo

Paso 2: Inicialización e Inicio del Servicio
============================================
Se recomienda operar el demonio en modo de usuario no privilegiado (rootless) gestionado por systemd:

.. code-block:: bash

   # Inicializar el almacén local de IPFS en el directorio de usuario (~/.ipfs)
   ipfs init

   # Habilitar e iniciar el servicio persistente de usuario
   systemctl --user enable --now ipfs.service

   # Verificar que el servicio esté activo y funcionando
   systemctl --user status ipfs.service

Paso 3: Apertura de Puertos en el Cortafuegos
=============================================
Para que otros pares en internet y en tu red local puedan descargar bloques desde tu nodo, abre el puerto de escucha del enjambre (4001 TCP y UDP):

.. 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: Enlace Directo con el Nodo Semilla: Bootstrap y Peering
===============================================================
Para que tu nodo descubra y transfiera paquetes de inmediato desde el nodo maestro de la Fundación MxOS (``web0.mx-os.mx``) sin depender de demoras en la DHT global, agrégalo a tu lista de arranque (*bootstrap*) y configúralo como par permanente (*peering*):

.. code-block:: bash

   # 1. Agregar web0 a la lista de bootstrap inicial (TCP y QUIC)
   ipfs bootstrap add /ip4/38.58.139.30/tcp/4001/p2p/12D3KooWHJxzs8eArvUWLZGJJEowxXVVjbCK5MwZtDqECsGhjFjD
   ipfs bootstrap add /ip4/38.58.139.30/udp/4001/quic-v1/p2p/12D3KooWHJxzs8eArvUWLZGJJEowxXVVjbCK5MwZtDqECsGhjFjD

   # 2. Conectar de inmediato en vivo
   ipfs swarm connect /ip4/38.58.139.30/tcp/4001/p2p/12D3KooWHJxzs8eArvUWLZGJJEowxXVVjbCK5MwZtDqECsGhjFjD

   # 3. Configurar enlace permanente (Peering) para reconexión automática continua
   ipfs config --json Peering.Peers '[{
     "ID": "12D3KooWHJxzs8eArvUWLZGJJEowxXVVjbCK5MwZtDqECsGhjFjD",
     "Addrs": [
       "/ip4/38.58.139.30/tcp/4001",
       "/ip4/38.58.139.30/udp/4001/quic-v1"
     ]
   }]'

   # Reiniciar servicio para aplicar los cambios
   systemctl --user restart ipfs.service

Paso 5: Configuración de Resolución DNSLink sin Desfase de Caché
================================================================
Los enrutadores domésticos, universitarios o empresariales suelen retener en caché los registros TXT de DNSLink según sus políticas internas de resolución. Para evitar que tu nodo espere el vencimiento de estas cachés locales al publicarse nuevos paquetes, instruye a Kubo a consultar directamente el punto de resolución DoH de Cloudflare para la zona ``mx-os.mx``:

.. code-block:: bash

   # Configurar resolvedor DoH directo para mx-os.mx (FQDN estricto)
   ipfs config --json DNS.Resolvers '{"mx-os.mx.": "https://cloudflare-dns.com/dns-query", ".": "auto"}'

   # Reiniciar el servicio para aplicar los cambios
   systemctl --user restart ipfs.service

Paso 6: Exploración Previa de Módulos con ipfs ls
=================================================
Antes de comprometer almacenamiento local, puedes inspeccionar de forma remota la estructura del catálogo utilizando ``ipfs ls``:

.. code-block:: bash

   # Explorar la raíz del catálogo canónico
   ipfs ls /ipns/mirrors.mx-os.mx

   # Listar las ramas de Fedora disponibles (Everything e ISOs)
   ipfs ls /ipns/mirrors.mx-os.mx/fedora/releases
   ipfs ls /ipns/mirrors.mx-os.mx/fedora/updates
   ipfs ls /ipns/mirrors.mx-os.mx/fedora/iso

   # Listar CentOS Stream 10
   ipfs ls /ipns/mirrors.mx-os.mx/centos-stream/10-stream
   ipfs ls /ipns/mirrors.mx-os.mx/centos-stream/SIGs/10-stream

Paso 7: Enclavillado Granular por Módulo
========================================
No es necesario donar almacenamiento para la totalidad de los repositorios. Puedes seleccionar con precisión quirúrgica el componente que mejor se ajuste a tu capacidad de almacenamiento:

.. list-table::
   :header-rows: 1
   :widths: 28 42 15 15

   * - Módulo
     - Comando de Enclavillado
     - Tamaño en Red
     - Espacio Estimado
   * - **Fedora 43 Everything**
     - ``ipfs pin add /ipns/mirrors.mx-os.mx/fedora/releases/43/Everything``
     - 118G
     - ~125 GB
   * - **Fedora 43 Updates**
     - ``ipfs pin add /ipns/mirrors.mx-os.mx/fedora/updates/43``
     - 61G
     - ~65 GB
   * - **Fedora 44 Everything**
     - ``ipfs pin add /ipns/mirrors.mx-os.mx/fedora/releases/44/Everything``
     - 114G
     - ~125 GB
   * - **Fedora 44 Updates**
     - ``ipfs pin add /ipns/mirrors.mx-os.mx/fedora/updates/44``
     - 53G
     - ~60 GB
   * - **Fedora 45 Everything**
     - ``ipfs pin add /ipns/mirrors.mx-os.mx/fedora/releases/45/Everything``
     - 116G
     - ~125 GB
   * - **Fedora ISOs (43, 44, 45)**
     - ``ipfs pin add /ipns/mirrors.mx-os.mx/fedora/iso``
     - 1.2G
     - ~10 GB
   * - **CentOS Stream 10 BaseOS**
     - ``ipfs pin add /ipns/mirrors.mx-os.mx/centos-stream/10-stream/BaseOS``
     - 7.0G
     - ~15 GB
   * - **CentOS Stream 10 AppStream**
     - ``ipfs pin add /ipns/mirrors.mx-os.mx/centos-stream/10-stream/AppStream``
     - 29G
     - ~45 GB
   * - **CentOS Stream 10 Completo**
     - ``ipfs pin add /ipns/mirrors.mx-os.mx/centos-stream/10-stream``
     - 82G
     - ~80 GB
   * - **CentOS Stream 10 SIGs**
     - ``ipfs pin add /ipns/mirrors.mx-os.mx/centos-stream/SIGs/10-stream``
     - 19G
     - ~25 GB
   * - **Catálogo Canónico Completo**
     - ``ipfs pin add /ipns/mirrors.mx-os.mx``
     - 563G
     - ~600 GB

Paso 8: Gestión Eficiente con Btrfs y Subvolúmenes CoW
======================================================
Para los operadores que sincronizan o almacenan paquetes localmente, la infraestructura aprovecha las capacidades nativas de **Btrfs** y la copia en escritura (**CoW**; *Copy-on-Write*):

* **Eliminación atómica e instantánea:** Cada módulo puede residir en un subvolumen Btrfs independiente. Borrar un repositorio de más de 100 GB se efectúa instantáneamente a nivel de metadatos mediante ``btrfs subvolume delete``.
* **Instantáneas de respaldo con costo cero:** Antes de actualizar o depurar, puedes generar una instantánea de solo lectura en milisegundos (``btrfs subvolume snapshot -r``) sin consumir espacio adicional.
* **Permisos rootless:** Al habilitar la opción de montaje ``user_subvol_rm_allowed`` en ``/etc/fstab`` para el punto de montaje de IPFS, los operadores pueden gestionar subvolúmenes sin requerir privilegios de superusuario.

El repositorio provee el script de automatización ``nodo/bin/mxos-btrfs.bash``:

.. code-block:: bash

   # 1. Listar subvolúmenes e instantáneas por módulo
   ./nodo/bin/mxos-btrfs.bash list

   # 2. Inicializar o migrar módulos a subvolúmenes Btrfs
   ./nodo/bin/mxos-btrfs.bash init all

   # 3. Crear una instantánea de respaldo previa a sincronización
   ./nodo/bin/mxos-btrfs.bash snapshot centos-baseos pre-sync

   # 4. Eliminar un módulo entero de forma instantánea
   ./nodo/bin/mxos-btrfs.bash delete fedora-everything-43

Paso 9: Mantenimiento del Almacén y Recolección de Basura
=========================================================
Cuando se publican nuevas versiones o actualizaciones de seguridad, el CID de los directorios raíz cambia. Para mantener la higiene de tu almacenamiento local:

1. **Actualización periódica del módulo:**
   Ejecuta periódicamente el comando ``ipfs pin add`` sobre la ruta canónica en IPNS. Kubo descargará únicamente los bloques nuevos o modificados, reutilizando todos los bloques existentes.

2. **Ejecución de recolección de basura (GC):**
   Para purgar bloques antiguos que ya no estén vinculados a tus pines activos:

   .. code-block:: bash

      ipfs repo gc

   Los bloques enclavillados explícitamente jamás serán eliminados durante el proceso de recolección de basura.

3. **Límites de almacenamiento:**
   Puedes definir una cuota máxima en ``~/.ipfs/config`` bajo la sección ``Datastore.StorageMax`` (por ejemplo, ``150GB``) y programar tareas automáticas de mantenimiento mediante systemd.

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

El registro es estrictamente voluntario. Si prefieres no registrar tu nodo en ``guardianes.json``, tu equipo opera con total normalidad intercambiando paquetes a través de la DHT de libp2p y el protocolo Bitswap identificado únicamente por su hash criptográfico (``PeerID``). Los bloques servidos por custodios anónimos fortalecen la red exactamente con la misma soberanía y velocidad que los de cualquier nodo registrado.

Paso 10: Registro Voluntario en el Directorio Comunitario de Guardianes
=======================================================================
Si deseas vincular formalmente tu nodo a tu nombre, organización o institución educativa, puedes solicitar tu inclusión en el directorio público ``vigia/guardianes.json`` para recibir reconocimiento en el tablero de observabilidad **Vigía** (`mirrors.mx-os.mx/vigia/ <https://mirrors.mx-os.mx/vigia/>`_).

El tablero de Vigía presenta a la comunidad:

* **Estructura tabular estandarizada:** Columnas organizadas por rol, custodio, módulos custodiados, ubicación territorial y afiliación.
* **Copiado de identidad criptográfica con un clic:** Cualquier integrante puede copiar tu PeerID completo con confirmación visual instantánea.
* **Filtrado reactivo por módulos:** Al hacer clic en las etiquetas de los módulos custodiados, los visitantes aíslan en tiempo real a los nodos que custodian cada distribución.

Para formalizar tu registro:

1. **Consulta tu identificador PeerID:**

   .. code-block:: bash

      ipfs id -f="<id>\n"

2. **Agrega tu entrada en el archivo ``vigia/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. **Reglas de formato obligatorias:**
   * Escribe el nombre completo de los estados sin abreviaturas; por ejemplo, ``Jalisco`` o ``Querétaro``; nunca abreviado.
   * No utilices espacios alrededor de diagonales; utiliza redacción directa con comas o conjunciones.
   * Proporciona un enlace HTTPS funcional en el campo ``sitio``.
   * El campo ``organizacion`` se proyectará bajo la columna ``Afiliación`` en el tablero de Vigía.

4. **Envío de solicitud:**
   Crea una rama en tu copia local y abre un Merge Request en nuestro repositorio de Git (`git.mx-os.mx/MxOS/mirrors <https://git.mx-os.mx/MxOS/mirrors>`_ o `gitlab.com/mxos/mirrors <https://gitlab.com/mxos/mirrors>`_). Una vez verificado, tu nodo quedará acreditado públicamente en el enjambre.