N
Nanami Docs
Browse docs
Browse docs
Browse docs

Troubleshooting GRE

Interpret GRE fail-closed diagnostics and internal runtime readiness.

Section
Browse docs
Path
/troubleshooting/gre

Use this playbook only for internal/platform review or legacy GRE metadata. GRE is not public production-ready in Nanami today. WireGuard is the production available transport for normal users.

Common symptoms

  • Network transport default shows GRE but effective tunnel status remains unavailable or disabled.
  • Gateway is WireGuard-ready or process-healthy, but GRE readiness stays false.
  • Runtime status remains pending after desired-state change.

Checks in Dashboard

  1. Tunnels: inspect effective protocol and runtime state; do not assume GRE from the network default.
  2. Gateway details: check GRE-specific runtime status and health reasons.
  3. Network runtime status: verify routing/dns apply state is not error.

Checks on gateway host

bash
ip -d link show type gre
ip -s link show type gre
ip route show
iptables -S NANAMI_GW_FORWARD

Frequent failure modes

GRE runtime unverified

  • Symptom: gateway_gre_not_supported, gateway_gre_runtime_unverified, or gateway_gre_isolation_unverified.
  • Fix: keep the path unavailable. GRE requires explicit runtime readiness, route-domain isolation, firewall/routing verification, and scheduler eligibility.

Missing or invalid remote endpoint

  • Symptom: tunnel interface not created or stays down.
  • Fix: ensure peer endpoint is resolvable/reachable and correctly formatted.

GRE underlay blocked

  • Symptom: no traffic counters, persistent disabled status.
  • Fix: allow GRE protocol traffic in underlay/firewall path.

Expected encryption mismatch

  • Symptom: security review flags cleartext transport.
  • Fix: use WireGuard instead, or add encrypted underlay (for example IPsec).

Mixed protocol assumptions

  • Symptom: operator expects WireGuard runtime semantics from a GRE transport default.
  • Fix: verify the network transport default, then use effective tunnel/runtime protocol diagnostics for the active path.

API diagnostics

bash
curl -sS "$API_URL/api/v1/tunnels"
curl -sS "$API_URL/api/v1/networks/<network-id>/runtime-status"

Look for:

  • protocolType: "gre"
  • runtimeState.status: applied|pending|unknown
  • safe gateway health reasons such as gateway_gre_not_supported, gateway_gre_runtime_unverified, or gateway_gre_isolation_unverified.