Configuration Reference

The SMS Gateway Proxy uses two configuration files:

1. config_local.yaml — main application configuration (server, security, infrastructure connections, rate limiters, MCP filters, monitoring)
2. smpp_rules.toml — SMPP link and pool definitions (connections to SMSCs, rate limits, routing)

Application Configuration — config_local.yaml

This is the primary configuration file that controls the behavior of the proxy application. It is located next to the proxy binary or mounted as a volume in Docker.

General Settings

env: "production"          # Environment name: local, dev, staging, production
log_level: "info"          # Log verbosity: trace, debug, info, warn, error, fatal, panic
server_name: "proxy-01"    # Unique identifier for this proxy instance
storage_path: "./storage/sso.db"  # Path to the local SQLite database (user accounts)
customer: "acme-corp"      # Customer identifier for licensing
instance_id: "enterprise"  # Instance identifier for licensing

Aerospike — Message State Storage

aerospike:
  hosts: "aerospike-host"
  port: 3000
  namespace: "proxy"
  sweep_time: 1h
  write_policy_default_ttl: 86400
  write_policy_index_default_ttl: 86400

Rate Limiters

The proxy supports a layered rate limiting architecture. Rate limiters are defined as a list under the rate_limiters section.

rate_limiters:
  - name: "l1"
    type: "memory"
    description: "In-process rate limiter for global API requests"
    config:
      rps: 800
      burst: 960

  - name: "l2"
    type: "redis"
    description: "Distributed rate limiter for SMPP links"
    config:
      redis:
        addr: "redis-host:6379"
        password: ""
        db: 0
        dial_timeout: 5s
        read_timeout: 10s
        write_timeout: 500ms
        pool_size: 20
        min_idle_conns: 5
        retry_attempts: 5
        retry_delay: 2s

L1 — In-Process Rate Limiter

The L1 limiter runs in memory and protects the proxy from API-level overload. It applies to all incoming requests (REST + gRPC) before any further processing.

L2 — Distributed Rate Limiter (Redis)

The L2 limiter enforces per-link and per-pool rate limits defined in smpp_rules.toml. It uses Redis to coordinate limits across multiple proxy instances in a cluster. The actual RPS values per link are set via esme_rate in the SMPP rules — see the SMPP Links section below.

Security

security:
  token_ttl: 12h
  dedup_ttl: 1m

Web (REST API)

web:
  bind: "0.0.0.0"
  port: 8080
  tls: false
  admin_api_key: "your-secure-admin-key"

gRPC

grpc:
  port: 44044
  timeout: 1h

SMPP Protocol Settings

smpp:
  config_path: "./smpp_rules"
  config_file: "smpp_rules.toml"
  client_library: "v2"

MCP Filters (Contact Policy)

MCP filters define connections to the Message Control Platform instances. The filter name follows the pattern <strategy>_filter — for example, cp1_filter, cp2_filter. You can define as many filters as needed.

cp1_filter:
  active: true
  token: "mcp-access-token"
  cp_endpoint: "/api/v1/check"
  blacklist: false
  hosts:
    - "http://mcp-1:1880"
    - "http://mcp-2:1880"
    - "http://mcp-3:1880"
  blacklist_endpoint: "/api/v1/check"
  health_check_endpoint: "/api/v1/health"
  description: "Frequency-based contact policy (daily + weekly limits)"

cp2_filter:
  active: true
  token: "mcp-access-token"
  cp_endpoint: "/api/v1/check"
  blacklist: true
  hosts:
    - "http://mcp-dedup:1880"
  blacklist_endpoint: "/api/v1/check"
  health_check_endpoint: "/api/v1/health"
  description: "Deduplication with blacklist check"

How Filter Names Map to Strategies

The filter name prefix (before _filter) corresponds to the strategy name used in the API. When sending a message with "strategy": "cp1", the proxy uses the configuration from cp1_filter. This allows you to create custom strategy names — for example, premium_filter would be invoked with "strategy": "premium".

