mirror of
https://github.com/MacRimi/ProxMenux.git
synced 2026-08-02 05:46:21 +00:00
update documentation
This commit is contained in:
MacRimi
@@ -163,7 +163,7 @@
|
||||
"customPathsBody": "Una ruta custom añadida en línea en modo Custom o persistida en <code>backup-extra-paths.txt</code> pasa por el mismo pipeline de <code>rsync</code> que las rutas del perfil por defecto. Se aplican las exclusiones globales. Si la ruta custom está bajo <code>/root/</code> o <code>/usr/local/share/proxmenux/</code>, siguen aplicando las exclusiones específicas de arriba. Cada ruta archivada — default o custom — queda registrada en <code>metadata/paths_archived.txt</code>. Las rutas que no existen en el origen se registran en <code>metadata/missing_paths.txt</code> sin detener la copia."
|
||||
},
|
||||
"archiveStructure": {
|
||||
"heading": "Estructura del archive",
|
||||
"heading": "Estructura del archivo",
|
||||
"intro": "El directorio de staging que produce cada backend sigue el mismo layout con independencia del destino. El tarball, el <code>.pxar</code> de PBS o el archivo Borg almacenan este árbol verbatim.",
|
||||
"tree": "backup-[timestamp]/\n├── manifest.json # estado estructurado del host (kernel_params, hardware, storage, guests, components, source_host)\n├── metadata/\n│ ├── packages.manual.list # salida de apt-mark showmanual\n│ ├── run_info.env # hostname, timestamp, versión del kernel\n│ ├── paths_archived.txt # lista exacta de rutas que llegaron a rootfs/\n│ └── missing_paths.txt # rutas del perfil ausentes en el origen\n└── rootfs/\n ├── etc/ # /etc/pve, /etc/network, /etc/ssh, /etc/apt, ...\n ├── root/ # /root sin subpaths volátiles\n ├── usr/local/ # /usr/local/bin, /usr/local/sbin, /usr/local/share/proxmenux (sólo estado)\n └── var/ # /var/lib/pve-cluster, /var/spool/cron/crontabs"
|
||||
},
|
||||
|
||||
@@ -75,8 +75,8 @@
|
||||
"captionBorg": "Borg"
|
||||
},
|
||||
"sameArchive": {
|
||||
"heading": "El layout del archivo no cambia con el destino",
|
||||
"body": "Dentro de cualquiera de los tres destinos está presente el mismo layout <code>rootfs/</code> + <code>metadata/</code> + <code>manifest.json</code> descrito en <em>Cómo funciona</em>. Un <code>.tar.zst</code> extraído de un archivo local, un <code>.pxar</code> restaurado desde PBS y un archivo Borg extraído con <code>borg extract</code> producen todos un árbol de directorios idéntico. El camino de código de la restauración (<code>_rs_check_layout</code>, <code>_rs_apply</code>, <code>_rs_prepare_pending_restore</code>) lee los mismos tres bloques sin saber de qué destino vienen."
|
||||
"heading": "El contenido interno de la copia es el mismo en cualquier destino",
|
||||
"body": "Con independencia de dónde se guarde la copia, dentro siempre están los mismos tres bloques descritos en <em>Cómo funciona</em>: el sistema de ficheros (<code>rootfs/</code>), los metadatos (<code>metadata/</code>) y el manifiesto (<code>manifest.json</code>). Al extraer una copia local <code>.tar.zst</code>, restaurar un archivo <code>.pxar</code> desde PBS o descomprimir un archivo Borg, el árbol de directorios resultante es idéntico en los tres casos. Esto significa que el proceso de restauración lee siempre los mismos ficheros y no le importa desde qué destino provenga la copia."
|
||||
},
|
||||
"extractStandalone": {
|
||||
"heading": "Extraer una copia fuera de ProxMenux",
|
||||
|
||||
@@ -23,7 +23,7 @@
|
||||
},
|
||||
"repoSelection": {
|
||||
"heading": "Selección del repositorio",
|
||||
"intro": "ProxMenux descubre repositorios PBS desde dos fuentes en cada copia. El usuario elige uno desde un menú unificado; la elección determina <code>HB_PBS_REPOSITORY</code>, <code>HB_PBS_SECRET</code> y <code>HB_PBS_FINGERPRINT</code> para esa ejecución.",
|
||||
"intro": "ProxMenux descubre repositorios PBS desde dos fuentes en cada copia. El usuario elige uno desde un menú unificado; esa elección determina, para esa ejecución concreta, contra qué servidor y datastore se envía la copia, con qué contraseña se autentica y con qué huella (<em>fingerprint</em>) valida el certificado.",
|
||||
"sourceRows": [
|
||||
{
|
||||
"source": "storage.cfg de Proxmox (auto-descubierto)",
|
||||
@@ -45,30 +45,33 @@
|
||||
"cmd": "env \\\n PBS_PASSWORD=\"$HB_PBS_SECRET\" \\\n PBS_ENCRYPTION_PASSWORD=\"$HB_PBS_ENC_PASS\" \\\n PBS_FINGERPRINT=\"$HB_PBS_FINGERPRINT\" \\\n proxmox-backup-client backup \\\n hostcfg.pxar:$staging_root \\\n --repository USER@REALM@HOST:DATASTORE \\\n --backup-type host \\\n --backup-id hostcfg-HOSTNAME \\\n --backup-time BACKUP-EPOCH \\\n [--keyfile /usr/local/share/proxmenux/pbs-key.conf]",
|
||||
"backupIdTitle": "Nombrado del backup ID",
|
||||
"backupIdBody": "El backup ID por defecto es <code>hostcfg-HOSTNAME</code>. Se pide al usuario que lo confirme o edite antes de la subida; cualquier carácter fuera de <code>[A-Za-z0-9_-]</code> se elimina y los guiones finales se recortan. Reutilizar el mismo ID entre ejecuciones es intencional — PBS trata el ID como un <em>grupo</em>, y cada copia posterior aparece como un nuevo backup dentro de ese grupo, compartiendo dedup con las ejecuciones previas.",
|
||||
"pxarTitle": "Por qué el origen es la raíz de staging completa",
|
||||
"pxarBody": "El origen del <code>.pxar</code> es la <code>staging_root</code> entera — <code>rootfs/</code>, <code>metadata/</code> y <code>manifest.json</code> juntos. Versiones anteriores pasaban <code>$staging_root/rootfs</code> como origen; eso dejaba <code>metadata/</code> fuera del archivo y el chequeo de compatibilidad de la restauración no tenía nada que leer, degradándose a avisos cross-host incluso en restauraciones al mismo host. Los backups antiguos creados con el origen rootfs-only siguen restaurándose correctamente gracias a la rama caso-3 de <code>_rs_check_layout</code>, que envuelve un árbol plano <code>etc/var/root/usr</code> de vuelta en una jerarquía <code>rootfs/</code>."
|
||||
"pxarTitle": "Qué se incluye dentro del archivo .pxar",
|
||||
"pxarBody": "Al construir el archivo <code>.pxar</code> se empaqueta el directorio de trabajo completo: el sistema de ficheros del host (<code>rootfs/</code>), los metadatos (<code>metadata/</code>) y el manifiesto (<code>manifest.json</code>). Al restaurar, ProxMenux compara la información del manifiesto con la del host destino para detectar si son equivalentes, si cambia el hardware o si se trata de un equipo distinto, y ajustar el proceso en consecuencia. Las copias antiguas —hechas con versiones anteriores de ProxMenux que empaquetaban solo el sistema de ficheros— siguen restaurándose sin problema: el flujo de restauración detecta ese formato heredado y lo reorganiza automáticamente."
|
||||
},
|
||||
"encryption": {
|
||||
"heading": "Cifrado del lado del cliente",
|
||||
"intro": "El cifrado por keyfile del lado del cliente de PBS cifra los chunks en el host de origen antes de la subida. ProxMenux habilita esta funcionalidad con una restricción añadida: la passphrase de recuperación es obligatoria cuando se activa el cifrado. La passphrase no protege el keyfile local; protege la copia de escrow del keyfile que ProxMenux sube a PBS para recuperación ante desastre.",
|
||||
"keyfileTitle": "Keyfile",
|
||||
"keyfileBody": "El diálogo de cifrado sigue un flujo yes/no en dos pasos. El primer paso pregunta si se desea cifrar el backup: <em>No</em> continúa sin cifrado; <em>Yes</em> pasa al segundo paso. El segundo paso depende de si ya hay un keyfile instalado en <code>/usr/local/share/proxmenux/pbs-key.conf</code>. Si lo hay, se reutiliza silenciosamente y el backup continúa. Si no lo hay, aparece un menú de dos opciones. <em>Generate a new keyfile</em> ejecuta <code>proxmox-backup-client key create --kdf none</code> — el keyfile resultante no lleva passphrase, así que el runner programado bajo systemd puede usarlo sin prompt interactivo. <em>Import an existing keyfile</em> toma una ruta indicada por el operador y la copia en la ubicación canónica con <code>chmod 600</code>; ProxMenux no inspecciona el contenido (cualquier keyfile que el operador acepte como válido en su PBS se acepta aquí, incluyendo keyfiles cifrados con scrypt que no podrían validarse de forma no interactiva). Al importar, el flujo pide también la passphrase del propio keyfile — la que <code>proxmox-backup-client key create --kdf scrypt</code> pidió al crearlo. Esa passphrase se persiste en <code>/usr/local/share/proxmenux/pbs-key.pass</code> (chmod 600) y se reutiliza en cada job cifrado del host como <code>PBS_ENCRYPTION_PASSWORD</code>. Dejarla en blanco equivale a un keyfile <code>--kdf none</code> (sin passphrase). Ambas ramas se ejecutan solo tras confirmar la passphrase de recuperación — cancelar cualquier diálogo antes de ese punto deja el disco intacto.",
|
||||
"glossaryHint": "En esta sección aparecen los términos <em>clave</em>, <em>passphrase</em> y <em>sobre de recuperación</em>. Si en algún momento cuesta seguir cuál es cuál, el <glosarioLink>glosario</glosarioLink> resume las diferencias en una frase por término.",
|
||||
"intro": "PBS puede cifrar las copias con una clave que reside únicamente en el host de origen: los datos se cifran en el propio host antes de subirse, y en PBS solo se guardan cifrados. Sin esa clave, las copias no pueden descifrarse. ProxMenux añade una salvaguarda: cuando se activa el cifrado obliga a definir una <strong>passphrase de recuperación</strong>. Esa passphrase no protege la clave local (que ya vive en el host), sino una copia cifrada de la clave que ProxMenux sube al propio PBS, para poder recuperarla si el host se pierde o se reinstala.",
|
||||
"keyfileTitle": "La clave de cifrado (keyfile)",
|
||||
"keyfileBody": "El diálogo pregunta primero si se quiere cifrar la copia. Si se responde <em>No</em>, la copia continúa sin cifrado. Si se responde <em>Sí</em>, ProxMenux comprueba si el host ya tiene una clave instalada: en ese caso la reutiliza sin más preguntas; si no la tiene, ofrece dos opciones. <em>Generar una clave nueva</em> crea una clave sin contraseña, para que las copias programadas puedan ejecutarse automáticamente sin diálogos. <em>Importar una clave existente</em> permite indicar la ruta de una clave ya generada —por ejemplo la clave común de una flota de hosts—; en ese caso el diálogo pide también la contraseña de esa clave y la guarda cifrada en el host para reutilizarla en cada copia. Cualquiera de las dos opciones se ejecuta solo después de confirmar la passphrase de recuperación; cancelar el diálogo antes de ese punto no deja nada en disco.",
|
||||
"modesTitle": "Keyfile por host o compartido",
|
||||
"modesIntro": "Ambos modelos operativos están soportados y ninguno se impone — la decisión pertenece al usuario según cómo esté organizada su flota.",
|
||||
"modesPerHostTitle": "Keyfile por host (por defecto)",
|
||||
"modesPerHostBody": "Cada host genera su propio keyfile la primera vez que activa el cifrado PBS. El aislamiento es máximo: comprometer el keyfile de un host no expone las copias de ningún otro. Cada host tiene su propio blob de recuperación emparejado en PBS, restaurable con la passphrase de recuperación de ese host. Recomendado para flotas de producción y para entornos donde los hosts tienen propietarios o límites de compliance distintos.",
|
||||
"modesSharedTitle": "Keyfile compartido (importar en cada host)",
|
||||
"modesSharedBody": "Un keyfile maestro generado una vez e instalado en cada host mediante la opción <em>Importar</em>. La gestión es más simple: un único secreto que proteger, un único blob de recuperación sirve para todos los hosts, y cualquier host puede desencriptar los archives de cualquier otro (útil para consolidación, simulacros de restore cruzado o verificación centralizada de backups). El trade-off es que una filtración del keyfile compartido expone todos los hosts a la vez. Recomendado para homelabs y para flotas donde todos los hosts tienen el mismo propietario y límite de confianza.",
|
||||
"recoveryTitle": "Passphrase de recuperación y blob de escrow",
|
||||
"recoveryBody": "La passphrase de recuperación se solicita ANTES de escribir ningún keyfile en disco. ProxMenux la pide dos veces con validación de coincidencia; solo cuando el operador la confirma, se crea (o importa) el keyfile y <code>openssl</code> produce <code>pbs-key.recovery.enc</code> — el keyfile cifrado con la passphrase. Se escribe una copia en <code>/root/pbs-key.recovery-HOSTNAME-YYYYMMDD.enc</code> como respaldo offsite. Cancelar el diálogo de la passphrase deja el disco intacto — no se crea ningún keyfile y no hay nada que limpiar.",
|
||||
"modesPerHostBody": "Cada host genera su propia clave la primera vez que se activa el cifrado. Es el modo con mayor aislamiento: si la clave de un host se ve comprometida, no afecta a las copias de ningún otro. Cada host guarda además su propio sobre de recuperación en PBS, que se abre con la passphrase de recuperación de ese host. Recomendado para entornos de producción y para escenarios donde cada host tiene su propio responsable o requisitos distintos.",
|
||||
"modesSharedTitle": "Clave compartida (importar la misma en cada host)",
|
||||
"modesSharedBody": "Se genera una única clave y se importa en todos los hosts mediante la opción <em>Importar</em>. La gestión es más sencilla: hay un solo secreto que proteger, un solo sobre de recuperación válido para todos los hosts, y cualquier host puede leer las copias de cualquier otro (útil para verificar copias desde una máquina distinta o para ejercicios de restauración cruzada). A cambio, si la clave compartida se filtra queda expuesto todo el conjunto de hosts a la vez. Recomendado para laboratorios personales y entornos donde todos los hosts pertenecen al mismo responsable y comparten el mismo nivel de confianza.",
|
||||
"recoveryTitle": "Passphrase de recuperación y sobre cifrado",
|
||||
"recoveryBody": "La passphrase de recuperación se pide ANTES de generar o importar ninguna clave. ProxMenux la solicita dos veces y comprueba que coincidan; solo entonces crea la clave y produce el sobre de recuperación, que consiste en la propia clave cifrada con esa passphrase. Se guarda además una copia local del sobre en <code>/root/</code>, con el nombre del host y la fecha, pensada como respaldo externo (para llevarla a otro medio). Si se cancela el diálogo de la passphrase, no se crea nada: el host queda exactamente como estaba.",
|
||||
"blobUploadTitle": "Grupo emparejado en PBS",
|
||||
"blobUploadBody1": "Tras una copia PBS que usó el keyfile, el blob de escrow se sube como un segundo grupo de copia: <code>host/hostcfg-HOSTNAME-keyrecovery/BACKUP-TIME</code>. El prefijo compartido <code>hostcfg-HOSTNAME</code> coloca ambos grupos adyacentes en la interfaz de PBS; el sufijo <code>-keyrecovery</code> etiqueta la relación. La subida se ejecuta sin <code>--keyfile</code> (el blob ya está protegido con passphrase por openssl) y sólo cuando la copia actual usó el keyfile.",
|
||||
"blobUploadConstraintTitle": "Por qué dos grupos",
|
||||
"blobUploadConstraintBody": "<code>--keyfile</code> es un flag por invocación en <code>proxmox-backup-client backup</code>: todos los archivos de una misma invocación se cifran con el keyfile o ninguno. <code>hostcfg.pxar</code> requiere cifrado; <code>keyrecovery.conf</code> no puede cifrarse con el mismo keyfile (la recuperación en instalación fresca requeriría el propio keyfile que pretende recuperar). Dos invocaciones, dos backup IDs.",
|
||||
"blobUploadBody1": "Tras una copia cifrada, ProxMenux sube el sobre de recuperación a PBS como un segundo grupo de copia, con el mismo nombre que el del host pero terminado en <code>-keyrecovery</code>. Así aparecen los dos juntos en el listado del datastore, uno con las copias del host y otro con los sobres de recuperación. <strong>El sobre nunca sale del host en claro</strong>: antes de subirse, ProxMenux lo transforma en el propio host en un fichero cifrado con AES-256-CBC, usando una clave derivada de la passphrase de recuperación mediante PBKDF2 con 600 000 iteraciones y sal aleatoria (<code>openssl enc -aes-256-cbc -pbkdf2 -iter 600000 -salt</code>). PBS recibe únicamente el sobre ya cifrado, y solo se sube cuando la copia principal ha ido cifrada.",
|
||||
"envelopeSecurityTitle": "¿No es un riesgo subir el archivo keyrecovery a PBS?",
|
||||
"envelopeSecurityBody": "El keyrecovery viaja y se almacena cifrado en todo momento. La passphrase de recuperación nunca abandona el host: el cifrado ocurre localmente antes de la subida y PBS solo recibe el resultado ya cifrado. Aunque un administrador de PBS —o cualquiera con acceso al datastore— descargue el keyrecovery, sin la passphrase de recuperación no puede leer la clave que contiene: son solo bytes cifrados. Para reconstruir la clave hacen falta las dos cosas al mismo tiempo, el keyrecovery y la passphrase, y solo el operador dispone de ambas.",
|
||||
"blobUploadConstraintTitle": "Por qué dos grupos y no uno solo cifrado",
|
||||
"blobUploadConstraintBody": "Una misma subida de <code>proxmox-backup-client backup</code> cifra todos sus archivos con la misma clave, o no cifra ninguno — no hay opción intermedia. La copia del host tiene que ir cifrada con la clave del host; el sobre de recuperación no puede ir en esa misma subida, porque quedaría cifrado con la clave que precisamente contiene: en un equipo recién reinstalado no habría manera de abrirlo (haría falta la clave para descifrar la clave). Por eso se hacen dos subidas independientes y aparecen como dos grupos separados: la copia del host va cifrada por PBS con la clave, y el sobre de recuperación va cifrado por ProxMenux con la passphrase antes de subirse. Son dos capas de cifrado distintas que protegen dos activos distintos.",
|
||||
"blobUploadImageAlt": "Interfaz de PBS mostrando los grupos hostcfg-HOSTNAME y hostcfg-HOSTNAME-keyrecovery adyacentes en el listado del datastore.",
|
||||
"blobUploadImageCaption": "Interfaz de PBS — los grupos de copia emparejados. El grupo principal contiene las copias del host; el grupo -keyrecovery contiene el blob de escrow.",
|
||||
"recoverTitle": "Recuperación en instalación fresca",
|
||||
"recoverBody": "En un host sin keyfile local, el flujo de restauración llama a <code>hb_pbs_try_keyfile_recovery</code>. La función lista los grupos keyrecovery del PBS configurado, descarga el más reciente y pregunta por la passphrase. En caso de éxito, <code>pbs-key.conf</code> se escribe en el directorio de estado de ProxMenux y la copia cifrada puede restaurarse. Sin el keyfile y la passphrase, la copia cifrada no es recuperable."
|
||||
"recoverTitle": "Recuperación en un equipo recién instalado",
|
||||
"recoverBody": "Si se intenta restaurar en un equipo que no tiene todavía la clave de cifrado —por ejemplo tras reinstalar el host desde cero—, ProxMenux consulta los grupos de recuperación del PBS configurado, descarga el sobre más reciente y pide la passphrase de recuperación. Al confirmarla, la clave queda instalada en el host y la copia cifrada ya puede restaurarse con normalidad. Sin la clave y sin la passphrase, la copia cifrada no puede recuperarse."
|
||||
},
|
||||
"restoreAccess": {
|
||||
"heading": "Recuperación del lado de la restauración",
|
||||
|
||||
@@ -0,0 +1,238 @@
|
||||
{
|
||||
"meta": {
|
||||
"title": "Glosario de términos — Backup & Restore | ProxMenux",
|
||||
"description": "Glosario de términos y definiciones en español para el sistema de copia y restauración de ProxMenux: cifrado, clave, passphrase, sobre de recuperación, PBS, chunks, rootfs, manifiesto, runner y hidratación cross-kernel.",
|
||||
"ogTitle": "Glosario de Backup & Restore | ProxMenux",
|
||||
"ogDescription": "Definiciones claras en español para los términos que aparecen en la documentación de copia y restauración de ProxMenux.",
|
||||
"twitterTitle": "Glosario Backup & Restore | ProxMenux",
|
||||
"twitterDescription": "Passphrase, keyfile, sobre de recuperación, rootfs, manifiesto, PBS, chunks — todo definido en español."
|
||||
},
|
||||
"header": {
|
||||
"title": "Glosario",
|
||||
"description": "Términos que aparecen a lo largo de la documentación de copia y restauración, con su definición.",
|
||||
"section": "Backup & Restore"
|
||||
},
|
||||
"intro": {
|
||||
"body": "Los términos están agrupados por temas. Cada entrada incluye una definición breve."
|
||||
},
|
||||
"groups": [
|
||||
{
|
||||
"title": "Cifrado y recuperación de clave",
|
||||
"intro": "Terminología del bloque de cifrado de copias en PBS. Incluye dos secretos distintos: una clave binaria y una passphrase escrita.",
|
||||
"entries": [
|
||||
{
|
||||
"id": "passphrase-recuperacion",
|
||||
"term": "Passphrase de recuperación",
|
||||
"also": "recovery passphrase",
|
||||
"def": "Contraseña de texto que elige el operador para proteger el <a href=\"#sobre-recuperacion\">sobre de recuperación</a>. Se pide dos veces con validación de coincidencia y solo se usa para cifrar el sobre y para descifrarlo si algún día hay que recuperar la clave. <strong>No sirve para desbloquear la clave del keyfile</strong> ni se envía nunca a PBS. Nunca sale del host durante una copia normal."
|
||||
},
|
||||
{
|
||||
"id": "clave-cifrado",
|
||||
"term": "Clave de cifrado (keyfile)",
|
||||
"also": "keyfile, PBS encryption key",
|
||||
"def": "Fichero binario que Proxmox Backup Server utiliza para cifrar los <a href=\"#chunk\">chunks</a> de la copia antes de subirlos. Sin ese fichero, ninguna copia cifrada puede leerse. ProxMenux lo guarda en <code>/usr/local/share/proxmenux/pbs-key.conf</code> con permisos <code>600</code>. Es el activo que hay que proteger; el <a href=\"#sobre-recuperacion\">sobre de recuperación</a> existe precisamente para poder rescatar este fichero si se pierde."
|
||||
},
|
||||
{
|
||||
"id": "contrasena-keyfile",
|
||||
"term": "Contraseña de la clave (KDF passphrase)",
|
||||
"also": "keyfile passphrase, scrypt passphrase",
|
||||
"def": "Contraseña opcional que puede llevar la propia clave, distinta de la <a href=\"#passphrase-recuperacion\">passphrase de recuperación</a>. Solo aparece si la clave se creó con <code>--kdf scrypt</code> (una clave importada de otro sitio, por ejemplo). Sin ella, la clave no se puede desbloquear en cada uso. ProxMenux la persiste cifrada en el host para que las copias programadas puedan ejecutarse sin diálogo interactivo."
|
||||
},
|
||||
{
|
||||
"id": "sobre-recuperacion",
|
||||
"term": "Sobre de recuperación",
|
||||
"also": "recovery envelope, escrow blob, pbs-key.recovery.enc",
|
||||
"def": "La propia <a href=\"#clave-cifrado\">clave de cifrado</a> envuelta en una capa adicional: se cifra con la <a href=\"#passphrase-recuperacion\">passphrase de recuperación</a> mediante <a href=\"#aes-256-cbc\">AES-256-CBC</a> y <a href=\"#pbkdf2\">PBKDF2</a> antes de salir del host. Es lo que se sube a PBS en el grupo <code>-keyrecovery</code> y lo que se guarda además en <code>/root/pbs-key.recovery-HOSTNAME-FECHA.enc</code> como respaldo local. Sin la passphrase, el sobre es opaco: descargarlo desde PBS no revela la clave."
|
||||
},
|
||||
{
|
||||
"id": "cifrado-cliente",
|
||||
"term": "Cifrado del lado del cliente",
|
||||
"also": "client-side encryption",
|
||||
"def": "Modelo en el que los datos se cifran en el host de origen antes de subirse. PBS solo recibe y almacena datos cifrados; ni siquiera un administrador de PBS con acceso al datastore puede leerlos sin la clave. ProxMenux se apoya en este modelo y añade el <a href=\"#sobre-recuperacion\">sobre de recuperación</a> encima."
|
||||
},
|
||||
{
|
||||
"id": "kdf-none",
|
||||
"term": "--kdf none",
|
||||
"also": "clave sin contraseña",
|
||||
"def": "Opción de <code>proxmox-backup-client key create</code> que genera una clave sin contraseña asociada. La clave se puede usar directamente sin ningún diálogo, lo que es imprescindible para que los trabajos programados corran de forma desatendida. Es lo que ProxMenux usa por defecto al generar una clave nueva."
|
||||
},
|
||||
{
|
||||
"id": "kdf-scrypt",
|
||||
"term": "--kdf scrypt",
|
||||
"also": "clave con contraseña",
|
||||
"def": "Opción de <code>proxmox-backup-client key create</code> que genera una clave protegida con una <a href=\"#contrasena-keyfile\">contraseña de la clave</a>. Cada vez que se usa la clave hay que desbloquearla con esa contraseña. ProxMenux acepta este tipo de claves al importarlas y guarda la contraseña cifrada para que las copias programadas puedan correr sin intervención."
|
||||
},
|
||||
{
|
||||
"id": "aes-256-cbc",
|
||||
"term": "AES-256-CBC",
|
||||
"def": "Algoritmo de cifrado simétrico estándar. ProxMenux lo utiliza (vía <code>openssl enc -aes-256-cbc</code>) para envolver la <a href=\"#clave-cifrado\">clave de cifrado</a> con la <a href=\"#passphrase-recuperacion\">passphrase de recuperación</a> y producir el <a href=\"#sobre-recuperacion\">sobre</a>."
|
||||
},
|
||||
{
|
||||
"id": "pbkdf2",
|
||||
"term": "PBKDF2",
|
||||
"def": "Función criptográfica que transforma una contraseña escrita por una persona en una clave binaria adecuada para cifrar datos. Encarece los intentos de fuerza bruta aplicando muchas iteraciones. ProxMenux la usa con 600 000 iteraciones y sal aleatoria cuando cifra el sobre de recuperación."
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Estructura de la copia",
|
||||
"intro": "Términos que describen lo que hay dentro de una copia, sea cual sea el destino.",
|
||||
"entries": [
|
||||
{
|
||||
"id": "rootfs",
|
||||
"term": "rootfs / sistema de archivos raíz",
|
||||
"def": "Copia plana del sistema de ficheros del host de origen, producida por <code>rsync</code> sobre el <a href=\"#perfil-defecto\">perfil por defecto</a> más cualquier <a href=\"#rutas-personalizadas\">ruta personalizada</a>. No es una imagen del disco entero: solo se copian las rutas que contienen configuración o estado que Proxmox no puede regenerar por sí solo."
|
||||
},
|
||||
{
|
||||
"id": "manifiesto",
|
||||
"term": "Manifiesto (manifest.json)",
|
||||
"def": "Documento JSON estructurado que describe el host de origen en el momento de la copia: hardware, almacenamiento, kernel, componentes instalados por ProxMenux e inventario de VMs y LXCs. Lo genera ProxMenux con seis colectores independientes. La restauración lo utiliza para comparar origen y destino."
|
||||
},
|
||||
{
|
||||
"id": "staging",
|
||||
"term": "Directorio de staging",
|
||||
"def": "Directorio temporal donde ProxMenux ensambla los tres bloques (rootfs, metadata y manifiesto) antes de empaquetarlos y subirlos al destino. Se elimina automáticamente al terminar la copia, incluso si se aborta."
|
||||
},
|
||||
{
|
||||
"id": "perfil-defecto",
|
||||
"term": "Perfil por defecto",
|
||||
"def": "Conjunto curado de rutas que ProxMenux copia por defecto en toda copia. Cubre configuración de PVE, red, SSH, kernel, apt, herramientas ProxMenux y otras. Está definido en el código y se documenta en la página <em>Cómo funciona</em>."
|
||||
},
|
||||
{
|
||||
"id": "rutas-personalizadas",
|
||||
"term": "Rutas personalizadas (custom paths)",
|
||||
"def": "Rutas adicionales que el usuario añade al <a href=\"#perfil-defecto\">perfil por defecto</a>. Pueden ser persistentes (guardadas en <code>backup-extra-paths.txt</code>) o puntuales para una sola ejecución (marcadas en modo Custom)."
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Destinos y almacenamiento",
|
||||
"intro": "Términos ligados al lugar donde acaba la copia — servidor PBS, archivo local o repositorio Borg — y a la forma en que PBS organiza los datos.",
|
||||
"entries": [
|
||||
{
|
||||
"id": "repositorio-pbs",
|
||||
"term": "Repositorio PBS",
|
||||
"def": "Combinación de servidor Proxmox Backup Server + <a href=\"#datastore\">datastore</a> + usuario al que se suben las copias. Se identifica con el formato <code>usuario@realm@host:datastore</code>. Un mismo servidor PBS puede alojar varios repositorios."
|
||||
},
|
||||
{
|
||||
"id": "datastore",
|
||||
"term": "Datastore",
|
||||
"def": "Almacén concreto dentro de un servidor PBS donde se guardan las copias y sus chunks. Cada datastore vive sobre un sistema de ficheros del servidor PBS y tiene sus propios permisos y políticas."
|
||||
},
|
||||
{
|
||||
"id": "chunk",
|
||||
"term": "Chunk / deduplicación por chunks",
|
||||
"def": "PBS divide cada copia en trozos (chunks) de tamaño variable, identifica cada trozo por su hash y solo guarda cada trozo una vez, aunque aparezca en muchas copias distintas. Esto hace que copias sucesivas del mismo host o entre hosts similares consuman muy poco espacio adicional."
|
||||
},
|
||||
{
|
||||
"id": "fingerprint",
|
||||
"term": "Fingerprint (huella)",
|
||||
"def": "Huella criptográfica del certificado TLS del servidor PBS. Sirve para verificar que se está hablando con el servidor correcto sin depender de una autoridad certificadora pública. ProxMenux la pasa a <code>proxmox-backup-client</code> vía la variable <code>PBS_FINGERPRINT</code>."
|
||||
},
|
||||
{
|
||||
"id": "grupo-copia",
|
||||
"term": "Grupo de copia (backup group)",
|
||||
"def": "Contenedor lógico dentro de PBS bajo el cual se acumulan todas las copias sucesivas del mismo activo. Cada nueva copia comparte deduplicación con las anteriores del mismo grupo. ProxMenux utiliza dos grupos por host cuando hay cifrado: uno para la copia del host y otro con sufijo <code>-keyrecovery</code> para el <a href=\"#sobre-recuperacion\">sobre de recuperación</a>."
|
||||
},
|
||||
{
|
||||
"id": "backup-id",
|
||||
"term": "Backup ID",
|
||||
"def": "Nombre del <a href=\"#grupo-copia\">grupo de copia</a>. ProxMenux propone por defecto <code>hostcfg-HOSTNAME</code> y permite editarlo antes de la subida; los caracteres no admitidos se limpian automáticamente."
|
||||
},
|
||||
{
|
||||
"id": "pxar",
|
||||
"term": ".pxar",
|
||||
"def": "Formato de archivo propio de PBS para directorios. Actúa como un tar optimizado para la deduplicación por chunks: en lugar de almacenar un fichero opaco, PBS descompone su contenido en chunks reusables."
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Ejecución y programación",
|
||||
"intro": "Términos del sistema de trabajos programados de ProxMenux.",
|
||||
"entries": [
|
||||
{
|
||||
"id": "runner",
|
||||
"term": "Runner",
|
||||
"def": "Script <code>run_scheduled_backup.sh</code> que ejecuta una copia programada. Lee la configuración del trabajo, lanza el backend correspondiente (Local, PBS o Borg), aplica la retención al terminar y envía las notificaciones configuradas."
|
||||
},
|
||||
{
|
||||
"id": "trabajo-programado",
|
||||
"term": "Trabajo programado",
|
||||
"def": "Configuración persistida de una copia recurrente. Incluye destino, credenciales, cifrado, horario y retención. Se guarda en <code>/var/lib/proxmenux/backup-jobs/<id>.env</code>."
|
||||
},
|
||||
{
|
||||
"id": "modo-adjunto",
|
||||
"term": "Modo adjunto (attach mode)",
|
||||
"def": "Trabajo programado que no lleva horario propio; se dispara automáticamente cada vez que una tarea <code>vzdump</code> de PVE existente se ejecuta. Hereda el horario y la retención de esa tarea padre. Solo compatible con destinos Local y PBS."
|
||||
},
|
||||
{
|
||||
"id": "timer-systemd",
|
||||
"term": "Timer systemd",
|
||||
"def": "Mecanismo estándar de systemd para disparar un comando según un calendario. ProxMenux crea un timer por cada trabajo programado <em>independiente</em> (no adjunto); los trabajos adjuntos no usan timer porque se disparan desde el <a href=\"#modo-adjunto\">script-hook de PVE</a>."
|
||||
},
|
||||
{
|
||||
"id": "retencion",
|
||||
"term": "Retención (keep-last, keep-daily…)",
|
||||
"def": "Política que decide qué copias antiguas se conservan y cuáles se eliminan. Se define por trabajo con parámetros como <code>keep-last</code>, <code>keep-daily</code>, <code>keep-weekly</code>, <code>keep-monthly</code>. El runner la aplica después de cada copia exitosa."
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Restauración",
|
||||
"intro": "Términos del flujo de restauración.",
|
||||
"entries": [
|
||||
{
|
||||
"id": "restauracion-universal",
|
||||
"term": "Restauración universal",
|
||||
"def": "La restauración de ProxMenux no se limita a extraer el sistema de ficheros: consulta el manifiesto para detectar diferencias entre origen y destino, reproduce la configuración del sistema y relanza los instaladores de los componentes propios. El objetivo es reproducir el host de origen, no solo el archivo."
|
||||
},
|
||||
{
|
||||
"id": "hidratacion",
|
||||
"term": "Hidratación (cross-kernel)",
|
||||
"def": "Pasada de restauración que funde la configuración propia del usuario del origen (tokens IOMMU, IDs de dispositivos VFIO, quirks personalizadas, claves de GRUB) sobre la configuración de arranque fresca del destino, sin copiar verbatim los ficheros ligados al kernel del origen. Se ejecuta cuando el kernel del destino es más reciente que el de la copia."
|
||||
},
|
||||
{
|
||||
"id": "cross-kernel",
|
||||
"term": "Restauración cross-kernel",
|
||||
"def": "Restauración en la que el kernel del destino es distinto (normalmente más nuevo) que el del origen. Requiere la pasada de <a href=\"#hidratacion\">hidratación</a> para no arrastrar ficheros incompatibles con el kernel del destino."
|
||||
},
|
||||
{
|
||||
"id": "instalador-postboot",
|
||||
"term": "Instalador post-arranque",
|
||||
"def": "Componentes que se reinstalan tras el primer arranque del host restaurado (drivers NVIDIA, drivers Coral TPU, herramientas AMD GPU, herramientas Intel GPU). Cada instalador se ejecuta contra el kernel del destino, por lo que el host restaurado no depende de que el kernel del origen esté presente."
|
||||
},
|
||||
{
|
||||
"id": "compatibility-check",
|
||||
"term": "Compatibility check",
|
||||
"def": "Comparación entre el manifiesto del origen y el estado del destino que ProxMenux realiza al principio de la restauración. Decide qué partes se copian verbatim, cuáles necesitan hidratación y cuáles se recrean desde el instalador."
|
||||
},
|
||||
{
|
||||
"id": "equipo-recien-instalado",
|
||||
"term": "Equipo recién instalado",
|
||||
"also": "fresh install",
|
||||
"def": "Host acabado de reinstalar desde cero, sin la <a href=\"#clave-cifrado\">clave de cifrado</a> local. Para restaurar copias cifradas hace falta primero recuperar la clave desde el <a href=\"#sobre-recuperacion\">sobre</a> almacenado en PBS, con la <a href=\"#passphrase-recuperacion\">passphrase de recuperación</a>."
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"whereNext": {
|
||||
"heading": "Dónde seguir",
|
||||
"items": [
|
||||
{
|
||||
"label": "Cómo funciona",
|
||||
"href": "/docs/backup-restore/how-it-works",
|
||||
"tail": " — dónde encajan el rootfs, el manifiesto y el inventario de aplicaciones en cada copia."
|
||||
},
|
||||
{
|
||||
"label": "Destino Proxmox Backup Server",
|
||||
"href": "/docs/backup-restore/destinations/pbs",
|
||||
"tail": " — dónde se explica en profundidad el cifrado del lado del cliente, la clave, la passphrase de recuperación y el sobre."
|
||||
},
|
||||
{
|
||||
"label": "Restauración",
|
||||
"href": "/docs/backup-restore/restoring",
|
||||
"tail": " — flujo de la restauración y uso del manifiesto."
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -9,12 +9,12 @@
|
||||
},
|
||||
"header": {
|
||||
"title": "Cómo funciona",
|
||||
"description": "Desglose interno de una copia de ProxMenux — sistema de ficheros, manifiesto e inventario de aplicaciones — y cómo la restauración consume los tres para reproducir el host de origen sobre un destino que puede no compartir el mismo kernel.",
|
||||
"description": "Desglose interno de una copia de seguridad creada con ProxMenux — sistema de ficheros, manifiesto e inventario de aplicaciones — y cómo la restauración consume los tres para reproducir el host de origen sobre un destino que puede no compartir el mismo kernel.",
|
||||
"section": "Backup & Restore"
|
||||
},
|
||||
"intro": {
|
||||
"title": "Un archivo, tres bloques",
|
||||
"body": "Cada copia produce un layout de directorio con tres bloques bien definidos bajo una única raíz de staging. El archivo que se sube al destino (archivo local <code>.tar.zst</code>, backup PBS o archivo Borg) contiene ese layout exacto. La restauración lee los tres bloques de forma independiente, en un orden concreto que garantiza la corrección: primero se copia el <strong>rootfs</strong> para colocar la configuración, después se consulta <strong>el manifiesto</strong> para detectar drift y decidir qué omitir, y finalmente <strong>el inventario de aplicaciones</strong> dirige la pasada de reinstalación post-arranque. No hay dependencias entre bloques — cada uno puede inspeccionarse o extraerse de forma independiente."
|
||||
"body": "Cada copia produce un layout de directorio con tres bloques bien definidos bajo una única raíz de staging. El archivo que se sube al destino (archivo local <code>.tar.zst</code>, backup PBS o archivo Borg) contiene ese layout exacto. La restauración lee los tres bloques de forma independiente, en un orden concreto que garantiza la corrección: primero se copia el <strong>rootfs</strong> —el sistema de archivos raíz del host— para colocar la configuración, después se consulta <strong>el manifiesto</strong> para detectar drift y decidir qué omitir, y finalmente <strong>el inventario de aplicaciones</strong> dirige la pasada de reinstalación post-arranque. No hay dependencias entre bloques — cada uno puede inspeccionarse o extraerse de forma independiente."
|
||||
},
|
||||
"layout": {
|
||||
"heading": "Layout del archivo",
|
||||
@@ -121,7 +121,7 @@
|
||||
}
|
||||
],
|
||||
"schemaTitle": "Validación por esquema",
|
||||
"schemaBody": "El manifiesto valida contra <code>scripts/backup_restore/schema/manifest.schema.json</code>. Ejecutar <code>build_manifest.sh --validate</code> dispara una validación JSON Schema por Python (requiere <code>python3</code> + <code>jsonschema</code>). Si el módulo no está presente, la comprobación se omite silenciosamente — la validación es principalmente una ayuda de desarrollo, no una dependencia en tiempo de ejecución."
|
||||
"schemaBody": "ProxMenux incluye una plantilla que describe qué campos debe contener el manifiesto y qué forma tiene cada uno. Cuando se genera una copia se puede comprobar automáticamente que el manifiesto respeta esa plantilla, de modo que si un colector produjera un JSON malformado o con un campo mal escrito se detectaría en el momento. Es una comprobación destinada al desarrollo del propio ProxMenux: si el sistema no la tiene instalada, la copia sigue funcionando con normalidad y el manifiesto se genera igual."
|
||||
},
|
||||
"applications": {
|
||||
"heading": "El inventario de aplicaciones",
|
||||
|
||||
@@ -38,7 +38,7 @@
|
||||
},
|
||||
"restoreIsUniversal": {
|
||||
"heading": "La restauración reproduce el host de origen, no el archivo",
|
||||
"body": "Restaurar una copia de ProxMenux no consiste solamente en extraer el sistema de ficheros. El flujo de restauración lee el manifiesto para detectar diferencias entre origen y destino (variaciones de hardware, renombrado de NICs, versión de kernel, identidad de la pool ZFS), reproduce el sistema de ficheros y lanza el instalador correspondiente a cada servicio que estuviera instalado en el origen (controlador NVIDIA, Coral TPU, herramientas AMD GPU, herramientas Intel GPU). Cada instalador se ejecuta contra el <strong>kernel actual del destino</strong>, por lo que el host restaurado no depende de que el kernel del origen esté presente. Cuando el kernel del destino es más reciente que el de la copia, una pasada de <strong>hidratación</strong> kernel-agnóstica funde la configuración propia del usuario (tokens IOMMU, IDs de dispositivos VFIO, quirks personalizadas, claves de GRUB) sobre la configuración de arranque fresca del destino, sin copiar verbatim los ficheros ligados al kernel."
|
||||
"body": "Restaurar una copia de seguridad no consiste solamente en extraer el sistema de ficheros. El flujo de restauración lee el manifiesto para detectar diferencias entre origen y destino (variaciones de hardware, renombrado de NICs, versión de kernel, identidad de la pool ZFS), reproduce el sistema de ficheros y lanza el instalador correspondiente a cada servicio que estuviera instalado en el origen (controlador NVIDIA, Coral TPU, herramientas AMD GPU, herramientas Intel GPU). Cada instalador se ejecuta contra el <strong>kernel actual del destino</strong>, por lo que el host restaurado no depende de que el kernel del origen esté presente. Cuando el kernel del destino es más reciente que el de la copia, una pasada de <strong>hidratación</strong> kernel-agnóstica funde la configuración propia del usuario (tokens IOMMU, IDs de dispositivos VFIO, quirks personalizadas, claves de GRUB) sobre la configuración de arranque fresca del destino, sin copiar verbatim los ficheros ligados al kernel."
|
||||
},
|
||||
"twoInterfaces": {
|
||||
"heading": "Dos interfaces, un único backend",
|
||||
|
||||
@@ -24,6 +24,10 @@
|
||||
"title": "Modo adjunto — recomendado cuando ya existe una tarea vzdump de PVE",
|
||||
"body": "Cuando ya hay una tarea de copia vzdump de PVE configurada para las VMs y los LXCs de este nodo, adjuntar la copia de host a esa tarea garantiza que la configuración del host se captura en la <strong>misma ventana</strong> que los invitados. En la restauración, las configuraciones de los invitados vienen de la copia de host (viven bajo <code>/etc/pve</code>), y los discos de los invitados vienen de la copia vzdump tomada al mismo tiempo — ambos conjuntos son consistentes entre sí, por lo que una recuperación completa del nodo puede reproducir el host y re-adjuntar cada invitado sin drift de versiones."
|
||||
},
|
||||
"frequencyBadge": {
|
||||
"title": "Frecuencia recomendada",
|
||||
"body": "Para garantizar la máxima compatibilidad entre la copia y su posterior restauración se recomienda hacer copias de seguridad del host con frecuencia. Cuanto más reciente sea la copia respecto al estado actual del host, menor será la desviación de configuración, paquetes y componentes que la restauración tendrá que reconciliar."
|
||||
},
|
||||
"modes": {
|
||||
"heading": "Los dos modos",
|
||||
"rows": [
|
||||
|
||||
Reference in New Issue
Block a user