1xBTS 1xBTS

Femtocell Setup

Use a compatible CDMA2000 femtocell as the radio for your 1xBTS network. The femtocell connects over Ethernet and provides coverage for your handsets. You do not need an SDR for this setup.

This guide uses Docker Compose on a Linux host on the same local network as the femtocell. The shared network core runs on that host. You can also add femtocells to an existing 1xBTS network alongside SDR cells.

Compatibility

Femtocell support is organized around device profiles. A profile selects the device’s provisioning, authentication, and voice handling. Being a CDMA2000 femtocell alone does not guarantee compatibility.

Device or profileWhat to expect
Airvana Airave 2.5Use airave-25-2x for 2.x firmware or airave-25-5x for 5.x firmware. Use the Airave instructions below.
Airvana Airave 2.5+Use airave-25plus. Service uses BC1 / 1900 MHz PCS. The 800 MHz radios are discovery beacons and do not support service for BC0-only phones.
Other CDMA2000 femtocellsstandard-xs0059 provides a generic starting point. Supply the provisioning settings and credentials required by your device. These models are not covered by the Airave compatibility claim.

Available services depend on the femtocell and handset. Configure 1x for calls, SMS, and 1x packet data, and enable a separate EV-DO carrier when your device supports it. MMS also requires the MMS service. A SIP trunk is required for calls to external phone numbers.

Before you start

You need:

  • A compatible femtocell (such as Airave 2.5).
  • A Linux host with Docker Compose and the 1xBTS build prerequisites.
  • The femtocell’s identity and its tunnel, provisioning, and SIP credentials. These must match the device. Arbitrary new passwords cannot replace credentials it already expects.
  • Control of the DNS resolver used by the femtocell before it establishes its tunnel.
  • A handset configured for your network’s identity, band, and channel.

Give the Linux host a fixed LAN address. The example below uses 192.168.1.50. Choose radio settings supported by the femtocell and your handset, and keep the radio disabled until you have reviewed them.

Configure bootstrap DNS outside Compose

The femtocell must find your security gateway (SeGW) before it can connect to 1xBTS. Configure its gateway hostnames in your router’s DNS server or another LAN resolver, with A records pointing to the Linux host’s LAN address.

RecordAddress
Each SeGW hostname configured in your device, including its backup gateway names192.168.1.50 in this example

Airave 2.5 DNS override

Configure *.femto.sprint.net → your SeGW host’s LAN address in the resolver used by the Airave. For this guide’s example host, the answer is 192.168.1.50. This covers the Airave’s segw* gateway names, including backups.

For a dnsmasq-based LAN resolver, the equivalent local configuration is:

address=/femto.sprint.net/192.168.1.50

Apply this to your LAN resolver, outside the Compose stack, and reload that resolver. Use a router’s domain override facility if it offers one. Other femtocells may use a different gateway domain.

Use the resolver’s local override or wildcard feature if the device uses a family of segw* names. A DNS wildcard is generally for an entire subdomain, not a partial label such as segw*. Otherwise add each hostname separately. Configure DHCP or the device’s network settings so it actually uses this resolver.

This step is out of band. Compose does not create these records in your LAN DNS. Editing the Linux host’s hosts file does not change what the femtocell resolves. The DNS supplied inside the tunnel cannot bootstrap that tunnel.

Verify each gateway name resolves to a SeGW address reachable from the femtocell, using the same resolver as the device. Ensure the IPsec ports, UDP 500 and 4500, are permitted by the host firewall and any firewall between the femtocell and the SeGW, whether they are on a local network or connecting remotely.

After connection, Compose supplies DNS inside the tunnel for the provisioning and SIP services. The default Airave names are fsmhdm.femto.spcsdns.net and fap.airave2.ims.spcsdns.net, resolving to the internal service address 10.56.0.2. These are different from the bootstrap SeGW records. For another device, set FEMTO_ACS_DOMAIN and FEMTO_SIP_DOMAIN in the Compose environment to match its service names, and configure the corresponding device profile.

Enable packet data

Configure the PDSN before adding a site. The femtocell requires it, and the site configuration uses the terminal-authentication secret generated here. Create or merge the following into config/pdsn.local.json:

{
"a10_bearer": {
"mode": "raw_gre",
"udp_bind_addr": null,
"udp_peer_addr": null
},
"a11": {
"bind_addr": "172.31.0.1:699",
"peer_addr": "0.0.0.0:0",
"framing": "bare"
},
"a11_security": {
"spi": 256,
"shared_secret_hex": "REPLACE_WITH_YOUR_HEX_KEY"
},
"a12": {
"radius_secret": "REPLACE_WITH_YOUR_TERM_AUTH_SECRET"
}
}

The null values remove UDP endpoints inherited from the base configuration. Raw GRE rejects configurations that still contain those endpoints.

Generate your own A11 key and terminal-authentication secret, running the command once for each:

Terminal window
openssl rand -hex 16

Set a11_security.shared_secret_hex to the first output and a12.radius_secret to the second. Keep the second value for term_auth_psk in the site configuration.

