GAMMU-SMSDRC(5)

πŸ“¦
version 1.45.0 Β· 6 versions
, in arch rolling

πŸ’– NAME πŸ’–

okay so this is GAMMU-SMSDRC(5), aka the manual page for the gammu-smsd(1) config file β€” the little file that tells the SMS daemon how to behave. bestie, this is important stuff ✨

🌸 DESCRIPTION 🌸

gammu-smsd reads its configuration from a config file. You can point it at a specific location on the command line, otherwise it uses the default path /etc/gammu-smsdrc. easy peasy πŸ’…

This file uses ini file syntax β€” see INI file format.

The config file for gammu-smsd has at least two sections: [gammu] and [smsd]. If you're using SQL Service, you can also use [sql] and [tables]. so many little sections, we love a structured queen πŸ‘‘

The [gammu] section is the phone connection config, and it's the same as described in Gammu Configuration File β€” with one tiny exception: LogFile is ignored, and common logging for the gammu library and the SMS daemon is used instead. But the LogFormat directive still controls how many messages gammu emits. periodt.

  • [smsd] β€” this section configures the SMS daemon itself, and it's described in the following subsections. First you get the general parameters of the SMS daemon, then the specific parameters for storage backends. slay.
  • [include_numbers] β€” list of numbers from which to accept messages, see Message filtering.
  • [exclude_numbers] β€” list of numbers from which to reject messages, see Message filtering.
  • [include_smsc] β€” list of SMSC numbers from which to accept messages, see Message filtering.
  • [exclude_smsc] β€” list of SMSC numbers from which to reject messages, see Message filtering.
  • [sql] β€” configure SQL queries used by SQL Service; you usually don't have to modify them. See also: Configurable queries. πŸ’–
  • [tables] β€” configure SQL table names used by SQL Service; you usually don't have to modify them. See also: Tables.

✨ GENERAL PARAMETERS OF SMS DAEMON ✨

πŸŽ€ Service πŸŽ€

The SMSD service to use. Pick one of these cuties:

  • FILES β€” stores messages in files, see Files backend for details. very filecore πŸ’…
  • NULL β€” does not store messages at all, see Null Backend for details. literally storing nothing, iconic.
  • SQL β€” stores messages in an SQL database, see SQL Service for details, and choose the database type to use with Driver. added in version 1.28.93 ✨
  • MYSQL β€” deprecated since version 1.28.93: use Service = SQL and Driver = native_mysql instead. it's a compatibility option for older config files, and it stores messages in a MySQL database, see MySQL Backend for details.
  • PGSQL β€” deprecated since version 1.28.93: use Service = SQL and Driver = native_pgsql instead. compatibility option for older config files, stores messages in a PostgreSQL database, see PostgreSQL Backend for details.
  • DBI β€” deprecated since version 1.28.93: use Service = SQL and Driver = DBI driver instead. compatibility option for older config files, stores messages in any database supported by libdbi, see DBI Backend for details.
Note: availability of backends depends on platform and compile time configuration. no cap, check your build bestie 🫢

πŸ” PIN πŸ”

PIN for the SIM card. This is optional, but you should set it if your phone requires a PIN after power on. protect the phone, protect the vibes πŸ’…

🌐 NetworkCode 🌐

Network personalisation password. This is optional, but some phones require it after power on.

πŸ“± PhoneCode πŸ“±

Phone lock password. This is optional, but some phones require it after power on.

πŸ“ LogFile πŸ“

File where SMSD actions are being logged. You can also use the special value syslog, which sends all messages to the syslog daemon. On Windows there's another special value, eventlog, which sends logs to Windows Event Log. fancy ✨

If you run SMSD as a system daemon (or service), it is recommended to use an absolute path to the log file, because the startup directory might be different than you expect. trust me, absolute path is the main character here πŸ‘‘

Default is to provide no logging.

Note: for logging to Windows Event Log, it is recommended to install the Event Log source by invoking gammu-smsd -e (this is automatically done during installation of Gammu).

