diff options
Diffstat (limited to 'doc')
90 files changed, 3914 insertions, 0 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 new file mode 100644 index 0000000..a1f9198 --- /dev/null +++ b/doc/accesslist-duplicates.md @@ -0,0 +1,57 @@ +Find and remove access list duplicates +====================================== + +[](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 interactively to find and remove duplicate +entries in wireless access list. + +Requirements and installation +----------------------------- + +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 accesslist-duplicates.wifi; + +For legacy CAPsMAN: + + $ScriptInstallUpdate accesslist-duplicates.capsman; + +For legacy local interface: + + $ScriptInstallUpdate accesslist-duplicates.local; + +Usage and invocation +-------------------- + +Run this script from a terminal: + + /system/script/run accesslist-duplicates.wifi; + + + +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) 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..1f9e123 --- /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](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..3b1dbb2 --- /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](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..1cef2c9 --- /dev/null +++ b/doc/backup-partition.md @@ -0,0 +1,78 @@ +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). +It can also copy-over the RouterOS installation when run interactively +or just before a feature update. + +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**: By default only the configuration is saved to backup +> partition. Every now and then you should copy your installation over +> for a recent RouterOS version! See below for options. + +Requirements and installation +----------------------------- + +Just install the script: + + $ScriptInstallUpdate backup-partition; + +Configuration +------------- + +The configuration goes to `global-config-overlay`, the only parameter is: + +* `BackupPartitionCopyBeforeFeatureUpdate`: copy-over the RouterOS + installation when a feature update is pending + +> ℹ️ **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-partition; + +When run interactively from terminal it supports to copy-over the RouterOS +installation when versions differ. + +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..c44217c --- /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](backup-partition.md) + +--- +[⬅️ 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 new file mode 100644 index 0000000..c68900e --- /dev/null +++ b/doc/capsman-download-packages.md @@ -0,0 +1,83 @@ +Download packages for CAP upgrade from CAPsMAN +============================================= + +[](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 +----------- + +CAPsMAN can upgrate CAP devices. If CAPsMAN device and CAP device(s) are +differnet architecture you need to store packages for CAP device's +architecture on local storage. + +This script automatically downloads these packages. + +Requirements and installation +----------------------------- + +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: + + /system/scheduler/add name=capsman-download-packages on-event="/system/script/run capsman-download-packages.capsman;" start-time=startup; + +Packages available in local storage in older version are downloaded +unconditionally. + +If no packages are found the script downloads a default set of packages: + + * `wifi`: `routeros` and `wifi-qcom` for *arm* and *arm64*, `wifi-qcom-ac` for *arm* + * legacy CAPsMAN: `routeros` and `wireless` for *arm* and *mipsbe* + +> ℹ️ **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.wifi; + +... or from scheduler. + +After package download all out-of-date CAP devices are upgraded automatically. +For a rolling upgrade install extra script +[capsman-rolling-upgrade](capsman-rolling-upgrade.md). + +See also +-------- + +* [Run rolling CAP upgrades from CAPsMAN](capsman-rolling-upgrade.md) + +--- +[⬅️ 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 new file mode 100644 index 0000000..27d855f --- /dev/null +++ b/doc/capsman-rolling-upgrade.md @@ -0,0 +1,60 @@ +Run rolling CAP upgrades from CAPsMAN +===================================== + +[](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 +----------- + +CAPsMAN can upgrade CAP devices. This script runs a rolling upgrade for +out-of-date CAP devices. The idea is to have just a fraction of devices +reboot at a time, having the others to serve wireless connectivity. + +Note that the script does not wait for the CAPs to reconnect, it just defers +the upgrade commands. The more CAPs you have the more will upgrade in +parallel. + +Requirements and installation +----------------------------- + +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.capsman; + +Usage and invocation +-------------------- + +This script is intended as an add-on to +[capsman-download-packages](capsman-download-packages.md), being invoked by +that script when required. + +Alternatively run it manually: + + /system/script/run capsman-rolling-upgrade.wifi; + +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) diff --git a/doc/certificate-renew-issued.md b/doc/certificate-renew-issued.md new file mode 100644 index 0000000..91a1914 --- /dev/null +++ b/doc/certificate-renew-issued.md @@ -0,0 +1,61 @@ +Renew locally issued certificates +================================= + +[](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 renews certificates issued by a local certificate authority (CA). +Optionally the certificates are exported with individual passphrases for +easy pick-up. + +Requirements and installation +----------------------------- + +Just install the script: + + $ScriptInstallUpdate certificate-renew-issued; + +Configuration +------------- + +The configuration goes to `global-config-overlay`, there is just one +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; + +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 +certificate is given in `CertRenewPass` the certificate is exported and +PKCS#12 file (`cert-issued/CN.p12`) can be found on device's storage. + +See also +-------- + +* [Renew certificates and notify on expiration](check-certificates.md) + +--- +[⬅️ 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 new file mode 100644 index 0000000..636f719 --- /dev/null +++ b/doc/check-certificates.md @@ -0,0 +1,97 @@ +Renew certificates and notify on expiration +=========================================== + +[](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 tries to download and renew certificates, then notifies about +certificates that are still about to expire. + +### Sample notification + + + +Requirements and installation +----------------------------- + +Just install the script: + + $ScriptInstallUpdate check-certificates; + +Configuration +------------- + +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. + +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; + +... 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; + + +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 + +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: + + /certificate/add name=example.com common-name=example.com days-valid=1; + /certificate/sign example.com; + /system/script/run check-certificates; + +See also +-------- + +* [Renew locally issued certificates](certificate-renew-issued.md) + +--- +[⬅️ 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 new file mode 100644 index 0000000..f94a0bf --- /dev/null +++ b/doc/check-health.md @@ -0,0 +1,96 @@ +Notify about health state +========================= + +[](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 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. + +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) + + + + +#### Voltage + + + +#### Temperature + + + + +#### PSU state + + + + +Requirements and installation +----------------------------- + +Just install the script and create a scheduler: + + $ScriptInstallUpdate check-health; + /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: + +* `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 + +> ℹ️ **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) 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 new file mode 100644 index 0000000..59a62c7 --- /dev/null +++ b/doc/check-lte-firmware-upgrade.md @@ -0,0 +1,58 @@ +Notify on LTE firmware upgrade +============================== + +[](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 run from scheduler periodically, checking for LTE firmware +upgrades. Currently supported LTE hardware: + +* R11e-LTE +* R11e-LTE-US +* R11e-4G +* R11e-LTE6 + +### Sample notification + + + +Requirements and installation +----------------------------- + +Just install the script: + + $ScriptInstallUpdate check-lte-firmware-upgrade; + +... 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; + +Configuration +------------- + +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 +-------- + +* [Notify on RouterOS update](check-routeros-update.md) +* [Install LTE firmware upgrade](unattended-lte-firmware-upgrade.md) + +--- +[⬅️ 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 new file mode 100644 index 0000000..f9d485c --- /dev/null +++ b/doc/check-routeros-update.md @@ -0,0 +1,107 @@ +Notify on RouterOS update +========================= + +[](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 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. 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 +----------------------------- + +Just install the script: + + $ScriptInstallUpdate check-routeros-update; + +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; + +Configuration +------------- + +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; + +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) diff --git a/doc/cloud-backup.md b/doc/cloud-backup.md new file mode 100644 index 0000000..e161cfa --- /dev/null +++ b/doc/cloud-backup.md @@ -0,0 +1 @@ +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 new file mode 100644 index 0000000..57032d8 --- /dev/null +++ b/doc/collect-wireless-mac.md @@ -0,0 +1,77 @@ +Collect MAC addresses in wireless access list +============================================= + +[](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 unknown MAC addresses of connected wireless devices to +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 `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 legacy CAPsMAN: + + $ScriptInstallUpdate collect-wireless-mac.capsman; + +For legacy local interface: + + $ScriptInstallUpdate collect-wireless-mac.local; + +Configuration +------------- + +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](mod/notification-email.md), +[matrix](mod/notification-matrix.md), +[ntfy](mod/notification-ntfy.md) and/or +[telegram](mod/notification-telegram.md). + +Usage and invocation +-------------------- + +Run this script from a dhcp server as lease-script to collect the MAC +address when a new address is leased. You may want to use +[lease-script](lease-script.md). + +See also +-------- + +* [Comment DHCP leases with info from access list](dhcp-lease-comment.md) +* [Create DNS records for DHCP leases](dhcp-to-dns.md) +* [Run other scripts on DHCP lease](lease-script.md) + +--- +[⬅️ 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 new file mode 100644 index 0000000..3894d52 --- /dev/null +++ b/doc/daily-psk.md @@ -0,0 +1,88 @@ +Use wireless network with daily psk +=================================== + +[](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 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 `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 `wifi`: + + $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 legacy CAPsMAN: + + $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; + +For legacy local interface: + + $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. + +Configuration +------------- + +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 + +> ℹ️ **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"; + +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) diff --git a/doc/dhcp-lease-comment.md b/doc/dhcp-lease-comment.md new file mode 100644 index 0000000..f95b124 --- /dev/null +++ b/doc/dhcp-lease-comment.md @@ -0,0 +1,64 @@ +Comment DHCP leases with info from access list +============================================== + +[](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 comments to dynamic dhcp server leases. Infos are taken +from wireless access list. + +Requirements and installation +----------------------------- + +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 legacy CAPsMAN: + + $ScriptInstallUpdate dhcp-lease-comment.capsman; + +For legacy local interface: + + $ScriptInstallUpdate dhcp-lease-comment.local; + +Configuration +------------- + +Infos are taken from wireless access list. Add entries with proper comments +there. You may want to use [collect-wireless-mac](collect-wireless-mac.md) +to prepare entries. + +Usage and invocation +-------------------- + +Run this script from a dhcp server as lease-script to update the comment +just after a new address is leased. You may want to use +[lease-script](lease-script.md). + +See also +-------- + +* [Collect MAC addresses in wireless access list](collect-wireless-mac.md) +* [Create DNS records for DHCP leases](dhcp-to-dns.md) +* [Run other scripts on DHCP lease](lease-script.md) + +--- +[⬅️ 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 new file mode 100644 index 0000000..13d5ef3 --- /dev/null +++ b/doc/dhcp-to-dns.md @@ -0,0 +1,93 @@ +Create DNS records for DHCP leases +================================== + +[](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 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 +----------------------------- + +Just install the script: + + $ScriptInstallUpdate dhcp-to-dns; + +Then run it from dhcp server as lease script. You may want to use +[lease-script](lease-script.md). + +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; + +Configuration +------------- + +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 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 + +> ℹ️ **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) diff --git a/doc/early-errors.md b/doc/early-errors.md new file mode 100644 index 0000000..b3c6800 --- /dev/null +++ b/doc/early-errors.md @@ -0,0 +1,2 @@ +This script has been replaced. Please migrate to +[Forward log messages via notification](log-forward.md). diff --git a/doc/email-backup.md b/doc/email-backup.md new file mode 100644 index 0000000..d674743 --- /dev/null +++ b/doc/email-backup.md @@ -0,0 +1 @@ +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..e9a8ff7 --- /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/), [dshield.org](https://dshield.org/) +and [blocklist.de](https://www.blocklist.de/), 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 new file mode 100644 index 0000000..7006fb3 --- /dev/null +++ b/doc/gps-track.md @@ -0,0 +1,51 @@ +Send GPS position 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 is supposed to run periodically from scheduler and send GPS +position data to a server for tracking. + +A hardware GPS antenna is required. + +Requirements and installation +----------------------------- + +Just install the script: + + $ScriptInstallUpdate gps-track; + +... and create a scheduler: + + /system/scheduler/add interval=1m name=gps-track on-event="/system/script/run gps-track;" start-time=startup; + +Configuration +------------- + +The configuration goes to `global-config-overlay`, the only parameter is: + +* `GpsTrackUrl`: the url to send json data 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. + +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) diff --git a/doc/hotspot-to-wpa.md b/doc/hotspot-to-wpa.md new file mode 100644 index 0000000..275fe4d --- /dev/null +++ b/doc/hotspot-to-wpa.md @@ -0,0 +1,124 @@ +Use WPA network with hotspot credentials +======================================== + +[](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 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 WPA enabled +SSID with suffix "`-wpa`". + +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. + +For `wifi`: + + $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; + +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 +------------- + +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. + +Create hotspot login credentials: + + /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 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) diff --git a/doc/ip-addr-bridge.md b/doc/ip-addr-bridge.md new file mode 100644 index 0000000..941a8ae --- /dev/null +++ b/doc/ip-addr-bridge.md @@ -0,0 +1,39 @@ +Manage IP addresses with bridge status +====================================== + +[](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 +----------- + +With RouterOS an IP address is always active, even if an interface is down. +Other venders handle this differently - and sometimes this behavior is +expected. This script mimics this behavior. + +Requirements and installation +----------------------------- + +Just install the script: + + $ScriptInstallUpdate ip-addr-bridge; + +... and make it run from scheduler: + + /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 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) 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 new file mode 100644 index 0000000..20265fe --- /dev/null +++ b/doc/ipv6-update.md @@ -0,0 +1,80 @@ +Update configuration on IPv6 prefix change +========================================== + +[](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 (prefixes (`/64`) and host addresses (`/128`)) +* dns records + +Requirements and installation +----------------------------- + +Just install the script: + + $ScriptInstallUpdate ipv6-update; + +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; + +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; + +Sometimes dhcp client is stuck on reconnect and needs to be released. +Installing [ppp-on-up](ppp-on-up.md) may solve this. + +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; + +As this entry is mandatory it is created automatically if it does not exist, +with the comment also set for list. + +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; + +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; + +See also +-------- + +* [Run scripts on ppp connection](ppp-on-up.md) + +--- +[⬅️ Go back to main README](../README.md) +[⬆️ Go back to top](#top) diff --git a/doc/lease-script.md b/doc/lease-script.md new file mode 100644 index 0000000..4d2f3bc --- /dev/null +++ b/doc/lease-script.md @@ -0,0 +1,54 @@ +Run other scripts on DHCP lease +=============================== + +[](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. 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: + +* [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 +----------------------------- + +Just install the script: + + $ScriptInstallUpdate lease-script; + +... and add it as `lease-script` to your dhcp server: + + /ip/dhcp-server/set lease-script=lease-script [ find ]; + +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) diff --git a/doc/leds-mode.md b/doc/leds-mode.md new file mode 100644 index 0000000..90ea418 --- /dev/null +++ b/doc/leds-mode.md @@ -0,0 +1,57 @@ +Manage LEDs dark mode +===================== + +[](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 +----------- + +These scripts control LEDs mode and allow to run your device +completely dark. Hardware support for dark mode is required. + +Requirements and installation +----------------------------- + +Just install the scripts: + + $ScriptInstallUpdate leds-day-mode,leds-night-mode,leds-toggle-mode; + +Usage and invocation +-------------------- + +To switch the device to dark mode: + + /system/script/run leds-night-mode; + +... and back to normal mode: + + /system/script/run leds-day-mode; + +To toggle between the two modes: + + /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; + +The script `leds-toggle-mode` can be used from [mode button](mode-button.md) +to toggle mode. + +See also +-------- + +* [Mode button with multiple presses](mode-button.md) + +--- +[⬅️ 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 new file mode 100644 index 0000000..44409dc --- /dev/null +++ b/doc/log-forward.md @@ -0,0 +1,95 @@ +Forward log messages via notification +===================================== + +[](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 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, or breaks intermittently +* lots of messages generate a flood of mails +* 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) + +It is intended to be run periodically from scheduler, then collects new +log messages and forwards them via notification. + +### Sample notification + + + +Requirements and installation +----------------------------- + +Just install the script: + + $ScriptInstallUpdate log-forward; + +... and add a scheduler: + + /system/scheduler/add interval=1m name=log-forward on-event="/system/script/run log-forward;" start-time=startup; + +Configuration +------------- + +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)"; + +This will match on every log message beginning with `router rebooted`. + +--- +[⬅️ 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 new file mode 100644 index 0000000..8734352 --- /dev/null +++ b/doc/mode-button.md @@ -0,0 +1,75 @@ +Mode button with multiple presses +================================= + +[](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 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 +can configure the reset button to act the same, see +`/system/routerboard/reset-button`. + +Copy this code to terminal to check: + +``` +: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={ + :put "Mode button is not supported, but reset button is."; + } else={ + :put "Neither mode button nor reset button is supported."; + } +} +``` + +Requirements and installation +----------------------------- + +Just install the script: + + $ScriptInstallUpdate mode-button; + +Then configure the mode button to 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;"; + +Configuration +------------- + +The configuration goes to `global-config-overlay`, these are the parameters: + +* `ModeButton`: an array with defined actions +* `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. 😜 + +--- +[⬅️ 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 new file mode 100644 index 0000000..2db32bb --- /dev/null +++ b/doc/netwatch-notify.md @@ -0,0 +1,189 @@ +Notify on host up and down +========================== + +[](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` +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 +----------------------------- + +Just install the script: + + $ScriptInstallUpdate netwatch-notify; + +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; + +Configuration +------------- + +The hosts to be checked have to be added to netwatch with specific comment: + + /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, note that some characters need extra escaping: + + /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, 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, 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. + +### 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) diff --git a/doc/netwatch-syslog.md b/doc/netwatch-syslog.md new file mode 100644 index 0000000..6a337d4 --- /dev/null +++ b/doc/netwatch-syslog.md @@ -0,0 +1,5 @@ +This script has been dropped. Filtering in firewall is advised, which should +look something like this: + + /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 new file mode 100644 index 0000000..121f77b --- /dev/null +++ b/doc/ospf-to-leds.md @@ -0,0 +1,44 @@ +Visualize OSPF state via LEDs +============================= + +[](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 +----------- + +Physical interfaces have their state LEDs, software-defined connectivity +does not. This script helps to visualize whether or not an OSPF instance +is running. + +Requirements and installation +----------------------------- + +Just install the script: + + $ScriptInstallUpdate ospf-to-leds; + +... 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; + +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"; + +--- +[⬅️ Go back to main README](../README.md) +[⬆️ Go back to top](#top) diff --git a/doc/packages-update.md b/doc/packages-update.md new file mode 100644 index 0000000..fae3896 --- /dev/null +++ b/doc/packages-update.md @@ -0,0 +1,78 @@ +Manage system update +==================== + +[](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 +packages. This script tries to avoid this situation by doing some basic +verification. + +But it provides some extra functionality: + +* 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 +----------------------------- + +Just install the script: + + $ScriptInstallUpdate packages-update; + +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; + +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) +* [Automatically upgrade firmware and reboot](firmware-upgrade-reboot.md) + +--- +[⬅️ 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 new file mode 100644 index 0000000..21847c7 --- /dev/null +++ b/doc/ppp-on-up.md @@ -0,0 +1,44 @@ +Run scripts on ppp connection +============================= + +[](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 on established ppp connection. Currently +it does: + +* release IPv6 dhcp leases (and thus force a renew) +* run [update-tunnelbroker](update-tunnelbroker.md) + +Requirements and installation +----------------------------- + +Just install the script: + + $ScriptInstallUpdate ppp-on-up; + +... and make it the `on-up` script for ppp profile: + + /ppp/profile/set on-up=ppp-on-up [ find ]; + +See also +-------- + +* [Update configuration on IPv6 prefix change](ipv6-update.md) +* [Update tunnelbroker configuration](update-tunnelbroker.md) + +--- +[⬅️ Go back to main README](../README.md) +[⬆️ Go back to top](#top) diff --git a/doc/rotate-ntp.md b/doc/rotate-ntp.md new file mode 100644 index 0000000..9a016a3 --- /dev/null +++ b/doc/rotate-ntp.md @@ -0,0 +1,3 @@ +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 new file mode 100644 index 0000000..b4678af --- /dev/null +++ b/doc/sms-action.md @@ -0,0 +1,63 @@ +Act on received SMS +=================== + +[](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 can act on received SMS. Reboot the device from remote or do +whatever is required. + +A broadband interface with SMS support is required. + +Requirements and installation +----------------------------- + +Just install the script: + + $ScriptInstallUpdate sms-action; + +Configuration +------------- + +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; + +Usage and invocation +-------------------- + +Send a SMS from allowed number to your device's phone number: + + :cmd s3cr3t script sms-action action=reboot; + +The value given by "`action=`" is one of the pre-defined actions from +`SmsAction`. + +See also +-------- + +* [Forward received SMS](sms-forward.md) + +--- +[⬅️ 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 new file mode 100644 index 0000000..597410b --- /dev/null +++ b/doc/sms-forward.md @@ -0,0 +1,98 @@ +Forward received SMS +==================== + +[](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 can receive SMS. This script forwards SMS as notification. + +A broadband interface with SMS support is required. + +### Sample notification + + + +Requirements and installation +----------------------------- + +Just install the script: + + $ScriptInstallUpdate sms-forward; + +... 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; + +Configuration +------------- + +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\";" }; + }; + +Adjust the values to your own needs. + +See also +-------- + +* [Act on received SMS](sms-action.md) + +--- +[⬅️ 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 new file mode 100644 index 0000000..d1325aa --- /dev/null +++ b/doc/ssh-keys-import.md @@ -0,0 +1,2 @@ +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 new file mode 100644 index 0000000..e4bae2e --- /dev/null +++ b/doc/super-mario-theme.md @@ -0,0 +1,38 @@ +Play Super Mario theme +====================== + +[](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 +----------- + +This script plays Super Mario theme. + +The hardware needs a beeper. + +Requirements and installation +----------------------------- + +Just install the script: + + $ScriptInstallUpdate super-mario-theme; + +Usage and invocation +-------------------- + +Just run the script to play: + + /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) 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 new file mode 100644 index 0000000..6680447 --- /dev/null +++ b/doc/unattended-lte-firmware-upgrade.md @@ -0,0 +1,54 @@ +Install LTE firmware upgrade +============================ + +[](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 +----------- + +This script upgrades LTE firmware on compatible devices: + +* R11e-LTE +* 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. + +Requirements and installation +----------------------------- + +The firmware is downloaded over the air, so a working broadband connection +on the lte interface to be updated is required! Having internet access from +different gateway is not sufficient! + +Just install the script: + + $ScriptInstallUpdate unattended-lte-firmware-upgrade; + +Usage and invocation +-------------------- + +Run the script if an upgrade for your LTE hardware is available: + + /system/script/run unattended-lte-firmware-upgrade; + +Then be patient, go for a coffee and wait for the upgrade process to finish. + +See also +-------- + +* [Notify on LTE firmware upgrade](check-lte-firmware-upgrade.md) + +--- +[⬅️ 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 new file mode 100644 index 0000000..80902b9 --- /dev/null +++ b/doc/update-gre-address.md @@ -0,0 +1,48 @@ +Update GRE configuration with dynamic addresses +=============================================== + +[](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 +----------- + +Running a GRE tunnel over IPSec with IKEv2 is a common scenario. This is +easy to configure on client, but has an issue on server side: client IP +addresses are assigned dynamically via mode-config and have to be updated +for GRE interface. + +This script handles the address updates and disables the interface if the +client is disconnected. + +Requirements and installation +----------------------------- + +Just install the script: + + $ScriptInstallUpdate update-gre-address; + +... 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; + +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; + +--- +[⬅️ Go back to main README](../README.md) +[⬆️ Go back to top](#top) diff --git a/doc/update-tunnelbroker.md b/doc/update-tunnelbroker.md new file mode 100644 index 0000000..2539e2f --- /dev/null +++ b/doc/update-tunnelbroker.md @@ -0,0 +1,50 @@ +Update tunnelbroker configuration +================================= + +[](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 +----------- + +Connecting to [tunnelbroker.net](//tunnelbroker.net) from dynamic public +ip address requires the address to be sent to the remote, and to be set +locally. This script does both. + +Requirements and installation +----------------------------- + +Just install the script: + + $ScriptInstallUpdate update-tunnelbroker; + +Installing [ppp-on-up](ppp-on-up.md) makes this script run when ever a ppp +connection is established. + +Configuration +------------- + +The configuration goes to interface's comment: + + /interface/6to4/set comment="tunnelbroker, user=user, id=12345, pass=s3cr3t" tunnelbroker; + +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 +-------- + +* [Run scripts on ppp connection](ppp-on-up.md) + +--- +[⬅️ Go back to main README](../README.md) +[⬆️ Go back to top](#top) diff --git a/doc/upload-backup.md b/doc/upload-backup.md new file mode 100644 index 0000000..83c9991 --- /dev/null +++ b/doc/upload-backup.md @@ -0,0 +1 @@ +This script has been renamed. Please see [backup-upload](backup-upload.md). |
