Author’s Notes:
December 2012 update: As of Software Update 6.0, we have incorporated the Professional Quota API into our new 6.0 GUI, which is documented in our full User Guide. The”Professional Quota API User Guide” is now deprecated.
Due to the popularity of User Quotas, we built a GUI to implement the quota commands. We recommend using the 6.0 GUI to configure User quotas, which incorporates all the commands listed below and does NOT require basic programming skills to use.
July 2012 update: As of Software Update 5.8, we now offer the Professional Quota API, which provides a GUI front-end to the NUQ-API. Enclosed is a link to the Professional Quota API User Guide (PDF), which walks you through how to use the new GUI toolset.

Professional Quota API Guide
If you prefer to use the native commands (NUQ API) instead of the new GUI, OR if you are using a Software Update prior to 5.8 (< 5.8), please follow the instructions below. If you are current on NSS, we recommend upgrading to 5.8 to use the new Professional Quota API GUI. If you are not current on NSS, you can call 303.997.1300 ext.5 or email admin@apconnections.net to get current.
The following article serves as the programmer’s toolkit for the new NetEqualizer User-Quota API (NUQ API). Other industry terms for this process include bandwidth allotment, and usage-based service. The NUQ API toolkit is available with NetEqualizer release 4.5 and above and a current software subscription license (NSS).
Note: NetEqualizer is a commercial-grade, Linux-based, in-line bandwidth shaper. If you are looking something windows-based try these.
Background
Prior to this release, we provided a GUI-based user limit tool, but it was discontinued with release 4.0. The GUI tool did not have the flexibility for application development, and was inadequate for customizations. The NetEqualizer User-Quota API (NUQ API) programmer’s toolkit is our replacement for the GUI tool. The motivation for developing the toolkit was to allow ISPs, satellite providers, and other Internet management companies to customize their business processes around user limits. The NUQ API is a quick and easy way to string together a program of actions in unique ways to meet your needs. However, it does require basic programming/Linux skills.
Terms of Use
APconnections, the maker of the NetEqualizer, is an OEM manufacturer of a bandwidth shaping appliance. The toolkit below provides short examples of how to use the NUQ API to get you started developing a system to enforce quota bandwidth limits for your customers. You are free to copy/paste and use our sample programs in the programmer’s toolkit to your liking. However, questions and support are not covered in the normal setup of the NetEqualizer product (NSS) and must be negotiated separately. Please call 303.997.1300 x103 or email sales@apconnections.net to set up a support contract for the NUQ API programmer’s toolkit.
Once you have upgraded to version 4.5 and have purchased a current NSS, please contact APconnections for installation instructions. Once installed, you can find the tools available in the directory/art/quota.
Step 1: Start the Quota Server
In order to use the NUQ API programmer’s toolkit, you must have the main quota server running. To start the quota server from the Linux command line, you can type:
# /art/quota/quota &
Once the quota main process is running, you can make requests using the command line API.
The following API commands are available:
quota_create
Usage:
quota_create 102.20.20.2/24
Will cause the NetEqualizer to start tracking data for a block (subnet) of IP addresses in the range 10.20.20.0 through 10.20.20.255.
_________________________________________________________________________________________________________
quota_remove
Usage:
/art/quota/quota_remove 102.20.20.2/24
Will remove a block of IP addresses from the quota system.
Note: You must use the exact same IP address and mask to remove a block as was used to create the block.
_________________________________________________________________________________________________________
quota_set_alarm
Usage:
/art/quota/quota_set_alarm 102.20.20.2/17 <down limit> <up limit>
Will set an alarm when an IP address reaches a defined limit.
Alarm notifications will be reported in the log /tmp/quotalog. See the sample programs below for usage.
Note: All IPs in the subnet range will get flagged when/if they reach the defined limit. The limits are in bytes transferred. Alarm notifications are reported in the quotalog /tmp/quotalog. See example below.
_________________________________________________________________________________________________________
quota_remove_alarm
Usage:
/art/quota/quota_remove_alarm 102.20.20.2/17
Will remove all alarms in effect on the specified subnet.
Note: The subnet specification must match exactly the format used when the alarm was created — same exact IP address and same exact mask.
_________________________________________________________________________________________________________
quota_reset_ip
Usage:
/art/quota/quota_reset_ip 102.20.20.2/17
Will reset the usage counters for the specified subnet range
_________________________________________________________________________________________________________
quota_status_ip
Usage:
/art/quota/quota_status_ip 102.20.20.2/24
Will show the current usage byte count for the specified IPs in the range to the console. The usage counters must be initiated with quota_create command.
Will also put usage statistics to the default log /tmp/quotalog
_________________________________________________________________________________________________________
quota_rules
Will display all current rules in effect
Usage:
/art/quota/quota_rules
_________________________________________________________________________________________________________
ADD_CONFIG
Usage:
/art/ADD_CONFIG HARD <ip> <down> <up><subnet mask> <burst factor>
Used to set rate limits on IP’s, which would be the normal response should a user exceed their quota.
Parameter definitions:
HARD Constant that specifies the type of operation. In this case HARD indicates “hard limit”.
<ip> The IP address in format x.x.x.x
<down> Is the specified max download (inbound) transfer speed for this ip in BYTES per second, this is not kbs.
<up> Is the specified upload (outbound) transfer speed in BYTES per second
<subnet mask> Specifies the subnet mask for the IP address. For example, 24 would be the same as x.x.x.x/24 notation. However, for this command the mask is specified as a separate parameter.
<burst factor> The last field in the command specifies the burst factor. Set this field to 1 (no bursting) or to a multiple greater than 1 (bursting). BURST FACTOR is multiplied times the <down> and <up> HARD LIMITs to arrive at the BURST LIMIT (default speed you wish to burst up to). For example… 2Mbps <down> HARD LIMIT x 4 BURST FACTOR = 8Mbps <down> BURST LIMIT.
_________________________________________________________________________________________________________
REMOVE_CONFIG
Usage:
/art/REMOVE_CONFIG HARD x.x.x.x
Where x.x.x.x is the base ip used in the ADD_CONFIG HARD command no other parameters are necessary on the removal of the rule.
_________________________________________________________________________________________________________
To view the Log:
Usage:
/tmp/quotalog
Various status messages will get reported along with ALARMs and usage statistics
_________________________________________________________________________________________________________
Examples and Sample sessions (assumes Linux shell and Perl knowledge)
From the command line of a running NetEqualizer first start the quota server
root@neteq:/art/quota# /art/quota/quota &
[1] 29653
#
Then I issue a command to start tracking byte counts on the local subnet, for this example I have some background network traffic running across the NetEqualizer.
root@neteq:/art/quota# ./quota_create 192.168.1.143/24
Created 192.168.1.143/24
root@neteq:/art/quota#
I have now told the quota server to start tracking bytes on the subnet 192.168.1.*
To see the transferred current byte count on an IP you can use the status_ip command
root@neteq:/art/quota# ./quota_status_ip 192.168.1.143/24
Begin status for 192.168.1.143/24
status for 192.168.1.255
start time = Fri Apr 2 21:23:13 UTC 2010
current date time = Fri Apr 2 21:55:28 UTC 2010
Total bytes down = 65033
Total bytes up = 0
status for 192.168.1.119
start time = Fri Apr 2 21:54:50 UTC 2010
current date time = Fri Apr 2 21:55:28 UTC 2010
Total bytes down = 3234
Total bytes up = 4695
End of status for 192.168.1.143/24
root@neteq:/art/quota#
Yes, the output is a bit cryptic, but everything is there. For example, the start time and current time since the data collection started on each IP reporting in.
Now let’s say we wanted to do something useful when a byte count or quota was exceeded by a user.
First, we would set up an alarm.
root@neteq:/art/quota# ./quota_set_alarm 192.168.1.143/24 10000 10000
alarm block created for 192.168.1.143/24
We have now told the quota server to notify us when any IP in the range 192.168.1.* exceeds 10000 bytes up or 10000 bytes down.
Note: If an alarm is raised, the next alarm will occur at twice the original byte count. In the example above, we will get alarms at 10,000, 20,000, 30,000 and so forth for all IPs in the range. Obviously, in a commercial operation, you would want your quotas set much higher in the gigabyte range.
Now that we have alarms set, how do we know when the happen and how can we take action?
Just for fun, we wrote a little perl script to take action when an alarm occurs. So, first here’s the perl script code and then and example of how to use it.
root@neteq:/art# cat test
#!/usr/bin/perl
while ( 1)
{ $line = readline(*STDIN);
print $line;
chomp ($line);
@foo=split(” “, $line);
if ( $foo[0] eq “ALARM”)
{
print “send an email to somebody important here \n”;
}
}
First, save the perl script off to a file. In our example, we save it to a file /art/test
Next, we will monitor the /tmp/quotalog for new alarms as they occur, and when we find one we will print the message “send and email to somebody important here” . To actually send an email you would need to set up an email server and call the command line smtp command with your message , we did not go that far here.
Here is how we use the test script to monitor the quotalog (where ALARM Messages get reported)
root@neteq:/art# tail -f /tmp/quotalog | ./test
Log Reset
ALARM 192.168.1.119 has exceeded up byte count of 160000
send an email to somebody important here
ALARM 192.168.1.119 has exceeded down byte count of 190000
send an email to somebody important here
ALARM 192.168.1.119 has exceeded up byte count of 170000
send an email to somebody important here
ALARM 192.168.1.119 has exceeded down byte count of 200000
send an email to somebody important here
ALARM 192.168.1.119 has exceeded up byte count of 180000
send an email to somebody important here
ALARM 192.168.1.119 has exceeded down byte count of 210000
send an email to somebody important here
ALARM 192.168.1.119 has exceeded up byte count of 190000
send an email to somebody important here
ALARM 192.168.1.119 has exceeded down byte count of 220000
send an email to somebody important here
Now, what if we just want to see what rules are in effect? Here is a sequence where we create a couple of rules and show how you can status them. Note the subtle difference between the command quota_rules and status_ip. Status_ip shows ip’s that are part of rule and are actively counting bytes. Since a rule does not become active (show up in status) until there are actually bytes transferred.
root@neteq:/art/quota# ./quota_create 192.168.13.143/24
Created 192.168.13.143/24
root@neteq:/art/quota# ./quota_rules
Active Quotas —————
192.168.13.143/24
Active Alarms —————-
root@neteq:/art/quota# ./quota_set_alarm 192.168.11.143/24 20000 20000
alarm block created for 192.168.11.143/24
root@neteq:/art/quota# ./quota_rules
Active Quotas —————
192.168.13.143/24
Active Alarms —————-
192.168.11.0/24
root@neteq:/art/quota#
That concludes the NetEqualizer User-Quota API (NUQ API) programmers toolkit for now. We will be adding more examples and features in the near future. Please feel free to e-mail us at support@apconnections.net with feature requests and bug reports on this tool.
Note: You must have a current NSS to receive the toolkit software. It is not enabled with the default system.
Related Opinion Article on the effectiveness of Quotas
Simple Is Better with Bandwidth Monitoring and Traffic Shaping Equipment
June 7, 2010 — netequalizerBy Art Reisman
Editor’s note: Art Reisman is the CTO of APconnections. APconnections designs and manufactures the popular NetEqualizer bandwidth shaper.
For most IT administrators, bandwidth monitoring of some sort is an essential part of keeping track of, as well as justifying, network expenses. However, the question a typical CIO will want to know before approving any purchase is, “What is the return on investment for your equipment purchase?”. Putting a hard and fast number on bandwidth optimization equipment may seem straight forward. If you can quantify the cost of your bandwidth and project an approximate reduction in usage or increase in throughput, you can crunch the numbers. But, is that all you should consider when determining how much you should spend on a bandwidth optimization device?
The traditional way of looking at monitoring your Internet has two dimensions. First, the fixed cost of the monitoring tool used to identify traffic, and second, the labor associated with devising and implementing the remedy. In an ironic inverse correlation, we assert that your ROI will degrade with the complexity of the monitoring tool.
Obviously, the more detailed the reporting/shaping tool, the more expensive its initial price tag. Yet, the real kicker comes with part two. The more detailed data output generally leads to an increase in the time an administrator is likely to spend making adjustments and looking for optimal performance.
But, is it really fair to assume higher labor costs with more advanced monitoring and information?
Well, obviously it wouldn’t make sense to pay more for an advanced tool if there was no intention of doing anything with the detailed information it provides. But, typically, the more information an admin has about a network, the more inclined he or she might be to spend time making adjustments.
On a similar note, an oversight often made with labor costs is the belief that when the work needed to adjust the network comes to fruition, the associated adjustments can remain statically in place. However, in reality, network traffic changes constantly, and thus the tuning so meticulously performed on Monday may be obsolete by Friday.
Does this mean that the overall productivity of using a bandwidth tool is a loss? Not at all. Bandwidth monitoring and network adjusting can certainly result in a cost-effective solution. But, where is the tipping point? When does a monitoring solution create more costs than it saves?
A review of recent history reveals that technologies with a path similar to bandwidth monitoring have become commodities and shunned the overhead of most human intervention. For example, computer operators disappeared off the face of the earth with the invention of cheaper computing in the late 1980s. The function of a computer operator did not disappear completely, it just got automated and rolled into the computer itself. The point is, anytime the cost of a resource is falling, the attention and costs used to manage it should be revisited.
An effective compromise with many of our customers is that they are stepping down from expensive, complex reporting tools to a simpler approach. Instead of trying to determine every type of traffic on a network by type, time of day, etc., an admin can spot trouble by simply checking overall usage numbers once a week or so. With a basic bandwidth control solution in place (such as a NetEqualizer), the acute problems of a network locking up will go away, leaving what we would call only “chronic” problems, which may need to be addressed eventually, but do not require immediate action.
For example, with a simple reporting tool you can plot network usage by user. Such a report, although limited in detail, will often reveal a very distinct bell curve of usage behavior. Most users will be near the mean, and then there are perhaps one or two percent of users that will be well above the mean. You don’t need a fancy tool to see what they are doing. Abuse becomes obvious just looking at the usage (a simple report).
However, there is also the personal control factor, which often does not follow clear lines of ROI.
What we have experienced when proposing a more hands-off model to network management is that a customer’s comfort depends on their bias for needing to know, which is an unquantifiable personal preference. Even in a world where bandwidth is free, it is still human nature to want to know specifically what bandwidth is being used for, with detailed information regarding the type of traffic. There is nothing wrong with this desire, but we wonder how strong it might be if the savings obtained from using simpler monitoring tools were converted into, for example, a trip to Hawaii.
In our next article, we’ll put some real world numbers to the test for actual breakdowns, so stay tuned. In the mean time, here are some other articles on bandwidth monitoring that we recommend. And, don’t forget to take our poll.
List of monitoring tools compiled by Stanford
ROI tool , determine how much a bandwidth control device can save.
Great article on choosing a bandwidth controller
Planetmy
Linux Tips
How to set up a monitor for free
Good enough is better a lesson from the Digital Camera Revolution
Created by APconnections, the NetEqualizer is a plug-and-play bandwidth control and WAN/Internet optimization appliance that is flexible and scalable. When the network is congested, NetEqualizer’s unique “behavior shaping” technology dynamically and automatically gives priority to latency sensitive applications, such as VoIP and email. Click here for a full price list.
Share this: