Binkd User Guide


This document is the Binkd User Guide beta version. In other words, it's a draft of the work in progress. Don't assume this document to be error proof, both from conceptual and linguistic point of view. Any suggestions and corrections are highly appreciated. Mail them to Nick Soveiko, nsoveiko@doe.carleton.ca. The latest version of this document is available at http://www.doe.carleton.ca/~nsoveiko/fido/binkd/man/.

Current document revision 000630, current binkd version: 0.9.4.

Revision history:

010220
000630
-C command line option updated
000628
000525
major update: when binkd/0.9.3 was released about a month ago, I decided to hold on the documentation because 0.9.4 was already in the pipeline.
990917
fixed Slava Filimonov's email and mirror site addresses
990607
Binkp/1.0 description has been significantly updated with connection to it's submission to FTSC as a Fidonet Standard Proposal.
990316
inbound description updated w/respect to rename() implementation under *NIX.
990201
minor update in the links section.
990106
updated:
981013
updated Dima Maloff's email and his binkd page location
971127
bugfix: pid-file keyword was described as pid
971028
binkd/0.9.2 new features documented:
971008
flag and exec keywords descriptions updated with regard to wildcards
970911
changes:
970711
added: binlog and tzoff, send-if-pwd and kill-old-bsy keywords, -C command line option
970709
minor reviews;
970703
initial draft; primary review and first HTML version.


This document is (c) Copyright 1997-2000 Nick Soveiko.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts and no Back-Cover Texts.

A copy of the License can be obtained at http://www.fsf.org/copyleft/fdl.html or by writing to: Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111, USA.

This document is distributed in the hope that it will be useful, but without any warranty, without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.


 [Where?] Table of contents


 [What?] 0. Introduction

0.1. What is binkd?

Binkd (Binkley daemon) is a next generation Fidonet mailer designed exclusively to operate via TCP/IP networks. As a FTN-compatible internet daemon, it makes possible efficient utilization of TCP/IP protocol suite as a transport layer in FTN-based (Fido Technology Network) networks.

Binkd is a Bink-style-outbound (BSO) mailer. The reader is assumed to be familiar with this type of mailers. For a comprehensive discussion of BSO, please refer elsewhere. A good introductory reading on this matter is the regular BinkleyTerm documentation, file bt_user.doc, search for Idea #4. BinkleyTerm itself, Xenia, The Brake!(tm) are all examples of BSO mailers. FrontDoor is an example of mailer that does not support BSO. T-Mail has support for BSO, but it is turned off by default.

0.2. Distribution

Binkd is being developed and distributed under the terms of GNU public license. In short, it's freeware and it's sources are freely available. Development team is lead by Dima Maloff, maloff@corbina.net, http://www.corbina.net/~maloff/binkd/ and Pavel Gulchouck gul@gul.kiev.ua who did most of the development for 0.9.3+.

Binkd distribution sites:


 [Why?] 1. Binkd philosophy

1.1. Protocol

Binkd was designed for operation over a TCP/IP connection. A TCP/IP connection is quite different in many aspects from a direct modem connection:

So binkp protocol was born.

Binkp is the protocol that Binkd uses for establishing a session and transferring files. Comprehensive description of binkp can be found in binkp10.htm which should arrive alone with your binkd distribution.

The highlights are:

1.2. Clients and servers

Being a modern day internet daemon, binkd can handle several concurrent inbound and outbound connections. Client and server managers are initiated as separate processes after processing of configuration files upon startup.

Client manager reads the outbound directory, maintans outbound queue and starts a separate client for each attempt to establish an outbound session, up to maximum number of clients that may be specified in configuration file. Each client quits upon (either successful or not) termination of it's session. Client manager rescans outbound each time when the number of active clients reaches zero.

In a similar fashion, server manager monitors attempts to establish an inbound connection to the designated port and fires up a server process to handle an inbound session. Max number of servers can be specified in configuration file as well. When number of active servers reaches it's maximum, inbound connections are reset by the server manager after sending remote system a message that we are already running too many servers.

1.3. Mailer vs Filer

The main purpose of Binkd is to efficiently transmit files and interoperate with other software by means of simple and documented interfaces. And it does it's job way better than many other mailers (insert your favourite disclaimer here).

If you are looking for a swiss knife type of mailer that will also wake you up in the morning, make you a coffee and perform oral sex on you, you came to the wrong place. You have been warned. ;)


 [How?] 2. Installation

2.1. Binaries

2.1.1. OS/2, Win95 and WinNT

You can download precompiled executable files for these platforms.

There are two OS/2 ports. One is done for Watcom C compiler and the other one is for EMX GNU environment. For Watcom version (binkd2.*), as well as for Win95 (binkd95.*) and WinNT (binkdnt.*) you won't need anything else but a sample config file.

