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
NetEqualizer News Blog 
Behind the Scenes on the latest Comcast Ruling on Net Neutrality
April 7, 2010 — netequalizerYesterday the FCC ruled in favor of Comcast regarding their rights to manipulate consumer traffic . As usual, the news coverage was a bit oversimplified and generic. Below we present a breakdown of the players involved, and our educated opinion as to their motivations.
1) The Large Service Providers for Internet Service: Comcast, Time Warner, Quest
From the perspective of Large Service Providers, these companies all want to get a return on their investment, charging the most money the market will tolerate. They will also try to increase market share by consolidating provider choices in local markets. Since they are directly visible to the public, they will also be trying to serve the public’s interest at heart; for without popular support, they will get regulated into oblivion. Case in point, the original Comcast problems stemmed from angry consumers after learning their p2p downloads were being redirected and/or blocked.
Any and all government regulation will be opposed at every turn, as it is generally not good for private business. In the face of a strong headwind, don’t be surprised if Large Service Providers might try to reach a compromise quickly to alleviate any uncertainty. Uncertainty can be more costly than regulation.
To be fair, Large Service Providers are staffed top to bottom with honest, hard-working people but, their decision-making as an entity will ultimately be based on profit. To be the most profitable they will want to prevent third-party Traditional Content Providers from flooding their networks with videos. That was the original reason why Comcast thwarted bittorrent traffic. All of the Large Service Providers are currently, or plotting to be, content providers, and hence they have two motives to restrict unwanted traffic. Motive one, is to keep their capacities in line with their capabilities for all generic traffic. Motive two, would be to thwart other content providers, thus making their content more attractive. For example who’s movie service are you going to subscribe with? A generic cloud provider such as Netflix whose movies run choppy or your local provider with better quality by design?
2) The Traditional Content Providers: Google, YouTube, Netflix etc.
They have a vested interest in expanding their reach by providing expanded video content. Google, with nowhere to go for new revenue in the search engine and advertising business, will be attempting an end-run around Large Service Providers to take market share. The only thing standing in their way is the shortcomings in the delivery mechanism. They have even gone so far as to build out an extensive, heavily subsidized, fiber test network of their own. Much of the hubbub about Net Neutrality is based on a market play to force Large Service Providers to shoulder the Traditional Content Providers’ delivery costs. An analogy from the bird world would be the brown-headed cowbird, where the mother lays her eggs in another bird’s nest, and then lets her chicks be raised by an unknowing other species. Without their own delivery mechanism direct-to-the-consumer, the Traditional Content Providers must keep pounding at the FCC for rulings in their favor. Part of the strategy is to rile consumers against the Large Service Providers, with the Net Neutrality cry.
3) The FCC
The FCC is a government organization trying to take their existing powers, which were granted for airwaves, and extend them to the Internet. As with any regulatory body, things start out well-intentioned, protection of consumers etc., but then quickly they become self-absorbed with their mission. The original reason for the FCC was that the public airways for television and radio have limited frequencies for broadcasts. You can’t make a bigger pipe than what frequencies will allow, and hence it made sense to have a regulatory body oversee this vital resource. In the early stages of commercial radio, there was a real issue of competing entities broadcasting over each other in an arms race for the most powerful signal. Along those lines, the regulatory entity (FCC) has forever expanded their mission. For example, the government deciding what words can be uttered on primetime is an extension of this power.
Now with Internet, the FCC’s goal will be to regulate whatever they can, slowly creating rules for the “good of the people”. Will these rules be for the better? Most likely the net effect is no; left alone the Internet was fine, but agencies will be agencies.
4) The Administration and current Congress
The current Administration has touted their support of Net Neutrality, and perhaps have been so overburdened with the battle on health care and other pressing matters that there has not been any regulation passed. In the face of the aftermath of the FCC getting slapped down in court to limit their current powers, I would not be surprised to see a round of legislation on this issue to regulate Large Service Providers in the near future. The Administraton will be painted as consumer protection against big greedy companies that need to be reigned in, as we have seen with banks, insurance companies, etc…. I hope that we do not end up with an Internet Czar, but some regulation is inevitable, if nothing else for a revenue stream to tap into.
5) The Public
The Public will be the dupes in all of this, ignorant voting blocks lobbied by various scare tactics. The big demographic difference on swaying this opinion will be much different from the health care lobby. People concerned for and against Internet Regulation will be in income brackets that have a higher education and employment rate than the typical entitlement lobbies that support regulation. It is certainly not going to be the AARP or a Union Lobbyist leading the charge to regulate the Internet; hence legislation may be a bit delayed.
6) Al Gore
Not sure if he has a dog in this fight; we just threw him in here for fun.
7) NetEqualizer
Honestly, bandwidth control will always be needed, as long as there is more demand for bandwidth than there is bandwidth available. We will not be lobbying for or against Net Neutrality.
8) The Courts
This is an area where I am a bit weak in understanding how a Court will follow legal precedent. However, it seems to me that almost any court can rule from the bench, by finding the precedent they want and ignoring others if they so choose? Ultimately, Congress can pass new laws to regulate just about anything with impunity. There is no constitutional protection regarding Internet access. Most likely the FCC will be the agency carrying out enforcement once the laws are in place.
Share this: