Blog post

Introducing the Sendium Kannel Migration Converter

Table of Contents

The Sendium Kannel Migration Converter helps teams running Kannel evaluate Sendium using their existing configurations. This free, browser-based Kannel Migration Converter generates starter files for HTTP credentials, SMPP connections, and SMS routing rules. Paste a kannel.conf into the browser tool and it generates starter files for HTTP credentials, SMPP connections, and supported routing rules. It also flags settings that need a closer look. The conversion runs locally in your browser. Try the Kannel Migration Converter

In our earlier article on Kannel compatibility, we looked at why keeping a familiar HTTP interface can make it easier to evaluate a new gateway. The converter makes that idea tangible. Here’s what it generates from a small configuration, including how it translates allowed-smsc-id and how an existing /sendsms client can exercise that route. Kannel compatibility in Sendium

A small configuration to try in the converter

Take a small, sanitized slice of your Kannel configuration. This example has an HTTP user called legacy-http-user and an SMPP connection called upstream-a. The connection’s allowed-smsc-id includes the selector upstream-a. We’ll use that same selector in the test request so it’s easy to trace from the input file to the outbound connection.

group = sendsms-user
username = legacy-http-user
password = example-http-password
group = smsc
smsc = smpp
smsc-id = upstream-a
host = smpp.provider.example
port = 2775
smsc-username = example-smpp-user
smsc-password = example-smpp-password
transceiver-mode = true
allowed-smsc-id = upstream-a
This is an excerpt for the converter. The provider address and credentials are placeholders. For the staging test, use a test SMPP connection and a sender and recipient approved for that connection.

What the Kannel Migration Converter Generates

Open the converter, paste the example into the kannel.conf input, and review the generated files and diagnostics. Conversion runs locally in the browser. You’ll use three files for this walkthrough. Open the Kannel migration converter

Generated File
What to Check
credentials.yml

The HTTP credential uses legacy-http-user. This is the username the application supplies to /sendsms.

smsg.properties

The SMPP worker is named upstreamA. This is where you review the provider host, port, bind credentials, and connection mode.

routingTable.conf

A selector rule matches upstream-a and routes the message to upstreamA. The file also includes a default route for the example.

Treat these as starter files. Compare them with your staging configuration before applying them, especially if you already have provider connections or routing rules there. Review the diagnostics alongside the output. For allowed-smsc-id, the diagnostic calls out request-level selector precedence, fallback behavior, and any legacy allow policy you still need to account for. Converter documentation

 Configuration review and testing are also important considerations for modern SMS infrastructure, as discussed in our article on the future of open-source SMS gateways.

How the converter handles allowed-smsc-id​

Find this line in routingTable.conf:

upstreamA:message_center:equals:upstream-a

Read it from left to right. upstreamA is the destination worker. The rule checks the message’s message_center field for the exact value upstream-a. The Kannel-compatible HTTP endpoint sets that field from the request’s smsc query parameter, so a request with smsc=upstream-a supplies the value the rule expects.

 

The distinction matters when you move beyond this example. Kannel places allowed-smsc-id on the SMSC block. The converter expresses that setting as a Sendium route match. What happens to a different selector depends on the rest of the routing table. If your existing setup restricts where particular requests may go, include those cases in staging and check how unmatched selectors are handled. Sendium routing guide · Converter routing notes

Replay a Kannel-compatible request in staging

Load the reviewed files into a staging Sendium instance and confirm that the SMPP worker can bind to the test provider. A bind gives you a connection to test. The next step verifies the full path from the application’s HTTP credential to an outbound SMPP submission.

Start with a request your application already makes to Kannel. For the first staging test, point it at Sendium’s /sendsms endpoint and use the HTTP user from the converted configuration. This example assumes Sendium listens on local port 8080. Set SENDIUM_HTTP_PASSWORD to the password in the staged HTTP credential, and set TEST_SENDER and TEST_RECIPIENT to values accepted by the test provider. The request passes smsc=upstream-a, which supplies the selector from the generated routing rule.

 

curl -i -G ‘http://127.0.0.1:8080/sendsms’ \

  –data-urlencode ‘username=legacy-http-user’ \

  –data-urlencode “password=${SENDIUM_HTTP_PASSWORD}” \

  –data-urlencode “from=${TEST_SENDER}” \

  –data-urlencode “to=${TEST_RECIPIENT}” \

  –data-urlencode ‘text=Sendium migration test’ \

  –data-urlencode ‘smsc=upstream-a’

 

Look for 202 Accepted and save the gateway UUID returned as plain text. The HTTP response confirms that Sendium admitted the request. In staging, set message.trace.mode = all to see the routing target in the message.routed log, then check the SMPP provider or simulator for the corresponding submit_sm. The provider response tells you whether it accepted the submission. Handset delivery is a later outcome. Kannel-compatible HTTP API · Troubleshooting guide

Understanding the complete message path is essential when troubleshooting SMS delivery. Our guide to SMS gateway observability explores the signals operators should monitor.

Verify that the selector changes the route

With one provider, both the selector rule and the generated default route point to upstreamA. A successful submission verifies the outbound path. To verify that the selector changes where the message goes, configure a second test worker in staging and point the default rule to that worker. Keep the message_center rule above the default in the [MESSAGE] table.

Staging request
Expected routing target
smsc=upstream-a

The upstreamA worker

No smsc parameter

The second worker

An unfamiliar smsc value

The second worker, with this catch-all rule

For a broader discussion of routing behavior when a preferred path becomes unavailable, see our article on SMS fallback routing.

Keep the sender, recipient, and message the same across the three requests. Compare the routing target logged for each returned UUID. The last row is especially useful if the legacy deployment depended on a strict allow policy. It makes the behavior of the generated catch-all explicit and gives you a concrete case to include in your cutover checks. Sendium routing guide

Use those three results as a small acceptance test for the migration. Record the selector sent by the client, the expected worker, the observed worker, and the provider response for each case. If a selector reaches the fallback worker unexpectedly, start with the generated rule’s value and its position in the routing table. If the selected worker is correct but the submission fails, look at that worker’s bind and the provider’s response. Each result tells you where to look next.

Try the converter with your own configuration

Once you’ve successfully tested your first route with the Sendium Kannel Migration Converter, repeat the process with a second provider or application. Use selectors your applications actually send and include a request with no selector, so you can check the default behavior explicitly. If an application depends on delivery receipts or inbound SMS, test those flows in staging before moving its traffic.

Start by bringing one sanitized configuration to the converter. Review what it generates, pick one route you can verify end to end, and use that result to decide what to migrate next. Kannel migration converter · Sendium deployment guide

Latest News