![[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 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 990607, current binkd version: 0.9.2.
This document is (c) Copyright 1997-1999 Nick Soveiko.
This HTML document as well as it's reproduction in any form is a free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
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.
Table of contents![[What?]](gif/info03.gif){kind=small}
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@corbina.net, http://www.corbina.net/~maloff/binkd/.
![[Why?]](gif/yin_yang.gif){kind=small}
1. Binkd philosophyBinkd 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:
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.
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?]](gif/onramp1.gif)
2. InstallationYou 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.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 ftp://ftp.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. 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.
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.
4. Configuration fileConfiguration 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.
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.
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
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_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).
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 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!
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 console. 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 specified by binlog and/or fdinhist and fdouthist
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: fdinhist and fdouthist keywords specify complete filenames to the inbound and outbound binary history files with FrontDoor and Bink/+ compatible format.
Note: if your file system uses backslashes as path
separators, each backslash should be escaped with another one.
fdinhist [<path><separator>]<log_file> fdouthist [<path><separator>]<log_file>
fdinhist o:\\log\\in.his fdouthist /var/spool/fnet/logs/outbound.history
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-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.
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.
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. Filenames together with timestamp will be stored in
inbound/foobar.dt and file data in
inbound/foobar.hr files. Same rule also applies
to inbound-nonsecure.
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 indefinitely. 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 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.
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 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.
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).
flag [!]<flag> <wildcard_list>
Create flag mail.now immediately after any .pkt file is received to any directory:
flag !mail.now *.pkt
Create flag toss.now after inbound arcmail session:
flag toss.now *.su? *.mo? *.tu? *.we? *.th? *.fr? *.sa?
Create flag ndl_sec.now after a session, during which any file matching net50*.* was received to directory z:\fido\inbound\secure\ :
flag ndl_sec.now z:\\\\fido\\\\inbound\\\\secure\\\\net50*.*
On *NIX this might look like
flag ndl_sec.now /var/spool/inbound/secure/net50*
Create flag ndl_any.now after a session, during which any file matching net50*.* was received to any directory:
flag ndl_any.now *\\\\net50*.*
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).
Note: if your file system uses backslashes as path
separators, each backslash 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.
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).
exec <commandline> <filemask>
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.
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 permanent links later in the master config file or even in separate file each.
node [[zone:]net/]node[.point][@domain] [-nr] [{hostlist|-} [{password|-} [flavour [{obox|-} [{ibox|-}]]]]]
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).
-nr stands for Non Reliable link, 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. 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.
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:
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:
password field specifies password for the remote system.
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.
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).
Note: if your file system uses backslashes as path
separators, each backslash should be escaped with another one.
![[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-nonsecure depending on the value of the password field, i.e. default is no inbound filebox.
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 -
Purpose: root-domain keyword defines the default domain name which binkd will use while making fully qualified domain names from FTN addresses.
root-domain domain_name
root-domain fidonet.net
![[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]}'
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...
![[Content enhanced]](gif/enhanced.gif){kind=small}
![[Lynx enhanced]](gif/lynx.gif){kind=small}
