Knowledge Base

How to connect your router to the BGPCast route server. Two ways: direct BGP peering (needs a public IP on your router) or the connector agent (if your router is behind NAT/CGNAT). Copy the commands and substitute your values from the app.

Direct peering (router's public IP)

For routers with a public IP. Bring up a BGP session with the route server and substitute your peer IP and ASN from the app.

1. Filter rules (next-hop to ISP + discard)

/routing filter rule
add chain=bgp_in comment="Nexthop to ISP" disabled=no rule="set gw <next-hop>; accept;"
add chain=discard disabled=no rule="reject;"

2. BGP template

/routing bgp template
add as=<your-asn> disabled=no name=bgpcast output.network=bgp-networks .no-client-to-client-reflection=yes routing-table=main

3. BGP connection

/routing bgp connection
add as=<your-asn> cisco-vpls-nlri-len-fmt=auto-bits connect=yes disabled=no hold-time=4m input.filter=bgp_in instance=bgp-instance-bgpcast keepalive-time=1m listen=yes \
    local.address=<your-ip> .role=ebgp multihop=yes name=bgpcast output.filter-chain=discard .network=bgp-networks .no-client-to-client-reflection=yes \
    remote.address=<bgpcast-ip> .as=<bgpcast-asn> routing-table=main templates=bgpcast vrf=main

4. Verify the session is established

/routing/bgp/session/print

1. Full config (frr.conf)

! frr.conf
frr defaults traditional
hostname bgpcast-router
!
ip nht resolve-via-default
!
route-map bgpcast-in permit 10
 set ip next-hop <next-hop>
!
route-map bgpcast-out deny 10
!
router bgp <your-asn>
 neighbor <bgpcast-ip> remote-as <bgpcast-asn>
 neighbor <bgpcast-ip> ebgp-multihop 255
 address-family ipv4 unicast
  neighbor <bgpcast-ip> activate
  neighbor <bgpcast-ip> route-map bgpcast-in in
  neighbor <bgpcast-ip> route-map bgpcast-out out
  neighbor <bgpcast-ip> soft-reconfiguration inbound
 exit-address-family
!

<your-asn>, <bgpcast-asn>, <bgpcast-ip> — from the peer card in the app; <next-hop> — your ISP gateway. Routes install into the kernel automatically (zebra) — no extra stanza needed.

2. Verify the session is established

vtysh -c 'show bgp summary'

1. Full config (bird.conf)

# bird.conf
log syslog all;
router id <router-id>;

protocol device {}

protocol kernel {
  ipv4 { export all; };   # install learned routes into the kernel FIB
}

protocol bgp bgpcast {
  local as <your-asn>;
  neighbor <bgpcast-ip> as <bgpcast-asn>;
  multihop 255;
  ipv4 {
    import filter { gw = <next-hop>; accept; };
    export none;
  };
}

<router-id> — any 32-bit ID, e.g. the router's LAN IP; <your-asn>, <bgpcast-asn>, <bgpcast-ip> — from the peer card in the app; <next-hop> — your ISP gateway

2. Verify the session is established

birdc show protocols all bgpcast

Connector agent (behind NAT)

If your router is behind NAT/CGNAT. The agent is a small daemon: it pulls your announce set from the route server over HTTPS/WSS and re-originates it as BGP locally on your router. No inbound BGP session required. The agent is published at github.com/samfili/bgpcast-agent — the container image tagged latest on GHCR (used below), and the .ipk packages under Releases.

1. Install the package and start the service

opkg install ./bgpcast-agent_<version>-1_<arch>_entware.ipk
/opt/etc/init.d/S99bgpcast-agent start

2. Open the settings page (LAN only)

http://<router-ip>:8080/

3. Fill in the fields and click "Save & apply"

API URL:      https://bgpcast.cc
Agent token:  <your-token>

4. Full BIRD2 config (bird.conf)

# bird.conf
log syslog all;
router id <router-id>;

protocol device {}

protocol kernel {
  ipv4 { export all; };
}

protocol bgp bgpcast {
  local port 1791 as <your-asn>;       # BIRD uses 1791, leaving TCP/179 for the agent
  neighbor 127.0.0.1 as <agent-asn>;   # the agent listens on 179
  ipv4 {
    import filter { gw = <next-hop>; accept; };
    export none;
  };
}

<router-id> — any 32-bit ID, e.g. the router's LAN IP; <your-asn> = "Your ASN", <agent-asn> = "Agent ASN" — from the peer card in the app; <next-hop> — your ISP gateway. local port 1791 keeps BIRD off TCP/179 so it doesn't clash with the agent, which listens on 179.

Architectures: mipsel, mips, aarch64. The settings page has two fields — "API URL" (the route server address) and "Agent token" (from the app); the page is reachable from the local network only.

1. Install the package and enable the service

opkg install --force-architecture ./bgpcast-agent_<version>-1_<arch>_openwrt.ipk
/etc/init.d/bgpcast-agent enable
/etc/init.d/bgpcast-agent start

2. Open the settings page (LAN only)

http://<router-ip>:8080/

3. Fill in the fields and click "Save & apply"

API URL:      https://bgpcast.cc
Agent token:  <your-token>

4. Full BIRD2 config (bird.conf)

# bird.conf
log syslog all;
router id <router-id>;

protocol device {}

protocol kernel {
  ipv4 { export all; };
}

protocol bgp bgpcast {
  local port 1791 as <your-asn>;       # BIRD uses 1791, leaving TCP/179 for the agent
  neighbor 127.0.0.1 as <agent-asn>;   # the agent listens on 179
  ipv4 {
    import filter { gw = <next-hop>; accept; };
    export none;
  };
}

Architectures: aarch64, arm, mipsel, mips. The settings page has two fields — "API URL" (the route server address) and "Agent token" (from the app); the page is reachable from the local network only.

1. Set the environment variables

/container/envs/add list=ENV_BGPCAST key=BGPCAST_API_URL         value="https://bgpcast.cc"
/container/envs/add list=ENV_BGPCAST key=BGPCAST_AGENT_TOKEN      value="<your-token>"
/container/envs/add list=ENV_BGPCAST key=BGPCAST_AGENT_BGP_LISTEN value=":1790"

2. Add the registry and create the container

/container/config/set registry-url=https://ghcr.io tmpdir=disk1/tmp
/container/add remote-image=samfili/bgpcast-agent:latest \
    interface=veth-bgpcast root-dir=disk1/bgpcast envlist=ENV_BGPCAST name=bgpcast
/container/start bgpcast

3.1. Filter rules (next-hop + discard)

/routing filter rule
add chain=bgp_in comment="Nexthop" disabled=no rule="set gw <next-hop>; accept;"
add chain=discard disabled=no rule="reject;"

<next-hop> — the gateway to send the routes learned from the agent through.

3.2. BGP template

/routing bgp template
add as=<your-asn> disabled=no name=bgpcast output.network=bgp-networks .no-client-to-client-reflection=yes routing-table=main

3.3. BGP connection to the agent

/routing bgp connection
add as=<your-asn> cisco-vpls-nlri-len-fmt=auto-bits connect=yes disabled=no hold-time=4m input.filter=bgp_in instance=bgp-instance-bgpcast keepalive-time=1m listen=no \
    local.address=<bridge-address> .role=ebgp multihop=yes name=bgpcast-agent output.filter-chain=discard .network=bgp-networks .no-client-to-client-reflection=yes \
    remote.address=<container-address> .port=1790 .as=<agent-asn> routing-table=main templates=bgpcast vrf=main

<your-asn> = "Your ASN", <agent-asn> = "Agent ASN" — from the peer card in the app; <container-address> — the agent container's IP (port 1790); <bridge-address> — the bridge-docker address (the container's gateway); <next-hop> — the gateway for the routes. listen=no is required: RouterOS does not support listen=yes with a non-default port (1790) — the agent listens, the router only connects (connect=yes). The peer state in the app changes from "Waiting" only after the agent is peered with the router's local BGP (session established).

RouterOS v7: the container package, a disk, and veth/bridge.

Common issues

Session not coming up (Active/Connect): Check that <bgpcast-ip> is reachable and that outbound TCP/179 is not blocked by your firewall.
No established state, but port is open: Verify the ASN on both sides — they must match the parameters shown in the app.
Established, but 0 prefixes: Make sure you have subscribed to at least one category and that the peer is enabled in the app.
Session is flapping: A cloud peer requires multihop (TTL>1). Verify that multihop/ebgp-multihop is enabled.
Agent: session not coming up: Check the token on the :8080 LAN page and that outbound 443 (HTTPS/WSS) to bgpcast.cc is not blocked by a firewall.
Agent: BGP won't start / port 179 already in use: On Entware/OpenWrt the agent listens on TCP/179, and BIRD2 defaults to 179 too. Set `local port 1791 as <your-asn>;` in bird.conf so BIRD uses 1791 and leaves 179 for the agent.
Agent: :8080 page unreachable: The settings page is reachable only from your local network (LAN), not the internet. Open it from a device on the same network.
MikroTik: container won't start: Check that the disk (disk1) is present, the veth-bgpcast interface exists, and BGPCAST_AGENT_BGP_LISTEN is set (a high port, e.g. :1790).