plexsphere

Appearance

Register a Node ​

Node self-enrolment is performed by the plexd agent against POST /v1/register; plexctl does not wrap it. This how-to drives the contract directly with curl so an operator can verify enrolment before handing it off to plexd.

Prerequisites ​

  • A BootstrapToken plaintext — see Issue a bootstrap token.
  • ${PLEXSPHERE_URL}, the ${PROJECT_ID} UUID, and the ${RESOURCE_ID} Resource handle for the Node.
  • WireGuard userland tools (wg) for the X25519 keypair.

Steps ​

Generate the keypair on the Node ​

shell
wg genkey | tee node.key | wg pubkey > node.pub
PUBKEY="$(cat node.pub)"     # 44-char base64, 32-byte X25519 point
NONCE="$(head -c 16 /dev/urandom | base64)"

The private half never leaves the Node. A non-X25519 key is rejected with 400 public_key_invalid.

Redeem the token ​

shell
curl --silent --show-error --fail-with-body \
  --request POST --header "Content-Type: application/json" \
  --data @- "${PLEXSPHERE_URL}/v1/register" <<EOF
{
  "project_id": "${PROJECT_ID}",
  "resource_id": "${RESOURCE_ID}",
  "bootstrap_token": "${BOOTSTRAP_TOKEN}",
  "nonce": "${NONCE}",
  "public_key": "${PUBKEY}"
}
EOF

The response carries the assigned mesh_ip, the per-Node secret, and the Domain's signing_public_key / signing_key_id. A reused nonce returns 403 nonce_collision; a second redemption of the same token returns 403 token_consumed.

Verification ​

shell
# mesh_ip from the response must fall inside the Domain mesh CIDR
ip -o addr show | grep "$(jq -r .mesh_ip register-response.json)"

See also ​