diff options
Diffstat (limited to 'doc/mod')
22 files changed, 819 insertions, 25 deletions
diff --git a/doc/mod/bridge-port-to.md b/doc/mod/bridge-port-to.md index 5b2817b..629c526 100644 --- a/doc/mod/bridge-port-to.md +++ b/doc/mod/bridge-port-to.md @@ -1,10 +1,17 @@ Manage ports in bridge ====================== -[◀ Go back to main README](../README.md) +[](https://github.com/eworm-de/routeros-scripts/stargazers) +[](https://github.com/eworm-de/routeros-scripts/network) +[](https://github.com/eworm-de/routeros-scripts/watchers) +[](https://mikrotik.com/download/changelogs/) +[](https://t.me/routeros_scripts) +[](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=A4ZXBD6YS2W8J) -🛈 This module can not be used on its own but requires the base installation. -See [main README](../README.md) for details. +[⬅️ Go back to main README](../../README.md) + +> ℹ️️ **Info**: This module can not be used on its own but requires the base +> installation. See [main README](../../README.md) for details. Description ----------- @@ -22,20 +29,20 @@ Just install the module: Configuration ------------- -The configuration goes to ports' comments (`/ interface bridge port`). +The configuration goes to ports' comments (`/interface/bridge/port`). - / interface bridge port add bridge=br-guest comment="default=dhcp-client, alt=br-guest" disabled=yes interface=en1; - / interface bridge port add bridge=br-intern comment="default=br-intern, alt=br-guest" interface=en2; - / interface bridge port add bridge=br-guest comment="default=br-guest, extra=br-extra" interface=en3; + /interface/bridge/port/add bridge=br-guest comment="default=dhcp-client, alt=br-guest" disabled=yes interface=en1; + /interface/bridge/port/add bridge=br-intern comment="default=br-intern, alt=br-guest" interface=en2; + /interface/bridge/port/add bridge=br-guest comment="default=br-guest, extra=br-extra" interface=en3; Also dhcp client can be handled: - / ip dhcp-client add comment="toggle with bridge port" disabled=no interface=en1; + /ip/dhcp-client/add comment="toggle with bridge port" disabled=no interface=en1; Add a scheduler to start with default setup on system startup: $ScriptInstallUpdate global-wait; - / system scheduler add name=bridge-port-vlan on-event="/ system script run global-wait; :global BridgePortTo; \$BridgePortTo default;" start-time=startup; + /system/scheduler/add name=bridge-port-to on-event="/system/script/run global-wait; :global BridgePortTo; \$BridgePortTo default;" start-time=startup; Usage and invocation -------------------- @@ -77,5 +84,5 @@ See also * [Manage VLANs on bridge ports](bridge-port-vlan.md) --- -[◀ Go back to main README](../README.md) -[▲ Go back to top](#top) +[⬅️ Go back to main README](../../README.md) +[⬆️ Go back to top](#top) diff --git a/doc/mod/bridge-port-vlan.md b/doc/mod/bridge-port-vlan.md index 67dd04d..cf29199 100644 --- a/doc/mod/bridge-port-vlan.md +++ b/doc/mod/bridge-port-vlan.md @@ -1,10 +1,17 @@ Manage VLANs on bridge ports ============================ -[◀ Go back to main README](../../README.md) +[](https://github.com/eworm-de/routeros-scripts/stargazers) +[](https://github.com/eworm-de/routeros-scripts/network) +[](https://github.com/eworm-de/routeros-scripts/watchers) +[](https://mikrotik.com/download/changelogs/) +[](https://t.me/routeros_scripts) +[](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=A4ZXBD6YS2W8J) -🛈 This module can not be used on its own but requires the base installation. -See [main README](../../README.md) for details. +[⬅️ Go back to main README](../../README.md) + +> ℹ️️ **Info**: This module can not be used on its own but requires the base +> installation. See [main README](../../README.md) for details. Description ----------- @@ -23,24 +30,24 @@ Configuration Using named VLANs you have to add comments in bridge vlan menu: - / interface bridge vlan add bridge=bridge comment=intern tagged=br-local vlan-ids=10; - / interface bridge vlan add bridge=bridge comment=geust tagged=br-local vlan-ids=20; - / interface bridge vlan add bridge=bridge comment=extra tagged=br-local vlan-ids=30; + /interface/bridge/vlan/add bridge=bridge comment=intern tagged=br-local vlan-ids=10; + /interface/bridge/vlan/add bridge=bridge comment=geust tagged=br-local vlan-ids=20; + /interface/bridge/vlan/add bridge=bridge comment=extra tagged=br-local vlan-ids=30; -The configuration goes to ports' comments (`/ interface bridge port`). +The configuration goes to ports' comments (`/interface/bridge/port`). - / interface bridge port add bridge=bridge comment="default=dhcp-client, alt=guest" disabled=yes interface=en1; - / interface bridge port add bridge=bridge comment="default=intern, alt=guest, extra=30" interface=en2; - / interface bridge port add bridge=bridge comment="default=guest, extra=extra" interface=en3; + /interface/bridge/port/add bridge=bridge comment="default=dhcp-client, alt=guest" disabled=yes interface=en1; + /interface/bridge/port/add bridge=bridge comment="default=intern, alt=guest, extra=30" interface=en2; + /interface/bridge/port/add bridge=bridge comment="default=guest, extra=extra" interface=en3; Also dhcp client can be handled: - / ip dhcp-client add comment="toggle with bridge port" disabled=no interface=en1; + /ip/dhcp-client/add comment="toggle with bridge port" disabled=no interface=en1; Add a scheduler to start with default setup on system startup: $ScriptInstallUpdate global-wait; - / system scheduler add name=bridge-port-vlan on-event="/ system script run global-wait; :global BridgePortVlan; \$BridgePortVlan default;" start-time=startup; + /system/scheduler/add name=bridge-port-vlan on-event="/system/script/run global-wait; :global BridgePortVlan; \$BridgePortVlan default;" start-time=startup; Usage and invocation -------------------- @@ -81,5 +88,5 @@ See also * [Manage ports in bridge](bridge-port-to.md) --- -[◀ Go back to main README](../../README.md) -[▲ Go back to top](#top) +[⬅️ Go back to main README](../../README.md) +[⬆️ Go back to top](#top) diff --git a/doc/mod/inspectvar.d/inspectvar.avif b/doc/mod/inspectvar.d/inspectvar.avif Binary files differnew file mode 100644 index 0000000..f1da1d4 --- /dev/null +++ b/doc/mod/inspectvar.d/inspectvar.avif diff --git a/doc/mod/inspectvar.md b/doc/mod/inspectvar.md new file mode 100644 index 0000000..7daba15 --- /dev/null +++ b/doc/mod/inspectvar.md @@ -0,0 +1,40 @@ +Inspect variables +================= + +[](https://github.com/eworm-de/routeros-scripts/stargazers) +[](https://github.com/eworm-de/routeros-scripts/network) +[](https://github.com/eworm-de/routeros-scripts/watchers) +[](https://mikrotik.com/download/changelogs/) +[](https://t.me/routeros_scripts) +[](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=A4ZXBD6YS2W8J) + +[⬅️ Go back to main README](../../README.md) + +> ℹ️️ **Info**: This module can not be used on its own but requires the base +> installation. See [main README](../../README.md) for details. + +Description +----------- + +RouterOS handles not just scalar variables, but also arrays - even nested. +This module adds a function to inspect variables. + +Requirements and installation +----------------------------- + +Just install the module: + + $ScriptInstallUpdate mod/inspectvar; + +Usage and invocation +-------------------- + +Call the function `$InspectVar` with a variable as parameter: + + $InspectVar $ModeButton; + + + +--- +[⬅️ Go back to main README](../../README.md) +[⬆️ Go back to top](#top) diff --git a/doc/mod/ipcalc.d/ipcalc.avif b/doc/mod/ipcalc.d/ipcalc.avif Binary files differnew file mode 100644 index 0000000..fe726e8 --- /dev/null +++ b/doc/mod/ipcalc.d/ipcalc.avif diff --git a/doc/mod/ipcalc.d/ipcalcreturn.avif b/doc/mod/ipcalc.d/ipcalcreturn.avif Binary files differnew file mode 100644 index 0000000..5e4dd57 --- /dev/null +++ b/doc/mod/ipcalc.d/ipcalcreturn.avif diff --git a/doc/mod/ipcalc.md b/doc/mod/ipcalc.md new file mode 100644 index 0000000..c07853e --- /dev/null +++ b/doc/mod/ipcalc.md @@ -0,0 +1,60 @@ +IP address calculation +====================== + +[](https://github.com/eworm-de/routeros-scripts/stargazers) +[](https://github.com/eworm-de/routeros-scripts/network) +[](https://github.com/eworm-de/routeros-scripts/watchers) +[](https://mikrotik.com/download/changelogs/) +[](https://t.me/routeros_scripts) +[](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=A4ZXBD6YS2W8J) + +[⬅️ Go back to main README](../../README.md) + +> ℹ️️ **Info**: This module can not be used on its own but requires the base +> installation. See [main README](../../README.md) for details. + +Description +----------- + +This module adds functions for IP address calculation. + +Requirements and installation +----------------------------- + +Just install the module: + + $ScriptInstallUpdate mod/ipcalc; + +Usage and invocation +-------------------- + +### IPCalc + +The function `$IPCalc` prints information to terminal, including: + +* address +* netmask +* network in CIDR notation +* minimum host address +* maximum host address +* broadcast address + +It expects an IP address in CIDR notation as argument. + + $IPCalc 192.168.88.1/24; + + + +### IPCalcReturn + +The function `$IPCalcReturn` expects an IP address in CIDR notation as +argument as well. But it does not print to terminal, instead it returns +the information in a named array. + + :put ([ $IPCalcReturn 192.168.88.1/24 ]->"broadcast"); + + + +--- +[⬅️ Go back to main README](../../README.md) +[⬆️ Go back to top](#top) diff --git a/doc/mod/notification-email.md b/doc/mod/notification-email.md new file mode 100644 index 0000000..127bf96 --- /dev/null +++ b/doc/mod/notification-email.md @@ -0,0 +1,89 @@ +Send notifications via e-mail +============================= + +[](https://github.com/eworm-de/routeros-scripts/stargazers) +[](https://github.com/eworm-de/routeros-scripts/network) +[](https://github.com/eworm-de/routeros-scripts/watchers) +[](https://mikrotik.com/download/changelogs/) +[](https://t.me/routeros_scripts) +[](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=A4ZXBD6YS2W8J) + +[⬅️ Go back to main README](../../README.md) + +> ℹ️️ **Info**: This module can not be used on its own but requires the base +> installation. See [main README](../../README.md) for details. + +Description +----------- + +This module adds support for sending notifications via e-mail. A queue is +used to make sure notifications are not lost on failure but sent later. + +Requirements and installation +----------------------------- + +Just install the module: + + $ScriptInstallUpdate mod/notification-email; + +Also you need a valid e-mail account with smtp login credentials. + +Configuration +------------- + +Set up your device's +[e-mail settings ↗️](https://wiki.mikrotik.com/wiki/Manual:Tools/email). +Also make sure the device has correct time configured, best is to set up +the ntp client. + +Then edit `global-config-overlay`, add `EmailGeneralTo` with a valid +recipient address. Finally reload the configuration. + +> ℹ️ **Info**: Copy relevant configuration from +> [`global-config`](../../global-config.rsc) (the one without `-overlay`) to +> your local `global-config-overlay` and modify it to your specific needs. + +### Sending to several recipients + +Sending notifications to several recipients is possible as well. Add +`EmailGeneralCc` on top, which can have a single mail address or a comma +separated list. + +Usage and invocation +-------------------- + +There's nothing special to do. Every script or function sending a notification +will now send it to your e-mail account. + +But of course you can use the function to send notifications directly. Give +it a try: + + $SendEMail "Subject..." "Body..."; + +Alternatively this sends a notification with all available and configured +methods: + + $SendNotification "Subject..." "Body..."; + +To use the functions in your own scripts you have to declare them first. +Place this before you call them: + + :global SendEMail; + :global SendNotification; + +In case there is a situation when the queue needs to be purged there is a +function available: + + $PurgeEMailQueue; + +See also +-------- + +* [Send notifications via Gotify](notification-gotify.md) +* [Send notifications via Matrix](notification-matrix.md) +* [Send notifications via Ntfy](notification-ntfy.md) +* [Send notifications via Telegram](notification-telegram.md) + +--- +[⬅️ Go back to main README](../../README.md) +[⬆️ Go back to top](#top) diff --git a/doc/mod/notification-gotify.d/appsetup.avif b/doc/mod/notification-gotify.d/appsetup.avif Binary files differnew file mode 100644 index 0000000..58f57a8 --- /dev/null +++ b/doc/mod/notification-gotify.d/appsetup.avif diff --git a/doc/mod/notification-gotify.md b/doc/mod/notification-gotify.md new file mode 100644 index 0000000..6fce629 --- /dev/null +++ b/doc/mod/notification-gotify.md @@ -0,0 +1,97 @@ +Send notifications via Gotify +=========================== + +[](https://github.com/eworm-de/routeros-scripts/stargazers) +[](https://github.com/eworm-de/routeros-scripts/network) +[](https://github.com/eworm-de/routeros-scripts/watchers) +[](https://mikrotik.com/download/changelogs/) +[](https://t.me/routeros_scripts) +[](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=A4ZXBD6YS2W8J) + +[⬅️ Go back to main README](../../README.md) + +> ℹ️️ **Info**: This module can not be used on its own but requires the base +> installation. See [main README](../../README.md) for details. + +Description +----------- + +This module adds support for sending notifications via +[Gotify ↗️](https://gotify.net/). A queue is used to make sure +notifications are not lost on failure but sent later. + +Requirements and installation +----------------------------- + +Just install the module: + + $ScriptInstallUpdate mod/notification-gotify; + +Also deploy the [Gotify server ↗️](https://github.com/gotify/server) and +optionally install a Gotify client on your mobile device. + +Configuration +------------- + +Follow the [Installation ↗️](https://gotify.net/docs/install) instructions +and the [First Login ↗️](https://gotify.net/docs/first-login) setup. Once +you have a user and account you can start creating apps. Each app is an +independent notification feed for a device or application. + + + +On creation apps are assigned a *Token* for authentification, you will need +that in configuration. + +Edit `global-config-overlay`, add `GotifyServer` with your server address +(just the address, no protocol - `https://` is assumed) and `GotifyToken` +with the *Token* from your configured app on the Gotify server. Then reload +the configuration. + +> ℹ️ **Info**: Copy relevant configuration from +> [`global-config`](../../global-config.rsc) (the one without `-overlay`) to +> your local `global-config-overlay` and modify it to your specific needs. + +For a custom service installing an additional certificate may be required. +You may want to install that certificate manually, after finding the +[certificate name from browser](../../CERTIFICATES.md). + +Usage and invocation +-------------------- + +There's nothing special to do. Every script or function sending a notification +will now send it to your Gotify application feed. + +But of course you can use the function to send notifications directly. Give +it a try: + + $SendGotify "Subject..." "Body..."; + +Alternatively this sends a notification with all available and configured +methods: + + $SendNotification "Subject..." "Body..."; + +To use the functions in your own scripts you have to declare them first. +Place this before you call them: + + :global SendGotify; + :global SendNotification; + +In case there is a situation when the queue needs to be purged there is a +function available: + + $PurgeGotifyQueue; + +See also +-------- + +* [Certificate name from browser](../../CERTIFICATES.md) +* [Send notifications via e-mail](notification-email.md) +* [Send notifications via Matrix](notification-matrix.md) +* [Send notifications via Ntfy](notification-ntfy.md) +* [Send notifications via Telegram](notification-telegram.md) + +--- +[⬅️ Go back to main README](../../README.md) +[⬆️ Go back to top](#top) diff --git a/doc/mod/notification-matrix.d/01-authenticate.avif b/doc/mod/notification-matrix.d/01-authenticate.avif Binary files differnew file mode 100644 index 0000000..b897943 --- /dev/null +++ b/doc/mod/notification-matrix.d/01-authenticate.avif diff --git a/doc/mod/notification-matrix.d/02-join-room.avif b/doc/mod/notification-matrix.d/02-join-room.avif Binary files differnew file mode 100644 index 0000000..ad99ffd --- /dev/null +++ b/doc/mod/notification-matrix.d/02-join-room.avif diff --git a/doc/mod/notification-matrix.md b/doc/mod/notification-matrix.md new file mode 100644 index 0000000..da6d6de --- /dev/null +++ b/doc/mod/notification-matrix.md @@ -0,0 +1,140 @@ +Send notifications via Matrix +============================= + +[](https://github.com/eworm-de/routeros-scripts/stargazers) +[](https://github.com/eworm-de/routeros-scripts/network) +[](https://github.com/eworm-de/routeros-scripts/watchers) +[](https://mikrotik.com/download/changelogs/) +[](https://t.me/routeros_scripts) +[](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=A4ZXBD6YS2W8J) + +[⬅️ Go back to main README](../../README.md) + +> ℹ️️ **Info**: This module can not be used on its own but requires the base +> installation. See [main README](../../README.md) for details. + +Description +----------- + +This module adds support for sending notifications via +[Matrix ↗️](https://matrix.org/) via client server api. A queue is used to +make sure notifications are not lost on failure but sent later. + +Requirements and installation +----------------------------- + +Just install the module: + + $ScriptInstallUpdate mod/notification-matrix; + +Also install a Matrix client on at least one of your mobile and/or desktop +devices. Create and setup an account there, we will reference that as +"*general account*" later. + +Configuration +------------- + +Edit `global-config-overlay`, add `MatrixHomeServer`, `MatrixAccessToken` and +`MatrixRoom` - see below on hints how to retrieve this information. Then +reload the configuration. + +> ℹ️ **Info**: Copy relevant configuration from +> [`global-config`](../../global-config.rsc) (the one without `-overlay`) to +> your local `global-config-overlay` and modify it to your specific needs. + +The Matrix server is connected via encrypted https, and certificate +verification is applied. So make sure you have the certificate chain for +your server in device's certificate store. + +The example below is for `matrix.org`, which uses a trust chain from *Google +Trust Services*. Run this to import the required certificate: + + $CertificateAvailable "GTS Root R4"; + +Replace the CA certificate name with what ever is needed for your server. +You may want to find the +[certificate name from browser](../../CERTIFICATES.md). + +### From other device + +If you have setup your Matrix *notification account* before just reuse that. +Copy the relevant configuration to the device to be configured. + +### Setup new account + +As there is no privilege separation you should create a dedicated account +for use with these scripts, in addition to your *general account*. +We will reference that as "*notification account*" in the following steps. + +#### Authenticate + +Matrix user accounts are identified by a unique user id in the form of +`@localpart:domain`. Use that and your password to generate an access token +and write first part of the configuration: + + $SetupMatrixAuthenticate "@example:matrix.org" "v3ry-s3cr3t"; + + + +The configuration is written to a new configuration snippet +`global-config-overlay.d/mod/notification-matrix`. + +#### Join Room + +Every Matix chat is a room, so we have to create one. Do that with your +*general account*, this makes sure your *general account* is the room owner. +Then join the room and invite the *notification account* by its user id +"*@example:matrix.org*". +Look up the *room id* within the Matrix client, it should read like +"*!WUcxpSjKyxSGelouhA:matrix.org*" (starting with an exclamation mark and +ending with the domain). + +Finally make the *notification account* join into the room by accepting +the invite. + + $SetupMatrixJoinRoom "!WUcxpSjKyxSGelouhA:matrix.org"; + + + +The configuration is appended to the configuration snippet +`global-config-overlay.d/mod/notification-matrix`. + +Usage and invocation +-------------------- + +There's nothing special to do. Every script or function sending a notification +will now send it to your Matrix account. + +But of course you can use the function to send notifications directly. Give +it a try: + + $SendMatrix "Subject..." "Body..."; + +Alternatively this sends a notification with all available and configured +methods: + + $SendNotification "Subject..." "Body..."; + +To use the functions in your own scripts you have to declare them first. +Place this before you call them: + + :global SendMatrix; + :global SendNotification; + +In case there is a situation when the queue needs to be purged there is a +function available: + + $PurgeMatrixQueue; + +See also +-------- + +* [Certificate name from browser](../../CERTIFICATES.md) +* [Send notifications via e-mail](notification-email.md) +* [Send notifications via Gotify](notification-gotify.md) +* [Send notifications via Ntfy](notification-ntfy.md) +* [Send notifications via Telegram](notification-telegram.md) + +--- +[⬅️ Go back to main README](../../README.md) +[⬆️ Go back to top](#top) diff --git a/doc/mod/notification-ntfy.md b/doc/mod/notification-ntfy.md new file mode 100644 index 0000000..993501d --- /dev/null +++ b/doc/mod/notification-ntfy.md @@ -0,0 +1,99 @@ +Send notifications via Ntfy +=========================== + +[](https://github.com/eworm-de/routeros-scripts/stargazers) +[](https://github.com/eworm-de/routeros-scripts/network) +[](https://github.com/eworm-de/routeros-scripts/watchers) +[](https://mikrotik.com/download/changelogs/) +[](https://t.me/routeros_scripts) +[](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=A4ZXBD6YS2W8J) + +[⬅️ Go back to main README](../../README.md) + +> ℹ️️ **Info**: This module can not be used on its own but requires the base +> installation. See [main README](../../README.md) for details. + +Description +----------- + +This module adds support for sending notifications via +[Ntfy ↗️](https://ntfy.sh/). A queue is used to make sure +notifications are not lost on failure but sent later. + +Requirements and installation +----------------------------- + +Just install the module: + + $ScriptInstallUpdate mod/notification-ntfy; + +Also install the Ntfy app on your mobile device or use the +[web app ↗️](https://ntfy.sh/app) in a browser of your choice. + +Configuration +------------- + +Creating an account is not required. Just choose a topic and you are good +to go. + +> ⚠️ **Warning**: If you use ntfy without sign-up, the topic is essentially +> a password, so pick something that's not easily guessable. + +Edit `global-config-overlay`, add `NtfyServer` (leave it unchanged, unless +you are self-hosting the service) and `NtfyTopic` with your choosen topic. +Then reload the configuration. + +> ℹ️ **Info**: Copy relevant configuration from +> [`global-config`](../../global-config.rsc) (the one without `-overlay`) to +> your local `global-config-overlay` and modify it to your specific needs. + +Using a paid account or running a server on-premises allows to add additional +basic authentication. Configure `NtfyServerUser` and `NtfyServerPass` for this. +Even authentication via access token is possible, adding it as password with +a blank username. + +Also available is `NtfyServerToken` to add a bearer token for authentication. + +For a custom service installing an additional certificate may be required. +You may want to install that certificate manually, after finding the +[certificate name from browser](../../CERTIFICATES.md). + +Usage and invocation +-------------------- + +There's nothing special to do. Every script or function sending a notification +will now send it to your Ntfy topic. + +But of course you can use the function to send notifications directly. Give +it a try: + + $SendNtfy "Subject..." "Body..."; + +Alternatively this sends a notification with all available and configured +methods: + + $SendNotification "Subject..." "Body..."; + +To use the functions in your own scripts you have to declare them first. +Place this before you call them: + + :global SendNtfy; + :global SendNotification; + +In case there is a situation when the queue needs to be purged there is a +function available: + + $PurgeNtfyQueue; + +See also +-------- + +* [Certificate name from browser](../../CERTIFICATES.md) +* [Send notifications via e-mail](notification-email.md) +* [Send notifications via Gotify](notification-gotify.md) +* [Send notifications via Matrix](notification-matrix.md) +* [Send notifications via Telegram](notification-telegram.md) + +--- +[⬅️ Go back to main README](../../README.md) +[⬆️ Go back to top](#top) diff --git a/doc/mod/notification-telegram.d/getchatid.avif b/doc/mod/notification-telegram.d/getchatid.avif Binary files differnew file mode 100644 index 0000000..7792969 --- /dev/null +++ b/doc/mod/notification-telegram.d/getchatid.avif diff --git a/doc/mod/notification-telegram.d/newbot.avif b/doc/mod/notification-telegram.d/newbot.avif Binary files differnew file mode 100644 index 0000000..1fc7355 --- /dev/null +++ b/doc/mod/notification-telegram.d/newbot.avif diff --git a/doc/mod/notification-telegram.d/setuserpic.avif b/doc/mod/notification-telegram.d/setuserpic.avif Binary files differnew file mode 100644 index 0000000..2017d20 --- /dev/null +++ b/doc/mod/notification-telegram.d/setuserpic.avif diff --git a/doc/mod/notification-telegram.md b/doc/mod/notification-telegram.md new file mode 100644 index 0000000..804104f --- /dev/null +++ b/doc/mod/notification-telegram.md @@ -0,0 +1,124 @@ +Send notifications via Telegram +=============================== + +[](https://github.com/eworm-de/routeros-scripts/stargazers) +[](https://github.com/eworm-de/routeros-scripts/network) +[](https://github.com/eworm-de/routeros-scripts/watchers) +[](https://mikrotik.com/download/changelogs/) +[](https://t.me/routeros_scripts) +[](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=A4ZXBD6YS2W8J) + +[⬅️ Go back to main README](../../README.md) + +> ℹ️️ **Info**: This module can not be used on its own but requires the base +> installation. See [main README](../../README.md) for details. + +Description +----------- + +This module adds support for sending notifications via +[Telegram ↗️](https://telegram.org/) via bot api. A queue is used to make sure +notifications are not lost on failure but sent later. + +Requirements and installation +----------------------------- + +Just install the module: + + $ScriptInstallUpdate mod/notification-telegram; + +Also install Telegram on at least one of your mobile and/or desktop devices +and create an account. + +Configuration +------------- + +Open Telegram, then start a chat with [BotFather ↗️](https://t.me/BotFather) and +create your own bot: + + + +Set that token from *BotFather* (use your own!) to `TelegramTokenId`, for +now just temporarily: + + :set TelegramTokenId "5214364459:AAHLwf1o7ybbKDo6pY24Kd2bZ5rjCakDXTc"; + +Now open a chat with your bot and start it by clicking the `START` button, +then send your first message. Any text will do. On your device run +`$GetTelegramChatId` to retrieve the chat id: + + $GetTelegramChatId; + + + +Finally edit `global-config-overlay`, add `TelegramTokenId` with the token +from *BotFather* and `TelegramChatId` with your retrieved chat id. Then +reload the configuration. + +> ℹ️ **Info**: Copy relevant configuration from +> [`global-config`](../../global-config.rsc) (the one without `-overlay`) to +> your local `global-config-overlay` and modify it to your specific needs. + +### Notifications to a group + +Sending notifications to a group is possible as well. Add your bot to a group +and make it an admin (required for read access!) and send a message and run +`$GetTelegramChatId` again. Then use that chat id (which starts with a dash) +for `TelegramChatId`. + +Groups can enable the `Topics` feature. Use `TelegramThreadId` to send to a +specific topic in a group. + +Usage and invocation +-------------------- + +There's nothing special to do. Every script or function sending a notification +will now send it to your Telegram account. + +But of course you can use the function to send notifications directly. Give +it a try: + + $SendTelegram "Subject..." "Body..."; + +Alternatively this sends a notification with all available and configured +methods: + + $SendNotification "Subject..." "Body..."; + +To use the functions in your own scripts you have to declare them first. +Place this before you call them: + + :global SendTelegram; + :global SendNotification; + +In case there is a situation when the queue needs to be purged there is a +function available: + + $PurgeTelegramQueue; + +Tips & Tricks +------------- + +### Set a profile photo + +You can use a profile photo for your bot to make it recognizable. Open the +chat with [BotFather ↗️](https://t.me/BotFather) and set it there. + + + +Have a look at my +[RouterOS-Scripts Logo Color Changer](https://git.eworm.de/cgit/routeros-scripts/plain/contrib/logo-color.html) +to create a colored version of this scripts' logo. + +See also +-------- + +* [Chat with your router and send commands via Telegram bot](../telegram-chat.md) +* [Send notifications via e-mail](notification-email.md) +* [Send notifications via Gotify](notification-gotify.md) +* [Send notifications via Matrix](notification-matrix.md) +* [Send notifications via Ntfy](notification-ntfy.md) + +--- +[⬅️ Go back to main README](../../README.md) +[⬆️ Go back to top](#top) diff --git a/doc/mod/scriptrunonce.d/hello-world.rsc b/doc/mod/scriptrunonce.d/hello-world.rsc new file mode 100644 index 0000000..6404781 --- /dev/null +++ b/doc/mod/scriptrunonce.d/hello-world.rsc @@ -0,0 +1,3 @@ +#!rsc by RouterOS + +:put ("Hello World from " . [ /system/identity/get name ] . "!"); diff --git a/doc/mod/scriptrunonce.d/scriptrunonce.avif b/doc/mod/scriptrunonce.d/scriptrunonce.avif Binary files differnew file mode 100644 index 0000000..27ccd41 --- /dev/null +++ b/doc/mod/scriptrunonce.d/scriptrunonce.avif diff --git a/doc/mod/scriptrunonce.md b/doc/mod/scriptrunonce.md new file mode 100644 index 0000000..955d12e --- /dev/null +++ b/doc/mod/scriptrunonce.md @@ -0,0 +1,59 @@ +Download script and run it once +=============================== + +[](https://github.com/eworm-de/routeros-scripts/stargazers) +[](https://github.com/eworm-de/routeros-scripts/network) +[](https://github.com/eworm-de/routeros-scripts/watchers) +[](https://mikrotik.com/download/changelogs/) +[](https://t.me/routeros_scripts) +[](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=A4ZXBD6YS2W8J) + +[⬅️ Go back to main README](../../README.md) + +> ℹ️️ **Info**: This module can not be used on its own but requires the base +> installation. See [main README](../../README.md) for details. + +Description +----------- + +This module adds a function that downloads a script, checks for syntax +validity and runs it once. + +Requirements and installation +----------------------------- + +Just install the module: + + $ScriptInstallUpdate mod/scriptrunonce; + +Configuration +------------- + +The optional configuration goes to `global-config-overlay`. + +* `ScriptRunOnceBaseUrl`: base url, prepended to parameter +* `ScriptRunOnceUrlSuffix`: url suffix, appended to parameter + +> ℹ️ **Info**: Copy relevant configuration from +> [`global-config`](../../global-config.rsc) (the one without `-overlay`) to +> your local `global-config-overlay` and modify it to your specific needs. + +If the parameter passed to the function is not a complete URL (starting +with protocol `ftp://`, `http://`, `https://` or `sftp://`) the base-url is +prepended, and file extension `.rsc` and url-suffix are appended. + +Usage and invocation +-------------------- + +The function `$ScriptRunOnce` expects an URL (or name if +`ScriptRunOnceBaseUrl` is given) pointing to a script as parameter. + + $ScriptRunOnce https://git.eworm.de/cgit/routeros-scripts/plain/doc/mod/scriptrunonce.d/hello-world.rsc; + + + +Giving multiple scripts is possible, separated by comma. + +--- +[⬅️ Go back to main README](../../README.md) +[⬆️ Go back to top](#top) diff --git a/doc/mod/ssh-keys-import.md b/doc/mod/ssh-keys-import.md new file mode 100644 index 0000000..344f4bc --- /dev/null +++ b/doc/mod/ssh-keys-import.md @@ -0,0 +1,69 @@ +Import ssh keys for public key authentication +============================================= + +[](https://github.com/eworm-de/routeros-scripts/stargazers) +[](https://github.com/eworm-de/routeros-scripts/network) +[](https://github.com/eworm-de/routeros-scripts/watchers) +[](https://mikrotik.com/download/changelogs/) +[](https://t.me/routeros_scripts) +[](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=A4ZXBD6YS2W8J) + +[⬅️ Go back to main README](../../README.md) + +> ℹ️️ **Info**: This module can not be used on its own but requires the base +> installation. See [main README](../../README.md) for details. + +Description +----------- + +RouterOS supports ssh login with public key authentication. The functions +in this module help importing the keys. + +Requirements and installation +----------------------------- + +Just install the module: + + $ScriptInstallUpdate mod/ssh-keys-import; + +Usage and invocation +-------------------- + +### Import single key from terminal + +Call the function `$SSHKeysImport` with key and user as parameter to +import that key: + + $SSHKeysImport "ssh-ed25519 AAAAC3Nza...ZVugJT user" admin; + $SSHKeysImport "ssh-rsa AAAAB3Nza...QYZk8= user" admin; + +The third part of the key (`user` in this example) is inherited as +`key-owner` in RouterOS. Also the `MD5` fingerprint is recorded, this helps +to audit and verify the available keys. + +> ℹ️️ **Info**: Use `ssh-keygen` to show a fingerprint of an existing public +> key file: `ssh-keygen -l -E md5 -f ~/.ssh/id_ed25519.pub` + +### Import several keys from file + +The functions `$SSHKeysImportFile` can read an `authorized_keys`-style file +and import all the keys. The user given to the function can be overwritting +from comments in the file. Create a file `keys.pub` with this content: + +``` +ssh-ed25519 AAAAC3Nza...3OcN8A user@client +ssh-rsa AAAAB3Nza...ozyts= worker@station +# user=example +ssh-rsa AAAAB3Nza...GXQVk= person@host +``` + +Then import it with: + + $SSHKeysImportFile keys.pub admin; + +This will import the first two keys for user `admin` (as given to function) +and the third one for user `example` (as defined in comment). + +--- +[⬅️ Go back to main README](../../README.md) +[⬆️ Go back to top](#top) |
