This document describes the installation of a single instance of OpenBTS on a single PC with a single radio. These instructions are admittedly focused around a very specific collection of hardware and software, namely those that are used in the products that Range Networks ships. We are working to change this so instructions are provided for a wide variety of Linux distributions and architectures as well as for SDR hardware from different vendors. This default configurations support this setup, and it's the right place to start. For a multi-BTS environment, see this page.
This document details installation from top-of-tree, with all of the latest community changes. If you are updating OpenBTS, please see UpdateOpenBTS. If you want to install OpenBTS using debian packages, please see DebOpenBTS.
- 1 Building, Installing and Running OpenBTS
- 2 Build and Install the Subscriber Registry and Sipauthserve
- 3 Build and Install Smqueue
- 4 Selecting and Configuring a PBX
Building, Installing and Running OpenBTS
A complete installation of OpenBTS comprises these components:
- OpenBTS itself. This is the GSM implementation from the TDMA part of L1 up through L3 and the L3/L4 boundary. Its SIP interface is normally on port 5062. This is located in openbts/trunk.
- Transceiver. This is the software radiomodem, implementing the lower part of L1. OpenBTS starts the transceiver automatically. These are located in openbts/trunk/Transceiver*.
- A SIP PBX or softswitch (Asterisk, FeeeSWITCH, etc.) This component connects speech calls. Its SIP interface is normally on port 5060. This is not packaged with OpenBTS.
- Sipauthserver. This is the SIP registration and authorization server, used to process location updating requests from OpenBTS and perform corresponding updates in the subscriber registry database. Its SIP interface normally runs on port 5064. This is located in subscriberRegistry/trunk.
- Smqueue. This is the store-and-forward text messaging server. It needs to be started independently of OpenBTS. Its SIP interface is normally run on port 5063. Smqueue is not required in installations that do not support text messaging. This is located in smqueue/trunk.
- Rrlpserver. This is the RRLP aiding server and it is run as a CGI script in a web server. Rrlpserver is not required if RRLP is not being used. This is located in RRLP/trunk.
In this diagram, Black links are network connections (SIP). Red links are file system connections (sqlite3 lookups). Blue links are ODBC (network/local DB lookups).
Several prerequisites are required before your system will be capable of building, installing, and running OpenBTS.
Ubuntu 12.04 i386
If you're already running Ubuntu Desktop or Server 32-bit 12.04, you can skip this section.
- Download Ubuntu Server 32-bit 12.04.4 LTS from here
- Boot the .iso on a fresh machine (VMWare virtual machines are also often used)
- Select "English" for language
- Press F4
- Select "Install a minimal system" from install type
- Select "Install Ubuntu Server" from main menu
- Select your language
- Select your country
- Use keyboard layout auto-detection or select the country and layout
- Enter a hostname
- Enter "openbts" for "full name for the new user"
- Enter "openbts" for "username for your account"
- Enter and confirm a password for the openbts account
- Select "no" to "Encrypt your home directory?"
- Select "Guided - Use Entire Disk" for "Partitioning method"
- Select/confirm the disk you'd like to use
- Select "yes" to "Write the changes to disks?"
- Enter nothing for "HTTP Proxy" and select continue
- Select "No automatic updates"
- Toggle OpenSSH on in "Software selection"
- Select "continue"
- Select "yes" to "Install the GRUB boot loader on a hard disk"
- Select "continue" to "Finish the installation"
The OpenBTS project utilizes several new features in Git. To make sure your client is compatible (e.g. newer than 1.8.2), perform the following.
$ sudo apt-get install software-properties-common python-software-properties $ sudo add-apt-repository ppa:git-core/ppa (press enter to continue) $ sudo apt-get update $ sudo apt-get install git
Once you have git installed, most of the remaining installation process is automated via scripts.
Getting the Code
From the command line in your fresh development environment, execute the following to download the most recent set of tools:
$ git clone https://github.com/RangeNetworks/dev.git
Before proceeding, these tools require that you are using a modern version of Git (>1.8.2). If you followed the instructions above in Git setup prerequisites, you should be good to go. Check now if you are:
$ git --version git version 1.9.1
These development scripts assume that you have SSH keys set up for GitHub. If you do not, please follow these instructions to set them up before proceeding. Now, to download all of the components simply run the clone.sh script.
$ cd dev $ ./clone.sh
Selecting a Branch or Tag
Before building, you should choose which branch or tag you'd like to compile using switchto.sh.
$ ./switchto.sh master (or) $ ./switchto.sh 4.0 (or) $ ./switchto.sh v4.0.0
To compile the various parts of OpenBTS (minus the PBX) you'll need the following additional libraries, packages, and utilities installed:
- libsqlite3-dev (sipauthserve only)
These can be installed (on a Debian-flavored unix distro) with the following command:
sudo apt-get install autoconf libtool libosip2-dev libortp-dev libusb-1.0-0-dev g++ sqlite3 libsqlite3-dev erlang libreadline6-dev libncurses5-dev
You will also need to install liba53, which is included with the distribution. The following commands should install it correctly from the OPENBTS_ROOT
cd a53/trunk sudo make install
Building the Code
The build.sh script will automatically install any build dependencies (building them manually when required). After dependencies are taken care of, each component is compiled into an installable package.
$ ./build.sh radio-type (component-name)
Compiled packages are now in a new directory named BUILDS/sometimestamp.
Build and Install the Transceiver
OpenBTS can be run on variety of hardware devices. You must first note the specific hardware being used. There are currently three distinct types:
With OpenBTS built, you now need to configure it to run correctly. There are a two key files that must be created for this to happen.
OpenBTS.db is the database store for all OpenBTS configuration. It must be installed at /etc/OpenBTS, which likely does not exist. So, to create this file:
(from the OpenBTS directory) sudo mkdir /etc/OpenBTS sudo sqlite3 -init ./apps/OpenBTS.example.sql /etc/OpenBTS/OpenBTS.db ".quit"
Test this by running:
sqlite3 /etc/OpenBTS/OpenBTS.db .dump
If you see a lot of configuration variables, the DB has been installed correctly.
At this point, we should be able to perform a basic sanity check of OpenBTS.
(from OpenBTS root) cd apps sudo ./OpenBTS
You should see output like this:
system ready use the OpenBTSCLI utility to access CLI
And if you scan for GSM towers on your phone, you should see a 00101 (test) network. If you try to attach, it will reject you. This is because OpenBTS, by default, only allows registered handsets to connect. As we are not running our registration server (sipauthserve) no phones will camp. From here, we should look at a few OpenBTS configuration variables. Connect to OpenBTS with the OpenBTSCLI command:
(from OpenBTS root) cd apps sudo ./OpenBTSCLI
The OpenBTSCLI has several commands that can be used to interact with the software. From within the CLI, execute:
You will see a lot of stock configuration options. You can find these listed on the OpenBTSConfig listing page. Most of these only need to be tweaked if you are moving beyond a simple desktop setup. However, a few are required for basic operation. These are:
- GSM.Radio.Band - Set this to the GSM band appropriate for your hardware.
- GSM.Radio.C0 - This is the ARFCN. Set it to something appropriate for your band.
- Control.LUR.OpenRegistration - Set this to a regular expression matching the IMSIs of your test phones. This tells OpenBTS to not reject your handset just because your registration server (below) isn't responding. Useful for debugging and initializing the system.
The values can be modified from OpenBTSCLI with the config command. For example,
config Control.LUR.OpenRegistration .*
to allow registrations from any phone regardless of their provider. Caution: With this config all phones have access, without any restriction. When an antenna is attached, at least your neighbors will connect, so do not try this at home :-)
If these steps are complete, you have a working BTS. If they do not, check out the common errors.
You also need a home location registrar (sipauthserve), short message service center (smqueue) and switch (PBX) in order to register, send and receive sms, and send and receive calls. Those steps are below.
Build and Install the Subscriber Registry and Sipauthserve
OpenBTS depends on the installation of Sipauthserver the SIP authorization server for registration traffic. You will not be able to have a usable system without it.
To setup the Subscriber Registry database you must first create the file path the db will reside in. By default, this is /var/lib/asterisk/sqlite3dir.
sudo mkdir -p /var/lib/asterisk/sqlite3dir
Sipauthserve is an aptly-named daemon providing SIP authentication services. The SIP.Proxy.Registration config variable in openbts should point to its hostname and port.
To build Sipauthserve:
(from svn root) cd subscriberRegistry/trunk make
This will produce a sipauthserve executable.
As with OpenBTS, you'll need to configure sipauthserve. We assume /etc/OpenBTS/ already exists.
(from subscriberRegistry root) sudo sqlite3 -init subscriberRegistry.example.sql /etc/OpenBTS/sipauthserve.db ".quit"
Running sipauthserve will provide you with a registration server. To do so:
(from subscriberRegistry root) sudo ./sipauthserve
sipauthserve does not have a CLI, so you'll only see a small output:
ALERT 139639310980928 sipauthserve.cpp:214:main: ./sipauthserve (re)starting
Remember, if you change any of the config variables, you'll need to restart sipauthserve for the changes to take effect.
Build and Install Smqueue
Smqueue is the store-and-forward message service packaged with OpenBTS. Building and running is very similar to the process used for OpenBTS.
In the smqueue/trunk directory, run the following commands:
autoreconf -i ./configure make
You should now have an smqueue executable in the smqueue/trunk/smqueue directory.
Similar to OpenBTS, Smqueue also depends on a configuration file, located at /etc/OpenBTS/smqueue.db. Smqueue creates an empty, nonfunctional version of this db if it is not available. That's of no use. Instead, do as we did with OpenBTS and run the following command:
(from the smqueue directory) sudo sqlite3 -init smqueue/smqueue.example.sql /etc/OpenBTS/smqueue.db ".quit"
That will initialize /etc/OpenBTS/smqueue.db with default values. These configuration variables should work without modification, and are listed here.
Smqueue is run with the following command:
(from the smqueue directory) cd smqueue sudo ./smqueue
Smqueue does not have a command-line interface, instead just reading configuration values and processing messages. So you'll only see a small output:
ALERT 140545832068928 smqueue.cpp:2421:main: smqueue (re)starting smqueue logs to syslogd facility LOCAL7, so there's not much to see here
Remember, if you change any of the variables, you'll need to restart smqueue for the changes to take effect.
Selecting and Configuring a PBX
There are three primary open-source PBX/Soft switches available. These are Asterisk, FreeSwitch and yate. The differences, tradeoffs, and advantages to using one system over the other are too numerous and outside the scope of this document. However, the key point is that all are actively supported and used by the OpenBTS community.
Asterisk is the "standard" OpenBTS PBX and is shipped in the commercial units. It's the easiest to set up, and most documented option. However, it's probably the most difficult. Please see the steps for installing and configuring Asterisk to work with OpenBTS.
FreeSwitch is an up-and-coming Asterisk competitor. Its interoperation with OpenBTS is supported primarily by the group at Berkeley. It provides programmatic voice and text routing, as well as a more flexible programming environment for voice/sms applications at the cost of being buggier and having less support. The steps for installing and configuring FreeSwitch to work with OpenBTS are documented here.
Running It All
Use one of the startup scripts or run each individual executable in a separate terminal/window. Each component has an Upstart service definition for Ubuntu. To start all the required services, execute the following:
$ sudo start sipauthserve $ sudo start smqueue $ sudo start openbts $ sudo start asterisk
Conversely, to stop them:
$ sudo stop sipauthserve $ sudo stop smqueue $ sudo stop openbts $ sudo stop asterisk
Then turn on a phone with a GSM SIM card installed. It would be best if this SIM was NOT from a local carrier; then the phone will not immediately camp to one of their towers in the area. In most cases, on most phones, there is a way to select the specific network you wish to attach to. For this basic install, the network will be announced as: 001 01. Connect to that network. Your BTS should reply, allowing the phone to associate. If this fails, make sure you set the Control.LUR.OpenRegistration variable in OpenBTS.db.
With these two tests passed, you can now test the voice connection. Call 600 from the phone (9196 with FreeSWITCH) to call the "echo" service. If that's working, congrats!
Lastly, we can test SMS support. Send an SMS to 101 with a 7-10 digit number (configurable in smqueue). That is now your new number in the system. Do this with a second phone/SIM and then text between them. If this is working, congrats, your SMS services are working as well!
If you wish to enable data service on your network, visit here.
By default OpenBTS logs to syslogd. As such, you can see all openbts traffic with the following command:
tail -f /var/log/syslog | grep OpenBTS
If you're seeing problems, check here for any glaring issues (Probably ALARM/ERR). You can similarly look for issues with sipauthserve and smqueue.
Please see UpdateOpenBTS.
OpenBTS is a registered trademark of Range Networks, Inc.