For the EMX version (binkd2e.*), you'll need EMX Runtime version 0.9d or later, available at Hobbes OS/2 archives. Follow instructions found inside emxrt.zip to install EMX Runtime.

2.1.2. Other platforms

Get latest Binkd sources, unpack the archive file and compile it for your platforms. It should not cause any major difficulties compiling for most *NIX flavours, as Binkd is developed keeping in mind this portability. However, if you are running system that does not have fork() and sockets or their equivalent (DOS is an example of such system), you're out of luck. Don't get me wrong - DOS port is not impossible, it even exists in a stripped down version (either single server or single client mode). My point is that if you're still running a system without sockets and fork(), it's time to think that life is too short for spending it in such a way.

Ports to the other platforms are encouraged and if you have a working binary, feel free to send me the file or link - I'll put it on the Web for our lazier colleagues.

2.2. Putting the things together


3. Synopsis

binkd [options] <config_file> [socket]
options
-i
run Binkd from inetd (OS/2 or *NIX only)
 [Warning!] Attention *NIX users: don't forget either to
  • comment out printq, conlog and percents from the config file
  • or include -q in the command line when running from inetd
binkd won't take care about this itself. Otherwise, your binkd console output will go to the 'net!

-q
"quet" mode, overruns printq, conlog and percents options in configuration file; handy to use in conjunction with the -i option

-c
start client manager only.

-C
Binkd running with this option will exit with return code 3 when configuration file is changed. Configuration file is checked every rescan-delay seconds and also on initiation of an incoming connection.

 [bug] binkd/OS2 v0.9.1 compiled for EMX environment will not quit until all active connections are closed.

 Note: 0.9.3+: All the *nix versions and OS/2 EMX port of binkd will just restart itself with the new config settings instead of exit(3)

 Note: 0.9.4+: All included files are also checked now, even when run with -c option.

-p
start client manager only, make polls, quit if the queue seems to be empty after the next rescan

 [bug] binkd v0.9.0 actually exits after making one attempt to poll each node in the queue - it's a bug.

-s
start servmgr only

-P ftn_addr
create an immediate poll for a node; ftn_addr can be an incomplete address relative to our own primary address; if IP address of ftn_addr is not known, it will be obtained by constructing a FQDN and resolving it via DNS.
Example: binkd -P .1 -p binkd.cfg will create a poll for the first point of your bossnode.

-i
install binkd as service (WinNT only)

-u
uninstall binkd as service (WinNT only)

config_file
config_file is the binkd configuration file containing directives describing binkd behaviour. Refer to section 4, Configuration file for more information.

socket (OS/2 only)
by means of the socket parameter you can specify which socket binkd should use (OS/2 inetd can be configured to do this)

4. Configuration file

General format

Configuration file contains a number of keywords that determine Binkd behaviour. Anything after the '#' character and up to the end of the line is treated as a comment. All keywords are case insensitive. Maximum length of a single configuration file line is 1024 characters.

Most keywords are followed by parameters. Parameters can be separated from each other as well as from the keyword by space and/or tabulation character(s). If a parameter itself has to contain spaces and/or tabulations inside, it has to be enclosed in double quotation marks. See exec keyword for examples.

Any keyword can occur in configuration file as many times as you want. If that is the case, a keyword describing a list will append it's value to the list and a keyword describing a single value redefines the value. Address is an example of a keyword describing a list and timeout is an example of a keyword describing a single value.

Most keywords are self-explanatory and are described in the sample config file included with your distribution.

Environment variables

Binkd can recognize environment variables in configuration file and obtain their values from the operating system environment. Environment variables included in config file should be enclosed by a single percent character '%' on each side. If you need to use a percent character literally, escape it with another '%'. Environment variable name can not contain spaces and it's length can not exceed 256 characters.

Example:

domain fidonet %OUTBOUND% 2

If the value of OUTBOUND is equal to /var/spool/fido/outbound, then the above statement is equivalent to

domain fidonet /var/spool/fido/outbound 2

Keywords used in configuration file

Domain

Purpose: domain keyword defines FTN domains for your system, aliases for domains (optional), default zonenumber and outbound directory for each domain.

Syntax:

domain {<name> <main-outbound> <default-zone> | <new-name> alias-for <name>}

 [Warning!] Note: if your file system uses backslashes as path separators, each backslash should be escaped with another one.

main_outbound can not contain a dot in the directory name.

If you are a member of only one FTN network, you can just specify your zone number as default_zone here and skip the examples.

default_zone is the number that will not be appended to your outbound directory extension (see examples 2-4).


Examples:

