MUT is a command-line toolset for managing MikroTik routers, designed to automate the creation of a CSV inventory, perform configuration backups, and execute RouterOS upgrades or downgrades. It leverages SSH and Expect to interact with MikroTik devices, making it ideal for network administrators managing MikroTik infrastructure. It supports air-gapped networks, robust hostname handling, and addon package upgrades, making it ideal for systems engineers managing multiple devices. The tool operates in two modes: build mode to generate a CSV inventory from neighbor data, and upgrade mode to upgrade devices directly or based on filtered CSV data.
This software is provided by the copyright holders and contributors "as is" and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall Sean Crites be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.
- Inventory Creation: Generates a CSV file with details like identity, IP address, MAC address, interface, platform, board_name, version, and upgrade status using MikroTik neighbor data.
- Configuration Backups: Automatically backs up router configurations before upgrades, saving them as
.rscfiles. - RouterOS Upgrades/Downgrades: Supports upgrading or downgrading to specific RouterOS versions (e.g.,
7.18or7.18.2), with version selection logic to pick the highest patch or exact match, including addon packages (e.g.,wireless,dhcp). - RouterOS Version Validation: Ensures valid version formats (N.NN or N.NN.N) for
-roption. - Centralized CSV Path Resolution: Consistently handles CSV file paths (current directory or
$HOME) for build and upgrade modes. - Credentials File Validation: Ensures
mut_up.expcredentials file uses correct key=value format. - Configurable SSH Timeout: Supports customizable SSH timeouts via
mut_opt.conffor both scripts. - Enhanced SCP Error Handling: Provides specific error messages for SCP failures (e.g., permission denied, no route to host).
- Air-Gapped Support: Enables automated updates in air-gapped networks by downloading the project and RouterOS
.npkfiles/packages offline. - Hostname Support: Handles FQDNs (e.g.,
router.prv.example.com), short hostnames (e.g.,router.prv), and local FQDNs (e.g.,router.local.lan) with a fallback mechanism that tries short hostname prompts first, then full FQDN. - CSV Filtering: Allows upgrades of specific devices by filtering CSV data with
awkregex onidentityorboard_namefields. - Failure Tracking: Tracks and summarizes failed upgrades when processing multiple devices, ensuring all devices are attempted.
- Test Mode: Simulates upgrades without applying changes, ideal for testing workflows.
- Debug Mode: Provides verbose output and detailed logging for troubleshooting.
- Logging: Saves detailed logs to a specified directory, including a summary of failed upgrades for multiple devices.
- POSIX Compliance:
mut_inv.shis largely POSIX-compliant, with documented external dependencies. - Configuration File: Supports a
mut_opt.conffile for customizing paths and settings. - Firmware Verification: Verifies firmware versions post-upgrade, handling pending firmware upgrades with automatic reboots.
- Reachability Check: Confirms device reachability via
pingbefore upgrades, enhancing reliability.
- Shell: POSIX-compliant shell (e.g.,
sh,bash,dash) - Utilities:
ssh(OpenSSH, version 7.0 or later)scp(for file transfers)sshpass(version 1.06 or later)expect(version 5.45 or later)awk,ping,sed,read,stty,catgetent,host(for hostname resolution inmut_inv.sh)
- MikroTik Access:
- SSH access to devices (port 22, admin privileges)
- RouterOS
.npkfiles (including addon packages) inos/vN.NN/(e.g.,os/v7.18/routeros-7.18.2-mipsbe.npk,os/v7.18/wireless-7.18.2-mipsbe.npk)
- Permissions:
- Write access to
backups/,logs/, and$HOMEfor CSV output
- Write access to
- Files:
mut_inv.shmut_up.exp- Optional:
mut_opt.conffor configuration overrides
For air-gapped networks, download the project and .npk files offline and transfer them to the target system.
-
Clone the Repository:
git clone https://github.com/seancrites/mut.git cd mut -
Set Up Directories: Create directories for RouterOS images, backups, and logs:
mkdir -p os backups logs
-
Download RouterOS Images: Place
.npkfiles in versioned subdirectories (e.g.,os/v7.18/routeros-7.18.2-mipsbe.npk). Obtain these from MikroTik’s download page. -
Install Dependencies: Ensure all required utilities are installed using the package manager for your distribution. Below are examples for Alpine Linux, Debian, and Rocky Linux.
-
Alpine Linux (using
apk):apk update apk add openssh-client sshpass expect gawk iputils-ping sed coreutils net-tools
Note:
sshpassis in thecommunityrepository; ensure it’s enabled in/etc/apk/repositories(e.g.,https://dl-cdn.alpinelinux.org/alpine/v3.22/community). Thecoreutilspackage providesread,stty, andcat;net-toolsprovidesgetentandhost. -
Debian (using
apt):sudo apt update sudo apt install openssh-client sshpass expect gawk iputils-ping sed coreutils net-tools
Note: All utilities are available in Debian’s default repositories. The
coreutilspackage includesread,stty, andcat;net-toolsprovidesgetentandhost. -
Rocky Linux (using
dnf):sudo dnf update sudo dnf install openssh-clients sshpass expect gawk iputils sed coreutils net-tools
Note:
sshpassmay require the EPEL repository. Enable it withsudo dnf install epel-release. Thecoreutilspackage includesread,stty, andcat;net-toolsprovidesgetentandhost.
-
-
Set Permissions: Make scripts executable:
chmod +x mut_inv.sh mut_up.exp
-
Configure
mut_opt.conf(optional): Create or editmut_opt.confto customize paths and settings (see Configuration File):ROS_IMAGE_DIR=$PWD/os BACKUP_DIR=$PWD/backups LOGS_DIR=$PWD/logs SSH_TIMEOUT=30
The optional mut_opt.conf file customizes script behavior. It uses a key=value format, with supported keys:
ROS_IMAGE_DIR: Directory for RouterOS.npkfiles (default:./os).BACKUP_DIR: Directory for configuration backups (default:./backups).LOGS_DIR: Directory for logs (default:./logs).SSH_TIMEOUT: SSH connection timeout in seconds (default: 30).
Example mut_opt.conf:
ROS_IMAGE_DIR=/opt/mikrotik/os
BACKUP_DIR=/var/backups/mikrotik
LOGS_DIR=/var/log/mikrotik
SSH_TIMEOUT=60
Lines starting with # are ignored, and ~ or $PWD are expanded to $HOME or the current directory.
Generate a CSV inventory from a MikroTik router’s IP neighbor data.
-
Console Output (no CSV file):
./mut_inv.sh -b <host>
Example:
./mut_inv.sh -b router.prv.example.com
-
Save to CSV (tries current directory, then
$HOMEif not writable, or specify with-c):./mut_inv.sh -b [-c inventory.csv] <host>
Example:
./mut_inv.sh -b -c /path/to/routers.csv router.prv.example.com
Upgrade or downgrade MikroTik routers, either directly or based on a filter
A38A
ed CSV. When using -c, all filtered devices are processed, even if some fail, with a summary of failures logged. The -r version must be in N.NN or N.NN.N format.
-
Direct Upgrade (single host):
./mut_inv.sh -u [-r version] <host>
Example (upgrade to latest
7.18patch):./mut_inv.sh -u -r 7.18 router.prv.example.com
Example (upgrade to exact
7.18.2):./mut_inv.sh -u -r 7.18.2 router.prv.example.com
-
Filtered Upgrade (from CSV):
./mut_inv.sh -u -c <csv_file> -f <filter> [-r version]
Example (upgrade devices with board_name containing “rb” to
7.18.2):./mut_inv.sh -u -c routers.csv -f rb -r 7.18.2
Example (upgrade both CRS312 and mAP devices to
7.16.2):./mut_inv.sh -u -c routers.csv -f "crs312|rbmap2nd" -r 7.16.2
-d: Enable debug output for troubleshooting.-e: Enable enhanced logging of MikroTik commands (ignored if-dis used).-t: Simulate upgrades (test mode).-l: Enable logging tologs/directory.-o <options_file>: Use a custom configuration file (default:mut_opt.conf).
Example with all options:
./mut_inv.sh -u -c routers.csv -f rb -r 7.18.2 -d -e -t -l -o custom.confThe inventory CSV has the following columns:
identity: Router identity (name)ip_addr: IP address (IPv4 or IPv6, non-link-local)mac_addr: MAC addressinterface: Interface usedplatform: Platform (always “MikroTik”)board_name: Board name (e.g., “RB4011”)version: RouterOS versionmut_status: Upgrade status (e.g.,SUCCESS: Updated to v<version> <timestamp>,FAILED: Invalid credentials <timestamp>)
Example:
identity,ip_addr,mac_addr,interface,platform,board_name,version,mut_status
"Router1","192.168.1.2","00:0C:29:12:34:56","ether1","MikroTik","RB4011","7.16.2","SUCCESS: Updated to v7.16.2 20250604_123456 -0800"
"Router2","192.168.1.3","00:0C:29:78:90:AB","ether2","MikroTik","CRS312","7.18.2","FAILED: Invalid credentials 20250604_123500 -0800"
- When: Backups are performed before upgrades in
mut_up.exp. - Format: Configuration exports (
/export show-sensitive) saved as.rscfiles inbackups/. - Naming:
config.<host>-<timestamp>.rsc(e.g.,config.router1-20250604_123456.rsc). - Verification: Backups are verified for readability and non-empty content.
- Enabled: With
-loption. - Location:
logs/mut_inventory_<timestamp>.log(formut_inv.sh) andlogs/mut_upgrade_<timestamp>.log(formut_up.exp). - Failure Summary: In
-cmode, a summary of failed upgrades is logged (e.g.,Summary: Failed upgrades for hosts: router1 router2). - Debug Logs: With
-d, additional debug logs (logs/mut_upgrade_debug_<timestamp>.log) include Expect diagnostics and CLI interactions.
- Credentials: Stored temporarily in a secure file (
/tmp/mikrotik_cred_<pid>.txt, mode 600, where<pid>is the process ID), deleted after use. - SSH: Uses
sshpassfor automation; ensurecred_fileis protected. - Sensitive Data: Passwords are suppressed in debug logs for security.
- Requires routable IPv4 or IPv6 addresses (excludes link-local
fe80::addresses). - Non-POSIX utilities (
awk,ssh,sshpass,expect,getent,host) are used, noted in headers. - Upgrade process assumes
.npkfiles are organized inos/vN.NN/directories. - Multiple device upgrades (
-c) continue despite failures, exiting with 0 unless a critical error occurs (e.g., invalid CSV). - Hostname for SSH must match the prompt set in
/system/identity/set name=NAME, typically the short hostname for internet-routable FQDNs (e.g.,router.prvforrouter.prv.example.com). - Invalid RouterOS versions (e.g.,
7,abc) or malformed credentials files cause explicit errors. - SSH timeouts are configurable but require sufficient network stability.
See CHANGELOG.md for a detailed history of changes.
Contributions are welcome! Please:
- Fork the repository.
- Create a feature branch (
git checkout -b feature/your-feature). - Commit changes (
git commit -m "Add your feature"). - Push to the branch (
git push origin feature/your-feature). - Open a pull request.
Mikrotik, network-management, inventory-management, network-automation, routeros, shell-scripting, firmware-upgrade, mikrotik-backup-script, systems-administration, mikrotik-router, mikrotik-routeros, mikrotik-update, routeros-scripts, posix-shell, mikrotik-switch, expect-scripting.
This project is licensed under the BSD 3-Clause License. See the LICENSE file for details.
For issues or questions, open a GitHub issue or contact Sean Crites at sean.crites@gmail.com.