Skip to content

Latest commit

 

History

History
executable file
·
410 lines (317 loc) · 17.3 KB

README.md

File metadata and controls

executable file
·
410 lines (317 loc) · 17.3 KB

UniFi API browser

This tool allows you to browse data exposed through the UniFi Controller API, developed using PHP, JavaScript, and the Bootstrap CSS framework. It comes bundled with two API clients:

  • The classic PHP API client (UniFi-API-client) for username/password authentication against the classic UniFi Controller API
  • The official UniFi Network Application API client (unifi-network-application-api-client) for API key authentication against the official UniFi Network Application API

Please keep the following in mind when using the UniFi API browser:

  • The tool does not support all available data collections and API endpoints. See the list below for those currently supported.
  • Classic controllers: versions 5.X.X, 6.X.X, 7.X.X, 8.X.X, and 9.X.X of the UniFi Controller/Networking Application software are supported (version 9.4.19 has been confirmed to work)
  • Official API controllers: requires a UniFi Network Application that supports API key authentication
  • Network Application on UniFi OS-based consoles and servers is also supported
  • When accessing UniFi OS-based controllers through this tool, please read the remarks regarding UniFi OS support
  • Please read the Security Notice before installing this tool.

Upgrading from 2.x to 3.x

Version 3.0.0 introduces the following major changes:

  • PHP 8.1 or higher is now required (previously PHP 7.4)
  • Official UniFi Network Application API support: you can now configure controllers that use API key authentication alongside the classic username/password controllers
  • Twig 3.x replaces Twig 2.x (end of life)
  • Kint 5.x replaces Kint 3.x for PHP 8.1+ compatibility
  • Auto-select single site: when a controller has only one site, it is automatically selected
  • Custom menu entries added in config.php only apply to classic controllers and are hidden when an official API controller is selected

When upgrading, update your config/config.php based on the new config/config-template.php file. Your existing classic controller entries will continue to work without changes. To add official API controllers, see the Configuration section below.

Features

The UniFi API browser tool offers the following features:

  • Browse data collections and API endpoints exposed by the UniFi Controller API in an easy manner
  • Support for both classic (username/password) and official (API key) controller authentication
  • Switch between multiple controllers of different types from the dropdown menu
  • Switch between sites managed by the connected controller (auto-selects when only one site is available)
  • Switch between output formats (currently JSON, JSON highlighted, PHP array, interactive, and PHP array, highlighted)
  • Copy the results to clipboard (this is only supported with the JSON output format and will fail gracefully with large collections)
  • Switch between the default Bootstrap theme and the Bootswatch themes
  • An About modal that shows version information for PHP, cURL, and the UniFi Controller
  • Very easy setup with minimal dependencies
  • Timing details of API calls can be useful to "benchmark" your UniFi Controller
  • A useful tool when developing applications that make use of the UniFi Controller API
  • The API exposes more data than is visible through the UniFi controller's web interface, making it useful for troubleshooting purposes
  • Debug mode to troubleshoot cURL connections (set $debug to true in the config file to enable debug mode)

Data collections/API endpoints currently implemented in the API browser

Official API controllers

  • Application
    • Application info
  • Sites
    • List sites
  • Devices
    • List adopted devices
    • List pending devices
    • Device statistics
  • Clients
    • List clients
  • Networks
    • List networks
  • WiFi
    • List WiFi broadcasts
  • Hotspot
    • List vouchers
  • Firewall
    • List firewall zones
    • List firewall policies
    • List ACL rules
    • List traffic matching lists
    • List DNS policies
  • Switching
    • List switch stacks
    • List MC-LAG domains
    • List LAGs
  • Supporting Resources
    • WAN interfaces
    • Site-to-site VPN tunnels
    • VPN servers
    • RADIUS profiles
    • Device tags
    • DPI categories
    • DPI applications
    • Countries

