ros-client

RouterOS API Client 🌐

A powerful Node.js module for seamless interaction with MikroTik RouterOS API, supporting both plain text (port 8728) and encrypted (port 8729) connections. 🚀

🆕 What's New in v1.1.0

• 📚 Comprehensive Command Reference - Complete RouterOS API command reference in Refrence.js
• 🧪 Production Example - Enhanced app.js with advanced error handling and connectivity testing
• 🔧 Improved Buffer Management - Enhanced buffer handling for better performance
• 📖 Enhanced Documentation - Better examples and troubleshooting guides
• 💬 Community Support - Telegram support group for community assistance

✨ Key Features

• 🔒 Secure connections via plain text and TLS encryption
• 🔄 Full support for RouterOS API protocol encoding/decoding
• ⚡ Modern Promise-based API implementation
• 🛠️ Comprehensive MikroTik API command helpers
• 🐛 Robust error handling mechanism
• 🔍 Built-in debug mode for troubleshooting
• 📦 Lightweight with minimal dependencies

📦 Installation

npm install ros-client

🚀 Quick Start

const RouterOSClient = require("ros-client");

// Create API client instance
const api = new RouterOSClient({
  host: "192.168.88.1",
  username: "admin",
  password: "your-password",
  port: 8728, // Use 8729 for TLS
  tls: false, // Set to true for encrypted connection
});

async function example() {
  try {
    await api.connect();
    console.log("✅ Connected successfully!");

    // Get system identity
    const identity = await api.send(["/system/identity/print"]);
    console.log("🖥️ Router identity:", identity);

    // Get all interfaces
    const interfaces = await api.send(["/interface/print"]);
    console.log("🌐 Interfaces:", interfaces);

    await api.close();
  } catch (err) {
    console.error("❌ Error:", err.message);
  }
}

example();

📚 Documentation & Examples

📖 Command Reference

For a comprehensive list of all available RouterOS API commands with detailed documentation, see the Refrence.js file. This file contains:

• 🔧 System Commands - Identity, resources, clock, logging, etc.
• 🌐 Interface Management - Ethernet, wireless, bridge, VLAN, etc.
• 🌍 IP Configuration - Addresses, routes, DNS, DHCP, firewall, etc.
• 📶 Wireless Operations - Registration, scanning, security, etc.
• 🔒 Security Features - Firewall rules, NAT, user management, etc.
• 📊 Monitoring Tools - Traffic, queues, logs, statistics, etc.

🧪 Complete Example

For a production-ready example with advanced error handling and connectivity testing, see the app.js file which demonstrates:

• ✅ Connection Testing - TCP connectivity validation
• 🔥 Advanced Error Handling - Detailed error categorization and troubleshooting
• 📊 Event Monitoring - Comprehensive event listeners
• 🚨 Timeout Management - Connection and operation timeouts
• 🔍 Debug Logging - Detailed connection and operation logging

⚙️ Configuration Options

const api = new RouterOSClient({
  host: "192.168.88.1", // Router IP address
  username: "admin", // Username
  password: "password", // Password
  port: 8728, // API port (8729 for TLS)
  tls: false, // TLS encryption
  timeout: 10000, // Connection timeout (ms)
  debug: false, // Debug output
});

📚 API Documentation

🔌 Connection Methods

connect()

Establishes and authenticates the RouterOS connection.

await api.connect();

close()

Gracefully terminates the RouterOS connection.

await api.close();

🛠️ Command Methods

send(words)

Executes commands on the RouterOS device.

const result = await api.send(["/system/resource/print"]);

📝 Command Examples

🖥️ System Management

// System identity operations
const identity = await api.send(["/system/identity/print"]);
await api.send(["/system/identity/set", "=name=my-router"]);

// Resource monitoring
const resources = await api.send(["/system/resource/print"]);

// System maintenance
await api.send(["/system/reboot"]);

🌐 Network Interface Management

// Interface operations
const interfaces = await api.send(["/interface/print"]);
await api.send(["/interface/enable", "=.id=ether1"]);

// Wireless interface management
const wireless = await api.send(["/interface/wireless/print"]);

🔧 IP Configuration

// IP address management
const addresses = await api.send(["/ip/address/print"]);
await api.send([
  "/ip/address/add",
  "=address=192.168.1.1/24",
  "=interface=ether1",
]);

// DHCP server management
const leases = await api.send(["/ip/dhcp-server/lease/print"]);

🎯 Events

The client emits these events:

• connected ✅ - Connection established
• error ❌ - Error occurred
• close 🔒 - Connection terminated

api.on("connected", () => console.log("✅ Connected"));
api.on("error", (err) => console.error("❌ Error:", err.message));
api.on("close", () => console.log("🔒 Connection closed"));

🔍 Debug Mode

Enable detailed logging:

const api = new RouterOSClient({
  debug: true,
  // other options...
});

❌ Error Handling

try {
  await api.connect();
  const result = await api.send(["/command"]);
} catch (err) {
  console.error("❌ Error:", err.message);
}

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

We welcome contributions! Here's how:

1. 🔀 Fork the repository
2. 🌿 Create your feature branch (git checkout -b feature/amazing-feature)
3. ✍️ Commit changes (git commit -m 'Add amazing feature')
4. 📤 Push to branch (git push origin feature/amazing-feature)
5. 📫 Open a Pull Request

👥 Contributors

We thank the following contributors for their valuable contributions to this project:

• mbingsdk - Update limit buffer functionality 🔧
• AviStudio - Command Reference (Refrence.js) documentation 📚

💬 Support

Need help or have questions? Join our community:

📲 Telegram Support Group: https://t.me/ros_client

📋 Changelog

For detailed information about changes in each version, see the CHANGELOG.md file.

---

⭐ Star this repository if you find it helpful!