Example 1 (general):
domain fidonet c:\\bbs\\outbound 2
domain pivanet /home/binkd/pivanet 999
domain fido alias-for fidonet
domain fidonet.org alias-for fidonet

Example 1 above defines outbound for fidonet zone 2 and pivanet zone 999. It also specifies aliases fido and fidonet.org for the fidonet domains.


Example 2:

You are a member of networks operating in zones 1, 2, 3, 4, 5 and 16. Your mail processing software (echotosser, netmail packer, etc.) is configured to use zone 2 as a default and your outbound tree structure looks like this:

c:\bbs\out.001
c:\bbs\out
c:\bbs\out.003
c:\bbs\out.004
c:\bbs\out.005
c:\bbs\out.006
c:\bbs\out.010
then, your binkd configuration would look like:
domain fidonet c:\\bbs\\out 2
domain alt_net c:\\bbs\\out 2

Example 3:

Your addresses are the same as in Example 2, but your mail processing software is aware of 5d addresses and your outbound looks like

c:\bbs\out.001
c:\bbs\out
c:\bbs\out.003
c:\bbs\out.004
c:\bbs\out.005
c:\bbs\out.006
c:\bbs\alt_net.010
In this case, your binkd configuration should look like
domain fidonet c:\\bbs\\out 2
domain alt_net c:\\bbs\\alt_net 2

Example 4:

Your addresses are the same as in Example 2, but your mail processing software is aware of 5d addresses and is smart enough to assign a separate default outbound directory for each domain:

c:\bbs\out.001
c:\bbs\out
c:\bbs\out.003
c:\bbs\out.004
c:\bbs\out.005
c:\bbs\out.006
c:\bbs\alt_net
In this case, your binkd configuration would look like this:
domain fidonet c:\\bbs\\out 2
domain alt_net c:\\bbs\\alt_net 16

Address

Purpose: address keywords define 4D or 5D addresses of your system. First address in the list is assumed to be primary address always.

Syntax:

address <addr1> [addr2 ... [addrn]]

Example:

address 2:5047/13@fidonet 2:5020/79.31@fidonet

Sysname, location, sysop and nodeinfo

Purpose: these keywords provide description of your system.

Syntax:

self-explanatory.

Examples:

sysname "Beercan"
location "Magadan, Russia"
sysop "Dima Maloff"
nodeinfo 115200,TCP,BINKP

Iport and oport

Purpose: iport and oport keywords define TCP port number for inbound and outbound connections. Default value is 24554.

Syntax:

iport { <port_number> | <service_name> }

Examples:

iport 24554
oport 60179
iport binkp
oport binkp

Oblksize

Purpose: oblksize keyword defines maximum block size in bytes for outbound transmission. Default value is 4096.

Syntax:

oblksize <block_size>

Example:

oblksize 4096

Timeout

Purpose: timeout keyword defines transmission timeout in seconds before a session is aborted. Default value: 60. See also connect-timeout.

Syntax:

timeout <value>

Example:

timeout 240

Connect-timeout

Purpose: connect-timeout keyword defines timeout in seconds before an unsuccessful attempt to establish a TCP/IP connection is aborted. A value of 0 means not to perform this check and rely on TCP/IP stack timeouts. Default value: 0. See also: timeout

 [bug] This option does not work in multithreaded binkd ports.

Syntax:

connect-timeout <value>

Example:

connect-timeout 60

Call-delay and rescan-delay

Purpose: call-delay keyword defines delay in seconds before an outbound call is made. Rescan-delay keyword defines delay in seconds before rescan of the outbound. Default value is 60 seconds each.

Syntax:

self-explanatory.

Examples:

call-delay 60
rescan-delay 60

Maxservers and maxclients

Purpose: maxservers and maxclients keywords define maximum number of servers and clients (see section 1.2, Clients and servers). Default value is 100 each. Use as many as you need and your system and internet connection can handle.

Example:

maxservers 2
maxclients 2

Try and hold

Purpose: these keywords together with timeout control handling of systems with particularly bad and/or non-permanent IP connections. Binkd will try to call a node N times, if failed, it will hold the node for S seconds. This feature is off by default.

Syntax:

try <N>
hold <S>

Examples:

try 10
hold 600

Hold-skipped

Purpose: hold-skipped keyword defines delay in seconds before next attempt is made to poll a node that requested a file to be skipped. That's useful to avoid unnecessary polls to a temporarily overloaded system. Default value is 3600 (one hour).

Syntax:

hold-skipped <S>

Example:

hold-skipped 3600

Log and loglevel

