V600-TCP Interface

From Newsbin

Jump to: navigation, search

Version 6 TCP Interface

Version 6.10 Interface Spec

Track discussion on expanding the interface in the Discussion Tab



The Newsbin TCP Command Interface is designed to provide a method for allowing external programs to control certain aspects of Newsbin operation. The selection of TCP as the interface mechanism was for a number of reasons:

  • It could be done without programs needing to know any details of the Newsbin internal structure.
  • It was independent of any particular programming language
  • It was easy to implement!

The Newsbin TCP Command Interface was first introduced in the Newsbin 4.33 series, and the first stable version was in Newsbin 4.33B6. The Newsbin 5 series also supports this interface, although some of the commands supported are different to reflect the way that Newsbin 5 operates. It is also intended that Newsbin 5 will eventually support a much richer command set than the Newsbin 4.33 series.

Significant enhancements are being considered for Version 6 for potential remote control from iPhone, iPad, and Android devices, as well as remote computers.

Connecting to the Interface

NewsBin listens on port 118 on localhost ( It is not accessible to any process not running directly on your computer.

To connect from an application external to the host machine, a tunneling program needs to be running. A simple open source program is available here. For encrypting your connections, WinSSHD is a good SSH Server that is free for non-commercial personal use.

Successful commands have a 200 return. Errors have a 400 status return.

The easiest way to connect to this interface to see how it works is to:

Go to the Start Menu Select the option run a Command Prompt Type in the command "TELNET 118" (without the quotes) and press OK This should start up the Windows Telnet client and result in a message of the form: 200 Newsbin Server being displayed. At this point you can type in commands and see what happens.

Command Summary

The following is a summary list of the commands, and an indication of which versions of newsbin support particular commands. More details on each command is given in the next section.

Command Implemented Proposed Description
BWL X Bandwidth Limiter
CLEAR X Clear Post List
COMPRESS X Compress Spools
FILE X Load File
GetSection X Get INI file section
GetVar X Get INI file variable
PAUSE X Pause Downloads
QUIT X Close Connection
SetVar X Set INI file variable
START X Start Header Download
STOP X Stop Header Download
UPDATE X Update Headers
Downloads X New commands for remote administration. Switches include Clear, Count, List, Lock, Unlock. Read more on forum

Command Reference

Commands are not case sensitive. They are entered using standard DOS/Windows conventions for end of line (CR/LF) (also often written as /r/n). All commands return a response code followed by descriptive text. As far as the response codes are concerned, then anything 400 or higher is an error. Good results will range from 200-299 though only 200 is used today.

The following is a full list of the commands available in alphabetical order. Where a particular command is only available with specific version of Newsbin this is indicated. Any item that is enclosed in square brackets is optional. Items separated by the '|' character indicates alternatives. Items in italics are logical items (e.g. variable names).

Bandwidth Limiter

Command: BWL [ON|OFF]

Turn bandwidth limiter on or off. If the bandwidth liniter is already in the state you have requested then the command will have no effect. Returns:

200 BW Limiter On 200 BW Limiter Off


Command: CLEAR

Clearing Post list and Memory


200 Clear


Command: CLOSE

Gracefully shuts down Newsbin, saves any current download list and configuration changes


200 Newsbin Exiting



Newsbin 4.33B6/B8 only Compress all spools. Note that in this context the term "Compress" simply means remove any wasted space or headers that have expired. If you are using NTFS filing system it can still be advantageous to turn on Windows level compression which will typically reduce the space occupied by headers by 50% or more. Would allow external app to initiate auto compress at 4:00am or something.

Returns: DIR>200 Compress Started Then proceeds to list progress i.e. Server: newserver - newsgroup" for each server and each group that has any previously downloaded headers in the spool files.y downloaded headers in the spool files.

Import NZB File

Command: FILE [\path\filename.ext]

Provide a .NZB filename and path. Newsbin will parse and load into the Post List.


200 OK

Get NBI Section

Command: GetSection [section <section>]

Newsbin 5 only Returns a section of the NBI. The basic format of a good response will always be: 200 Section List Follows contents of the section . So a command of the form: GetSection Servers might return data of the form: 200 Section List Follows NTLWorld Astraweb Astraweb_Europe Giganews Giganews2 Astraweb_Test If you type an invalid section name, then the response will be: 401 GetSection - Section not Found

Get NBI Variable

Command: GetVar [section.name]

Newsbin 5 only Returns a string that represents the configuration variable. Example:

"Getvar nh:priority" "Getvar nh:address" Returns:


Command: PAUSE [ON|OFF]

Pause downloads queued in the Download List. With Newsbin 4 the files are paused immediately. With Newsbin 5 each download thread is paused when it completes the current chunk it is working on so it can be several seconds before the pause takes full effect..


200 Download Paused 200 Download Resumed

Save Configuration

Commnad: SAVE

Newsbin 5 only Saves the configuration file. This would typically be used after using a series of SetVar commands to store or update values in the configuration file.


200 Config Saved

Set NBI Variable

Command: SetVar [section:name:value]

Newsbin 5 only Lets you set any individual value in the current Newsbin configuration (.NBI) file Example: "SetVar nh:address:test.newshosting.com"

You aren't limited to existing sections either. If you want to store your own variables in the NBI you can.

"SetVar Itimpi:saveinterval:50" "Save"

"GetVar Itimpi:saveinterval" The format of the results is: NNN Text\r\n value1\r\n value2\r\n ... .\r\n GetVar will only return one result, setvar returns nothing but the response.


Command: START

Newsbin 4.33B6/B8 only Same as hitting the start button. Starts header download in manual mode or starts header and file download in automatic mode. Works on all groups in the group list with a check mark next to it.




Command: STOP

Newsbin 4.33B6/B8 only Same as hitting the stop button. Stops and header downloads that is in progress. Does notaffect any file downloads.


200 Stop


Commnad: UPDATE [groupname]

Newsbin 5 only Updates the headers for all enabled groups if no groupname specified, and the specified group if groupname is given


200 Header Update Commencing


This is one of the new commands to remotely manage the your downloads.

Downloads Lock is to be used before making changes to the list, otherwise the index might change between performing List command and necessary actions. Lock also freezes the GUI until the Unlock command is performed.

Downloads Clear is used to clear the downloads list if you must.

Downloads Count is used to get a total count of unexpanded sets or files.

Downloads List # # is used to get the list of unexpanded sets or files. The first # is the lowest number to show, starting with 0. The second # is the highest number line to show, not to exceed the value of sets returned from the Count command minus 1 becuase the index starts at 0 (zero).

Downloads Unlock is used to unlock the list after making changes to list, and also unfreeze the Newsbin GUI.

More TCP commands are still planned for implementation. A list of proposed features can be read here or discussed here.

Change History

The following is the history of changes:

Date Version Change Description
July 2005 1.0 First Version by Itimpi (Copyright © 2005 David J Walker, used with permission)
October 2005 1.1 Major update following Newsbin 5.0 reaching General Release status
February 2011 2.0 Copy from Itimpi's original document. Begin brainstorming expanded functionality
Personal tools