πŸͺ΅ LogFacility πŸͺ΅

Facility to use on logging backends which support it (currently only syslog). Pick one of these:

  • DAEMON (default)
  • USER
  • LOCAL0
  • LOCAL1
  • LOCAL2
  • LOCAL3
  • LOCAL4
  • LOCAL5
  • LOCAL6
  • LOCAL7

Added in version 1.30.91. πŸ’–

🐞 DebugLevel 🐞

Debug level for SMSD. The integer value should be the sum of all the flags you want to enable. math girlie moment πŸ”₯

  • 1 β€” enables basic debugging information
  • 2 β€” enables logging of SQL queries of service backends
  • 4 β€” enables logging of gammu debug information

Generally, to get as much debug information as possible, use 255. maximum chaos, maximum info πŸ’€

Default is 0, which should mean no extra information.

⏱️ CommTimeout ⏱️

How many seconds should SMSD wait after there is no message in the outbox before scanning it again.

Default is 30.

πŸ“€ SendTimeout πŸ“€

Shows how many seconds SMSD should wait for a network answer during sending SMS. If nothing happens during this time, the SMS will be resent.

Default is 30.

πŸ” MaxRetries πŸ”

How many times will SMSD try to resend a message if sending fails. This is tracked per message and supported with SQL and Files backends.

With the Files backend, retry counts are kept in memory and reset when SMSD restarts. Counts are keyed by filename, so use a unique filename for each queued message. After the initial attempt and the configured number of retries fail, the message is moved to ErrorSMSPath. important detail bestie, don't miss it 🫢

Default is 1.

⏳ RetryTimeout ⏳

How long to wait before resending a failed message (needs to be enabled by MaxRetries).

Is used in update_retries.

Supported only with SQL backends. The Files backend retries on subsequent processing loops without this delay.

Default is 600.

πŸ“₯ ReceiveFrequency πŸ“₯

The number of seconds between testing for received SMSes, when the phone is busy sending SMSes. Normally a test for received SMSes is done every CommTimeout seconds and after each sent SMS.

Default is 15.

πŸ”‹ StatusFrequency πŸ”‹

The number of seconds between refreshing phone status (battery, signal) stored in shared memory and possibly in service backends. Use 0 to disable.

With the default SQL queries, the phone record expires ten seconds after the next refresh is due.

You might want to increase this for higher throughput.

Default is 60.

😴 LoopSleep 😴

The number of seconds how long SMSD will sleep before checking for some activity. Please note that setting this to a value higher than 1 will have effects on other time based configurations, because they will be effectively rounded to a multiple of this value.

Setting this to 0 disables sleeping. Please note this might cause Gammu to consume quite a lot of CPU power as it will effectively do a busy loop. not the busy loop, anything but the busy loop 😭

This sleep is utilized only if the main loop (sending and receiving messages) takes less than the defined time. For example, if you set LoopSleep to 5 seconds and sending messages takes 10 seconds, no sleep will be done in the iteration which is sending messages. Also the sleep time is lowered by the already processed time.

Default is 1.

🧩 MultipartTimeout 🧩

The number of seconds how long SMSD will wait for all parts of a multipart message. If all parts won't arrive in time, the parts will be processed as separate messages.

Default is 600 (10 minutes).

πŸ”’ CheckSecurity πŸ”’

Whether to check if the phone wants to enter a PIN.

Default is 1 (enabled).

πŸ“΄ HangupCalls πŸ“΄

Added in version 1.34.0.

Whether to automatically hang up any incoming calls.

Default is 0 (disabled).

πŸ”‹ CheckBattery πŸ”‹

Whether to check phone battery state periodically.

Default is 1 (enabled).

πŸ“Ά CheckSignal πŸ“Ά

Whether to check signal level periodically.

Default is 1 (enabled).

🌐 CheckNetwork 🌐

Added in version 1.37.90.

Whether to check network status periodically.

If the phone is reported to be not on the network, SMSD tries to power it on.

Default is 1 (enabled).

πŸ”„ ResetFrequency πŸ”„

The number of seconds between performing a preventive soft reset in order to minimize the cases of hanging phones β€” e.g. Nokia 5110 will sometimes freeze to a state when only after unmounting the battery will the phone be functional again. the Nokia 5110 said no to functioning, and honestly same 😭

Default is 0 (not used).

πŸ’₯ HardResetFrequency πŸ’₯

Added in version 1.28.92.

Warning: for some phones a hard reset means deleting all data in it. Use ResetFrequency instead, unless you know what you are doing. bestie, please read that twice πŸ’€

The number of seconds between performing a preventive hard reset in order to minimize the cases of hanging phones.

Default is 0 (not used).

πŸ“¬ DeliveryReport πŸ“¬

Whether delivery reports should be used, one of no, log, sms.

  • log β€” one line log entry
  • sms β€” store in inbox as a received SMS
  • no β€” no delivery reports

Default is no.

⏲️ DeliveryReportDelay ⏲️

Delay in seconds how long a delivery report is still considered valid. This depends on the brokenness of your network (a delivery report should have the same timestamp as the sent message). Increase this if delivery reports are not paired with sent messages.

Default is 600 (10 minutes).

🏷️ PhoneID 🏷️

String with info about the phone used for sending/receiving. This can be useful if you want to run several SMS daemons (see Multiple modems). multiple modems? multiple main characters, honestly πŸ‘‘πŸ’…

...and like, the second you set PhoneID, every single message (even the injected ones πŸ‘€) gets tagged with that string β€” it lands in the database as SenderID β€” and that's literally what lets multiple SMS daemons share one database without chaos. Slay.

So in that setup, the SMSD daemon only sends out <#outbox> outbox messages whose SenderID matches or is empty. Selective queen behavior πŸ’…

Heads up bestie: this option has, like, actually no effect with the Files backend <#gammu-smsd-files>. Not a thing there. Periodt.

SMSC

<span class="mint">Added in version 1.36.2.</span>

The SMSC number to use when sending messages β€” but only if the message didn't already specify one (peep the options of gammu-smsd-inject <#gammu-smsd-inject> for that).

Honestly? In most cases you don't need this setting at all, because Gammu tries to read the correct SMSC straight from the phone. But sometimes that fails 😭 β€” and if it does, try gammu getsmsc <#cmdoption-gammu-arg-getsmsc> and see what's up.

RunOnReceive

Runs a program after a message comes in. Like, an actual program, after an actual message. Iconic.

The command you configure can include any number of parameters. On POSIX systems it's executed through the shell, so any special characters in your configured command need to be escaped accordingly β€” yes, properly, don't come crying to me 🫢. The identifiers of received messages get passed as separate literal arguments and are not interpreted as shell syntax. What those identifiers actually are depends on your service backend: typically they're IDs of inserted rows for database backends, or file names for file-based backends.

On Windows, SMSD starts the configured executable directly. Wanna run a batch file? Then explicitly invoke cmd.exe /d /c, exactly like it says in Running a batch file on Windows <#smsd-run-windows>. Arguments containing command processor metacharacters, variable expansion characters, or control characters get rejected and the hook is not started. Why? Because that prevents caller-controlled values from being interpreted when a configured command invokes cmd.exe or a batch file. This restriction applies to all RunOn directives, no exceptions ✨

On POSIX systems, SMSD waits for the script to terminate β€” so a slow script can genuinely delay receiving new messages 😬. And no, do not rely on a fixed timeout to interrupt a blocked script, that's not how this works. On Windows, SMSD does not wait for completion or collect the script's exit status, so the script has to log its own processing failures. Responsibility era πŸ’€

The process gets a whole lot of info about the received message in its environment β€” check RunOnReceive Directive <#gammu-smsd-run> for the details.

RunOnFailure

<span class="mint">Added in version 1.28.93.</span>

