Skip to content

Commit 891c955

Browse files
committed
updated README to reflect UniFi OS Server support
1 parent 098a06f commit 891c955

File tree

3 files changed

+68
-29
lines changed

3 files changed

+68
-29
lines changed

.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,3 +13,6 @@ desktop.ini
1313
ehthumbs.db
1414
Thumbs.db
1515
/.idea
16+
17+
# ignore Work in Progress files
18+
RECOMMENDATIONS.md

README.md

Lines changed: 64 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -10,31 +10,37 @@ There, you will also find examples and detailed instructions on how to use it.
1010

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

13-
- The tool does not support all available data collections and API endpoints. See the list below for those currently supported.
14-
- Currently, versions 5.X.X, 6.X.X, 7.X.X, and 8.X.X of the UniFi Controller software are supported (version **8.5.60** has been confirmed to work)
15-
- The Network Application on UniFi OS-based controllers is also supported, same versions as above
13+
- The tool does not support all available data collections and API endpoints. See the list below for those currently
14+
supported.
15+
- Currently, 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
16+
supported (version **9.4.19** has been confirmed to work)
17+
- Network Application on UniFi OS-based consoles and servers is also supported, same versions as above
1618
- When accessing UniFi OS-based controllers through this tool, please read the remarks regarding UniFi OS support
1719
- Please read the Security Notice before installing this tool.
1820

1921

2022
### Upgrading from 1.x to 2.x
2123

22-
Because the structure of the configuration file has changed, we recommend creating a fresh install when upgrading from 1.x to 2.x.
24+
Because the structure of the configuration file has changed, we recommend creating a fresh install when upgrading from
25+
1.x to 2.x.
2326

2427

2528
### Features
2629

