aboutsummaryrefslogtreecommitdiffstats
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md176
1 files changed, 128 insertions, 48 deletions
diff --git a/README.md b/README.md
index df3cb9e..614095a 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,12 @@
RouterOS Scripts
================
-[![GitHub stars](https://img.shields.io/github/stars/eworm-de/routeros-scripts?style=social)](https://github.com/eworm-de/routeros-scripts/stargazers)
-[![GitHub forks](https://img.shields.io/github/forks/eworm-de/routeros-scripts?style=social)](https://github.com/eworm-de/routeros-scripts/network)
-[![GitHub watchers](https://img.shields.io/github/watchers/eworm-de/routeros-scripts?style=social)](https://github.com/eworm-de/routeros-scripts/watchers)
+[![GitHub stars](https://img.shields.io/github/stars/eworm-de/routeros-scripts?logo=GitHub&style=flat&color=red)](https://github.com/eworm-de/routeros-scripts/stargazers)
+[![GitHub forks](https://img.shields.io/github/forks/eworm-de/routeros-scripts?logo=GitHub&style=flat&color=green)](https://github.com/eworm-de/routeros-scripts/network)
+[![GitHub watchers](https://img.shields.io/github/watchers/eworm-de/routeros-scripts?logo=GitHub&style=flat&color=blue)](https://github.com/eworm-de/routeros-scripts/watchers)
+[![required RouterOS version](https://img.shields.io/badge/RouterOS-7.12-yellow?style=flat)](https://mikrotik.com/download/changelogs/)
+[![Telegram group @routeros_scripts](https://img.shields.io/badge/Telegram-%40routeros__scripts-%2326A5E4?logo=telegram&style=flat)](https://t.me/routeros_scripts)
+[![donate with PayPal](https://img.shields.io/badge/Like_it%3F-Donate!-orange?logo=githubsponsors&logoColor=orange&style=flat)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=A4ZXBD6YS2W8J)
![RouterOS Scripts Logo](logo.svg)
@@ -18,14 +21,27 @@ to manage RouterOS devices or extend their functionality.
Requirements
------------
+### Software (RouterOS)
+
Latest version of the scripts require recent RouterOS to function properly.
-Make sure to install latest updates before you begin.
+Make sure to install latest updates before you begin. If new functionality
+or a breaking change in RouterOS `7.n` is used in my scripts I push my
+change some time after `7.(n+1)` was released. At any time you should have
+at least two minor and their bugfix releases to choose from.
Specific scripts may require even newer RouterOS version.
> ℹ️ **Info**: The `main` branch is now RouterOS v7 only. If you are still
> running RouterOS v6 switch to `routeros-v6` branch!
+### Hardware
+
+RouterOS packages increase in size with each release. This becomes a
+problem for devices with 16MB storage and below, those with an ARM CPU
+are specifically affected.
+
+Huge configuration and lots of scripts give an extra risk. **Take care!**
+
Initial setup
-------------
@@ -53,7 +69,7 @@ download the certificates. If you intend to download the scripts from a
different location (for example from github.com) install the corresponding
certificate chain.
- /tool/fetch "https://git.eworm.de/cgit/routeros-scripts/plain/certs/R3.pem" dst-path="letsencrypt-R3.pem";
+ /tool/fetch "https://git.eworm.de/cgit/routeros-scripts/plain/certs/E1.pem" dst-path="letsencrypt-E1.pem";
![screenshot: download certs](README.d/01-download-certs.avif)
@@ -61,21 +77,25 @@ Note that the commands above do *not* verify server certificate, so if you
want to be safe download with your workstations's browser and transfer the
files to your MikroTik device.
-* [ISRG Root X1](https://letsencrypt.org/certs/isrgrootx1.pem)
-* Let's Encrypt [R3](https://letsencrypt.org/certs/lets-encrypt-r3.pem)
+* [ISRG Root X2](https://letsencrypt.org/certs/isrg-root-x2.pem)
+* Let's Encrypt [E1](https://letsencrypt.org/certs/lets-encrypt-e1.pem)
Then we import the certificates.
- /certificate/import file-name=letsencrypt-R3.pem passphrase="";
+ /certificate/import file-name=letsencrypt-E1.pem passphrase="";
+
+Do not worry that the command is not shown - that happens because it contains
+a sensitive property, the passphrase.
![screenshot: import certs](README.d/02-import-certs.avif)
-For basic verification we rename the certificates and print their count. Make
-sure the certificate count is **two**.
+For basic verification we rename the certificates and print them by
+fingerprint. Make sure exactly these two certificates ("*E1*" and
+"*ISRG-Root-X2*") are shown.
- /certificate/set name="R3" [ find where fingerprint="67add1166b020ae61b8f5fc96813c04c2aa589960796865572a3c7e737613dfd" ];
- /certificate/set name="ISRG-Root-X1" [ find where fingerprint="96bcec06264976f37460779acf28c5a7cfe8a3c0aae11a8ffcee05c0bddf08c6" ];
- /certificate/print count-only where fingerprint="67add1166b020ae61b8f5fc96813c04c2aa589960796865572a3c7e737613dfd" or fingerprint="96bcec06264976f37460779acf28c5a7cfe8a3c0aae11a8ffcee05c0bddf08c6";
+ /certificate/set name="E1" [ find where common-name="E1" ];
+ /certificate/set name="ISRG-Root-X2" [ find where common-name="ISRG Root X2" ];
+ /certificate/print proplist=name where fingerprint="46494e30379059df18be52124305e606fc59070e5b21076ce113954b60517cda" or fingerprint="69729b8e15a86efc177a57afb7171dfc64add28c2fca8cf1507e34453ccb1470";
![screenshot: check certs](README.d/03-check-certs.avif)
@@ -87,32 +107,56 @@ date and time is set correctly!
Now let's download the main scripts and add them in configuration on the fly.
- :foreach Script in={ "global-config"; "global-config-overlay"; "global-functions" } do={ /system/script/add name=$Script source=([ /tool/fetch check-certificate=yes-without-crl ("https://git.eworm.de/cgit/routeros-scripts/plain/" . $Script) output=user as-value]->"data"); };
+ :foreach Script in={ "global-config"; "global-config-overlay"; "global-functions" } do={ /system/script/add name=$Script owner=$Script source=([ /tool/fetch check-certificate=yes-without-crl ("https://git.eworm.de/cgit/routeros-scripts/plain/" . $Script . ".rsc") output=user as-value]->"data"); };
![screenshot: import scripts](README.d/04-import-scripts.avif)
+And finally load configuration and functions and add the scheduler.
+
+ /system/script { run global-config; run global-functions; };
+ /system/scheduler/add name="global-scripts" start-time=startup on-event="/system/script { run global-config; run global-functions; }";
+
+![screenshot: run and schedule scripts](README.d/05-run-and-schedule-scripts.avif)
+
+### Scheduled automatic updates
+
+The last step is optional: Add this scheduler **only** if you want the
+scripts to be updated automatically!
+
+ /system/scheduler/add name="ScriptInstallUpdate" start-time=startup interval=1d on-event=":global ScriptInstallUpdate; \$ScriptInstallUpdate;";
+
+![screenshot: schedule update](README.d/06-schedule-update.avif)
+
+Editing configuration
+---------------------
+
The configuration needs to be tweaked for your needs. Edit
-`global-config-overlay`, copy configuration from
-[`global-config`](global-config) (the one without `-overlay`).
+`global-config-overlay`, copy relevant configuration from
+[`global-config`](global-config.rsc) (the one without `-overlay`).
Save changes and exit with `Ctrl-o`.
- /system/script edit global-config-overlay source;
+ /system/script/edit global-config-overlay source;
-![screenshot: edit global-config-overlay](README.d/05-edit-global-config-overlay.avif)
+![screenshot: edit global-config-overlay](README.d/07-edit-global-config-overlay.avif)
-And finally load configuration and functions and add the scheduler.
+Additionally creating configuration snippets is supported. The script name
+of these snippets has to start with `global-config-overlay.d/` to make them
+being loaded automatically. This allows to split off parts of the
+configuration.
- /system/script { run global-config; run global-functions; };
- /system/scheduler/add name="global-scripts" start-time=startup on-event="/system/script { run global-config; run global-functions; }";
+To apply your changes run `global-config`, which will automatically load
+the overlay as well:
-![screenshot: run and schedule scripts](README.d/06-run-and-schedule-scripts.avif)
+ /system/script/run global-config;
-The last step is optional: Add this scheduler **only** if you want the scripts
-to be updated automatically!
+![screenshot: apply configuration](README.d/08-apply-configuration.avif)
- /system/scheduler/add name="ScriptInstallUpdate" start-time=startup interval=1d on-event=":global ScriptInstallUpdate; \$ScriptInstallUpdate;";
+This last step is required when ever you make changes to your configuration.
-![screenshot: schedule update](README.d/07-schedule-update.avif)
+> ℹ️ **Info**: It is recommended to edit the configuration using the command
+> line interface. If using Winbox on Windows OS, the line endings may be
+> missing. To fix this run:
+> `/system/script/set source=[ $Unix2Dos [ get global-config-overlay source ] ] global-config-overlay;`
Updating scripts
----------------
@@ -122,7 +166,12 @@ everything is up-to-date it will not produce any output.
$ScriptInstallUpdate;
-![screenshot: update scripts](README.d/08-update-scripts.avif)
+![screenshot: update scripts](README.d/09-update-scripts.avif)
+
+If the update includes news or requires configuration changes a notification
+is sent - in addition to terminal output and log messages.
+
+![news and changes notification](README.d/notification-news-and-changes.avif)
Adding a script
---------------
@@ -132,7 +181,7 @@ a comma separated list of script names.
$ScriptInstallUpdate check-certificates,check-routeros-update;
-![screenshot: install scripts](README.d/09-install-scripts.avif)
+![screenshot: install scripts](README.d/10-install-scripts.avif)
Scheduler and events
--------------------
@@ -144,7 +193,7 @@ miss an update.
/system/scheduler/add name="check-routeros-update" interval=1h on-event="/system/script/run check-routeros-update;";
-![screenshot: schedule script](README.d/10-schedule-script.avif)
+![screenshot: schedule script](README.d/11-schedule-script.avif)
Some events can run a script. If you want your DHCP hostnames to be available
in DNS use `dhcp-to-dns` with the events from dhcp server. For a regular
@@ -154,7 +203,7 @@ cleanup add a scheduler entry.
/ip/dhcp-server/set lease-script=lease-script [ find ];
/system/scheduler/add name="dhcp-to-dns" interval=5m on-event="/system/script/run dhcp-to-dns;";
-![screenshot: setup lease script](README.d/11-setup-lease-script.avif)
+![screenshot: setup lease script](README.d/12-setup-lease-script.avif)
There's much more to explore... Have fun!
@@ -178,9 +227,10 @@ Available scripts
* [Comment DHCP leases with info from access list](doc/dhcp-lease-comment.md)
* [Create DNS records for DHCP leases](doc/dhcp-to-dns.md)
* [Automatically upgrade firmware and reboot](doc/firmware-upgrade-reboot.md)
+* [Download, import and update firewall address-lists](doc/fw-addr-lists.md)
* [Wait for global functions und modules](doc/global-wait.md)
* [Send GPS position to server](doc/gps-track.md)
-* [Use WPA2 network with hotspot credentials](doc/hotspot-to-wpa.md)
+* [Use WPA network with hotspot credentials](doc/hotspot-to-wpa.md)
* [Create DNS records for IPSec peers](doc/ipsec-to-dns.md)
* [Update configuration on IPv6 prefix change](doc/ipv6-update.md)
* [Manage IP addresses with bridge status](doc/ip-addr-bridge.md)
@@ -190,23 +240,17 @@ Available scripts
* [Mode button with multiple presses](doc/mode-button.md)
* [Manage DNS and DoH servers from netwatch](doc/netwatch-dns.md)
* [Notify on host up and down](doc/netwatch-notify.md)
-* [Manage remote logging](doc/netwatch-syslog.md)
* [Visualize OSPF state via LEDs](doc/ospf-to-leds.md)
* [Manage system update](doc/packages-update.md)
* [Run scripts on ppp connection](doc/ppp-on-up.md)
-* [Rotate NTP servers](doc/rotate-ntp.md)
* [Act on received SMS](doc/sms-action.md)
* [Forward received SMS](doc/sms-forward.md)
-* [Import SSH keys](doc/ssh-keys-import.md)
* [Play Super Mario theme](doc/super-mario-theme.md)
+* [Chat with your router and send commands via Telegram bot](doc/telegram-chat.md)
* [Install LTE firmware upgrade](doc/unattended-lte-firmware-upgrade.md)
* [Update GRE configuration with dynamic addresses](doc/update-gre-address.md)
* [Update tunnelbroker configuration](doc/update-tunnelbroker.md)
-[comment]: # (TODO: currently undocumented)
-[comment]: # (* learn-mac-based-vlan)
-[comment]: # (* manage-umts)
-
Available modules
-----------------
@@ -214,9 +258,12 @@ Available modules
* [Manage VLANs on bridge ports](doc/mod/bridge-port-vlan.md)
* [Inspect variables](doc/mod/inspectvar.md)
* [IP address calculation](doc/mod/ipcalc.md)
+* [Send notifications via e-mail](doc/mod/notification-email.md)
* [Send notifications via Matrix](doc/mod/notification-matrix.md)
+* [Send notifications via Ntfy](doc/mod/notification-ntfy.md)
* [Send notifications via Telegram](doc/mod/notification-telegram.md)
* [Download script and run it once](doc/mod/scriptrunonce.md)
+* [Import ssh keys for public key authentication](doc/mod/ssh-keys-import.md)
Installing custom scripts & modules
-----------------------------------
@@ -227,12 +274,9 @@ still use my scripts to manage and deploy yours, by specifying `base-url`
This will fetch and install a script `hello-world.rsc` from the given url:
- $ScriptInstallUpdate hello-world.rsc "base-url=https://git.eworm.de/cgit/routeros-scripts/plain/README.d/";
-
-![screenshot: install custom script](README.d/12-install-custom-script.avif)
+ $ScriptInstallUpdate hello-world "base-url=https://git.eworm.de/cgit/routeros-scripts-custom/plain/";
-(Yes, the example url still belongs to the repository for easy
-handling - but the url can be what ever you use.)
+![screenshot: install custom script](README.d/13-install-custom-script.avif)
For a script to be considered valid it has to begin with a *magic token*.
Have a look at [any script](README.d/hello-world.rsc) and copy the first line
@@ -241,12 +285,44 @@ without modification.
Starting a script's name with `mod/` makes it a module and it is run
automatically by `global-functions`.
+### Linked custom scripts & modules
+
+> ⚠️ **Warning**: These links are being provided for your convenience only;
+> they do not constitute an endorsement or an approval by me. I bear no
+> responsibility for the accuracy, legality or content of the external site
+> or for that of subsequent links. Contact the external site for answers to
+> questions regarding its content.
+
+* [Hello World](https://git.eworm.de/cgit/routeros-scripts-custom/about/doc/hello-world.md)
+ (This is a demo script to show how the linking to external documentation
+ will be done.)
+
+> ℹ️ **Info**: You have your own set of scripts and/or modules and want these
+> to be listed here? There should be a general info page that links here,
+> and documentation for each script. You can start by cloning my
+> [Custom RouterOS-Scripts](https://git.eworm.de/cgit/routeros-scripts-custom/)
+> (or fork on [GitHub](https://github.com/eworm-de/routeros-scripts-custom)
+> or [GitLab](https://gitlab.com/eworm-de/routeros-scripts-custom)) and make
+> your changes. Then please [get in contact](#patches-issues-and-whishlist)...
+
+Removing a script
+-----------------
+
+There is no specific function for script removal. Just remove it from
+configuration...
+
+ /system/script/remove to-be-removed;
+
+![screenshot: remove script](README.d/14-remove-script.avif)
+
+Possibly a scheduler and other configuration has to be removed as well.
+
Contact
-------
We have a Telegram Group [RouterOS-Scripts](https://t.me/routeros_scripts)!
-![RouterOS Scripts Telegram Group](README.d/telegram-group.avif)
+[![RouterOS Scripts Telegram Group](README.d/telegram-group.avif)](https://t.me/routeros_scripts)
Get help, give feedback or just chat - but do not expect free professional
support!
@@ -254,12 +330,14 @@ support!
Contribute
----------
-Thanks a lot for [past contributions](CONTRIBUTIONS.md)!
+Thanks a lot for [past contributions](CONTRIBUTIONS.md)! ❤️
### Patches, issues and whishlist
Feel free to contact me via e-mail or open an
-[issue at github](https://github.com/eworm-de/routeros-scripts/issues).
+[issue](https://github.com/eworm-de/routeros-scripts/issues) or
+[pull request](https://github.com/eworm-de/routeros-scripts/pulls)
+at github.
### Donate
@@ -268,7 +346,7 @@ for you. If you like the scripts and think this is of value for you or your
business please consider to
[donate with PayPal](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=A4ZXBD6YS2W8J).
-[![donate with PayPal](https://www.paypalobjects.com/en_US/i/btn/btn_donate_SM.gif)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=A4ZXBD6YS2W8J)
+[![donate with PayPal](https://img.shields.io/badge/Like_it%3F-Donate!-orange?logo=githubsponsors&logoColor=orange&style=for-the-badge)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=A4ZXBD6YS2W8J)
Thanks a lot for your support!
@@ -288,6 +366,8 @@ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
Upstream
--------
+![upstream](README.d/upstream.png)
+
URL:
[GitHub.com](https://github.com/eworm-de/routeros-scripts#routeros-scripts)
@@ -296,4 +376,4 @@ Mirror:
[GitLab.com](https://gitlab.com/eworm-de/routeros-scripts#routeros-scripts)
---
-[▲ Go back to top](#top)
+[⬆️ Go back to top](#top)