diff options
Diffstat (limited to 'doc')
91 files changed, 2771 insertions, 618 deletions
diff --git a/doc/accesslist-duplicates.d/01-example.avif b/doc/accesslist-duplicates.d/01-example.avif Binary files differnew file mode 100644 index 0000000..11b3fc5 --- /dev/null +++ b/doc/accesslist-duplicates.d/01-example.avif diff --git a/doc/accesslist-duplicates.md b/doc/accesslist-duplicates.md index 2189322..a1f9198 100644 --- a/doc/accesslist-duplicates.md +++ b/doc/accesslist-duplicates.md @@ -1,7 +1,17 @@ Find and remove access list duplicates ====================================== -[◀ 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) + +[⬅️ Go back to main README](../README.md) + +> ℹ️️ **Info**: This script can not be used on its own but requires the base +> installation. See [main README](../README.md) for details. Description ----------- @@ -12,14 +22,19 @@ entries in wireless access list. Requirements and installation ----------------------------- -Depending on whether you use CAPsMAN (`/ caps-man`) or local wireless -interface (`/ interface wireless`) you need to install a different script. +Depending on whether you use `wifi` package (`/interface/wifi`), legacy +wifi with CAPsMAN (`/caps-man`) or local wireless interface +(`/interface/wireless`) you need to install a different script. + +For `wifi`: -For CAPsMAN: + $ScriptInstallUpdate accesslist-duplicates.wifi; + +For legacy CAPsMAN: $ScriptInstallUpdate accesslist-duplicates.capsman; -For local interface: +For legacy local interface: $ScriptInstallUpdate accesslist-duplicates.local; @@ -28,16 +43,9 @@ Usage and invocation Run this script from a terminal: - [admin@kalyke] > / system script run accesslist-duplicates.local - Flags: X - disabled - 0 ;;; First entry with identical mac address... - mac-address=00:11:22:33:44:55 interface=any signal-range=-120..120 allow-signal-out-of-range=10s authentication=yes forwarding=yes ap-tx-limit=0 client-tx-limit=0 private-algo=none private-key="" private-pre-shared-key="" management-protection-key="" vlan-mode=default vlan-id=1 - - 1 ;;; Second entry with identical mac address... - mac-address=00:11:22:33:44:55 interface=any signal-range=-120..120 allow-signal-out-of-range=10s authentication=yes forwarding=yes ap-tx-limit=0 client-tx-limit=0 private-algo=none private-key="" private-pre-shared-key="" management-protection-key="" vlan-mode=default vlan-id=1 + /system/script/run accesslist-duplicates.wifi; - Numeric id to remove, any key to skip! - Removing numeric id 1... + See also -------- @@ -45,5 +53,5 @@ See also * [Collect MAC addresses in wireless access list](collect-wireless-mac.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/backup-cloud.d/notification.avif b/doc/backup-cloud.d/notification.avif Binary files differnew file mode 100644 index 0000000..e533908 --- /dev/null +++ b/doc/backup-cloud.d/notification.avif diff --git a/doc/backup-cloud.md b/doc/backup-cloud.md new file mode 100644 index 0000000..be6e06d --- /dev/null +++ b/doc/backup-cloud.md @@ -0,0 +1,76 @@ +Upload backup to Mikrotik cloud +=============================== + +[](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 script can not be used on its own but requires the base +> installation. See [main README](../README.md) for details. + +Description +----------- + +This script uploads +[binary backup to Mikrotik cloud](https://wiki.mikrotik.com/wiki/Manual:IP/Cloud#Backup). + +> ⚠️ **Warning**: The used command can hit errors that a script can with +> workaround only. A notification *should* be sent anyway. But it can result +> in malfunction of fetch command (where all up- and downloads break) for +> some time. Failed notifications are queued then. + +### Sample notification + + + +Requirements and installation +----------------------------- + +Just install the script: + + $ScriptInstallUpdate backup-cloud; + +Configuration +------------- + +The configuration goes to `global-config-overlay`, these are the parameters: + +* `BackupPassword`: password to encrypt the backup with +* `BackupRandomDelay`: delay up to amount of seconds when run from scheduler + +> ℹ️ **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. + +Also notification settings are required for +[e-mail](mod/notification-email.md), +[matrix](mod/notification-matrix.md), +[ntfy](mod/notification-ntfy.md) and/or +[telegram](mod/notification-telegram.md). + +Usage and invocation +-------------------- + +Just run the script: + + /system/script/run backup-cloud; + +Creating a scheduler may be an option: + + /system/scheduler/add interval=1w name=backup-cloud on-event="/system/script/run backup-cloud;" start-time=09:20:00; + +See also +-------- + +* [Send backup via e-mail](backup-email.md) +* [Save configuration to fallback partition](doc/backup-partition.md) +* [Upload backup to server](backup-upload.md) + +--- +[⬅️ Go back to main README](../README.md) +[⬆️ Go back to top](#top) diff --git a/doc/backup-email.md b/doc/backup-email.md new file mode 100644 index 0000000..a506543 --- /dev/null +++ b/doc/backup-email.md @@ -0,0 +1,68 @@ +Send backup 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 script can not be used on its own but requires the base +> installation. See [main README](../README.md) for details. + +Description +----------- + +This script sends binary backup (`/system/backup/save`) and complete +configuration export (`/export terse show-sensitive`) via e-mail. + +Requirements and installation +----------------------------- + +Just install the script and the required module: + + $ScriptInstallUpdate mod/notification-email,backup-email; + +Also make sure you configure +[sending notifications via e-mail](mod/notification-email.md). + +Configuration +------------- + +The configuration goes to `global-config-overlay`, these are the parameters: + +* `BackupSendBinary`: whether to send binary backup +* `BackupSendExport`: whether to send configuration export +* `BackupSendGlobalConfig`: whether to send `global-config-overlay` +* `BackupPassword`: password to encrypt the backup with +* `BackupRandomDelay`: delay up to amount of seconds when run from scheduler + +> ℹ️ **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. + +Usage and invocation +-------------------- + +Just run the script: + + /system/script/run backup-email; + +Creating a scheduler may be an option: + + /system/scheduler/add interval=1w name=backup-email on-event="/system/script/run backup-email;" start-time=09:15:00; + +See also +-------- + +* [Upload backup to Mikrotik cloud](backup-cloud.md) +* [Save configuration to fallback partition](doc/backup-partition.md) +* [Send notifications via e-mail](mod/notification-email.md) +* [Upload backup to server](backup-upload.md) + +--- +[⬅️ Go back to main README](../README.md) +[⬆️ Go back to top](#top) diff --git a/doc/backup-partition.md b/doc/backup-partition.md new file mode 100644 index 0000000..ba20657 --- /dev/null +++ b/doc/backup-partition.md @@ -0,0 +1,61 @@ +Save configuration to fallback partition +======================================== + +[](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 script can not be used on its own but requires the base +> installation. See [main README](../README.md) for details. + +Description +----------- + +This script saves the current configuration to fallback +[partition](https://wiki.mikrotik.com/wiki/Manual:Partitions). + +For this to work you need a device with sufficient flash storage that is +properly partitioned. + +To make you aware of a possible issue a scheduler logging a warning is +added in the backup partition's configuration. You may want to use +[log-forward](log-forward.md) to be notified. + +> ⚠️ **Warning**: Only the configuration is saved to backup partition. +> Every now and then you should copy your installation over for a recent +> RouterOS version! + +Requirements and installation +----------------------------- + +Just install the script: + + $ScriptInstallUpdate backup-partition; + +Usage and invocation +-------------------- + +Just run the script: + + /system/script/run backup-partition; + +Creating a scheduler may be an option: + + /system/scheduler/add interval=1w name=backup-partition on-event="/system/script/run backup-partition;" start-time=09:30:00; + +See also +-------- + +* [Upload backup to Mikrotik cloud](backup-cloud.md) +* [Send backup via e-mail](backup-email.md) +* [Upload backup to server](backup-upload.md) +* [Forward log messages via notification](log-forward.md) + +--- +[⬅️ Go back to main README](../README.md) +[⬆️ Go back to top](#top) diff --git a/doc/backup-upload.d/notification.avif b/doc/backup-upload.d/notification.avif Binary files differnew file mode 100644 index 0000000..83cfb18 --- /dev/null +++ b/doc/backup-upload.d/notification.avif diff --git a/doc/backup-upload.md b/doc/backup-upload.md new file mode 100644 index 0000000..f524adb --- /dev/null +++ b/doc/backup-upload.md @@ -0,0 +1,92 @@ +Upload backup to server +======================= + +[](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 script can not be used on its own but requires the base +> installation. See [main README](../README.md) for details. + +Description +----------- + +This script uploads binary backup (`/system/backup/save`) and complete +configuration export (`/export terse show-sensitive`) to external server. + +> ⚠️ **Warning**: The used command can hit errors that a script can not handle. +> This may result in script termination (where no notification is sent) or +> malfunction of fetch command (where all up- and downloads break) for some +> time. Failed notifications are queued then. + +### Sample notification + + + +Requirements and installation +----------------------------- + +Just install the script: + + $ScriptInstallUpdate backup-upload; + +Configuration +------------- + +The configuration goes to `global-config-overlay`, these are the parameters: + +* `BackupSendBinary`: whether to send binary backup +* `BackupSendExport`: whether to send configuration export +* `BackupSendGlobalConfig`: whether to send `global-config-overlay` +* `BackupPassword`: password to encrypt the backup with +* `BackupRandomDelay`: delay up to amount of seconds when run from scheduler +* `BackupUploadUrl`: url to upload to +* `BackupUploadUser`: username for server authentication +* `BackupUploadPass`: password for server authentication + +> ℹ️ **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. + +Also notification settings are required for +[e-mail](mod/notification-email.md), +[matrix](mod/notification-matrix.md), +[ntfy](mod/notification-ntfy.md) and/or +[telegram](mod/notification-telegram.md). + +### Issues with SFTP client + +The RouterOS SFTP client is picky if it comes to authentication methods. +I had to disable all but password authentication on server side. For openssh +edit `/etc/ssh/sshd_config` and add a directive like this, changed for your +needs: + + Match User mikrotik + AuthenticationMethods password + +Usage and invocation +-------------------- + +Just run the script: + + /system/script/run backup-upload; + +Creating a scheduler may be an option: + + /system/scheduler/add interval=1w name=backup-upload on-event="/system/script/run backup-upload;" start-time=09:25:00; + +See also +-------- + +* [Upload backup to Mikrotik cloud](backup-cloud.md) +* [Send backup via e-mail](backup-email.md) +* [Save configuration to fallback partition](doc/backup-partition.md) + +--- +[⬅️ Go back to main README](../README.md) +[⬆️ Go back to top](#top) diff --git a/doc/bridge-port.md b/doc/bridge-port.md deleted file mode 100644 index 8cbe15b..0000000 --- a/doc/bridge-port.md +++ /dev/null @@ -1,78 +0,0 @@ -Manage ports in bridge -====================== - -[◀ Go back to main README](../README.md) - -Description ------------ - -These scripts are supposed to handle interfaces and switching them from -one bridge to another. - -Requirements and installation ------------------------------ - -Just install the scripts: - - $ScriptInstallUpdate bridge-port-to-default,bridge-port-toggle; - -Configuration -------------- - -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; - -Also dhcp client can be handled: - - / ip dhcp-client add comment="toggle with bridge port" disabled=no interface=en1; - -There is also global configuration: - -* `BridgePortTo`: specify the configuration to be applied by default - -Add a scheduler to start with default setup on system startup: - - / system scheduler add name=bridge-port-to-default on-event="/ system script run bridge-port-to-default;" start-time=startup; - -Usage and invocation --------------------- - -The usage examples show what happens with the configuration from above. - -Running the script `bridge-port-to-default` applies all configuration given -with `default=`: - - / system script run bridge-port-to-default; - -For the three interfaces we get this configuration: - -* The special value `dhcp-client` enables the dhcp client for interface `en1`. The bridge port entry is disabled. -* Interface `en2` is put in bridge `br-intern`. -* Interface `en3` is put in bridge `br-guest`. - -Running the script `bridge-port-toggle` toggles to configuration given -with `alt=`: - - / system script run bridge-port-toggle; - -* Interface `en1` is put in bridge `br-guest`, dhcp client for the interface is disabled. -* Interface `en2` is put in bridge `br-guest`. -* Interface `en3` is unchanged, stays in bridge `br-guest`. - -Running the script `bridge-port-toggle` again toggles back to configuration -given with `default=`. - -More configuration can be loaded by setting `BridgePortTo`: - - :set BridgePortTo "extra"; - / system script run bridge-port-to-default; - -* Interfaces `en1` and `en2` are unchanged. -* Interface `en3` is put in bridge `br-intern`. - ---- -[◀ Go back to main README](../README.md) -[▲ Go back to top](#top) diff --git a/doc/capsman-download-packages.md b/doc/capsman-download-packages.md index 8516ff4..c68900e 100644 --- a/doc/capsman-download-packages.md +++ b/doc/capsman-download-packages.md @@ -1,7 +1,17 @@ Download packages for CAP upgrade from CAPsMAN ============================================= -[◀ 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) + +[⬅️ Go back to main README](../README.md) + +> ℹ️ **Info**: This script can not be used on its own but requires the base +> installation. See [main README](../README.md) for details. Description ----------- @@ -15,33 +25,47 @@ This script automatically downloads these packages. Requirements and installation ----------------------------- -Just install the script on CAPsMAN device: +Make sure you have the `package-path` set in your CAPsMAN configuration, +as that is where packages are downloaded to and where the system expects +them. + +Then just install the script on CAPsMAN device. +Depending on whether you use `wifi` package (`/interface/wifi`) or legacy +wifi with CAPsMAN (`/caps-man`) you need to install a different script. + +For `wifi`: + + $ScriptInstallUpdate capsman-download-packages.wifi; + +For legacy CAPsMAN: + + $ScriptInstallUpdate capsman-download-packages.capsman; + +Optionally add a scheduler to run after startup. For `wifi`: + + /system/scheduler/add name=capsman-download-packages on-event="/system/script/run capsman-download-packages.wifi;" start-time=startup; + +For legacy CAPsMAN: - $ScriptInstallUpdate capsman-download-packages; + /system/scheduler/add name=capsman-download-packages on-event="/system/script/run capsman-download-packages.capsman;" start-time=startup; -Optionally add a scheduler to run after startup: +Packages available in local storage in older version are downloaded +unconditionally. - / system scheduler add name=capsman-download-packages on-event="/ system script run capsman-download-packages;" start-time=startup; +If no packages are found the script downloads a default set of packages: -Only packages available in older version are downloaded. For initial setup -place the required packages to CAPsMAN package path (see -`/ caps-man manager`). The packages can be downloaded from device with -function `$DownloadPackage`, use something like this to download latest -packages to directory `routeros`: + * `wifi`: `routeros` and `wifi-qcom` for *arm* and *arm64*, `wifi-qcom-ac` for *arm* + * legacy CAPsMAN: `routeros` and `wireless` for *arm* and *mipsbe* - $DownloadPackage system "" arm routeros; - $DownloadPackage security "" arm routeros; - [...] - $DownloadPackage system "" mipsbe routeros; - $DownloadPackage security "" mipsbe routeros; - [...] +> ℹ️ **Info**: If you have packages in the directory and things go wrong for +> what ever unknown reason: Remove **all** packages and start over. Usage and invocation -------------------- Run the script manually: - / system script run capsman-download-packages; + /system/script/run capsman-download-packages.wifi; ... or from scheduler. @@ -55,5 +79,5 @@ See also * [Run rolling CAP upgrades from CAPsMAN](capsman-rolling-upgrade.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/capsman-rolling-upgrade.md b/doc/capsman-rolling-upgrade.md index 04952e2..27d855f 100644 --- a/doc/capsman-rolling-upgrade.md +++ b/doc/capsman-rolling-upgrade.md @@ -1,7 +1,17 @@ Run rolling CAP upgrades from CAPsMAN ===================================== -[◀ 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) + +[⬅️ Go back to main README](../README.md) + +> ℹ️ **Info**: This script can not be used on its own but requires the base +> installation. See [main README](../README.md) for details. Description ----------- @@ -17,9 +27,17 @@ parallel. Requirements and installation ----------------------------- -Just install the script: +Just install the script on CAPsMAN device. +Depending on whether you use `wifi` package (`/interface/wifi`) or legacy +wifi with CAPsMAN (`/caps-man`) you need to install a different script. + +For `wifi`: + + $ScriptInstallUpdate capsman-rolling-upgrade.wifi; + +For legacy CAPsMAN: - $ScriptInstallUpdate capsman-rolling-upgrade; + $ScriptInstallUpdate capsman-rolling-upgrade.capsman; Usage and invocation -------------------- @@ -30,7 +48,7 @@ that script when required. Alternatively run it manually: - / system script run capsman-rolling-upgrade; + /system/script/run capsman-rolling-upgrade.wifi; See also -------- @@ -38,5 +56,5 @@ See also * [Download packages for CAP upgrade from CAPsMAN](capsman-download-packages.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/certificate-renew-issued.md b/doc/certificate-renew-issued.md index e460ce1..91a1914 100644 --- a/doc/certificate-renew-issued.md +++ b/doc/certificate-renew-issued.md @@ -1,7 +1,17 @@ Renew locally issued certificates ================================= -[◀ 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) + +[⬅️ Go back to main README](../README.md) + +> ℹ️ **Info**: This script can not be used on its own but requires the base +> installation. See [main README](../README.md) for details. Description ----------- @@ -25,12 +35,16 @@ parameter: * `CertRenewPass`: an array holding individual passphrases for certificates +> ℹ️ **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. + Usage and invocation -------------------- Run the script to renew certificates issued from a local CA. - / system script run certificate-renew-issued; + /system/script/run certificate-renew-issued; Only scripts with a remaining lifetime of three weeks or less are renewed. The old certificate is revoked automatically. If a passphrase for a specific @@ -43,5 +57,5 @@ See also * [Renew certificates and notify on expiration](check-certificates.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/check-certificates.d/notification.avif b/doc/check-certificates.d/notification.avif Binary files differnew file mode 100644 index 0000000..7c250da --- /dev/null +++ b/doc/check-certificates.d/notification.avif diff --git a/doc/check-certificates.md b/doc/check-certificates.md index 318805d..636f719 100644 --- a/doc/check-certificates.md +++ b/doc/check-certificates.md @@ -1,7 +1,17 @@ Renew certificates and notify on expiration =========================================== -[◀ 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) + +[⬅️ Go back to main README](../README.md) + +> ℹ️ **Info**: This script can not be used on its own but requires the base +> installation. See [main README](../README.md) for details. Description ----------- @@ -9,6 +19,10 @@ Description This script tries to download and renew certificates, then notifies about certificates that are still about to expire. +### Sample notification + + + Requirements and installation ----------------------------- @@ -19,32 +33,59 @@ Just install the script: Configuration ------------- -The expiry notifications just require notification settings for e-mail and -telegram. - For automatic download and renewal of certificates you need configuration in `global-config-overlay`, these are the parameters: * `CertRenewPass`: an array of passphrases to try +* `CertRenewTime`: on what remaining time to try a renew * `CertRenewUrl`: the url to download certificates from +* `CertWarnTime`: on what remaining time to warn via notification + +> ℹ️ **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. + +Certificates on the web server should be named by their common name, like +`CN.pem` (`PEM` format) or`CN.p12` (`PKCS#12` format). Alternatively any +subject alternative name (aka *Subject Alt Name* or *SAN*) can be used. -Certificates on the web server should be named `CN.pem` (`PEM` format) or -`CN.p12` (`PKCS#12` format). +Also notification settings are required for +[e-mail](mod/notification-email.md), +[matrix](mod/notification-matrix.md), +[ntfy](mod/notification-ntfy.md) and/or +[telegram](mod/notification-telegram.md). Usage and invocation -------------------- Just run the script: - / system script run check-certificates; + /system/script/run check-certificates; ... or create a scheduler for periodic execution: - / system scheduler add interval=1d name=check-certificates on-event="/ system script run check-certificates;" start-time=startup; + /system/scheduler/add interval=1d name=check-certificates on-event="/system/script/run check-certificates;" start-time=startup; + + +Tips & Tricks +------------- + +### Schedule at startup + +The script checks for full connectivity before acting, so scheduling at +startup is perfectly valid: + + /system/scheduler/add name=check-certificates@startup on-event="/system/script/run check-certificates;" start-time=startup; + +### Initial import -Alternatively running on startup may be desired: +Given you have a certificate on you server, you can use `check-certificates` +for the initial import. Just create a *dummy* certificate with short lifetime +that matches criteria to be renewed: - / system scheduler add name=check-certificates-startup on-event="/ system script run check-certificates;" start-time=startup; + /certificate/add name=example.com common-name=example.com days-valid=1; + /certificate/sign example.com; + /system/script/run check-certificates; See also -------- @@ -52,5 +93,5 @@ See also * [Renew locally issued certificates](certificate-renew-issued.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/check-health.d/notification-01-cpu-utilization-high.avif b/doc/check-health.d/notification-01-cpu-utilization-high.avif Binary files differnew file mode 100644 index 0000000..326e7fe --- /dev/null +++ b/doc/check-health.d/notification-01-cpu-utilization-high.avif diff --git a/doc/check-health.d/notification-02-cpu-utilization-ok.avif b/doc/check-health.d/notification-02-cpu-utilization-ok.avif Binary files differnew file mode 100644 index 0000000..811ccd7 --- /dev/null +++ b/doc/check-health.d/notification-02-cpu-utilization-ok.avif diff --git a/doc/check-health.d/notification-03-ram-utilization-high.avif b/doc/check-health.d/notification-03-ram-utilization-high.avif Binary files differnew file mode 100644 index 0000000..59155c5 --- /dev/null +++ b/doc/check-health.d/notification-03-ram-utilization-high.avif diff --git a/doc/check-health.d/notification-04-ram-utilization-ok.avif b/doc/check-health.d/notification-04-ram-utilization-ok.avif Binary files differnew file mode 100644 index 0000000..d995b9a --- /dev/null +++ b/doc/check-health.d/notification-04-ram-utilization-ok.avif diff --git a/doc/check-health.d/notification-05-voltage.avif b/doc/check-health.d/notification-05-voltage.avif Binary files differnew file mode 100644 index 0000000..17a385b --- /dev/null +++ b/doc/check-health.d/notification-05-voltage.avif diff --git a/doc/check-health.d/notification-06-temperature-high.avif b/doc/check-health.d/notification-06-temperature-high.avif Binary files differnew file mode 100644 index 0000000..60d3802 --- /dev/null +++ b/doc/check-health.d/notification-06-temperature-high.avif diff --git a/doc/check-health.d/notification-07-temperature-ok.avif b/doc/check-health.d/notification-07-temperature-ok.avif Binary files differnew file mode 100644 index 0000000..4afed02 --- /dev/null +++ b/doc/check-health.d/notification-07-temperature-ok.avif diff --git a/doc/check-health.d/notification-08-psu-fail.avif b/doc/check-health.d/notification-08-psu-fail.avif Binary files differnew file mode 100644 index 0000000..ad049ac --- /dev/null +++ b/doc/check-health.d/notification-08-psu-fail.avif diff --git a/doc/check-health.d/notification-09-psu-ok.avif b/doc/check-health.d/notification-09-psu-ok.avif Binary files differnew file mode 100644 index 0000000..26f5a74 --- /dev/null +++ b/doc/check-health.d/notification-09-psu-ok.avif diff --git a/doc/check-health.md b/doc/check-health.md index 37f8e34..f94a0bf 100644 --- a/doc/check-health.md +++ b/doc/check-health.md @@ -1,7 +1,17 @@ Notify about health state ========================= -[◀ 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) + +[⬅️ Go back to main README](../README.md) + +> ℹ️ **Info**: This script can not be used on its own but requires the base +> installation. See [main README](../README.md) for details. Description ----------- @@ -9,16 +19,46 @@ Description This script is run from scheduler periodically, sending notification on health related events: +* high CPU utilization +* high RAM utilization (low available RAM) * voltage jumps up or down more than configured threshold +* voltage drops below hard lower limit * power supply failed or recovered * temperature is above or below threshold Note that bad initial state will not trigger an event. -Only sensors available in hardware can be checked. See what your -hardware supports: +Monitoring CPU and RAM utilization (available processing and memory +resources) works on all devices. Other than that only sensors available +in hardware can be checked. See what your hardware supports: + + /system/health/print; + +### Sample notifications + +#### CPU utilization + + + + +#### RAM utilization (low available RAM) + + + - / system health print; +#### Voltage + + + +#### Temperature + + + + +#### PSU state + + + Requirements and installation ----------------------------- @@ -26,18 +66,31 @@ Requirements and installation Just install the script and create a scheduler: $ScriptInstallUpdate check-health; - / system scheduler add interval=1m name=check-health on-event="/ system script run check-health;" start-time=startup; + /system/scheduler/add interval=53s name=check-health on-event="/system/script/run check-health;" start-time=startup; + +> ℹ️ **Info**: Running lots of scripts simultaneously can tamper the +> precision of cpu utilization, escpecially on devices with limited +> resources. Thus an unusual interval is used here. Configuration ------------- -The configuration goes to `global-config-overlay`, These are the parameters: +The configuration goes to `global-config-overlay`, these are the parameters: * `CheckHealthTemperature`: an array specifying temperature thresholds for sensors +* `CheckHealthVoltageLow`: value (in volt*10) giving a hard lower limit * `CheckHealthVoltagePercent`: percentage value to trigger voltage jumps -Also notification settings are required for e-mail and telegram. +> ℹ️ **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. + +Also notification settings are required for +[e-mail](mod/notification-email.md), +[matrix](mod/notification-matrix.md), +[ntfy](mod/notification-ntfy.md) and/or +[telegram](mod/notification-telegram.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/check-lte-firmware-upgrade.d/notification.avif b/doc/check-lte-firmware-upgrade.d/notification.avif Binary files differnew file mode 100644 index 0000000..c440da5 --- /dev/null +++ b/doc/check-lte-firmware-upgrade.d/notification.avif diff --git a/doc/check-lte-firmware-upgrade.md b/doc/check-lte-firmware-upgrade.md index c71dee5..59a62c7 100644 --- a/doc/check-lte-firmware-upgrade.md +++ b/doc/check-lte-firmware-upgrade.md @@ -1,7 +1,17 @@ Notify on LTE firmware upgrade ============================== -[◀ 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) + +[⬅️ Go back to main README](../README.md) + +> ℹ️ **Info**: This script can not be used on its own but requires the base +> installation. See [main README](../README.md) for details. Description ----------- @@ -14,6 +24,10 @@ upgrades. Currently supported LTE hardware: * R11e-4G * R11e-LTE6 +### Sample notification + + + Requirements and installation ----------------------------- @@ -23,12 +37,15 @@ Just install the script: ... and create a scheduler: - / system scheduler add interval=1d name=check-lte-firmware-upgrade on-event="/ system script run check-lte-firmware-upgrade;" start-time=startup; + /system/scheduler/add interval=1d name=check-lte-firmware-upgrade on-event="/system/script/run check-lte-firmware-upgrade;" start-time=startup; Configuration ------------- -Notification setting are required for e-mail and telegram. +Also notification settings are required for +[e-mail](mod/notification-email.md), +[matrix](mod/notification-matrix.md) and/or +[telegram](mod/notification-telegram.md). See also -------- @@ -37,5 +54,5 @@ See also * [Install LTE firmware upgrade](unattended-lte-firmware-upgrade.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/check-routeros-update.d/notification.avif b/doc/check-routeros-update.d/notification.avif Binary files differnew file mode 100644 index 0000000..50317cf --- /dev/null +++ b/doc/check-routeros-update.d/notification.avif diff --git a/doc/check-routeros-update.md b/doc/check-routeros-update.md index bd25ab1..f9d485c 100644 --- a/doc/check-routeros-update.md +++ b/doc/check-routeros-update.md @@ -1,7 +1,17 @@ Notify on RouterOS update ========================= -[◀ 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) + +[⬅️ Go back to main README](../README.md) + +> ℹ️ **Info**: This script can not be used on its own but requires the base +> installation. See [main README](../README.md) for details. Description ----------- @@ -11,11 +21,24 @@ The primary use of this script is to notify about RouterOS updates. Run from a terminal you can start the update process or schedule it. Centrally managing update process of several devices is possibly by -specifying versions safe to be updated on a web server. +specifying versions safe to be updated on a web server. Versions seen +in neighbor discovery can be specified to be safe as well. Also installing patch updates (where just last digit is increased) automatically is supported. +> ⚠️ **Warning**: Installing updates is important from a security point +> of view. At the same time it can be source of serve breakage. So test +> versions in lab and read +> [changelog](https://mikrotik.com/download/changelogs/) and +> [forum](https://forum.mikrotik.com/viewforum.php?f=21) before deploying +> to your production environment! Automatic updates should be handled +> with care! + +### Sample notification + + + Requirements and installation ----------------------------- @@ -25,36 +48,60 @@ Just install the script: And add a scheduler for automatic update notification: - / system scheduler add interval=1d name=check-routeros-update on-event="/ system script run check-routeros-update;" start-time=startup; + /system/scheduler/add interval=1d name=check-routeros-update on-event="/system/script/run check-routeros-update;" start-time=startup; Configuration ------------- -Configuration is required only if you want to control update process with -safe versions from a web server. The configuration goes to -`global-config-overlay`, this is the parameter: - -* `SafeUpdateNeighbor`: install updates automatically if seen in neighbor list -* `SafeUpdatePatch`: install patch updates automatically -* `SafeUpdateUrl`: url to check for safe update, the channel (`long-term`, -`stable` or `testing`) is appended +No extra configuration is required to receive notifications. Several +mechanisms are availalbe to enable automatic installation of updates. +The configuration goes to `global-config-overlay`, these are the parameters: + +* `SafeUpdateNeighbor`: install updates automatically if at least one other + device is seen in neighbor list with new version +* `SafeUpdateNeighborIdentity`: regular expression to match identity for + trusted devices, leave empty to match all +* `SafeUpdatePatch`: install patch updates (where just last digit changes) + automatically +* `SafeUpdateUrl`: url on webserver to check for safe update, the channel + (`long-term`, `stable` or `testing`) is appended +* `SafeUpdateAll`: install **all** updates automatically + +> ℹ️ **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. + +Also notification settings are required for +[e-mail](mod/notification-email.md), +[matrix](mod/notification-matrix.md), +[ntfy](mod/notification-ntfy.md) and/or +[telegram](mod/notification-telegram.md). Usage and invocation -------------------- Be notified when run from scheduler or run it manually: - / system script run check-routeros-update; + /system/script/run check-routeros-update; If an update is found you can install it right away. Installing script [packages-update](packages-update.md) gives extra options. +Tips & Tricks +------------- + +The script checks for full connectivity before acting, so scheduling at +startup is perfectly valid: + + /system/scheduler/add name=check-routeros-update@startup on-event="/system/script/run check-routeros-update;" start-time=startup; + See also -------- +* [Automatically upgrade firmware and reboot](firmware-upgrade-reboot.md) * [Manage system update](packages-update.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/cloud-backup.md b/doc/cloud-backup.md index 1417242..e161cfa 100644 --- a/doc/cloud-backup.md +++ b/doc/cloud-backup.md @@ -1,47 +1 @@ -Upload backup to Mikrotik cloud -=============================== - -[◀ Go back to main README](../README.md) - -Description ------------ - -This script uploads [binary backup to Mikrotik cloud](https://wiki.mikrotik.com/wiki/Manual:IP/Cloud#Backup). - -Requirements and installation ------------------------------ - -Just install the script: - - $ScriptInstallUpdate cloud-backup; - -Configuration -------------- - -The configuration goes to `global-config-overlay`, these are the parameters: - -* `BackupPassword`: password to encrypt the backup with -* `BackupRandomDelay`: delay up to amount of seconds when run from scheduler - -Also notification settings are required for e-mail and telegram. - -Usage and invocation --------------------- - -Just run the script: - - / system script run cloud-backup; - -Creating a scheduler may be an option: - - / system scheduler add interval=1w name=cloud-backup on-event="/ system script run cloud-backup;" start-time=09:20:00; - -See also --------- - -* [Send backup via e-mail](email-backup.md) -* [Upload backup to server](upload-backup.md) - ---- -[◀ Go back to main README](../README.md) -[▲ Go back to top](#top) +This script has been renamed. Please see [backup-cloud](backup-cloud.md). diff --git a/doc/collect-wireless-mac.d/notification.avif b/doc/collect-wireless-mac.d/notification.avif Binary files differnew file mode 100644 index 0000000..a2833f0 --- /dev/null +++ b/doc/collect-wireless-mac.d/notification.avif diff --git a/doc/collect-wireless-mac.md b/doc/collect-wireless-mac.md index 45489bf..57032d8 100644 --- a/doc/collect-wireless-mac.md +++ b/doc/collect-wireless-mac.md @@ -1,7 +1,17 @@ Collect MAC addresses in wireless access list ============================================= -[◀ 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) + +[⬅️ Go back to main README](../README.md) + +> ℹ️ **Info**: This script can not be used on its own but requires the base +> installation. See [main README](../README.md) for details. Description ----------- @@ -12,17 +22,26 @@ address list. In addition a notification is sent. By default the access list entry is disabled, but you can easily enable and modify it to your needs. +### Sample notification + + + Requirements and installation ----------------------------- -Depending on whether you use CAPsMAN (`/ caps-man`) or local wireless -interface (`/ interface wireless`) you need to install a different script. +Depending on whether you use `wifi` package (`/interface/wifi`), legacy +wifi with CAPsMAN (`/caps-man`) or local wireless interface +(`/interface/wireless`) you need to install a different script. + +For `wifi`: + + $ScriptInstallUpdate collect-wireless-mac.wifi; -For CAPsMAN: +For legacy CAPsMAN: $ScriptInstallUpdate collect-wireless-mac.capsman; -For local interface: +For legacy local interface: $ScriptInstallUpdate collect-wireless-mac.local; @@ -33,7 +52,11 @@ On first run a disabled access list entry acting as marker (with comment "`--- collected above ---`") is added. Move this entry to define where new entries are to be added. -Also notification settings are required for e-mail and telegram. +Also notification settings are required for +[e-mail](mod/notification-email.md), +[matrix](mod/notification-matrix.md), +[ntfy](mod/notification-ntfy.md) and/or +[telegram](mod/notification-telegram.md). Usage and invocation -------------------- @@ -50,5 +73,5 @@ See also * [Run other scripts on DHCP lease](lease-script.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/daily-psk.d/notification.avif b/doc/daily-psk.d/notification.avif Binary files differnew file mode 100644 index 0000000..dd0b1b6 --- /dev/null +++ b/doc/daily-psk.d/notification.avif diff --git a/doc/daily-psk.md b/doc/daily-psk.md index d472269..3894d52 100644 --- a/doc/daily-psk.md +++ b/doc/daily-psk.md @@ -1,7 +1,17 @@ Use wireless network with daily psk =================================== -[◀ 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) + +[⬅️ Go back to main README](../README.md) + +> ℹ️ **Info**: This script can not be used on its own but requires the base +> installation. See [main README](../README.md) for details. Description ----------- @@ -9,26 +19,37 @@ Description This script is supposed to provide a wifi network which changes the passphrase to a pseudo-random string daily. +### Sample notification + + + Requirements and installation ----------------------------- Just install this script. -Depending on whether you use CAPsMAN (`/ caps-man`) or local wireless -interface (`/ interface wireless`) you need to install a different script. +Depending on whether you use `wifi` package (`/interface/wifi`), legacy +wifi with CAPsMAN (`/caps-man`) or local wireless interface +(`/interface/wireless`) you need to install a different script and add +schedulers to run the script: -For CAPsMAN: +For `wifi`: - $ScriptInstallUpdate daily-psk.capsman; + $ScriptInstallUpdate daily-psk.wifi; + /system/scheduler/add interval=1d name=daily-psk on-event="/system/script/run daily-psk.wifi;" start-time=03:00:00; + /system/scheduler/add name=daily-psk@startup on-event="/system/script/run daily-psk.wifi;" start-time=startup; -For local interface: +For legacy CAPsMAN: - $ScriptInstallUpdate daily-psk.local; + $ScriptInstallUpdate daily-psk.capsman; + /system/scheduler/add interval=1d name=daily-psk on-event="/system/script/run daily-psk.capsman;" start-time=03:00:00; + /system/scheduler/add name=daily-psk@startup on-event="/system/script/run daily-psk.capsman;" start-time=startup; -And add schedulers to run the script: +For legacy local interface: - / system scheduler add interval=1d name=daily-psk-nightly on-event="/ system script run daily-psk.local;" start-date=may/23/2018 start-time=03:00:00; - / system scheduler add name=daily-psk-startup on-event="/ system script run daily-psk.local;" start-time=startup; + $ScriptInstallUpdate daily-psk.local; + /system/scheduler/add interval=1d name=daily-psk on-event="/system/script/run daily-psk.local;" start-time=03:00:00; + /system/scheduler/add name=daily-psk@startup on-event="/system/script/run daily-psk.local;" start-time=startup; These will update the passphrase on boot and nightly at 3:00. @@ -40,12 +61,28 @@ The configuration goes to `global-config-overlay`, these are the parameters: * `DailyPskMatchComment`: pattern to match the wireless access list comment * `DailyPskSecrets`: an array with pseudo random strings -Then add an access list entry: +> ℹ️ **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. + +Then add an access list entry. For `wifi`: + + /interface/wifi/access-list/add comment="Daily PSK" ssid-regexp="-guest\$" passphrase="ToBeChangedDaily"; + +For legacy CAPsMAN: + + /caps-man/access-list/add comment="Daily PSK" ssid-regexp="-guest\$" private-passphrase="ToBeChangedDaily"; + +For legacy local interface: - / interface wireless access-list add comment="Daily PSK" interface=wl-daily private-pre-shared-key="ToBeChangedDaily"; + /interface/wireless/access-list/add comment="Daily PSK" interface=wl-daily private-pre-shared-key="ToBeChangedDaily"; -Also notification settings are required for e-mail and telegram. +Also notification settings are required for +[e-mail](mod/notification-email.md), +[trix](mod/notification-matrix.md), +[ntfy](mod/notification-ntfy.md) and/or +[telegram](mod/notification-telegram.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/dhcp-lease-comment.md b/doc/dhcp-lease-comment.md index caba7d6..f95b124 100644 --- a/doc/dhcp-lease-comment.md +++ b/doc/dhcp-lease-comment.md @@ -1,7 +1,17 @@ Comment DHCP leases with info from access list ============================================== -[◀ 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) + +[⬅️ Go back to main README](../README.md) + +> ℹ️ **Info**: This script can not be used on its own but requires the base +> installation. See [main README](../README.md) for details. Description ----------- @@ -12,14 +22,19 @@ from wireless access list. Requirements and installation ----------------------------- -Depending on whether you use CAPsMAN (`/ caps-man`) or local wireless -interface (`/ interface wireless`) you need to install a different script. +Depending on whether you use `wifi` package (`/interface/wifi`), legacy +wifi with CAPsMAN (`/caps-man`) or local wireless interface +(`/interface/wireless`) you need to install a different script. + +For `wifi`: + + $ScriptInstallUpdate dhcp-lease-comment.wifi; -For CAPsMAN: +For legacy CAPsMAN: $ScriptInstallUpdate dhcp-lease-comment.capsman; -For local interface: +For legacy local interface: $ScriptInstallUpdate dhcp-lease-comment.local; @@ -45,5 +60,5 @@ See also * [Run other scripts on DHCP lease](lease-script.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/dhcp-to-dns.md b/doc/dhcp-to-dns.md index 699b6a5..13d5ef3 100644 --- a/doc/dhcp-to-dns.md +++ b/doc/dhcp-to-dns.md @@ -1,12 +1,24 @@ Create DNS records for DHCP leases ================================== -[◀ 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) + +[⬅️ Go back to main README](../README.md) + +> ℹ️ **Info**: This script can not be used on its own but requires the base +> installation. See [main README](../README.md) for details. Description ----------- -This script adds (and removes) dns records based on dhcp server leases. +This script adds (and updates & removes) dns records based on dhcp server +leases. An A record based on mac address is created for all bound lease, +additionally a CNAME record is created from host name if available. Requirements and installation ----------------------------- @@ -20,7 +32,7 @@ Then run it from dhcp server as lease script. You may want to use A scheduler cares about cleanup: - / system scheduler add interval=15m name=dhcp-to-dns on-event="/ system script run dhcp-to-dns;" start-time=startup; + /system/scheduler/add interval=15m name=dhcp-to-dns on-event="/system/script/run dhcp-to-dns;" start-time=startup; Configuration ------------- @@ -29,20 +41,53 @@ On first run a disabled static dns record acting as marker (with comment "`--- dhcp-to-dns above ---`") is added. Move this entry to define where new entries are to be added. -The configuration goes to `global-config-overlay`, these are the parameters: +The configuration goes to dhcp server's network definition. The domain is +used to form the dns name: + + /ip/dhcp-server/network/add address=10.0.0.0/24 domain=example.com; + +A bound lease for mac address `00:11:22:33:44:55` with ip address +`10.0.0.50` would result in an A record `00-11-22-33-44-55.example.com` +pointing to the given ip address. + +Additional options can be given from comment, to add an extra level in +dns name or define a different domain. + + /ip/dhcp-server/network/add address=10.0.0.0/24 domain=example.com comment="domain=another-domain.com, name-extra=dhcp"; + +This example would result in name `00-11-22-33-44-55.dhcp.another-domain.com` +for the same lease. + +If no domain is found in dhcp server's network definition a fallback from +`global-config-overlay` is used. This is the parameter: * `Domain`: the domain used for dns records -* `HostNameInZone`: whether or not to add the dhcp/dns server's hostname -* `PrefixInZone`: whether or not to add prefix `dhcp` -* `ServerNameInZone`: whether or not to add DHCP server name + +> ℹ️ **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. + +### Host name from DHCP lease comment + +Overwriting the host name from dhcp lease comment is supported, just add +something like `hostname=new-hostname` in comment, and separate it by comma +from other information if required: + + /ip/dhcp-server/lease/add address=10.0.0.50 comment="my device, hostname=new-hostname" mac-address=00:11:22:33:44:55 server=dhcp; + +Note this information can be configured in wireless access list with +[dhcp-lease-comment](dhcp-lease-comment.md), though it comes with a delay +then due to script execution order. Decrease the scheduler interval to +reduce the effect. See also -------- * [Collect MAC addresses in wireless access list](collect-wireless-mac.md) * [Comment DHCP leases with info from access list](dhcp-lease-comment.md) +* [Create DNS records for IPSec peers](ipsec-to-dns.md) * [Run other scripts on DHCP lease](lease-script.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/early-errors.md b/doc/early-errors.md index a16da7d..b3c6800 100644 --- a/doc/early-errors.md +++ b/doc/early-errors.md @@ -1,11 +1,2 @@ -Send notification with early errors -=================================== - -[◀ Go back to main README](../README.md) - -This script has been replace. Please migrate to +This script has been replaced. Please migrate to [Forward log messages via notification](log-forward.md). - ---- -[◀ Go back to main README](../README.md) -[▲ Go back to top](#top) diff --git a/doc/email-backup.md b/doc/email-backup.md index 4b769ec..d674743 100644 --- a/doc/email-backup.md +++ b/doc/email-backup.md @@ -1,53 +1 @@ -Send backup via e-mail -====================== - -[◀ Go back to main README](../README.md) - -Description ------------ - -This script sends binary backup (`/ system backup save`) and complete -configuration export (`/ export terse`) via e-mail. - - -Requirements and installation ------------------------------ - -Just install the script: - - $ScriptInstallUpdate email-backup; - -Configuration -------------- - -The configuration goes to `global-config-overlay`, these are the parameters: - -* `BackupSendBinary`: whether to send binary backup -* `BackupSendExport`: whether to send configuration export -* `BackupPassword`: password to encrypt the backup with -* `BackupRandomDelay`: delay up to amount of seconds when run from scheduler -* `EmailBackupTo`: e-mail address to send to -* `EmailBackupCc`: e-mail address(es) to send in copy - -Also valid e-mail settings in `/ tool e-mail` are required to send mails. - -Usage and invocation --------------------- - -Just run the script: - - / system script run email-backup; - -Creating a scheduler may be an option: - - / system scheduler add interval=1w name=email-backup on-event="/ system script run email-backup;" start-time=09:15:00; - -See also --------- - -* [Upload backup to Mikrotik cloud](cloud-backup.md) -* [Upload backup to server](upload-backup.md) - ---- -[◀ Go back to main README](../README.md) -[▲ Go back to top](#top) +This script has been renamed. Please see [backup-email](backup-email.md).
\ No newline at end of file diff --git a/doc/firmware-upgrade-reboot.md b/doc/firmware-upgrade-reboot.md new file mode 100644 index 0000000..bac17a7 --- /dev/null +++ b/doc/firmware-upgrade-reboot.md @@ -0,0 +1,43 @@ +Automatically upgrade firmware and reboot +========================================= + +[](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 script can not be used on its own but requires the base +> installation. See [main README](../README.md) for details. + +Description +----------- + +RouterOS and firmware are upgraded separately, activating the latter +requires an extra reboot. This script handles upgrade and reboot. + +> ⚠️ **Warning**: This *should* be bullet proof, but I can not guarantee. In +> worst case it has potential to cause a boot loop, so handle with care! + +Requirements and installation +----------------------------- + +Just install the script and create a scheduler: + + $ScriptInstallUpdate firmware-upgrade-reboot; + /system/scheduler/add name=firmware-upgrade-reboot on-event="/system/script/run firmware-upgrade-reboot;" start-time=startup; + +Enjoy firmware being up to date and in sync with RouterOS. + +See also +-------- + +* [Notify on RouterOS update](check-routeros-update.md) +* [Manage system update](packages-update.md) + +--- +[⬅️ Go back to main README](../README.md) +[⬆️ Go back to top](#top) diff --git a/doc/fw-addr-lists.md b/doc/fw-addr-lists.md new file mode 100644 index 0000000..ac34c88 --- /dev/null +++ b/doc/fw-addr-lists.md @@ -0,0 +1,132 @@ +Download, import and update firewall address-lists +================================================== + +[](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 script can not be used on its own but requires the base +> installation. See [main README](../README.md) for details. + +Description +----------- + +This script downloads, imports and updates firewall address-lists. Its main +purpose is to block attacking ip addresses, spam hosts, command-and-control +servers and similar malicious entities. The default configuration contains +lists from [abuse.ch](https://abuse.ch/) and +[dshield.org](https://dshield.org/), and +lists from [spamhaus.org](https://spamhaus.org/) are prepared. + +The address-lists are updated in place, so after initial import you will not +see situation when the lists are not populated. + +To mitigate man-in-the-middle attacks with altered lists the server's +certificate is checked. + +> ⚠️ **Warning**: The script does not limit the size of a list, but keep in +> mind that huge lists can exhaust your device's resources (RAM and CPU), +> and may take a long time to process. + +Requirements and installation +----------------------------- + +Just install the script: + + $ScriptInstallUpdate fw-addr-lists; + +And add two schedulers, first one for initial import after startup, second +one for subsequent updates: + + /system/scheduler/add name="fw-addr-lists@startup" start-time=startup on-event="/system/script/run fw-addr-lists;"; + /system/scheduler/add name="fw-addr-lists" start-time=startup interval=2h on-event="/system/script/run fw-addr-lists;"; + +> ℹ️ **Info**: Modify the interval to your needs, but it is recommended to +> use less than half of the configured timeout for expiration. + +Configuration +------------- + +The configuration goes to `global-config-overlay`, these are the parameters: + +* `FwAddrLists`: a list of firewall address-lists to download and import +* `FwAddrListTimeOut`: the timeout for expiration without renew + +> ℹ️ **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. + +Naming a certificate for a list makes the script verify the server +certificate, so you should add that if possible. Some certificates are +available in my repository and downloaded automatically. Import it manually +(menu `/certificate/`) if missing. + +Create firewall rules to process the packets that are related to addresses +from address-lists. + +### IPv4 rules + +This rejects the packets from and to IPv4 addresses listed in +address-list `block`. + + /ip/firewall/filter/add chain=input src-address-list=block action=reject reject-with=icmp-admin-prohibited; + /ip/firewall/filter/add chain=forward src-address-list=block action=reject reject-with=icmp-admin-prohibited; + /ip/firewall/filter/add chain=forward dst-address-list=block action=reject reject-with=icmp-admin-prohibited; + /ip/firewall/filter/add chain=output dst-address-list=block action=reject reject-with=icmp-admin-prohibited; + +You may want to have an address-list to allow specific addresses, as prepared +with a list `allow`. In fact you can use any list name, just change the +default ones or add your own - matching in configuration and firewall rules. + + /ip/firewall/filter/add chain=input src-address-list=allow action=accept; + /ip/firewall/filter/add chain=forward src-address-list=allow action=accept; + /ip/firewall/filter/add chain=forward dst-address-list=allow action=accept; + /ip/firewall/filter/add chain=output dst-address-list=allow action=accept; + +Modify these for your needs, but **most important**: Move the rules up in +chains and make sure they actually take effect as expected! + +Alternatively handle the packets in firewall's raw section if you prefer: + + /ip/firewall/raw/add chain=prerouting src-address-list=block action=drop; + /ip/firewall/raw/add chain=prerouting dst-address-list=block action=drop; + /ip/firewall/raw/add chain=output dst-address-list=block action=drop; + +> ⚠️ **Warning**: Just again... The order of firewall rules is important. Make +> sure they actually take effect as expected! + +### IPv6 rules + +These are the same rules, but for IPv6. + +Reject packets in address-list `block`: + + /ipv6/firewall/filter/add chain=input src-address-list=block action=reject reject-with=icmp-admin-prohibited; + /ipv6/firewall/filter/add chain=forward src-address-list=block action=reject reject-with=icmp-admin-prohibited; + /ipv6/firewall/filter/add chain=forward dst-address-list=block action=reject reject-with=icmp-admin-prohibited; + /ipv6/firewall/filter/add chain=output dst-address-list=block action=reject reject-with=icmp-admin-prohibited; + +Allow packets in address-list `allow`: + + /ipv6/firewall/filter/add chain=input src-address-list=allow action=accept; + /ipv6/firewall/filter/add chain=forward src-address-list=allow action=accept; + /ipv6/firewall/filter/add chain=forward dst-address-list=allow action=accept; + /ipv6/firewall/filter/add chain=output dst-address-list=allow action=accept; + +Drop packets in firewall's raw section: + + /ipv6/firewall/raw/add chain=prerouting src-address-list=block action=drop; + /ipv6/firewall/raw/add chain=prerouting dst-address-list=block action=drop; + /ipv6/firewall/raw/add chain=output dst-address-list=block action=drop; + +> ⚠️ **Warning**: Just again... The order of firewall rules is important. Make +> sure they actually take effect as expected! + +--- +[⬅️ Go back to main README](../README.md) +[⬆️ Go back to top](#top) diff --git a/doc/global-wait.md b/doc/global-wait.md new file mode 100644 index 0000000..4b42717 --- /dev/null +++ b/doc/global-wait.md @@ -0,0 +1,47 @@ +Wait for global functions and modules +===================================== + +[](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 script can not be used on its own but requires the base +> installation. See [main README](../README.md) for details. + +Description +----------- + +The global functions from `global-functions` and modules are loaded by +scheduler at system startup. Running these functions at system startup may +result in race condition where configuration and/or function are not yet +available. This script is supposed to wait for everything being prepared. + +Do **not** add this script `global-wait` to the `global-scripts` scheduler! +It would inhibit the initialization of configuration and functions. + +Requirements and installation +----------------------------- + +Just install the script: + + $ScriptInstallUpdate global-wait; + +... and add it to your scheduler, for example in combination with the module +to [manage VLANs on bridge ports](mod/bridge-port-vlan.md): + + /system/scheduler/add name=bridge-port-vlan on-event="/system/script/run global-wait; :global BridgePortVlan; \$BridgePortVlan default;" start-time=startup; + +See also +-------- + +* [Manage ports in bridge](mod/bridge-port-to.md) +* [Manage VLANs on bridge ports](mod/bridge-port-vlan.md) + +--- +[⬅️ Go back to main README](../README.md) +[⬆️ Go back to top](#top) diff --git a/doc/gps-track.md b/doc/gps-track.md index cda7901..7006fb3 100644 --- a/doc/gps-track.md +++ b/doc/gps-track.md @@ -1,7 +1,17 @@ Send GPS position to server =========================== -[◀ 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) + +[⬅️ Go back to main README](../README.md) + +> ℹ️ **Info**: This script can not be used on its own but requires the base +> installation. See [main README](../README.md) for details. Description ----------- @@ -20,7 +30,7 @@ Just install the script: ... and create a scheduler: - / system scheduler add interval=1m name=gps-track on-event="/ system script run gps-track;" start-time=startup; + /system/scheduler/add interval=1m name=gps-track on-event="/system/script/run gps-track;" start-time=startup; Configuration ------------- @@ -29,9 +39,13 @@ The configuration goes to `global-config-overlay`, the only parameter is: * `GpsTrackUrl`: the url to send json data to -The configured coordinate format (see `/ system gps`) defines the format +> ℹ️ **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 configured coordinate format (see `/system/gps`) defines the format sent to the server. --- -[◀ 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/hotspot-to-wpa.md b/doc/hotspot-to-wpa.md index fbb9640..275fe4d 100644 --- a/doc/hotspot-to-wpa.md +++ b/doc/hotspot-to-wpa.md @@ -1,28 +1,72 @@ -Use WPA2 network with hotspot credentials -========================================= +Use WPA network with hotspot credentials +======================================== -[◀ 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) + +[⬅️ Go back to main README](../README.md) + +> ℹ️ **Info**: This script can not be used on its own but requires the base +> installation. See [main README](../README.md) for details. Description ----------- RouterOS supports an unlimited number of MAC address specific passphrases -for WPA2 encrypted wifi networks via access list. The idea of this script -is to transfer hotspot credentials to MAC address specific WPA2 passphrase. +for WPA encrypted wifi networks via access list. The idea of this script +is to transfer hotspot credentials to MAC address specific WPA passphrase. Requirements and installation ----------------------------- -You need a properly configured hotspot on one (open) SSID and a WP2 enabled +You need a properly configured hotspot on one (open) SSID and a WPA enabled SSID with suffix "`-wpa`". -Then install the script: +Then install the script. +Depending on whether you use `wifi` package (`/interface/wifi`)or legacy +wifi with CAPsMAN (`/caps-man`) you need to install a different script and +set it as `on-login` script in hotspot. + +For `wifi`: + + $ScriptInstallUpdate hotspot-to-wpa.wifi; + /ip/hotspot/user/profile/set on-login="hotspot-to-wpa.wifi" [ find ]; + +For legacy CAPsMAN: + + $ScriptInstallUpdate hotspot-to-wpa.capsman; + /ip/hotspot/user/profile/set on-login="hotspot-to-wpa.capsman" [ find ]; + +### Automatic cleanup + +With just `hotspot-to-wpa` installed the mac addresses will last in the +access list forever. Install the optional script for automatic cleanup +and add a scheduler. - $ScriptInstallUpdate hotspot-to-wpa; +For `wifi`: -Configure your hotspot to use this script as `on-login` script: + $ScriptInstallUpdate hotspot-to-wpa-cleanup.wifi,lease-script; + /system/scheduler/add interval=1d name=hotspot-to-wpa-cleanup on-event="/system/script/run hotspot-to-wpa-cleanup.wifi;" start-time=startup; - / ip hotspot user profile set on-login=hotspot-to-wpa [ find ]; +For legacy CAPsMAN: + + $ScriptInstallUpdate hotspot-to-wpa-cleanup.capsman,lease-script; + /system/scheduler/add interval=1d name=hotspot-to-wpa-cleanup on-event="/system/script/run hotspot-to-wpa-cleanup.capsman;" start-time=startup; + +And add the lease script and matcher comment to your wpa interfaces' dhcp +server. You can add more information to the comment, separated by comma. In +this example the server is called `hotspot-to-wpa`. + + /ip/dhcp-server/set lease-script=lease-script comment="hotspot-to-wpa=wpa" hotspot-to-wpa; + +You can specify the timeout after which a device is removed from leases and +access-list. The default is four weeks. + + /ip/dhcp-server/set lease-script=lease-script comment="hotspot-to-wpa=wpa, timeout=2w" hotspot-to-wpa; Configuration ------------- @@ -31,18 +75,50 @@ On first run a disabled access list entry acting as marker (with comment "`--- hotspot-to-wpa above ---`") is added. Move this entry to define where new entries are to be added. -Usage and invocation --------------------- - Create hotspot login credentials: - / ip hotspot user add add comment="Test User 1" name=user1 password=v3ry; - / ip hotspot user add add comment="Test User 2" name=user2 password=s3cr3t; + /ip/hotspot/user/add comment="Test User 1" name=user1 password=v3ry; + /ip/hotspot/user/add comment="Test User 2" name=user2 password=s3cr3t; + +This also works with authentication via radius, but is limited then: +Additional information is not available, including the password. + +Additionally templates can be created to give more options for access list: + +* `action`: set to `reject` to ignore logins on that hotspot +* `passphrase` or `private-passphrase`: do **not** use passphrase from + hotspot's user credentials, but given one - or unset (use default + passphrase) with special word `ignore` +* `ssid-regexp`: set a different SSID regular expression to match +* `vlan-id`: connect device to specific VLAN +* `vlan-mode`: set the VLAN mode for device + +For a hotspot called `example` the template could look like this. +For `wifi`: + + /interface/wifi/access-list/add comment="hotspot-to-wpa template example" disabled=yes passphrase="ignore" ssid-regexp="^example\$" vlan-id=10; + +For legacy CAPsMAN: + + /caps-man/access-list/add comment="hotspot-to-wpa template example" disabled=yes private-passphrase="ignore" ssid-regexp="^example\$" vlan-id=10 vlan-mode=use-tag; + +The same settings are available in hotspot user's comment and take precedence +over the template settings: + + /ip/hotspot/user/add comment="private-passphrase=ignore, ssid-regexp=^example\\\$, vlan-id=10, vlan-mode=use-tag" name=user password=v3ry-s3cr3t; + +Usage and invocation +-------------------- Now let the users connect and login to the hotspot. After that the devices -(identified by MAC address) can connect to the WPA2 network, using the +(identified by MAC address) can connect to the WPA network, using the passphrase from hotspot credentials. +See also +-------- + +* [Run other scripts on DHCP lease](lease-script.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/ip-addr-bridge.md b/doc/ip-addr-bridge.md index 44dac6a..941a8ae 100644 --- a/doc/ip-addr-bridge.md +++ b/doc/ip-addr-bridge.md @@ -1,7 +1,14 @@ Manage IP addresses with bridge status ====================================== -[◀ 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) + +[⬅️ Go back to main README](../README.md) Description ----------- @@ -19,14 +26,14 @@ Just install the script: ... and make it run from scheduler: - / system scheduler add name=ip-addr-bridge on-event="/ system script run ip-addr-bridge;" start-time=startup; + /system/scheduler/add name=ip-addr-bridge on-event="/system/script/run ip-addr-bridge;" start-time=startup; -This will disable IP addresses on bridges without at lease one running port. +This will disable IP addresses on bridges without at least one running port. The IP address is enabled if at least one port is running. Note that IP addresses on bridges without a single port (acting as loopback interface) are ignored. --- -[◀ 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/ipsec-to-dns.md b/doc/ipsec-to-dns.md new file mode 100644 index 0000000..0a91960 --- /dev/null +++ b/doc/ipsec-to-dns.md @@ -0,0 +1,57 @@ +Create DNS records for IPSec peers +================================== + +[](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 script can not be used on its own but requires the base +> installation. See [main README](../README.md) for details. + +Description +----------- + +This script adds (and removes) dns records based on IPSec peers and their +dynamic addresses from mode-config. + +Requirements and installation +----------------------------- + +Just install the script: + + $ScriptInstallUpdate ipsec-to-dns; + +This script is run from scheduler: + + /system/scheduler/add interval=1m name=ipsec-to-dns on-event="/system/script/run ipsec-to-dns;" start-time=startup; + +Configuration +------------- + +On first run a disabled static dns record acting as marker (with comment +"`--- ipsec-to-dns above ---`") is added. Move this entry to define where new +entries are to be added. + +The configuration goes to `global-config-overlay`, these are the parameters: + +* `Domain`: the domain used for dns records +* `HostNameInZone`: whether or not to add the ipsec/dns server's hostname +* `PrefixInZone`: whether or not to add prefix `ipsec` + +> ℹ️ **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. + +See also +-------- + +* [Create DNS records for DHCP leases](dns-to-dhcp.md) + +--- +[⬅️ Go back to main README](../README.md) +[⬆️ Go back to top](#top) diff --git a/doc/ipv6-update.md b/doc/ipv6-update.md index f736433..20265fe 100644 --- a/doc/ipv6-update.md +++ b/doc/ipv6-update.md @@ -1,14 +1,24 @@ Update configuration on IPv6 prefix change ========================================== -[◀ 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) + +[⬅️ Go back to main README](../README.md) + +> ℹ️ **Info**: This script can not be used on its own but requires the base +> installation. See [main README](../README.md) for details. Description ----------- With changing IPv6 prefix from ISP this script handles to update... -* ipv6 firewall address-list +* ipv6 firewall address-list (prefixes (`/64`) and host addresses (`/128`)) * dns records Requirements and installation @@ -20,14 +30,14 @@ Just install the script: Your ISP needs to provide an IPv6 prefix, your device receives it via dhcp: - / ipv6 dhcp-client add add-default-route=yes interface=ppp-isp pool-name=isp request=prefix script=ipv6-update; + /ipv6/dhcp-client/add add-default-route=yes interface=ppp-isp pool-name=isp request=prefix script=ipv6-update; Note this already adds this script as `script`. The pool name (here: "`isp`") is important, we need it later. Also this expects there is an address assigned from pool to an interface: - / ipv6 address add from-pool=isp interface=br-local; + /ipv6/address/add from-pool=isp interface=br-local; Sometimes dhcp client is stuck on reconnect and needs to be released. Installing [ppp-on-up](ppp-on-up.md) may solve this. @@ -38,7 +48,7 @@ Configuration An address list entry is updated with current prefix and can be used in firewall rules, comment has to be "`ipv6-pool-`" and actual pool name: - / ipv6 firewall address-list add address=2003:cf:2f0f:de00::/56 comment=ipv6-pool-isp list=extern; + /ipv6/firewall/address-list/add address=2003:cf:2f0f:de00::/56 comment=ipv6-pool-isp list=extern; As this entry is mandatory it is created automatically if it does not exist, with the comment also set for list. @@ -47,13 +57,18 @@ Address list entries for specific interfaces can be updated as well. The interface needs to get its address from pool `isp` and the address list entry has to be associated to an interface in comment: - / ipv6 firewall address-list add address=2003:cf:2f0f:de01::/64 comment="ipv6-pool-isp, interface=br-local" list=local; + /ipv6/firewall/address-list/add address=2003:cf:2f0f:de01::/64 comment="ipv6-pool-isp, interface=br-local" list=local; + +Updating address list entries with host addresses works as well, the new +prefix is combinded with given suffix then: + + /ipv6/firewall/address-list/add address=2003:cf:2f0f:de01:e3e0:f8fa:8cd6:dbe1/128 comment="ipv6-pool-isp, interface=br-local" list=hosts; Static DNS records need a special comment to be updated. Again it has to start with "`ipv6-pool-`" and actual pool name, followed by a comma, "`interface=`" and the name of interface this address is connected to: - / ip dns static add address=2003:cf:2f0f:de00:1122:3344:5566:7788 comment="ipv6-pool-isp, interface=br-local" name=test.example.com ttl=15m; + /ip/dns/static/add address=2003:cf:2f0f:de00:1122:3344:5566:7788 comment="ipv6-pool-isp, interface=br-local" name=test.example.com ttl=15m; See also -------- @@ -61,5 +76,5 @@ See also * [Run scripts on ppp connection](ppp-on-up.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/lease-script.md b/doc/lease-script.md index 3c774f1..4d2f3bc 100644 --- a/doc/lease-script.md +++ b/doc/lease-script.md @@ -1,17 +1,34 @@ Run other scripts on DHCP lease =============================== -[◀ 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) + +[⬅️ Go back to main README](../README.md) + +> ℹ️ **Info**: This script can not be used on its own but requires the base +> installation. See [main README](../README.md) for details. Description ----------- -This script is supposed to run from dhcp server as lease script. Currently -it does: +This script is supposed to run from dhcp server as lease script. On a dhcp +lease it runs each script containing the following line, where `##` is a +decimal number for ordering: + + # provides: lease-script, order=## + +Currently it runs if available, in order: -* run [dhcp-to-dns](dhcp-to-dns.md) -* run [collect-wireless-mac](collect-wireless-mac.md) -* run [dhcp-lease-comment](dhcp-lease-comment.md) +* [dhcp-to-dns](dhcp-to-dns.md) +* [collect-wireless-mac](collect-wireless-mac.md) +* [dhcp-lease-comment](dhcp-lease-comment.md) +* `hotspot-to-wpa-cleanup`, which is an optional cleanup script + of [hotspot-to-wpa](hotspot-to-wpa.md) Requirements and installation ----------------------------- @@ -22,7 +39,7 @@ Just install the script: ... and add it as `lease-script` to your dhcp server: - / ip dhcp-server set lease-script=lease-script [ find ]; + /ip/dhcp-server/set lease-script=lease-script [ find ]; See also -------- @@ -30,7 +47,8 @@ See also * [Collect MAC addresses in wireless access list](collect-wireless-mac.md) * [Comment DHCP leases with info from access list](dhcp-lease-comment.md) * [Create DNS records for DHCP leases](dhcp-to-dns.md) +* [Use WPA network with hotspot credentials](hotspot-to-wpa.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/leds-mode.md b/doc/leds-mode.md index b525220..90ea418 100644 --- a/doc/leds-mode.md +++ b/doc/leds-mode.md @@ -1,7 +1,14 @@ Manage LEDs dark mode ===================== -[◀ 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) + +[⬅️ Go back to main README](../README.md) Description ----------- @@ -21,21 +28,21 @@ Usage and invocation To switch the device to dark mode: - / system script run leds-night-mode; + /system/script/run leds-night-mode; ... and back to normal mode: - / system script run leds-day-mode; + /system/script/run leds-day-mode; To toggle between the two modes: - / system script run leds-toggle-mode; + /system/script/run leds-toggle-mode; Add these schedulers to switch to dark mode in the evening and back to normal mode in the morning: - / system scheduler add interval=1d name=leds-day-mode on-event="/ system script run leds-day-mode;" start-time=07:00:00; - / system scheduler add interval=1d name=leds-night-mode on-event="/ system script run leds-night-mode;" start-time=21:00:00; + /system/scheduler/add interval=1d name=leds-day-mode on-event="/system/script/run leds-day-mode;" start-time=07:00:00; + /system/scheduler/add interval=1d name=leds-night-mode on-event="/system/script/run leds-night-mode;" start-time=21:00:00; The script `leds-toggle-mode` can be used from [mode button](mode-button.md) to toggle mode. @@ -46,5 +53,5 @@ See also * [Mode button with multiple presses](mode-button.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/log-forward.d/notification.avif b/doc/log-forward.d/notification.avif Binary files differnew file mode 100644 index 0000000..a0f9ab3 --- /dev/null +++ b/doc/log-forward.d/notification.avif diff --git a/doc/log-forward.md b/doc/log-forward.md index afb695e..44409dc 100644 --- a/doc/log-forward.md +++ b/doc/log-forward.md @@ -1,21 +1,43 @@ Forward log messages via notification ===================================== -[◀ 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) + +[⬅️ Go back to main README](../README.md) + +> ℹ️ **Info**: This script can not be used on its own but requires the base +> installation. See [main README](../README.md) for details. Description ----------- -RouterOS supports sending log messages via e-mail or to a syslog server. -This has some limitation, however: +RouterOS itself supports sending log messages via e-mail or to a syslog +server (see `/system/logging`). This has some limitation, however: * does not work early after boot if network connectivity is not - yet established + yet established, or breaks intermittently * lots of messages generate a flood of mails -* Telegram is not supported +* Matrix and Telegram are not supported + +The script works around the limitations, for example it does: + +* read from `/log`, including messages from early boot +* skip multi-repeated messages +* rate-limit itself to mitigate flooding +* forward via notification (which includes *e-mail*, *Matrix* and *Telegram* + when installed and configured, see below) -The script is intended to be run periodically. It collects log messages -and forwards them via notification. +It is intended to be run periodically from scheduler, then collects new +log messages and forwards them via notification. + +### Sample notification + + Requirements and installation ----------------------------- @@ -26,7 +48,7 @@ Just install the script: ... and add a scheduler: - / system scheduler add interval=1m name=log-forward on-event="/ system script run log-forward;" start-time=startup; + /system/scheduler/add interval=1m name=log-forward on-event="/system/script/run log-forward;" start-time=startup; Configuration ------------- @@ -35,9 +57,39 @@ The configuration goes to `global-config-overlay`, these are the parameters: * `LogForwardFilter`: define topics *not* to be forwarded * `LogForwardFilterMessage`: define message text *not* to be forwarded +* `LogForwardInclude`: define topics to be forwarded (even if filter matches) +* `LogForwardIncludeMessage`: define message text to be forwarded (even if + filter matches) + +> ℹ️ **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. + +These patterns are matched as +[regular expressions](https://wiki.mikrotik.com/wiki/Manual:Regular_Expressions). +To forward **all** (ignoring severity) log messages with topics `account` +(which includes user logins) and `dhcp` you need something like: + + :global LogForwardInclude "(account|dhcp)"; + +Also notification settings are required for +[e-mail](mod/notification-email.md), +[matrix](mod/notification-matrix.md), +[ntfy](mod/notification-ntfy.md) and/or +[telegram](mod/notification-telegram.md). + +Tips & Tricks +------------- + +### Notification on reboot + +You want to receive a notification on every device (re-)boot? Quite easy, +just add: + + :global LogForwardIncludeMessage "(^router rebooted)"; -Also notification settings are required for e-mail and telegram. +This will match on every log message beginning with `router rebooted`. --- -[◀ 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-to.md b/doc/mod/bridge-port-to.md new file mode 100644 index 0000000..5c8bebc --- /dev/null +++ b/doc/mod/bridge-port-to.md @@ -0,0 +1,88 @@ +Manage ports in bridge +====================== + +[](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 and its functio are are supposed to handle interfaces and +switching them from one bridge to another. + +Requirements and installation +----------------------------- + +Just install the module: + + $ScriptInstallUpdate mod/bridge-port-to; + +Configuration +------------- + +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; + +Also dhcp client can be handled: + + /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-to on-event="/system/script/run global-wait; :global BridgePortTo; \$BridgePortTo default;" start-time=startup; + +Usage and invocation +-------------------- + +The usage examples show what happens with the configuration from above. + +Running the function `$BridgePortTo` with parameter `default` applies all +configuration given with `default=`: + + $BridgePortTo default; + +For the three interfaces we get this configuration: + +* The special value `dhcp-client` enables the dhcp client for interface `en1`. The bridge port entry is disabled. +* Interface `en2` is put in bridge `br-intern`. +* Interface `en3` is put in bridge `br-guest`. + +Running the function `$BridgePortTo` with parameter `alt` applies all +configuration given with `alt=`: + + $BridgePortTo alt; + +* Interface `en1` is put in bridge `br-guest`, dhcp client for the interface is disabled. +* Interface `en2` is put in bridge `br-guest`. +* Interface `en3` is unchanged, stays in bridge `br-guest`. + +Running the function `$BridgePortTo` with parameter `extra` applies another +configuration: + + $BridgePortTo extra; + +* Interfaces `en1` and `en2` are unchanged. +* Interface `en3` is put in bridge `br-intern`. + +See also +-------- + +* [Wait for global functions und modules](../global-wait.md) +* [Manage VLANs on bridge ports](bridge-port-vlan.md) + +--- +[⬅️ 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 new file mode 100644 index 0000000..d23d5b5 --- /dev/null +++ b/doc/mod/bridge-port-vlan.md @@ -0,0 +1,92 @@ +Manage VLANs on bridge ports +============================ + +[](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 and its function are supposed to handle VLANs on bridge ports. + +Requirements and installation +----------------------------- + +Just install the module: + + $ScriptInstallUpdate mod/bridge-port-vlan; + +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; + +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; + +Also dhcp client can be handled: + + /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; + +Usage and invocation +-------------------- + +The usage examples show what happens with the configuration from above. + +Running the function `$BridgePortVlan` with parameter `default` applies all +configuration given with `default=`: + + $BridgePortVlan default; + +For the three interfaces we get this configuration: + +* The special value `dhcp-client` enables the dhcp client for interface `en1`. The bridge port entry is disabled. +* Primary VLAN `intern` (ID `10`) is configured on `en2`. +* Primary VLAN `guest` (ID `20`) is configured on `en3`. + +Running the function `$BridgePortVlan` with parameter `alt` applies all +configuration given with `alt=`: + + $BridgePortVlan alt; + +* Primary VLAN `guest` (ID `20`) is configured on `en1`, dhcp client for the interface is disabled. +* Primary VLAN `guest` (ID `20`) is configured on `en2`. +* Interface `en3` is unchanged, primary VLAN `guest` (ID `20`) is unchanged. + +Running the function `$BridgePortVlan` with parameter `extra` applies another +configuration: + +* Interface `en1` is unchanged. +* Primary VLAN `extra` (via its ID `30`) is configured on `en2`. +* Primary VLAN `extra` (ID `30`) is configured on `en3`. + +See also +-------- + +* [Wait for global functions und modules](../global-wait.md) +* [Manage ports in bridge](bridge-port-to.md) + +--- +[⬅️ 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..d4e59b3 --- /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..cb655bc --- /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..2138e31 --- /dev/null +++ b/doc/mod/notification-email.md @@ -0,0 +1,88 @@ +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 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..92383be --- /dev/null +++ b/doc/mod/notification-matrix.md @@ -0,0 +1,132 @@ +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. + +> ℹ️ **Info**: The *matrix.org* server uses a Cloudflare certificate. You can +> install that with: `$CertificateAvailable "Cloudflare Inc ECC CA-3"` + +### 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 +-------- + +* [Send notifications via e-mail](notification-email.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..b2330a5 --- /dev/null +++ b/doc/mod/notification-ntfy.md @@ -0,0 +1,91 @@ +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. + +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 +-------- + +* [Send notifications via e-mail](notification-email.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/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..159fda9 --- /dev/null +++ b/doc/mod/notification-telegram.md @@ -0,0 +1,112 @@ +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: + + + +Now open a chat with your bot and start it by clicking the `START` button. + +Open just another chat with [GetIDs Bot](https://t.me/getidsbot), again start +with the `START` button. It will send you some information, including the +`id`, just below `You`. + +Finally edit `global-config-overlay`, add `TelegramTokenId` with the token +from *BotFather* and `TelegramChatId` with your id from *GetIDs Bot*. 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 and the +*GetIDs Bot* to a group, then use the group's id (which starts with a dash) +for `TelegramChatId`. Then remove *GetIDs Bot* from 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 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..c5fa891 --- /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..db8e322 --- /dev/null +++ b/doc/mod/ssh-keys-import.md @@ -0,0 +1,73 @@ +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-rsa AAAAB3Nza...QYZk8= user" admin; + +Starting with RouterOS *7.12beta1* support for keys of type `ed25519` has +been added: + + $SSHKeysImport "ssh-ed25519 AAAAC3Nza...ZVugJT 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) diff --git a/doc/mode-button.md b/doc/mode-button.md index 8d037e5..8734352 100644 --- a/doc/mode-button.md +++ b/doc/mode-button.md @@ -1,7 +1,17 @@ Mode button with multiple presses ================================= -[◀ 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) + +[⬅️ Go back to main README](../README.md) + +> ℹ️ **Info**: This script can not be used on its own but requires the base +> installation. See [main README](../README.md) for details. Description ----------- @@ -10,17 +20,17 @@ This script extend the functionality of mode button. Instead of just one you can trigger several actions by pressing the mode button several times. The hardware needs to have a mode button, see -`/ system routerboard mode-button`. Starting with RouterOS 6.47beta60 you +`/system/routerboard/mode-button`. Starting with RouterOS 6.47beta60 you can configure the reset button to act the same, see -`/ system routerboard reset-button`. +`/system/routerboard/reset-button`. Copy this code to terminal to check: ``` -:if ([ :len [ /system routerboard mode-button print as-value ] ] > 0) do={ +:if ([ :len [ /system/routerboard/mode-button/print as-value ] ] > 0) do={ :put "Mode button is supported."; } else={ - :if ([ :len [ /system routerboard reset-button print as-value ] ] > 0) do={ + :if ([ :len [ /system/routerboard/reset-button/print as-value ] ] > 0) do={ :put "Mode button is not supported, but reset button is."; } else={ :put "Neither mode button nor reset button is supported."; @@ -37,11 +47,11 @@ Just install the script: Then configure the mode button to run `mode-button`: - / system routerboard mode-button set enabled=yes on-event="/ system script run mode-button;"; + /system/routerboard/mode-button/set enabled=yes on-event="/system/script/run mode-button;"; To use the reset button instead: - / system routerboard reset-button set enabled=yes on-event="/ system script run mode-button;"; + /system/routerboard/reset-button/set enabled=yes on-event="/system/script/run mode-button;"; Configuration ------------- @@ -49,13 +59,17 @@ Configuration The configuration goes to `global-config-overlay`, these are the parameters: * `ModeButton`: an array with defined actions -* `ModeButtonLED`: led to give visual feedback +* `ModeButtonLED`: led to give visual feedback, `type` must be `on` or `off` + +> ℹ️ **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. Usage and invocation -------------------- -Press the mode button. :) +Press the mode button. 😜 --- -[◀ 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/netwatch-dns.md b/doc/netwatch-dns.md new file mode 100644 index 0000000..443106f --- /dev/null +++ b/doc/netwatch-dns.md @@ -0,0 +1,94 @@ +Manage DNS and DoH servers from netwatch +======================================== + +[](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 script can not be used on its own but requires the base +> installation. See [main README](../README.md) for details. + +Description +----------- + +This script reads server state from netwatch and manages used DNS and +DoH (DNS over HTTPS) servers. + +Requirements and installation +----------------------------- + +Just install the script: + + $ScriptInstallUpdate netwatch-dns; + +Then add a scheduler to run it periodically: + + /system/scheduler/add interval=1m name=netwatch-dns on-event="/system/script/run netwatch-dns;" start-time=startup; + +Configuration +------------- + +The DNS and DoH servers to be checked have to be added to netwatch with +specific comment: + + /tool/netwatch/add comment="doh" host=1.1.1.1; + /tool/netwatch/add comment="dns" host=8.8.8.8; + /tool/netwatch/add comment="doh, dns" host=9.9.9.9; + +This will configure *cloudflare-dns* for DoH (`https://1.1.1.1/dnsquery`), and +*google-dns* and *quad-nine* for regular DNS (`8.8.8.8,9.9.9.9`) if up. +If *cloudflare-dns* is down the script will fall back to *quad-nine* for DoH. + +Giving a specific query url for DoH is possible: + + /tool/netwatch/add comment="doh, doh-url=https://dns.nextdns.io/dns-query" host=199.247.16.158; + +Note that using a name in DoH url may introduce a chicken-and-egg issue! + +Adding a static DNS record has the same result for the url, but always +resolves to the same address. + + /ip/dns/static/add name="dns.nextdns.io" address=199.247.16.158; + /tool/netwatch/add comment="doh" host=199.247.16.158; + +Be aware that you have to keep the ip address in sync with real world +manually! + +Importing a certificate automatically is possible, at least if available in +the repository (see `certs` sub directory). + + /tool/netwatch/add comment="doh, doh-cert=DigiCert Global G2 TLS RSA SHA256 2020 CA1" host=1.1.1.1; + /tool/netwatch/add comment="doh, doh-cert=DigiCert TLS Hybrid ECC SHA384 2020 CA1" host=9.9.9.9; + /tool/netwatch/add comment="doh, doh-cert=GTS CA 1C3" host=8.8.8.8; + +Sometimes using just one specific (possibly internal) DNS server may be +desired, with fallback in case it fails. This is possible as well: + + /tool/netwatch/add comment="dns" host=10.0.0.10; + /tool/netwatch/add comment="dns-fallback" host=1.1.1.1; + +Tips & Tricks +------------- + +### Use in combination with notifications + +Netwatch entries can be created to work with both - this script and +[netwatch-notify](netwatch-notify.md). Just give options for both: + + /tool/netwatch/add comment="doh, notify, name=cloudflare-dns" host=1.1.1.1; + +Also this allows to update host address, see option `resolve`. + +See also +-------- + +* [Notify on host up and down](netwatch-notify.md) + +--- +[⬅️ Go back to main README](../README.md) +[⬆️ Go back to top](#top) diff --git a/doc/netwatch-notify.d/notification-01-down.avif b/doc/netwatch-notify.d/notification-01-down.avif Binary files differnew file mode 100644 index 0000000..894fb23 --- /dev/null +++ b/doc/netwatch-notify.d/notification-01-down.avif diff --git a/doc/netwatch-notify.d/notification-02-up.avif b/doc/netwatch-notify.d/notification-02-up.avif Binary files differnew file mode 100644 index 0000000..9021a93 --- /dev/null +++ b/doc/netwatch-notify.d/notification-02-up.avif diff --git a/doc/netwatch-notify.md b/doc/netwatch-notify.md index 11371ff..2db32bb 100644 --- a/doc/netwatch-notify.md +++ b/doc/netwatch-notify.md @@ -1,17 +1,32 @@ Notify on host up and down ========================== -[◀ 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) + +[⬅️ Go back to main README](../README.md) + +> ℹ️ **Info**: This script can not be used on its own but requires the base +> installation. See [main README](../README.md) for details. Description ----------- This script sends notifications about host UP and DOWN events. In comparison -to just netwatch (`/ tool netwatch`) and its `up-script` and `down-script` +to just netwatch (`/tool/netwatch`) and its `up-script` and `down-script` this script implements a simple state machine and dependency model. Host down events are triggered only if the host is down for several checks and optional parent host is not down to avoid false alerts. +### Sample notifications + + + + Requirements and installation ----------------------------- @@ -21,36 +36,154 @@ Just install the script: Then add a scheduler to run it periodically: - / system scheduler add interval=1m name=netwatch-notify on-event="/ system script run netwatch-notify;" start-time=startup; + /system/scheduler/add interval=1m name=netwatch-notify on-event="/system/script/run netwatch-notify;" start-time=startup; Configuration ------------- The hosts to be checked have to be added to netwatch with specific comment: - / tool netwatch add comment="notify, hostname=example.com" host=[ :resolve "example.com" ]; + /tool/netwatch/add comment="notify, name=example.com" host=[ :resolve "example.com" ]; + +Also notification settings are required for +[e-mail](mod/notification-email.md), +[matrix](mod/notification-matrix.md), +[ntfy](mod/notification-ntfy.md) and/or +[telegram](mod/notification-telegram.md). + +### Hooks It is possible to run an up hook command (`up-hook`) or down hook command (`down-hook`) when a notification is triggered. This has to be added in -comment: +comment, note that some characters need extra escaping: - / tool netwatch add comment="notify, hostname=poe-device, down-hook=/ interface ethernet poe power-cycle en21;" host=10.0.0.20; + /tool/netwatch/add comment=("notify, name=device, down-hook=/interface/ethernet \\{ disable \\\"en2\\\"; enable \\\"en2\\\"; \\}") host=10.0.0.20; + +Also there is a `pre-down-hook` that fires at two thirds of failed checks +required for the notification. The idea is to fix the issue before a +notification is sent. + +Getting the escaping right may be troublesome. Please consider adding a +script in `/system/script`, then running that from hook. + +### Count threshould The count threshould (default is 5 checks) is configurable as well: - / tool netwatch add comment="notify, hostname=example.com, count=10" host=104.18.144.11; + /tool/netwatch/add comment="notify, name=example.com, count=10" host=104.18.144.11; + +### Parents & dependencies If the host is behind another checked host add a dependency, this will suppress notification if the parent host is down: - / tool netwatch add comment="notify, hostname=gateway" host=93.184.216.1; - / tool netwatch add comment="notify, hostname=example.com, parent=gateway" host=93.184.216.34; + /tool/netwatch/add comment="notify, name=gateway" host=93.184.216.1; + /tool/netwatch/add comment="notify, name=example.com, parent=gateway" host=93.184.216.34; Note that every configured parent in a chain increases the check count threshould by one. -Also notification settings are required for e-mail and telegram. +### Update from DNS + +The host address can be updated dynamically. Give extra parameter `resolve` +with a resolvable name: + + /tool/netwatch/add comment="notify, name=example.com, resolve=example.com"; + +This supports multiple A or AAAA records for a name just fine, even a CNAME +to those. An update happens only if no more record with the configured host +address is found. + +### No notification on host down + +Also suppressing the notification on host down is possible with parameter +`no-down-notification`. This may be desired for devices that are usually +powered off, but accessibility is of interest. + + /tool/netwatch/add comment="notify, name=printer, no-down-notification" host=10.0.0.30; + +Go and get your coffee ☕️ before sending the print job. + +### No log on failed resolve + +A message is writting to log after three failed attemts to resolve a host. +However this can cause some noise for hosts that are expected to have +failures, for example when the name is dynamically added by +[`dhcp-to-dns`](dhcp-to-dns.md). This can be suppressed: + + /tool/netwatch/add comment="notify, name=client, resolve=client.dhcp.example.com, no-resolve-fail" host=10.0.0.0; + +### Add a note in notification + +For some extra information it is possible to add a text note. This is +included verbatim into the notification. + + /tool/netwatch/add comment="notify, name=example, note=Do not touch!" host=10.0.0.31; + +### Add a link in notification + +It is possible to add a link in notification, that is added below the +formatted notification text. + + /tool/netwatch/add comment="notify, name=example.com, resolve=example.com, link=https://example.com/"; + +Tips & Tricks +------------- + +### One of several hosts + +Sometimes it is sufficient if one of a number of hosts is available. You can +make `netwatch-notify` check for that by adding several items with same +`name`. Note that `count` has to be multiplied to keep the actual time. + + /tool/netwatch/add comment="notify, name=service, count=10" host=10.0.0.10; + /tool/netwatch/add comment="notify, name=service, count=10" host=10.0.0.20; + +### Checking internet connectivity + +Sometimes you can not check your gateway for internet connectivity, for +example when it does not respond to pings or has a dynamic address. You could +check `1.1.1.1` (Cloudflare DNS), `9.9.9.9` (Quad-nine DNS), `8.8.8.8` +(Google DNS) or any other reliable address that indicates internet +connectivity. + + /tool/netwatch/add comment="notify, name=internet" host=1.1.1.1; + +A target like this suits well to be parent for other checks. + + /tool/netwatch/add comment="notify, name=example.com, parent=internet" host=93.184.216.34; + +### Checking specific ISP + +Having several ISPs for redundancy a failed link may go unnoticed without +proper monitoring. You can use routing-mark to monitor specific connections. +Create a route and firewall mangle rule. + + /routing/table/add fib name=via-isp1; + /ip/route/add distance=1 gateway=isp1 routing-table=via-isp1; + /ip/firewall/mangle/add action=mark-routing chain=output new-routing-mark=via-isp1 dst-address=1.0.0.1 passthrough=yes; + +Finally monitor the address with `netwatch-notify`. + + /tool/netwatch/add comment="notify, name=quad-one via isp1" host=1.0.0.1; + +Note that *all* traffic to the given address is routed that way. In case of +link failure this address is not available, so use something reliable but +non-essential. In this example the address `1.0.0.1` is used, the same service +(Cloudflare DNS) is available at `1.1.1.1`. + +### Use in combination with DNS and DoH management + +Netwatch entries can be created to work with both - this script and +[netwatch-dns](netwatch-dns.md). Just give options for both: + + /tool/netwatch/add comment="doh, notify, name=cloudflare-dns" host=1.1.1.1; + +See also +-------- + +* [Manage DNS and DoH servers from netwatch](netwatch-dns.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/netwatch-syslog.md b/doc/netwatch-syslog.md index 9a28bb9..6a337d4 100644 --- a/doc/netwatch-syslog.md +++ b/doc/netwatch-syslog.md @@ -1,34 +1,5 @@ -Manage remote logging -===================== +This script has been dropped. Filtering in firewall is advised, which should +look something like this: -[◀ Go back to main README](../README.md) - -Description ------------ - -RouterOS supports sending log messages via network to a remote syslog server. -If the server is not available no log messages (with potentially sensitive -information) should be sent. This script disables remote logging by -availability. - -Requirements and installation ------------------------------ - -Let's assume there is a remote log action and associated logging rule: - - / system logging action set remote=10.0.0.1 [ find where name="remote" ]; - / system logging add action=remote topics=info; - -Just install the script: - - $ScriptInstallUpdate netwatch-syslog; - -... and create a netwatch matching the IP address from logging action above: - - / tool netwatch add down-script=netwatch-syslog host=10.0.0.1 up-script=netwatch-syslog; - -All logging rules are disabled when host is down. - ---- -[◀ Go back to main README](../README.md) -[▲ Go back to top](#top) + /ip/firewall/filter/add action=reject chain=output out-interface-list=WAN port=514 protocol=udp reject-with=icmp-admin-prohibited; + /ip/firewall/filter/add action=reject chain=forward out-interface-list=WAN port=514 protocol=udp reject-with=icmp-admin-prohibited; diff --git a/doc/ospf-to-leds.md b/doc/ospf-to-leds.md index 72fab6b..121f77b 100644 --- a/doc/ospf-to-leds.md +++ b/doc/ospf-to-leds.md @@ -1,7 +1,17 @@ Visualize OSPF state via LEDs ============================= -[◀ 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) + +[⬅️ Go back to main README](../README.md) + +> ℹ️ **Info**: This script can not be used on its own but requires the base +> installation. See [main README](../README.md) for details. Description ----------- @@ -19,7 +29,7 @@ Just install the script: ... and add a scheduler to run the script periodically: - / system scheduler add interval=20s name=ospf-to-leds on-event="/ system script run ospf-to-leds;" start-time=startup; + /system/scheduler/add interval=20s name=ospf-to-leds on-event="/system/script/run ospf-to-leds;" start-time=startup; Configuration ------------- @@ -27,8 +37,8 @@ Configuration The configuration goes to OSPF instance's comment. To visualize state for instance `default` via LED `user-led` set this: - / routing ospf instance set default comment="ospf-to-leds, leds=user-led"; + /routing/ospf/instance/set default comment="ospf-to-leds, leds=user-led"; --- -[◀ 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/packages-update.md b/doc/packages-update.md index 882ce80..fae3896 100644 --- a/doc/packages-update.md +++ b/doc/packages-update.md @@ -1,20 +1,34 @@ Manage system update ==================== -[◀ 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) + +[⬅️ Go back to main README](../README.md) + +> ℹ️ **Info**: This script can not be used on its own but requires the base +> installation. See [main README](../README.md) for details. Description ----------- In rare cases RouterOS fails to properly downlaod package on update -(`/ system package update install`), resulting in borked system with missing +(`/system/package/update/install`), resulting in borked system with missing packages. This script tries to avoid this situation by doing some basic verification. But it provides some extra functionality: -* send backup via e-mail if [email-backup](email-backup.md) is installed -* upload backup if [upload-backup](upload-backup.md) is installed +* upload backup to Mikrotik cloud if [backup-cloud](backup-cloud.md) is + installed +* send backup via e-mail if [backup-email](backup-email.md) is installed +* save configuration to fallback partition if + [backup-partition](backup-partition.md) is installed +* upload backup to server if [backup-upload](backup-upload.md) is installed * schedule reboot at night Requirements and installation @@ -27,20 +41,38 @@ Just install the script: It is automatically run by [check-routeros-update](check-routeros-update.md) if available. +Configuration +------------- + +The configuration goes to `global-config-overlay`, this is the only parameter: + +* `PackagesUpdateDeferReboot`: defer the reboot for night (between 3 AM + and 5 AM) + +By modifying the scheduler's `start-time` you can force the reboot at +different time. + +> ℹ️ **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. + Usage and invocation -------------------- Alternatively run it manually: - / system script run packages-update; + /system/script/run packages-update; See also -------- +* [Upload backup to Mikrotik cloud](backup-cloud.md) +* [Send backup via e-mail](backup-email.md) +* [Save configuration to fallback partition](backup-partition.md) +* [Upload backup to server](backup-upload.md) * [Notify on RouterOS update](check-routeros-update.md) -* [Send backup via e-mail](email-backup.md) -* [Upload backup to server](upload-backup.md) +* [Automatically upgrade firmware and reboot](firmware-upgrade-reboot.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/ppp-on-up.md b/doc/ppp-on-up.md index 432a640..21847c7 100644 --- a/doc/ppp-on-up.md +++ b/doc/ppp-on-up.md @@ -1,7 +1,17 @@ Run scripts on ppp connection ============================= -[◀ 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) + +[⬅️ Go back to main README](../README.md) + +> ℹ️ **Info**: This script can not be used on its own but requires the base +> installation. See [main README](../README.md) for details. Description ----------- @@ -21,7 +31,7 @@ Just install the script: ... and make it the `on-up` script for ppp profile: - / ppp profile set on-up=ppp-on-up [ find ]; + /ppp/profile/set on-up=ppp-on-up [ find ]; See also -------- @@ -30,5 +40,5 @@ See also * [Update tunnelbroker configuration](update-tunnelbroker.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/rotate-ntp.md b/doc/rotate-ntp.md index eb04f5c..9a016a3 100644 --- a/doc/rotate-ntp.md +++ b/doc/rotate-ntp.md @@ -1,40 +1,3 @@ -Rotate NTP servers -================== - -[◀ Go back to main README](../README.md) - -Description ------------ - -RouterOS requires NTP servers to be configured by IP address. Servers from a -pool may appear and disappear, leaving broken NTP configuration. - -This script allows to rotate IP addresses from a given pool. - -Requirements and installation ------------------------------ - -Just install the script: - - $ScriptInstallUpdate rotate-ntp; - -Configuration -------------- - -The configuration goes to `global-config-overlay`, this is the parameter: - -* `NtpPool`: dns name of ntp server pool - -Usage and invocation --------------------- - -Just run the script to update the NTP configuration with actual IP -addresses from pool if required. - -Alternatively a scheduler can be created: - - / system scheduler add interval=5d name=rotate-ntp on-event="/ system script run rotate-ntp;" start-time=startup; - ---- -[◀ Go back to main README](../README.md) -[▲ Go back to top](#top) +This script has been dropped as the limitation does no longer exist with +RouterOS 7.x, where you can enable a ntp server and use a name for the client +at the same time. diff --git a/doc/sms-action.md b/doc/sms-action.md index df9e14f..b4678af 100644 --- a/doc/sms-action.md +++ b/doc/sms-action.md @@ -1,7 +1,17 @@ Act on received SMS =================== -[◀ 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) + +[⬅️ Go back to main README](../README.md) + +> ℹ️ **Info**: This script can not be used on its own but requires the base +> installation. See [main README](../README.md) for details. Description ----------- @@ -25,9 +35,13 @@ The configuration goes to `global-config-overlay`, this is the only parameter: * `SmsAction`: an array with pre-defined actions +> ℹ️ **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. + Then enable SMS actions: - / tool sms set allowed-number=+491234567890 receive-enabled=yes secret=s3cr3t; + /tool/sms/set allowed-number=+491234567890 receive-enabled=yes secret=s3cr3t; Usage and invocation -------------------- @@ -45,5 +59,5 @@ See also * [Forward received SMS](sms-forward.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/sms-forward.d/notification.avif b/doc/sms-forward.d/notification.avif Binary files differnew file mode 100644 index 0000000..01eb7ba --- /dev/null +++ b/doc/sms-forward.d/notification.avif diff --git a/doc/sms-forward.md b/doc/sms-forward.md index 27c3847..597410b 100644 --- a/doc/sms-forward.md +++ b/doc/sms-forward.md @@ -1,7 +1,17 @@ Forward received SMS ==================== -[◀ 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) + +[⬅️ Go back to main README](../README.md) + +> ℹ️ **Info**: This script can not be used on its own but requires the base +> installation. See [main README](../README.md) for details. Description ----------- @@ -10,6 +20,10 @@ RouterOS can receive SMS. This script forwards SMS as notification. A broadband interface with SMS support is required. +### Sample notification + + + Requirements and installation ----------------------------- @@ -19,15 +33,60 @@ Just install the script: ... and add a scheduler to run it periodically: - / system scheduler add interval=2m name=sms-forward on-event="/ system script run sms-forward;" start-time=startup; + /system/scheduler/add interval=2m name=sms-forward on-event="/system/script/run sms-forward;" start-time=startup; Configuration ------------- -Notification settings are required for e-mail and telegram. Also you have -to enable receiving of SMS: +You have to enable receiving of SMS: + + /tool/sms/set receive-enabled=yes; + +The configuration goes to `global-config-overlay`, this is the only parameter: + +* `SmsForwardHooks`: an array with pre-defined hooks, where each hook consists + of `match` (which is matched against the received message), `allowed-number` + (which is matched against the sending phone number or name) and `command`. + For `match` and `allowed-number` regular expressions are supported. Actual + phone number (`$Phone`) and message (`$Message`) are available for the hook. + +> ℹ️ **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. + +Notification settings are required for +[e-mail](mod/notification-email.md), +[matrix](mod/notification-matrix.md), +[ntfy](mod/notification-ntfy.md) and/or +[telegram](mod/notification-telegram.md). + +Tips & Tricks +------------- + +### Take care of harmful commands! + +It is easy to fake the sending phone number! So make sure you do not rely on +that number for potentially harmful commands. Add a shared secret to match +into the text instead, for example: `reboot-53cr3t-5tr1n9` instead of just +`reboot`. + +### Order new volume + +Most broadband providers include a volume limit for their data plans. The +hook functionality can be used to order new volume automatically. + +Let's assume an imaginary provider **ABC** sends a message when the available +volume is about to deplete. The message is sent from `ABC` and the text +contains the string `80%`. New volume can be ordered by sending a SMS back to +the phone number `1234` with the text `data-plan`. + + :global SmsForwardHooks { + { match="80%"; + allowed-number="ABC"; + command="/tool/sms/send lte1 phone-number=1234 message=\"data-plan\";" }; + }; - / tool sms set receive-enabled=yes; +Adjust the values to your own needs. See also -------- @@ -35,5 +94,5 @@ See also * [Act on received SMS](sms-action.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/ssh-keys-import.md b/doc/ssh-keys-import.md index d221072..d1325aa 100644 --- a/doc/ssh-keys-import.md +++ b/doc/ssh-keys-import.md @@ -1,33 +1,2 @@ -Import SSH keys -=============== - -[◀ Go back to main README](../README.md) - -Description ------------ - -This script imports public SSH keys (files with extension "`pub`") into -local store for user authentication. - -Requirements and installation ------------------------------ - -Just install the script: - - $ScriptInstallUpdate ssh-keys-import; - -Usage and invocation --------------------- - -Copy files with extension "`pub`" containing public SSH keys for your device. -Then run the script: - - / system script run ssh-keys-import; - -Starting with an `authorized_keys` file you can split it on a shell: - - while read type key name; do echo $type $key $name > $name.pub; done < authorized_keys - ---- -[◀ Go back to main README](../README.md) -[▲ Go back to top](#top) +This script has been replaced by a module. Please see +[Import ssh keys for public key authentication](mod/ssh-keys-import.md). diff --git a/doc/super-mario-theme.md b/doc/super-mario-theme.md index 68484dc..e4bae2e 100644 --- a/doc/super-mario-theme.md +++ b/doc/super-mario-theme.md @@ -1,7 +1,14 @@ Play Super Mario theme ====================== -[◀ 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) + +[⬅️ Go back to main README](../README.md) Description ----------- @@ -22,10 +29,10 @@ Usage and invocation Just run the script to play: - / system script run super-mario-theme; + /system/script/run super-mario-theme; For extra fun use it for dhcp lease script. :) --- -[◀ 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/telegram-chat.d/01-chat-specific.avif b/doc/telegram-chat.d/01-chat-specific.avif Binary files differnew file mode 100644 index 0000000..ab75f78 --- /dev/null +++ b/doc/telegram-chat.d/01-chat-specific.avif diff --git a/doc/telegram-chat.d/02-chat-all.avif b/doc/telegram-chat.d/02-chat-all.avif Binary files differnew file mode 100644 index 0000000..ed1a389 --- /dev/null +++ b/doc/telegram-chat.d/02-chat-all.avif diff --git a/doc/telegram-chat.d/03-reply.avif b/doc/telegram-chat.d/03-reply.avif Binary files differnew file mode 100644 index 0000000..515853e --- /dev/null +++ b/doc/telegram-chat.d/03-reply.avif diff --git a/doc/telegram-chat.md b/doc/telegram-chat.md new file mode 100644 index 0000000..eb4acf5 --- /dev/null +++ b/doc/telegram-chat.md @@ -0,0 +1,152 @@ +Chat with your router and send commands via Telegram bot +======================================================== + +[](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 script can not be used on its own but requires the base +> installation. See [main README](../README.md) for details. + +Description +----------- + +This script makes your device poll a Telegram bot for new messages. With +these messages you can send commands to your device and make it run them. +The resulting output is send back to you. + +Requirements and installation +----------------------------- + +Just install the script and the module for notifications via Telegram: + + $ScriptInstallUpdate telegram-chat,mod/notification-telegram; + +Then create a schedule that runs the script periodically: + + /system/scheduler/add start-time=startup interval=30s name=telegram-chat on-event="/system/script/run telegram-chat;"; + +> ⚠️ **Warning**: Make sure to keep the interval in sync when installing +> on several devices. Differing polling intervals will result in missed +> messages. + +Configuration +------------- + +Make sure to configure +[notifications via telegram](mod/notification-telegram.md) first. The +additional configuration goes to `global-config-overlay`, these are the +parameters: + +* `TelegramChatIdsTrusted`: an array with trusted chat ids or user names +* `TelegramChatGroups`: define the groups a device should belong to + +> ℹ️ **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. + +Usage and invocation +-------------------- + +### Activating device(s) + +This script is capable of chatting with multiple devices. By default a +device is passive and not acting on messages. To activate it send a message +containing `! identity` (exclamation mark, optional space and system's +identity). To query all dynamic ip addresses form a device named "*MikroTik*" +send `! MikroTik`, followed by `/ip/address/print where dynamic;`. + + + +Devices can be grouped to chat with them simultaneously. The default group +"*all*" can be activated by sending `! @all`, which will make all devices +act on your commands. + + + +Send a single exclamation mark or non-existent identity to make all +devices passive again. + +### Reply to message + +Let's assume you received a message from a device before, and want to send +a command to that device. No need to activate it, you can just reply to +that message. + + + +Associated messages are cleared on device reboot. + +### Ask for devices + +Send a message with a single question mark (`?`) to query for devices +currenty online. The answer can be used for command via reply then. + +Known limitations +----------------- + +### Do not use numeric ids! + +Numeric ids are valid within a session only. Usually you can use something +like this to print all ip addresses and remove the first one: + + /ip/address/print; + /ip/address/remove 0; + +This will fail when sent in separate messages. Instead you should use basic +scripting capabilities. Try to print what you want to act on... + + /ip/address/print where interface=eth; + +... verify and finally remove it. + + /ip/address/remove [ find where interface=eth ]; + +What does work is using the persistent ids: + + /ip/address/print show-ids; + +The output contains an id starting with asterisk that can be used: + + /ip/address/remove *E; + +### Mind command runtime + +The command is run in background while the script waits for it - about +20 seconds at maximum. A command exceeding that time continues to run in +background, but the output in the message is missing or truncated then. + +If you still want a response you can work around this by making your code +send information on its own. Something like this should do the job: + + :global SendTelegram; + :delay 30s; + $SendTelegram "Command finished" "Your command finished..."; + +### Output size + +Telegram messages have a limit of 4096 characters. If output is too large it +is truncated, and a warning is added to the message. + +### Sending commands to a group + +Adding a bot to a group allows it to send messages to that group. To allow +it to receive messages you have to make it an admin of that group! It is +fine to deny all permissions, though. + +Also adding an admin to a group can cause the group id to change, so check +that if notifications break suddenly. + +See also +-------- + +* [Send notifications via Telegram](mod/notification-telegram.md) + +--- +[⬅️ Go back to main README](../README.md) +[⬆️ Go back to top](#top) diff --git a/doc/unattended-lte-firmware-upgrade.md b/doc/unattended-lte-firmware-upgrade.md index 65801a6..6680447 100644 --- a/doc/unattended-lte-firmware-upgrade.md +++ b/doc/unattended-lte-firmware-upgrade.md @@ -1,7 +1,14 @@ Install LTE firmware upgrade ============================ -[◀ 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) + +[⬅️ Go back to main README](../README.md) Description ----------- @@ -12,6 +19,7 @@ This script upgrades LTE firmware on compatible devices: * R11e-LTE-US * R11e-4G * R11e-LTE6 +* ... and more - probably what ever Mikrotik builds into their devices A temporary scheduler is created to be independent from terminal. Thus starting the upgrade process over the broadband connection is supported. @@ -32,7 +40,7 @@ Usage and invocation Run the script if an upgrade for your LTE hardware is available: - / system script run unattended-lte-firmware-upgrade; + /system/script/run unattended-lte-firmware-upgrade; Then be patient, go for a coffee and wait for the upgrade process to finish. @@ -42,5 +50,5 @@ See also * [Notify on LTE firmware upgrade](check-lte-firmware-upgrade.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/update-gre-address.md b/doc/update-gre-address.md index 870759e..80902b9 100644 --- a/doc/update-gre-address.md +++ b/doc/update-gre-address.md @@ -1,7 +1,17 @@ Update GRE configuration with dynamic addresses =============================================== -[◀ 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) + +[⬅️ Go back to main README](../README.md) + +> ℹ️ **Info**: This script can not be used on its own but requires the base +> installation. See [main README](../README.md) for details. Description ----------- @@ -23,7 +33,7 @@ Just install the script: ... and add a scheduler to run the script periodically: - / system scheduler add interval=30s name=update-gre-address on-event="/ system script run update-gre-address;" start-time=startup; + /system/scheduler/add interval=30s name=update-gre-address on-event="/system/script/run update-gre-address;" start-time=startup; Configuration ------------- @@ -31,8 +41,8 @@ Configuration The configuration goes to interface's comment. Add the client's IKEv2 certificate CN into the comment: - / interface gre set comment="ikev2-client1" gre-client1; + /interface/gre/set comment="ikev2-client1" gre-client1; --- -[◀ 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/update-tunnelbroker.md b/doc/update-tunnelbroker.md index 3641588..2539e2f 100644 --- a/doc/update-tunnelbroker.md +++ b/doc/update-tunnelbroker.md @@ -1,7 +1,17 @@ Update tunnelbroker configuration ================================= -[◀ 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) + +[⬅️ Go back to main README](../README.md) + +> ℹ️ **Info**: This script can not be used on its own but requires the base +> installation. See [main README](../README.md) for details. Description ----------- @@ -25,11 +35,10 @@ Configuration The configuration goes to interface's comment: - / interface 6to4 set comment="tunnelbroker, user=user, pass=s3cr3t, id=12345" tunnelbroker; - -Also enabling dynamic DNS in Mikrotik cloud is required: + /interface/6to4/set comment="tunnelbroker, user=user, id=12345, pass=s3cr3t" tunnelbroker; - / ip cloud set ddns-enabled=yes; +You should know you user name from login. The `id` is the tunnel's numeric +id, `pass` is the *update key* found on the tunnel's advanced tab. See also -------- @@ -37,5 +46,5 @@ See also * [Run scripts on ppp connection](ppp-on-up.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/upload-backup.md b/doc/upload-backup.md index e6ba9e2..83c9991 100644 --- a/doc/upload-backup.md +++ b/doc/upload-backup.md @@ -1,63 +1 @@ -Upload backup to server -======================= - -[◀ Go back to main README](../README.md) - -Description ------------ - -This script uploads binary backup (`/ system backup save`) and complete -configuration export (`/ export terse`) to external server. - -Requirements and installation ------------------------------ - -Just install the script: - - $ScriptInstallUpdate upload-backup; - -Configuration -------------- - -The configuration goes to `global-config-overlay`, these are the parameters: - -* `BackupSendBinary`: whether to send binary backup -* `BackupSendExport`: whether to send configuration export -* `BackupPassword`: password to encrypt the backup with -* `BackupRandomDelay`: delay up to amount of seconds when run from scheduler -* `BackupUploadUrl`: url to upload to -* `BackupUploadUser`: username for server authentication -* `BackupUploadPass`: password for server authentication - -Also notification settings are required for e-mail and telegram. - -### Issues with SFTP client - -The RouterOS SFTP client is picky if it comes to authentication methods. -I had to disable all but password authentication on server side. For openssh -edit `/etc/ssh/sshd_config` and add a directive like this, changed for your -needs: - - Match User mikrotik - AuthenticationMethods password - -Usage and invocation --------------------- - -Just run the script: - - / system script run upload-backup; - -Creating a scheduler may be an option: - - / system scheduler add interval=1w name=upload-backup on-event="/ system script run upload-backup;" start-time=09:25:00; - -See also --------- - -* [Send backup via e-mail](email-backup.md) -* [Upload backup to Mikrotik cloud](cloud-backup.md) - ---- -[◀ Go back to main README](../README.md) -[▲ Go back to top](#top) +This script has been renamed. Please see [backup-upload](backup-upload.md). |
