Telegram destination in syslog-ng

Getting started with the Telegram destination of syslog-ng is not an easy and straightforward process, but it is well worth the efforts. If you do not know Telegram yet, Telegram is a cloud-based messaging application known for its security and speed. Best of all, it is a free app without ads. No wonder that Telegram is also used by many system administrators. With the Telegram destination of syslog-ng introduced in version 3.16, we intend to help your work as a sysadmin. As a result, you can now receive critical log messages in real-time on your mobile or desktop Telegram client.

Creating a new bot

To be able to use the Telegram API for sending messages, you need to set up a bot user. This part is really easy. It involves just a quick chat with a bot, called the BotFather.

1. Start the process by sending the /newbot command to BotFather.
2. BotFather asks for a name, which will be displayed on the screen.
3. Next, it asks you for a username. The usernameneeds to end with “bot”. If a name is already taken, BotFather asks you to enter another name.
4. Once you entered a username, BotFather prints a token, which you can use to access the HTTP API. The token will look something like this:

1234567:wertwertwertwertwert

In the syslog-ng configuration, you will only need the token but we recommend noting down all three values.

Finding a chat id

Sending messages requires a chat id. Before you can findout the chat id, you need to open a chat with your freshly created bot. Just click on the link provided by BotFather and you are in a chat with the new bot. You can write anything. It does not matter what you write, the sole purpose is to have a chat started and a chat id created.

Figuring out the chat id is a bit more tricky as you need to use the Telegram API for that. You can use curl or you can also use your browser to figure it out. The URL has the following format:

https://api.telegram.org/bot<token>/getUpdates

With the token example above, the URL would look like this:

https://api.telegram.org/bot1234567:wertwertwertwertwert/getUpdates

The API should return a JSON structure also containing the chat id we are looking for. It is a number, for example:

3456789

If you receive a nearly empty answer, try chatting a bit more with your new bot and repeat the API request.

Configuring syslog-ng

You can read more about the possible options in the GitHub pull request at https://github.com/balabit/syslog-ng/pull/2085 Here, I only show a minimal configuration with the above example values. To make the example self contained and easy to use, I added a network source and connected the two using a log statement.

source s_network {
    network();
};

destination d_telegram {
  telegram(
    bot-id("bot1234567:wertwertwertwertwert")
    chat-id("3456789"));
};

log {source(s_network); destination(d_telegram); };

Notice that in the bot-id, the “bot” value is inserted before the token. However, starting with the next release (3.17), entering the token here will be enough.

Testing

If you used the above configuration example for testing the Telegram destination, you can test it using the following command:

logger -T --rfc3164 -n 127.0.0.1 -P 514 This is a test…

Within a second you should see the test message showing up in your Telegram client.

Now you can turn your configuration to production. In a real life configuration, you will most likely add a couple of filters to make sure that only relevant, really critical messages are sent to Telegram.

If you have questions or comments related to syslog-ng, do not hesitate to contact us. You can reach us by email or you can even chat with us. For a list of possibilities, check our GitHub page under the “Community” section at https://github.com/balabit/syslog-ng.