The second part of this tutorial will discuss the use of placeholders and variables.
Placeholders
Placeholders are a convenient method to parametrize commands sent to a controller. By default, placeholder definitions are read from a file named:
"placeholders" or "placeholders.txt".
You can change the default by using the command line option:
--placeholders <placeholders-file>
The placeholders file is a simple text file with a single placeholder specification per line. A placeholder specification takes the form:
<placeholder>=<value1>,<value2>,...
For example:
apname=AP1,AP2
A placeholder is later referenced in the commands file by using the following syntax: ${<placeholdername>}. For each placeholder value, AirRecorder will run the specified command with the "${<placeholdername>}” string replaced with its corresponding value.
For example, consider an entry like this in your commands file:
0,show ap active ap-name ${apname}
and AirRecorder would run two commands once each:
show ap active ap-name AP1
show ap active ap-name AP2
NOTE: a placeholder definition can be spread over multiple lines by escaping the end of line with a \
apname3=\
AP6,\
AP7
Variables
Variables offer an additional flexible way of parametrising commands sent to a controller. Whereas placeholders use a predefined set of values, variables work with data that is fetched from the controller at runtime. For example, to run a command for every AP on the controller, one would use the variable: %{ap:name}.
Out of the box, AirRecorder comes with a pre-defined list of variables:
%{ap:name} => all AP names as listed by "show ap active", column Name
%{ap:group} => all AP group names as listed by "show ap active", column Group
%{ap-group:name} => all AP group names as listed by "show ap-group", column Name
%{user:ip} => all IP addresses as listed by "show user-table", column IP
%{user:mac => all MAC addresses as listed by "show user-table", column MAC
%{user:name} => all user names as listed by "show user-table", column Name
%{time:hhmm} => outputs current controller time as hours:minutes (i.e. 10:42)
%{time:mmmdd} => outputs current controller time as month day (i.e. Jun 19)
Consider following entry in your commands file:
0,show ap active ap-name %{ap:name}
would instruct AirRecorder to run the command once for each active AP name.
NOTE: while variables offer a powerful way of running the same commands against multiple values, please keep in mind that it potentially generates a high number of commands that are send towards the CLI process of the controller. Use with caution!
Variables post-processing
The data set of a variable can be post-processed using processors. The general syntax is for a processor is:
.processor([argument[,argument]])
AirRecorder comes out of the box with following processors:
- .upper(): convert variable values into upper case
- .lower(): convert variable values into lower case
- .droplast(): drop last value from variable values
- .include("include string"): retains only values that contains "include string"
- .exclude("exclude string"): retains only values that do not contain "exclude string"
- .match("regular expression"): retains only values that match the regular expression
- .differ("regular expression"): retains only values that do not match the regular expression
- .replace("regular expression", "replacement"): replaces every variable value
matching regular expression
with replacement
Note that processors can be chained.
%{ap-group:name}.upper()
%{ap-group:name}.match("^DE.*").include("236")
%{time:hhmm}.replace(".$","")
NOTE/LIMITATION: when escaping in regular expressions, one needs to use double escape \ with \\: i.e. write \\S+.* for final expression: \S+.*
Custom variables
Custom variable definitions allow for arbitrary data extraction. The syntax is as follows:
#{<command>,<marker>,<column>[,<ttl>]}
where
- <command> is the command to run to fetch values, i.e. "show ap active"
- <marker> is the marker line to parse output, i.e. "Active AP Table"
- <column> is the name of the column to extract, i.e. "Name"
- <ttl> is the time-to-live of the variable content:
-1: variable is loaded once (default)
0: variable is loaded every time
x: variable is loaded every x seconds
Consider following example, with an entry like this in your commands file:
0,show ap debug radio-stats ap-name #{show ap database group APGROUP status up,,Name}
and AirRecorder would run the command once for each active AP in the AP group named APGROUP.
NOTES:
- the variable parser currently understands only the table based output commands
- marker and column are CASE sensitive
- marker can be left empty, i.e. #{<command>,,<column>[,<ttl>]}
EXCEPTIONS:
#{show clock,<format>,<N/A>,<always 0>} will output current controller time
according to <format>. <column> is ignored and <ttl> is always 0.
<format> patterns are described in
http://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html