Running agents on Raspberry Pi 5¶

Sipfront provides docker images for linux/arm64, so the Sipfront agent can be started on Raspberry Pi 4 and 5 (Raspi in short) with docker enabled using the usual docker run ... command.

The Sipfront Raspi image¶

Sipfront provides an optimized image for the Raspberry Pi 4 and 5. This image is based on the official Raspberry Pi OS image, and is optimized for:

• easily configuring the Sipfront agent pool during flashing of the SD cards without logging into the Raspi
• automatically starting the Sipfront agent on boot using the latest Sipfront agent docker image
• running the system on a read-only file system to prevent SD card corruption

Flashing the Sipfront Raspi image to an SD card¶

Download the image¶

You can find the latest Sipfront Raspi image here.

wget https://cdn.sipfront.com/sipfront-agent-rpi5-latest.img

Flash the image¶

We highly advise to use Balena Etcher to flash the image to your SD card. It is available for Windows, MacOS and Linux.

Select the image from file.¶

Select target SD card¶

Flash image to SD card¶

Wait for the flashing and verification to finish, then proceed to the configuration step.

Configure the agent pool on the SD card¶

Once the flashing is completed, you can configure the agent pool on the SD card without logging into the Raspi.

Locate the sipfront.txt config file¶

Check if the SD card is mounted. On MacOS, it will be mounted automatically, on Windows or Linux you might need to re-seat the SD card into the reader of your computer where you just flashed the card. The bootfs Volume will be mounted, where you can find the agent config file sipfront.txt

Edit the config file¶

Open the sipfront.txt file in a text editor and configure the agent pool using the information from your Agentpool Section, e.g.:

# the device will be accessible in your LAN via $AGENT_HOSTNAME.local
AGENT_HOSTNAME="sipfront-agent"

# fill in your Sipfront agent credentials
AGENT_POOL_ID="your-pool-id"
AGENT_POOL_SECRET="your-pool-secret"
AGENT_POOL_GROUP="raspi"

# fill in your WiFi credentials to enable wifi, otherwise keep empty
AGENT_WIFI_SSID="your-wifi-ssid"
AGENT_WIFI_PASSWORD="your-wifi-pass"

# set to no to disable mobile phone testing via bluetooth
AGENT_PHONE_DRIVER="no"

The AGENT_POOL_GROUP can be named individually, e.g. the name of the location you put the Raspi in, or the customer name where the Raspi is being placed.

Save the file and eject the SD card¶

Run the Raspi¶

1. Insert the SD card into the Raspi, connect the Raspi to power and network, and wait for the Raspi to boot up. It will take a couple of minutes for the agent to boot, pull the sipfront/agent:latest image and run it. Once it's up, it will show up as pool group in the Agentpool Section. This process is completely automated, so you don't have to do any manual steps. You could re-pack the Raspi with the inserted SD card and ship it to your customer, asking to plug it into their network.

2. If you really need to log in, you can SSH into the device with the user sipfront and the default password Sipfront!. Once logged in, switch the Raspi to read/write-mode by issuing the command rw, then change the password via the command passwd. Switch back to readonly-mode using the command ro.

3. You can use sudo -s to switch to root at any time.

Advanced configuration¶

You can set some advanced options in sipfront.txt to tune the agent behavior. The following options are available:

• AGENT_START_PORT: The ports allocated for SIP, RTP and other services. SIP/UDP and SIP/TCP will bind to AGENT_START_PORT, SIP/TLS to AGENT_START_PORT + 1, while RTP will use AGENT_START_PORT + 9 and upwards. The default is port 10000.
• AGENT_SKIP_IP_DISCOVERY: Set to yes to skip detecting the public ip address behind NAT, making the agent use its local ip address for SIP and RTP. This might be useful if the system under test is doing proper far-end NAT traversal, which might break if the agent advertises its public ip in the Contact/Via/SDP. The default is "no".
• AGENT_POOL_COUNT: The number of agents to start on the Raspi. This is useful if you want to run multiple agents on the same device, e.g. for testing internal calls within your PBX. Plan about 500MB of RAM per additional agent: a 4GB Raspi runs two or three agents comfortably, 8GB is advised beyond that. The first agent will start allocating ports at AGENT_START_PORT (see above), each further agent will start with an offset of 1000 ports from the previous agent. Thus, three agents will use 10000-10999, 11000-11999 and 12000-12999. The default is 1 agent.
• AGENT_POOL_IMAGE: The docker image to use. This is useful if you want to run a different agent image than the default one. The default is sipfront/agent:latest. Usually only used on request by Sipfront support.
• SF_AGENT_RUNTIME: The agent runtime the device announces to Sipfront. The runtime decides which kinds of test actions the scheduler will send to this agent (its capabilities): the regular runtime sipfront-agent handles SIP calls, DNS, traceroute, bandwidth and web checks, while sipfront-agent-mobile only handles real mobile phone calls through a phone paired via Bluetooth and is never given regular SIP work. The default is sipfront-agent, or sipfront-agent-mobile when AGENT_PHONE_DRIVER is set to yes, so you normally do not need to set this. Only override it on request by Sipfront support, for example together with a dedicated AGENT_POOL_IMAGE.
• AGENT_PROXY: The URL of an http(s) proxy (e.g. a Squid instance) to be used to tunnel all control traffic through (pulling the sipfront/agent docker image from dockerhub, connecting to the Sipfront backend and downloading configs and uploading artifacts in the AWS cloud). This can be helpful on strictly firewalled environments, where setting a proxy only requires you to open the proxy's ip in the firewall rules. The default is empty, so no proxy is used. Example usage is AGENT_PROXY="http://myproxy.com:80".