Skip to content

Legacy configuration guide

Jump to bottom Edit New page
Italo Cunha edited this page Jun 4, 2016 · 1 revision

Configuring your PEERING client

Configuring your PEERING client has two main steps: configuring the control plane and configuring the data plane. The control plane is set up by BGP sessions (usually) configured in the Quagga software router, and the data plane requires some fine-tuning of the Linux kernel to work correctly. Communication between your client and the PEERING BGP routers (also called muxes), for both the control and data planes) go through OpenVPN tunnels.

Before you can set up your PEERING client, it must have been approved by PEERING staff. This usually requires submitting a project proposal to the [email protected] mailing list and getting approval. Once approved, PEERING staff will provide you with a certificate to establish the OpenVPN tunnels with PEERING servers (make sure you have the certificates before you start), add your client to the data base of PEERING clients, and allocate you PEERING IP prefixes if your experiment needs them. Before you start, you will also need an updated database of PEERING muxes and prefix allocations.

Before you start, make sure you have received your certificates to set up OpenVPN tunnels. You will also need to download PEERING's SQLite3 database with current muxes and prefix allocations at the top of this page.

Setting up OpenVPN tunnels between your client and muxes

You will need OpenVPN installed (it is available in most distributions' repositories) and PEERING's current mux and client databases.

Run the openvpn/mkconfigs.py to generate OpenVPN tunnel configuration files. This script receives as input the sqlite3 data base you downloaded from the website. OpenVPN configuration files are named after mux nicknames (e.g., wisc.conf and gatech.conf). The easiest way to make these tunnels operational is to put them in /etc/openvpn, so they are automatically started during startup.

The configuration scripts above set up connections (tunnels) to PEERING muxes. Tunnel setup and teardown call the up.sh and down.sh scripts in openvpn/scripts. These scripts should be copied to /etc/openvpn/scripts.

Your certificate will go into /etc/openvpn/keys. The ca.crt file can be copied unchanged, but the other .crt, .key, and .csr files need to be renamed to client.crt, client.key, and client.csr before being moved to /etc/openvpn/keys (this is so we do not have to change the file names in the configuration files).

If you want to place files in different directories, you will need to edit the tunnel configuration files (or the template they are generated from).

Depending on the GNU/Linux distribution you are using, OpenVPN may be picky about file permissions. Change ownership (chown) for everything in /etc/openvpn to root and set permissions (chmod) for everything in /etc/openvpn/keys/ to 600.

In general, the OpenVPN setup goes like the following:

$ cd PATH_TO_REPOSITORY/openvpn
$ ./mkconfigs.py --db PATH_TO_DATABASE/tp.db
# cp -a scripts /etc/openvpn/scripts
# cp -a configs/* /etc/openvpn
# mkdir /etc/openvpn/keys
# cp PATH_TO_CERTIFICATE/ca.crt /etc/openvpn/keys
# cp PATH_TO_CERTIFICATE/NAME.crt /etc/openvpn/keys/client.crt
# cp PATH_TO_CERTIFICATE/NAME.csr /etc/openvpn/keys/client.csr
# cp PATH_TO_CERTIFICATE/NAME.key /etc/openvpn/keys/client.key
# chown -R root.root /etc/openvpn
# chmod 600 -R /etc/openvpn/keys
# /etc/init.d/openvpn start

Troubleshooting OpenVPN tunnels

Once established, OpenVPN tunnels show up as tun devices on your computer. You can list them using the ifconfig command. Please read up on the OpenVPN setup overview below to check if your tunnels seem configured correctly. At a minimum, you should be able to ping the muxes's end of each tunnel, with, e.g.,

$ ping 10.193.0.1

OpenVPN logs are stored at /tmp/openvpn-MUXNAME.log and /tmp/openvpn-up-down.log, these may contain relevant information.

A common source of OpenVPN connectivity problems is that our OpenVPN servers accept only one connection per client but our configuration above will bring OpenVPN tunnels up at boot time. If you install multiple clients using the same key, your clients will keep disconnecting each other from the server.

If everything seems configured correctly on your end, but OpenVPN tunnels are not up, please ask your PEERING contact whether your client is configured and enabled on PEERING muxes.

Setting up the control plane (Quagga)

The control plane is usually set up using Quagga. After installing Quagga (available in most distributions), copy the quagga/bgpd.conf.sample file into /etc/quagga/bgpd.conf, and make the following modifications:

  • Uncomment configuration for the muxes you want to connect to (the lines starting with 'neighbor').

  • Configure your router's ID in the line with bgp router-id; the router ID is usually it's local (public) IP address.

  • Please keep all prefix-list and route-map lines unmodified as they are used by the prefix-controller to control route announcements.

  • If you want, you can also change the password for connecting to your router (in the password line).

After your configuration file is ready, edit /etc/quagga/daemons and enable the BGPd daemon and edit the /etc/quagga/debian.conf file and enable vtysh.

Finally, run sudo /etc/init.d/quagga start to start the BGP daemon.

Checking the control plane

Establishing the BGP sessions requires that the OpenVPN tunnels are up. So please refer to the OpenVPN session. You can check if the BGP sessions are up (their state should be 'Established') by getting into Quagga's command prompt:

$ sudo vtysh -d bgpd

Then running:

> show ip bgp neighbors
> show ip bgp summary (for a shorter version of the above)

Once you (try to) make an announcement (see below), you can check what your router is effectively sending to PEERING routers with the following command:

> show ip bgp neighbor MUX_IP_ADDRESS advertised-routes

If your announcement is being sent to PEERING routers, you can check if it is propagating to the rest of the Internet at Looking Glass servers provided by network operators:

$ telnet route-server.ip.att.net
# login with rviews/rviews
> show route 184.164.240.0/24
# change the prefix according to what you announce

Enabling BGP debugging might be helpful in debugging BGP problems:

> debug bgp commands

Data plane setup

You should execute the commands in the data-plane/peering-data-plane.sh script during startup to set up routing on the data-plane in your Linux client. Options vary by distribution; on Debian and Ubuntu, one way to do this is to add peering-data-plane.sh's contents to /etc/rc.local. The data plane configuration script performs the following actions:

  • Add .1 IP addresses for all PEERING prefixes to the loopback interface so your client answers to pings and traceroute toward these addresses.

  • Source-route all packets from PEERING prefixes through the Wisconsin mux. Your client's default upstream (e.g., your university's network) may have ingress filters to prevent IP source address spoofing. This will prevent your client from sending packets with IP source addresses from PEERING prefixes through your university's network. If your client does not connect to the Wisconsin mux, please edit peering-data-plane.sh to choose a different mux.

  • Linux employs reverse path filtering by default (usually to prevent source address spoofing), which prevents ICMP echo replies to be sent out of an interface (Wisconsin's OpenVPN tunnel) different from the interface where the echo request was received. The peering-data-plane.sh script will disable reverse path filtering.

You can check the data plane by pinging the .1 address of prefixes you are announcing. Tracerouting to the .1 address should work and the route should go to one of the muxes you are announcing from.

Route control

The prefix-controller/ctrlpfx.py script allows you to easily control prefix announcements made from your client. It also serves as a good start point on how to change the default configuration file to control announcements.

You may need to fetch the prefix controller script as a submodule:

$ git submodule init
$ git submodule update

Acceptable use policies

Please take precautions to ensure the following:

  • Do not make announcements more frequently than once every 90 minutes. This is to avoid route flap dampening and complaints from network operators.

  • Do not make announcements with AS-paths longer than 6 ASes. Do not make announcements with AS-paths containing AS-sets larger th an 5 ASes. This is to prevent overloading or crashing routers.

  • Discuss with PEERING staff if your experiment uses more than 5Mbps of traffic. Special arrangements may be necessary as some PEERING muxes have limited bandwidth available.

Add a custom footer
Add a custom sidebar
Clone this wiki locally