BuildInstallRun

From OpenBTS
Jump to: navigation, search

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.

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).

Openbts system diagram.png

System Prerequisites

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.

  1. Download Ubuntu Server 32-bit 12.04.4 LTS from here
  2. Boot the .iso on a fresh machine (VMWare virtual machines are also often used)
  3. Select "English" for language
  4. Press F4
  5. Select "Install a minimal system" from install type
  6. Select "Install Ubuntu Server" from main menu
  7. Select your language
  8. Select your country
  9. Use keyboard layout auto-detection or select the country and layout
  10. Enter a hostname
  11. Enter "openbts" for "full name for the new user"
  12. Enter "openbts" for "username for your account"
  13. Enter and confirm a password for the openbts account
  14. Select "no" to "Encrypt your home directory?"
  15. Select "Guided - Use Entire Disk" for "Partitioning method"
  16. Select/confirm the disk you'd like to use
  17. Select "yes" to "Write the changes to disks?"
  18. Enter nothing for "HTTP Proxy" and select continue
  19. Select "No automatic updates"
  20. Toggle OpenSSH on in "Software selection"
  21. Select "continue"
  22. Select "yes" to "Install the GRUB boot loader on a hard disk"
  23. Select "continue" to "Finish the installation"

Update Git

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

Required Libraries

To compile the various parts of OpenBTS (minus the PBX) you'll need the following additional libraries, packages, and utilities installed:

  • autoconf
  • libtool
  • libosip2
  • libortp
  • libusb-1.0
  • g++
  • sqlite3
  • libsqlite3-dev (sipauthserve only)
  • libreadline6-dev
  • libncurses5-dev

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:

  • Range Networks RAD1
  • Fairwaves UmTRX
  • Ettus Research USRP

Configuring OpenBTS

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.

/etc/OpenBTS/OpenBTS.db

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.

Running OpenBTS

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:

config

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.

Subscriber Registry

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

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

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.

Building Smqueue

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.

Configuring Smqueue

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.

Running Smqueue

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.

Yate is another SIP switch in active development. Instructions for interoperating with Yate are here. This is also supported by Berkeley and is buggy with less support than Asterisk.

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!

Data Service

If you wish to enable data service on your network, visit here.

Debugging OpenBTS

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.

Updating OpenBTS

Please see UpdateOpenBTS.


OpenBTS is a registered trademark of Range Networks, Inc.