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.

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.

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.

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

Replace the identity and credential placeholders with values for your device. The band and channel are examples, not a recommendation for your hardware. This example leaves the radio disabled and EV-DO off.

{
  "sites": {
    "home": {
      "feid": "0005B9AABBCC",
      "profile": "airave-25-2x",
      "name": "Home femtocell",
      "cell": {
        "mcc": "310",
        "imsi_11_12": "00",
        "cell_id": 403,
        "sector": 0
      },
      "1x": {
        "enabled": false,
        "sid": 22,
        "nid": 65535,
        "band_class": 1,
        "channel": 50,
        "pn_offset": 0,
        "max_sector_power_dbm": -30
      },
      "evdo": { "enabled": false },
      "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"
      }
    }
  }
}

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:

{
  "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:

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:

cargo build --release -p cdma-nib --no-default-features

For packet data, configure and grant the PDSN’s required privileges first, as described below. 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:

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:

target/release/cdma-nib --config-dir config \
  --component cdma-pdsn \
  --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:

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 before adding data services.

Enable packet data

Femtocell packet data needs additional PDSN configuration. 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"
  }
}

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:

openssl rand -hex 16

Set a11_security.shared_secret_hex to the output. With airave-25-5x, provisioning copies the key and SPI to the femtocell’s 1x and EV-DO settings.

After changing the key or SPI, 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.

The PDSN needs CAP_NET_RAW to receive native GRE and CAP_NET_BIND_SERVICE to bind A11 on UDP port 699 (or run it as root). Build the core first, then grant the capability to the executable you run:

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 above. Reapply the capability after rebuilding. Keep fou-nat running for internet routing and DNS.

For EV-DO, configure the site’s evdo settings and enable that carrier. Match the femtocell’s terminal-authentication server address and shared secret with the PDSN’s a12 settings. For the Airave 5.x profile, set a top-level term_auth_psk in config/femto.local.json and set a12.radius_secret in config/pdsn.local.json to the same value. The provisioning service sends this secret to the femtocell. Do not leave the PDSN secret empty while the device retains a different one. Handset data credentials must also match the network’s authentication policy. The supplied packet-core defaults permit some unverified authentication, so review them before using the network beyond your own devices.

Check the handset in Packet Sessions and test browsing. For MMS, follow the separate MMS guide.

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. Turning on 1x does not enable EV-DO.
• Other models can have different DNS names, credentials, bands, power limits, and timing requirements.

Troubleshooting

Next steps

• Voice Calls
• SMS
• Packet Data Setup
• Multiple Base Stations