196 lines
6.3 KiB
Markdown
196 lines
6.3 KiB
Markdown
# About sms-handler
|
|
|
|
[sms-handler](https://code.philo.ydns.eu/philorg/sms-handler) is a simple companion service of the
|
|
*SMS to URL Forwarder* app available on [F-Droid](https://f-droid.org/en/packages/tech.bogomolov.incomingsmsgateway/),
|
|
to send notification mails on reception of SMSes.
|
|
|
|
Main audience: people who run a server on the public internet, configured with an email server
|
|
or configured as a relay.
|
|
|
|
## Installation
|
|
|
|
```sh
|
|
PIP_EXTRA_INDEX_URL=https://pypi.org/simple/ pip install --index-url https://code.philo.ydns.eu/api/packages/philorg/pypi/simple/ sms-handler
|
|
```
|
|
|
|
Debian and other systems prefer using `pipx` instead of `pip`:
|
|
|
|
```sh
|
|
sudo apt install -y pipx
|
|
PIP_EXTRA_INDEX_URL=https://pypi.org/simple/ pipx install --index-url https://code.philo.ydns.eu/api/packages/philorg/pypi/simple/ sms-handler
|
|
```
|
|
|
|
*sms-handler* can be run with any unprivileged user.
|
|
However due to standard security schemes, opening a port in the range 1-1024
|
|
is allowed to privileged users only (such as *root*).
|
|
Use `sudo` to install as root if *sms-handler* is to be configured
|
|
with a reserved port.
|
|
|
|
### Upgrade
|
|
|
|
```sh
|
|
pip upgrade --index-url https://code.philo.ydns.eu/api/packages/philorg/pypi/simple sms-handler
|
|
```
|
|
|
|
or:
|
|
|
|
```sh
|
|
pipx upgrade --index-url https://code.philo.ydns.eu/api/packages/philorg/pypi/simple sms-handler
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Configuration is done by environment variables, prefixed by `SMS_HANDLER_`:
|
|
|
|
* `SMS_HANDLER_MAIL_SENDER`: origin email address (default: *username*@localhost)
|
|
* `SMS_HANDLER_MAIL_TO`: destination email address (default: *username*@localhost)
|
|
* `SMS_HANDLER_MAIL_SERVER`: address of the mail server (default: localhost)
|
|
* `SMS_HANDLER_MAIL_SERVER_PORT`: port of the mail server (default: 25)
|
|
* `SMS_HANDLER_MAIL_SERVER_USERNAME`: username of the mail server (default: None)
|
|
* `SMS_HANDLER_MAIL_SERVER_PASSWORD`: port of the mail server (default: None)
|
|
* `SMS_HANDLER_MAIL_SERVER_START_TLS`: initiate mail server connection with TLS, eg. when using port 587 (default: no)
|
|
* `SMS_HANDLER_MAIL_SERVER_USE_TLS`: use mail server connection TLS, eg when using prot 465 (default: no)
|
|
* `SMS_HANDLER_MAIL_SUBJECT`: used to format the subject of the mails
|
|
* `SMS_HANDLER_MAIL_TEMPLATE`: used to format the body of the mails
|
|
* `SMS_HANDLER_MAIL_ENABLE`: no or false to disable mails (default: yes)
|
|
|
|
The default settings work with a mail server runs on the localhost,
|
|
and mails are sent to the user that owns the process.
|
|
|
|
### Templates
|
|
|
|
The `SMS_HANDLER_MAIL_TEMPLATE` and `SMS_HANDLER_MAIL_SUBJECT` variable use the standard
|
|
Python [string formatting](https://peps.python.org/pep-3101/).
|
|
See for example [here](https://www.w3schools.com/python/python_string_formatting.asp) for simple examples.
|
|
|
|
The field names are the same as the default JSON setting in the *SMS to URL Forwarder* app.
|
|
Additionally, a `pretty_from` variable can be used in the templates, which combines the phone number
|
|
of the sender with its name if found in the SMS record in the `fromName` field.
|
|
|
|
The default setting formats emails as below:
|
|
|
|
```text
|
|
{text}
|
|
---
|
|
From: {pretty_from}
|
|
Sent: {sentStamp:%c}
|
|
Received: {receivedStamp:%c}
|
|
Sim: {sim}
|
|
```
|
|
|
|
### SMS handler app configuration
|
|
|
|
Set the *Webhook URL* to `http://your.server.name:8025/handle-sms`.
|
|
|
|
Adjust with the public name (`your.server.name`) and the port where the
|
|
service is exposed. This corresponds to the
|
|
`--port` option of `sms-handler`. See also the *Reverse proxy* note below.
|
|
|
|
*Note*: the URI path `/handle-sms` is not configurable.
|
|
|
|
## Run
|
|
|
|
### As a daemon (Systemd)
|
|
|
|
Create a service as below, adapt the email addresses (`snoopy@peanuts.com` in this example).
|
|
|
|
Settings for the web server (listen address and port) can be given
|
|
in the ExecStart statement if the default values need to be adapted.
|
|
|
|
Other parameters are given as environment variables (see above).
|
|
|
|
```systemd
|
|
[Unit]
|
|
Description=SMS handler
|
|
|
|
[Service]
|
|
ExecStart=/home/snoopy/.local/bin/sms-handler
|
|
Environment=SMS_HANDLER_MAIL_SENDER=snoopy@peanuts.com
|
|
Environment=SMS_HANDLER_MAIL_TO=snoopy@peanuts.com
|
|
Restart=on-failure
|
|
|
|
[Install]
|
|
WantedBy=default.target
|
|
```
|
|
|
|
### Run in a container
|
|
|
|
*Sms-handler* is also packaged as a container for running with *docker*,
|
|
*podman*, or *Kunernetes*.
|
|
|
|
See `CONTAINER.md` for the details.
|
|
|
|
## Run behind a reverse proxy
|
|
|
|
*sms-handler* can run behind a reverse proxy (Nginx, Apache, Lighttpd, HAProxy, Caddy, Traefik, etc),
|
|
eg. for HTTPs support. The URI (configured in the *SMS to URL Forwarder* app) can be prefixed
|
|
to dispatch different applications on the same server.
|
|
|
|
[Caddy](https://caddyserver.com/) is suggested as it is straightforward to set up, with this Caddyfile extract:
|
|
|
|
```text
|
|
my.example.com {
|
|
handle /sms-handler/* {
|
|
uri strip_prefix /sms-handler
|
|
reverse_proxy 127.0.0.1:8025
|
|
}
|
|
}
|
|
```
|
|
|
|
Replace the public host name `my.example.com` and
|
|
the destination IP:port `127.0.0.1:8025` for your setup.
|
|
|
|
### In foreground
|
|
|
|
A service like `sms-handler` is designed to run as a background service (daemon).
|
|
|
|
However it is possible to run it manually:
|
|
|
|
```sh
|
|
sms-handler
|
|
```
|
|
|
|
Note that the default port is 8025, as it is not a restricted port so does not
|
|
need privileged permissions, aka root/sudo.
|
|
|
|
Set port and listen address:
|
|
|
|
```sh
|
|
sms-handler --port 80125 --host 192.168.100.55
|
|
```
|
|
|
|
## Development and test
|
|
|
|
*sms-handler* is packaged with [uv](https://docs.astral.sh/uv/).
|
|
|
|
Download source code, create a Python virtual environment, install dependencies and run the tests:
|
|
|
|
```sh
|
|
git clone https://code.philo.ydns.eu/philorg/sms-handler.git
|
|
cd sms-handler
|
|
uv venv
|
|
uv sync
|
|
. .venv/bin/activate # for bash. For fish: . .venv/bin/activate.fish
|
|
pytest -s tests/basic.py
|
|
```
|
|
|
|
The *sms-handler* source includes a CI test workflow for [Forgejo](https://forgejo.org/).
|
|
|
|
## Compatibility
|
|
|
|
*sms-handler* is also compatible with
|
|
[this fork of *SMS to URL Forwarder*](https://github.com/scottmconway/android_income_sms_gateway_webhook)
|
|
which includes also the sender's name.
|
|
|
|
## Alternatives
|
|
|
|
For a more flexible way to use a tool like *SMS to URL Forwarder*,
|
|
a pub/sub service like [ntfy](https://ntfy.sh/) should be considered.
|
|
It makes it easy to integrate with other components
|
|
for notification on various devices and automation.
|
|
|
|
## License, etc
|
|
|
|
*sms-handler* is BSD licensed. Suggestions and contributions are welcome.
|
|
|
|
<a href="https://liberapay.com/Philo/donate"><img alt="Donate using Liberapay" src="https://liberapay.com/assets/widgets/donate.svg"></a>
|