Skip to content

configuration.md

Latest commit

 

History

History
280 lines (212 loc) · 10 KB

configuration.md

File metadata and controls

280 lines (212 loc) · 10 KB

Configuration Documentation

This document describes the configuration file format and options for the SMS/Modem Gateway application. The configuration uses TOML format and is typically stored as config.toml in the application root directory.

Table of Contents

Database Configuration

The database section configures the connection to your database and encryption settings.

Required Fields

Field Type Description
database_url String Database connection URL.
encryption_key String Base64-encoded 32-byte encryption key.

Example

[database]
database_url = "/home/pi/example.db"
encryption_key = "SGVsbG8gV29ybGQhIFRoaXMgaXMgYSAzMiBieXRlIGtleQ=="

Tip

Generate a secure encryption key using: openssl rand -base64 32

Modem Configuration

The modem section configures the cellular modem connection and behavior.

Fields

Field Type Default Description
device String "/dev/ttyS0" Serial device path for the modem
baud_rate u32 115200 Serial baud rate
gnss_enabled bool false Enable GPS/GNSS functionality
gnss_report_interval u32 0 GNSS report interval in seconds (0 = disabled)
cmd_channel_buffer_size usize 32 Command channel buffer size
read_buffer_size usize 4096 Read buffer size in bytes
line_buffer_size usize 4096 Line buffer size in bytes
gpio_enabled bool false Should the GPIO power pin be toggled on startup. Requires gpio feature
gpio_power_pin u8 4 GPIO power pin, uses Waveshare GSM Hat default. Requires gpio feature
gpio_repower bool true Toggle power pin on worker connection failure. Requires gpio feature

Example

[modem]
device = "/dev/ttyUSB0"
baud_rate = 115200
gnss_enabled = true
gnss_report_interval = 30
cmd_channel_buffer_size = 64
read_buffer_size = 8192
line_buffer_size = 8192
gpio_enabled = true
gpio_power_pin = 4
gpio_repower = true

Notes

  • All fields are optional and will use defaults if not specified.
  • GNSS reporting interval of 0 disables periodic reports.
  • GPIO options are only used if compiled with gpio feature.

HTTP Server Configuration

The HTTP section configures the web server for REST API and WebSocket connections.

Fields

Field Type Default Description
enabled bool false Enable HTTP server
address String "127.0.0.1:3000" Server bind address and port
send_international_format_only bool true Only send numbers in international format
require_authentication bool true Require authentication for API access
websocket_enabled bool true Enable WebSocket support
phone_number String null Default phone number for the modem
tls TLSConfig null TLS configuration (see below)

Example

[http]
enabled = true
address = "0.0.0.0:8080"
send_international_format_only = true
require_authentication = true
websocket_enabled = true
phone_number = "+1234567890"

Notes

  • Set address to 0.0.0.0:port to accept connections from any IP.
  • Use 127.0.0.1:port for localhost-only access.
  • Phone number should be in international format (starting with +).

TLS Configuration

TLS configuration is a subsection of the HTTP configuration that enables HTTPS.

Fields

Field Type Description
certificate_path String Path to TLS certificate file
key_path String Path to TLS private key file

Example

[http]
enabled = true
address = "0.0.0.0:8443"

[http.tls]
certificate_path = "/path/to/certificate.crt"
key_path = "/path/to/private.key"

Notes

  • Both certificate and key files must exist and be readable.
  • Use full paths to certificate files.
  • The application will validate file existence at startup.

Webhook Configuration

Webhooks allow the application to send HTTP requests when specific events occur.

Fields

Field Type Default Description
url String - Webhook endpoint URL
expected_status u16 null Expected HTTP status code (optional)
events String[] ["incoming"] List of events to trigger webhook
headers Object null Custom HTTP headers
certificate String null Path to custom CA certificate

Example

[[webhooks]]
url = "https://api.example.com/sms-webhook"
events = ["incoming", "outgoing"]

[webhooks.headers]
Authorization = "Bearer your-token-here"

[[webhooks]]
url = "https://internal.company.com/notifications"
expected_status = 204
events = ["incoming"]
certificate = "/path/to/internal-ca.crt"

Notes

  • Multiple webhooks can be configured using [[webhooks]] array syntax.
  • If expected_status is not specified, any 2xx status is considered success.
  • Custom certificates are useful for internal/self-signed endpoints.
  • Headers are optional and can include authentication tokens.

Sentry Configuration (Optional)

Sentry integration provides error tracking. This section is only available when compiled with the sentry feature.

Fields

Field Type Default Description
dsn String - Sentry Data Source Name
environment String null Environment name (e.g., "production")
server_name String null Server name for event tagging
debug bool false Enable Sentry debug mode
send_default_pii bool true Send personally identifiable information

Example

[sentry]
dsn = "https://your-dsn@sentry.io/project-id"
environment = "production"
server_name = "sms-gateway-01"
debug = false
send_default_pii = false

Notes

  • This section is only processed when the application is built with Sentry support.
  • DSN can be found in your Sentry project settings.
  • Set send_default_pii = false for privacy-sensitive deployments.

Complete Example

Here's a complete configuration file example:

# Database configuration
[database]
database_url = "/home/pi/example.db"
encryption_key = "SGVsbG8gV29ybGQhIFRoaXMgaXMgYSAzMiBieXRlIGtleQ=="

# Modem configuration
[modem]
device = "/dev/ttyUSB0"
baud_rate = 115200
gnss_enabled = true
gnss_report_interval = 60
gpio_power_pin = true
gpio_repower = true
cmd_channel_buffer_size = 64
read_buffer_size = 8192
line_buffer_size = 8192

# HTTP server configuration
[http]
enabled = true
address = "0.0.0.0:8080"
send_international_format_only = true
require_authentication = true
websocket_enabled = true
phone_number = "+1234567890"

# TLS configuration (HTTPS)
[http.tls]
certificate_path = "/etc/ssl/certs/sms-gateway.crt"
key_path = "/etc/ssl/private/sms-gateway.key"

# Webhook configurations
[[webhooks]]
url = "https://api.myservice.com/sms-received"
events = ["incoming"]

[[webhooks]]
url = "https://internal.company.com/alerts"
expected_status = 204
events = ["incoming"]
certificate = "/etc/ssl/certs/company-ca.crt"

# Sentry error tracking (optional)
[sentry]
dsn = "https://your-key@sentry.io/project-id"
environment = "production"
server_name = "gateway-prod-01"
debug = false
send_default_pii = false

Configuration File Loading

The application looks for the configuration file in the following order:

  1. Path specified via command line argument. Eg: sms-server -c config.toml
  2. config.toml in the current working directory.

If the configuration file cannot be found or parsed, the application will exit with an error message.

Security Considerations

  • Store the configuration file securely with appropriate file permissions.
  • Use strong, randomly generated encryption keys.
  • Regularly rotate encryption keys and authentication tokens.
  • Use TLS for all webhook endpoints when possible.