Classic controllers

  • Configuration
    • list sites on this controller
    • list site settings
    • list admins for the current site
    • system information (sysinfo)
    • self
    • list wlan config
    • list VoIP extension
    • list network configuration
    • list port configurations
    • list port forwarding rules
    • list firewall groups
    • list current channels
    • list DPI stats
    • dynamic DNS configuration
    • list country codes
    • list Radius accounts (supported on controller version 5.5.19 and higher)
  • Clients/users
    • list online clients
    • list guests
    • list users
    • list user groups
    • stat all users
    • stat authorisations
    • stat sessions
  • Devices
    • list devices (access points, USG routers and USW switches)
    • list wlan groups
    • list AP groups (supported on controller version 6.0.X and higher)
    • list rogue access points
    • list devices tags (supported on controller version 5.5.19 and higher)
  • Stats
    • all sites stats
    • 5-minute site stats
    • hourly site stats
    • daily site stats
    • monthly site stats
    • 5-minute access point stats
    • hourly access point stats
    • daily access point stats
    • monthly access point stats
    • 5-minute gateway stats
    • hourly gateway stats
    • daily gateway stats
    • monthly gateway stats
    • 5-minute dashboard metrics
    • hourly dashboard metrics
    • site health metrics
    • port forward stats
    • DPI stats
  • Hotspot
    • stat vouchers
    • stat payments
    • list hotspot operators
  • Messages
    • list events
    • list alarms
    • count alarms
    • list IDS/IPS events
    • list system log entries

Please note that the bundled API client supports many more API endpoints, not all make sense to add to the API browser though.

Requirements

  • A web server with PHP (8.1.0 or higher) and the php-curl module installed
  • Network connectivity between this web server and the server (and port) where the UniFi controller is running (in case you are seeing errors, please check out this issue)
  • Web browsers accessing this tool should have full internet access because several CSS and JS files are loaded from public CDNs.
  • Using an administrator account with read-only permissions can limit visibility on certain collection/object properties. See this issue and this issue for an example where the WPA2 password isn't accessible for read-only administrator accounts.

Installation

Installation of this tool is quite straightforward. The easiest way to do this is by using git clone which also allows for easy updates:

  • open up a terminal window on your server and cd to the root folder of your web server (on Ubuntu this is /var/www/html) and execute the following command from your command prompt:
git clone https://github.com/Art-of-WiFi/UniFi-API-browser.git
  • when git is done cloning, follow the configuration steps below to configure the settings for access to your UniFi Controller's API

Alternatively, you may choose to download the zip file and unzip it in your directory of choice, then follow the configuration steps below.

Installation using Docker

@scyto maintains Docker containers for quick and easy deployment of the UniFi API browser tool. Please refer to this Wiki page within the repository for more details. Please note we don't provide support related to Docker-based installs.

Configuration

  • Copy config/config-template.php to config/config.php and edit it with your controller details
  • You can configure multiple controllers of different types in the $controllers array
  • Two controller types are supported:
    • classic (default): uses username/password authentication with the classic UniFi API client
    • official: uses API key authentication with the official UniFi Network Application API client

Classic controller example

[
    'user'     => 'admin',
    'password' => 'your-password',
    'url'      => 'https://192.168.1.1:8443',
    'name'     => 'Home Controller',
    'type'     => 'classic',
],

Official API controller example

To use the official API, you need to generate an API key in the UniFi Network Application (Settings > ) API section. Then add a controller entry in the config.php like this:

[
    'api_key'    => 'your-api-key-here',
    'url'        => 'https://192.168.1.1',
    'name'       => 'Office (Official API)',
    'type'       => 'official',
    'verify_ssl' => false, // optional, set to false to disable SSL verification (default: true)
],

Note: official API controllers do not require a username or password, only an API key. The type field must be set to 'official' for API key authentication to work.

Additional configuration

  • If the type field is omitted from a controller entry, it defaults to classic for backward compatibility
  • You can restrict access to the tool by creating user accounts and passwords. Please refer to the instructions in the config/users-template.php file for further details
  • After following these steps, you can open the tool in your browser (assuming you installed it in the root folder of your web server as suggested above) by going to this url: http(s)://<server IP address>/UniFi-API-browser/

UniFi OS support

