Documentation and FAQs Documentation and FAQs about NetBalancer
Questions and answers regarding NetBalancer's application (also called agent) functionality.
NetBalancer App is a software application for monitoring and managing network traffic of a computer or a group of computers.
It shows you the network traffic on your computer and helps you to set limits, priorities and rules for that traffic.
This is a concept in NetBalancer that is used to delimit network traffic in 7 main categories:
- Normal traffic - all the traffic that doesn't fall into the other 6 cathegories.
- Limited traffic - traffic whose speed can't be higher than a set limit.
- High priority traffic - traffic that has the highest priority when sent or received by your computer. This means that if, for example, Firefox and Download Manager are downloading simultaneously some files right now, and Firefox has a High priority set for its traffic (while Download Manager has just a Normal priority) then Firefox will download the files much faster then Download Manager.
- Low priority traffic - traffic that has a network priority lower than both High and Normal.
- Ignored - traffic that is completely ignored.
- Dropped - traffic that is dropped with a set drop rate.
- Delayed - traffic that is delayed.
- Custom - traffic that can be delayed, dropped and/or limited at the same time.
Also:
- Processes with a High priority will get more bandwidth than those with Normal or Low.
- When there are no other processes with a higher priority using the network then processes with Low priorities will get all the bandwidth available
- Limited, Ignored, Dropped and Delayed processes are excluded when calculating bandwidth of High, Normal or Low priority processes.
- A Limited process will be just limited when it reaches the maximum allowed bandwidth, otherwise it will work as usual.
- Dropped priorities, with a set Drop Rate, means that a part of their traffic will be dropped. For example if the drop rate is 40% then out of 100 network packets of a process about 40 of them will not reach their destination.
- Blocked is the same as Drooped with 100% Drop Rate, but works faster and requires less CPU.
- When a process has a Delayed priority then all its network packets are delayed with the set delay, in milliseconds. Usually this increases latency, and by a lesser factor decreases download/upload rates.
- Ignored processes work without any management from NetBalancer.
- The Custom priority is a useful feature for developers to simulate unstable and limited networks, similar to low quality wireless and satellite signals.
- When 'Apply limits for each connection separately' is activated then the limits are applied per connection. For example if we set a download limit of 20KB/s to Firefox and activate the 'Apply limits..' option then every single connection of the dozens Firefox makes will be limited to 20KB/s, but in total Firefox will be able to donwload at a much higher rate.
Our recommendation is to set a High priority for your most important applications, and a Low priority for the less important. For example set for your streaming application a High priority, so you can watch and listen to the media without any interruptions or hiccups. And set the priority for uTorrent and Download Manager to low, so they won't interfere with your more important applications.
Then, after you are getting used with how NetBalancer works you can set more advanced settings using Limits and Rules.
The Rules are a more advanced method of setting priorities and limits for your traffic. While the basic functionality permits you to set priorities and limits on a per process basis, Rules can be set specifying the network adapter, remote or local IP and Port, network protocol, time and more.
The Filters are just like Rules with the difference that they work at the driver level, and apply to traffic before it enters NetBalancer. A good use for filters is performance optimizations: if there is in your system some critically important traffic that must fly through the wires at the maximum speed possible then set it with filters to be Ignored, so it will go directly to its destination avoiding NetBalancer's limits, priorities and rules, and hence not spending precious precious milliseconds.
Another useful scenario is blocking at the driver level; although Rules contain the block action too, they lack some Filters only parameters, like MAC address or EtherType protocol. And you can pipe the traffic from a filter to one or more specific rules using the Rule/FilterID field, for more advanced use case.
Another useful scenario is blocking at the driver level; although Rules contain the block action too, they lack some Filters only parameters, like MAC address or EtherType protocol. And you can pipe the traffic from a filter to one or more specific rules using the Rule/FilterID field, for more advanced use case.
Yes, rules have the Time panel, where you can select the hours, day of week and/or month and set the appropriate priority for that traffic. You may want to create 2 (or more) rules, for each time period, with different settings.
Yes, add a rule for all your traffic with the traffic limited to, let say 128 kbps, and with the condition "Apply priority only when the traffic of this rule is more than 4GB in the last 1 Month". So when this rule will accumulate 4GB of traffic then all you computer speed will be limited to 128kbps.
Also you can add additional rules, for 4.5GB with a 64kbps limit or even for 5GB with traffic blocked to avoid overpay. Place the 4.5GB rule on top of the 4.GB, and the 5GB rule on top of all of them.
At the Traffic Chart, located on the bottom of NetBalancer's main window. Right click on it to change various settings or copy the viewed data to clipboard and paste it in a text or spreadsheet editor.
It is a tab where are shown all active connection on the current computer. If you select a specific process then the tab will show only that process' connection, if any. Right click on a connection to launch Ping, Trace or other tools on the connection's remote IP.
Run it from the command console as administrator:
NetBalancerSetup.exe /sp- /verysilent /norestart
We recommend to change NetBalancer's settings with
And because NetBalancer's setup file is built with Inno Setup, all Inno Setup's command line arguments are also supported.
The example below installs NetBalancer's agent only, silently, with no icons and with UI password "mypony123"
NBCMD.exe after setup, but the setup also supports a few command line args:/pwd= - sets the UI password/priorities_file= - sets the global priorities file/priorities_file_interval= - sets the global interval at which the priorities file will be re-read/rules_file= - sets the global rules file/rules_file_interval= - sets the global interval at which the rules file will be re-read/serial= - activates NetBalancer during setup/user_name= - sets the desired registration user name, that will be shown in About window/components="agent,tray,ui" - select which components must be installed. Supported components are agent, ui and tray, comma separated.
agent is the Windows service of NetBalancer App, it is mandatory, the App won't work without the agent. ui is App's main window, and tray is the tray icon and taskbar toolbar.
And because NetBalancer's setup file is built with Inno Setup, all Inno Setup's command line arguments are also supported.
The example below installs NetBalancer's agent only, silently, with no icons and with UI password "mypony123"
NetBalancerSetup.exe /sp- /verysilent /norestart /components="agent" /pwd=mypony123
NetBalancer keeps its settings in a couple of locations, depending on settings type:
- In registry, at
HKEY_CURRENT_USER\Software\SeriousBit\NetBalancerare kept the settings of the GUI and Tray apps. - The
HKEY_USERS\Default\Software\SeriousBit\NetBalancerkey contains the settings of NetBalancer's Windows service, except priorities, rules and traffic statistics, which are stored in XML files. - The rules are storred in
C:\ProgramData\SeriousBit\NetBalancer\Rules.xml - Priorities are storred in
C:\ProgramData\SeriousBit\NetBalancer\Priorities*.xml, where * is the ID of the network adapter, a number that can be negative.
Then there are also some files named C:\ProgramData\SeriousBit\NetBalancer\Traffic*.zip that contain various traffic stats.
The recommended way of changing these settings is via NBCMD.exe, however, if you want to modify them manually, you should first stop NetBalancer's service, named "NetBalancerService", otherwise it will replace your own settings on shutdown. After you changed the settings start back the service and NetBalancer will load them (it loads them only at start, and then keeps them in memory.)
Report it to us, click in NetBalancer Menu>Help>Report Bug, or please contact us via the Contact page
Ask us, and we'll answer to you directly and eventually add your question here too.
Questions and answers regarding NetBalancer Service's functionality.
It is a web service designed to remotely control one or more computer networks' traffic. More technically: the service can control a group of NetBalancer Apps.
The most common scenario is when the user installs NetBalancer on a couple or more computers and then finds out that it is quite inconvenient
and time consuming to setup them and maintain. So the service solves this very problem: all you need to do is to sync all agents and then you can
easely control them from service's control panel.
Almost all settigns and options from the Desktop app are available, and even some more, like charts, API and statistics.
From NetBalancer App's Menu>Edit>Cloud Sync.
We are still working on it, and going to release in a few months. The exact API's functionality will be published on release.
A machine and all related data is deleted automatically from our database after one month of inactivity.
"One month of inactivity" means that a machine performed its last successful sync one month ago.
Also you can delete any machine or even your entire account and all related information manually from machine details or account settings pages.
Also you can delete any machine or even your entire account and all related information manually from machine details or account settings pages.
They already are, here.
We are constantly improving NetBalancer App and Service, just keep pressing F5 on our news page. :)
Information regarding NetBalancer's command line and options.
nbcmd.exe (NetBalancer Command) is a command line tool that permits to execute various specialized commands and automate NetBalancer application from scripts or programs to programmatically control network traffic. Basically NBCMD offers the same management functionality as NetBalancer's UI, and we plan in the nearest future to add also the monitoring part.
When executed from command line NBCMD.exe will show a list of all available commands
and sub-commands with a short summary. Below is an example of the first few lines of
NBCMD's output (as it was at the moment of writing of this help):
> nbcmd.exe
application|a - shows information about NetBalancer activate|a <name> <code> - activate NetBalancer deactivate|d - deactivate NetBalancer update|u [timeout=10] [force] - check for new version and update service|s - show NetBalancer Service running status start|s - start NetBalancer Service stop|p - stop NetBalancer Service restart|r - restart NetBalancer Service settings|t - settings info logs|l <true|false> - log errors to system events log latency|y [ms] - set preferred latency security|u <old pass><new pass> - set a new password ...<CONTINUES>...
The first four lines of the output say that application is a command with no parameters but
with 2 sub-commands
To call application we must write the following command from command line:
or, alternatively we can use use the mnemonic:
Usually the mnemonic is command names's first letter, with a few exceptions. The mnemonics are shown immediately after command name:
Sub-commands are called using all preceding commands names:
or with mnemonics:
activate and update, one of which (activate) has its own sub-command deactivate.
Sub-command activate has 2 required parameters name and code, while update has two optional
parameters timeout and force, and timeout has a default value of 10 when not specified.
We'll describe all commands and sub-commands in more details further below.To call application we must write the following command from command line:
nbcmd.exe applicationor, alternatively we can use use the mnemonic:
nbcmd.exe aUsually the mnemonic is command names's first letter, with a few exceptions. The mnemonics are shown immediately after command name:
application|aSub-commands are called using all preceding commands names:
nbcmd.exe application service startor with mnemonics:
nbcmd.exe ass
All parameters are space delimited, if a complex parameter that contains spaces needs to be specified then use quotes "":
Parameters can be of several types:
When NetBalancer App is protected with a password (Menu>Edit>Settings>Security) then the spacial
nbcmd.exe command_name parameter1 "complex parameter 2" parameter3 Parameters can be of several types:
<parameter> - required parameter[parameter] - optional parameter[parameter=10] - optional parameter with a default value of 10 when not specified.<val1|val2> - un-named parameter that can accept only val1 or val2 as values. For example <true|false><down true|false> - parameter named down that accepts only true or false values.<par1 par2="" ...=""> - parameter that can accept multiple values delimited by spacesWhen NetBalancer App is protected with a password (Menu>Edit>Settings>Security) then the spacial
pwd parameter must be specified:nbcmd.exe pwd:my_supper_pass command_name parameter1 parameter2
application - show general information about NetBalancer, like version, service status and some other.application activate <name> <code> - activate NetBalancer using the supplied user's full name and activation code.nbcmd.exe activate "John Doe" 123456890 application activate deactivate - deactivate NetBalancer, i.e. remove current activation from NetBalancer.application update [timeout=10] [force] - verify for new version availability online and if there is a new version then update NetBalancer. [timeout=10] sets the maximum amount of minutes to wait for NetBalancer setup to be downloaded, after which nbcmd.exe will exit with a timeout error. if [force] is specified then NetBalancer will be updated without version verification:
> nbcmd.exe application update 10 force
Downloading setup to 'C:\cygwin\tmp\NetBalancerSetup.exe' Downloaded 16,1 KB, 0% Downloaded 376,5 KB, 13% Downloaded 1,3 MB, 45% Downloaded 2,0 MB, 72% Downloaded 2,5 MB, 89% Downloaded 2,8 MB, 100% Download completed, installing...
application service - show if NetBalancer's Windows service is running or not.application service start - start NetBalancer's Windows service.application service stop - stop NetBalancer's Windows service.application service restart - stop then start NetBalancer's Windows service.settings - show NetBalancer's current settings (one setting per line) in form of name and value delimited by a : sequence:
> nbcmd.exe settings
[Network adapters] Monitor adapter 1. 'Ethernet': True Monitor adapter 3. 'Local Area Connection': True [Severity] Level severity: 50 Severity multiplier: 5 [System] Log error to system event log: True [Bandwidth] Recalculate bandwidth: True Recalculate bandwidth every: 60 minutes [System traffic] System traffic download is limited: False System traffic download limit: 0 ...<CONTINUES>...
settings logs <true|false> - if set to true then NetBalancer will log its errors to system events logsettings latency [ms=0] - set traffic induced latency in milliseconds, with default value 0 ms.settings password <old pwd> <new pwd> - set a new password for NetBalancer UIsettings adapters - show all currently installed network adapterssettings adapters monitor <adapter nr> <true|false> - enable monitoring for a network adapter. <adapter nr> is the order number of the adapter as shown by command "settings adapters".
<true> will set adapter to be monitored, <false> will stop adapter for being monitored.settings traffic - shows the settings for bandwidth recalculation and system traffic limit.settings traffic bandwidth <true|false> [minutes] - edit bandwidth recalculation settings, enables recalculation if <true> and sets the recalculation interval to the value of [minutes] when specified. settings traffic limit <down true|false> <up true|false> [down val] [up val] - edit system traffic limit, [down val] and [up val] are numbers that specify the value in bytes/s of download and respectively upload limit.
For example nbcmd.exe settings traffic limit true true 100000 50000 will limit system traffic to a maximum of 100 KB/s download and 50 KB/s upload speeds.
settings priorities - show current default priority and ACK packets settings.settings priorities ack <true|false> - enable or disable high priority for ACK packets.settings priorities severity <value> [multiplier=5] - set severity level value and optional multiplier.settings priorities default <down priority> <up priority> [down val] [up val] [per connection <true|false>] - set the default priority, <down priority> and <up priority> are download and respectively upload priority and can accept values Low, Normal, High, Blocked, Ignored, Limited, Delayed, or Dropped. The optional [down val] and [up val] are required only when the selected priority is eighter Limited, Delayed or Dropped, in these cases the values set the limit in bytes/s, the delay in milliseconds, or the drop rate in float values from 0.0 to 1.0. Option [per connection <true|false>] can get only true or false values and sets the "Limit per connection" setting.settings priorities edit - <exe path> <down priority> <up priority> [down val] [up val] [per conn.=false] - edit the priority of an executable. <exe path> is the full path of the executable file. All other options are the same as for "settings priorities default" command.settings files - show settings of "Global priorities file" and "Global rules file" settings.settings files priorities <true|false> <interval> <path> - edit the options of the global priorities file settings, <true|false> sets if the setting is enabled, <interval> edits load interval in minutes, <path> sets the full path to the file.settings files priorities load <path> - replace all current priorities with the ones from the file located at <path>.settings files rules <true|false> <interval> <path> - edit the options of the global rules file settings, the parameters have the same meaning as at "settings files priorities" command.settings files rules load <path> - load rules from a file located at <path>.settings reset - reset all settings, including priorities, rules and filters.settings reset priorities - reset priorities only.sync <true|false> - enable or disable sync.sync account <username> <password> - set the username and password for sync, this is the registration username on our website.sync interval <seconds> - edit the interval at which NetBalancer syncs with the service, in seconds. Value 180 is recommended.sync alerts <true|false> - show alerts to user when sync is offline.sync maxevents <value> - set the maximum number of network events that NetBalancer will store in memory when offline.sync events <true|false> - enable or disable all network events reporting.sync events connections <true|false> - enable or disable connections events reporting.sync events XXX <true|false> - enable or disable XXX events reporting, where XXX is not porn but processes, icons, priorities etc.sync traffic <true|false> - enable all traffic reporting.sync servers [serv1 serv2 ...] - change sync servers list to serv1, serv2, etc. where serv1, serv2 are the IP addresses of the new serverssync now - tell NetBalancer Windows service to synchronize right now, to send all data and receive eventual commands.sync id_change <true|false> - change sync ID when machine name changes.interactive - this starts an interactive session of NBCMD.sync commands console <true|false> - accept console commands from sync service.sync commands admin <true|false> - accept admin commands.sync commands shutdown <true|false> - accept shutdown/restart user machine.sync commands password <true|false> - accept password changes from sync.sync commands updates <true|false> - accept update commands from sync.
Information regarding NetBalancer's API and usage examples.
NetBalancer Service provides a REST based API for sync automation. It can be used with any programming language that can access HTML pages, i.e. any modern programming langauge.
All API access is over HTTPS, and accessed from the
netbalancer.com/api page.
The current version of API can be read with a GET request from
/api/version
> curl -i https://netbalancer.com/api/version
HTTP/1.1 200 OK Date: Tue, 04 Feb 2014 13:32:24 GMT Content-Type: application/json; charset=utf-8 { "api_version": "1.1.0" }
All data is sent and received as JSON.
Blank fields are included as
All timestamps are returned in ISO 8601 format:
Blank fields are included as
null instead of being omitted.All timestamps are returned in ISO 8601 format:
YYYY-MM-DDTHH:MM:SSZ
All traffic values are in bytes and all traffic rate values are in bytes/second.
For GET requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter:
> curl -i https://netbalancer.com/api/machines/5F843BF3-D21B-4DE9-A067-B73AC576CB4B/urls?max=20
In this example the "5F843BF3-D21B-4DE9-A067-B73AC576CB4B" is provided for the
For POST, PATCH, PUT, and DELETE requests, parameters not included in the URL should be encoded as JSON with a Content-Type of 'application/x-www-form-urlencoded':
machineId parameter in the path while max
is passed in the query string.For POST, PATCH, PUT, and DELETE requests, parameters not included in the URL should be encoded as JSON with a Content-Type of 'application/x-www-form-urlencoded':
curl -i -u username -d '{ "name":"DarkLord", "code":1234}' https://netbalancer.com/api/machines/5F843BF3-D21B-4DE9-A067-B73AC576CB4B/activate"
There are three possible types of client errors on API calls:
1. Sending invalid JSON in request body will result in a
1. Sending invalid JSON in request body will result in a
400 Bad Request response.
> 400 Bad Request
HTTP/1.1 400 Bad Request Content-Length: 35 {"message":"Problems parsing JSON"}
2. Sending the wrong type of JSON values in request body will result in a
400 Bad Request response.
> 400 Bad Request
HTTP/1.1 400 Bad Request Content-Length: 40 {"message":"Body should be a JSON Hash"}
3. Sending invalid fields will result in a
422 Unprocessable Entity response.
> 422 Unprocessable Entity
HTTP/1.1 422 Unprocessable Entity Content-Length: 149 { "message": "Validation Failed", "errors": [ { "field": "name", "code": "missing_field" } ] }
All error objects have resource and field properties so that your client can tell what the problem is. There’s also an error code to let you know what is wrong with the field. These are the possible validation error codes:
missing - This means a resource does not exist.missing_field - This means a required field on a resource has not been set.invalid - This means the formatting of a field is invalid. The documentation for that resource should be able to give you more specific information.already_exists - This means another resource has the same value as this field. This can happen in resources that must have some unique key (such as Label names).
NetBalancer REST API currently supports only Basic Authentication, requests that require authentication will return
403 Forbidden.
> curl -u "username" https://netbalancer.com/api/machines
Authenticating with invalid credentials will return 401 Unauthorized:
> curl -i https://netbalancer.com/api/machines -u foo:bar
HTTP/1.1 401 Unauthorized { "message": "Bad credentials", "documentation_url": "https://netbalancer.com/docs#api_overview" }
After detecting several requests with invalid credentials within a short period, the API will temporarily reject all authentication attempts for that user (including ones with valid credentials) with
403 Forbidden:
> curl -i https://netbalancer.com/api/machines -u username:password
HTTP/1.1 403 Forbidden { "message": "Maximum number of login attempts exceeded. Please try again later.", "documentation_url": "https://netbalancer.com/docs#api_overview" }
For requests using Basic Authentication you can make up to 5,000 requests per hour. For unauthenticated requests, the rate limit allows you to make up to 60 requests per hour.
You can check the returned HTTP headers of any API request to see your current rate limit status:
> curl -i https://netbalancer.com/api/version
HTTP/1.1 200 OK Date: Mon, 01 Jul 2013 17:27:06 GMT Status: 200 OK X-RateLimit-Limit: 60 X-RateLimit-Remaining: 56 X-RateLimit-Reset: 1372700873
The headers tell you everything you need to know about your current rate limit status:
Once you go over the rate limit you will receive an error response:
X-RateLimit-Limit - The maximum number of requests that the consumer is permitted to make per hour.X-RateLimit-Remaining - The number of requests remaining in the current rate limit window.X-RateLimit-Reset - The time at which the current rate limit window resets in UTC epoch seconds.Once you go over the rate limit you will receive an error response:
> HTTP/1.1 403 Forbidden
HTTP/1.1 403 Forbidden Date: Tue, 20 Aug 2013 14:50:41 GMT Status: 403 Forbidden X-RateLimit-Limit: 60 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1377013266 { "message": "API rate limit exceeded. See https://netbalancer.com/docs#api_overview for details." }
Most responses return an
ETag header. You can use the value of this header to make subsequent requests to those resources using
the If-None-Match header. If the resource has not changed, the server will return a 304 Not Modified.
Also note: making a conditional request and receiving a 304 response does not count against your Rate Limit,
so we encourage you to use it whenever possible.
> curl -iH 'User-Agent: ' https://netbalancer.com/api/machines
HTTP/1.0 403 Forbidden Content-Type: text/html Request forbidden by administrative rules. Please make sure your request has a User-Agent header. Check https://netbalancer.com/docs#api_overview for other possible causes." }
All API requests MUST include a valid User-Agent header. Requests with no User-Agent header will be rejected.
We request that you use your NetBalancer username, or the name of your application, for the User-Agent header value.
This allows us to contact you if there are problems.
Here’s an example:
If you provide an invalid User-Agent header, you will receive a 403 Forbidden response:
Here’s an example:
User-Agent: Awesome-NetBalancer-User
If you provide an invalid User-Agent header, you will receive a 403 Forbidden response:
> curl -iH 'User-Agent: ' https://netbalancer.com/api/machines
HTTP/1.0 403 Forbidden Content-Type: text/html Request forbidden by administrative rules. Please make sure your request has a User-Agent header. Check https://netbalancer.com/docs#api_overview for other possible causes." }
Full list of all API methods with examples.
The current version of API can be read with a GET request from
/api/version. This method does not require authentication.
> GET /api/version
HTTP/1.1 200 OK { "api_version": "1.0.0" }
You can request a specific version of the API via the
Accept header:curl -i --header "Accept: v1" https://netbalancer.com/api/version
Returns a list of all user's machines, where "name" is machine's current network name, "id" is a Guid assigned by NetBalancer and "is_favorite" shows if user has marked the machine as favorite.
> GET /api/machines
HTTP/1.1 200 OK { "Machines": [ { "name": "MACWIN8", "id":"531b83ce-757f-4164-8d17-5bf58784a6b5", "is_favorite":false }, { "name":"MACWIN9", "id":"220282ae-6dea-4209-b695-b869aa298f9b", "is_favorite":true } ] }
Returns dashboard info for a machine.
:id is machine's Id, can be read whith GET /api/machines.
> GET /machines/:id
HTTP/1.1 200 OK { "os": "Microsoft Windows 8.1 Pro", "os_bits": 64, "processes": 74, "connections": 56, "downloaded": 211584, "download_rate": 0, "uploaded": 246558, "upload_rate": 0, "ip": "178.168.41.125", "last_online": "2013-10-16T11:56:59.739Z", "is_favorite": false }
Get current traffic rules of a machine.
> GET /machines/:id/rules
HTTP/1.1 200 OK { "rules": [ { "name": "New Rule 1", "adapter_id": null, "process_name": "winamp", "command_line" : "", "process_id": "", "filter_id": "", "local_endpoint": "", "local_port": "", "remote_endpoint": "", "remote_port": "", "protocol": null, "priority": { "download_priority": "normal", "upload_priority": "normal", "download_limit": 30000, "upload_limit": 30000, "download_delay": 0, "upload_delay": 0, "download_drop_rate": 0.0, "upload_drop_rate": 0.0, "download_delay_jitter": 0, "upload_delay_jitter": 0, "per_connection_limits": false }, "time": null, "day_week": null, "day_month": null, "month": null, "condition": { "enabled": false, "more_than": true, "quantity": 1000000000, "unit": "GB", "sent": null, "time": 1, "time_unit": "month" }, "url": null, "enabled": true, "ssid": "", "user": "SYSTEM", "country_code": "US, UK, MD" } ] }
Get traffic filters of a machine.
> GET /machines/:id/filters
HTTP/1.1 200 OK { "filters": [ { "adapter": null, "direction": 3, "action": 1, "ethernet_filter": null, "network_filter": { "src_address": "10.0.0.0 - 10.255.255.255", "src_mask": null, "dest_address": "10.0.0.0 - 10.255.255.255", "dest_mask": null, "protocol": null }, "transport_filter": null, "name": "Local Network Range #1", "enabled": true, "time": null, "day_week": null, "day_month": null, "month": null }, { "adapter": null, "direction": 3, "action": 1, "ethernet_filter": null, "network_filter": { "src_address": "169.254.0.0 - 169.254.255.255", "src_mask": null, "dest_address": "169.254.0.0 - 169.254.255.255", "dest_mask": null, "protocol": null }, "transport_filter": null, "name": "Local Network Range #2", "enabled": true, "time": null, "day_week": null, "day_month": null, "month": null } ] }
Get running processes on a machine.
> GET /machines/:id/processes
HTTP/1.1 200 OK { "processes": [ { "id": "6221a141-5c7f-436a-8ef5-72f8a8356ea3", "pid": 396, "name": "csrss.exe", "path": "csrss.exe [Unknown]", "download": 0, "upload": 0, "connection": 0, "download_delay": 0, "download_drop_rate": 0.0, "download_limit": 30000, "download_priority": "normal", "upload_delay": 0, "upload_drop_rate": 0.0, "upload_limit": 30000, "upload_priority": "normal", "download_delay_jitter": 0, "upload_delay_jitter": 0, "per_connection_limits": false }, { "id": "7b15f874-1cb2-45a1-b7b2-e16ca0ef54fe", "pid": 0, "name": "System Idle Process", "path": "System Idle Process [Unknown]", "download": 0, "upload": 0, "connection": 0, "download_delay": 0, "download_drop_rate": 0.0, "download_limit": 30000, "download_priority": "normal", "upload_delay": 0, "upload_drop_rate": 0.0, "upload_limit": 30000, "upload_priority": "normal", "download_delay_jitter": 0, "upload_delay_jitter": 0, "per_connection_limits": false } ] }
Returns the traffic history of a machine with 1 second resolution.
time is in UTC epoch seconds, download and upload are in bytes.
> GET /machines/:id/traffic/seconds
HTTP/1.1 200 OK { "traffic": [ { "time": 1391677345000, "download": 383732, "upload": 45345 }, { "time": 1391677355000, "download": 0, "upload": 453 }, { "time": 1391677365000, "download": 732, "upload": 0 }, { "time": 1391677375000, "download": 37, "upload": 45 }, ] }
Same as above: returns traffic history in minutes, hours and respectively days in the same format.
GET /machines/:id/traffic/minutesGET /machines/:id/traffic/hoursGET /machines/:id/traffic/days
Gets a list of last visited URLs on a machine.
> GET /api/machines/:id/urls
HTTP/1.1 200 OK { "urls": [ { "address": "mscrl.microsoft.com/pki/mscorp/crl/mswww(6).crl", "time": 1381923815994 }, { "address": "ubuntu.com", "time": 1381923815687 }, { "address": "apple.com", "time": 1381923477129 } ] }
Returns the current settings of NetBalancer on that machine.
> GET /api/machines/:id/settings
HTTP/1.1 200 OK { "log_errors_to_system_events_log": true, "check_bandwidth": true, "bandwidth_limit": 0.78, "bandwidth_recalculate": true, "bandwidth_recalculate_interval": 3600000, "limit_multiple_instances_as_one": false, "limit_download_traffic": false, "download_traffic_limit": 100000, "limit_upload_traffic": false, "upload_traffic_limit": 100000, "high_priority_for_ack": false, "preferred_latency": 5, "fast_traffic_detection": true, "download_delay": 0, "download_drop_rate": 0.0, "download_limit": 30000, "download_priority": "normal", "download_delay_jitter": 0, "per_connection_limits": false, "upload_delay": 0, "upload_drop_rate": 0.0, "upload_limit": 30000, "upload_priority": "normal", "upload_delay_jitter": 0, "count_ignored_processes_traffic": false, "level_severity": 50, "severity_multiplier": 1, "rules_first": true }
Gets current Sync settings of a machine.
sync_frequency is in seconds, sync_timeout is in milliseconds.
> GET /api/machines/:id/settings/sync
HTTP/1.1 200 OK { "sync_frequency": 10, "max_events": 1000000, "is_sync_enabled": true, "is_reporting_connections": true, "is_reporting_loopback_connections": false, "is_reporting_processes": true, "is_reporting_icons": true, "is_reporting_priorities": true, "is_reporting_rules": true, "is_reporting_filters": true, "is_reporting_urls": true, "is_reporting_cpu_load_per_process": true, "is_reporting_system_info": true, "is_reporting_internal_ip": true, "is_reporting_external_ip": true, "is_reporting_connections_traffic": true, "is_reporting_processes_traffic": true, "is_reporting_rules_traffic": true, "is_reporting_filters_traffic": true, "is_reporting_protocols_traffic": true, "is_reporting_sys_event_log": true, "accept_admin_commands": true, "accept_console_commands": true, "accept_shutdown_commands": true, "accept_password_changes_command": true, "accept_automatic_updates_command": true, "change_id_when_machine_name_changes": true, "sync_timeout": 60000 }
Checks whether Traffic Inspector is currently enabled for that machine or not.
> GET /api/machines/:id/inspector
HTTP/1.1 200 OK { "enabled": false }
To sets a new set of filters on a machine use the PUT HTTP verb:
> PUT /api/machines/:id/filters
INPUT DATA: { filters: [ { adapter: 341, direction: "all", action: "block", ethernet_filter: { src_mac: "123456789ABC", dest_mac: "00A0C914C829", protocol: 0xCAFE }, network_filter: { src_address: "80.68.3.4", src_mask: "255.243.3.4", dest_address: "192.168.1.2", dest_mask: "255.255.255.200", protocol: 70 }, transport_filter: { src_port_range: [ 30, 3433 ], dest_port_range: [ 10, 1000 ] }, name: "test filter 1", enabled: true, time: [ 60, 360 ], day_week: [ true, false, false, true, true, false, false ], day_month: [ true, false, true, false, true, false, true, false, true, false, true, false, true, false, true, false, true, false, true, false, true, false, true, true, true, true, true, true, true, true, true ], month: [ false, true, false, false, false, false, false, true, true, false, false, true ] } ] }
Sets a new set of rules.
> PUT /api/machines/:id/rules
INPUT DATA: { rules: [ { name: "rule test 1", adapter_id: 54321, process_name: "skype.exe", command_line: "--debug", process_id: "9001", filter_id: "287628276287", local_endpoint: "192.168.2.1", local_port: "8082", remote_endpoint: "skype.com", remote_port: "928", protocol: 54, priority: { download_priority: "high", upload_priority: "low", download_limit: 23849, upload_limit: 32223, download_delay: 10, upload_delay: 45, download_drop_rate: 0.34, upload_drop_rate: 0.64, download_delay_jitter: 20, upload_delay_jitter: 53, per_connection_limits: true }, time: [ 60, 360 ], day_week: [ true, false, false, true, true, false, false ], day_month: [ true, false, true, false, true, false, true, false, true, false, true, false, true, false, true, false, true, false, true, false, true, false, true, true, true, true, true, true, true, true, true ], month: [ false, true, false, false, false, false, false, true, true, false, false, true ], condition: { enabled: true, more_than: true, quantity: 192727, unit: "byte", sent: true, time: 3, time_unit: "hour" }, url: "http: \\netbalancer.com", enabled: true, ssid: "23446", user: "test_user" }, { name: "rule test 2", adapter_id: null, process_name: "winamp.exe", command_line:"", process_id: "9023", filter_id: "", local_endpoint: "192.168.2.1", local_port: "8565", remote_endpoint: "92.23.34.22", remote_port: "9265", protocol: null, priority: { download_priority: "dropped", upload_priority: "ignored", download_limit: 23841, upload_limit: 32123, download_delay: 13, upload_delay: 42, download_drop_rate: 0.32, upload_drop_rate: 0.64, download_delay_jitter: 23, upload_delay_jitter: 52, per_connection_limits: true }, time: [ 10, 320 ], day_week: [ true, true, false, true, false, false, true ], day_month: [ false, false, true, false, true, false, true, false, true, false, true, false, false, false, true, false, true, false, true, false, true, false, true, true, true, false, false, true, true, true, false ], month: [ false, true, true, true, false, false, true, true, true, false, false, true ], condition: { enabled: true, more_than: false, quantity: 192727, unit: "Byte", sent: null, time: 3, time_unit: "hour" }, url: "http: \\example.com", enabled: true, ssid: "23446", user: "test_user", "country_code": "US, UK, MD", block_lists: [ 'afe76670-5b67-d2ad-6b77-1160d0ba1df5', 'ffc721b6-d040-eec6-cfb8-36afd6daeab4', 'b46d7dab-a78e-c50a-cb14-9e6ff0fe4f71' ] } ] }
Sets a new priority for an executable.
> PUT /api/machines/:id/priority
INPUT DATA: { priority: { executable_path: "c: \\test\\winamp.exe", download_limit: 23849, download_delay: 12, download_delay_jitter: 22, download_drop_rate: 0.34, download_priority: "high", upload_limit: 32223, upload_delay: 45, upload_delay_jitter: 53, upload_drop_rate: 0.64, upload_priority: "low", per_connection_limits: true } }
Enables or disables traffic inspector on a single machine.
> PUT /api/machines/:id/inspector
INPUT DATA: { enabled : true }
Activates a machine with an activation (license) code.
> PUT /api/machines/:id/activate
INPUT DATA: { name : "Anton Carton", code: "398423097420" }
Set a password for NetBalancer App UI, if the password string is empty then it will remove it.
> PUT /api/machines/:id/password
INPUT DATA: { new_password : 'password123' }
Edits the settings of a machine.
> PUT /api/machines/:id/settings
INPUT DATA: { settings: { log_errors_to_system_events_log: false, check_bandwidth: true, bandwidth_limit: 123.0, bandwidth_recalculate: false, bandwidth_recalculate_interval: 10, limit_multiple_instances_as_one: true, limit_download_traffic: true, download_traffic_limit: 50, limit_upload_traffic: false, upload_traffic_limit: 35, high_priority_for_ack: true, preferred_latency: 50, fast_traffic_detection: true, download_delay: 10, download_drop_rate: 0.34, download_limit: 23849, download_priority: 'high', download_delay_jitter: 20, per_connection_limits: true, upload_delay: 45, upload_drop_rate: 0.64, upload_limit: 32223, upload_priority: 'low', upload_delay_jitter: 53, count_ignored_processes_traffic: false, level_severity: 51, severity_multiplier: 3, rules_first: false } }
> PUT /api/machines/:id/settings/sync
INPUT DATA: { sync_settings: { sync_frequency: 60, max_events: 10, is_sync_enabled: true, is_reporting_connections: false, is_reporting_processes: false, is_reporting_icons: false, is_reporting_priorities: false, is_reporting_rules: false, is_reporting_filters: false, is_reporting_urls: true, is_reporting_cpu_load_per_process: true, is_reporting_system_info: false, is_reporting_internal_ip: true, is_reporting_external_ip: false, is_reporting_connections_traffic: true, is_reporting_processes_traffic: true, is_reporting_rules_traffic: true, is_reporting_filters_traffic: true, is_reporting_protocols_traffic: true, is_reporting_sys_event_log: true, accept_admin_commands: false, accept_console_commands: true, accept_shutdown_commands: true, accept_password_changes_command: true, accept_automatic_updates_command: false, change_id_when_machine_name_changes: false, sync_timeout: 15 } }
Sends a Shutdown command to a machine. The command will be executed on next machine sync.
> PUT /api/machines/:id/commands/shutdown
> PUT /api/machines/:id/commands/reboot
Send an list of commands to NBCMD.exe on a machine, which will executed in sent order.
> PUT /api/machines/:id/commands/admin
INPUT DATA: { commands : [ "sync now" "application service stop" "application update", "application service start' ] }
To delete a machine and all related data, including traffic history, use DELETE verb with the path below.
> DELETE /api/machines/:id/
Resets all custom priorities to the default priority, usually Normal/Normal.
> DELETE /api/machines/:id/priorities
> DELETE /api/machines/:id/settings
Deletes all currently queued commands, including admin commands, edit setting commands, edit sync commands, reboots etc.
> DELETE /api/machines/:id/commands
> GET /api/account
HTTP/1.1 200 OK { "email":"test@example.com", "name":null, "company":null, "is_bit_preferred":true, "accept_promotions":true, "accept_product_updates":true, "accept_important_emails":true, "last_login_ip": "192.168.1.101", "last_login_time": "2014-01-24T08:57:17.614Z" }
Changes the password of netbalancer.com web account.
> PUT /api/user/password
{ new_password : "1234567890" }
Changes company name if the account.
> PUT /api/machines/:id/
{ company: "SeriousBit" }
The change yoru email preferences use one of the following API calls:
PUT /api/account/email/promotionsPUT /api/account/email/updatesPUT /api/account/email/important> PUT /account/email/promotions
{ "enabled": false }
Deletes your account and related data, including machines, commands, settings, traffic history, etc.
> DELETE /api/account
To get machine specific statistics use one of the API calls below with a GET request:
Similarily for aggregate statistics:
/api/machines/:id/statistics/processes/day/api/machines/:id/statistics/processes/week/api/machines/:id/statistics/processes/month/api/machines/:id/statistics/ips/day/api/machines/:id/statistics/ips/week/api/machines/:id/statistics/ips/month/api/machines/:id/statistics/websites/day/api/machines/:id/statistics/websites/week/api/machines/:id/statistics/websites/monthSimilarily for aggregate statistics:
/api/statistics/processes/day/api/statistics/processes/week/api/statistics/processes/month/api/statistics/ips/day/api/statistics/ips/week/api/statistics/ips/month/api/statistics/websites/day/api/statistics/websites/week/api/statistics/websites/month> GET /machines/:id/statistics/processes/day
HTTP/1.1 200 OK { "processes": [ { "executable": "System Idle Process [Unknown]", "downloaded": 60, "uploaded": 42 }, { "executable": "C:\\wrk\\netbalancer2\\deskapp\\src\\SeriousBit.NetBalancer.UI\\bin\\Debug\\SeriousBit.NetBalancer.UI.exe", "downloaded": 66, "uploaded": 297 } ] }
> GET /machines/:id/statistics/ips/day
HTTP/1.1 200 OK { "ips": [ { "ip": "192.168.1.1", "downloaded": 60, "uploaded": 42 }, { "ip": "192.168.1.2", "downloaded": 66, "uploaded": 297 } ] }
> GET /machines/:id/statistics/websites/day
HTTP/1.1 200 OK { "urls": [ { "url": "http://example.com", "downloaded": 60, "uploaded": 42 }, { "url": "http://seriousbit.com", "downloaded": 66, "uploaded": 297 } ] }
> PUT /api/log
HTTP/1.1 200 OK { "log": [ { "id": "b626387d-87a4-47c3-918d-9c82f4dc2c43", "machine_id": "00000000-0000-0000-0000-000000000000", "time": "2014-02-05T08:41:25.393Z", "message": "Attempt to log into web account, ip ::1", "priority": "critical" }, { "id": "8111d793-8ee8-4ef3-9774-2f161d062024", "machine_id": "00000000-0000-0000-0000-000000000000", "time": "2014-02-05T08:41:20.292Z", "message": "User logged out of web account", "priority": "normal" }, { "id": "1390e1b6-c58d-48f7-aeef-896e0a476d02", "machine_id": "93b77c42-d637-4881-8af4-3f22062697dc", "time": "2014-01-29T13:43:44.645Z", "message": "Commands \"icon request\" sent to MACWIN8", "priority": "normal" } ] }
Returns detailed information about this machine's OS and sowftare configuration.
> PUT /api/machines/:id/software
HTTP/1.1 200 OK { "system_bootup_state": "Normal boot", "system_daylight_in_effect": true, "system_vendor": "Acer", "system_infrared_supported": true, "system_processors_count": 1, "system_domain": "WORKGROUP", "system_is_domain": false, "system_owner": "rsologub", "system_description": "AT/AT COMPATIBLE", "system_type": "x64-based PC", "memory_installed": 1073741824, "memory_capacity": 4294967296, "proc_version": "Model 4, Stepping 2", "proc_manufacturer": "AuthenticAMD", "proc_id": "078BFBFF00020F42", "proc_type": 3, "proc_description": "AMD64 Family 15 Model 36 Stepping 2", "proc_status": "OK", "proc_ext_clock": 800, "proc_current_clock_speed": 1800, "proc_name": "AMD Turion(tm) 64 Mobile Technology ML-34", "os_organization": "", "os_serial_number": "00426-OEM-8992662-00400", "os_csd_number": "Service Pack 1", "os_registered_user": "rsologub", "os_install_date": "2012-11-06T00:00:00Z", "os_directory": "C:\\Windows", "os_code_set": 1251, "os_system_directory": "C:\\Windows\\system32", "os_suite_mask": 272, "os_build_number": 7601, "os_version": "6.1.7601", "os_name": "Microsoft Windows 7 Ultimate " }
Returns detailed information about this machine's hardware devices and configuration.
> PUT /api/machines/:id/hardware
HTTP/1.1 200 OK { "processors": [ { "id": 33562629, "name": "AMD Turion 64 ML-34", "logo_name": "amd_turion64", "code_name": "Lancaster", "package": "Socket 754", "technology": 90.5, "technology_unit": "nm", "core_voltage": -1.0, "specification": "AMD Turion(tm) 64 Mobile Technology ML-34", "family": 15, "model": 4, "stepping": 2, "ext_family": 15, "ext_model": 36, "revision": "SH8-E5", "instructions": [ "MMX Ext", "3DNow! Ext", "SSE", "SSE2", "SSE3", "x86-64", "NX" ], "cores": [ { "number": 0, "speed": 799.05, "multiplier": 4.0, "temp_sensor": null } ], "bus_speed": 200.0, "qpi_link": 800.0, "max_cache_level": 2, "caches": [ { "size": 64, "count": 1, "level": 1, "ways": 2, "line_size": 64, "type": "Data" }, { "size": 64, "count": 1, "level": 1, "ways": 2, "line_size": 64, "type": "Instructions" }, { "size": 1024, "count": 1, "level": 2, "ways": 16, "line_size": 64, "type": "Unified" } ], "threads": 1, "ht_supported": false, "ht_enabled": false, "vt_supported": false, "vt_enabled": false, "stock_clock_frequency": 1800, "stock_bus_frequency": 200, "manufacturer": "Unknown" } ], "mainboard": { "manufacturer": "Acer", "model": "Aspire 5020", "model_rev": "Rev.A", "serial_number": "LXA4605061542063C2KS00", "chipset_manufacturer": "ATI", "chipset": "Xpress 200 (RS480)", "chipset_rev": "01", "southbridge_manufacturer": "ATI", "southbridge": "SB400 Rev. 00", "bios": "Phoenix", "bios_version": "V1.13", "bios_date": "09/09/2005", "graphic_version": "PCI-Express", "graphic_link_width": -1 }, "memory": { "type": "DDR", "channels": 1, "size": 1024, "dram_frequency": 160.0, "cas_latency": 2.5, "ras_to_cas_delay": 3, "ras_precharge": 3, "cycle_time": 7, "command_rate": 2, "row_to_column": 10 }, "spds": [ { "memory_type": "DDR", "module_size": 512, "max_bandwidth": "PC2700(166 MHz)", "manufacturer": "Siemens AG", "part_number": "SDN06464O2B32MT-60", "serial_number": "09205617", "week": 55, "year": 3, "timming_tables": [ { "frequency": 133, "cas_latency": 2, "ras_to_cas": 3, "ras_precharge": 3, "t_ras": 6, "trc": 0, "command_rate": 0, "voltage": 2.5 }, { "frequency": 166, "cas_latency": 2, "ras_to_cas": 3, "ras_precharge": 3, "t_ras": 7, "trc": 0, "command_rate": 0, "voltage": 2.5 } ] }, { "memory_type": "DDR", "module_size": 512, "max_bandwidth": "PC2700(166 MHz)", "manufacturer": "Corsair", "part_number": "VS512SDS333 ", "serial_number": "00000000", "week": 0, "year": 0, "timming_tables": [ { "frequency": 166, "cas_latency": 2, "ras_to_cas": 3, "ras_precharge": 3, "t_ras": 7, "trc": 0, "command_rate": 0, "voltage": 2.5 } ] } ], "graphic_cards": [ { "name": "Intel(R) HD Graphics", "code_name": "", "technology": null, "memory_size": -1, "memory_type": "Unknown (-1)", "bus_width": 0, "performance_levels": [ { "name": "", "core": -1, "shaders": -1, "memory": -1, "stock_core": -1, "stock_shaders": -1, "stock_memory": -1 } ], "current_performance_level": -1, "core_temp": -1, "shaders_temp": -1, "memory_temp": -1, "fan_speed": -1, "fam_pwm": -1, "driver_version": null, "directx_version": "11.0", "bus_type": 0, "multi_vpu": 0 } ], "monitors": [ { "name": "Battery 1", "type": "Batterry", "id": 0, "internal_id": -1, "sensors": [ { "name": "Current Voltage", "sensor_index": 0, "monitor_id": 0, "raw_value": 16256, "float_value": 16.256, "min_value": 16.256, "max_value": 16.256, "type": "Voltage" }, { "name": "Designed Capacity", "sensor_index": 0, "monitor_id": 0, "raw_value": 1100, "float_value": 1100.0, "min_value": 1100.0, "max_value": 1100.0, "type": "Capacity" }, { "name": "Full Charge Capacity", "sensor_index": 1, "monitor_id": 0, "raw_value": 63, "float_value": 63.0, "min_value": 63.0, "max_value": 63.0, "type": "Capacity" }, { "name": "Current Capacity", "sensor_index": 2, "monitor_id": 0, "raw_value": 61, "float_value": 61.0, "min_value": 61.0, "max_value": 61.0, "type": "Capacity" }, { "name": "Wear Level", "sensor_index": 0, "monitor_id": 0, "raw_value": 5, "float_value": 95.0, "min_value": 95.0, "max_value": 95.0, "type": "Level" }, { "name": "Charge Level", "sensor_index": 1, "monitor_id": 0, "raw_value": 96, "float_value": 96.82539, "min_value": 96.82539, "max_value": 96.82539, "type": "Level" } ] }, { "name": "TOSHIBA MK1234GAX", "type": "Hdd", "id": 1, "internal_id": -1, "sensors": [ { "name": "Assembly", "sensor_index": 0, "monitor_id": 1, "raw_value": 22, "float_value": 22.0, "min_value": 22.0, "max_value": 22.0, "type": "Temperature" } ] } ] }
Returns the list of block lists on this machine.
> GET /machines/:id/blocklists
HTTP/1.1 200 OK { 'block_lists':[ { id: '719b4ab1-23ab-4942-046b-ebe2605b3002', name: 'block_list_name_1', autoUpdate: false, urlFileName: 'some_path_to_file_on_machine_or_url_path', lastUpdated: 'Monday, June 15, 2009 1:45:30 PM', ranges: 231000 }, { id: '719b4ab1-23ab-4942-046b-ebe2605b3002', name: 'block_list_name_2', autoUpdate: false, urlFileName: 'some_path_to_file_on_machine_or_url_path', lastUpdated: 'Monday, June 15, 2009 1:45:30 PM', ranges: 785469 }, { id: '719b4ab1-23ab-4942-046b-ebe2605b3002', name: 'block_list_name_3', autoUpdate: true, urlFileName: 'some_path_to_file_on_machine_or_url_path', lastUpdated: 'Tuesday, June 16, 2009 1:46:30 PM', ranges: 123058 } ] }
Returns the the block list on this machine.
> GET /machines/:machineid/blocklists/:blocklistid
HTTP/1.1 200 OK { id: "719b4ab1-23ab-4942-046b-ebe2605b3002" name: 'block_list_name', autoUpdate: true, urlFileName: 'some_path_to_file_on_machine_or_url_path', lastUpdated: 'Monday, June 15, 2009 1:45:30 PM', ranges: 231000 }
Modifies the block lists on this machine.
> PUT /machines/:machineid/blocklists
{ 'block_lists':[ { id: '719b4ab1-23ab-4942-046b-ebe2605b3002', name: 'block_list_name_1', autoUpdate: false, urlFileName: 'some_path_to_file_on_machine_or_url_path', lastUpdated: 'Monday, June 15, 2009 1:45:30 PM', ranges: 231000 }, { id: '719b4ab1-23ab-4942-046b-ebe2605b3002', name: 'block_list_name_2', autoUpdate: false, urlFileName: 'some_path_to_file_on_machine_or_url_path', lastUpdated: 'Monday, June 15, 2009 1:45:30 PM', ranges: 785469 }, { id: '719b4ab1-23ab-4942-046b-ebe2605b3002', name: 'block_list_name_3', autoUpdate: true, urlFileName: 'some_path_to_file_on_machine_or_url_path', lastUpdated: 'Tuesday, June 16, 2009 1:46:30 PM', ranges: 123058 } ] }
Info about NetBalancer's programmable rules and conditions.
Rules for Writing Programmable Rules in NetBalancer
Overview
Programmable rules in NetBalancer allow you to manage and manipulate network traffic by defining packet priorities, traffic limits, bindings, delays, and more. The rules use a C#-based script to define the behavior for incoming and outgoing network packets. The programmable environment consists of the Packet and Context classes, along with helper methods for prioritizing, limiting, delaying, and binding network traffic.
Structure of a Programmable Rule
Programmable rules are written as simple scripts that manipulate the network traffic based on properties of each packet and the surrounding context. Below are key components and helper functions you can use to write effective rules:
1. Define Packet and Context Variables
packetprovides details about the current packet, such as direction, protocol, application, and more.contextprovides additional information about the network environment, and each rule has its own separate context, such as:context.ruleName: The name of the current rule.context.downloaded/context.uploaded: The total downloaded or uploaded data matched by the current rule, in bytes.context.vpn: The current VPN status, indicating whether the connection is active and providing information like VPN server name and IP.context.tag: User-defined data associated with the rule.
The context variable persists until the rule is modified or the program is restarted.
2. Logic for Rule Evaluation
Define logic to determine how packets should be processed, using fields such as packet.incoming, packet.country, packet.ipProto, etc. Use conditional statements to classify packets based on attributes like country, application protocol, adapter, or network direction.
3. Set Traffic Priorities
Helper Functions to set priority for packets:
high(),normal(),low()- Assigns high, normal, or low priority.block()- Blocks a packet.ignore()- Ignores the packet, excluding it from statistics.limit(traffic, packet)- Limits traffic speed and/or packet count.delay(delay, jitter)- Introduces a delay with optional jitter.drop(rate)- Drops packets at a given rate (0.0 to 1.0).custom(trafficLimit, packetsLimit, delay, jitter, dropRate)- Advanced custom handling.traffic(time, unit, incoming)- Returns the traffic downloaded or uploaded by the current rule. Helper variables are defined (`seconds`, `minutes`, `hours`, `days`, `months` for the `unit` parameter; and `incoming` and `outgoing` for the `incoming` parameter).
4. Bind Traffic
Use bind(macAddress) to bind traffic to a specific network adapter if required. Ensure to check with canBind(macAddress) to validate whether traffic can be bound.
5. DSCP Settings
Set Differentiated Services Code Point (DSCP) values using dscp(precedence, delay, throughput, reliability) to prioritize packets on network segments.
6. Pass to Next Rule
Use pass() when the packet does not meet the criteria of the current rule and should be evaluated by the next rule.
Detailed Description of Packet and Context Variables
Packet Fields
The packet variable contains details about each network packet being processed. Below are the fields available:
body: The body of the packet at the data link OSI layer (layer 2), represented as a byte array.ack: Boolean value indicating if the packet has the ACK (Acknowledgment) flag set.syn: Boolean value indicating if the SYN (Synchronize) flag is set for this packet.outgoing: Boolean value indicating if the packet is outgoing from the current PC.incoming: Boolean value indicating if the packet is incoming from the network.localIp: The local IP of the packet, represented as an array of 4 (IPv4) or 16 (IPv6) bytes, ornullif not available.remoteIp: The remote IP of the packet, represented as an array of 4 (IPv4) or 16 (IPv6) bytes, ornullif not available.localPort: The local port of the packet's connection.remotePort: The remote port of the packet's connection.ethProto: The Ethernet protocol number (e.g., IPv4, ARP).ipProto: The IP protocol number (e.g., TCP, UDP).appProto: The name of the detected application protocol if DPI (Deep Packet Inspection) is enabled. This can benull.country: The detected country code of the remote IP. Can benullif unknown.filter: The filter ID of the packet, starts from 1, or 0 if no filter is applied.pid: The process ID (PID) of the application that this packet belongs to, or-1if no PID is available.executable: The full path to the executable associated with the packet (e.g.,C:\Program Files\App\app.exe). Can be an empty string but nevernull.exeName: The name of the executable without the path (e.g.,app.exe). Can be an empty string but nevernull.user: The user name associated with the process that this packet belongs to.adapter: The name of the network adapter that the packet passes through.ssid: The WiFi SSID name of the network adapter if applicable. Can benull.latitude: The geographic latitude of the remote endpoint (range:-90to+90). Is0if the location is unknown or the IP is on a local network.longitude: The geographic longitude of the remote endpoint (range:-180to+180). Is0if the location is unknown or the IP is on a local network.
Context Fields
The context variable provides information about the environment in which the packet is processed:
ruleName: The name of the rule currently being executed.downloaded: The total number of bytes downloaded by traffic matched by the current rule.uploaded: The total number of bytes uploaded by traffic matched by the current rule.vpn: The current VPN status, provided as an instance of theVpnStatusclass:vpn.name: The name of the current VPN server (e.g.,"nuremberg"). Is an empty string if no VPN is connected.vpn.ip: The IP address of the current VPN server. Is"0.0.0.0"if no VPN is connected.vpn.connected: Boolean indicating whether the VPN is connected.vpn.connecting: Boolean indicating whether the VPN is in the process of connecting.vpn.disconnecting: Boolean indicating whether the VPN is in the process of disconnecting.vpn.disconnected: Boolean indicating the VPN is disconnected.vpn.error: Boolean indicating whether an error occurred while connecting to the VPN.vpn.p2p: Boolean indicating whether the current VPN server allows P2P (peer-to-peer) traffic.
tag: User-defined data associated with the rule. This can be used to store information that needs to persist across multiple rule evaluations.
The context variable persists until the rule is modified or the program is restarted.
Example Rules
Here are some example rules to help illustrate how to create effective programmatic conditions:
Example 1: Prioritize US-Based Incoming Traffic
if (packet.country == "US" && packet.incoming) {
// Set high priority for incoming traffic from the US
high();
}
Explanation: Incoming traffic from the United States is set to high priority.
Example 2: Limit Upload Traffic to Specific Countries
if (packet.country == "CN" && packet.outgoing) {
// Limit upload traffic to China to 50 KB/s
limit(50000);
}
Explanation: The rule limits the upload traffic destined to China to 50 KB/s.
Example 3: Block All P2P Traffic
if (packet.ipProto == UDP && (packet.remotePort == 6881 || packet.remotePort == 6882)) {
block();
}
Explanation: The rule blocks traffic using typical BitTorrent ports.
Example 4: Apply Delay for Traffic in Peak Hours
var currentTime = DateTime.Now;
// Delay all traffic between 6 PM and 10 PM by 200 ms
if (currentTime.Hour >= 18 && currentTime.Hour <= 22) {
delay(200);
}
Explanation: This rule adds a 200ms delay to all traffic during peak hours between 6 PM and 10 PM.
Example 5: Allow Program Only via VPN
if ((context.vpn.connected || context.vpn.connecting) && packet.exeName == "vpn_app.exe") {
high();
} else {
block();
}
Explanation: This rule ensures that traffic from the application vpn_app.exe is allowed only if the VPN is connected or in the process of connecting.
Example 6: Block Microsoft Telemetry IPs
if (packet.remoteIp != null && (packet.remoteIp.SequenceEqual(new byte[] { 13, 107, 42, 12 }) ||
packet.remoteIp.SequenceEqual(new byte[] { 40, 90, 189, 100 }))) {
block();
}
Explanation: This rule blocks specific IP addresses used for Microsoft telemetry. The byte arrays (new byte[] { 13, 107, 42, 12 } and new byte[] { 40, 90, 189, 100 }) represent the IP addresses 13.107.42.12 and 40.90.189.100, respectively, in their raw form. Each number corresponds to an octet of the IP address.
Example 7: Bind Program to Adapter
if (packet.exeName == "bind_app.exe") {
bind("48-E7-DA-0D-C4-C9");
}
Explanation: The rule binds traffic from the bind_app.exe application to a specific network adapter identified by its MAC address.
Example 8: Block All But One Process
if (packet.exeName != "allowed_process.exe") {
// Block all traffic except for the allowed process
// Allow ARP, ICMP, LLMNR, NBNS, DNS traffic, as blocking these can disrupt basic network functionality in Windows
if (
packet.ethProto == Arp ||
packet.ipProto == ICMP ||
packet.ipProto == UDP && (packet.remotePort == 5355 || // LLMNR
packet.remotePort == 137 || // NBNS
packet.remotePort == 53) // DNS
) {
pass();
} else {
block();
}
}
Explanation: This rule blocks all traffic except for the traffic generated by allowed_process.exe and essential network traffic.
Example 9: Track State with Context Tag
if (packet.exeName == "example_app.exe") {
// Use tag to track packet order number and drop every 5th packet
if (context.tag == null) {
context.tag = 1;
} else {
context.tag = (int)context.tag + 1;
}
if ((int)context.tag % 5 == 0) {
drop(1.0); // Drop every 5th packet
}
}
Explanation: This rule uses the context's tag to keep track of packet order and drops every fifth packet.
Example 10: Use DSCP for Quality of Service
if (packet.country == "US" && packet.incoming) {
// Set DSCP value to prioritize traffic
dscp(precedence: 5, delay: false, throughput: true, reliability: true);
}
Explanation: This rule sets the DSCP values to provide specific Quality of Service for incoming traffic from the US.
Example 11: Use the traffic() function to get the downloaded or uploaded traffic for this rule in the past
if (traffic(30, minutes, outgoing) > 1000000) {
// Limit outgoing traffic if it exceeds 1 MB in the last 30 minutes
limit(10000);
} else if (traffic(60, minutes, incoming) > 2000000) {
// Limit incoming traffic if it exceeds 2 MB in the last 60 minutes
limit(10000);
} else {
normal();
}
Explanation: This rule limits the outgoing traffic rate to 10 KB/s if the total outgoing traffic in the past 30 minutes exceeds 1 MB. Additionally, if the total incoming traffic in the past 60 minutes exceeds 2 MB, it limits the rate to 10 KB/s.
Best Practices for Writing Rules
- Simplicity: Keep the rules simple. Avoid excessive complexity that may impact performance.
- Order of Rules: Rules are evaluated in order, so ensure the order of checks aligns with the desired traffic management strategy.
- Testing: Test each rule in a controlled environment before deploying to production. This is critical for avoiding disruptions.
-
Use
pass()Wisely : Avoid creating a bottleneck where every rule always passes; instead, be strategic in designing when to pass or handle traffic.
Key Methods and Their Use
high()/normal()/low(): Sets the priority of the current packet.block(): Prevents packet transmission completely.limit(traffic, packets): Limits traffic to the specified rate.delay(delay, jitter): Adds a latency factor to the packet.dscp(): Manages packet DSCP fields for Quality of Service settings.bind(macAddress): Rebinds the packet to a network adapter by its MAC address.traffic(time, unit, incoming): Returns the traffic downloaded or uploaded by the current rule.require(dll): Includes a reference to a .NET assembly.
Helper Constants for Protocols
Ethernet (ETH) Protocols
- No Ethernet type:
const ushort None = 0x0000; - Internet Protocol, Version 4 (IPv4):
const ushort IpV4 = 0x0800; - Address Resolution Protocol (ARP):
const ushort Arp = 0x0806; - Reverse Address Resolution Protocol (RARP):
const ushort ReverseArp = 0x8035; - Wake-On-Lan (WOL):
const ushort WakeOnLan = 0x0842; - AppleTalk (Ethertalk):
const ushort AppleTalk = 0x809B; - AppleTalk Address Resolution Protocol (AARP):
const ushort AppleTalkArp = 0x80F3; - VLAN-tagged frame (IEEE 802.1Q):
const ushort VLanTaggedFrame = 0x8100; - Internet Protocol, Version 6 (IPv6):
const ushort IpV6 = 0x86DD; - Link Layer Discovery Protocol (LLDP):
const ushort LLDP = 0x88CC; - MAC security (IEEE 802.1AE):
const ushort MacSecurity = 0x88E5; - Precision Time Protocol (IEEE 1588):
const ushort PrecisionTimeProtocol = 0x88f7; - Fibre Channel over Ethernet:
const ushort FibreChannelOverEthernet = 0x8906; - Ethernet loopback packet:
const ushort Loop = 0x0060; - (...Additional constants are defined for other protocols...)
IP Protocols
- Dummy protocol for TCP:
const ushort IP = 0; - IPv6 Hop-by-Hop options:
const ushort HOPOPTS = 0; - Internet Control Message Protocol:
const ushort ICMP = 1; - User Datagram Protocol:
const ushort UDP = 17; - Transmission Control Protocol:
const ushort TCP = 6; - Encapsulation Header:
const ushort ENCAP = 98; - Protocol Independent Multicast:
const ushort PIM = 103; - Raw IP packets:
const ushort RAW = 255; - (...Additional constants are defined for other protocols...)
These constants can be used in the programmable rules to check fields like packet.ethProto and packet.ipProto to easily identify the type of Ethernet or IP protocol being processed.