FreeSwitch Java Manager (fs-manager-slim)

A lightweight Spring Boot sidecar service for managing FreeSwitch user directories and SIP user provisioning.

---

What This Does

This service acts as a management layer on top of a running FreeSwitch instance. It exposes a small REST API that handles:

• User provisioning — Creates new SIP users by writing entries directly into the FreeSwitch XML user directory (conf/directory/default/*.xml), then triggers a live reloadxml so changes take effect without restarting FreeSwitch
• User lookup — Queries the FreeSwitch Web API (mod_xml_rpc) to check whether a user already exists before attempting to create them
• SMS PIN delivery — After provisioning, sends an SMS PIN code to the user via an external SMS provider (sms.to)
• User directory listing — Returns all users currently defined in the XML directory file

The service is designed to run alongside FreeSwitch on the same host or within the same private network, with direct filesystem access to the FreeSwitch config directory.

---

Goals

• Provide a simple, deployable API to automate FreeSwitch user onboarding without manual XML editing
• Keep the service minimal — no database, no heavy framework overhead; FreeSwitch's own XML directory is the data store
• Enable integration with a frontend/mobile app that handles SIP registration and SMS-based authentication flows
• Auto-publish versioned JARs to GitHub Packages on every merge to main via CI

---

How to Run

Prerequisites

• Java 11+
• Maven 3.6+
• A running FreeSwitch instance with mod_xml_rpc enabled and accessible
• The service must have read/write access to the FreeSwitch XML directory file

Development

The development profile points to a local FreeSwitch instance at 127.0.0.1:8080.

mvn spring-boot:run

The app will start on port 34080 with the development profile active by default (application-development.yml).

You can override the directory path in application-development.yml:

freeswitch:
  user-directory-path: /usr/local/freeswitch/conf/directory/default/387.xml
  host: 127.0.0.1
  port: 8080
  webapi: http://${freeswitch.host}:${freeswitch.port}/webapi

Production

Set the following environment variables before running:

Variable	Description
SERVER_PORT	Port the service listens on
ACTIVE_PROFILE	Spring profile (production, defaults to development)
FS_USER_DIRECTORY_PATH	Absolute path to the FreeSwitch XML directory file
FS_HOST	FreeSwitch host
FS_HTTP_PORT	FreeSwitch HTTP API port (mod_xml_rpc)
FS_WEB_API_URL	Full base URL of the FreeSwitch Web API

export SERVER_PORT=8080
export ACTIVE_PROFILE=production
export FS_USER_DIRECTORY_PATH=/usr/local/freeswitch/conf/directory/default/users.xml
export FS_HOST=127.0.0.1
export FS_HTTP_PORT=8080
export FS_WEB_API_URL=http://127.0.0.1:8080/webapi

java -jar target/fs-manager-slim-*.jar

Build

mvn clean package -DskipTests

Published JARs are available on GitHub Packages.

---

API

POST /api/user-directory

Provisions a new SIP user (skips creation if the user already exists) and sends them an SMS PIN.

Request body:

{
  "userId": "1001",
  "displayName": "John Doe",
  "domain": "sip.example.com",
  "password": "secret",
  "smsPinCode": "4829"
}

GET /api/user-directory

Returns all users from the XML directory file.

---

Future Todos

Technical Improvements

• Add tests — unit tests for UserDirectoryRepository and SmsService, integration tests for the API endpoints; test dependencies (JUnit, Mockito, AssertJ) are already in the POM
• Move credentials to config — FreeSwitch Basic Auth credentials and the SMS API key should come from environment variables / application.yml, not be hardcoded
• Input validation — add @Valid and JSR-303 constraints on AuthenticationRequest fields (userId format, password length, etc.)
• Proper error handling — replace generic throws Exception with specific exceptions and a @RestControllerAdvice global handler returning structured error responses
• CORS hardening — replace the wildcard allowedOrigin("*") with explicit allowed origins from config
• Upgrade Spring Boot — track newer Spring Boot releases as they stabilize
• XML escaping — sanitize userId, displayName, and password before writing into XML to guard against malformed entries
• HTTP client reuse — HttpClient in SmsService should be a singleton bean, not instantiated per request
• Actuator health endpoint — add Spring Boot Actuator for /health and basic metrics

Features

• Multi-user-file support — currently targets a single XML file; support sharding users across multiple domain files
• User deletion — ability to remove a user entry from the directory and trigger reloadxml
• User update — change password or display name for an existing user
• Bulk provisioning — accept a list of users in a single request
• Audit log — persist a record of who was provisioned, when, and by whom
• Retry logic for SMS — handle transient SMS provider failures with a simple retry/backoff
• Webhook / callback — notify a caller when provisioning completes asynchronously
• Docker support — add a Dockerfile and docker-compose.yml for easier local setup alongside a FreeSwitch container