![[Where?]](gif/signpost.gif){kind=small}
Table of contentsThis 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 errorproof, 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/binkd.man.html.
Current document revision 970711, current binkd version: 0.9.1.
(c) 1997 Nick Soveiko
Table of contents
0. IntroductionBinkd (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 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.
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 (2:5047/13), maloff@tts.magadan.ru, http://www.magadan.su/~maloff/binkd/.
![[YinYang]](gif/yin_yang.gif){kind=small}
1. Binkd philosophyBinkd was designed for operating 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 protocol.txt included with your distribution (so far it's in Russian only).
The highlights are:
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 then reads the outbound directory, manages 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 dies upon termination of it's session, whether successfully or not. Client manager rescans outbound 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 to handle an inbound session. Max number of servers can be specified in config 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.
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 for you, you came to a wrong place. You have been warned. ;)
![[Onramp]](gif/onramp1.gif)
2. InstallationYou can download precompiled executable files for these platforms.
There are two OS/2 ports, however. One is done for Watcom C compiler and the other 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.9c or later. ftp://hobbes.nmsu.edu/pub/os2/unix/emx09c/ used to be the primary distribution site for the EMX software. However, as of the time of this document, there seems to be a major restructuring of the Hobbes archives and EMX Runtime is not available from there. In the meanwhile, you can get EMX Runtime (emxrt.zip) from the Hobbes mirror at http://www.cdrom.com/pub/hobbes/emx09c/. Follow instructions found inside emxrt.zip to install EMX Runtime.
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. Ports to 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.
![[Tag]](gif/tag.gif){kind=small}
3. Synopsisbinkd [options] <config_file> [socket]
![[Warning!]](gif/warning.gif){kind=small}
Attention *NIX users: don't forget either to
![[bug]](gif/bug.gif){kind=small}
binkd/OS2 compiled for EMX environment will not quit until all active connections are closed.
binkd v0.9.0 actually exits
after making one attempt to poll each node in the queue - it's a
bug.
![[Paper pile]](gif/doc02.gif){kind=small}
4. Configuration fileConfiguration file contains a number of keywords that determine Binkd behaviour. Anything after '#' character and up to the end of the line is treated as a comment. All keywords are case insensitive.
Any keyword can occure 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 describinng 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 encluded with your distribution.
Purpose: domain keyword defines FTN domains for your system, aliases for domains (optional), default zonenumber and outbound directory for each domain.
domain {<name> <main-outbound> <default-zone> | <new-name> alias-for <name>}
Note: if your file system uses backslashes as path separators,
each backslash should be escaped with another one.
main_outboundcan 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).
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.
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.010then, your binkd configuration would look like:
domain fidonet c:\\bbs\\out 2 domain alt_net c:\\bbs\\out 2
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.010In this case, your binkd configuration should look like
domain fidonet c:\\bbs\\out 2 domain alt_net c:\\bbs\\alt_net 2
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_netIn this case, your binkd configuration would look like this:
domain fidonet c:\\bbs\\out 2 domain alt_net c:\\bbs\\alt_net 16
Purpose: address keywords define 4D or 5D addresses of your system. First address in the list is assumed to be primary address always.
address <addr1> [addr2 ... [addrn]]
address 2:5047/13@fidonet 2:5020/79.31@fidonet
Purpose: these keywords provide description of your system.
sysname "Beercan" location "Magadan, Russia" sysop "Dima Maloff" nodeinfo 115200,TCP,BINKP
Purpose: iport and oport keywords define TCP port number for inbound and outbound connections. Default value is 24554.
iport { <port_number> | <service_name> }
iport 24554 oport 60179 iport binkp oport binkp
Purpose: oblksize keyword defines maximum block size in bytes for outbound transmission. Default value is 4096.
oblksize <block_size>
oblksize 4096
Purpose: timeout keyword defines transmission timeout in seconds before a session is aborted. Default value: 60.
timeout <value>
timeout 240
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.
call-delay 60 rescan-delay 60
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.
maxservers 2 maxclients 2
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.
try <N> hold <S>
try 10 hold 600
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).
hold-skipped <S>
hold-skipped 3600
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 op[erations. Try loglevel 5 if you're really curious. Anything above this is useful for debugging only and produces lots of logs: watch your diskspace!
Note: if your file system uses backslashes as path separators, each
backslash should be escaped with another one.
log [<path><separator>]<log_file> loglevel <value>
log binkd.log loglevel 4
Purpose: same as loglevel, but for your console output. Default is 0, so uncomment it if you want anything to show up on your comsole. On the contrary, comment it out if you're running binkd as a daemon.
Purpose: binlog keyword specifies full filename to the binary log file in T-Mail-compatible format.
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.
Note: if your file system uses backslashes as path
separators, each backslash should be escaped with another one.
binlog [<path><separator>]<log_file> tzoff <value>
binlog o:\\log\\binkd.sts tzoff 10800
Purpose: syslog keyword forces binkd to use syslog for logging on compatible systems. Use only if compiled with -DHAVE_VSYSLOG and -DHAVE_FACILITYNAMES. You probably won't want to uncomment this keyword unless you are a *NIX sysadmin.
syslog local0
Purpose: pid keyword instructs binkd to log it's pid. You probably won't want to uncomment this keyword unless you are a *NIX sysadmin.
pid-file /var/run/binkd.pid
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.
Note: if a file system involved here uses backslashes as path separators,
each backslash should be escaped with another one.
ftrans <search_for> <replace_with>
ftrans "D:\\fido\\outbound" "/var/spool/fido/outb" ftrans "\\" "/" # replace all backslashes with slashes
Purpose: these keywords define inbound directories for password protected and regular sessions.
Note: if your file system uses backslashes as path separators, each
backslash should be escaped with another one.
inbound <path> inbound-nonsecure <path>
inbound c:\\bbs\\inbound inbound-nonsecure c:\\bbs\\inbound\\unknown
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.
send-if-pwd
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.
minfree <value> minfree-nonsecure <value>
minfree 2048 minfree-nonsecure 2048
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 undefinitely. See also kill-old-partial-files.
kill-dup-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.
kill-old-partial-files <NNN>
kill-old-partial-files 86400
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 always touches it's active *.bsy and *.csy files during the session, so it will be a safe move to set this to 43200 (12 hours) on almost any system (you don't have sessions lasting for 12 hours straight, d'ya?). 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.
kill-old-bsy <NNN>
kill-old-bsy 43200
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.
Note: if your file system uses backslashes as path
separators, each
backslash should be escaped with another one.
flag [!]<flag> <wildcard_list>
flag !mail.now *.pkt flag toss.now *.su? *.mo? *.tu? *.we? *.th? *.fr? *.sa?
Purpose: run an external program when a file satisfying the wildcards is received. The "*S" macro in commandline is substituted with Standard Request Information File, see !srif.txt for more details. This allows you to run an external file request processor (besides zillions of other possibilities).
exec <commandline> <filemask>
exec "my-freq-processor.exe /options *S" *.req exec "my-pkt-unpacker.exe /options *S" *.pkt
Purpose: include another file as a part of current config. Nested includes are allowed (up to 8 inclusion levels).
Note: if your file system uses backslashes as path separators, each
backslash should be escaped with another one.
include [<path><separator>]<include_file>
include foo.bar include c:\\bbs\\nodelist\\addresses.binkd include /usr/local/binkd/config/common
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 links later in the config or even in separate file each.
Incomplete parts of the address field are assumed to be the same as for our primary address, except for point, which by default is 0 (bossnode).
Filebox is a "private" in/outbound directory specified for a particular node. Whenever you define an outbox for a system, any file that appers in that outbox will be transmitted to this 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.
![[Noway!]](gif/noway.gif){kind=small}
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-nosecure depending on the value of the password field, i.e. no inbound filebox.
Default value for port is our own oport.
-nr stands for Not Reliable Link, this works only on outbound calls with another binkp/1.1 mailer. It forces binkd to turn off the protocol optimisation that is based on the assumption that TCP/IP connections are rarely aborted. 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.
Flavour is one of i(mmediate), c(rash), d(irect), -(none), h(old); and is the flavour for the outbound filebox (obox).
node [[zone:]net/]node[.point][@domain] [-nr] [{host[:port]|-} [{password|-} [flavour [{obox|-} [{ibox|-}]]]]]
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
![[FAQ]](gif/book08.gif){kind=small}
5. Frequently Asked Questions and Troubleshooting-DSYSVSIGNALS parameter to the *nix
Makefile.
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:
grep X binkd.log | tail -1
grep '[]] [sr][ec][nv][td]:' binkd.log | grep Y | awk '{n++; cps+=$9} END {print cps/n}'
grep addr: binkd.log | awk '{print $7}' | sort | uniq
grep '[]] [sr][ec][nv][td]:' binkd.log | awk 'BEGIN{FS="\\(|\\)|,| "} $6 ~ /s/ { s+=$9} $6 ~ /r/ {r+=$9} END {print s, r}'
grep '[]] [sr][ec][nv][td]:' binkd.log | awk 'BEGIN {FS="\\(|\\)|,| "} $6 ~ /s/ {s[$14]+=$9} $6 ~ /r/ {r[$14]+=$9; s[$14]+=0} END {for(i in s) print i, s[i], r[
i]}'
![[Mosaic]](gif/mosaic.gif){kind=small}
6. Binkd-related resources on the 'net![[Note]](gif/note02.gif){kind=small}
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 html exersize.
![[KGV Checked!]](gif/valid1.gif){kind=small}
![[W3C Wilbur Checked!]](gif/valid2.gif){kind=small}
![[Best viewed with open eyes]](gif/besteyes.gif){kind=small}
![[Lynx enhanced]](gif/lynx.gif){kind=small}