mikrotik-swos 1.2.2

Python library and tools for managing MikroTik SwOS and SwOS Lite switches

SwOS API and Tools

Python library and tools for managing MikroTik SwOS (SwitchOS) and SwOS Lite (SwitchOS Lite) switches.

Components

• swos package: Python library for reading/writing switch configuration
• swos-config: CLI tool for displaying configuration
• swos-export: CLI tool for exporting configurations to Ansible YAML format
• Ansible module: Full-featured Ansible integration for declarative, idempotent switch configuration management
  • Supports check mode (dry-run)
  • Auto-detects platform (SwOS vs SwOS Lite)
  • Manages ports, PoE, VLANs, LAG/LACP, SNMP
  • See ANSIBLE.md for complete documentation

Capabilities

Read: System info, ports, PoE, LAG/LACP, per-port VLANs, VLAN table, host table, SFP info, SNMP Write: System settings, port config, PoE settings, LAG/LACP, per-port VLANs, VLAN table, SNMP Backup/Restore: Download binary backups, restore from backup files SwOS-only: VLAN names, isolation, learning, mirror settings (not available on SwOS Lite) Note: All configuration changes are immediately applied and persisted by the switch.

Requirements

• Python 3.6+
• requests>=2.25.0

Installation

pip install mikrotik-swos

Or for development:

pip install -r requirements.txt

Confirmed Compatibility

• SwOS 2.17

• SwOS 2.18

• SwOS Lite 2.17

• SwOS Lite 2.18

• SwOS Lite 2.19

• SwOS Lite 2.20

Tested Hardware

• CRS305-1G-4S+

• CRS309-1G-8S+

• CRS310-8G+2S+

• CRS326-24S+2Q

• CSS610-8G-2S+

• CSS610-8P-2S+

Note: Gracefully handles switches without PoE, LAG/LACP, or SFP capabilities.

Quick Start

CLI Tools

swos-config - Display switch configuration:

# Display configuration
swos-config 192.168.88.1 admin ""

# Save to file
swos-config 192.168.88.1 admin "" > backup.txt

swos-export - Export to Ansible YAML format:

# Export all switches from inventory
swos-export -i inventory.yml -o configs/

# Export single switch
swos-export --host 192.168.1.1 --username admin --password "" -o switch.yml

Python API

from swos import get_system_info, set_port_config, get_backup

url = "http://192.168.88.1"
system = get_system_info(url, "admin", "")
print(f"{system['identity']} - {system['model']}")

# Configure a port
set_port_config(url, "admin", "", port_number=1, name="Uplink")

# Create a backup
backup_data = get_backup(url, "admin", "")
with open("switch_backup.swb", "wb") as f:
    f.write(backup_data)

See module docstrings for complete API documentation.

Ansible - Infrastructure as Code

Perfect for managing multiple switches declaratively!

Quick Setup:

# Install package
pip install mikrotik-swos

# Copy module to your playbook
mkdir -p library
cp ansible/swos.py library/

Example Playbook:

- name: Configure Switch
  hosts: switches
  tasks:
    - name: Apply configuration
      swos:
        host: "{{ ansible_host }}"
        username: admin
        password: ""
        config:
          system:
            identity: "Office-Switch-01"
          ports:
            - port: 1
              name: "Uplink"
              enabled: true
            - port: 2
              name: "Server"
              enabled: true
          vlans:
            - vlan_id: 10
              members: [2, 3, 4]

Features:

• Idempotent - only applies changes when needed
• Check mode - preview changes with --check
• Auto-detection - works with both SwOS and SwOS Lite
• Complete validation - catches configuration errors before applying

Full Ansible Documentation - Complete guide with advanced examples

API Functions

Read: get_system_info(), get_links(), get_poe(), get_lag(), get_port_vlans(), get_vlans(), get_hosts(), get_sfp_info(), get_snmp()

Write: set_system(), set_port_config(), set_poe_config(), set_lag_config(), set_port_vlan(), set_vlans(), set_snmp()

Backup/Restore: get_backup(), restore_backup()

All functions take (url, username, password, ...) parameters. Read functions return lists of dictionaries with configuration data. Write functions take port_number and optional setting parameters (except set_system(), set_snmp(), and set_vlans() which set global config). Backup functions work with binary .swb files (encrypted/proprietary MikroTik format).

See docstrings in the swos module for detailed parameters and return values.

Security

• SwOS Lite uses HTTP with Digest Authentication (no HTTPS)
• Use on trusted networks only
• Use Ansible Vault for password storage

Development

Publishing a New Release

1. Create and push a git tag:

   git tag v0.2.0
   git push origin v0.2.0
   

2. GitHub Actions automatically builds and publishes to PyPI

Credits

Certain components of this codebase were created with the assistance of AI.