Multiple MCP Instances

You can list multiple hosts for a single filter to achieve horizontal scaling:

cp1_filter:
  hosts:
    - "http://mcp-1:1880"
    - "http://mcp-2:1880"
    - "http://mcp-3:1880"
    - "http://mcp-4:1880"
    - "http://mcp-5:1880"

All instances must share the same flow definitions and connect to the same Redis backend. The proxy distributes policy check requests across all listed hosts.

Statistics Exporter

The statistics exporter sends CDR (Call Detail Records) data to external S3-compatible storage for auditing and analytics.

statistic_exporter:
  enabled_export: false
  local_path: "./journal/stat"
  port: 30188
  host: "s3-host"
  hostname: "smpp-proxy-01"
  prefix: "statistics"
  tls: false
  s3Region: "us-east-1"
  access: "your-s3-access-key"
  secret: "your-s3-secret-key"
  bucket: "sms-stat"
  subpath: "sms"

Monitoring (OpenTelemetry)

monitoring:
  otel: false
  otel_samling: 100
  otel_collector_endpoint: "otel-collector:4318"

When enabled, the proxy sends distributed traces to the configured collector, allowing you to trace message processing across all internal components.

SMPP Configuration — smpp_rules.toml

This file defines the physical SMPP connections and virtual pools. It is located in the directory specified by smpp.config_path in the application config.

SMPP Links

Each link represents a physical SMPP connection to an SMSC (Short Message Service Center). Links are defined under the [links.N] section, where N is a unique numeric identifier (ESME ID).

Link Parameters

Link Example

[links.100]
esme_disabled = false
esme_addr = "smsc1.example.com"
esme_port = 2775
esme_systemid = "smppclient1"
esme_password = "password"
esme_enquirelink = 15
esme_enquirelink_timeout = 40
esme_rate = 200
esme_rate_burst = 200
esme_resp_timeout = 20
esme_routes_path = "smpp_rules/routes.ini"
esme_route_filter = false
esme_use_payload = false
esme_ip_whitelist = ["127.0.0.1"]

Virtual Pools

Pools group multiple physical SMPP links into a single logical sender with weighted load balancing. Messages sent to a pool are automatically distributed across member links using a Smooth Weighted Round-Robin algorithm.

Pools are defined under the [pools.N] section, where N is a unique numeric pool identifier. Inside the section, each key is a link ESME ID and the value is its weight.

Pool Configuration

[pools.1001]
100 = 1000
101 = 1000

In this example, pool 1001 consists of links 100 and 101, each with a weight of 1000. Since weights are equal, traffic is distributed evenly (50/50). If you set different weights — for example 100 = 2000 and 101 = 1000 — link 100 will receive approximately twice as much traffic as link 101.

Multiple Pools Example

# --- Links ---

[links.100]
esme_addr = "smsc1.operator-a.com"
esme_port = 2775
esme_systemid = "client_a1"
esme_password = "pass_a1"
esme_rate = 200
esme_rate_burst = 200

[links.101]
esme_addr = "smsc2.operator-a.com"
esme_port = 2775
esme_systemid = "client_a2"
esme_password = "pass_a2"
esme_rate = 200
esme_rate_burst = 200

[links.102]
esme_addr = "smsc1.operator-b.com"
esme_port = 2775
esme_systemid = "client_b1"
esme_password = "pass_b1"
esme_rate = 100
esme_rate_burst = 100

# --- Pools ---

[pools.1001]   # Operator A — balanced across two links
100 = 1000
101 = 1000

[pools.1002]   # Operator B — single link
102 = 1000

Configuration Files Summary

Next Steps

• Installation Guide — deploy the platform using Docker Compose
• Load Balancing — detailed documentation on virtual pools and traffic distribution
• Rate Limiting & Throttling — multi-layer rate limiting architecture
• REST API — manage SMPP links and pools via the HTTP API