ferrix/docs/content/docs/getting-started/quick-start.md

+++ title = "Quick Start" description = "Describes how to establish a BGP session between Ferrix and a test peer on a single host, and how to verify the routes that Ferrix accepts and rejects." weight = 3 +++

This procedure establishes a BGP session between Ferrix and a test peer over the loopback interface. The procedure requires no privileges and does not modify the kernel routing table.

The test peer, fake_peer, is a minimal BGP speaker included in the repository. It advertises the prefixes that you specify, displays every UPDATE message that it receives, and optionally advertises received routes back to Ferrix.

Before You Begin

Build Ferrix from source as described in Installing Ferrix. Run the commands in this procedure from the root of the repository.

Configuring Ferrix

The following configuration defines one neighbor, two originated routes, and the HTTP status interface:

{{ example(name="quick-start") }}

For a description of each statement, see the Configuration Reference.

1. Validate the configuration.

   cargo run -p bgp -- --check docs/examples/quick-start.textpb
   

   The daemon reports that the configuration is valid:

   docs/examples/quick-start.textpb is in order: AS64500, peers: 1, routes originated: 2
   

2. Start the daemon.

   cargo run -p bgp -- docs/examples/quick-start.textpb
   

   The daemon listens on 127.0.0.1:1790. It also attempts to connect to the neighbor on port 1791, where no peer is listening; these attempts fail until the test peer connects.

Establishing the Session

1. In a second terminal, start the test peer. The peer uses AS 65001, advertises 203.0.113.0/24, and with --echo advertises every route that it receives back to Ferrix.

   cargo run -p bgp-integration-tests --example fake_peer -- \
       --server 127.0.0.1:1790 --asn 65001 --announce 203.0.113.0/24 --echo
   

2. Verify that the session is established. The test peer displays output similar to the following:

   established with 127.0.0.1:1790 (AS64500 router-id 192.0.2.1)
   announced 203.0.113.0/24
   UPDATE 198.51.100.0/24 attrs=[Origin(IGP), AsPath(...[64500]...), NextHop(127.0.0.1)]
     echoed 198.51.100.0/24 back with path [65001, 64500]
   

   The peer received the route 198.51.100.0/24 from Ferrix and advertised it back with AS 65001 prepended.

Verifying Received Routes

1. Display the routes received for 203.0.113.0/24:

   curl -s '127.0.0.1:8080/api/routes/received?prefix=203.0.113.0/24'
   

   {"routes":[{"peer_name":"test-peer","prefix":"203.0.113.0/24","best":true,
     "summary":{"origin":"IGP","as_path":[65001],"next_hop":"10.0.0.2", ...}}]}
   

   Ferrix accepted the route and selected it as the best path.

2. Display the rejected routes:

   curl -s 127.0.0.1:8080/api/routes/rejected
   

   [{"peer":"test-peer","total":1,"by_reason":{"own AS in path":1},
     "recent":[{"prefix":"198.51.100.0/24","reason":"own AS in path","as_path":[65001,64500]}]}]
   

   Ferrix rejected the route that the peer advertised back, because its AS path contains the local AS number (64500). This is BGP loop detection.

The status page at http://127.0.0.1:8080/statusz displays the same information. Rejected routes are also counted in the bgp_routes_rejected_total metric at /metricz. For alerting rules based on this metric, see Monitoring Ferrix.

Next Steps

• BGP Neighbors
• Import Policy
• Configuration Examples