After changing the key, SPI, or terminal-authentication secret, restart the PDSN and femto-core, then use Sync femtocell. If you use a11_peers, each association needs a distinct SPI. Set packet.a11_spi in config/femto.local.json to select that association for provisioning. A software PCF must also use the key and SPI of its PDSN association.

Add a site

From your 1xBTS checkout, create config/femto.local.json. The checked-in config/femto.json supplies the service defaults and device profiles. The local file overrides them and holds your site’s credentials. Keep it private.

Each entry under sites associates one femtocell with its network identity and radio settings. Use a unique feid and cell_id for each device.

Airave 2.5 example

This example is a working Airave 2.5 configuration on 5.x firmware, serving 1x and EV-DO to Sprint handsets. It uses a Sprint SID and a Sprint EV-DO sector ID. Replace the identity and credential placeholders with values for your device. The bands, channels, and power levels are examples, not a recommendation for your hardware.

config/femto.local.json
{
"term_auth_psk": "REPLACE_WITH_YOUR_TERM_AUTH_SECRET",
"sites": {
"home": {
"feid": "0005B9AABBCC",
"profile": "airave-25-5x",
"name": "Home femtocell",
"cell": {
"mcc": "310",
"imsi_11_12": "00",
"cell_id": 403,
"sector": 0
},
"1x": {
"enabled": true,
"sid": 4107,
"nid": 65535,
"band_class": 1,
"channel": 50,
"pn_offset": 510,
"max_sector_power_dbm": -20
},
"evdo": {
"enabled": true,
"band_class": 1,
"channel": 75,
"cell_id": 1612,
"sector_id": "0x00840ac0000000000000000000000000",
"color_code": 58,
"tx_power": -9,
"pn_offset": 504
},
"acs": {
"username": "DEVICE_PROVISIONING_USERNAME",
"password": "DEVICE_PROVISIONING_PASSWORD"
},
"sip": { "password": "DEVICE_SIP_PASSWORD" },
"segw": {
"security_profile": "legacy",
"ike_group_key": "DEVICE_IKE_GROUP_KEY",
"eap_identity": "DEVICE_EAP_IDENTITY",
"eap_password": "DEVICE_EAP_PASSWORD"
}
}
}
}
SettingWhat you choose
term_auth_pskThe terminal-authentication secret generated in Enable packet data. It must match a12.radius_secret.
feidThe femtocell’s identity, matching its provisioning and tunnel credentials
profileA profile supported by that device
cellThe cell’s identity in 1xBTS. Keep mcc and imsi_11_12 as digit strings so leading zeroes are preserved.
1xWhether 1x is enabled, the handset’s network identity, band, channel, pilot offset, and transmit power
evdoWhether the data carrier is enabled, and its band, channel, sector ID, and color code
acs, sip, segwCredentials used for device provisioning, signaling, and the encrypted tunnel

The Airave profiles provision sip.password to the femtocell. Use a 10-digit number. Generate one with:

Terminal window
LC_ALL=C tr -dc '0-9' < /dev/urandom | head -c 10; echo

EV-DO settings

EV-DO is provisioned by the airave-25-5x profile only. The airave-25-2x and airave-25plus profiles do not provision EV-DO and ignore the evdo block. EV-DO runs on its own carrier, separate from 1x, and needs packet data configured before handsets can use it.

SettingWhat it sets
enabledWhether the EV-DO carrier transmits. When false, provisioning takes the EV-DO sector out of service.
band_class, channelThe EV-DO carrier frequency. Use a channel different from the 1x channel. The example uses PCS channel 75 beside 1x on channel 50.
sector_idThe 128-bit EV-DO sector ID, as a 0x-prefixed hex string. Carrier-branded handsets only use EV-DO whose sector ID matches their carrier.
color_codeThe EV-DO color code advertised with the sector
cell_idThe EV-DO cell identity on the femtocell
pn_offsetThe EV-DO pilot PN offset. The example keeps it apart from the 1x PN offset.
tx_powerEV-DO transmit power in dBm

An omitted value is not written, and the femtocell keeps its current setting. Changing the band, channel, or sector ID briefly takes the radio out of service while it is reprovisioned.

Verizon handsets. Verizon handsets need a Verizon SID and a Verizon EV-DO sector ID. A working Verizon site differs from the Sprint example in these settings:

"1x": { "sid": 2 },
"evdo": { "sector_id": "0x00800580000000000000000000000000" }

Keep the remaining 1x and evdo settings from the full example. A handset uses only the network its PRL accepts, so match the SID and sector ID to the carrier the handset is provisioned for.

For another device, select its profile and security settings. Certificate authentication uses security_profile: "standard" with fap_ca_cert, segw_cert, and segw_key paths accessible inside the containers. Mount the certificate files and private key before starting. The Airave’s legacy credentials and profile do not apply to other models.

Connect the shared core

If you already have a running core, add the femtocell management endpoint to its existing base-station list. For a femtocell-only network, create this local override:

