Configuring BGP with BIRD 2 on Equinix Metal

BIRD is an open source routing daemon for Unix-like systems. It can be used to establish Border Gateway Protocol (BGP) sessions between your servers and the Equinix Metal network. This is a guide for a minimum viable configuration to announce an IP address from your server via BGP.

At the end of this guide, you'll find a link to an Equinix Labs GitHub repository that contains some helpful scripts and tips automate this setup.

Getting Started

If you are configuring BGP for the first time, you'll need to follow the steps outlined in our Local BGP documentation to Enable BGP on the Project and Create Local BGP Sessions for the server you're configuring with BIRD.

You'll also need an IP address to advertise over BGP, though you don't need to assign it to a server in the Metal console. If you don't have one already, you can request an Elastic IP from Equinix Metal. See the Global Anycast IP Addresses documentation for more information about setting up a Global Elastic IP.

The rest of this guide will assume you have completed the above setup and have connected to your linux server with ssh or similar. This guide will use Ubuntu 24.04 as it's example OS. At the end of this guide, you'll find a shell script you could use to do all of the setup and configuration automatically assuming the above prerequisites are met.

Required Packages

This guide will need bird2 to complete the installation and make use of jq to query some of our server metadata. If you don't already have these packages installed, run:

apt -y update && apt -y install bird2 jq

Note: specified in this installation is bird2 and not bird. If you do not specify the number at the end, your package manager will likely install the older, version 1.x of BIRD. To verify which version you've installed, type bird --version at the terminal.

Update the Network Interface

First, we'll create a loopback interface and assign it the IP address we'd like to advertise to peers. You'll want to add it to /etc/network/interfaces to ensure persistence after a system restart. You can append it manually or copy and paste the below, replacing the IP after address with the IP you'd like to advertise.

cat <<EOF >> /etc/network/interfaces
auto lo:0
iface lo:0 inet static
  address 192.0.2.1
  netmask 255.255.255.255
EOF

Configuring BIRD

BIRD comes with a minimal configuration file, sufficient enough to start the daemon, but nothing else. We'll need to update this file with the information about our environment, but first, we'll need to gether that information which we can do using the Platform Equinix metadata service. Find more information in our BGP metadata documentation.

You can query all of this by hand and write a bespoke configuration file, but for the purposes of this guide, we're going to leverage a bit more advanced shell techniques to automate this a little bit.

Gathering Information

First, we're going to query the metadata service using curl, and filter to just the information we need with jq saving the output as the variables we need later:

json=$(curl -s https://metadata.platformequinix.com/metadata)
MY_PRIVATE_IP=$(echo $json | jq -r ".network.addresses[] | select(.public == false) | .address")
MY_PRIVATE_GW=$(echo $json | jq -r '.network.addresses[] | select(.public == false and .address_family == 4).gateway')
MY_PEER_1=$(echo $json | jq -r '.bgp_neighbors[0].peer_ips[0]')
MY_PEER_2=$(echo $json | jq -r '.bgp_neighbors[0].peer_ips[1]')
MY_ASN=$(echo $json | jq -r '.bgp_neighbors[0].peer_as')

Because all of our output has been set as variables, you may not see anything happen in the terminal. So if you want to test this, you can use something like echo $MY_ASN or echo $MY_PRIVATE_GW to ensure it was set.

Next, we'll need to save the global IP address we want to advertise over BGP as a variable as well. Replace 192.0.2.1 below with the Equinix Global Elastic IP or the one you brought with you:

ELASTIC_IP=192.0.2.1

Creating the BIRD config

Once BIRD is installed, its configuration file is found in /etc/bird/bird.conf and is sufficient to let the daemon start without error, but doesn't actually route anything. We're going to replace that file with the text in the command written below.

Run the following in the server's terminal:

cat << EOF > /etc/bird/bird.conf
# Create a filter to advertise only the Elastic IP we've chosen.
# This IP must be bound to the lo interface
filter equinix_bgp {
  if net = $ELASTIC_IP/32 then accept;
}

router id $MY_PRIVATE_IP;

# Add direct routes only on ipv4 on the lo interface
protocol direct {
  ipv4;
  interface "lo";
}

# Import routes from kernel
protocol kernel {
  scan time 20;
  ipv4 {
    import all;
    export all;
  };
}

# Static routes to reach peers via private Equinix network
# Peers always 169.254.255.1 & 169.254.255.2 on Equinix Metal
protocol static {
  ipv4;
  route $MY_PEER_1/32 via $MY_PRIVATE_GW;
  route $MY_PEER_2/32 via $MY_PRIVATE_GW;
}

# Check for interface up/down events
protocol device {
  scan time 10; # Scan interfaces every 10 seconds
}

# BGP advertisement to neighbors
# Neighbor ASN should always be 65530 on Equinix Metal
# edit password line and uncomment as needed
protocol bgp neighbor_v4_1 {
  local as 65000;
  neighbor $MY_PEER_1 as $MY_ASN;
  #password string;
  multihop 5;
  ipv4 {
    export filter equinix_bgp;
    import all;
  };
}

protocol bgp neighbor_v4_2 {
  local as 65000;
  multihop 5;
  neighbor $MY_PEER_2 as $MY_ASN;
  #password string;
  ipv4 {
    export filter equinix_bgp;
    import all;
  };
}
EOF

Ensure this has updated your bird.conf file properly by reading its contents with less, cat or similar:

less /etc/bird/bird.conf

Verify that this file looks similar to the text in the previous command, but of course with the variables we extracted from metadata in the proper places. If any of these is blank or doesn't contain the expected data, ensure that BGP is enabled in your Equinix project and on that device specifically for IPv4 then try repeat the steps above from Gathering Information.

Restart BIRD

Once your configuration has been checked, you'll need to restart the bird service for it to take effect.

systemctl restart bird

Confirming BGP

To confirm BGP sessions have been established, you can use the Update Now button and refresh the BGP tab of your server management page in the Equinix portal, or we can use the BIRD console on the server itself

Start the console with birdc and you should see a new BIRD console line where we can enter some commands:

bird>

Then you can use show protocols to view the protocols we just specified, and see whether the neighbor connections have been established. It should looks something like:

bird> show protocols
Name       Proto      Table      State  Since         Info
direct1    Direct     ---        up     20:19:06.003
kernel1    Kernel     master4    up     20:19:06.003
static1    Static     master4    up     20:19:06.003
device1    Device     ---        up     20:19:06.003
neighbor_v4_1 BGP        ---        up     20:19:10.579  Established
neighbor_v4_2 BGP        ---        up     20:19:10.700  Established
bird>

Your connections should now be established and your server is advertising the IP address specified at the beginning of this guide. You can test this through ping or any other method you might use to connect to this server.

Conclusion

Congratulations! You've setup your server to advertise a global IP over BGP through the Equinix network! If you'd like to do this in a more automated fashion, I've created a couple of scripts over in our Equinix Labs Organization on github you can download, modify or otherwise use to automatically setup and configure BIRD2 on your Equinix Metal devices.

Further Reading

• Monitoring BGP page
• Configuring BGP with FRR on an Equinix Metal Server
• BGP on Equinix Metal