Runs a program when something goes wrong. Proactive queen behavior πŸ‘‘

Use it to react to failures ahead of time, or to interactively detect that sending a message failed.

The program receives an optional literal argument, which right now can be either INIT (meaning the failure happened during phone initialization) or a message ID (which indicates an error while sending that message).

Note: the message details from RunOnReceive are not passed to this command. The PHONE_ID <#envvar-PHONE_ID> variable is still available though 🫢

RunOnSent

<span class="mint">Added in version 1.36.4.</span>

Runs a program after a message is sent. Closure, bestie πŸ¦‹

The program receives an optional literal argument containing a message ID, plus an environment full of message details as described in RunOnReceive Directive <#gammu-smsd-run>.

RunOnIncomingCall

<span class="mint">Added in version 1.38.5.</span>

Runs a program after an incoming call is cancelled.

The program receives a literal argument containing the phone number of the call. The PHONE_ID <#envvar-PHONE_ID> variable identifies the receiving SMSD instance. And PSA: this requires HangupCalls to be enabled, otherwise nothing happens πŸ’…

IncludeNumbersFile

A file with the list of numbers that SMSD accepts. One number per line, blank lines are ignored, very chill. The file is read at startup and only reread when the configuration is being reread. See Message filtering for the deets.

ExcludeNumbersFile

A file with the list of numbers SMSD does not accept. One number per line, blank lines ignored. Read at startup, reread only when the config is being reread. See Message filtering for details.

IncludeSMSCFile

A file listing the SMSC numbers that are accepted by SMSD. One number per line, blank lines ignored. Read at startup, reread only on config reread. See Message filtering ✨

ExcludeSMSCFile

A file listing the SMSC numbers that are not accepted by SMSD. One number per line, blank lines ignored. Read at startup, reread only when the configuration is being reread. See Message filtering for the full picture.

BackendRetries

How many times the SMSD backend will retry an operation. Resilient icon 🧚

The implementation differs between backends β€” for database backends it generally means how many times it'll try to reconnect to the server.

Default is 10.

Send

<span class="mint">Added in version 1.28.91.</span>

Whether to enable sending of messages. Yes or no, that's the whole vibe.

Default is True.

Receive

<span class="mint">Added in version 1.28.91.</span>

Whether to enable receiving of messages.

Default is True.

πŸ’Ύ DATABASE BACKENDS OPTIONS πŸ’Ύ

Okay so bestie, all the DBI, ODBC, MYSQL and PGSQL backends (peep the MySQL Backend, ODBC Backend, PostgreSQL Backend, and DBI Backend docs for their whole lore) support the same options for setting up the connection to a database. Iconic, honestly:

  • User β€” the user name used for connection to a database. Your database's main character name.
  • Password β€” password used for connection to a database. Keep it secret, keep it safe 🫢
  • Host β€” database server address. It can also contain port or socket path after a semicolon, for example localhost:/path/to/socket or 192.168.1.1:8000.

For ODBC this is used as Data source name.

Note: some database servers differentiate usage of localhost (to use local socket) and 127.0.0.1 (to use locat TCP/IP connection). Please make sure your SMSD settings match the database server ones. A lil mismatched vibe check and nothing works, so double-check it πŸ’…

Added in version 1.28.92.

  • PC β€” deprecated since version 1.28.92: please use Host instead. It's a synonym for Host, kept for backwards compatibility. It's giving legacy, but respectful.
  • Database β€” name of database (or schema) to use and where SMSD can find it's tables.

