---
title: "Operaciones de Cosigner"
description: "Referencia de cosigner-cli, copias de seguridad, exportaciones de recuperación, actualizaciones y monitoreo."
url: https://docs.fystack.io/es/cosigner/operations
last_updated: 2026-11-13
---

> ## Documentation index
> Fetch the complete documentation index at: https://docs.fystack.io/llms.txt
> Use it to discover all available pages before exploring further.

# Operaciones de Cosigner

Referencia de la CLI, copias de seguridad, actualizaciones y monitoreo.

## Comandos

Flags globales: `--home` (directorio de la instancia; por defecto `COSIGNER_HOME` y luego el directorio actual) y `--docker`.

| Comando | Qué hace | Flags |
| --- | --- | --- |
| `up` | Verifica, empareja e inicia una nueva instancia. Equivale a `start` una vez emparejada. | `--apex-endpoint` `--config` `--profile` `--image` `--token-file` |
| `start` | Inicia. Pide la contraseña en el perfil manual. |  |
| `stop` | Detiene y conserva el estado. Drena las sesiones durante hasta 25s. |  |
| `restart` | Recrea el contenedor. |  |
| `status` | `ready`, `state`, `participant_id`, `active_sessions`. |  |
| `logs` | Logs del contenedor. | `--tail` `-f` |
| `doctor` | Comprueba el host, la configuración y la firma de la imagen. |  |
| `info` | Clave pública, imagen, huella del callback. |  |
| `callback add` | Exige la aprobación por callback. | `--url` `--server-public-key` `--ca` `--no-restart` |
| `callback remove` | Deja de exigir la aprobación. | `-y` `--no-restart` |
| `backup` | Copia de seguridad cifrada de la instancia. El Cosigner debe estar detenido. | `--out` |
| `restore` | Restaura en un directorio vacío. | `--in` |
| `export` | Escribe archivos de recuperación `.mshare`. Perfil manual, detenido. | `--wallet` `--out-dir` `--list` |
| `update` | Verifica e instala una versión más reciente tras una copia de seguridad. | `--version` `--backup-out` `--dry-run` |
| `version` | Versión de la CLI. |  |

### Variables de entorno

| Variable | Uso |
| --- | --- |
| `COSIGNER_HOME` | Directorio de la instancia |
| `COSIGNER_PASSWORD_FD` | Lee la contraseña de almacenamiento desde un descriptor de archivo |
| `COSIGNER_RECOVERY_PASSWORD_FD` | Lee la contraseña de la copia de seguridad desde un descriptor de archivo |
| `COSIGNER_NO_UPDATE_CHECK=1` | Oculta los avisos de actualización |

## Perfiles

|  | manual | unattended |
| --- | --- | --- |
| Clave de almacenamiento | Contraseña (Argon2id) | AWS KMS |
| Inicio | Contraseña en cada inicio | Automático, al arrancar |
| Reinicio de Docker | `no` | `on-failure:5` |
| `.mshare` export | Sí | No |

Se define en `up`. No se puede cambiar después.

## Automatizar el reinicio

En el perfil manual, `start` y `restart` piden la frase de contraseña de almacenamiento. Para ejecutarlos desde un script, pasa la frase de contraseña por un descriptor de archivo con `COSIGNER_PASSWORD_FD`.

Desde un archivo:

```bash
chmod 600 /etc/cosigner/passphrase
COSIGNER_PASSWORD_FD=3 cosigner-cli --home /srv/cosigner restart 3< /etc/cosigner/passphrase
```

Desde un almacén de secretos, para que la frase de contraseña no se escriba en disco:

```bash
COSIGNER_PASSWORD_FD=3 cosigner-cli --home /srv/cosigner restart \
  3< <(gcloud secrets versions access latest --secret=cosigner-passphrase)
```

- `3` es el número del descriptor de archivo. Debe ser 3 o mayor y el mismo en ambos lugares.
- El archivo debe contener solo la frase de contraseña. Se elimina un salto de línea final; cualquier otro carácter adicional hace que el desbloqueo falle.
- Una frase de contraseña incorrecta falla de inmediato, sin reintentos.

> **Note:** Esto es menos seguro que escribir la frase de contraseña a mano. Cualquiera que pueda leer el archivo de la frase de contraseña o el secreto, y ejecutar `cosigner-cli`, puede desbloquear el Cosigner. Guarda la frase de contraseña fuera del directorio de la instancia, nunca junto a `secrets/storage-kek.enc`, y limita quién puede leerla. Es preferible usar un almacén de secretos en lugar de un archivo.

## Copia de seguridad y restauración

`backup` escribe un único archivo con la configuración, los secretos, la identidad, el registro de emparejamiento, la base de datos cifrada y el log de auditoría. Se cifra con una contraseña de recuperación independiente (Argon2id + AES-256-GCM).

```bash
cosigner-cli stop
cosigner-cli backup --out /backups/cosigner-2026-10-12.cosrec
cosigner-cli start
```

Escríbelo fuera del directorio de la instancia. Los datos de la instancia están limitados a 128 MiB.

```bash
cosigner-cli --home /srv/cosigner-restored restore --in /backups/cosigner-2026-10-12.cosrec
cosigner-cli --home /srv/cosigner-restored start
```

> **Note:** Detén o revoca primero la instancia anterior. Nunca ejecutes dos copias del mismo Cosigner.

Prueba las restauraciones en un host limpio con regularidad.

## Exportación de recuperación

`export` escribe un `.mshare` por billetera, cifrado con una frase de contraseña de seis palabras que se muestra una sola vez. Estos archivos son la aportación del Cosigner a [Fystack Recovery](https://github.com/fystack/cosigner-recovery), que reconstruye las claves sin conexión a partir de un umbral de shares. Un solo archivo no puede reconstruir una clave.

```bash
cosigner-cli stop
cosigner-cli export --out-dir /secure/recovery
cosigner-cli start
```

Guarda las frases de contraseña separadas de los archivos. Consulta [Recuperación de claves](https://docs.fystack.io/cosigner/recovery.md) para ver el procedimiento completo.

## Actualizaciones

```bash
cosigner-cli update --dry-run
cosigner-cli update --backup-out /backups/pre-update.cosrec
```

1. Elige la versión más reciente (o `--version`). No permite volver a versiones anteriores.
2. Verifica la firma y el contrato del contenedor.
3. Detiene el Cosigner y escribe una copia de seguridad.
4. Fija el nuevo digest e inicia.

No hay reversión automática. Conserva la copia de seguridad hasta que la nueva versión haya firmado transacciones reales.

## Monitoreo

**Estado**: se comprueba cada 10s; se considera desactualizado tras 15s. Configura alertas para:

- `ready: false` más allá de la configuración del primer arranque.
- `state: callback_unavailable`.
- Salida del contenedor (el perfil manual nunca se reinicia por sí solo).

**Log de auditoría**: `state/audit.jsonl`, firmado y encadenado por hash. Eventos: `session_start`, `session_end`, `session_abort`, `callback_decision`, `kek_use`, `identity_sign`, `backup_created`, `restore_performed`. Envíalo fuera del host; Docker no lo rota.

**Logs**: Docker `json-file`, 10 MB x 5.

## Retirada del servicio

1. Pide a Fystack que revoque el Cosigner.
2. `cosigner-cli stop`.
3. Conserva una copia de seguridad final y las exportaciones según tu política de retención y, luego, elimina el directorio de la instancia.