Unifi SSH Commands and Examples

By /

Unifi SSH Commands and Examples: A Comprehensive Guide

Ubiquiti’s UniFi networking platform provides robust management capabilities through its intuitive web interface. However, for advanced configurations, troubleshooting, and automation, SSH access unlocks a treasure trove of power and flexibility. This comprehensive guide explores the world of UniFi SSH commands, offering detailed explanations and practical examples to empower you to manage your network with precision.

Accessing Your UniFi Device via SSH:

Before diving into commands, ensure SSH is enabled on your UniFi device (either a Cloud Key, Dream Machine, or self-hosted controller). You’ll need the device’s IP address and the credentials of an account with administrator privileges. Use an SSH client like PuTTY, Terminal (macOS/Linux), or Windows PowerShell to establish the connection.

Understanding the Shell Environment:

Upon successful login, you’ll encounter a Linux-based shell environment. Most UniFi devices run a Debian-based distribution. This means familiar Linux commands like ls, cd, cat, grep, and others are at your disposal.

Key UniFi-Specific Commands and Utilities:

This guide focuses on commands relevant to UniFi network management, categorized for clarity:

1. System Information and Management:

  • info: Displays essential system information, including device model, firmware version, uptime, and resource utilization. This is often the first command to run for a quick overview.

    bash
    info

  • uptime: Shows how long the device has been running since the last reboot.

    bash
    uptime

  • df -h: Reports disk space usage in a human-readable format. Crucial for monitoring storage on your controller.

    bash
    df -h

  • top (or htop if installed): Displays real-time system processes, CPU usage, memory consumption, and more. Helpful for identifying resource-intensive tasks.

    bash
    top

  • reboot: Restarts the UniFi device.

    bash
    reboot

  • shutdown -h now: Shuts down the UniFi device immediately.

    bash
    shutdown -h now

  • mca-cli: The UniFi controller’s command-line interface. Provides access to a wealth of network management functionalities. (More details in the dedicated section below).

2. Network Configuration and Management:

  • ifconfig (or ip a): Displays network interface information, including IP addresses, MAC addresses, and network status. Essential for troubleshooting network connectivity issues.

    bash
    ifconfig

  • ping <IP_address/hostname>: Tests network connectivity to a specific IP address or hostname.

    bash
    ping 8.8.8.8

  • traceroute <IP_address/hostname>: Traces the network route to a specific IP address or hostname, revealing potential network bottlenecks.

    bash
    traceroute google.com

  • netstat -tulnp: Lists active network connections and listening ports, including the associated processes. Useful for security audits and troubleshooting connection problems.

    bash
    netstat -tulnp

  • iwconfig: Displays and configures wireless network interfaces (if applicable).

    bash
    iwconfig

3. Log Management:

  • tail -f /var/log/messages: Displays the system log in real-time, showing ongoing system events and errors. Invaluable for debugging.

    bash
    tail -f /var/log/messages

  • grep <search_term> /var/log/messages: Searches the system log for specific keywords or patterns.

    bash
    grep "authentication failure" /var/log/messages

  • less /var/log/messages: Views the system log file with navigation capabilities (e.g., scrolling, searching).

    bash
    less /var/log/messages

4. Backup and Restore:

  • Creating Backups (using mca-cli):

    bash
    mca-cli backups create

  • Restoring Backups (using mca-cli):

    bash
    mca-cli backups restore <backup_file_name>

5. The mca-cli Command-Line Interface (Deep Dive):

The mca-cli utility is the heart of UniFi command-line management. It provides a structured way to interact with the controller and manipulate network settings. Here are some key mca-cli commands and examples:

  • mca-cli help: Lists all available mca-cli commands. Your starting point for exploring its capabilities.

    bash
    mca-cli help

  • mca-cli help <command>: Displays help information for a specific mca-cli command.

    bash
    mca-cli help sites

  • Site Management:

    • mca-cli sites list: Lists all configured sites on the controller.

      bash
      mca-cli sites list

    • mca-cli sites create <site_name>: Creates a new site.

      bash
      mca-cli sites create "New Site"

    • mca-cli sites delete <site_id>: Deletes a site. (Use with caution!)

      bash
      mca-cli sites delete <site_id>

  • Device Management:

    • mca-cli devices list: Lists all devices adopted by the controller.

      bash
      mca-cli devices list

    • mca-cli devices forget <device_mac>: Forgets a specific device from the controller.

      bash
      mca-cli devices forget <device_mac>

    • mca-cli devices restart <device_mac>: Restarts a specific device.

      bash
      mca-cli devices restart <device_mac>

  • Network Configuration:

    • mca-cli networks list: Lists all configured networks.

      bash
      mca-cli networks list

    • mca-cli networks create <network_name> <purpose>: Creates a new network (e.g., VLAN). The purpose can be corporate, guest, or vlan-only.

      bash
      mca-cli networks create "Guest Network" guest

  • User Management:

    • mca-cli users list: Lists all users.

      bash
      mca-cli users list

    • mca-cli users create <username> <password> <role>: Creates a new user. Roles can vary depending on your controller version (e.g., “admin”, “operator”). Consult the UniFi documentation for available roles.

      bash
      mca-cli users create newuser password123 operator

Important Considerations:

  • Caution: Exercise caution when using SSH commands, especially those that modify system settings or delete data. Incorrect commands can lead to network instability or data loss. Always back up your configuration before making significant changes.

  • Updates: UniFi regularly updates its software and firmware. Commands and their behavior might change between versions. Consult the official UniFi documentation for the most up-to-date information.

  • Scripting: The power of SSH extends beyond individual commands. You can create scripts to automate tasks, perform bulk operations, and monitor your network proactively.

  • Security: Secure your SSH access by using strong passwords and limiting access to authorized personnel only. Consider disabling SSH when not needed.

This guide provides a solid foundation for leveraging the power of SSH within your UniFi network. By understanding these commands and utilizing the resources mentioned, you can take your network management to the next level. Remember to explore the official UniFi documentation and community forums for further insights and assistance. With practice and exploration, you can unlock the full potential of your UniFi deployment.

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top