58 lines
2.9 KiB
Markdown
58 lines
2.9 KiB
Markdown
---
|
|
name: wg_peer_add
|
|
kind: function
|
|
lang: go
|
|
domain: infra
|
|
version: "1.0.0"
|
|
purity: impure
|
|
signature: "func WGPeerAdd(spec WGPeerSpec, configPath, subnetCIDR string) (WGPeerResult, error)"
|
|
description: "Hub-side: anade peer WireGuard al wg0.conf con IP asignada del pool, syncconf en caliente sin reiniciar interface. Idempotente por PublicKey + DeviceID. Mantiene comentario # DeviceID:<id> sobre cada bloque [Peer] para tracking inverso."
|
|
tags: [wireguard, hub, peer, mesh, infra]
|
|
params:
|
|
- name: spec
|
|
desc: "WGPeerSpec con DeviceID (identificador logico), PublicKey (base64), PresharedKey (base64, opcional), AllowedIPs (CIDR; vacio = autoasignar del pool)"
|
|
- name: configPath
|
|
desc: "Ruta absoluta al wg0.conf del hub, ej /etc/wireguard/wg0.conf"
|
|
- name: subnetCIDR
|
|
desc: "Subnet del pool de IPs WireGuard, ej '10.42.0.0/24'. La .1 se reserva para el hub y se excluye del pool."
|
|
output: "WGPeerResult con DeviceID, AssignedIP (pura sin CIDR), ConfigPath y Status ('added'|'already-present'|'reconfigured')"
|
|
uses_functions: []
|
|
uses_types: [wg_peer_spec_go_infra, wg_peer_result_go_infra]
|
|
returns: [wg_peer_result_go_infra]
|
|
returns_optional: false
|
|
error_type: "error_go_core"
|
|
imports: []
|
|
tested: true
|
|
tests:
|
|
- "peer nuevo con AllowedIPs vacio asigna 10.42.0.2"
|
|
- "agregar segundo peer asigna 10.42.0.3"
|
|
- "agregar mismo PublicKey otra vez retorna already-present"
|
|
- "agregar DeviceID existente con clave distinta retorna reconfigured"
|
|
test_file_path: "functions/infra/wg_peer_add_test.go"
|
|
file_path: "functions/infra/wg_peer_add.go"
|
|
---
|
|
|
|
## Ejemplo
|
|
|
|
```go
|
|
spec := infra.WGPeerSpec{
|
|
DeviceID: "pc-aurgi",
|
|
PublicKey: "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=",
|
|
}
|
|
res, err := infra.WGPeerAdd(spec, "/etc/wireguard/wg0.conf", "10.42.0.0/24")
|
|
// res.AssignedIP == "10.42.0.2" (primera IP libre del pool)
|
|
// res.Status == "added"
|
|
```
|
|
|
|
## Cuando usarla
|
|
|
|
Cuando un dispositivo nuevo (PC, contenedor, mobile) se une al mesh WireGuard del hub. Llamar tras generar las claves con `wg_keygen_go_infra`. Idempotente: si el DeviceID ya existe con la misma clave, devuelve `already-present` sin tocar el config.
|
|
|
|
## Gotchas
|
|
|
|
- **Race condition**: si dos llamadas concurrentes añaden peers simultáneamente, la segunda puede asignar la misma IP libre. Usar file lock (`flock`) sobre `configPath` para serializar en produccion.
|
|
- **WG_SKIP_SYNCCONF=1**: en entornos CI sin WireGuard instalado, establecer esta variable para saltarse el exec de `wg syncconf`. Los tests ya la activan en el `init()`.
|
|
- **syncconf falla → rollback automático**: si el `wg syncconf` devuelve error, se restaura el backup `.bak` y se devuelve error. El config queda intacto.
|
|
- **chmod 600**: la función hace `chmod 600` sobre `configPath` tras cada escritura. Asegúrate de que el proceso tiene permisos sobre el archivo.
|
|
- **Hub IP .1**: la función excluye `<red>.1` del pool de autoasignación. El hub debe tener esa IP. Si el hub usa otra IP, ajustar la lógica de `wgNextFreeIP`.
|