How to: Install Coova Captive Portal on Ubuntu / Debian / Raspbian


In this How to we will be using Coova open source software, this project used to be called ”. This piece of powerful open-source software will allow you to create a (paid) captive portal. There are enough help documents that will help you further set-up your idea after following this guide.


A system running either Ubuntu, Debian or Raspbian. As it’s a personal project, I will use my raspberry pi with Raspbian to install and configure Coova. To keep this simple, I will just give you a summary:

  • As mentioned above, an operating system as Ubuntu, Debian or Raspbian. Other operating systems can be used, but please keep in mind the commands used might not work on your OS. So if needed, tweak them a bit for the corresponding OS.
  • Your operating system should be connected to the internet to install dependencies, files, updates etc.
  • Basic knowledge about Linux operating systems is recommended. You can use on of the cheatsheets on my website to take a look at the basic commands or look at the internet for other guides. Linux OS’s are great but you can break things easily!
  • As stated in the help documents, you need a RADIUS server (either locally or access to an instance) to get Coova working.
  • Time: 30 minutes – 1 hour will suffice!

Getting your OS ready

As we will edit files, you will need a file editing program. I will use ‘nano’:

sudo apt-get install nano

We will use git to clone the Captive Portal software. So install git with the command:

sudo apt-get install git

To make sure we all have the latest updates installed. Run:

sudo apt-get update
sudo apt-get upgrade

This will both update your Operating System and the installed software.


To make sure Coova will run without any problems, we will install the dependencies first. To do so, run the following commands:

sudo apt-get install -y -f haserl gengetopt devscripts bash-completion libtool libjson-c-dev libssl-dev autoconf automake

Installing those dependencies might take some time depending of the speed of your network and machine. Grab a cup of coffee or wait for a while. Once everything is done reboot your system using to make sure all the changes are applied:

sudo reboot now

Above is not a required step, but I find it a safe way to apply my new settings and see if everything is still working. Also optional: I ran the apt-get update & upgrade again after installing the dependencies. Some packages had updates available. Once done we continue to the next step.

Downloading and installing the Coova Project

To clone the project to your directory, use the command:

git clone

Coova Git Clone Citricks

Once cloned you can find a copy of Coova project in the working directory. Confirm you’re seeing the folder and move inside it. Then run:

sudo dpkg-buildpackage -us -uc

DPKG Build Coova

Once you run the command it will take some time until it’s finalised. On my Raspberry it took around 10 minutes to finalise. The screenshot shown above is only 1% of the total output it will show. After it’s done run the generated .deb file by using:

sudo dpkg -i coova-chilli_1.3.0_armhf.deb

Keep in mind that the command will only work for version 1.3.0. If you downloaded another version change the command shown above to its corresponding version. The command above took around a few minutes to complete.

Coova Installed

Coova is now installed!

You’ve now got a working Coova installation. To maximise the use of the software I can recommend to dive into the configuration settings and take a look around. There is so much to tweak!