AirControl v1.

4 API
For use with development build:
Open the About dialog. Press CTRL!"#FT$
Change update site $RL to: http:%%www.ubnt.&om%downloads%air&ontrol%upd'()%
Cli&* Che&* +or $pdates and then update to the new version shown
,$RL above is not +or entr- into the browser address bar but into the AirControl update dialog..
To revert to previous version:
stop server
/o into the 0AC1#R2%webapps dire&tor-
delete ROOT%
delete ROOT.war
rename previous ar&hive to ROOT.war
start server
External API Usage
AirControl e3poses an e3perimental4 limited web servi&e to integrate with &ustom management solutions or other +rontend appli&ations. #t &an be used
with &ommand line tools li*e wget and curl or an- s&ripting language that understands "TTP,!.4 in&luding P"P4 P-thon4 "T5L%6ava!&ript. 7ou
don8t need to be a programmer to use the AP#4 but should be read- to use the shell%&ommand line ,wget and &url are also available +or 9indows..
This API follows REST conventions/style and requires authentication. For modifying oerations! administrative rivileges are required. Those need to
"e rotected and should only "e used from a server or in a way that does not e#ose them to other users $for e#amle through %avaScrit in a
customer facing ortal etc.&.
'ot all (TTP clients $"rowsers& suort (TTP P)T or *E+ETE methods. For those methods server side usage with an aroriate caa"le (TTP
client is assumed.
E#amles "elow are using wget utility $wget is availa"le on all latforms! including ,indows as art of -ygwin! an alternative is curl that suorts the
use cases "elow! .ust through different otions&.
Retrieving Server Info
/et AirControl status ,&uurentl- onl- version.:
wget /htt0//localhost01232/ai/system/status4auth.user5u"nt6auth.assword5u"nt/
/et list o+ de+ined devi&e groups:
wget /htt0//localhost01232/ai/system/devicegrous4auth.user5u"nt6auth.assword5u"nt/
Retrieving Device Data
/et a devi&e list b- spe&i+-ing a group name. /roups &an be an- &ustom group under :9at&h: or :All 1evi&es: ,but not the autogroupings.. This list
&an be retrieved periodi&all- and &a&hed in a +rontend s-stem or &onsumed dire&tl- and +et&hed on demand.
The &olumns and order are as de+ined in the devi&e list &ustomi;er within the AirControl /$#. !o -ou &an setup a dedi&ated a&&ount and &ustomi;e the
devi&e table +or what -ou want to get through the AP#.
A&&ess to data through "TTP4 all parameters in&luding authenti&ation in $RL4 e3ample:
htt0//localhost01232/ai/devicegrou/All782*evices4auth.user5u"nt6auth.assword5u"nt
/et :All 1evi&es: data in T!< +ormat:
wget 99header5/Accet0te#t/ta"9searated9values/ /htt0//localhost01232/ai/devicegrou/All782*evices4auth.user5u"nt6auth.assword5u"nt/
/et :All 1evi&es: in 6!O= +ormat:
wget 99header5/Accet0alication/.son/ /htt0//localhost01232/ai/devicegrou/All782*evices4auth.user5u"nt6auth.assword5u"nt/
There is also a sample "T5L%6ava!&ript e3ample +or 6!O= and d-nami& s&ript tags that -ou &an get +rom the running server:
htt0//localhost01232/Ai:et*evice+ist.html
Access Current Statistics for single Device:
http:%%lo&alhost:>?)?%api%devi&es%??:'@:A1:BC:DC:?E%&urrent!tatsFauth.userGubntHauth.passwordGubntHt-peGtsv
$RL Iuer- parameters in&luding output options are same as +or devi&e group list.
Statistics History:
!ingle 1evi&e:
http://localhost:9080/api/devices/00:15:6D:72:42:0E/stats/wlanT!"tes#
auth$user%u&nt'auth$password%u&nt'stats(nterval)eriod%hour'stats(nterval*ount%24
Parameters: 5AC #1 and attribute name in the $R#. Attribute name ,not title. as +ound in the Attribute Con+iguration dialog in the /$#.
stats#ntervalPeriod: Aggregation%time interval ,8minute84 8hour84 8da-84 8wee*8.
stats#ntervalCount: =umber o+ intervals in the ouput.
Currentl- onl- supports T!< output +ormat. The report will have a &olumn +or ea&h interval4 with the interval start date as header.
Report &urrentl- does not &ontain line or &olumn summar- ,sum4 min4 ma34 avg..
1evi&e /roup:
http://localhost:9080/api/devicegroup/+ll,20Devices/stats/wlanT!"tes#
auth$user%u&nt'auth$password%u&nt'stats(nterval)eriod%hour'stats(nterval*ount%24
One o+ the use &ases is to generate usage reports and load the data into a spreadsheet appli&ation +or +urther pro&essing.
Get Device Map KM
http:%%lo&alhost:>?)?%api%devi&egroup%All782*evices/ma/;ml4auth.user5u"nt6auth.assword5u"nt
The resulting <=+ file can "e loaded into :oogle earth or viewed through :oogle mas $htt0//econym.org.u;/gma/;ml.htm&
Adding and deleting devices
wget 9v 9> rs.t#t 99ost9file ai9add9device.t#t 99header5/-ontent9Tye0 alication/.son/ /htt0//localhost01232/ai/devices4
auth.user5u"nt6auth.assword5u"nt/
The 6!O= data +or this reIuest:
-
/hwaddr/: /00:15:6D:16:*0:00/1
/ipaddr/: /0$0$0$0/1
/na2e/ : /api test device/1
/ssh)ort/ : null1
/we&)ort/ : null1
/latitude/ : 07$410918642822571
/longitude/ : 3121$9424858060698
4
!pe&i+-ing the the port numbers as null or omitting them will indi&ate that the s-stem wide settings should be e++e&tive +or the new devi&e.
!e"ove Device
&url i " :A&&ept: appli&ation%Json: K 1ELETE http:%%lo&alhost:>?)?%api%devi&es%??:'@:A1:'A:C(:?? 4auth.user5u"nt6auth.assword5u"nt /
Control Operations
A +ew &ontrol operations are now available: Conne&t4 upgrade ,optional +or nonmanaged devi&e.4 restore &on+iguration. A++e&ted devi&es &an be
spe&i+ied as 5AC address list or devi&e group. E3ample on how to submit a reIuest spe&i+ied in a +ile as "TTP PO!T reIuest:
wget 3v 35 ac3response$tt 33post36ile ac3re7uest$tt 33header%/*ontent3T"pe: application/8son/
9http://localhost:9080/api/tas:#auth$user%u&nt'auth$password%u&nt9
Above submits the +ile apireIuest.t3t ,6!O= +ormat. to AirControl4 running on lo&alhost:>?)?4 using login ubnt%ubnt. The a&&ount used to s&hedule
tas*s must have A15#= priviledge.
The reIuest will be e3e&uted as-n&hronousl-4 loo* at the progress list in AC and the s-stem log +or results. !u&&ess+ul s&heduled will result in "TTP
status C?'. !hould the reIuest return "TTP error @??4 &he&* 0ACL"O5E2%logs%server.log. 5ost li*el- the 6!O= +ormat was invalid.
Currentl- there is no wa- to poll the tas* status through the AP# based on the tas* identi+ier returned with "TTP response status C?'M this is something
that will be added in the +uture. At this time it is +ire and +orget as +ar as the AP# &lient is &on&erned.
#+ -ou re&eived status C?'4 AirControl has s&heduled the reIuest and it will +or a short time appear in the s&hedule list. On&e pro&essing4 loo* +or status
in the respe&tive devi&e details ,li*e an- other inprogress operation in AirControl.. !hould pro&essing +ail4 the error will be re&orded in the event log.
The AP# reIuest spe&i+i&s are en&oded in 6!O= +ormat in the +ile. !ample pa-loads are given below4 &op- these into the te3t +ile re+eren&ed on the wget
&ommand line.
Ea&h reIuest has the &ommon parameter devi&e5a&List or devi&e/roup. 1evi&e groups &an be spe&i+ied as the simple name o+ an- o+ the groups under
:9at&h: in the group tree ,e.g. :All 1evi&es: or :Low !ignal:. or4 +or &onvenien&e4 also autogroups4 su&h as :+)3;roups/T<5=+>3?>=23@)D5/4
where the leading path &omponent is the grouping name and the se&ond &omponent the spe&i+i& attribute value.
Connect #put un$er "anage"ent% $evice#s% &y MAC ID'
-
/actionT"pe/ : /connect/1
/device=acAist/:B/00:15:6D:72:42:0E/1/00:15:6D:+7:*E:7!/1/00:15:6D:16:*0:7!/C1
/login/: /u&nt/1
/password/: /u&nt/
4
,The devi&e,s. must have been added in AirControl be+ore..
Conne&t using devi&e authenti&ation with !!" *e- instead o+ password:
-
/actionT"pe/ : /connect/1
/device=acAist/:B/00:15:6D:16:*0:7!/C1
/login/: /u&nt/1
/sshDe"Eile/: //u&nt/console/test/con6ig/idFrsaFapi/
4
!e&oot Manage$ Devices
-
/actionT"pe/ : /re&oot/1
/device=acAist/:B/00:15:6D:72:42:0E/1/00:15:6D:+7:*E:7!/1/00:15:6D:16:*0:7!/C
4
Upgra$e $evice:
-
/actionT"pe/ : /6ir2ware@pdate/1
/device=acAist/:B/00:15:6D:16:*0:7!/C1
/6ir2wareGersion/ : /H=$ar7240$v5$03&eta5$7490$101210$2221/
4
@pgrade un2anaged device with eplicit device authentication I>>< :e"J:
-
/actionT"pe/ : /6ir2ware@pdate/1
/device=acAist/:B/00:15:6D:16:*0:7!/C1
/6ir2wareGersion/ : /H=$ar7240$v5$03K*2$7694$110105$1600/1
/login/: /u&nt/1
/sshDe"Eile/: //u&nt/console/test/con6ig/idFrsaFapi/
4
Configuration &ac(up for a group of $evices:
-
/actionT"pe/ : /&ac:up*on6iguration/1
/device;roup/: /+ll Devices/1
/&ac:up?a2e/ : /+)(3!ac:up/1
/&ac:up*ount/ : 0
4
!estore latest &ac(up for a group of $evices:
-
/actionT"pe/ : /restore*on6iguration/1
/device;roup/: /=" Device ;roup/1
/&ac:up?a2e/ : /5n3De2and3!ac:up/
4
A not so obvious use &ase +or this:
Na&*up a set o+ devi&es ,+rom the AirControl $#4 ondemand or s&heduled.
5anipulate the &on+iguration +iles with a &ustom routine ,at -our own ris*O.
Restore manipulated +iles through the AP# to all units.
=ote this not a recommended solution +or &on+iguration &hange4 use at own risk i+ -ou *now how to deal with s-stem.&+g and want to a&&omplish
things that &annot be a&&omplished through higher level tools at this timeO
#Mass% Configuration
A limited set o+ parameters is available +or &on+iguration through the AP# ,see list below e3amples.. !upported +irmware versions are @.( and (.A. This
is alpha +un&tionalit-. Please alwa-s test on a radio that -ou &an reset easil- be+ore appl-ing &hanges to multiple or &riti&al devi&es.
#+ -ou are running AirControl on Linu3 and using Open61P ,not !un 61P.: !ome Open61P distributions do not in&lude the s&ript engine that is
reIuired b- the &on+iguation AP#. # have seen it missing on Centos4 Fedora Open61P et&. distributions. # have seen it present on $buntu >.3 and '?.3.
#+ -ou see an error in the s-stem log re+erring to the s&ript engine4 please either install the !un 61P or email +or instru&tions on how to add it to the
e3isting Open61P ,mention e3a&t Linu3 and Open61P version..
9hen &hanging multiple devi&es in the same reIuest4 ma*e sure to onl- spe&i+- devi&es that are managed and online. Changing man- devi&es in a
bat&h will s-n&hroni;e the &on+iguration &hange so that restart o&&urs at the same time ,the larger the bat&h the more s-stem resour&es are reIuired to
pro&ess it and ma- impa&t the per+orman&e o+ -our server signi+i&antl-.. Nat&h reIuest will be &an&elled i+ an- one devi&e +ails to update ,ne&essar- +or
&hange o+ parameters that a++e&t dependen&- within groups.. Also ma*e sure to test &hanges be+ore appl-ing to multiple%man- units.
#+ &hanges do not reIuire s-n&hroni;ed e3e&ution4 spe&i+- serial e3e&ution to &hange one devi&e at a time and ignore pro&essing errors ,add
/eecute>e7uential/ : true to the reIuest.. The de+ault is :+alse: Q s-n&hroni;ed bat&h pro&essing.
-
/actionT"pe/ : /con6igure/
/device;roup/: /="Device;roup/1
/eecute>e7uential/ : true1
/attri&uteGalues/ : -
$$$
4
4
As general guideline4 *eep bat&h si;es relativel- small +or s-n&hroni;ed &hanges su&h as wireless paramaters that reIuires all devi&es to be updated at
on&e and use seIuential pro&essing other modi+i&ations.
The &on+iguration &hanges are spe&i+ied as a list o+ attributes4 whi&h will be applied on top o+ the &urrent &on+iguration on the devi&e. Ea&h reIuest &an
&ontain multiple *e-value pairs. !ome o+ those parameters have dependen&ies. For e3ample4 -ou +irst need to enable 9PA se&urit- be+ore attempting
to set the P!P. Li*ewise4 -ou onl- need to send the P!P i+ 9PA was alread- enabled. Nelow are e3amples onl-4 whi&h -ou &an adJust to the &urrent
&on+iguration state o+ the devi&es.
=ote that the *e-s used4 while the- ma- mat&h the propert- names in s-stem.&+g on the devi&e4 are not the same propert- names. The- are mapped b-
AirControl and -ou will onl- be able to &hange what is published in the AP#. ,Amongst other reasons this is ne&essar- to en+or&e integrit- rules and
guard +rom mis&on+iguration..
E3amples:
Change se&urit- to 9PA and set P!P:
-
/actionT"pe/ : /con6igure/1
/device=acAist/:B/00:15:6D:16:*0:7!/C1
/attri&uteGalues/ : -
/wireless$1$securit"/ : /wpa/1
/wireless$1$securit"$wpa$auth/ : /L)+3)>D/1
/wireless$1$securit"$wpa$ps:/ : /1204567890/
4
4
Change se&urit- to 9EP and set *e-:
-
/actionT"pe/ : /con6igure/1
/device=acAist/:B/00:15:6D:16:*0:7!/C1
/attri&uteGalueAist/ : B
B/wireless$1$securit"/1 /wep64/C1
B/wireless$1$securit"$wep$:e"3t"pe/1 /2/C1
B/wireless$1$securit"$wep$:e"/1 /62045/C
C
R
Turn o++ se&urit-:
-
/actionT"pe/ : /con6igure/1
/device=acAist/:B/00:15:6D:16:*0:7!/C1
/attri&uteGalueAist/ : B
B/wireless$1$securit"/1 /none/C
C
R
Change !!#14 wireless mode4 &hannel width4 &hannel shi+ting ,v5.3, M2.:
-
/actionT"pe/ : /con6igure/1
/device=acAist/:B/00:15:6D:16:*0:7!/C1
/attri&uteGalueAist/ : B
B/radio$1$2ode/1 /stawds/C1
B/wireless$1$ssid/1 />>(DTE>T1/C1
B/radio$1$cl:sel/ 1 /E/C1
B/radio$1$rate$2a/ 1 /7/C1
B/radio$1$chanshi6t/ 1 /ena&led/C
C
R
Change admin user:
-
/actionT"pe/ : /con6igure/1
/device=acAist/:B/00:15:6D:16:*0:7!/C1
/attri&uteGalueAist/ : B
B/s"ste2$users$1$na2e/1 /ad2in/C1
B/s"ste2$users$1$password$con6ir2/1 /u&nt/C1
B/s"ste2$users$1$password/1 /u&nt/C
C
R
!etup ping wat&h dog:
-
/actionT"pe/ : /con6igure/1
/device=acAist/:B/00:15:6D:16:*0:7!/C1
/attri&uteGalueAist/ : B
B/service$pwdog$status/1 /disa&led/C1
B/service$pwdog$host/1 /127$0$0$1/C1
B/service$pwdog$period/1 /00/C1
B/service$pwdog$dela"/1 /60/C1
B/service$pwdog$retr"/1 /0/C
C
4
List o+ &urrentl- supported parameters as o+ v'.(.B ,will be e3panded in the near +uture and as per +eedba&* re&eived.:
5ore has been added sin&e. $se the devi&e &on+iguration dialog in the AirControl /$# to &on+irm supported settings. 5a*e &hanges in the
&on+iguration tree and then review the parameters on the &on+irmation step. <alues displa-ed there are the same that need to be sent through the AP#.
Parameter Allowed values/description
RADIO SETTINGS
+ir=a )riorit"
radio$1$air2a3priorit"
-0:9<igh911:9=ediu2912:9Aow910:9?one94
radio$1$2ode
9ireless mode: /sta/1 /stawds/1 /ap/1 /apwds/
(EEE 2ode
radio$1$ieeeF2ode
+vaila&le 2odes depend on product$
E= version 0$: -9a9:9+919&9:9! onl"919g9:9!/; 2ied19pureg9:9; onl"4
E= version 5$: -911naht9 : 9+/? 2ied91911nght9 : 9!/;/? 2ied94
*hannel Lidth
radio$1$cl:sel
:?: Q C? 5";
:': Q '? 5h;
:C: Q @ 5h;
:E: Q Auto C?%D?
*hannel >hi6ting
radio$1$chanshi6t
:disabled:
:enabled:
=a Data Kate
radio$1$rate$2a
5a3imum TK Rate as inde3. Compare dropdown in AirO! $# 9ireless Tab.
<alues +or AirO! @.(: SB4A4@4D4(4C4'4?T and S'@..?T +or C3C &hain
<alues +or (.A:
- B7$$0C 6or 5;<M / + 2ode 4
- B0$$0C 6or 2;<M / ! onl" 4
- B7$$0C 6or 2;<M / ; onl" 4
- B7$$0C 6or 2;<M / !/; 2ied / 5 or 10=<M 4
U S''..?T +or C/"; % N%/ mi3ed % C?5"; R
Auto 1ata Rate
radio$1$rate$auto$status
:disabled:
:enabled:
Output Power
radio$1$tpower
The output power at whi&h wireless module transmits data . The minimun and ma3imum power
depends on produ&t. Nelow are the e3amples
Nullet 5@: min:AdNm4ma3:C@dNm
Nullet 5C: min:'CdNm4ma3:C)dNm
Ro&*et 5CKC: min: (dNm4ma3:C)dNm
Pi&ostation @: min:(dNm4ma3:CCdNm
Pi&o!tation C: min:DdNm4ma3:C?dNm
A&* distan&e
radio$1$ac:distance
#t should be less than ma3 distan&e +or given #EEE mode and &hannel width
1e+aults to ma3 distan&e i+ input distan&e is greater than ma3 distan&e
E3amples:
AirO! (.3
USma3:(C.BmilesT +or N%/ 5i3ed and C?5h;R4
USma3:A@.>milesT +or N%/ 5i3ed and '?5h;R4
USma3:'(CmilesT +or N%/ 5i3ed and @5h;R4
USma3:ABmilesT +or N Onl- and C?5h;R4
AirO! @.3
USma3:(C.CmilesT +or N%/%= 5i3ed and C?5h;R4
USma3:A@.(milesT +or N%/%= 5i3ed and '?5h;R4
USma3:'('milesT +or N%/%= 5i3ed and @5h;R4
A&* Timeout
radio$1$ac:ti2eout
#t should be between 5in and 5a3 values .
5in and 5a3 values +or timeout are derived based on #EEE mode4 &hannel width and depend
on the AirO! version. #+ value is 0min then it de+aults to min For value is 2ma3 de+aults to ma3
E3amples:

AirO! (.3
USmin:C' ma3:(BCT +or N%/ mi3ed and C?5h;R4
USmin:(B ma3:BDDT +or N%/ mi3ed and '?5h;R4
USmin:B( ma3:'D)>T +or N%/ mi3ed and @5h;R4
USmin:C@ ma3:BDDT +or N Onl- and C?5h;R4
USmin:'' ma3:C?DT +or A Onl- and D?5h;R4
AirO! @.3
USmin:CB ma3:C?DT +or A%= mi3ed,''nahtD?4''nahtD?Plus4''nahtD?5inus. and
D?5h;R4
USmin:(B ma3:D?>T +or A%= mi3ed,''nahtC?. and C?5h;R
Auto A&*
radio$1$ac:$auto$status
enabled or disabled
5uti&ast Rate
radio$1$2castrate
AirO! (.3 O=L7. Possible values are same as :radio.'.rate.ma3:
Rate Algorithm
radio$1$rateF2odue
Possible values AirO! (.A:
U:athLrateLsample:::Optimisti&:4:athLrateLonoe:::Conservative:4:athLrateLminstrel:4:E95A
:R
WIRELESS/SSID
wireless$1$ssid
0E!!#12
wireless$1$2acFacl$status
enabled or disabled
wireless$1$2acFacl$polic" /allow/1 /den"/
wireless$1$2acFacl$list
&omma separated list o+ 5AC #1s
wireless$1$securit"
:wpa:
:wpat*ip:
:wpaaes:
:wpaC:
:wpaCt*ip:
:wpaCaes:
:wepAD:
:wep'C):
:wep'@C:
:none:
wireless$1$securit"$wpa$auth
:9PAP!P:4 :9PAEAP:
station mode onl-
,valid with :wireless.'.se&urit-:G :wpa:KKK.
wireless$1$securit"$wpa$ps:
0P!P2
,valid with :wireless.'.se&urit-.wpa.auth:G :9PAP!P:.
wireless$1$securit"$wpa$eap$t"pe
:TTL!:4 :PEAP:
valid with :wireless.'.se&urit-.wpa.auth:G :9PAEAP:
station mode onl-
wireless$1$securit"$wpa$eap$inner
:5!C"AP<C: %% +i3ed
wireless$1$securit"$wpa$eap$anon"2ous3
identit"
wireless$1$securit"$wpa$eap$identit"
wireless$1$securit"$wpa$eap$passwd
wireless$1$securit"$wep$:e"3length
9EP Pe- Length: :wepAD: Q AD bit4 :wep'C): Q 'C) bit
wireless$1$securit"$wep$:e"3t"pe
:': Q he3
:C: as&ii
wireless$1$securit"$wep$:e"
9EP *e-
,Length depends on 9EP *e- length and t-pe4 see AirO! $# 9ireless Tab.
wireless$1$securit"$wep$auth2ode
:Authenti&ation T-pe: : :': open4 :C: shared *e-
SSTE!
s"ste2$device$na2e
0name o+ the devi&e2
s"ste2$latitude
s"ste2$longitude
!-stem lo&ation4 &oordinates in de&imal notation4 e.g. 'CC.?D>C??
s"ste2$users$1$na2e
0user name2 de+ault :ubnt:
s"ste2$users$1$password$con6ir2
s"ste2$users$1$password
The new password4 sent twi&e.
s"ste2$users$2$status
s"ste2$users$2$na2e
s"ste2$users$2$password
Con+iguration o+ readonl- a&&ount.
!tatus is either /ena&led/ or /disa&led/
SER"I#ES
service$pwdog$status
PING WATCH DOG /ena&led/ or /disa&led/
service$pwdog$host
#P Address To Ping
service$pwdog$period
Ping #nterval ,se&onds.
service$pwdog$dela"
!tartup 1ela- ,se&onds.
service$pwdog$retr"
Failure Count To Reboot
service$sshd$status
>>< /ena&led/ or /disa&led/ N +ir*ontrol re7uires >>< ena&led
service$sshd$port
service$sn2p$status
>?=) /ena&led/ or /disa&led/
service$sn2p$co22unit"
service$sn2p$contact
service$sn2p$location
service$ntpclient$status
?T) /ena&led/ or /disa&led/
service$ntpclient$server
service$we&server$https$status
LE!>EKGEK /ena&led/ or /disa&led/
service$we&server$https$port
service$we&server$http$port
service$we&server$session$ti2eout
service$telnet$status
TEA?ET /ena&led/ or /disa&led/
service$telnet$port
service$s"slog$status
>O>A5; /ena&led/ or /disa&led/
service$s"slog$re2ote$ip
service$s"slog$re2ote$port
service$s"slog$re2ote$status
/ena&led/ or /disa&led/
service$d"na2ic3dns$status
D"na2ic D?>1 +ir5> 5$0 onl": /ena&led/ or /disa&led/
service$d"na2ic3dns$hostna2e
service$d"na2ic3dns$userna2e
service$d"na2ic3dns$password