---
updatedAt: 2026-03-20T19:25:50.000Z
agentTools:
  projectIndex: https://docs.melrosenetworks.com/llms.txt
---

# Operator Guide: Running SignalBridge at the Edge

# What you’re operating

SignalBridge sits in the **operator environment**: it **ingests** S1AP/NGAP signalling (from file, TCP PCAP stream, or stdin), **filters** what you allow, **anonymises** subscriber identities when configured, and **exports** to PCAP, TCP, UDP, or **HTTP(S)** NDJSON batches—typically toward analysis or a platform like [Signal Cloud](https://melrosenetworks.com/scloud). Your job is to wire capture → policy → egress safely and observably.

# Before you start

* **Data governance:** Confirm what may leave the core (raw vs anonymised, retention, lawful basis).
* **Network:** Inbound path to your capture source (file mount, mirror port, or TCP listener); outbound to ingest (HTTPS URL, TCP/UDP peer). Firewall and TLS termination as required.
* **Secrets:** If you use encrypted HTTP output, the config includes a hex **encryption key** (32-byte). Treat it like any key material—vault, rotation policy, no plain-text tickets.

# Deploy the binary

Operators usually take a **released** `signalbridge` from the build pipeline. If you must build on-site, use the same dependency list as in the README (libpcap, yaml-cpp, curl, OpenSSL, zlib). The public bundle vendors parsers under `third_party/s1see/` so a standard clone builds without a separate S1-SEE checkout.

# Configuration (`config/conduit.yaml`)

The sample file shows the knobs you actually turn:

```4:28:config/conduit.yaml
# When set (hex-encoded 32-byte key), HTTP output is encrypted with AES-256-GCM.
encryption_key: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"

anonymisation:
  enabled: false
  mcc: "999"
  mnc: "99"
  # imsi_map_path: ""  # Optional: write "original -> anonymised" mapping when done
  replacement_byte: 0  # Legacy: used when mcc empty (zero-fill mode)

filter:
  # Include only these protocols (empty = all). Values: S1AP, NGAP
  protocol_include: []
  # Exclude these protocols
  protocol_exclude: []
  # Include only these procedure codes (empty = all)
  procedure_include: []
  # Exclude these procedure codes
  procedure_exclude: []
  # IP allow list (empty = allow all)
  ip_allow: []
  # IP deny list
  ip_deny: []
  # Drop encrypted NAS (cannot anonymise without keys)
  drop_encrypted_nas: false
```

**Operator checklist:**

| Area                 | What to decide                                                                                                                                                                    |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Anonymisation**    | On/off, synthetic MCC/MNC, optional `imsi_map_path` for audit/debug (protect that file).                                                                                          |
| **Filters**          | S1AP-only vs NGAP vs both; procedure allow/deny lists to cut volume; IP allow/deny to scope eNB/gNB or probes.                                                                    |
| **Encrypted NAS**    | `drop_encrypted_nas: true` when you cannot decrypt—avoids leaking opaque payloads you can’t anonymise.                                                                            |
| **HTTP(S) security** | Real `encryption_key` in prod; HTTPS URL to trusted ingest; path must match what the receiver expects (e.g. `/frames/{uuid}`).                                                    |
| **Inputs**           | `file` with path, or `tcp` listener `address`, or stdin (often used under a supervisor). Comments in YAML mention `grpc` as a type—confirm against your release notes if present. |
| **Outputs**          | `http`/`https` URL, or file, or `tcp`/`udp` peer per your downstream.                                                                                                             |

Example output stanza from the same file:

```50:56:config/conduit.yaml
outputs:
  - type: "http"
    path: "http://127.0.0.1:9876/frames/550e8400-e29b-41d4-a716-446655440000"
    # Set to file path, or use type: https with address for HTTP streaming
    # For HTTP streaming: type: https, address: "https://ingest.example.com/frames/{uuid}"
    # For TCP output: type: tcp, address: "host:port"
    # For UDP output: type: udp, address: "host:port"
```

Ingest path conventions are also summarized in [config/ingest\_endpoints.yaml](https://github.com/melrosenetworks/SignalBridge/blob/main/config/ingest_endpoints.yaml).

# Validate, then run

Dry-run config parsing (no traffic processing):

```bash
./signalbridge validate -c /path/to/conduit.yaml
```

Live run:

```bash
./signalbridge run -c /path/to/conduit.yaml
```

CLI override for a one-off file test:

```bash
./signalbridge run -i capture.pcap -o anonymised.pcap
```

# Prometheus metrics

Metrics bind is **CLI**, not YAML: `-m` / `--metrics <addr>`, default **`127.0.0.1:9090`**. For scraping from another host, set an interface/IP your monitoring can reach and open the port in policy. Endpoint is `/metrics` (see `apps/signalbridge.cc` help string and metrics server startup).

# Local smoke test (optional)

To verify HTTP streaming before pointing at production, a reference Python ingest exists under `server/` (`signalvault_ingest.py`); use only on controlled lab networks. Details: [README.md](https://github.com/melrosenetworks/SignalBridge/blob/main/README.md)  § HTTP streaming.

# Run as a service (typical pattern)

* Run `signalbridge run -c ...` under **systemd** (or equivalent) with `Restart=on-failure`, explicit user, read-only config path, and locked-down permissions on YAML and any `imsi_map_path` output.
* Redirect logs to your aggregator; rely on **metrics** for throughput and error trending.
* Align **capture restart** (TCP reconnect, file rotation) with your input mode—use `--loop` for TCP if your deployment expects repeated connections and config reload (per root README).

<br />