The main objective of [RARE / FreeRouter 101] series is to help you getting started with FreeRouter from scratch without any prior knowledge.

Requirement

Basic Linux/Unix knowledge
Basic networking knowledge

Overview

freeRouter is a free, open source router control plane software. For nostalgic and old networkers (like me), freeRouter is able to handle HDLC, X25, frame-relay, ATM encapsulation. Since it handles packets itself at the socket layer, it is independent of underlying Operation System capabilities. We will see in the next articles how freeRouter subtlety leverage this inherently independence to connect different data-plane such as OpenFlow, P4 and other possible data-plane that would appear in the near future.

The command line tries to mimic the industry standards with one exception:

no global routing table: every routed interface must be in a virtual routing table
positive side effect: there are no vrf-awareness questions

Article objective

This article is meant to simply deploy 2 instances of freeRouter on the same fresh linux installed linux box. We are voluntary using freeRouter (freerouter.nop.hu) "raw" official repository in order to get familiar with the deployment manual process. Even if the deployment process is straightforward, it is not self explanatory for people non familiar with java/linux.

In order to simplify the deployment we have automated freeRouter daily builds on:

But let's get our "hand dirty" and follow the simple manual installation.

Diagram

[ #001 ] - Cookbook

Expand

title	Install your favorite operating system

In our example we will use a genuine debian stable image (buster) installed as a VirtualBox VM.

Expand

title	Get your system up to date

Start & connect your VM as root
Update your VM

Code Block

language	bash
theme	Midnight

apt-get update
apt-get upgrade

Install operating system default java package

Code Block

language	bash
theme	Midnight

apt-get install default-jre-headless

Expand

title	Install operating system java package

In this example, we won't recompile freeRouter so installing headless java runtime is enough. This set up is recommended for production environment in order to ensure minimal software footprint

Code Block

language	bash
theme	Midnight

apt-get install default-jre-headless --no-install-recommends

Expand

title	Create freeRouter environment

Let's create the following structure, even if some folder are empty for now:

Code Block

language	bash
theme	Midnight

mkdir -p ~/freeRouter/bin ~/freeRouter/lib ~/freeRouter/etc ~/freeRouter/log
cd ~/freeRouter/lib
wget http://freerouter.nop.hu/rtr.jar

so you have have the following environment:

Code Block

language	bash
theme	Midnight

╭─[11:11:54]floui@debian ~ 
╰─➤ tree freeRouter
freeRouter
├── bin   # binary files      
├── etc   # configuration files      
├── lib   # library files      
└── log   # log files

Expand

title	Create freeRouter configuration files for router: R1

FreeRouter uses 2 configuration files in order to run, let's write these configuration files for R1 in ~/freeRouter/etc

Code Block

language	bash
theme	Midnight
title	freeRouter hardware file: r1-hw.txt

int eth1 eth 0000.1111.0001 127.0.0.1 26011 127.0.0.1 26021
tcp2vrf 1123 v1 23

Code Block

language	bash
theme	Midnight
title	freeRouter software configuration file: r1-sw.txt

hostname r1
!
vrf definition v1
 exit
!
int eth1
desc r1@e1 -> r2@e1
vrf forwarding v1
 ipv4 address 1.1.1.1 255.255.255.252
 ipv6 address 1234::1 ffff:ffff:ffff:ffff::
 exit
!
server telnet tel
 security protocol telnet
 no exec authorization
 no login authentication
 vrf v1
 exit
!

Expand

title	Create freeRouter configuration files for router: R2

Repeat the same configuration for R2 in ~/freeRouter/etc

Code Block

language	bash
theme	Midnight
title	freeRouter hardware file: r2-hw.txt

int eth1 eth 0000.2222.0001 127.0.0.1 26021 127.0.0.1 26011
tcp2vrf 2223 v1 23

Code Block

language	bash
theme	Midnight
title	freeRouter software configuration file: r2-sw.txt

hostname r2
!
vrf definition v1
 exit
!
int eth1
desc r2@e1 -> r1@e1
vrf forwarding v1
 ipv4 address 1.1.1.2 255.255.255.252
 ipv6 address 1234::2 ffff:ffff:ffff:ffff::
 exit
!
server telnet tel
 security protocol telnet
 no exec authorization
 no login authentication
 vrf v1
 exit
!

Expand

title	Launch freeRouters R1 & R2

Code Block

language	bash
theme	Midnight
title	freeRrouter launch with blank parameters

╭─[12:58:45]floui@debian ~/freeRouter  
╰─➤  java -jar ./lib/rtr.jar 
java -jar ./lib/rtr.jar <parameters>
parameters:
  router <cfg>            - start router background
  routerc <cfg>           - start router with console
  routerw <cfg>           - start router with window
  routercw <cfg>          - start router with console and window
  routers <hwcfg> <swcfg> - start router from separate configs
  routera <swcfg>         - start router with sw config
  test <cmd>              - execute test command
  show <cmd>              - execute show command
  exec <cmd>              - execute exec command

Code Block

language	bash
theme	Midnight
title	R1 launch with supplied r1-hw.txt and r1-sw.txt with a console prompt

╭─[12:59:11]floui@debian ~/freeRouter  
╰─➤  java -jar lib/rtr.jar routersc etc/r1-hw.txt etc/r1-sw.txt 
info cfg.cfgInit.doInit:cfgInit.java:556 booting
info cfg.cfgInit.doInit:cfgInit.java:680 initializing hardware
info cfg.cfgInit.doInit:cfgInit.java:687 applying defaults
info cfg.cfgInit.doInit:cfgInit.java:695 applying configuration
info cfg.cfgInit.doInit:cfgInit.java:721 done
welcome
line ready
r1#

Code Block

language	bash
theme	Midnight
title	R2 launch with supplied r2-hw.txt and r2-sw.txt with a console prompt

╭─[12:58:52]floui@debian ~/freeRouter  
╰─➤  java -jar lib/rtr.jar routersc etc/r2-hw.txt etc/r2-sw.txt
info cfg.cfgInit.doInit:cfgInit.java:556 booting
info cfg.cfgInit.doInit:cfgInit.java:680 initializing hardware
info cfg.cfgInit.doInit:cfgInit.java:687 applying defaults
info cfg.cfgInit.doInit:cfgInit.java:695 applying configuration
info cfg.cfgInit.doInit:cfgInit.java:721 done
welcome
line ready
r2#

Verification

Expand

title	Check telnet access for R1@1123 and R2@2223

Code Block

language	bash
theme	Midnight
title	R1 telnet access from Virtualbox VM guest via port 1123

╭─[1:09:28]floui@debian ~  
╰─➤  telnet localhost 1123
Trying ::1...
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
welcome
line ready
r1#

Code Block

language	bash
theme	Midnight
title	R2 telnet access from Virtualbox VM guest via port 2223

╭─[1:15:37]floui@debian ~  
╰─➤  telnet localhost 2223                                                                                                                                           1 ↵
Trying ::1...
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
welcome
line ready
r2#

Expand

title	Check running-config for R1 and R2

Code Block

language	bash
theme	Midnight
title	R1 running configuration

r1#sh run                                                                      
hostname r1
buggy
!
!
vrf definition v1
 exit
!
interface ethernet1
 description r1@e1 -> r2@e1
 vrf forwarding v1
 ipv4 address 1.1.1.1 255.255.255.252
 ipv6 address 1234::1 ffff:ffff:ffff:ffff::
 no shutdown
 no log-link-change
 exit
!
!
!
!
!
!
!
!
!
!                  
!
!
!
!
server telnet tel
 security protocol telnet
 no exec authorization
 no login authentication
 vrf v1
 exit
!
!
end

r1#

Code Block

language	bash
theme	Midnight
title	Rr running configuration

r2#sh run                                                                      
hostname r2
buggy
!
!
vrf definition v1
 exit
!
interface ethernet1
 description r2@e1 -> r1@e1
 vrf forwarding v1
 ipv4 address 1.1.1.2 255.255.255.252
 ipv6 address 1234::2 ffff:ffff:ffff:ffff::
 no shutdown
 no log-link-change
 exit
!
!
!
!
!
!
!
!
!
!                  
!
!
!
!
server telnet tel
 security protocol telnet
 no exec authorization
 no login authentication
 vrf v1
 exit
!
!
end

r2#

Expand

title	Connectivity test between R1 and R2

Code Block

language	bash
theme	Midnight
title	Ping from R1 -> R2

r1#ping 1.1.1.2 /vrf v1                                                        
pinging 1.1.1.2, src=null, cnt=5, len=64, tim=1000, ttl=255, tos=0, sweep=false
!!!!!
result=100%, recv/sent/lost=5/5/0, rtt min/avg/max/total=1/2/3/13
r1#
r1#ping 1234::2 /vrf v1                                                        
pinging 1234::2, src=null, cnt=5, len=64, tim=1000, ttl=255, tos=0, sweep=false
!!!!!
result=100%, recv/sent/lost=5/5/0, rtt min/avg/max/total=1/4/11/23
r1#

Code Block

language	bash
theme	Midnight
title	Ping from R2 -> R1

r2#ping 1.1.1.1 /vrf v1                                                        
pinging 1.1.1.1, src=null, cnt=5, len=64, tim=1000, ttl=255, tos=0, sweep=false
!!!!!
result=100%, recv/sent/lost=5/5/0, rtt min/avg/max/total=0/1/2/12
r2#    
r2#ping 1234::1 /vrf v1                                                        
pinging 1234::1, src=null, cnt=5, len=64, tim=1000, ttl=255, tos=0, sweep=false
!!!!!
result=100%, recv/sent/lost=5/5/0, rtt min/avg/max/total=0/1/3/7
r2#

Code Block

language	bash
theme	Midnight
title	Initiate IPv4 telnet from R1 -> R2 (inside freeRouter scope)

r1#telnet 1.1.1.2 23 /vrf v1                                                   
 - connecting to 1.1.1.2 23

welcome
line ready
r2#

Code Block

language	bash
theme	Midnight
title	Initiate IPv6 telnet from R2 -> R1 (inside freeRouter scope)

r2#telnet 1234::1 /vrf v1                                                      
 - connecting to 1234::1 23

welcome
line ready
r1#

Conclusion

In this article you:

had a brief introduction of freeRouter networking swiiss-army knife
learn how to deploy 2 instances of freeRouter and interconect them via 2 UNIX sockets on a VM guest running on VirtualBox

Tip

title	(RARE-FreeRouter)-101 - [ #001 ] key take-away

FreeRouter is using UNIX socket in order to forward packet.

This is a key feature that will be leveraged to connect freeRouter control plane to any type of data-plane

In FreeRouter everything is in a VRF (so there is no global VRF)

This design choice has very positive consequences like: No VRF aware protocol,have multiple bgp processes (each bound to a different VRF)

freeRouter is dual stack

All the feature set is IPv4 and IPv6 compliant. So there is no compromised !

Blog

Versions Compared

Old Version 20

New Version 21

Key

Requirement

Overview

Article objective

Diagram

[ #001 ] - Cookbook

Verification

Conclusion

Blog

Page History

Versions Compared

Old Version 20

New Version 21

Key

Requirement

Overview

Article objective

Diagram

[ #001 ] - Cookbook

Verification

Conclusion