freebsd-nq/usr.sbin/i4b/isdnd/isdnd.rc.5
2004-07-02 23:13:00 +00:00

1116 lines
33 KiB
Groff

.\"
.\" Copyright (c) 1997, 2002 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: [Sun Aug 11 20:07:38 2002]
.\"
.Dd August 11, 2002
.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, one or more optional
.Em controller
sections 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 controller
section parameters regarding a particular controller 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
.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
.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 add-prefix
If set to
.Em on ,
for incoming numbers, have a look at the "type of number" indicator and
adjust the number as specified by the
.Em prefix-national
and
.Em prefix-international
keywords described later.
If this keyword is omitted, the system default (off) 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 full-screen mode, if this parameter is set to
.Em on ,
ring the bell when connecting or disconnecting a call.
.It Li extcallattr
If this parameter is set to
.Em on ,
the extended caller attributes "screening indicator" and "presentation
indicator" are written to the log-file.
The default is off.
(optional)
.It Li holidayfile
Specifies the name of the holiday file containing the dates of holidays.
This file is used in conjunction with the
.Em valid
keyword to lookup the dates of holidays.
(optional)
.It Li isdntime
If this parameter is set to
.Em on ,
date/time information from the exchange (if provided) is written to the
log-file.
The default is off.
(optional)
.It Li mailer
This keyword is used to specify the path/name of a mail program
which is able to use the "-s" flag to specify a subject on its
command line.
In case of a fatal error exit of
.Nm
this program is used to send mail to an administrator specified by
the keyword
.Em mailto .
(optional)
.It Li mailto
This keyword is used to specify the email address of someone to notify
in case of a fatal error exit of
.Nm .
(See also keyword
.Em mailer ) .
(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
.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
.It Ar fullcmd
.It Ar restrictedcmd
.It Ar channelstate
.It Ar logevents
.It Ar callin
.It Ar callout
.El
.It Li prefix-international
In conjunction with the
.Em add-prefix
switch (see above), specify the prefix number string for incoming numbers
with the international number tag.
If aliases are used, they have to be adjusted accordingly.
(optional)
.It Li prefix-national
In conjunction with the
.Em add-prefix
switch (see above), specify the prefix number string for incoming numbers
with the national number tag.
If aliases are used, they have to be adjusted accordingly.
(optional)
.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 accounting-filename.
In case
rotatesuffix is used and a USR1 signal is sent to isdnd, the log-file and the
accounting file is not only closed and reopened but the old log-file is also
renamed to the former filename with the rotatesuffix string appended.
If this keyword is omitted, the log-files are just closed and reopened; this
is also the default behavior.
(optional)
.It Li rtprio
Specifies the real-time 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 controller
This keyword starts the controller configuration section.
It must not
have a parameter and may be used once for every controller.
The keyword
is optional.
The following keywords are valid in a controller
configuration section:
.Bl -tag -width useacctfile
.It Li protocol
This keyword is used to set the D-channel protocol for the S0-bus a
controller is connected to.
The following parameters are currently
supported:
.Pp
.Bl -tag -width calledback -compact
.It Ar dss1
The DSS1 or so-called "Euro-ISDN" D-channel protocol according to
ITU Recommendations Q.921 and Q.931.
.It Ar d64s
An ISDN leased line with a single B-channel (called D64S in Germany).
.El
.It Li firmware
This keyword is used like
.Li firmware Ns = Ns Ar /path/to/file
to download the
firmware to active controllers supported by the
.Em iavc
driver (AVM B1, T1).
This keyword is supported for all controller types,
and causes
.Dv I4B_CTRL_DOWNLOAD
ioctl to be invoked with the specified file
as an argument.
In systems equipped with both active and passive adapters,
and the passive cards being detected first, dummy
.Ql controller
entries
are required for the passive cards to get the correct firmwares to
correct adapters.
.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
.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
.It Ar hdlc
HDLC framing.
.It Ar raw
No framing at all (used for telephony).
.El
.It Li bcap
Use a special bearer capability for this connection.
The keyword is optional.
.Pp
Any other value than
.Em dov
sets the bearer capability as configured by the
.Em b1protocol
keyword (see above).
The currently configurable values are:
.Pp
.Bl -tag -width Ds -compact
.It Ar dov
This connection is a
.Em Dov (Data over Voice)
connection.
The b1protocol keyword must be set to
.Em hdlc .
This feature is experimental and does work on outgoing calls only.
.El
.It Li budget-calloutperiod
is used to specify a time period in seconds.
Within this period, the number of calls
specified by
.Em 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)
.It Li budget-calloutncalls
The number of outgoing calls allowed within the time period specified by
.Em budget-calloutperiod .
(optional)
.It Li budget-calloutsfile
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.
(optional)
.It Li budget-calloutsfile-rotate
If set to
.Em on
rotate 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)
.It Li budget-callbackperiod
.It Li budget-callbackncalls
.It Li budget-callbacksfile
.It Li budget-calloutsfile-rotate
See
.Em budget-calloutperiod ,
.Em budget-calloutncalls ,
.Em budget-calloutsfile ,
and
.Em budget-calloutsfile-rotate
above.
These are used to specify the budgets for calling back a remote site.
.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 clone
This causes the contents of the specified entry to be copied from the
existing named entry to the current one.
When using this feature at least a new entry specific
.Ql name
and
.Ql usrdeviceunit
value should be specified for the current entry.
.It Li connectprog
specifies a program run every time after a connection is established and
address negotiation is complete (i.e.: the connection is usable).
.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 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
.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, hang up 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
.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.
Setting this to
.Em -1
gives an unlimited number of retries!
(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
.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 disconnectprog
specifies a program run every time 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)
.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 hang up 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
.It Ar fix-unit-size
idle algorithm which assumes fixed sized charging 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
.Xr timeout 9
kernel subroutine to delay the transmission of the first packet after a
successful 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
.Xr timeout 9
kernel subroutine to delay the transmission of the first packet after a
successful 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
user-land interfaces.
.It Li local-subaddr-dialout
The local subaddress used when the local site dials out.
When dialing
out to a remote site, the subaddress specified here is put into the
.Em "Calling Party Subaddress Information Element" .
.Pp
This keyword is mandatory for the
.Em ipr
user-land 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
.Em ipr
interfaces.
.It Li local-subaddr-incoming
The local subaddress used for verifying the destination of incoming
calls.
When a remote site dials in, this subaddress 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 Subaddress Information Element"
got from the telephone exchange.
.Pp
This keyword is mandatory for the
.Em ipr
interfaces.
.It Li name
Defines a symbolic name for this configuration entry.
Its 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 maxconnecttime
Specify a maximum connection time in seconds.
Use this to define an absolute
upper limit for a connection on the B-channel to last.
.Em 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 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)!
.It Li ppp-auth-paranoid
If set to
.Em no ,
the remote site is not required to prove its authentity for connections
that are initiated by the local site.
The default is
.Em yes
and requires the remote site to always authenticate.
.Pp
This keyword is only used if
.Em ppp-send-auth
has been set to pap or chap for an
.Em isp
PPP interface.
(optional)
.It Li ppp-auth-rechallenge
Set to
.Em no ,
if the other side does not support re-challenging for chap.
The default is
.Em yes ,
which causes verification of the remote site's authentity once in a while.
.Pp
This keyword is only used if
.Em ppp-expect-auth
has been set to chap for an
.Em isp
PPP interface.
(optional)
.It Li ppp-expect-auth
The local site expects the authentity of the remote site to be proved by
the specified method.
The supported methods are:
.Pp
.Bl -tag -width Ds -compact
.It Ar 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.
.It Ar chap
The preferred authentication method, which does not require a password to be sent
in the clear.
.It Ar pap
The unprotected authentication method, which allows anybody watching the wire
to grab name and password.
.El
.Pp
If
.Em ppp-auth-paranoid
is set to
.Em no
(the default is
.Em yes )
outgoing connections will not require the remote site to authenticate itself.
.Pp
This keyword is only used for the
.Em isp
PPP interfaces.
(optional)
.It Li ppp-expect-name
The name that has to be provided by the remote site to prove its authentity.
.Pp
This keyword is only used if
.Em ppp-expect-auth
has been set to pap or chap for an
.Em isp
PPP interface.
(optional)
.It Li ppp-expect-password
The secret that has to be provided by the remote site to prove its authentity.
.Pp
This keyword is only used if
.Em ppp-expect-auth
has been set to pap or chap for an
.Em isp
PPP interface.
(optional)
.It Li ppp-send-auth
The authentication method required by the remote site.
The currently supported parameters are:
.Pp
.Bl -tag -width Ds -compact
.It Ar none
The remote site does not expect or support authentication.
.It Ar chap
The preferred authentication method, which does not require a password to be sent
in the clear.
.It Ar pap
The unprotected authentication method, which allows anybody watching the wire
to grab name and password.
.El
.Pp
This keyword is only used for the
.Em isp
PPP interfaces.
(optional)
.It Li ppp-send-name
The authentication name sent to the remote site.
.Pp
This keyword is only used if
.Em ppp-send-auth
has been set to pap or chap for an
.Em isp
PPP interface.
(optional)
.It Li ppp-send-password
The secret used to prove the local site's authentity to the remote site.
.Pp
This keyword is only used if
.Em ppp-send-auth
has been set to pap or chap for an
.Em isp
PPP interface.
(optional)
.It Li ratetype
The rate entry used from the rates file.
(optional)
.Pp
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
.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-subaddr-dialout
The remote subaddress used when the local site dials out.
When dialing
out to a remote site, the subaddress specified here is put into the
.Em "Called Party Subaddress Information Element" .
.Pp
This keyword is mandatory for the
.Em ipr
interfaces.
It may be specified more than once to linked it to the
remote-phone-dialout 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 remote-subaddr-incoming
The remote subaddress used to verify an incoming call.
When a remote site
dials in, this subaddress 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 Subaddress 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 hang up a connection.
(optional)
.It Li unitlengthsrc
This keyword is used to specify from which source
.Xr isdnd 8
takes the unitlength for short-hold mode.
The currently configurable values are:
.Pp
.Bl -tag -width Ds -compact
.It Ar none
Then unitlength is not specified anywhere.
.It Ar cmdl
Use the unitlength specified on the command line.
.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 user-land interface which is used for interfacing ISDN B channel
data to the user-land.
The keyword is mandatory.
This keyword accepts the following parameters:
.Pp
.Bl -tag -width Ds -compact
.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.
.It Ar ing
configures an ISDN B-channel to NetGraph interface.
.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 usesubaddr
is used to enable the use of subaddresses.
This parameter is optional and is set to
.Em off
by default.
.It Li valid
.Em Note :
this feature is considered experimental!
The parameter to this keyword is a string specifying 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
.Em 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:
.Pp
.Bl -tag -width Ds -compact
.It Ar 0
Sunday
.It Ar 1
Monday
.It Ar 2
Tuesday
.It Ar 3
Wednesday
.It Ar 4
Thursday
.It Ar 5
Friday
.It Ar 6
Saturday
.It Ar 7
a Holiday
.El
.Pp
The following examples describe the "T-ISDN xxl" tariff of the german Telekom:
.Bl -tag -width Ds -compact
.It Ar 1,2,3,4,5,6,09:00-18:00
Monday through Saturday, daytime 9:00 to 18:00
.It Ar 1,2,3,4,5,6,18:00-9:00
Monday through Saturday, nighttime 18:00 to 9:00
.It Ar 0,7
Sunday and on holidays, all 24 hours
.El
.Pp
The use of this keyword is optional.
.El
.El
.Sh IDLETIME CALCULATION AND SHORT-HOLD MODE
.Bl -tag -width "incoming calls
.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
.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
|<unchecked-window>|<checkwindow>|<safetywindow>|
| | | |
+------------------+-------------+--------------+
| | | |
| |<-idle-time->|<earlyhangup->|
|<--------------unitlength--------------------->|
.Ed
.Pp
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
.Pp
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
.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
.An -nosplit
The
.Xr isdnd 8
daemon and this manual page were written by
.An Hellmuth Michaelis Aq hm@FreeBSD.org .
.Pp
Additions to this manual page by
.An Barry Scott Aq barry@scottb.demon.co.uk .