The Care and Feeding of ISDN4BSD
6.1.2 The Controller Configuration	6.1 The isdnd.rc Configuration	6.1.4 Idletime Calculation for

6.1.3 The Entry Configuration Section

The configuration statements in an entry section are used to setup one particular link between you and a remote site and to configure and customize the various ways such a link can be operated.

The first configuration statement of every entry section should be:

• [name](string) Assigns a symbolic name to this configuration entry. It's only purpose is to use this name in the full screen display for easy identification of a link to a remote site and for accounting purposes in the log- and accounting files. This keyword is mandatory.
• [clone](string) Copies the contents of the named entry to the current one. When using this feature at least a new entry specific `name' and `usrdeviceunit' value should be specified for the current entry.

The ISDN controller and B-channel to be used must be configured:

• [isdncontroller](integer, 0-n) The ISDN controller number to be used for connections for this entry. This keyword is mandatory.
• [isdnchannel](-1, 0, 1 or 2) The preferred ISDN controller B-channel number to be used for outgoing connections for this entry. A 0 or a -1 selects any B-channel. In case a B-channel is explicitly selected here, the SETUP message will request this channel but mark the request as preferred instead of exclusive. Thus the exchange is still free to select another than the requested channel! This keyword is mandatory.

Then the interface the B-channel data shall be routed to must be specified:

• [usrdevicename](ipr, isp, tel, rbch, ing) is used to specify the userland interface which is used for interfacing ISDN B channel data to the userland. The keyword is mandatory. This keyword accepts the following parameters:
  • [ipr]This parameter configures a raw HDLC IP over ISDN interface.
  • [isp]This parameter configures a synchronous PPP over ISDN interface.
  • [rbch]This specifies a Raw B CHannel access interface.
  • [tel]ISDN telephony.
  • [ing]configures a Netgraph interface to an ISDN B-channel
• [usrdeviceunit](integer, 0-n) Specifies the unit number for the device specified with the usrdevicename keyword.