Please note that you should create tables in this database before using gammu-smsd. SQL files for creating needed tables are included in documentation for individual database backends: MySQL Backend, ODBC Backend, PostgreSQL Backend, DBI Backend. Tables first, vibes second ✨

  • SkipSMSCNumber β€” when you send sms from some SMS centers you can have delivery reports from other SMSC number. You can set here number of this SMSC used by you and Gammu will not check it's number during assigning reports to sent SMS. Lowkey a lifesaver for those mismatched delivery reports πŸŽ€
  • Driver β€” SQL driver to use. Gammu supports several native drivers and generic interface using ODBC and DBI. Availability of the backends depends on compile time options. Choose your fighter:
    • odbc β€” connects to the database using ODBC, see ODBC Backend.
    • native_mysql β€” stores messages in MySQL database, see MySQL Backend for details.
    • native_pgsql β€” stores messages in PostgreSQL database, see PostgreSQL Backend for details.
    • db2, firebird, freetds, ingres, msql, mysql, oracle, pgsql, sqlite, sqlite3 β€” stores messages using DBI library in given backend. You need to have installed appropriate DBI driver to make it work. See DBI Backend for details. No driver, no slay 😭
  • SQL β€” SQL dialect to use. This is specially useful with ODBC Backend where SMSD does not know which server it is actually talking to. Possible values:
    • mysql β€” MySQL
    • pgsql β€” PostgreSQL
    • sqlite β€” SQLite
    • mssql β€” Microsoft SQL Server
    • sybase β€” Sybase
    • access β€” Microsoft Access
    • oracle β€” Oracle
    • odbc β€” Generic ODBC

Added in version 1.28.93.

See also: you can also completely customize SQL queries used as described in SQL Queries. Go off, customize πŸ‘‘
  • DriversPath β€” path, where DBI drivers are stored. This usually does not have to be set if you have properly installed drivers. If it's working, leave it alone fr.
  • DBDir β€” database directory for some (currently only sqlite) DBI drivers. Set here path where sqlite database files are stored.

πŸ“‚ Files backend options πŸ“‚

The FILES backend accepts following configuration options. See Files backend for more detailed service backend description. Please note that all path should contain trailing path separator (/ on Unix systems) β€” yes, the trailing slash is not optional, it's the whole personality πŸ’…:

  • InboxPath β€” where the received SMSes are stored.

Default is current directory.

  • OutboxPath β€” where SMSes to be sent should be placed.

Default is current directory.

  • SentSMSPath β€” where the transmitted SMSes are placed, if same as OutboxPath transmitted messages are deleted.

Default is to delete transmitted messages.

  • ErrorSMSPath β€” where SMSes with error in transmission is placed.

Default is same as SentSMSPath.

  • InboxFormat β€” the format in which the SMS will be stored: detail, unicode, standard.
    • detail format used for message backup by Gammu Utility, see SMS Backup Format
    • unicode β€” message text stored in unicode (UTF-16)
    • standard β€” message text stored in system charset

The standard and unicode settings do not apply for 8-bit messages, which are always written raw as they are received with extension .bin.

Default is standard.

Note: in detail format, all message parts are stored into single file, for all others each message part is saved separately. One file per message vs. one file per part β€” pick your vibe πŸ¦‹
  • OutboxFormat β€” the format in which messages created by gammu-smsd-inject will be stored. It accepts same values as InboxFormat.

Default is detail if Gammu is compiled in with backup functions, unicode otherwise.

  • TransmitFormat β€” the format for transmitting the SMS: auto, unicode, 7bit.

This option is used only if OutboxFormat is not set to detail. In such case encoding specified in the message is used (you can specify it to gammu-smsd-inject).

Default is auto.

🎯 MESSAGE FILTERING 🎯

SMSD allows one to process only a limited subset of incoming messages. You can define filters for sender number in [include_numbers] and [exclude_numbers] sections or using IncludeNumbersFile and ExcludeNumbersFile directives. Gatekeeping, but make it productive πŸ’…

If [include_numbers] section exists, all values (keys are ignored) from it are used as allowed phone numbers and no other message is processed. On the other side, in [exclude_numbers] you can specify numbers which you want to skip. Bye bestie πŸ‘‹

Lists from both sources are merged together. If there is any number in include list, only include list is used and only messages in this list are being accepted. If include list is empty, exclude list can be used to ignore messages from some numbers. If both lists are empty, all messages are accepted. Easy.

