diff options
Diffstat (limited to 'doc')
37 files changed, 1612 insertions, 46 deletions
diff --git a/doc/accesslist-duplicates.md b/doc/accesslist-duplicates.md new file mode 100644 index 0000000..2189322 --- /dev/null +++ b/doc/accesslist-duplicates.md @@ -0,0 +1,49 @@ +Find and remove access list duplicates +====================================== + +[◀ Go back to main README](../README.md) + +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 CAPsMAN (`/ caps-man`) or local wireless +interface (`/ interface wireless`) you need to install a different script. + +For CAPsMAN: + + $ScriptInstallUpdate accesslist-duplicates.capsman; + +For local interface: + + $ScriptInstallUpdate accesslist-duplicates.local; + +Usage and invocation +-------------------- + +Run this script from a terminal: + + [admin@kalyke] > / system script run accesslist-duplicates.local + Flags: X - disabled + 0 ;;; First entry with identical mac address... + mac-address=00:11:22:33:44:55 interface=any signal-range=-120..120 allow-signal-out-of-range=10s authentication=yes forwarding=yes ap-tx-limit=0 client-tx-limit=0 private-algo=none private-key="" private-pre-shared-key="" management-protection-key="" vlan-mode=default vlan-id=1 + + 1 ;;; Second entry with identical mac address... + mac-address=00:11:22:33:44:55 interface=any signal-range=-120..120 allow-signal-out-of-range=10s authentication=yes forwarding=yes ap-tx-limit=0 client-tx-limit=0 private-algo=none private-key="" private-pre-shared-key="" management-protection-key="" vlan-mode=default vlan-id=1 + + Numeric id to remove, any key to skip! + Removing numeric id 1... + +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/bridge-port.md b/doc/bridge-port.md new file mode 100644 index 0000000..2228ac8 --- /dev/null +++ b/doc/bridge-port.md @@ -0,0 +1,84 @@ +Manage ports in bridge +====================== + +[◀ Go back to main README](../README.md) + +Description +----------- + +These scripts are supposed to handle interfaces and switching them from +one bridge to another. + +Requirements and installation +----------------------------- + +Just install the scripts: + + $ScriptInstallUpdate bridge-port-to-default,bridge-port-toggle; + +Configuration +------------- + +The configuration goes to ports' comments (`/ interface bridge port`). + + / interface bridge port add bridge=br-guest comment="default=dhcp-client, alt=br-guest" disabled=yes interface=en1; + / interface bridge port add bridge=br-intern comment="default=br-intern, alt=br-guest" interface=en2; + / interface bridge port add bridge=br-guest comment="default=br-guest, extra=br-extra" interface=en3; + +Also dhcp client can be handled: + + / ip dhcp-client add comment="toggle with bridge port" disabled=no interface=en1; + +There is also global configuration: + +* `BridgePortTo`: specify the configuration to be applied by default + +Install [global-wait](global-wait.md) and add a scheduler to start with +default setup on system startup: + + / system scheduler add name=bridge-port-to-default on-event="/ system script { run global-wait; run bridge-port-to-default; }" start-time=startup; + +Usage and invocation +-------------------- + +The usage examples show what happens with the configuration from above. + +Running the script `bridge-port-to-default` applies all configuration given +with `default=`: + + / system script run bridge-port-to-default; + +For the three interfaces we get this configuration: + +* The special value `dhcp-client` enables the dhcp client for interface `en1`. The bridge port entry is disabled. +* Interface `en2` is put in bridge `br-intern`. +* Interface `en3` is put in bridge `br-guest`. + +Running the script `bridge-port-toggle` toggles to configuration given +with `alt=`: + + / system script run bridge-port-toggle; + +* Interface `en1` is put in bridge `br-guest`, dhcp client for the interface is disabled. +* Interface `en2` is put in bridge `br-guest`. +* Interface `en3` is unchanged, stays in bridge `br-guest`. + +Running the script `bridge-port-toggle` again toggles back to configuration +given with `default=`. + +More configuration can be loaded by setting `BridgePortTo`: + + :set BridgePortTo "extra"; + / system script run bridge-port-to-default; + +* Interfaces `en1` and `en2` are unchanged. +* Interface `en3` is put in bridge `br-intern`. + +See also +-------- + +* [Wait for configuration und functions](global-wait.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..ee4912d --- /dev/null +++ b/doc/capsman-download-packages.md @@ -0,0 +1,51 @@ +Download packages for CAP upgrade from CAPsMAN +============================================= + +[◀ Go back to main README](../README.md) + +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 +----------------------------- + +Just install the script on CAPsMAN device: + + $ScriptInstallUpdate capsman-download-packages; + +Optionally create a scheduler to run after startup, with a delay to ensure +internet connectivity is given: + + / system scheduler add name=capsman-download-packages on-event=":delay 2m; / system script run capsman-download-packages;" start-time=startup; + +Only packages available in older version are downloaded. For initial setup +place the required packages to CAPsMAN package path (see +`/ caps-man manager`). + +Usage and invocation +-------------------- + +Run the script manually: + + / system script run capsman-download-packages; + +... 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..e78c87a --- /dev/null +++ b/doc/capsman-rolling-upgrade.md @@ -0,0 +1,39 @@ +Run rolling CAP upgrades from CAPsMAN +===================================== + +[◀ Go back to main README](../README.md) + +Description +----------- + +CAPsMAN can upgrate 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. + + +Requirements and installation +----------------------------- + +Just install the script: + + $ScriptInstallUpdate capsman-rolling-upgrade; + +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; + +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..e460ce1 --- /dev/null +++ b/doc/certificate-renew-issued.md @@ -0,0 +1,47 @@ +Renew locally issued certificates +================================= + +[◀ Go back to main README](../README.md) + +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 + +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.md b/doc/check-certificates.md new file mode 100644 index 0000000..51ecd14 --- /dev/null +++ b/doc/check-certificates.md @@ -0,0 +1,52 @@ +Renew certificates and notify on expiration +=========================================== + +[◀ Go back to main README](../README.md) + +Description +----------- + +This script tries to download and renew certificates, then notifies about +certificates that are still about to expire. + +Requirements and installation +----------------------------- + +Just install the script: + + $ScriptInstallUpdate check-certificates; + +Configuration +------------- + +The expiry notifications just require notification settings for e-mail and +telegram. + +For automatic download and renewal of certificates you need configuration +in `global-config-overlay`, these are the parameters: + +* `CertRenewPass`: an array of passphrases to try +* `CertRenewUrl`: the url to download certificates from + +Certificates on the web server should be named `CN.pem` (`PEM` format) or +`CN.p12` (`PKCS#12` format). + +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; + +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.md b/doc/check-health.md new file mode 100644 index 0000000..37f8e34 --- /dev/null +++ b/doc/check-health.md @@ -0,0 +1,43 @@ +Notify about health state +========================= + +[◀ Go back to main README](../README.md) + +Description +----------- + +This script is run from scheduler periodically, sending notification on +health related events: + +* voltage jumps up or down more than configured threshold +* power supply failed or recovered +* temperature is above or below threshold + +Note that bad initial state will not trigger an event. + +Only sensors available in hardware can be checked. See what your +hardware supports: + + / system health print; + +Requirements and installation +----------------------------- + +Just install the script and create a scheduler: + + $ScriptInstallUpdate check-health; + / system scheduler add interval=1m name=check-health on-event="/ system script run check-health;" start-time=startup; + +Configuration +------------- + +The configuration goes to `global-config-overlay`, These are the parameters: + +* `CheckHealthTemperature`: an array specifying temperature thresholds for sensors +* `CheckHealthVoltagePercent`: percentage value to trigger voltage jumps + +Also notification settings are required for e-mail and telegram. + +--- +[◀ Go back to main README](../README.md) +[▲ Go back to top](#top) diff --git a/doc/check-lte-firmware-upgrade.md b/doc/check-lte-firmware-upgrade.md new file mode 100644 index 0000000..c71dee5 --- /dev/null +++ b/doc/check-lte-firmware-upgrade.md @@ -0,0 +1,41 @@ +Notify on LTE firmware upgrade +============================== + +[◀ Go back to main README](../README.md) + +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 + +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 +------------- + +Notification setting are required for e-mail and telegram. + +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.md b/doc/check-routeros-update.md new file mode 100644 index 0000000..c94381c --- /dev/null +++ b/doc/check-routeros-update.md @@ -0,0 +1,55 @@ +Notify on RouterOS update +========================= + +[◀ Go back to main README](../README.md) + +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. + +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 +------------- + +Configuration is required only if you want to control update process with +safe versions from a web server. The configuration goes to +`global-config-overlay`, this is the parameter: + +* `SafeUpdateUrl`: url to check for safe update, the channel (`long-term`, +`stable` or `testing`) is appended + +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. + +See also +-------- + +* [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..bda1267 --- /dev/null +++ b/doc/cloud-backup.md @@ -0,0 +1,46 @@ +Upload backup to Mikrotik cloud +=============================== + +[◀ Go back to main README](../README.md) + +Description +----------- + +This script uploads [binary backup to Mikrotik cloud](https://wiki.mikrotik.com/wiki/Manual:IP/Cloud#Backup). + +Requirements and installation +----------------------------- + +Just install the script: + + $ScriptInstallUpdate cloud-backup; + +Configuration +------------- + +The configuration goes to `global-config-overlay`, this is the only parameter: + +* `BackupPassword`: password to encrypt the backup with + +Also notification settings are required for e-mail and telegram. + +Usage and invocation +-------------------- + +Just run the script: + + / system script run cloud-backup; + +Creating a scheduler may be an option: + + / system scheduler add interval=1w name=cloud-backup on-event="/ system script run cloud-backup;" start-time=09:20:00; + +See also +-------- + +* [Send backup via e-mail](email-backup.md) +* [Upload backup to server](upload-backup.md) + +--- +[◀ Go back to main README](../README.md) +[▲ Go back to top](#top) diff --git a/doc/collect-wireless-mac.md b/doc/collect-wireless-mac.md new file mode 100644 index 0000000..45489bf --- /dev/null +++ b/doc/collect-wireless-mac.md @@ -0,0 +1,54 @@ +Collect MAC addresses in wireless access list +============================================= + +[◀ Go back to main README](../README.md) + +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. + +Requirements and installation +----------------------------- + +Depending on whether you use CAPsMAN (`/ caps-man`) or local wireless +interface (`/ interface wireless`) you need to install a different script. + +For CAPsMAN: + + $ScriptInstallUpdate collect-wireless-mac.capsman; + +For 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 and telegram. + +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.md b/doc/daily-psk.md new file mode 100644 index 0000000..e6d7aae --- /dev/null +++ b/doc/daily-psk.md @@ -0,0 +1,56 @@ +Use wireless network with daily psk +=================================== + +[◀ Go back to main README](../README.md) + +Description +----------- + +This script is supposed to provide a wifi network which changes the +passphrase to a pseudo-random string daily. + +Requirements and installation +----------------------------- + +Just install this script and [global-wait](global-wait.md). + +Depending on whether you use CAPsMAN (`/ caps-man`) or local wireless +interface (`/ interface wireless`) you need to install a different script. + +For CAPsMAN: + + $ScriptInstallUpdate daily-psk.capsman,global-wait; + +For local interface: + + $ScriptInstallUpdate daily-psk.local,global-wait; + +And add schedulers to run the script: + + / system scheduler add interval=1d name=daily-psk-nightly on-event="/ system script run daily-psk.local;" start-date=may/23/2018 start-time=03:00:00; + / system scheduler add name=daily-psk-startup on-event=":global WaitTimeSync; / system script { run global-wait; \$WaitTimeSync; 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 + +Then add an access list entry: + + / interface wireless access-list add comment="Daily PSK" interface=wl-daily private-pre-shared-key="ToBeChangedDaily"; + +Also notification settings are required for e-mail and telegram. + +See also +-------- + +* [Wait for configuration und functions](global-wait.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..caba7d6 --- /dev/null +++ b/doc/dhcp-lease-comment.md @@ -0,0 +1,49 @@ +Comment DHCP leases with info from access list +============================================== + +[◀ Go back to main README](../README.md) + +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 CAPsMAN (`/ caps-man`) or local wireless +interface (`/ interface wireless`) you need to install a different script. + +For CAPsMAN: + + $ScriptInstallUpdate dhcp-lease-comment.capsman; + +For 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..3f25659 --- /dev/null +++ b/doc/dhcp-to-dns.md @@ -0,0 +1,42 @@ +Create DNS records for DHCP leases +================================== + +[◀ Go back to main README](../README.md) + +Description +----------- + +This script adds (and removes) dns records based on dhcp server leases. + +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 +------------- + +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 dhcp/dns server's hostname + +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) +* [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/email-backup.md b/doc/email-backup.md new file mode 100644 index 0000000..7f89a06 --- /dev/null +++ b/doc/email-backup.md @@ -0,0 +1,52 @@ +Send backup via e-mail +====================== + +[◀ Go back to main README](../README.md) + +Description +----------- + +This script sends binary backup (`/ system backup save`) and complete +configuration export (`/ export terse`) via e-mail. + + +Requirements and installation +----------------------------- + +Just install the script: + + $ScriptInstallUpdate email-backup; + +Configuration +------------- + +The configuration goes to `global-config-overlay`, These are the parameters: + +* `BackupSendBinary`: whether to send binary backup +* `BackupSendExport`: whether to send configuration export +* `BackupPassword`: password to encrypt the backup with +* `EmailBackupTo`: e-mail address to send to +* `EmailBackupCc`: e-mail address(es) to send in copy + +Also valid e-mail settings in `/ tool e-mail` are required to send mails. + +Usage and invocation +-------------------- + +Just run the script: + + / system script run email-backup; + +Creating a scheduler may be an option: + + / system scheduler add interval=1w name=email-backup on-event="/ system script run email-backup;" start-time=09:15:00; + +See also +-------- + +* [Upload backup to Mikrotik cloud](cloud-backup.md) +* [Upload backup to server](upload-backup.md) + +--- +[◀ Go back to main README](../README.md) +[▲ Go back to top](#top) diff --git a/doc/global-wait.md b/doc/global-wait.md new file mode 100644 index 0000000..9fcaa96 --- /dev/null +++ b/doc/global-wait.md @@ -0,0 +1,34 @@ +Wait for configuration und functions +==================================== + +[◀ Go back to main README](../README.md) + +Description +----------- + +The global scripts `global-config`, `global-config-overlay` and +`global-functions` are run by scheduler at system startup. Running another +script 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. + +Requirements and installation +----------------------------- + +Just install the script: + + $ScriptInstallUpdate global-wait; + +... and add it to your scheduler, for example in combination with +[bridge-port](bridge-port.md): + + / system scheduler add name=bridge-port-to-default on-event="/ system script { run global-wait; run bridge-port-to-default; }" start-time=startup; + +See also +-------- + +* [Manage ports in bridge](bridge-port.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..a7b3d7f --- /dev/null +++ b/doc/gps-track.md @@ -0,0 +1,34 @@ +Send GPS position to server +=========================== + +[◀ Go back to main README](../README.md) + +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 + +--- +[◀ 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..fbb9640 --- /dev/null +++ b/doc/hotspot-to-wpa.md @@ -0,0 +1,48 @@ +Use WPA2 network with hotspot credentials +========================================= + +[◀ Go back to main README](../README.md) + +Description +----------- + +RouterOS supports an unlimited number of MAC address specific passphrases +for WPA2 encrypted wifi networks via access list. The idea of this script +is to transfer hotspot credentials to MAC address specific WPA2 passphrase. + +Requirements and installation +----------------------------- + +You need a properly configured hotspot on one (open) SSID and a WP2 enabled +SSID with suffix "`-wpa`". + +Then install the script: + + $ScriptInstallUpdate hotspot-to-wpa; + +Configure your hotspot to use this script as `on-login` script: + + / ip hotspot user profile set on-login=hotspot-to-wpa [ find ]; + +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. + +Usage and invocation +-------------------- + +Create hotspot login credentials: + + / ip hotspot user add add comment="Test User 1" name=user1 password=v3ry; + / ip hotspot user add add comment="Test User 2" name=user2 password=s3cr3t; + +Now let the users connect and login to the hotspot. After that the devices +(identified by MAC address) can connect to the WPA2 network, using the +passphrase from hotspot credentials. + +--- +[◀ 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..44dac6a --- /dev/null +++ b/doc/ip-addr-bridge.md @@ -0,0 +1,32 @@ +Manage IP addresses with bridge status +====================================== + +[◀ 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 lease 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/ipv6-update.md b/doc/ipv6-update.md new file mode 100644 index 0000000..93ada42 --- /dev/null +++ b/doc/ipv6-update.md @@ -0,0 +1,56 @@ +Update configuration on IPv6 prefix change +========================================== + +[◀ Go back to main README](../README.md) + +Description +----------- + +With changing IPv6 prefix from ISP this script handles to update... + +* ipv6 firewall address-list +* 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; + +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..3c774f1 --- /dev/null +++ b/doc/lease-script.md @@ -0,0 +1,36 @@ +Run other scripts on DHCP lease +=============================== + +[◀ Go back to main README](../README.md) + +Description +----------- + +This script is supposed to run from dhcp server as lease script. Currently +it does: + +* run [dhcp-to-dns](dhcp-to-dns.md) +* run [collect-wireless-mac](collect-wireless-mac.md) +* run [dhcp-lease-comment](dhcp-lease-comment.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) + +--- +[◀ 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..e0f7cf3 --- /dev/null +++ b/doc/leds-mode.md @@ -0,0 +1,50 @@ +Manage LEDs dark mode +===================== + +[◀ 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 botton with multiple presses](mode-button.md) + +--- +[◀ 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..5018d6e --- /dev/null +++ b/doc/mode-button.md @@ -0,0 +1,40 @@ +Mode botton with multiple presses +================================= + +[◀ Go back to main README](../README.md) + +Description +----------- + +These scripts 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`. + +Requirements and installation +----------------------------- + +Just install the scripts: + + $ScriptInstallUpdate mode-button-event,mode-button-scheduler; + +Then configure the mode-button to run `mode-button-event`: + + / system routerboard mode-button set enabled=yes on-event="/ system script run mode-button-event;"; + +Configuration +------------- + +The configuration goes to `global-config-overlay`, the only parameter is: + +* `ModeButton`: an array with defined actions + +Usage and invocation +-------------------- + +Press the mode button. :) + +--- +[◀ Go back to main README](../README.md) +[▲ Go back to top](#top) diff --git a/doc/netwatch-notify.md b/doc/netwatch-notify.md new file mode 100644 index 0000000..51768ff --- /dev/null +++ b/doc/netwatch-notify.md @@ -0,0 +1,36 @@ +Notify on host up and down +========================== + +[◀ Go back to main README](../README.md) + +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. Host down events are triggered +only if the host is down for several checks to avoid false alerts. + +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, hostname=example.com" host=[ :resolve "example.com" ] timeout=5s; + +Also notification settings are required for e-mail and telegram. + +--- +[◀ 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..9a28bb9 --- /dev/null +++ b/doc/netwatch-syslog.md @@ -0,0 +1,34 @@ +Manage remote logging +===================== + +[◀ Go back to main README](../README.md) + +Description +----------- + +RouterOS supports sending log messages via network to a remote syslog server. +If the server is not available no log messages (with potentially sensitive +information) should be sent. This script disables remote logging by +availability. + +Requirements and installation +----------------------------- + +Let's assume there is a remote log action and associated logging rule: + + / system logging action set remote=10.0.0.1 [ find where name="remote" ]; + / system logging add action=remote topics=info; + +Just install the script: + + $ScriptInstallUpdate netwatch-syslog; + +... and create a netwatch matching the IP address from logging action above: + + / tool netwatch add down-script=netwatch-syslog host=10.0.0.1 up-script=netwatch-syslog; + +All logging rules are disabled when host is down. + +--- +[◀ Go back to main README](../README.md) +[▲ Go back to top](#top) diff --git a/doc/packages-update.md b/doc/packages-update.md new file mode 100644 index 0000000..882ce80 --- /dev/null +++ b/doc/packages-update.md @@ -0,0 +1,46 @@ +Manage system update +==================== + +[◀ Go back to main README](../README.md) + +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: + +* send backup via e-mail if [email-backup](email-backup.md) is installed +* upload backup if [upload-backup](upload-backup.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. + +Usage and invocation +-------------------- + +Alternatively run it manually: + + / system script run packages-update; + +See also +-------- + +* [Notify on RouterOS update](check-routeros-update.md) +* [Send backup via e-mail](email-backup.md) +* [Upload backup to server](upload-backup.md) + +--- +[◀ Go back to main README](../README.md) +[▲ Go back to top](#top) diff --git a/doc/ppp-on-up.md b/doc/ppp-on-up.md new file mode 100644 index 0000000..432a640 --- /dev/null +++ b/doc/ppp-on-up.md @@ -0,0 +1,34 @@ +Run scripts on ppp connection +============================= + +[◀ Go back to main README](../README.md) + +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..eb04f5c --- /dev/null +++ b/doc/rotate-ntp.md @@ -0,0 +1,40 @@ +Rotate NTP servers +================== + +[◀ Go back to main README](../README.md) + +Description +----------- + +RouterOS requires NTP servers to be configured by IP address. Servers from a +pool may appear and disappear, leaving broken NTP configuration. + +This script allows to rotate IP addresses from a given pool. + +Requirements and installation +----------------------------- + +Just install the script: + + $ScriptInstallUpdate rotate-ntp; + +Configuration +------------- + +The configuration goes to `global-config-overlay`, this is the parameter: + +* `NtpPool`: dns name of ntp server pool + +Usage and invocation +-------------------- + +Just run the script to update the NTP configuration with actual IP +addresses from pool if required. + +Alternatively a scheduler can be created: + + / system scheduler add interval=5d name=rotate-ntp on-event="/ system script run rotate-ntp;" start-time=startup; + +--- +[◀ Go back to main README](../README.md) +[▲ Go back to top](#top) diff --git a/doc/sms-action.md b/doc/sms-action.md new file mode 100644 index 0000000..df9e14f --- /dev/null +++ b/doc/sms-action.md @@ -0,0 +1,49 @@ +Act on received SMS +=================== + +[◀ Go back to main README](../README.md) + +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 + +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.md b/doc/sms-forward.md new file mode 100644 index 0000000..28fc39b --- /dev/null +++ b/doc/sms-forward.md @@ -0,0 +1,36 @@ +Forward received SMS +==================== + +[◀ Go back to main README](../README.md) + +Description +----------- + +RouterOS can receive SMS. This script forwards SMS as notification. + +A broadband interface with SMS support is required. + +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 +------------- + +Notification settings are required for e-mail and telegram. + +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..d221072 --- /dev/null +++ b/doc/ssh-keys-import.md @@ -0,0 +1,33 @@ +Import SSH keys +=============== + +[◀ Go back to main README](../README.md) + +Description +----------- + +This script imports public SSH keys (files with extension "`pub`") into +local store for user authentication. + +Requirements and installation +----------------------------- + +Just install the script: + + $ScriptInstallUpdate ssh-keys-import; + +Usage and invocation +-------------------- + +Copy files with extension "`pub`" containing public SSH keys for your device. +Then run the script: + + / system script run ssh-keys-import; + +Starting with an `authorized_keys` file you can split it on a shell: + + while read type key name; do echo $type $key $name > $name.pub; done < authorized_keys + +--- +[◀ Go back to main README](../README.md) +[▲ Go back to top](#top) diff --git a/doc/super-mario-theme.md b/doc/super-mario-theme.md new file mode 100644 index 0000000..68484dc --- /dev/null +++ b/doc/super-mario-theme.md @@ -0,0 +1,31 @@ +Play Super Mario theme +====================== + +[◀ 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/template.md b/doc/template.md deleted file mode 100644 index bc86c32..0000000 --- a/doc/template.md +++ /dev/null @@ -1,46 +0,0 @@ -Script `template` -================= - -[◀ Go back to main README](../README.md) - -Description ------------ - -Short description... - -In detail ---------- - -Get all the details... - -Requirements and installation ------------------------------ - -We need... - -... then we install: - - [admin@MikroTik] > / system script add name=template - [admin@MikroTik] > / system script run script-updates - -Configuration -------------- - -The configuration goes to `global-config`, These are the parameters: - -* ... - -Usage and invocation --------------------- - -This is intended... - -See also --------- - -* [another script](template.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..68c74a1 --- /dev/null +++ b/doc/unattended-lte-firmware-upgrade.md @@ -0,0 +1,42 @@ +Install LTE firmware upgrade +============================ + +[◀ 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 + +A temporary scheduler is created to be independent from terminal. Thus +starting the upgrade process over the broadband connection is supported. + +Requirements and installation +----------------------------- + +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..870759e --- /dev/null +++ b/doc/update-gre-address.md @@ -0,0 +1,38 @@ +Update GRE configuration with dynamic addresses +=============================================== + +[◀ Go back to main README](../README.md) + +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..3641588 --- /dev/null +++ b/doc/update-tunnelbroker.md @@ -0,0 +1,41 @@ +Update tunnelbroker configuration +================================= + +[◀ Go back to main README](../README.md) + +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, pass=s3cr3t, id=12345" tunnelbroker; + +Also enabling dynamic DNS in Mikrotik cloud is required: + + / ip cloud set ddns-enabled=yes; + +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..bbfbcc4 --- /dev/null +++ b/doc/upload-backup.md @@ -0,0 +1,62 @@ +Upload backup to server +======================= + +[◀ Go back to main README](../README.md) + +Description +----------- + +This script uploads binary backup (`/ system backup save`) and complete +configuration export (`/ export terse`) to external server. + +Requirements and installation +----------------------------- + +Just install the script: + + $ScriptInstallUpdate upload-backup; + +Configuration +------------- + +The configuration goes to `global-config-overlay`, these are the parameters: + +* `BackupSendBinary`: whether to send binary backup +* `BackupSendExport`: whether to send configuration export +* `BackupPassword`: password to encrypt the backup with +* `BackupUploadUrl`: url to upload to +* `BackupUploadUser`: username for server authentication +* `BackupUploadPass`: password for server authentication + +Also notification settings are required for e-mail and telegram. + +### Issues with SFTP client + +The RouterOS SFTP client is picky if it comes to authentication methods. +I had to disable all but password authentication on server side. For openssh +edit `/etc/ssh/sshd_config` and add a directive like this, changed for your +needs: + + Match User mikrotik + AuthenticationMethods password + +Usage and invocation +-------------------- + +Just run the script: + + / system script run upload-backup; + +Creating a scheduler may be an option: + + / system scheduler add interval=1w name=upload-backup on-event="/ system script run upload-backup;" start-time=09:25:00; + +See also +-------- + +* [Send backup via e-mail](email-backup.md) +* [Upload backup to Mikrotik cloud](cloud-backup.md) + +--- +[◀ Go back to main README](../README.md) +[▲ Go back to top](#top) |