Skip to main content

Configure Telegram access notifications

PortGuard Server can send a Telegram message after a valid SPA packet adds a firewall rule. Notifications include the server hostname, allowed source IP, packet source IP, SPA username, requested access, opening time, expiration time, and timeout.

1. Create a Telegram bot​

  1. Open @BotFather in Telegram.
  2. Send /newbot and follow the prompts.
  3. Copy the Bot Token returned by BotFather. It looks like 123456789:AAExampleToken.

Treat the Bot Token as a password. Do not commit it to source control, paste it into support messages, or expose it in screenshots.

2. Find the destination Chat ID​

For a private chat, open the new bot, select Start, and send it a message. For a group, add the bot to the group and send a message or command that the bot can receive.

On the server, enter the Bot Token without saving it in shell history:

read -rsp 'Telegram Bot Token: ' TG_TOKEN; echo

Read the bot's latest updates:

curl --config - <<EOF
silent
show-error
fail
url = "https://api.telegram.org/bot${TG_TOKEN}/getUpdates"
EOF
unset TG_TOKEN

Find message.chat.id in the JSON response. Private Chat IDs are normally positive numbers. Group Chat IDs are normally negative and supergroup IDs often start with -100.

If result is empty, send the bot another message and run the request again. For a channel, you can use @channel_username after adding the bot as a channel administrator with permission to post messages.

3. Configure PortGuard Server​

Start the firewall console as root:

sudo portguard-fwknopd --fw-console

Select 5. Configure Telegram notifications, then enter:

  • Bot token: the token supplied by BotFather.
  • Chat ID: the numeric private/group ID or @channel_username.
  • Minimum notification interval: 0 sends a notification for every successful knock. A larger value suppresses additional notifications during that many seconds.

Confirm the configuration and choose y when asked to send a test notification. The console stores the settings in /etc/fwknop/fwknopd.conf with mode 600 and reloads the running daemon.

4. Configure it manually​

The same settings can be added directly to /etc/fwknop/fwknopd.conf:

PORTGUARD_TG_BOT_TOKEN       123456789:replace_with_bot_token;
PORTGUARD_TG_CHAT_ID          -1001234567890;
PORTGUARD_TG_NOTIFY_INTERVAL  0;

Both the Bot Token and Chat ID are required. Protect the configuration and restart the service after a manual change:

sudo chmod 600 /etc/fwknop/fwknopd.conf
sudo portguard-fwknopd --exit-parse-config \
  -c /etc/fwknop/fwknopd.conf \
  -a /etc/fwknop/access.conf
sudo systemctl restart fwknopd

5. Verify notifications​

Follow the daemon log while sending a valid SPA packet from PortGuard Client:

sudo journalctl -u fwknopd -f

A notification is queued only after the SPA packet is accepted and a firewall rule is successfully added. A repeated knock while the same rule is still active may not create another rule. Wait for the previous rule to expire before testing again.

If the console test fails or an accepted knock does not send a message, check:

  • The server can resolve api.telegram.org and make outbound HTTPS connections.
  • The private chat has been started, or the bot has permission to post in the destination group or channel.
  • The Chat ID belongs to the same bot conversation used with getUpdates.
  • PORTGUARD_TG_NOTIFY_INTERVAL is not suppressing the notification.
  • fwknopd was reloaded or restarted after a manual configuration change.

6. Disable notifications​

Run the console again, select option 5, enter disable as the Bot Token, and confirm. PortGuard removes all three Telegram settings and reloads the daemon.