2730
The UniFi API browser tool offers the following features:
2831
- Browse data collections and API endpoints exposed by the UniFi Controller API in an easy manner
2932
- Switch between sites managed by the connected controller
30-
- Switch between output formats (currently **JSON**, **JSON highlighted**, **PHP array**, **interactive**, and **PHP array, highlighted**)
31-
- Copy the results to clipboard (this is only supported with the JSON output format and will fail gracefully with large collections)
33+
- Switch between output formats (currently **JSON**, **JSON highlighted**, **PHP array**, **interactive**, and
34+
**PHP array, highlighted**)
35+
- Copy the results to clipboard (this is only supported with the JSON output format and will fail gracefully with
36+
large collections)
3237
- Switch between the default Bootstrap theme and the [Bootswatch](https://bootswatch.com/) themes
3338
- An **About** modal that shows version information for PHP, cURL, and the UniFi Controller
3439
- Very easy setup with minimal dependencies
3540
- Timing details of API calls can be useful to "benchmark" your UniFi Controller
3641
- A useful tool when developing applications that make use of the UniFi Controller API
37-
- The API exposes more data than is visible through the UniFi controller's web interface, making it useful for troubleshooting purposes
42+
- The API exposes more data than is visible through the UniFi controller's web interface, making it useful for
43+
troubleshooting purposes
3844
- Debug mode to troubleshoot cURL connections (set `$debug` to `true` in the config file to enable debug mode)
3945

4046

@@ -101,56 +107,75 @@ The UniFi API browser tool offers the following features:
101107
- list IDS/IPS events
102108
- list system log entries
103109

104-
Please note that the bundled API client supports many more API endpoints, not all make sense to add to the API browser though.
110+
Please note that the bundled API client supports many more API endpoints, not all make sense to add to the API browser
111+
though.
105112

106113

107114
### Requirements
108115

109116
- A web server with PHP (7.4.0 or higher) and the php-curl module installed
110-
- 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](https://github.com/Art-of-WiFi/UniFi-API-browser/issues/4))
111-
- Web browsers accessing this tool should have full internet access because several CSS and JS files are loaded from public CDNs.
112-
- Using an administrator account with **read-only** permissions can limit visibility on certain collection/object properties.
113-
See this [issue](https://github.com/Art-of-WiFi/UniFi-API-client/issues/129) and this [issue](https://github.com/Art-of-WiFi/UniFi-API-browser/issues/94)
114-
for an example where the WPA2 password isn't accessible for **read-only** administrator accounts.
117+
- Network connectivity between this web server and the server (and port) where the UniFi controller is running (in case
118+
you are seeing errors, please check out [this issue](https://github.com/Art-of-WiFi/UniFi-API-browser/issues/4))
119+
- Web browsers accessing this tool should have full internet access because several CSS and JS files are loaded from
120+
public CDNs.
121+
- Using an administrator account with **read-only** permissions can limit visibility on certain collection/object
122+
properties. See this [issue](https://github.com/Art-of-WiFi/UniFi-API-client/issues/129) and this [issue](https://github.com/Art-of-WiFi/UniFi-API-browser/issues/94) for an example where the WPA2 password isn't accessible for
123+
**read-only** administrator accounts.
115124

116125

117126
### Installation
118127

119-
Installation of this tool is quite straightforward. The easiest way to do this is by using `git clone` which also allows for easy updates:
120-
- 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:
128+
Installation of this tool is quite straightforward. The easiest way to do this is by using `git clone` which also allows
129+
for easy updates:
130+
- open up a terminal window on your server and `cd` to the root folder of your web server (on Ubuntu this is
131+
`/var/www/html`) and execute the following command from your command prompt:
121132
```bash
122133
git clone https://github.com/Art-of-WiFi/UniFi-API-browser.git
123134
```
124-
- when git is done cloning, follow the configuration steps below to configure the settings for access to your UniFi Controller's API
135+
- when git is done cloning, follow the configuration steps below to configure the settings for access to your UniFi
136+
Controller's API
125137

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

128141

129142
### Installation using Docker
130143

131-
@scyto maintains Docker containers for quick and easy deployment of the UniFi API browser tool. Please refer to [this Wiki page](https://github.com/Art-of-WiFi/UniFi-API-browser/wiki/Docker-Hosting) within the repository for more details. Please note we don't provide support related to Docker-based installs.
144+
@scyto maintains Docker containers for quick and easy deployment of the UniFi API browser tool. Please refer to
145+
[this Wiki page](https://github.com/Art-of-WiFi/UniFi-API-browser/wiki/Docker-Hosting) within the repository for more details. Please note we don't provide support related to
146+
Docker-based installs.
132147

133148

134149
### Configuration
135150

136-
- Credentials for access to the UniFi Controller API are configured in the file named `config/config-template.php` which should be copied/renamed to `config/config.php`
137-
- Starting with version 1.0.3, you can store **multiple controller configurations** in an array inside the `config/config.php` file
151+
- Credentials for access to the UniFi Controller API are configured in the file named `config/config-template.php` which
152+
should be copied/renamed to `config/config.php`
153+
- Starting with version 1.0.3, you can store **multiple controller configurations** in an array inside the
154+
`config/config.php` file
138155
- Please refer to the `config/config-template.php` file for further configuration instructions
139-
- Starting with API browser tool version 2.0.0, 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
140-
- 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/`
156+
- Starting with API browser tool version 2.0.0, you can restrict access to the tool by creating user accounts and
157+
passwords. Please refer to the instructions in the `config/users-template.php` file for further details
158+
- After following these steps, you can open the tool in your browser (assuming you installed it in the root folder of
159+
your web server as suggested above) by going to this url: `http(s)://<server IP address>/UniFi-API-browser/`
141160

142161

143162
### UniFi OS support
144163

145-
Support for UniFi OS-based controllers (for example, the 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.
164+
Support for UniFi OS-based controllers (for example, the UniFi Dream Machine Pro or UniFi OS Server) has been added with
165+
version 2.0.7. When adding the details for a UniFi OS console to the `config/config.php` file, please make sure not to
166+
add trailing slashes to the URL. For UniFi OS Consoles (e.g., UDM PRO) use port 443 for the connection.
146167

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

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

151175
### Extending the Collections dropdown menu
152176

153-
Since version 2.0.0 you can extend the Collections dropdown menu with your own options by adding them to the `config.php` file.
177+
Since version 2.0.0 you can extend the Collections dropdown menu with your own options by adding them to the
178+
`config.php` file.
154179

155180
Here's an example:
156181
```php
@@ -202,9 +227,11 @@ This is what the result looks like for the above example:
202227

203228
### Updates
204229

205-
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.
230+
If you installed the tool using the `git clone` command, you can apply updates by going into the directory where the
231+
tool is installed, and running the `git pull` command from there.
206232

207-
Otherwise, you can simply copy the contents from the latest [zip file](https://github.com/Art-of-WiFi/UniFi-API-browser/archive/master.zip) to the directory where the tool has been installed.
233+
Otherwise, you can simply copy the contents from the latest [zip file](https://github.com/Art-of-WiFi/UniFi-API-browser/archive/master.zip) to the directory where the tool has been
234+
installed.
208235

209236

210237
### Credits
@@ -240,7 +267,10 @@ Other included libraries:
240267
241268

242269
### Support and Feedback
243-
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](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 and questions.
270+
This project is actively maintained, and feedback and suggestions are always welcome. If you encounter any issues or
271+
have any suggestions for improvements, please use the GitHub [issue](https://github.com/Art-of-WiFi/UniFi-API-browser/issues) list or the Ubiquiti Community forums
272+
(https://community.ubnt.com/t5/UniFi-Wireless/UniFi-API-browser-tool-released/m-p/1392651) to share your ideas and
273+
questions.
244274

245275

246276
### Screenshots
@@ -274,3 +304,9 @@ Showing the site settings collection in interactive PHP format:
274304
The "About" modal:
275305

276306
![About modal](https://user-images.githubusercontent.com/12016131/67586311-9e320280-f751-11e9-9576-c0590c951edc.png "About modal")
307+
308+
309+
310+
## Recommendations
311+
312+
For prioritized technology and user experience recommendations, see RECOMMENDATIONS.md.

collections.php

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -98,7 +98,7 @@
9898
],
9999
[
100100
'type' => 'collection', // or divider
101-
'label' => 'list port configuration',
101+
'label' => 'list port profiles',
102102
'method' => 'list_portconf',
103103
'params' => [],
104104
],

0 commit comments

Comments
 (0)