Similar filtering rules can be used for SMSC number filtering, they just use different set of configuration options β€” [include_smsc] and [exclude_smsc] sections or IncludeSMSCFile and ExcludeSMSCFile directives. Same energy, different section name πŸ’–

🌈 EXAMPLES 🌈

There is more complete example available in Gammu documentation. Please note that for simplicity following examples do not include [gammu] section, you can look into Gammu Configuration File for some examples how it can look like. Copy-paste responsibly 🫢

πŸ“ Files service πŸ“

SMSD configuration file for FILES backend could look like:

[smsd]
Service = files
PIN = 1234
LogFile = syslog
InboxPath = /var/spool/sms/inbox/
OutboxPath = /var/spool/sms/outbox/
SentSMSPath = /var/spool/sms/sent/
ErrorSMSPath = /var/spool/sms/error/

🐬 MySQL service 🐬

If you want to use MYSQL backend, you will need something like this:

[smsd]
Service = sql
Driver = native_mysql
PIN = 1234
LogFile = syslog
User = smsd
Password = smsd
PC = localhost
Database = smsd

🧸 DBI service using SQLite 🧸

For DBI Backend backend, in this particular case SQLite:

[smsd]
Service = sql
Driver = sqlite3
DBDir = /var/lib/sqlite3
Database = smsd.db

πŸ”Œ ODBC service using MySQL πŸ”Œ

For ODBC Backend backend, in this particular case using DSN smsd server:

[smsd]
Service = sql
Driver = odbc
Host = smsd

The DSN definition (in ~/.odbc.ini on UNIX) for using MySQL server would look like:

[smsd]
Description         = MySQL
Driver              = MySQL
Server              = 127.0.0.1
Database            = smsd
Port                =
Socket              =
Option              =
Stmt                =

[smsdsuse]
Driver              = MySQL ODBC 3.51.27r695 Driver
DATABASE            = smsd
SERVER              = 127.0.0.1

🚫 Numbers filtering 🚫

Process only messages from 123456 number:

[include_numbers]
number1 = 123456

Do not process messages from evil number 666:

[exclude_numbers]
number1 = 666

🐞 Debugging 🐞

Enabling debugging:

[smsd]
debuglevel = 255
logfile = smsd.log

πŸ“± Multiple modems πŸ“±

You can run any number of SMSD instances and they can even share same backend database. For routing the messages, you need to set different PhoneID for each instance and set SenderID column in outbox table. Multitasking queen behavior πŸ‘‘

Following example shows configuration for two modems, but you can have any number of SMSD instances. The only limitation is performance of your hardware, especially if all modems are connected using USB. USB hub go brrrr πŸ’€

Configuration for first SMSD:

[gammu]
device = /dev/ttyACM0
connection = at

[smsd]
Service = sql
Driver = native_mysql
PIN = 1234
LogFile = syslog
User = smsd
Password = smsd
PC = localhost
Database = smsd
PhoneID = first

Configuration for second SMSD:

[gammu]
device = /dev/ttyACM1
connection = at

[smsd]
Service = sql
Driver = native_mysql
PIN = 1234
LogFile = syslog
User = smsd
Password = smsd
PC = localhost
Database = smsd
PhoneID = second

You can then start two separate instances of SMSD:

gammu-smsd -c /path/to/first-smsdrc
gammu-smsd -c /path/to/second-smsdrc

πŸ’œ Author πŸ’œ

Michal ČihaΕ™ <michal@cihar.com> β€” the icon who made all this happen 🌟

2009-2015, Michal ČihaΕ™ <michal@cihar.com>

✨ aaaand that's the whole page bestie ✨ This gorgeous little manual dropped as version 1.45.0, dated Sep 16, 2026, and it's filed under GAMMU-SMSDRC(5). Go forth and configure your SMSD, you absolute legend πŸŽ€πŸ’–

πŸ“¦ where this page comes from