The ``telephone'' numbers (or MSN's Multiple Subscriber Numbers) must be specified for the local and the remote sites:

• [local-phone-dialout](number string) This keyword is used to configure the local telephone number used when the local site dials out. When dialing out to a remote site, the number specified here is put into the Calling Party Number Information Element (see also [5], pp 79). This keyword is mandatory for the ipr and isp userland network interfaces.
• [local-phone-incoming](number string) This keyword specifies the local telephone number which is used for comparing to a destination number contained in an incoming call. When a remote site dials in, this number is used to verify that it is the local site which the remote site wants to connect to. It is compared against the Called Party Number Information Element (see also [5], pp 75) from the telephone exchange.
• [remote-phone-dialout](number string) The remote telephone number used when the local site dials out. When dialing out to a remote site, the number specified here is put into the Called Party Number Information Element. This keyword is mandatory for the ipr and isp interfaces. It may be specified more than once to try to dial to several numbers until one succeeds (see also keyword remdial-handling).
• [remote-phone-incoming](number string or *) The remote telephone number used to verify an incoming call. When a remote site dials in, this number is used to verify that it is the correct remote site which is herewith authorized to connect into the local system. This parameter is compared against the Calling Party Number Information Element got from the telephone exchange. This keyword is mandatory for the ipr and isp interfaces. This keyword may have a wildcard parameter '*' to permit anyone dialing in.
• [remdial-handling](first, last, next) is used to specify the dialout behavior in case more than one outgoing number is specified. The currently supported parameters are:
  • [first]For every new (non-retry) call setup, start with the first number.
  • [last]For every new (non-retry) call setup, start with the last number with which a successful connection was made.
  • [next]For every new (non-retry) call setup, start with the next number which follows the last one used.

Because this all is a bit confusing, lets look at an example of an incoming call from a remote site:

The D-channel layer 3 message signaling an incoming call contains the telephone number of the site which is calling us (040556677) and the telephone number which it wants to connect to (030112233). When isdnd gets this message, it searches its entry section configurations for a match. In our example, one of the entry sections contains the configuration remote-phone-incoming=040556677 and local-phone-incoming=030112233 which matches the numbers from the message of the incoming call and a connection is (when other parameters are matched as well) possible.

In case we have configured an outgoing link, for example:

In the corresponding entry configuration, the local number is configured as local-phone-outgoing=030112233 and the number of the site we want to connect to as remote-phone-outgoing=040123456. This two numbers will then become part of the outgoing D-channel layer 3 message to the exchange as the Calling Party Number and the Called Party Number.

Some remarks to telephone numbers:

• When talking of ``telephone number'' here, i always mean a Multiple Subscriber Number or MSN in short, which is the ISDN term for a telephone number.
• Local telephone numbers configured with the local-phone-outgoing keyword must be one of the locally assigned MSN's you got from your ISDN provider. In case you specify a telephone number which is not your own by using local-phone-outgoing, the exchange will detect this, remove the number in question and insert your base MSN (or first MSN) instead. Because of this, faking of numbers is almost impossible (this last paragraph might only apply for the Telekom provided ISDN here in Germany).
• Wether you may or must prepend a dialing prefix and/or your area- or country code to any of the described telephone number parameters depends on the exchange you are connected to and cannot be generally predicted.
• In case you are connected to a Private Branch Exchange (PBX), it might be the case that your local number (configured with local-phone-outgoing and/or local-phone-incoming) must be configured as your extension number. It is even possible (as in the company i work for) that you have to append a digit to your ``normal'' extension number to address several possible devices on the S0 bus you connected your machine to.
• In many cases the only reliable way to find out what type of prefixes or add-ons are required in your environment is to have a look at the isdntrace output while you try to call your number with a normal telephone.

Some configuration entries are only used for the telephone answering facility:

• [answerprog](programname) This keyword is used to specify the name of a program which is run in case an incoming telephone connection specified dialin-reaction = answer in its configuration entry. The default name is answer. Isdnd expects to find this program beneath the path /etc/isdn which is prepended to the string specified as a parameter to this keyword.
• [alert](integer, 5-180) is used to specify a time in seconds to wait before accepting a call. This keyword is only usable for incoming telephone calls (dialin-reaction = answer). It is used to have a chance to accept an incoming call on the phone before the answering machine starts to run. The minimum value for the alert parameter is 5 seconds and the maximum parameter allowed is 180 seconds.

Currently only one B-channel protocol is supported, which is selected by:

• [b1protocol]The B channel layer 1 protocol used for this connection. The keyword is mandatory. The currently configurable values are:
  • [hdlc]HDLC framing (must be configured for ipr and isp interfaces)
  • [raw]No framing at all (must be configured for telephony).

Next, general characteristics of the connection are configured:

• [dialin-reaction](accept, reject, ignore, answer, callback) Used to specify what to do when an incoming connection request is received. The keyword is mandatory. The currently supported parameters are:
  • [accept]Accept an incoming call.
  • [reject]Reject an incoming call.
  • [ignore]Ignore an incoming call.
  • [answer]Start telephone answering for an incoming voice call.
  • [callback]When a remote site calls, hang up and call back the remote site.
• [dialout-type](normal, calledback) This keyword ist used to configure what type of dialout mode is used. The keyword is mandatory. The currently supported parameters are:
  • [normal]Normal behavior, call the remote site which is supposed to accept the call.
  • [calledback]Callback behavior, call the remote side which rejects the call and calls us back.
• [direction](in, out, inout) This keyword is used to configure if incoming and outgoing, incoming-only or outgoing only connections are possible. The keyword is optional, the default is inout. The currently supported parameters are:
  • [inout]Normal behavior, connection establishment is possible from remote and local.
  • [in]Only incoming connections are possible.
  • [out]Only outgoing connections are possible.
• [dialrandincr](on/off) When dialing or re-dialing and this parameter is set to on, the dial retry time is added with a random value (currently 0...3 seconds) to minimize the chance of two sites dialing synchronously so each gets a busy each time it dials because the other side is also dialing.

Another part to configure is the dialing and the recovery from dialing failures:

• [dialretries](integer) The number of dialing retries before giving up. A value of -1 gives an ulimited amount of dial retries.
• [recoverytime](integer) The time in seconds to wait between dial retries.
• [usedown](on/off) is used to enable the use of the keywords downtries and downtime in an entry configuration section. It is used in the isdnd daemon to dynamically enable and disable the IP interfaces to avoid excessive dialing activities in case of transient failures (such as busy lines). This parameter is optional and is set to off by default.
• [downtries](integer) is used to configure the number of unsuccessful tries (= retry cycles!) before the interface is disabled (for downtime seconds). This keyword is optional.
• [downtime](integer) is used to configure the time in seconds an interface is disabled after the configured number of downtries. This keyword is optional and is set to 60 seconds by default.

In case we are called back from the remote end or we call the remote back, times to wait for this two modes have to be configured:

• [callbackwait](integer) The time in seconds to wait between hanging up the call from a remote site and calling back the remote site. This keyword is optional.
• [calledbackwait](integer) The time in seconds to wait for a remote site calling back the local site after a call from the local site to the remote site has been made. This keyword is optional.

One of the most complex parts to configure is the area of idle timeouts and short hold mode:

• [idle-algorithm-outgoing](fix-unit-size,var-unit-size) The algorithm used to determine when to hang up an outgoing call when the line becomes idle. The available algorithms are:
  • [fix-unit-size]idle algorithm which assumes fixed sized changing units during the whole call (i.e. used in Germany by the Telekom, especially if the AOCD [Advice Of Charge During the call] service is subscribed).
  • [var-unit-size]idle algorithm which assumes that the charging is time based after the first units time has expired (i.e. used in the UK by the British Telecom).
• [idletime-outgoing](integer) The time in seconds an outgoing connection must be idle before hanging up. (optional)
• [idletime-incoming](integer) The time in seconds an incoming connection must be idle before hanging up. (optional)
• [earlyhangup](integer) A (safety) time in seconds which specifies the time to hang up before an expected next charging unit will occur. (optional)
• [unitlengthsrc](none, cmdl, conf, rate, aocd) This keyword is used to specify from which source isdnd(8) takes the unit length for short hold mode. The currently configurable values are:
  • [none]Then unitlength is not specified anywhere.
  • [cmdl]Use the unit length specified on the command line.
  • [conf]Use the unit length specified in the configuration file with the keyword unitlength.
  • [rate]Use the unit length from the ratesfile specified in the configuration file with the keyword ratetype.
  • [aocd]Use a dynamically calculated unit length in case AOCD is subscribed on the ISDN line. (AOCD is an acronym for ``Advice Of Charge During the call'' which is a service provided by the telecommunication provider, to indicate billable units).
• [unitlength](integer) The length of a charging unit in seconds. This is used in conjunction with the idletime to decide when to hang up a connection. (optional)
• [ratetype]The rate entry used from the rates file. For example, ratetype=0 selects lines beginning "ra0" in /etc/isdn/isdnd.rates; (typically ra0 lines are a set of tables for local call rates on different days of the week & times per day).

Sometimes it is desirable to run programs or shell-scripts when a connection is established and/or when a connection is shut down. This seems to be helpful especially for PPP connections using the isp driver. Two entry-keywords are provided to support this:

• [connectprog](programname) specifies the program to be run every time after a connection is established and address negotiation is complete (i.e. the connection is usable). Isdnd expects to find the program below the path /etc/isdn, which is prepended to the string specified as a parameter to this keyword.
• [disconnectprog](programname) specifies the program to be run every time after a connection was shut down. Isdnd expects to find the program below the path /etc/isdn, which is prepended to the string specified as a parameter to this keyword.

For the ipr - interfaces, two special entry keywords are provided to delay transmitting data on the B-channel after a connection is established for incoming and/or outgoing calls. They are needed, because the B-channel is usually (due to the nature of the protocol handshake used on the D-channel to establish a connection) switched through asymmetrically. This means, that one side is able to send data on the B-channel a bit more earlier than the other side is able to receive data which results in data loss (my observation is, that the first 200...500 bytes are lost). In case of the ipr - interface, this means that the very first 2 or 3 packets of a TCP connection get lost resulting in a long TCP connection setup time of 10 to 30 seconds. Using the following keywords to delay transmission in this case results in a very fast connection setup because no packets are lost:

• [isdntxdel-incoming](integer) A delay value suitable for the timeout() kernel subroutine to delay the transmission of the first packet after a successful connection is made by this value for incoming ISDN connections. The specification unit is 1/100 second. A zero (0) disables this feature and is the default value. This feature is implemented (and makes sense only) for the i4bipr(4) IP over raw HDLC ISDN driver. (optional)
• [isdntxdel-outgoing](integer) A delay value suitable for the timeout() kernel subroutine to delay the transmission of the first packet after a successful connection is made by this value for outgoing ISDN connections. The specification unit is 1/100 second. A zero (0) disables this feature and is the default value. This feature is implemented (and makes sense only) for the i4bipr(4) IP over raw HDLC ISDN driver. (optional)

Sometimes it is desirable to limit the number of possible outgoing calls within a certain amount of time. For this reason, the concept of a callout budget was introduced. Two types of budget combinations may be specified: one budget for locally initiated outgoing calls and another for remotly initiated outgoing calls as a result of a callback trigger operation:

• [budget-calloutperiod](integer) is used to specify a time period in seconds. Within this period, the number of calls specified by budget-calloutncalls are allowed to succeed, any further attempt to call out will be blocked for the rest of the time left in the time period. (optional, default off)
• [budget-calloutncalls](integer) The number of outgoing calls allowed within the time period specified by budget-calloutperiod. (optional, default off)
• [budget-calloutsfile](string) A path/filename to which the number of successfull callouts are written. The contents of the file is preserved when it exists during startup of isdnd. The format of this file is: start time, last update time, number of calls and can i.e. be used to produce statistics with mrtg (see /usr/src/share/examples/isdn/contrib). (optional)
• [budget-calloutsfile-rotate](on/off) If set to on rotate the budget-calloutsfile every night when an attempt is made to update the file on a new day. The statistics for the previous day are witten to a file with the filename specified by budget-calloutsfile to which a hyphen and the new day's (!) day of month number is appended. (optional)
• [budget-callbackperiod](integer) is used to specify a time period in seconds. Within this period, the number of callback calls specified by budget-callbackncalls are allowed to succeed, any further attempt to call out will be blocked for the rest of the time left in the time period. (optional, default off)
• [budget-callbackncalls]The number of outgoing callback calls allowed within the time period specified by budget-callbackperiod. (optional, default off)
• [budget-callbacksfile](string) A path/filename to which the number of successfull callbacks are written. The contents of the file is preserved when it exists during startup of isdnd. The format of this file is: start time, last update time, number of calls and can i.e. be used to produce statistics with mrtg (see /usr/src/share/examples/isdn/contrib). (optional)
• [budget-callbacksfile-rotate](on/off) If set to on rotate the budget-callbacksfile every night when an attempt is made to update the file on a new day. The statistics for the previous day are witten to a file with the filename specified by budget-callbacksfile to which a hyphen and the new day's (!) day of month number is appended. (optional)
• [maxconnecttime](integer) Specify a maximum connection time in seconds. Use this to define an absolute upper limit for a con- nection on the B-channel to last. CAUTION: This feature is used to limit the connection time, _not_ number of attempts to establish a connection: when using this please take care to also enable the use of budgets to limit the number of connection establish attempts (otherwise the line will cycle thru an endless loop of connections and reconnections which will have an undesired effect on your telco bill)!

The following feature is closely related to budgets because it allows you to specify time frames in which an entry is valid. With other words, with this keyword you are able to create several entries for one and the same connection but with different budget- or other parameters for different times of the day or week.

• [valid](time range specification) Note: this feature is considered experimental! The parameter to this keyword is a string specify- ing a time range within which this entry is valid. The time specification consists of a list of weekdays and/or a holiday indicator ( see also the holidayfile keyword in the system section ) separated by commas followed by an optional daytime range specification in the form hh:mm-hh:mm. The weekdays are specified as numbers from 0 to 6 and the number 7 for holidays:
  • [0]Sunday
  • [1]Monday
  • [2]Tuesday
  • [3]Wednesday
  • [4]Thursday
  • [5]Friday
  • [6]Saturday
  • [7]a Holiday
  The following examples describe the "T-ISDN xxl" tariff of the german Telekom:
  • [1,2,3,4,5,6,09:00-18:00]Monday through Saturday, daytime 9:00 to 18:00
  • [1,2,3,4,5,6,18:00-9:00]Monday through Saturday, nighttime 18:00 to 9:00
  • [0,7]Sunday and on holidays, all 24 hours
  The use of the valid keyword is optional.

A new feature is that it is now possible to configure the isp - interfaces driectly from an entry in isdnd.rc instead of using ispppcontrol, the following keywords are used for that purpose:

• [ppp-auth-paranoid](on/off) If set to no, the remote site is not required to prove its authentity for connections that are ini- tiated by the local site. The default is yes and requires the remote site to always authenticate. This keyword is only used if ppp-send-auth has been set to pap or chap for an isp PPP interface. (optional)
• [ppp-auth-rechallenge](on/off) Set to no, if the other side does not support re- challenging for chap. The default is yes, which causes verification of the remote site's authenti- ty once in a while. This keyword is only used if ppp-expect-auth has been set to chap for an isp PPP interface. (op- tional)
• [ppp-expect-auth](none / chap / pap) The local site expects the authentity of the remote site to be proved by the specified method. If ppp-auth-paranoid is set to no (the default is yes), outgoing connections will not require the remote site to authenticate itself. This keyword is only used for the isp PPP interfaces.The supported methods are:
  • [none]Do not require the other side to authenticate. Typical uses are dial-out to an ISP (many ISPs do not authenticate themselves to clients) or offering anonymous dial-in at the local site.
  • [chap]The preferred authentication method, which does not require a password to be sent in the clear.
  • [pap]The unprotected authentication method, which allows anybody watching the wire to grab name and password.
• [ppp-expect-name](string) The name that has to be provided by the remote site to prove its authentity. This keyword is only used if ppp-expect-auth has been set to pap or chap for an isp PPP interface. (optional)
• [ppp-expect-password](string) The secret that has to be provided by the remote site to prove its authentity. This keyword is only used if ppp-expect-auth has been set to pap or chap for an isp PPP interface. (optional)
• [ppp-send-auth](none / pap / chap) The authentication method required by the remote site. The currently supported parameters are:
  • [none]The remote site does not expect or support authentication.
  • [chap]The preferred authentication method, which does not require a password to be sent in the clear.
  • [pap]The unprotected authentication method, which allows anybody watching the wire to grab name and password.
• [ppp-send-name](string) The authentication name sent to the remote site. This keyword is only used if ppp-send-auth has been set to pap or chap for an isp PPP interface. (optional)
• [ppp-send-password]The secret used to prove the local site's authentity to the remote site. This keyword is only used if ppp-send-auth has been set to pap or chap for an isp PPP interface. (optional)