.\" .\" Copyright (c) 1997, 1999 Hellmuth Michaelis. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .\" last edit-date: [Wed Jul 28 15:57:02 1999] .\" .Dd May 20, 1999 .Dt ISDND.RC 5 .Os .Sh NAME .Nm isdnd.rc .Nd isdn4bsd ISDN connection management daemon config file format .Sh DESCRIPTION The file .Pa /etc/isdn/isdnd.rc contains (if not otherwise specified on the command line) the runtime configuration for the .Xr isdnd 8 ISDN connection management daemon which is part of the isdn4bsd package. .Pp The configuration file consists of keywords which start in column 1 followed by one or more spaces or tabs, an equal sign, one or more spaces or tabs and a keyword dependent parameter value. .Pp A line beginning with '#' is treated as a comment line. .Pp For keywords requiring the specification of a boolean value, the truth value can be either .Em yes or .Em on while the false value can be either .Em no or .Em off . .Pp The configuration file consists of one .Em system section and one or more .Em entry sections. In the .Em system section parameters regarding the daemon operation or parameters not associated with a single remote connection can be set. In the .Em entry section(s) parameters directly associated with a single remote connection can be set. .Pp The following keywords are recognized by .Nm isdnd : .Pp .Bl -tag -width system -compact .It Li system This keyword starts the system configuration section. It must not have a parameter and may be used only once. The keyword is mandatory. The following keywords are valid in the system configuration section: .Bl -tag -width useacctfile -compact .It Li acctall If this parameter is set to .Em on , accounting information is written even if the local site was not charged or no charging information is available or is not subscribed. (optional) .It Li acctfile Specifies the name of the accounting file which is used when the keyword .Em useacctfile (see below) is set to .Em on . See also system keyword .Em rotatesuffix . If this keyword is omitted the system default is used. (optional) .It Li aliasing If this parameter is set to .Em on , alias processing of telephone-number to name is enabled (see also the .Em aliasfile keyword below). The default is off. (optional) .It Li aliasfile Specifies the name of the telephone number-to-name alias database file shared with the .Xr isdntel 1 utility when alias processing is enabled via the .Em aliasing keyword. (optional) .It Li beepconnect In fullscreen mode, if this parameter is set to .Em on , ring the bell when connecting or disconnecting a call. .It Li isdntime If this parameter is set to .Em on , date/time information from the exchange (if provided) is written to the logfile. The default is off. (optional) .It Li monitor-allowed If this parameter is set to .Em on or .Em yes , monitoring via a local or remote machine is enabled. This parameter is optional and is set to .Em off by default. .It Li monitor-port sets the TCP port number for remote monitoring. This integer parameter is optional and is set to port 451 by default. .It Li monitor This keyword specifies a local socket name or a host or network for remote monitoring. The .Em monitor specification may either be: .Pp .Bl -tag -width Ds -compact -offset .It Ar the name of a local (UNIX-domain) socket this MUST start with a "/", example: /var/run/isdn-monitor .It Ar a dotted-quad host specification example: 192.168.1.2 .It Ar a dotted-quad network address with netmask example: 192.168.1.0/24 .It Ar a resolvable host name example: localhost .It Ar a resolvable network name with netmask example: up-vision-net/24 .El .It Li monitor-access This keyword specifies the access rights for a previously used .Em monitor keyword. The supported access rights are: .Pp .Bl -tag -width Ds -compact -offset .It Ar fullcmd .It Ar restrictedcmd .It Ar channelstate .It Ar logevents .It Ar callin .It Ar callout .El .It Li ratesfile Specifies the name of the ratesfile. If this keyword is omitted the system default is used. (optional) .It Li regexpr This keyword is used to specify regular expressions. It can be specified more than once up to a compile time dependent value (currently set to 5 by the MAX_RE definition in the source). .Pp All specified regular expressions are compared to the log strings at runtime and if a match is found, a program is run with the log text as a parameter (see also the keyword .Em regprog below). .Pp For an explanation how regular expressions are specified, please have a look at .Xr re_format 7 and .Xr regex 3 . The .Em extended regular expression syntax is supported here. .Pp Hint: it might be necessary to properly quote the expression to avoid improper interpretation by the configuration file parser. (optional) .It Li regprog This keyword is used to specify the name of a program which is run in case a corresponding regular expression is matched by a logging string. .Nm Isdnd expects to find the program below the path .Pa /etc/isdn which is prepended to the string specified as a parameter to this keyword. (optional) .It Li rotatesuffix Specifies a suffix for renaming the log- and the accountingfilename. In case rotatesuffix is used and a USR1 signal is sent to isdnd, the logfile and the accounting file is not only closed and reopened but the old logfile is also renamed to the former filename with the rotatesuffix string appended. If this keyword is omitted, the logfiles are just closed and reopened; this is also the default behaviour. (optional) .It Li rtprio Specifies the realtime priority .Nm isdnd runs at as an integer value in the range 0...31 with 0 being the highest priority. This keyword is optional; if not specified the process priority of .Nm isdnd is not touched in any way. ( See also .Xr rtprio 1 ). This keyword is only available if .Nm was compiled with -DUSE_RTPRIO. .It Li useacctfile If this parameter is set to .Em on charging (if available) and accounting information is written to the accounting file. (optional) .El .It Li entry This keyword starts one configuration entry. It must not have a parameter. This keyword must be used at least once. The following keywords are valid in an entry section: .Bl -tag -width unitlengthsrc -compact .It Li answerprog This keyword is used to specify the name of a program which is run in case an incoming telephone connection specified .Em answer in its configuration entry. The default name is .Em answer . .Nm Isdnd expects to find this program beneath the path .Pa /etc/isdn which is prepended to the string specified as a parameter to this keyword. (optional) .It Li alert 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. (optional) .It Li b1protocol The B channel layer 1 protocol used for this connection. The keyword is mandatory. The currently configurable values are: .Pp .Bl -tag -width Ds -compact -offset .It Ar hdlc HDLC framing. .It Ar raw No framing at all (used for telephony). .El .It Li callbackwait The time in seconds to wait between hanging up the call from a remote site and calling back the remote site. (optional) .It Li calledbackwait 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. (optional) .It Li dialin-reaction Used to specify what to do when an incoming connection request is received. The keyword is mandatory. The currently supported parameters are: .Pp .Bl -tag -width calledback -compact -offset .It Ar accept Accept an incoming call. .It Ar reject Reject an incoming call. .It Ar ignore Ignore an incoming call. .It Ar answer Start telephone answering for an incoming voice call. .It Ar callback When a remote site calls, hangup and call back the remote site. .El .It Li dialout-type This keyword is used to configure what type of dialout mode is used. The keyword is mandatory. The currently supported parameters are: .Pp .Bl -tag -width Ds -compact -offset .It Ar normal Normal behavior, call the remote site which is supposed to accept the call. .It Ar calledback Callback behavior, call the remote side which rejects the call and calls us back. .El .It Li dialrandincr When dialing or re-dialing and this parameter is set to .Em 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. .It Li dialretries The number of dialing retries before giving up. (optional) .It Li direction 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 .Em inout . .Pp The currently supported parameters are: .Pp .Bl -tag -width Ds -compact -offset .It Ar inout Normal behavior, connection establishment is possible from remote and local. .It Ar in Only incoming connections are possible. .It Ar out Only outgoing connections are possible. .El .It Li downtries is used to configure the number of unsuccessful tries (= retry cycles!) before the interface is disabled (for .Em downtime seconds). (see also the keyword .Em usedown further up). This keyword is optional. .It Li downtime is used to configure the time in seconds an interface is disabled after the configured number of .Em downtries . (see also the keyword .Em usedown further up). This keyword is optional and is set to 60 seconds by default. .It Li earlyhangup A (safety) time in seconds which specifies the time to hangup before an expected next charging unit will occur. (optional) .It Li idle-algorithm-outgoing The algorithm used to determine when to hang up an outgoing call when the line becomes idle. The current algorithms are: .Pp .Bl -tag -width calledback -compact -offset .It Ar fix-unit-size idle algorithm which assumes fixed sized changing units during the whole call. .It Ar var-unit-size idle algorithm which assumes that the charging is time based after the first units time has expired. .El .It Li idletime-outgoing The time in seconds an outgoing connection must be idle before hanging up. An idle timeout of zero disables this functionality. (optional) .It Li idletime-incoming The time in seconds an incoming connection must be idle before hanging up. An idle timeout of zero disables this functionality. (optional) .It Li isdncontroller The ISDN controller number to be used for connections for this entry. (mandatory) .It Li isdnchannel The ISDN controller channel number to be used for connections for this entry. In case a channel is explicitly selected here, the SETUP message will request this channel but mark the request as .Em preferred (the indicated channel is preferred) instead of exclusive (only the indicated channel is acceptable). Thus the exchange is still free to select another than the requested channel! (mandatory) .It Li isdntxdel-incoming A delay value suitable for the .Em timeout() kernel subroutine to delay the transmittion of the first packet after a successfull connection is made by this value for .Em 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 .Xr i4bipr 4 IP over raw HDLC ISDN driver. (optional) .It Li isdntxdel-outgoing A delay value suitable for the .Em timeout() kernel subroutine to delay the transmittion of the first packet after a successfull connection is made by this value for .Em 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 .Xr i4bipr 4 IP over raw HDLC ISDN driver. (optional) .It Li local-phone-dialout 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 .Em "Calling Party Number Information Element" . .Pp This keyword is mandatory for the .Em ipr userland interfaces. .It Li local-phone-incoming The local telephone number used for verifying the destination of incoming calls. 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 with the .Em "Called Party Number Information Element" got from the telephone exchange. .Pp This keyword is mandatory for the ipr interfaces. .It Li name Defines a symbolic name for this configuration entry. It's 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. (mandatory) .It Li ratetype The rate entry used from the rates file. (optional) .br 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). .It Li recoverytime The time in seconds to wait between dial retries. (optional) .It Li remdial-handling is used to specify the dialout behavior in case more than one outgoing number is specified. The currently supported parameters are: .Pp .Bl -tag -width Ds -compact -offset .It Ar first For every new (non-retry) call setup, start with the first number. .It Ar last For every new (non-retry) call setup, start with the last number with which a successful connection was made. .It Ar next For every new (non-retry) call setup, start with the next number which follows the last one used. .El .It Li remote-phone-dialout 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 .Em "Called Party Number Information Element" . .Pp This keyword is mandatory for the .Em ipr interfaces. It may be specified more than once to try to dial to several numbers until one succeeds. .It Li remote-phone-incoming 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 .Em "Calling Party Number Information Element" got from the telephone exchange. .Pp This keyword is mandatory for the ipr interfaces. .Pp This keyword may have a wildcard parameter '*' to permit anyone dialing in. .It Li unitlength The length of a charging unit in seconds. This is used in conjunction with the idletime to decide when to hangup a connection. (optional) .It Li unitlengthsrc This keyword is used to specify from which source .Xr isdnd 8 takes the unitlength for shorthold mode. The currently configurable values are: .Pp .Bl -tag -width Ds -compact -offset .It Ar none Then unitlength is not specified anywhere. .It Ar cmdl Use the unitlength specified on the commandline. .It Ar conf Use the unitlength specified in the configuration file with the keyword .Em unitlength . .It Ar rate Use the unitlength from the ratesfile specified in the configuration file with the keyword .Em ratetype . .It Ar aocd Use a dynamically calculated unitlength 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 telecommunications (ie phone) provider, to indicate billable units). .El .It Li usrdevicename Specifies 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: .Pp .Bl -tag -width Ds -compact -offset .It Ar ipr This parameter configures a raw HDLC IP over ISDN interface. .It Ar isp This parameter configures a synchronous PPP over ISDN interface. .It Ar rbch This specifies a Raw B CHannel access interface. .It Ar tel ISDN telephony. .El .It Li usrdeviceunit Specifies the unit number for the device which is specified with usrdevicename. .It Li usedown is used to enable the use of the keywords .Em downtries and .Em downtime in the entries section(s). It is used in the .Nm 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 .Em off by default. .It Li connectprog specifies a program run everytime after a connection is established and address negotiation is complete (i.e.: the connection is useable). .Nm Isdnd expects to find the program below the path .Pa /etc/isdn which is prepended to the string specified as a parameter to this keyword. The programs specified by connect and disconnect will get the following command line arguments: -d (device) -f (flag) [ -a (addr) ] where .Em device is the name of device, e.g. "isp0", .Em flag will be "up" if connection just got up, or "down" if interface changed to down state and .Em addr the address that got assigned to the interface as a dotted-quad ip address (optional, only if it can be figured out by isdnd). (optional) .It Li disconnectprog specifies a program run everytime after a connection was shut down. .Nm Isdnd expects to find the program below the path .Pa /etc/isdn which is prepended to the string specified as a parameter to this keyword. (optional) .El .El .Sh IDLETIME CALCULATION AND SHORTHOLD MODE .Bl -tag -width incoming calls -compact .It Li incoming calls It is assumed that the calling side knows most about charging structures and such and as a consequence only the keyword .Em idletime-incoming has a function for incoming calls. .Pp For incoming calls the line is constantly monitored, and in case there was not traffic taking place for the time in seconds specified by .Em idletime-incoming the call is closed. .Pp Typically, .Em idletime-incoming is used as a last resort and is therefore set much higher than a charging unit time: typical values are one to five minutes. .It Li outgoing calls Outgoing call disconnect time can be setup in one of three ways: .Bl -tag -width shorthold mode -compact .It Li simple mode For simple mode, the .Em idle-algorithm-outgoing must be .Em fix-unit-size and the selected .Em unitlength must be 0 (zero) and .Em idletime-outgoing greater zero. .Pp The outgoing traffic is constantly monitored, and in case there was not traffic taking place for the time in seconds specified by .Em idletime-outgoing the call is closed. .Pp Typical values in simple mode are 10 to 30 seconds. .It Li shorthold mode for fixed unit charging For shorthold mode, the .Em idle-algorithm-outgoing must be .Em fix-unit-size and the selected .Em unitlength and .Em idletime-outgoing must be greater than 0 (zero); .Em earlyhangup must be >= 0 (zero). .Bd -literal |||| | | | | +------------------+-------------+--------------+ | | | | | |<-idle-time->|| |<--------------unitlength--------------------->| .Ed During the unchecked window which is (unitlength - (idle-time+earlyhangup)) in length, no idle check is done. After the unchecked window has ended, the line is checked for idle-time length if no traffic takes place. In case there was traffic detected in the check-window, the same procedure is restarted at the beginning of the next unit. In case no traffic was detected during the check-window, the line is closed at the end of the check window. .Pp Notice: .Em unitlength must (!) be greater than the sum of .Em idletime-outgoing and .Em earlyhangup ! .It Li shorthold mode for variable unit charging For shorthold mode, the .Em idle-algorithm-outgoing must be .Em var-unit-size and the selected .Em unitlength and .Em idletime-outgoing must be greater than 0 (zero); .Pp This shorthold mode is suitable when your calls are billed on the elapse time of the call plus a fixed connection charge. For example British Telecom bill this way. .Pp Each call is divided into two periods, the first is the .Em unchecked period and the second is the .Em checked . The .Em checked period starts 1 second before the first units time expires. .Pp During the .Em checked period if there is no traffic for .Em idle-time seconds the call is disconnected. .Pp .Bd -literal |<---unchecked------------------>|<------checked------> +------------------+-------------+ | |<-idle-time->| |<--------------unitlength------->| .Ed Experience shows that useful values for idle-time are from 15 to 30 seconds. .Pp If idle-time is too short an application that is not yet finished with the network will cause a new call to be placed. .Pp .El .El .Pp .Sh FILES .Bl -tag -width /etc/isdn/isdnd.rc -compact .It Pa /etc/isdn/isdnd.rc The default configuration file for the .Nm isdnd ISDN daemon. .El .Sh SEE ALSO .Xr regex 3 , .Xr re_format 7 , .Xr isdnd 8 , .Xr isdnmonitor 8 .Sh AUTHORS The .Xr isdnd 8 daemon and this manual page were written by .An Hellmuth Michaelis Aq hm@kts.org . .Pp Additions to this manual page by .An Barry Scott Aq barry@scottb.demon.co.uk .