This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

telegram: Send messages to Telegram

1: telegram() destination options

The telegram() destination sends log messages to Telegram, which is a secure, cloud-based mobile and desktop messaging app.

Note that this destination automatically uses the certificate store of the system (for details, see the curl documentation).

Declaration:

   telegram(parameters);

You can use the proxy() option to configure the HTTP driver in all HTTP-based destinations to use a specific HTTP proxy that is independent from the proxy configured for the system.

Example: Using the telegram() driver

The following example creates a telegram() destination.

   destination d_telegram {
        telegram(
            template("${MESSAGE}")
            throttle(1)
            parse-mode("markdown")
            disable-web-page-preview("true")
            bot-id("<bot id>")
            chat-id("<chat id>")
        );
    };

1 - telegram() destination options

The telegram() destination has the following options:

bot-id()


Type:	number
Default:	N/A

Description: This is a required option. Specifies the token for the bot necessary to access the Telegram HTTP API.

chat-id()


Type:	number
Default:	N/A

Description: This is a required option. Specifies the ID of the chat of the telegram destination.

disable_notification()


Type:	boolean
Default:	`false`

Description: Enables the telegram() destination to send silent messages. By default, the disable_notification() value is false.

Example: using the disable_notification() option with the telegram() destination

The following example illustrates how you can configure the disable_notification()option to send silent messages to the telegram() destination.

   destination {
      telegram(
        bot-id(...)
        chat-id(...) 
        disable_notification(true)
      ); 
    };

disable-web-page-preview()


Type:	boolean
Default:	true

Description: Disables link previews for links in the message. By default, the disable-web-page-preview value is true. From a security point of view, Axoflow recommends to leave it true, otherwise malicious messages can trick the telegram destination to generate traffic to any URL.

hook-commands()

Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.

Note The AxoSyslog application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable AxoSyslog to execute external applications.

Using `hook-commands()` when AxoSyslog starts or stops

To execute an external program when AxoSyslog starts or stops, use the following options:

`startup()`

Type:	string
Default:	N/A

Description: Defines the external program that is executed as AxoSyslog starts.

`shutdown()`

Type:	string
Default:	N/A

Description: Defines the external program that is executed as AxoSyslog stops.

Using the hook-commands() when AxoSyslog reloads

To execute an external program when the AxoSyslog configuration is initiated or torn down, for example, on startup/shutdown or during a AxoSyslog reload, use the following options:

`setup()`

Type:	string
Default:	N/A

Description: Defines an external program that is executed when the AxoSyslog configuration is initiated, for example, on startup or during a AxoSyslog reload.

`teardown()`

Type:	string
Default:	N/A

Description: Defines an external program that is executed when the AxoSyslog configuration is stopped or torn down, for example, on shutdown or during a AxoSyslog reload.

Example: Using hook-commands() with a network source

In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as AxoSyslog is started/stopped.

The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the AxoSyslog created rule is there, packets can flow, otherwise the port is closed.

source {
    network(transport(udp)
    hook-commands(
          startup("iptables -I LOGCHAIN 1 -p udp --dport 514 -j ACCEPT")
          shutdown("iptables -D LOGCHAIN 1")
        )
     );
};

parse-mode()


Type:	string
Default:	none

Description: Formats the message in a markdown-style or HTML-style formatting. By default, the parse-mode value is markdown, which means that the message is formatted in markdown style.

template()


Type:	string
Default:	`${MESSAGE}`

Description: Specifies the content of the message. The AxoSyslog application will automatically encode the content of this option using the url-encode() template function.

time-reopen()


Accepted values:	number [seconds]
Default:	60

Description: The time to wait in seconds before a dead connection is reestablished.

throttle()


Type:	number
Default:	0

Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.