config/msc.local.json
{
"base_stations": [
{
"id": "femto-fcs-1",
"management_endpoint": "http://127.0.0.1:17024"
}
],
"voice": { "voice_bearer_bind_ip": "172.31.0.1" }
}

Local override arrays replace the original arrays. Include your existing base stations if you want to keep them. The voice address above is the host’s address on the default femtocell Docker network, so audio can reach the femtocell through its tunnel.

Start the services

Start the supporting containers and femtocell services:

Terminal window
sudo modprobe fou ipip
docker compose --profile femto up -d --build
sudo docker/femto/host-route.sh add

The route command runs on the Linux host. Run it again after recreating the SeGW container. It installs the return routes needed to reach the femtocell and allows its packet-data traffic into the host. If the host firewall blocks Docker bridge traffic, also allow the containers to reach the host core on TCP ports 17017, 17019, 17020, 17021, and 17023. These ports do not need public access.

Build the shared core, then grant the PDSN CAP_NET_RAW to receive native GRE and CAP_NET_BIND_SERVICE to bind A11 on UDP port 699 (or run it as root):

Terminal window
cargo build --release -p cdma-nib --no-default-features
sudo setcap cap_net_raw,cap_net_bind_service+ep target/release/cdma-nib

Use this executable for both startup commands below. Reapply the capability after rebuilding. Keep fou-nat running for internet routing and DNS.

Wait until PostgreSQL is healthy in docker compose ps postgres. If your core is already running, use that instance instead of starting a second one.

Run the shared core without an SDR. In one terminal, start the subscriber, messaging, and event services:

Terminal window
target/release/cdma-nib --config-dir config \
--component cdma-hlr \
--component cdma-smsc \
--component cdma-events

Wait for the HLR and SMSC logs to report that their gRPC services are listening. Leave that terminal running. In a second terminal, start the packet and call services:

Terminal window
target/release/cdma-nib --config-dir config \
--component cdma-pdsn \
--component cdma-pcf \
--component cdma-msc

Start HLR before PDSN so EV-DO authentication can look up subscribers. If PDSN reports that MEID-to-IMSI lookup is disabled because HLR could not be reached, restart the second command after HLR is ready.

Power on the femtocell. Check the tunnel with:

Terminal window
docker compose logs --tail=100 femto-segw femto-core
docker compose exec femto-segw swanctl --list-sas

Check service in the dashboard

Open the dashboard on port 3000 of the Linux host. Select the femtocell from the cells list and check:

  1. ACS: Provisioned — the device received its configuration.
  2. SIP: Registered — the device connected for calls and messaging.
  3. GPS lock and timing — the device has the timing it needs to operate.
  4. Radio — the reported state matches what you requested.

Restart femto-core after changing the local configuration, then use Sync femtocell to apply it. Review the band, channel, and power before enabling the radio. Set 1x.enabled to true in the local site configuration for a persistent setting, then restart femto-core. The dashboard’s Enable femtocell and Disable femtocell actions request a radio state change. Wait for the device’s reported radio state to confirm it completed. Reboot femtocell reboots the device.

Add your handset in Subscribers with its IMSI and ESN or MEID, and the authentication credentials it requires. Configure its PRL or service settings to find the femtocell’s network. Confirm registration in Mobiles, then test a call and an SMS. Check the handset in Packet Sessions and test browsing. For MMS, follow the separate MMS guide.

CAVE authentication, OTASP A-key generation, voice privacy, and closed access have not been tested with femtocells. See Authentication & Voice Privacy for configuration and provisioning.

Airave 2.5 notes

  • Select airave-25-2x for 2.x firmware or airave-25-5x for 5.x firmware, and use the credentials expected by your Airave. Its legacy tunnel security is device-specific.
  • Connect the GPS antenna and allow time for GPS and timing lock. A connected tunnel alone does not mean the radio is operational.
  • The 1x transmit-power setting accepts no less than −30 dBm. A lower value is rejected by this device. Disable the radio rather than using an invalid power setting.
  • EV-DO uses its own carrier settings and requires airave-25-5x. Turning on 1x does not enable EV-DO.
  • Other models can have different DNS names, credentials, bands, power limits, and timing requirements.

Troubleshooting

What you seeWhat to check
No tunnelResolve every bootstrap SeGW name using the femtocell’s LAN DNS. Check UDP 500/4500 and tunnel credentials.
Tunnel connected, ACS pendingDevice’s provisioning hostname, provisioning credentials, and selected profile
ACS provisioned, SIP not registeredSIP credentials, realm, and device’s SIP service hostname
Device online, radio unavailableConfigured site, enabled setting, supported channel and power, GPS/timing status
Radio operational, handset absentSubscriber identity and authentication, handset PRL, band, channel, SID/NID
Call connects without audioHost route and voice_bearer_bind_ip; do not advertise loopback to the femtocell
Data failsPDSN address, matching A11 key/SPI, CAP_NET_RAW, host route, and fou-nat

Next steps

Esc