Purpose: these keywords control logging of binkd activity. Log defines path and name for the log file and loglevel defines detail level of logging. loglevel 0 produces no output. loglevel 4 is recommended for day-to-day operations. Try loglevel 5 if you're really curious. Anything above this is useful for debugging only and produces lots of logs: watch your disk space!

 [Warning!] Note: if your file system uses backslashes as path separators, each backslash should be escaped with another one.

 Note: 0.9.3+:: loglevel now also affects messages sent to syslog facility.

Syntax:

log [<path><separator>]<log_file>
loglevel <value>

Examples:

log binkd.log
loglevel 4

Conlog

Purpose: same as loglevel, but for your console output. Default is 0, so uncomment it if you want anything to show up on your console. On the contrary, comment it out if you're running binkd as a daemon.


Binlog and tzoff

Purpose: binlog keyword specifies full filename to the binary log file in T-Mail-compatible format.

 [bug] Most compilers under DOS-derived systems return local time as a value of time(). Even worse, this value is inconsistent from one compiler to another and from one library to another, so that it's quite possible that binkd and some T-Mail log analyser will be using different implementations of time() and output inconsistent timing.

tzoff keyword provides a workaround for this bug. You can specify an arbitrary time offset (in seconds) in order to force both programs to give same time values. This keyword affects time offset for binary logging only specified by binlog and/or fdinhist and fdouthist

 [Warning!] Note: if your file system uses backslashes as path separators, each backslash should be escaped with another one.

Syntax:

binlog [<path><separator>]<log_file>
tzoff <value>

Examples:

binlog o:\\log\\binkd.sts
tzoff 10800

Fdinhist and fdouthist

Purpose: fdinhist and fdouthist keywords specify complete filenames to the inbound and outbound binary history files with FrontDoor and Bink/+ compatible format.

 [Warning!] Note: if your file system uses backslashes as path separators, each backslash should be escaped with another one.

Syntax:

fdinhist [<path><separator>]<log_file>
fdouthist [<path><separator>]<log_file>

Example:

fdinhist o:\\log\\in.his
fdouthist /var/spool/fnet/logs/outbound.history

Syslog

Purpose: syslog keyword forces binkd to use syslog facility for logging on compatible systems. Use only if compiled with -DHAVE_VSYSLOG and -DHAVE_FACILITYNAMES. You might not want to use this unless you have administrator privileges. man syslogd for more details.

Example:

syslog local0

Pid-file

Purpose: pid-file keyword instructs binkd to log it's pid. You probably won't want to uncomment this keyword unless you understand what this is for and what you are doing.

Example:

pid-file /var/run/binkd.pid

Ftrans

Purpose: ftrans defines path translation rules for paths listed in *.?lo files. It comes really handy when you run binkd and tosser on different machines. Use as many ftranses as you want.

 [Warning!] Note: if a file system involved here uses backslashes as path separators, each backslash should be escaped with another one.

Syntax:

ftrans <search_for> <replace_with>

Examples:

ftrans "D:\\fido\\outbound" "/var/spool/fido/outb"
ftrans "\\" "/"             # replace all backslashes with slashes

Inbound and inbound-nonsecure

Purpose: these keywords define inbound directories for password protected and regular sessions. see also temp-inbound

 [Warning!] Note: if your file system uses backslashes as path separators, each backslash should be escaped with another one.

 Note: 0.9.3+: renaming of files in inbound is handled by new code which does not rely on link()/unlink() any more. Should solve the described below problem with various filesystems.

 [Warning!] Note for *NIX users: Because *NIX rename() overwrites destination file without warning, binkd uses link() and unlink() to rename received files. Therefore, your inbound filesystem should have correct implementation of link() and unlink() (FAT does not!). Otherwise, binkd won't be able to rename received files into their real names. Same rule also applies to inbound-nonsecure.

Syntax:

inbound <path>
inbound-nonsecure <path>

Examples:

inbound c:\\bbs\\inbound
inbound-nonsecure c:\\bbs\\inbound\\unknown

Temp-inbound