Support for UniFi OS-based controllers (for example, the UniFi Dream Machine Pro or UniFi OS Server) has been added with version 2.0.7. When adding the details for a UniFi OS console to the config/config.php file, please make sure not to add trailing slashes to the URL. For UniFi OS Consoles (e.g., UDM PRO) use port 443 for the connection.

When using the UniFi API browser to connect to a Network Application on a UniFi OS-based gateway via the WAN interface, it is necessary to create a specific firewall rule to allow external access to port 443 on the gateway's local interface. For more information, please refer to the following blog post for further details: https://artofwifi.net/2022/04/07/how-to-access-the-unifi-controller-by-wan-ip-or-hostname-on-a-udm-pro/

When connecting to a UniFi OS Server, make sure to use port 11443 for the connection.

Extending the Collections dropdown menu

Since version 2.0.0 you can extend the Collections dropdown menu with your own options by adding them to the config.php file.

Here's an example:

/**
 * adding a custom sub-menu example
 */
$collections = array_merge($collections, [
    [
        'label' => 'Custom Menu', // length of this string is limited due to dropdown menu width
        'options' => [
            [
                'type' => 'collection', // either 'collection' or 'divider'
                'label' => 'hourly site stats past 24 hours', // string that is displayed in the dropdown menu
                'method' => 'stat_hourly_site', // name of the method/function in the API client class that is called
                'params' => [(time() - (24 * 60 *60)) * 1000, time() * 1000], // an array containing the parameters as they are passed to the method/function
            ],
            [
                'type' => 'collection',
                'label' => 'daily site stats past 31 days',
                'method' => 'stat_daily_site',
                'params' => [(time() - (31 * 24 * 60 *60)) * 1000, time() * 1000],
            ],
            [
                'type' => 'divider', // dividers have no other properties
            ],
            [
                'type' => 'collection',
                'label' => 'enable the site LEDs',
                'method' => 'site_leds', // don't go too wild when adding such calls, this example is simply to show the flexibility
                'params' => [true]
            ],
            [
                'type' => 'collection',
                'label' => 'disable the site LEDs',
                'method' => 'site_leds', // don't go too wild when adding such calls, this example is simply to show the flexibility
                'params' => [false]
            ],
        ],
    ],
]);

Note: for a collection type menu option the type, label, method, and params "properties" are required.

Note: custom menu entries only apply to classic controllers. They are automatically hidden when an official API controller is selected.

This is what the result looks like for the above example:

Custom sub menu

Updates

If you installed the tool using the git clone command, you can apply updates by going into the directory where the tool is installed, and running the git pull command from there.

Otherwise, you can simply copy the contents from the latest zip file to the directory where the tool has been installed.

Credits

The PHP API client that comes bundled with this tool is based on the work by the following developers:

and the API as published by Ubiquiti:

Other included libraries:

Security notice

Caution

It is important to note that the UniFi API browser tool is a powerful tool that allows access to sensitive data and configuration options on your UniFi controller. It is therefore important you take appropriate security measures, such as limiting access to the tool to trusted individuals. Additionally, you should be aware of the security risks associated with running PHP code on your server.

We highly recommend enabling the username/password authentication feature by creating a config/users.php based on the included config/users-template.php file. When creating passwords and their SHA512 hashes for entry in the config/users.php file, make sure to use strong random passwords. Please refer to the instructions in the config/users-template.php file for further details

Support and Feedback

This project is actively maintained, and feedback and suggestions are always welcome. If you encounter any issues or have any suggestions for improvements, please use the GitHub issue list or the Ubiquiti Community forums (https://community.ubnt.com/t5/UniFi-Wireless/UniFi-API-browser-tool-released/m-p/1392651) to share your ideas and questions.

Screenshots

Here are a couple of screenshots of the tool in action.

The Login form when user authentication is enabled:

Login form

The controller selection dropdown menu:

Controller selection

Now with different controller types:

Image

The site selection dropdown menu:

Site selection

The collection dropdown menu:

Select collection

Showing the site settings collection in JSON format:

Site settings in JSON format

Showing the site settings collection in interactive PHP format:

Site settings in PHP format

Showing a collection from the Official API (initial page):

Image

Showing a collection from the Official API (all pages):

Image

The "About" modal:

About modal