Using freeRouter on Proxmox

The software freeRouter is a total sleeper in the world of routing software, however don't be fooled by its unassuming looks! FreeRouter is a FOSS router that supports an astounding number of network protocols. I want to show you how to get started using this fantastic software, however, I don't want to go too deep into what freeRouter is, as the freeRouter website does a good job explaining it. Additionally, Nick Buraglio has written about the tool, has many example configs, and recently hosted a Software Gone Wild episode with the creator of freeRouter. If you aren't already up to speed with what freeRouter is, check out those links and come back here.

Okay, you're back? Good. Now that you are all aboard the freeRouter hype train, let's figure out how to get this beast up and running so we can use it—I ran into a few bumps getting it spun up, and the documentation is on the sparse side of things so I am documenting what worked for me in this post. To keep things simple, I just spun up a VM on my Proxmox host with a single network interface and turned that into a template that I can use to spin up multiple instances. Read along to find out how you too can have your own freeRouter!

Acquiring freeRouter

First things first, you need to get your hands on freeRouter. Since freeRouter is FOSS, it's easy to acquire, and the creator, Csaba Mate, has made it available in numerous ways, each having a few caveats. I started off by using the ISO, however, I ultimately changed away from the ISO as it doesn't have an installer as far as I can tell and seems to be intended for cloning to a disk using DD. If you do go down the route of using the ISO, be aware that when you save your config, (duh, Chris, it's presented as a CD-ROM) it doesn't seem to actually go anywhere even though it says it was saved. This will make for a nice surprise when you reboot the router and find that it's back to its default state.

Since the ISO didn't quite fit my needs, I was going to convert the ISO to a read/write .qcow2 image for Proxmox and just attach that to a VM, however, Csaba has already done that for us and provided a downloadable QEMU disk image (as well as other formats)! With your fresh QEMU disk in hand, you are ready to go and start configuring your base VM!

Creating a Basic freeRouter VM

The hardware requirements are very minimal, but one thing that tripped me up was that freeRouter expects a serial port and by default cannot work over a standard VGA-style display. Other than that one quirk, I was able to get the VM working with mostly default settings using the Proxmox "Create VM" wizard. Here are my initial settings after running the wizard:

Since the Proxmox new VM wizard doesn't let you create a VM without a disk, you can go ahead and delete the disk that was created automatically by clicking on the disk, clicking detach and then clicking remove. Now that the VM is initialized, we need to upload the freeRouter QEMU image to our Proxmox host and attach it to the VM. I downloaded the rtr.qcow2 image from here to my local machine and then sent it over to my Proxmox host with SCP.

scp ~/Downloads/rtr.qcow2 chris@cc-ls-pve01.cummings.tech:/tmp/

Once your image is on your Proxmox host, you need to attach it to your freeRouter VM using the qm command. The syntax is simple, it's qm importdisk <VM-ID> <Image Path> <Destination Datastore Name>. For my Proxmox setup, the specific incantation was qm importdisk 120 /tmp/rtr.qcow2 LocalStore.

Now that the disk has been imported, you can see it on the datastore you chose to import it to and you can also see it under the VM as an unused disk. To attach the disk to your VM, double click on it in your VM settings and Proxmox will present you with all of the options. You can leave these at default, however, I like to tick the discard box as that will let Proxmox reclaim unused space and keep your total size on disk as low as possible.

Click on add and you are all set! Go ahead and boot your VM and head over to the console and you should see freeRouter booting. If not, wait a bit then hit the enter key. You should see a prompt and start configuring your router like so:

Converting the VM to a Template

Congrats on making it this far! You could just use your shiny freeRouter VM and run with it, however, I plan on spinning up a few of these for testing, so I went ahead and converted mine into a template.

Before templatizing the VM, I added a few pieces of basic freeRouter config that I will always use. Here's the config I applied to my template that creates a management VRF, enables Telnet (still trying to figure out SSH), sets the hostname, and adds a default route:

hostname freertr-template
!
vrf definition mgmt
 description mgmt
 exit
!
interface ethernet1
 no description
 vrf forwarding mgmt
 no shutdown
 no log-link-change
 exit
!
ipv4 route mgmt 0.0.0.0 0.0.0.0 <gateway IP>
!
server telnet mgmt
 security protocol telnet
 no exec authorization
 no login authentication
 vrf mgmt
 exit
!
end

The CLI is pretty similar to Cisco IOS, so this was fairly familiar to me, however, make sure you check out Nick Buraglio's repository that has a simple lab topology if you would like to see more configuration examples. Once you have applied your base config, make sure to save it with a write mem.

With the config bits applied, all you need to do is shutdown your VM (I just halted it via Proxmox) and convert it to a template. Proxmox makes it easy:

Proxmox needs to think for a second as it converts your VM to a template, but once that is complete, just click the Clone button in the same menu and you will have a nice shiny VM with all of your settings preserved. You can of course do this as many times as you want (well, as long as you have enough resources on your Proxmox host).

Summary

Hopefully this has been a helpful guide to getting started with freeRouter! If you have any questions, just reach out to me on twitter and I will be glad to (try to) help you out!