Purpose: this keyword allows to specify separate directory for binkd's temporary files. When binkd is receiving a file, it creates a header file foobar.hr which contains real filename, length and timestamp used to identify the file. File data is stored in foobar.dt. After all of the file data has been received, it will rename foobar.dt to it's realname and delete foobar.hr. If temp-inbound is not defined, *.hr/*.dt files will be stored in corresponding inbound directories.

 Note: 0.9.3+: binkd used to acknowledge a file as soon as it was completely received. Now it will do so only after the file was successfully renaimed and placed in proper inbound directory.

 [Warning!] Note: if your file system uses backslashes as path separators, each backslash should be escaped with another one.

Syntax:

temp-inbound <path>

Examples:

temp-inbound c:\\bbs\\inbound\\incomplete

Send-if-pwd

Purpose: send-if-pwd keyword defines binkd behaviour in case of unsecure inbound session. This keyword forces binkd to send nothing to the remote system during an unsecure session.

Syntax

send-if-pwd

Minfree and minfree-nonsecure

Purpose: minfree keyword defines minimum disk space in kbytes that should be kept free on the filesystem that carries our inbound. minfree-nonsecure does the same thing for nonsecure inbound. Binkd will try to keep the specified amount of free space by skipping inbound files during sessions. See also hold-skipped for handling this situation on the remote side.

Syntax:

minfree <value>
minfree-nonsecure <value>

Examples:

minfree 2048
minfree-nonsecure 2048

Kill-dup-partial-files

Purpose: this keyword instructs binkd to kill partially received files when trying to receive another file with the same name, but different size and/or timestamp. Default action is to retain partially received files in inbound dir as a pair of *.dt (data) / *.hr (header) files indefinitely. See also kill-old-partial-files.

Syntax:

kill-dup-partial-files

Kill-old-partial-files

Purpose: kill-old-partial-files keyword instructs binkd to unconditionally kill all partial files residing in inbound that are older than NNN seconds. This feature is off by default.

 Note: 0.9.3+: binkd will now acknowledge a received file only after it has been successfully renamed to it's realname. In other words, it's now safe to delete all *.hr/*.dt files that are reasonably old.

Syntax:

kill-old-partial-files <NNN>

Example:

kill-old-partial-files 86400

Kill-old-bsy

Purpose: kill-old-bsy keyword instructs binkd to remove any *.bsy and *.csy files residing in your outbound for more than NNN seconds and that probably were accidentally left there after a system crash. Binkd touches it's own active *.bsy and *.csy files every 5 minutes during the session. So it will be a safe move to set this parameter to 43200 (12 hours) on almost any system (unless your other mailers have sessions lasting for 12 hours straight). This feature is off by default.

What will happen if you set this for too low value: some active *.bsy and *.csy files might be killed that will result in a redundant session to be initiated with the remote which session will be rejected with No common AKAs or all AKAs are busy error message.

What will happen if you set this for too hight value: binkd will think that a session with the remote is in progress, make no attempt to call it and reject incoming sessions with the error message quoted above.

Syntax:

kill-old-bsy <NNN>

Example:

kill-old-bsy 43200

Flag

Purpose: after receiving a file that fits one of the specified wildcards, binkd will create corresponding flag. This allows you to fire up your tosser on the fly. Flag will be created upon session termination, unless it's preceded with !, in which case it will be created upon receiving a file.

 [Warning!] Note: if your file system uses backslashes as path separators, each backslash in the flag file name should be escaped with another one. Each backslash in the wildcard list name should be twice escaped, once for the binkd configuration file parser and another one for the wildcard parser. In other words, replace each backslash in a wildcard with four backslashes.

 [Warning!] Note: a wildcard is compared against complete path to the file. As so, a wilcard starting with a * refers to a file, matching the wildcard and residing in any subdirectory. In case when no reference (neither explicit path, nor wildcard starts with a *) to path is made in the wildcard, the result will depend upon your filesystem implementation (not recommended).

Syntax:

flag [!]<flag> <wildcard_list>

Examples:

Example 1

Create flag mail.now immediately after any .pkt file is received to any directory:

flag !mail.now *.pkt
Example 2

Create flag toss.now after inbound arcmail session:

flag toss.now *.su? *.mo? *.tu? *.we? *.th? *.fr? *.sa?
Example 3

Create flag y:\fido\flags\ndl_sec.now after a session, during which any file matching net50*.* was received to directory z:\fido\inbound\secure\ :

flag y:\\fido\\flags\\ndl_sec.now z:\\\\fido\\\\inbound\\\\secure\\\\net50*.*

On *NIX systems this may look like

flag /var/fido/flags/ndl_sec.now /var/spool/inbound/secure/net50*
Example 4

Create flag ndl_any.now after a session, during which any file matching net50*.* was received to any directory:

flag ndl_any.now *\\\\net50*.*

Exec

Purpose: run an external program when a file satisfying the wildcards is received.

 [Warning!] Note: if your file system uses backslashes as path separators, each backslash in the command should be escaped by another one. Each backslash in the filemask should be twice escaped, once for the binkd configuration file parser and another one for the wildcard parser. In other words, replace each backslash in the path with four backslashes.

 [Warning!] Note: a wildcard is compared against complete path to the file. As so, a wilcard starting with a * refers to a file, matching the wildcard and residing in any subdirectory. In case when no reference (neither explicit path, nor wildcard starts with a *) to path is made in the wildcard, the result will depend upon your filesystem implementation (not recommended).

Syntax:

exec [!]<commandline> <filemask>

An exclamation mark preceding the <commandline> indicates an immedieate event, such command will be executed immediately after a file matching the <filemask> is received. Otherwise, requests will be buffered and executed later during the session (after the next file transmission batch is over).

<commandline> can include macros to pass parameters to the external processes:

*S
is substituted with Standard Request Information File, see !srif.txt for more details
*F
is substituted with the name of the file that triggered exec
*N
same as *F, but on win32 platform is substituted for short filename (8.3 mangled)
*H
is substituted with the FQDN or IP address of the remote
*A
is substituted with the primary FTN address of the remote (use *A0 for primary and *A1...*A9 for AKAs if you need to access different AKAs)
*L
is substituted with 1 if remote is listed in our config, 0 otherwise
*P
is substituted with 1 if session is password protected, 0 otherwise

Examples:

exec "my-freq-processor.exe /options *S" *.req
exec "my-pkt-unpacker.exe /options *S" *.pkt
exec "/sbin/my-coffee-maker -double -au_lait" /var/spool/coffee/*

See also examples for the flag keyword.


Include

Purpose: include another file as a part of current config. Nested includes are allowed (up to 8 inclusion levels). See also: passwords

 [Warning!] Note: if your file system uses backslashes as path separators, each backslash should be escaped with another one.

Syntax:

include [<path><separator>]<include_file> 

Examples:

include foo.bar
include c:\\bbs\\nodelist\\addresses.binkd
include /usr/local/binkd/config/common

Node

Purpose: node keyword defines a link for your system. Binkd does not use conventional nodelist as it contains very little useful information for it. So, you must describe each node you want to call with the help of a node keyword.

A dash as a field value indicates that the field is empty. All non-empty fields will redefine values specified for the same node earlier in configuration file. Together with the include keyword that makes an extremely powerful tool. You can include a public list of binkp-capable nodes in your configuration file and redefine some of the parameters (password, fileboxes, flavour, etc.) for your permanent links later in the master config file or even in a separate file each.

Syntax:

node [ftn_addr [options] [{hostlist|-} [{password|-} [flavour [{obox|-} [{ibox|-}]]]]]
ftn_addr

Format:
[zone:]net/]node[.point][@domain]

Omitted parts of the address field (i.e. zone, net, point and/or domain) are assumed to be the same as for our primary address, except for the point part, which by default is 0 (bossnode).

options

options options is a list of protocol options that are enabled and/or enforced for this particular node. Options in the list are separated by one or more spaces. Each option is preceded by a dash.

-nr
stands for Non Reliable link mode, this works only on outbound calls with another mailer supporting this option (e.g. binkd/0.9+). It forces binkd to turn off the protocol optimisation that is based on assumption that TCP/IP connections are rarely aborted. Essentially, it sets file window size to one and mandates desired file offset to be requested by the transmitting side, so that there is protocol resync at the beginning of transmission of each file. The option solves the only problem with binkd having not enough time to start receiving file from non-zero offset before IP link is down. So don't use it unless you have this problem -- it's really not effective.

-nd
stands for No Dupes link mode. This mode is a further extension of the NR mode, so -nd option supercedes -nr option. In NR mode binkd will rename an inbound file1 to it's realname only after receiving an offset request for the next file, thus effectively making shure that the remote have deemed file1 to be successfully transmitted and will not attempt to do so again. Links status is stored in a outbound/*.stc file, so the session can be resumed even after reboot. This option will work only for outbound connections and only if the remote supports it (0.9.3).

-md
this option forces binkd to use CRAM-MD5 authentication on outbound session. If the remote doesn't support CRAM-MD5, session will be aborted without falling back to plain text authentication. (0.9.4)

 [Warning!] Enable this option only if you are absolutely sure that your link supports CRAM-MD5 at all times.

-ip
this option restricts IP address of the remote during an inbound session to one that can be derived from the hostlist. Otherwise, binkd will abort the session. (0.9.4)

 [Warning!] Use with caution, especially when operating binkd in unattended mode. If your link's IP address is hardcoded in the hostlist as the only means of obtaining it, it can easily break communication until the problem is discovered. This option obviously makes little sense if your link uses a dynamic IP address.

hostlist

Hostlist is a list of semicolon separated internet_address[:port] expressions. Default value for the port is our own oport. An internet_address can be in one of the following formats:

IP address, e.g. 123.45.67.89
binkd will attempt to connect this IP address directly
host address, e.g. fidohost
binkd will attempt to resolve this address in your default Internet domain
fully qualified domain address, e.g. binkd.my.domain.org
binkd will attempt to resolve this FQDN according to your current /etc/resolv.conf settings or whatever it is called on your platform
an asterisk character '*'
binkd will make a FQDN from the node's FTN address according to the rule: 1:2/3[.4] --> [p4.]f3.n2.z1.domain.name, where domain.name is specified by the root-domain keyword, and attempt to resolve it for an IP address

A binkd client starts with the leftmost hostlist entry, tries to obtain valid values for IP address and port number from it and connect to this IP address on the given port. If any of the following applies:

it will proceed to the next hostlist entry and repeat the procedure. If a session can not be successfully completed for all of the hostlis entries, the client reports failure and dies. The next client fired by the clientmanager for the same entry in outbound queue will make a new attempt according to the same procedure, up to a maximum of try N attempts.
password

password field specifies password for the remote system. See also passwords.

 [Warning!] binkp/1.0 makes provision for only one password to be transmitted during a session. So, you can not specify different passwords for different addresses of the remote. Binkd passwords are case sensitive.

 Note: 0.9.4+: Prior to version 0.9.4, binkd have supported only one authentication mechanism: sending plain text password across the network. This is pretty much a legacy of the dialup era when you could be at least remotely positive about difficulties of eavesdropping on a modem connection. Starting with ver. 0.9.4, binkd also supports CRAM-MD5 (Challenge-Response Authentication Mechanism with MD5 digests) authentication mechanism that avoids clear text transmission of session passwords.

An answering system generates a chunk of data called challenge that is unique to each session. Challenge is sent to the calling system during session setup stage. Calling system computes an MD5 digest of the challenge using session password as a secret key. This digest is sent in response to the challenge. Answering side also computes the digest and if they match, remote can be safely assumed to be the system it pretends to be. If the remote doesn't support CRAM-MD5, binkd will fall back to plain text authentication. See also -md link option.

Flavour

flavour is a single character, one of i(mmediate), c(rash), d(irect), -(none), h(old); and is the flavour for the outbound filebox (obox).

Fileboxes
Filebox is a "private" in/outbound directory specified for a particular node. Whenever you define an outbox for a system, any file that appears in that outbox will be transmitted to that system during the next session according to the specified flavour of the filebox. Binkd sends from outbox all non-dir entries not matching the .* wildcard and after receiving a proper acknowledgement from the remote, tries to unlink these directory entries.

 [Warning!] Note: if your file system uses backslashes as path separators, each backslash should be escaped with another one.

 [Noway!] EVERY TIME YOU PUT A FILE INTO AN OUTBOX MAKE SHURE THAT BINKD WILL BE ABLE TO UNLINK IT. Otherwise, the session will never end.

Anything received from a system with an inbox defined will be stored in this inbox. Default value for inbox is inbound or inbound-nonsecure depending on the value of the password field, i.e. default is no inbound filebox.

Examples:

node 888 - -       # really minimalistic description
node 9999/888 host.domain.com super_password
node 777:9999/888.66@nifiganet 123.45.67.89:666 -
node 777:9999/888.66@nifiganet - another_super_password # will override pwd
                                                        # field for the above
node 5047/999 * - i c:\\bbs\\boxes\\to999 c:\\bbs\\boxes\\from999
node 2:5020/118 *;comp.chem.msu.su;158.250.32.97:binkp;158.250.32.40:24554 -
node 2:5020/52 -md -ip * password

Root-domain

Purpose: root-domain keyword defines the default domain name which binkd will use while making fully qualified domain names from FTN addresses.

Syntax:

root-domain domain_name

Example:

root-domain fidonet.net

Filebox, brakebox and deletebox

Purpose: filebox defines directory for T-Mail-style outbound fileboxes, brakebox defines directory for The Brake! -style fileboxes. deletebox tells binkd to delete empty fileboxes in both these styles.

 [Warning!] Note: if your file system uses backslashes as path separators, each backslash should be escaped with another one.

Syntax:

filebox path
brakebox path
deletebox

Example:

filebox c:\\fido\\t-mail\\boxes
brakebox c:\\fido\\thebrake!\\outbound
deletebox

Prescan

Purpose: this keyword forces binkd to rescan outbound and relevant fileboxes at session startup stage and send traffic prognosis in Argus-compatible format.

Syntax:

prescan

Proxy

Purpose: this keyword allows binkd to make outbound connections via http/https proxy server (e.g. squid). The server settings must allow establishing TCP/IP connections to the desired host/port. You can specify optional username/password if proxy requires HTTP/1.1 authentication (RFC2068).

Syntax:

proxy proxy_address[:port][/user/password]

where:

proxy_address and port
are FQDN (or IP address) and port number of the http(s) proxy; default port is 3128
user and password
are your username and password for proxy authentication

Examples:

proxy 192.168.0.3:3128

proxy proxy 192.168.0.3:3128/joe/password

Socks

Purpose: this keyword allows you to specify socks4/socks5 proxy server for outbound connections. See RFC1928/RFC1929 for more info on socks5.

Syntax:

socks socks_address[:port][/[user/password]]

where:

socks_address and port
are FQDN (IP address) and port number of the socks server; default port number is 1080
user and password
are your username and password for authentication at the socks server; if user and password are not specified and the leading slash is omitted, binkd will assume socks4 server; socks5 otherwise

Examples:

# socks4 proxy
socks 192.168.0.3:1080

# socks5 proxy without authorization
socks 192.168.0.3:1080/

# socks5 proxy with username/password
socks 192.168.0.3:1080/user/password

defnode

Purpose: this keyword specifies default node characteristics. If defined in config file, binkd will assign these characteristics to all the nodes that are not explicitly defined. This keyword has the same syntax as the node keyword except for the absent ftn_addr field. If defnode is defined in config file, binkd will try to send all the mail found in outbound by applying these default node characteristics. See also root-domain .

Example:

defnode -nd *

Passwords

Purpose: this keyword can specify a file with session passwords in T-Mail format.

 [Warning!] Note: if your file system uses backslashes as path separators, each backslash should be escaped with another one.

Syntax:

passwords [<path><separator>]<passwords_file>

Examples:

passwords foo.bar
passwords c:\\fido\\t-mail\\password.lst

 [FAQ] 5. Frequently Asked Questions and Troubleshooting

5.1 No screen output

[Q]
I have installed binkd, but when I start it all I get is a blank screen. What's wrong?
[A]
By default, binkd will run in quiet mode producing no console output. Uncomment printq, conlog and percents from the config file and make sure you do not have -q option in your command line.

5.2 Binkd doesn't poll my bossnode

[Q]
I've installed and configured binkd, but it doesn't poll my bossnode. What's wrong?
[A]
Switch your mail processing software (echoprocessor, mail packer) to Bink Style Outbound (BSO) mode. Binkd won't deal with arcmail-attach outbound (as, probably, your T-Mail or FrontDoor does).

5.3 Binkd doesn't call particular node

[Q]
My binkd suddenly stopped calling one of the nodes for which there's mail. What's wrong?
[A]
Check your outbound directory and see if there's a *.?sy file for this node. Probably, there is one. Kill it. Some people even prefer to kill all the outbound/*.?sy files automatically from time to time, see kill-old-bsy keyword description.

5.4 Binkd/Linux running out of servers

[Q]
I'm running BinkD under Linux and old servers are staying in zombie mode instead of killing themselves... It causes that after maxservers number of servers has been started, no more connections are allowed and it keeps refusing all new inbound calls. What do I do?
[A]
1) Upgrade to version 0.8.8 or later.
2) Add -DSYSVSIGNALS parameter to the *nix Makefile.
3) Recompile.

5.5 Messy console/log output

[Q]
How do I get rid of the messy output produced by multiple concurrent sessions?
[A]
You can run several instances of binkd at the same time, each one with different command line parameters, i.e. with different config settings. Set maxservers and maxclients parameters and/or use -c and -s commandline options so that each instance is doing only one inbound or outbound session. This however will significantly increase your system load. Binkd was not designed to operate like this, but is not known to cause any problems either.

5.6 Log analysis tools

[Q]
Is there a log analyzer for binkd logfiles?
[A]
A good question. ;)

Binkd is portable, so a log analyzer program should also be portable. Regular grep, awk and other tools exist for most platforms and are quite handy to do such a job. Use them:

5.7 File requests

[Q]
Does binkd support file requests?
[A]
In short: yes, it does.

5.8 Tosser runs for every mail packet received

[Q]
I am using exec keyword to run my echoprocessor. But the tosser starts every time a mail bundle is received, not after the session. How do I specify that all the received mail is to be processed at once?
[A]
exec statement is executed each time a file matching the filemask is received. So far, the only way to process mail after the session is to create flags when mail is received and analyze these flags by an external script. Flags can be created either immediately or after session.

5.9 Binkd doesn't exit when run with -p option

[Q]
I am running binkd with -p command line option, but after a successful session it doesn't exit, so I have to press Ctrl-C. What's wrong?
[A]
binkd will exit whenever it will determine that the outbound queue is empty, i.e. has no entries that are not on hold. After the session it will wait rescan-delay seconds, rescan the outbound and exit only if it's empty.

6. Binkd-related resources on the 'net


7. Acknowledgements etc...

All trademarks are copyrights of their respective owners, blah, blah, blah...

Thanks to Department of Electronics for providing web space for this project.

Thanks to Dima Maloff, without whom...


The End


Valid HTML 3.2! [Content enhanced] [Lynx enhanced] binkd now!