Skip to content

Commit

Permalink
UniFi API browser 2.0.7
Browse files Browse the repository at this point in the history
- added support for UniFi OS-based controllers
- included the version 1.1.47 of the PHP API client class
  • Loading branch information
malle-pietje committed Feb 6, 2020
1 parent 4aceffc commit 55843a5
Show file tree
Hide file tree
Showing 15 changed files with 638 additions and 182 deletions.
12 changes: 9 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,16 @@ This tool is for browsing data that is exposed through Ubiquiti's UniFi Controll

It comes bundled with a **PHP class for access to the UniFi Controller API**, which supports [more API endpoints](https://github.com/Art-of-WiFi/UniFi-API-client#methods-and-functions-supported) than the UniFi API browser tool does.

If you plan to create your own PHP code leveraging the UniFi controller API, it is recommended to use the standalone version of the API client class which can be found here: https://github.com/Art-of-WiFi/UniFi-API-client
If you plan on creating your own PHP code to leverage the UniFi controller API, it is recommended to use the standalone version of the API client class which can be found here: https://github.com/Art-of-WiFi/UniFi-API-client

You will find examples and detailed instructions there.

Please keep the following in mind:

- the API browser tool doesn't support all available data collections/API endpoints, see the list below of those that are currently supported
- currently, versions 4.x.x and 5.x.x of the UniFi Controller software are supported (version 5.11.50 has been confirmed to work)
- there is still work to be done to add/improve functionality and usability of this tool so suggestions/comments are welcome. Please use the github [issue](https://github.com/Art-of-WiFi/UniFi-API-browser/issues) 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/questions.
- currently, versions 4.x.x and 5.x.x of the UniFi Controller software are supported (version 5.12.35 has been confirmed to work) as well as UniFi OS-based controllers (version 5.12.59 has been confirmed to work)
- when accessing UniFi OS-based controllers (e.g. UDM PRO) through this tool, please read the remarks below regarding UniFi OS support
- there is still work to be done to add/improve functionality and usability of this tool so suggestions/comments are welcome. Please use the GitHub [issue](https://github.com/Art-of-WiFi/UniFi-API-browser/issues) 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/questions.
- please read the Security Notice below before installing this tool!


Expand Down Expand Up @@ -129,6 +130,11 @@ Alternatively you may choose to download the zip file and unzip it in your direc
- 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 (UniFi Dream Machine Pro) has been added with version 2.0.7. When adding the details for a UniFi OS device to the `config/config.php` file, please make sure not to add a port suffix or trailing slashes to the URL.


### Extending the dropdown menu

Since version 2.0.0 you can extend the dropdown menu with your own options by adding them to the `config.php` file. Here's an example:
Expand Down
9 changes: 8 additions & 1 deletion ajax/fetch_collection.php
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,14 @@
'lan-rx_packets',
'lan-tx_packets',
'lan-rx_dropped',
'lan-tx_dropped'
'lan-tx_dropped',
'wan-tx_bytes',
'wan-rx_bytes',
'wan2-tx_bytes',
'wan2-rx_bytes',
'latency_min',
'latency_avg',
'latency_max',
];

/**
Expand Down
1 change: 1 addition & 0 deletions ajax/fetch_sites.php
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,7 @@
*/
$host = parse_url($controller['url'], PHP_URL_HOST);
$port = parse_url($controller['url'], PHP_URL_PORT);
$port = $port ?: 443;

if (!empty($host) && !empty($port)) {
$fp = @fsockopen($host, $port, $errno, $errstr, 2);
Expand Down
1 change: 1 addition & 0 deletions ajax/show_api_debug.php
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@
*/
$host = parse_url($controller['url'], PHP_URL_HOST);
$port = parse_url($controller['url'], PHP_URL_PORT);
$port = $port ?: 443;

if (!empty($host) && !empty($port)) {
$fp = @fsockopen($host, $port, $errno, $errstr, 2);
Expand Down
2 changes: 1 addition & 1 deletion common.php
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
* with this package in the file LICENSE.md
*
*/
define('TOOL_VERSION', '2.0.6');
define('TOOL_VERSION', '2.0.7');

/**
* gather some basic information for the About modal
Expand Down
12 changes: 6 additions & 6 deletions composer.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 2 additions & 1 deletion js/custom.js
Original file line number Diff line number Diff line change
Expand Up @@ -325,7 +325,8 @@ function fetchDebugDetails() {
}
}
});
}}
}
}

/**
* function to fetch a collection
Expand Down
20 changes: 14 additions & 6 deletions vendor/art-of-wifi/unifi-api-client/README.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,21 @@
## UniFi Controller API client class

A PHP class which provides access to Ubiquiti's [**UniFi SDN Controller API**](https://unifi-sdn.ui.com/), versions 4.X.X and 5.X.X of the UniFi SDN Controller software are supported (version 5.11.39 has been confirmed to work). It's a standalone version of the class which is used in our API browser tool which can be found [here](https://github.com/Art-of-WiFi/UniFi-API-browser).
A PHP class that provides access to Ubiquiti's [**UniFi SDN Controller**](https://unifi-sdn.ui.com/) API, versions 4.X.X and 5.X.X of the UniFi SDN Controller software are supported (version 5.12.35 has been confirmed to work) as well as UniFi OS-based controllers (version 5.12.59 has been confirmed to work). This class is used in our API browser tool which can be found [here](https://github.com/Art-of-WiFi/UniFi-API-browser).

This class can be installed manually or using composer/[packagist](https://packagist.org/packages/art-of-wifi/unifi-api-client) for easy inclusion in your projects.
The package can be installed manually or using composer/[packagist](https://packagist.org/packages/art-of-wifi/unifi-api-client) for easy inclusion in your projects.

## Requirements

- a web server with PHP and cURL modules installed (tested on Apache 2.4 with PHP Version 5.6.1 and cURL 7.42.1 and with PHP 7.2.10 and cURL 7.58.0)
- a web server with PHP and cURL modules installed (tested on Apache 2.4 with PHP Version 5.6.1 and cURL 7.42.1 and with PHP 7.2.24 and cURL 7.58.0)
- network connectivity between this web server and the server and port (normally TCP port 8443) where the UniFi Controller is running

## Installation ##
## UniFi OS Support

Support for UniFi OS-based controllers (UniFi Dream Machine Pro) has been added as of version 1.1.47. The class automatically detects UniFi OS devices and adjusts URLs and several functions/methods accordingly. If your own code applies strict validation of the URL that is passed to the constructor, please adapt your logic to allow URLs without a port suffix when dealing with a UniFi OS-based controller.

Please test all methods you plan on using thoroughly before using the API Client with UniFi OS devices in a production environment.

## Installation

You can use [Composer](#composer), [Git](#git) or simply [Download the Release](#download-the-release) to install the API client class.

Expand Down Expand Up @@ -169,7 +175,9 @@ The class currently supports the following functions/methods to GET/POST/PUT/DEL
- power_cycle_switch_port()
- reconnect_sta()
- rename_ap()
- restart_ap()
- restart_ap() (deprecated but still available as alias)
- restart_device()
- reboot_cloudkey()
- revoke_voucher()
- set_ap_radiosettings()
- set_device_settings_base()
Expand Down Expand Up @@ -261,7 +269,7 @@ This class is based on the initial work by the following developers:

and the API as published by Ubiquiti:

- https://dl.ubnt.com/unifi/5.10.19/unifi_sh_api
- https://dl.ui.com/unifi/5.12.35/unifi_sh_api

## Important Disclaimer

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
* PHP API usage example
*
* contributed by: @4oo4
* description: example script to check and upgrade device firmware (can be scheduled with systemd/cron)
* description: example script to upgrade device firmware (can be scheduled with systemd/cron)
* to the most current version
*/
require_once('vendor/autoload.php');
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,9 @@
*/
$controlleruser = ''; // the user name for access to the UniFi Controller
$controllerpassword = ''; // the password for access to the UniFi Controller
$controllerurl = ''; // full url to the UniFi Controller, eg. 'https://22.22.11.11:8443'
$controllerversion = ''; // the version of the Controller software, eg. '4.6.6' (must be at least 4.0.0)
$controllerurl = ''; // full url to the UniFi Controller, eg. 'https://22.22.11.11:8443', for UniFi OS-based
// controllers a port suffix isn't required, no trailing slashes should be added
$controllerversion = ''; // the version of the Controller software, e.g. '4.6.6' (must be at least 4.0.0)

/**
* set to true (without quotes) to enable debug output to the browser and the PHP error log
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
<?php
/**
* PHP API usage example
*
* contributed by: @gahujipo
* description: example to pull connected users and their details from the UniFi controller and output the results
* in JSON format
*/
/**
* using the composer autoloader
*/
require_once('vendor/autoload.php');

/**
* include the config file (place your credentials etc there if not already present)
* see the config.template.php file for an example
*/
require_once('config.php');

/**
* the short name of the site which you wish to query
*/
$site_id = '<enter your site id here>';

/**
* initialize the UniFi API connection class and log in to the controller and pull the requested data
*/
$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion);
$set_debug_mode = $unifi_connection->set_debug($debug);
$loginresults = $unifi_connection->login();
$clients_array = $unifi_connection->list_clients();

/**
* output the results in JSON format
*/
header('Content-Type: application/json; charset=utf-8');
echo json_encode($clients_array);
45 changes: 45 additions & 0 deletions vendor/art-of-wifi/unifi-api-client/examples/reconnect_client.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
<?php
/**
* PHP API usage example
*
* contributed by: Art of WiFi
* description: example basic PHP script to force a client device to reconnect
*/

/**
* using the composer autoloader
*/
require_once('vendor/autoload.php');

/**
* include the config file (place your credentials etc. there if not already present)
* see the config.template.php file for an example
*/
require_once('config.php');

/**
* the MAC address to reconnect
*/
$mac_to_reconnect = '<MAC address>';

/**
* site where the above MAC address is connected
*/
$site_id = '<enter your site id here>';

/**
* initialize the UniFi API connection class and log in to the controller
*/
$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion);
$set_debug_mode = $unifi_connection->set_debug($debug);
$loginresults = $unifi_connection->login();

/**
* then we force the device to reconnect
*/
$reconnect_result = $unifi_connection->reconnect_sta($mac_to_reconnect);

/**
* provide feedback in json format
*/
echo json_encode($reconnect_result, JSON_PRETTY_PRINT);
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
<?php
/**
* PHP API usage example to turn the PoE of the selected switch ports to "off" or "auto"
*
* contributed by: @Kaltt
* description: A use case for this script is to turn off the PoE of the port where a camera is connected in order to turn off the camera
*
* usage: If the file is called via a web URL, it should be called like: update_switch_poe-mode.php?poe_mode=off
* If the file is called via the command line, it should be called like: php update_switch_poe-mode.php off
* The values can be "off" or "auto"
*/

/**
* using the composer autoloader
*/
require_once('vendor/autoload.php');

/**
* include the config file (place your credentials etc. there if not already present)
* see the config.template.php file for an example
*/
require_once('config.php');

/**
* the site to use to log in to the controller
*/
$site_id = '<short site name of a site the credentials used have access to>';

/**
* the MAC address of the AC-IW device to re-configure
*/
$device_mac = '<enter MAC address>';

/**
* $lanports is an array that defines which ports should be changed
*/
$lanports = [6];

/**
* This is the function that reads out the current port configuration and changes the value for the poe_mode for the ports defined in $lanports
*/
function update_ports($running_config, $ports, $poe_mode){
/**
* Update already non-default ports
*/
$running_config_count = count($running_config);
for($i = 0; $i < $running_config_count; $i++){
if(in_array($running_config[$i]->port_idx, $ports)){
$running_config[$i]->poe_mode = $poe_mode;
unset($ports[array_search($running_config[$i]->port_idx, $ports)]);
}
}

$add_conf = [];
foreach($ports as $port){
$add_conf[] = [
'port_idx' => $port,
'poe_mode' => $poe_mode
];
}

return array_merge($running_config, $add_conf);
}

$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion, false);
$set_debug_mode = $unifi_connection->set_debug(false);
$loginresults = $unifi_connection->login();
$data = $unifi_connection->list_devices($device_mac);
$device_id = $data[0]->device_id;
$current_conf = $data[0]->port_overrides;

/**
* This reads in the values provided via URL or in the command line, if nothing is set than it will poe_mode will be set to "auto"
*/
if (isset($_GET['poe_mode'])) {
$poe_mode = $_GET['poe_mode'];
} elseif (isset($argv[1])) {
$poe_mode = $argv[1];
} else {
$poe_mode = 'auto';
}

$new_ports_config = [
'port_overrides' => update_ports($current_conf, $lanports, $poe_mode)
];

$update_device = $unifi_connection->set_device_settings_base($device_id, $new_ports_config);

if (!$update_device) {
$error = $unifi_connection->get_last_results_raw();
echo json_encode($error, JSON_PRETTY_PRINT);
}

echo json_encode($update_device, JSON_PRETTY_PRINT);
Loading

0 comments on commit 55843a5

Please sign in to comment.