usr.sbin/i4b/isdnd/isdnd.rc.5

   1 .\"
   2 .\" Copyright (c) 1997, 2002 Hellmuth Michaelis. All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .\"     last edit-date: [Sun Aug 11 20:07:38 2002]
  28 .\"
  29 .Dd August 11, 2002
  30 .Dt ISDND.RC 5
  31 .Os
  32 .Sh NAME
  33 .Nm isdnd.rc
  34 .Nd isdn4bsd ISDN connection management daemon config file format
  35 .Sh DESCRIPTION
  36 The file
  37 .Pa /etc/isdn/isdnd.rc
  38 contains (if not otherwise specified on the command line) the runtime
  39 configuration for the
  40 .Xr isdnd 8
  41 ISDN connection management daemon which is part of the isdn4bsd package.
  42 .Pp
  43 The configuration file consists of keywords which start in column 1 followed by
  44 one or more spaces or tabs, an equal sign, one or more spaces or tabs
  45 and a keyword dependent parameter value.
  46 .Pp
  47 A line beginning with '#' is treated as a comment line.
  48 .Pp
  49 For keywords requiring the specification of a boolean value, the truth
  50 value can be either
  51 .Em yes
  52 or
  53 .Em on
  54 while the false value can be either
  55 .Em no
  56 or
  57 .Em off .
  58 .Pp
  59 The configuration file consists of one
  60 .Em system
  61 section, one or more optional
  62 .Em controller
  63 sections and one or more
  64 .Em entry
  65 sections.
  66 In the
  67 .Em system
  68 section parameters regarding the daemon operation or parameters
  69 not associated with a single remote connection can be set.
  70 In the
  71 .Em controller
  72 section parameters regarding a particular controller can be set.
  73 In the
  74 .Em entry
  75 section(s) parameters directly associated with a single remote
  76 connection can be set.
  77 .Pp
  78 The following keywords are recognized by
  79 .Nm isdnd :
  80 .Pp
  81 .Bl -tag -width system
  82 .It Li system
  83 This keyword starts the system configuration section.
  84 It must not
  85 have a parameter and may be used only once.
  86 The keyword is mandatory.
  87 The following keywords are valid in the system configuration section:
  88 .Bl -tag -width useacctfile
  89 .It Li acctall
  90 If this parameter is set to
  91 .Em on ,
  92 accounting information is written even if the local site was not charged
  93 or no charging information is available or is not subscribed.
  94 (optional)
  95 .It Li acctfile
  96 Specifies the name of the accounting file which is used when the keyword
  97 .Em useacctfile
  98 (see below) is set to
  99 .Em on .
 100 See also system keyword
 101 .Em rotatesuffix .
 102 If this keyword is omitted the system default is used.
 103 (optional)
 104 .It Li add-prefix
 105 If set to
 106 .Em on ,
 107 for incoming numbers, have a look at the "type of number" indicator and
 108 adjust the number as specified by the
 109 .Em prefix-national
 110 and
 111 .Em prefix-international
 112 keywords described later.
 113 If this keyword is omitted, the system default (off) is used.
 114 (optional)
 115 .It Li aliasing
 116 If this parameter is set to
 117 .Em on ,
 118 alias processing of telephone-number to name is enabled (see also the
 119 .Em aliasfile
 120 keyword below).
 121 The default is off.
 122 (optional)
 123 .It Li aliasfile
 124 Specifies the name of the telephone number-to-name alias database file shared
 125 with the
 126 .Xr isdntel 8
 127 utility when alias processing is enabled via the
 128 .Em aliasing
 129 keyword.
 130 (optional)
 131 .It Li beepconnect
 132 In full-screen mode, if this parameter is set to
 133 .Em on ,
 134 ring the bell when connecting or disconnecting a call.
 135 .It Li extcallattr
 136 If this parameter is set to
 137 .Em on ,
 138 the extended caller attributes "screening indicator" and "presentation
 139 indicator" are written to the log-file.
 140 The default is off.
 141 (optional)
 142 .It Li holidayfile
 143 Specifies the name of the holiday file containing the dates of holidays.
 144 This file is used in conjunction with the
 145 .Em valid
 146 keyword to lookup the dates of holidays.
 147 (optional)
 148 .It Li isdntime
 149 If this parameter is set to
 150 .Em on ,
 151 date/time information from the exchange (if provided) is written to the
 152 log-file.
 153 The default is off.
 154 (optional)
 155 .It Li mailer
 156 This keyword is used to specify the path/name of a mail program
 157 which is able to use the "-s" flag to specify a subject on its
 158 command line.
 159 In case of a fatal error exit of
 160 .Nm
 161 this program is used to send mail to an administrator specified by
 162 the keyword
 163 .Em mailto .
 164 (optional)
 165 .It Li mailto
 166 This keyword is used to specify the email address of someone to notify
 167 in case of a fatal error exit of
 168 .Nm .
 169 (See also keyword
 170 .Em mailer ) .
 171 (optional)
 172 .It Li monitor-allowed
 173 If this parameter is set to
 174 .Em on
 175 or
 176 .Em yes ,
 177 monitoring via a local or remote machine is enabled.
 178 This parameter is optional and is set to
 179 .Em off
 180 by default.
 181 .It Li monitor-port
 182 sets the TCP port number for remote monitoring.
 183 This integer parameter is optional and is set to port 451 by default.
 184 .It Li monitor
 185 This keyword specifies a local socket name or a host or network for remote
 186 monitoring.
 187 The
 188 .Em monitor
 189 specification may either be:
 190 .Pp
 191 .Bl -tag -width Ds -compact
 192 .It Ar the name of a local (UNIX-domain) socket
 193 this MUST start with a "/", example: /var/run/isdn-monitor
 194 .It Ar a dotted-quad host specification
 195 example: 192.168.1.2
 196 .It Ar a dotted-quad network address with netmask
 197 example: 192.168.1.0/24
 198 .It Ar a resolvable host name
 199 example: localhost
 200 .It Ar a resolvable network name with netmask
 201 example: up-vision-net/24
 202 .El
 203 .It Li monitor-access
 204 This keyword specifies the access rights for a previously used
 205 .Em monitor
 206 keyword.
 207 The supported access rights are:
 208 .Pp
 209 .Bl -tag -width Ds -compact
 210 .It Ar fullcmd
 211 .It Ar restrictedcmd
 212 .It Ar channelstate
 213 .It Ar logevents
 214 .It Ar callin
 215 .It Ar callout
 216 .El
 217 .It Li prefix-international
 218 In conjunction with the
 219 .Em add-prefix
 220 switch (see above), specify the prefix number string for incoming numbers
 221 with the international number tag.
 222 If aliases are used, they have to be adjusted accordingly.
 223 (optional)
 224 .It Li prefix-national
 225 In conjunction with the
 226 .Em add-prefix
 227 switch (see above), specify the prefix number string for incoming numbers
 228 with the national number tag.
 229 If aliases are used, they have to be adjusted accordingly.
 230 (optional)
 231 .It Li ratesfile
 232 Specifies the name of the ratesfile.
 233 If this keyword is omitted the system
 234 default is used.
 235 (optional)
 236 .It Li regexpr
 237 This keyword is used to specify regular expressions.
 238 It can be specified
 239 more than once up to a compile time dependent value (currently set to 5 by
 240 the MAX_RE definition in the source).
 241 .Pp
 242 All specified regular expressions are compared to the log strings at runtime
 243 and if a match is found, a program is run with the log text as a parameter
 244 (see also the keyword
 245 .Em regprog
 246 below).
 247 .Pp
 248 For an explanation how regular expressions are specified, please have a
 249 look at
 250 .Xr re_format 7
 251 and
 252 .Xr regex 3 .
 253 The
 254 .Em extended
 255 regular expression syntax is supported here.
 256 .Pp
 257 Hint: it might be necessary to properly quote the expression to avoid
 258 improper interpretation by the configuration file parser.
 259 (optional)
 260 .It Li regprog
 261 This keyword is used to specify the name of a program which is run in
 262 case a corresponding regular expression is matched by a logging string.
 263 .Nm Isdnd
 264 expects to find the program below the path
 265 .Pa /etc/isdn
 266 which is prepended to the string specified as a parameter to this keyword.
 267 (optional)
 268 .It Li rotatesuffix
 269 Specifies a suffix for renaming the log- and the accounting-filename.
 270 In case
 271 rotatesuffix is used and a USR1 signal is sent to isdnd, the log-file and the
 272 accounting file is not only closed and reopened but the old log-file is also
 273 renamed to the former filename with the rotatesuffix string appended.
 274 If this keyword is omitted, the log-files are just closed and reopened; this
 275 is also the default behavior.
 276 (optional)
 277 .It Li rtprio
 278 Specifies the real-time priority
 279 .Nm isdnd
 280 runs at as an integer value in the range 0...31 with 0 being the highest
 281 priority.
 282 This keyword is optional; if not specified the process priority of
 283 .Nm isdnd
 284 is not touched in any way.
 285 ( See also
 286 .Xr rtprio 1 ) .
 287 This keyword is only available if
 288 .Nm
 289 was compiled with -DUSE_RTPRIO.
 290 .It Li useacctfile
 291 If this parameter is set to
 292 .Em on
 293 charging (if available) and accounting information is written to the
 294 accounting file.
 295 (optional)
 296 .El
 297 .It Li controller
 298 This keyword starts the controller configuration section.
 299 It must not
 300 have a parameter and may be used once for every controller.
 301 The keyword
 302 is optional.
 303 The following keywords are valid in a controller
 304 configuration section:
 305 .Bl -tag -width useacctfile
 306 .It Li protocol
 307 This keyword is used to set the D-channel protocol for the S0-bus a
 308 controller is connected to.
 309 The following parameters are currently
 310 supported:
 311 .Pp
 312 .Bl -tag -width calledback -compact
 313 .It Ar dss1
 314 The DSS1 or so-called "Euro-ISDN" D-channel protocol according to
 315 ITU Recommendations Q.921 and Q.931.
 316 .It Ar d64s
 317 An ISDN leased line with a single B-channel (called D64S in Germany).
 318 .El
 319 .It Li firmware
 320 This keyword is used like
 321 .Li firmware Ns = Ns Ar /path/to/file
 322 to download the
 323 firmware to active controllers supported by the
 324 .Em iavc
 325 driver (AVM B1, T1).
 326 This keyword is supported for all controller types,
 327 and causes
 328 .Dv I4B_CTRL_DOWNLOAD
 329 ioctl to be invoked with the specified file
 330 as an argument.
 331 In systems equipped with both active and passive adapters,
 332 and the passive cards being detected first, dummy
 333 .Ql controller
 334 entries
 335 are required for the passive cards to get the correct firmwares to
 336 correct adapters.
 337 .El
 338 .It Li entry
 339 This keyword starts one configuration entry.
 340 It must not have a parameter.
 341 This keyword must be used at least once.
 342 The following keywords are valid in an entry section:
 343 .Bl -tag -width unitlengthsrc
 344 .It Li answerprog
 345 This keyword is used to specify the name of a program which is run in
 346 case an incoming telephone connection specified
 347 .Em answer
 348 in its configuration entry.
 349 The default name is
 350 .Em answer .
 351 .Nm Isdnd
 352 expects to find this program beneath the path
 353 .Pa /etc/isdn
 354 which is prepended to the string specified as a parameter to this keyword.
 355 (optional)
 356 .It Li alert
 357 is used to specify a time in seconds to wait before accepting a call.
 358 This
 359 keyword is only usable for incoming telephone calls (dialin-reaction = answer).
 360 It is used to have a chance to accept an incoming call on the phone before
 361 the answering machine starts to run.
 362 The minimum value for the alert parameter
 363 is 5 seconds and the maximum parameter allowed is 180 seconds.
 364 (optional)
 365 .It Li b1protocol
 366 The B channel layer 1 protocol used for this connection.
 367 The keyword is mandatory.
 368 The currently configurable values are:
 369 .Pp
 370 .Bl -tag -width Ds -compact
 371 .It Ar hdlc
 372 HDLC framing.
 373 .It Ar raw
 374 No framing at all (used for telephony).
 375 .El
 376 .It Li bcap
 377 Use a special bearer capability for this connection.
 378 The keyword is optional.
 379 .Pp
 380 Any other value than
 381 .Em dov
 382 sets the bearer capability as configured by the
 383 .Em b1protocol
 384 keyword (see above).
 385 The currently configurable values are:
 386 .Pp
 387 .Bl -tag -width Ds -compact
 388 .It Ar dov
 389 This connection is a
 390 .Em Dov (Data over Voice)
 391 connection.
 392 The b1protocol keyword must be set to
 393 .Em hdlc .
 394 This feature is experimental and does work on outgoing calls only.
 395 .El
 396 .It Li budget-calloutperiod
 397 is used to specify a time period in seconds.
 398 Within this period, the number of calls
 399 specified by
 400 .Em budget-calloutncalls
 401 are allowed to succeed, any further attempt to call out will be blocked for the rest
 402 of the time left in the time period.
 403 (optional)
 404 .It Li budget-calloutncalls
 405 The number of outgoing calls allowed within the time period specified by
 406 .Em budget-calloutperiod .
 407 (optional)
 408 .It Li budget-calloutsfile
 409 A path/filename to which the number of successful callouts are written.
 410 The contents of the file is preserved when it exists during startup of isdnd.
 411 The format of this file is: start time, last update time, number of calls.
 412 (optional)
 413 .It Li budget-calloutsfile-rotate
 414 If set to
 415 .Em on
 416 rotate budget-calloutsfile every night when an attempt is made to update
 417 the file on a new day.
 418 The statistics for the previous day are written to
 419 a file with the filename specified by budget-calloutsfile to which a hyphen
 420 and the new day's (!) day of month number is appended.
 421 (optional)
 422 .It Li budget-callbackperiod
 423 .It Li budget-callbackncalls
 424 .It Li budget-callbacksfile
 425 .It Li budget-calloutsfile-rotate
 426 See
 427 .Em budget-calloutperiod ,
 428 .Em budget-calloutncalls ,
 429 .Em budget-calloutsfile ,
 430 and
 431 .Em budget-calloutsfile-rotate
 432 above.
 433 These are used to specify the budgets for calling back a remote site.
 434 .It Li callbackwait
 435 The time in seconds to wait between hanging up the call from a remote site
 436 and calling back the remote site.
 437 (optional)
 438 .It Li calledbackwait
 439 The time in seconds to wait for a remote site calling back the local site
 440 after a call from the local site to the remote site has been made.
 441 (optional)
 442 .It Li clone
 443 This causes the contents of the specified entry to be copied from the
 444 existing named entry to the current one.
 445 When using this feature at least a new entry specific
 446 .Ql name
 447 and
 448 .Ql usrdeviceunit
 449 value should be specified for the current entry.
 450 .It Li connectprog
 451 specifies a program run every time after a connection is established and
 452 address negotiation is complete (i.e.: the connection is usable).
 453 .Nm Isdnd
 454 expects to find the program below the path
 455 .Pa /etc/isdn
 456 which is prepended to the string specified as a parameter to this keyword.
 457 The programs specified by connect and disconnect will get the following
 458 command line arguments: -d (device) -f (flag) [ -a (addr) ] where
 459 .Em device
 460 is the name of device, e.g.\& "isp0",
 461 .Em flag
 462 will be "up" if connection just got up, or "down" if interface changed to down
 463 state and
 464 .Em addr
 465 the address that got assigned to the interface as a dotted-quad ip address
 466 (optional, only if it can be figured out by isdnd).
 467 (optional)
 468 .It Li dialin-reaction
 469 Used to specify what to do when an incoming connection request is received.
 470 The keyword is mandatory.
 471 The currently supported parameters are:
 472 .Pp
 473 .Bl -tag -width calledback -compact
 474 .It Ar accept
 475 Accept an incoming call.
 476 .It Ar reject
 477 Reject an incoming call.
 478 .It Ar ignore
 479 Ignore an incoming call.
 480 .It Ar answer
 481 Start telephone answering for an incoming voice call.
 482 .It Ar callback
 483 When a remote site calls, hang up and call back the remote site.
 484 .El
 485 .It Li dialout-type
 486 This keyword is used to configure what type of dialout mode is used.
 487 The keyword is mandatory.
 488 The currently supported parameters are:
 489 .Pp
 490 .Bl -tag -width Ds -compact
 491 .It Ar normal
 492 Normal behavior, call the remote site which is supposed to accept the call.
 493 .It Ar calledback
 494 Callback behavior, call the remote side which rejects the call and calls
 495 us back.
 496 .El
 497 .It Li dialrandincr
 498 When dialing or re-dialing and this parameter is set to
 499 .Em on ,
 500 the dial retry time is added with a random value (currently 0...3 seconds)
 501 to minimize the chance of two sites dialing synchronously so each gets a busy
 502 each time it dials because the other side is also dialing.
 503 .It Li dialretries
 504 The number of dialing retries before giving up.
 505 Setting this to
 506 .Em -1
 507 gives an unlimited number of retries!
 508 (optional)
 509 .It Li direction
 510 This keyword is used to configure if incoming and outgoing, incoming-only or
 511 outgoing only connections are possible.
 512 The keyword is optional, the default is
 513 .Em inout .
 514 .Pp
 515 The currently supported parameters are:
 516 .Pp
 517 .Bl -tag -width Ds -compact
 518 .It Ar inout
 519 Normal behavior, connection establishment is possible from remote and local.
 520 .It Ar in
 521 Only incoming connections are possible.
 522 .It Ar out
 523 Only outgoing connections are possible.
 524 .El
 525 .It Li disconnectprog
 526 specifies a program run every time after a connection was shut down.
 527 .Nm Isdnd
 528 expects to find the program below the path
 529 .Pa /etc/isdn
 530 which is prepended to the string specified as a parameter to this keyword.
 531 (optional)
 532 .It Li downtries
 533 is used to configure the number of unsuccessful tries (= retry cycles!) before
 534 the interface is disabled (for
 535 .Em downtime
 536 seconds).
 537 (see also the keyword
 538 .Em usedown
 539 further up).
 540 This keyword is optional.
 541 .It Li downtime
 542 is used to configure the time in seconds an interface is disabled
 543 after the configured number of
 544 .Em downtries .
 545 (see also the keyword
 546 .Em usedown
 547 further up).
 548 This keyword is optional and is set to 60 seconds by default.
 549 .It Li earlyhangup
 550 A (safety) time in seconds which specifies the time to hang up before an
 551 expected next charging unit will occur.
 552 (optional)
 553 .It Li idle-algorithm-outgoing
 554 The algorithm used to determine when to hang up an outgoing call when the
 555 line becomes idle.
 556 The current algorithms are:
 557 .Pp
 558 .Bl -tag -width calledback -compact
 559 .It Ar fix-unit-size
 560 idle algorithm which assumes fixed sized charging units during the whole call.
 561 .It Ar var-unit-size
 562 idle algorithm which assumes that the charging is time based after the first
 563 units time has expired.
 564 .El
 565 .It Li idletime-outgoing
 566 The time in seconds an outgoing connection must be idle before hanging up.
 567 An idle timeout of zero disables this functionality.
 568 (optional)
 569 .It Li idletime-incoming
 570 The time in seconds an incoming connection must be idle before hanging up.
 571 An idle timeout of zero disables this functionality.
 572 (optional)
 573 .It Li isdncontroller
 574 The ISDN controller number to be used for connections for this entry.
 575 (mandatory)
 576 .It Li isdnchannel
 577 The ISDN controller channel number to be used for connections for this entry.
 578 In case a channel is explicitly selected here, the SETUP message will request
 579 this channel but mark the request as
 580 .Em preferred
 581 (the indicated channel is preferred) instead of exclusive (only the indicated
 582 channel is acceptable).
 583 Thus the exchange is still free to select another
 584 than the requested channel!
 585 (mandatory)
 586 .It Li isdntxdel-incoming
 587 A delay value suitable for the
 588 .Xr timeout 9
 589 kernel subroutine to delay the transmission of the first packet after a
 590 successful connection is made by this value for
 591 .Em incoming
 592 ISDN connections.
 593 The specification unit is 1/100 second.
 594 A zero (0) disables
 595 this feature and is the default value.
 596 This feature is implemented (and makes
 597 sense only) for the
 598 .Xr i4bipr 4
 599 IP over raw HDLC ISDN driver.
 600 (optional)
 601 .It Li isdntxdel-outgoing
 602 A delay value suitable for the
 603 .Xr timeout 9
 604 kernel subroutine to delay the transmission of the first packet after a
 605 successful connection is made by this value for
 606 .Em outgoing
 607 ISDN connections.
 608 The specification unit is 1/100 second.
 609 A zero (0) disables
 610 this feature and is the default value.
 611 This feature is implemented (and makes
 612 sense only) for the
 613 .Xr i4bipr 4
 614 IP over raw HDLC ISDN driver.
 615 (optional)
 616 .It Li local-phone-dialout
 617 The local telephone number used when the local site dials out.
 618 When dialing
 619 out to a remote site, the number specified here is put into the
 620 .Em "Calling Party Number Information Element" .
 621 .Pp
 622 This keyword is mandatory for the
 623 .Em ipr
 624 user-land interfaces.
 625 .It Li local-subaddr-dialout
 626 The local subaddress used when the local site dials out.
 627 When dialing
 628 out to a remote site, the subaddress specified here is put into the
 629 .Em "Calling Party Subaddress Information Element" .
 630 .Pp
 631 This keyword is mandatory for the
 632 .Em ipr
 633 user-land interfaces.
 634 .It Li local-phone-incoming
 635 The local telephone number used for verifying the destination of incoming
 636 calls.
 637 When a remote site dials in, this number is used to verify that it
 638 is the local site which the remote site wants to connect to.
 639 It is compared
 640 with the
 641 .Em "Called Party Number Information Element"
 642 got from the telephone exchange.
 643 .Pp
 644 This keyword is mandatory for the
 645 .Em ipr
 646 interfaces.
 647 .It Li local-subaddr-incoming
 648 The local subaddress used for verifying the destination of incoming
 649 calls.
 650 When a remote site dials in, this subaddress is used to verify that it
 651 is the local site which the remote site wants to connect to.
 652 It is compared
 653 with the
 654 .Em "Called Party Subaddress Information Element"
 655 got from the telephone exchange.
 656 .Pp
 657 This keyword is mandatory for the
 658 .Em ipr
 659 interfaces.
 660 .It Li name
 661 Defines a symbolic name for this configuration entry.
 662 Its purpose is to
 663 use this name in the full-screen display for easy identification of a link
 664 to a remote site and for accounting purposes.
 665 (mandatory)
 666 .It Li maxconnecttime
 667 Specify a maximum connection time in seconds.
 668 Use this to define an absolute
 669 upper limit for a connection on the B-channel to last.
 670 .Em CAUTION:
 671 This feature is used to limit the connection time, _not_ number of attempts
 672 to establish a connection: when using this please take care to also enable
 673 the use of budgets to limit the connection establish attempts (otherwise
 674 the line will cycle thru an endless loop of connections and reconnections
 675 which will have an undesired effect on your telco bill)!
 676 .It Li ppp-auth-paranoid
 677 If set to
 678 .Em no ,
 679 the remote site is not required to prove its authentity for connections
 680 that are initiated by the local site.
 681 The default is
 682 .Em yes
 683 and requires the remote site to always authenticate.
 684 .Pp
 685 This keyword is only used if
 686 .Em ppp-send-auth
 687 has been set to pap or chap for an
 688 .Em isp
 689 PPP interface.
 690 (optional)
 691 .It Li ppp-auth-rechallenge
 692 Set to
 693 .Em no ,
 694 if the other side does not support re-challenging for chap.
 695 The default is
 696 .Em yes ,
 697 which causes verification of the remote site's authentity once in a while.
 698 .Pp
 699 This keyword is only used if
 700 .Em ppp-expect-auth
 701 has been set to chap for an
 702 .Em isp
 703 PPP interface.
 704 (optional)
 705 .It Li ppp-expect-auth
 706 The local site expects the authentity of the remote site to be proved by
 707 the specified method.
 708 The supported methods are:
 709 .Pp
 710 .Bl -tag -width Ds -compact
 711 .It Ar none
 712 Do not require the other side to authenticate.
 713 Typical uses are dial-out to an ISP
 714 (many ISPs do not authenticate themselves to clients)
 715 or offering anonymous dial-in at the local site.
 716 .It Ar chap
 717 The preferred authentication method, which does not require a password to be sent
 718 in the clear.
 719 .It Ar pap
 720 The unprotected authentication method, which allows anybody watching the wire
 721 to grab name and password.
 722 .El
 723 .Pp
 724 If
 725 .Em ppp-auth-paranoid
 726 is set to
 727 .Em no
 728 (the default is
 729 .Em yes )
 730 outgoing connections will not require the remote site to authenticate itself.
 731 .Pp
 732 This keyword is only used for the
 733 .Em isp
 734 PPP interfaces.
 735 (optional)
 736 .It Li ppp-expect-name
 737 The name that has to be provided by the remote site to prove its authentity.
 738 .Pp
 739 This keyword is only used if
 740 .Em ppp-expect-auth
 741 has been set to pap or chap for an
 742 .Em isp
 743 PPP interface.
 744 (optional)
 745 .It Li ppp-expect-password
 746 The secret that has to be provided by the remote site to prove its authentity.
 747 .Pp
 748 This keyword is only used if
 749 .Em ppp-expect-auth
 750 has been set to pap or chap for an
 751 .Em isp
 752 PPP interface.
 753 (optional)
 754 .It Li ppp-send-auth
 755 The authentication method required by the remote site.
 756 The currently supported parameters are:
 757 .Pp
 758 .Bl -tag -width Ds -compact
 759 .It Ar none
 760 The remote site does not expect or support authentication.
 761 .It Ar chap
 762 The preferred authentication method, which does not require a password to be sent
 763 in the clear.
 764 .It Ar pap
 765 The unprotected authentication method, which allows anybody watching the wire
 766 to grab name and password.
 767 .El
 768 .Pp
 769 This keyword is only used for the
 770 .Em isp
 771 PPP interfaces.
 772 (optional)
 773 .It Li ppp-send-name
 774 The authentication name sent to the remote site.
 775 .Pp
 776 This keyword is only used if
 777 .Em ppp-send-auth
 778 has been set to pap or chap for an
 779 .Em isp
 780 PPP interface.
 781 (optional)
 782 .It Li ppp-send-password
 783 The secret used to prove the local site's authentity to the remote site.
 784 .Pp
 785 This keyword is only used if
 786 .Em ppp-send-auth
 787 has been set to pap or chap for an
 788 .Em isp
 789 PPP interface.
 790 (optional)
 791 .It Li ratetype
 792 The rate entry used from the rates file.
 793 (optional)
 794 .Pp
 795 For example, ratetype=0 selects lines beginning "ra0" in /etc/isdn/isdnd.rates;
 796 (typically ra0 lines are a set of tables for local call rates on different
 797 days of the week & times per day).
 798 .It Li recoverytime
 799 The time in seconds to wait between dial retries.
 800 (optional)
 801 .It Li remdial-handling
 802 is used to specify the dialout behavior in case more than one outgoing
 803 number is specified.
 804 The currently supported parameters are:
 805 .Pp
 806 .Bl -tag -width Ds -compact
 807 .It Ar first
 808 For every new (non-retry) call setup, start with the first number.
 809 .It Ar last
 810 For every new (non-retry) call setup, start with the last number with
 811 which a successful connection was made.
 812 .It Ar next
 813 For every new (non-retry) call setup, start with the next number which
 814 follows the last one used.
 815 .El
 816 .It Li remote-phone-dialout
 817 The remote telephone number used when the local site dials out.
 818 When dialing
 819 out to a remote site, the number specified here is put into the
 820 .Em "Called Party Number Information Element" .
 821 .Pp
 822 This keyword is mandatory for the
 823 .Em ipr
 824 interfaces.
 825 It may be specified more than once to try to dial to several
 826 numbers until one succeeds.
 827 .It Li remote-subaddr-dialout
 828 The remote subaddress used when the local site dials out.
 829 When dialing
 830 out to a remote site, the subaddress specified here is put into the
 831 .Em "Called Party Subaddress Information Element" .
 832 .Pp
 833 This keyword is mandatory for the
 834 .Em ipr
 835 interfaces.
 836 It may be specified more than once to linked it to the
 837 remote-phone-dialout numbers until one succeeds.
 838 .It Li remote-phone-incoming
 839 The remote telephone number used to verify an incoming call.
 840 When a remote site
 841 dials in, this number is used to verify that it is the correct remote site
 842 which is herewith authorized to connect into the local system.
 843 This parameter
 844 is compared against the
 845 .Em "Calling Party Number Information Element"
 846 got from the telephone exchange.
 847 .Pp
 848 This keyword is mandatory for the ipr interfaces.
 849 .Pp
 850 This keyword may have a wildcard parameter '*' to permit anyone dialing in.
 851 .It Li remote-subaddr-incoming
 852 The remote subaddress used to verify an incoming call.
 853 When a remote site
 854 dials in, this subaddress is used to verify that it is the correct remote site
 855 which is herewith authorized to connect into the local system.
 856 This parameter
 857 is compared against the
 858 .Em "Calling Party Subaddress Information Element"
 859 got from the telephone exchange.
 860 .Pp
 861 This keyword is mandatory for the ipr interfaces.
 862 .Pp
 863 This keyword may have a wildcard parameter '*' to permit anyone dialing in.
 864 .It Li unitlength
 865 The length of a charging unit in seconds.
 866 This is used in conjunction with
 867 the idletime to decide when to hang up a connection.
 868 (optional)
 869 .It Li unitlengthsrc
 870 This keyword is used to specify from which source
 871 .Xr isdnd 8
 872 takes the unitlength for short-hold mode.
 873 The currently configurable values are:
 874 .Pp
 875 .Bl -tag -width Ds -compact
 876 .It Ar none
 877 Then unitlength is not specified anywhere.
 878 .It Ar cmdl
 879 Use the unitlength specified on the command line.
 880 .It Ar conf
 881 Use the unitlength specified in the configuration file with the keyword
 882 .Em unitlength .
 883 .It Ar rate
 884 Use the unitlength from the ratesfile specified in the configuration
 885 file with the keyword
 886 .Em ratetype .
 887 .It Ar aocd
 888 Use a dynamically calculated unitlength in case AOCD is subscribed on
 889 the ISDN line.
 890 (AOCD is an acronym for ``Advice Of Charge During the call''
 891 which is a service provided by the telecommunications (ie phone) provider,
 892 to indicate billable units).
 893 .El
 894 .It Li usrdevicename
 895 Specifies the user-land interface which is used for interfacing ISDN B channel
 896 data to the user-land.
 897 The keyword is mandatory.
 898 This keyword accepts the following parameters:
 899 .Pp
 900 .Bl -tag -width Ds -compact
 901 .It Ar ipr
 902 This parameter configures a raw HDLC IP over ISDN interface.
 903 .It Ar isp
 904 This parameter configures a synchronous PPP over ISDN interface.
 905 .It Ar rbch
 906 This specifies a Raw B CHannel access interface.
 907 .It Ar tel
 908 ISDN telephony.
 909 .It Ar ing
 910 configures an ISDN B-channel to NetGraph interface.
 911 .El
 912 .It Li usrdeviceunit
 913 Specifies the unit number for the device which is specified with
 914 usrdevicename.
 915 .It Li usedown
 916 is used to enable the use of the keywords
 917 .Em downtries
 918 and
 919 .Em downtime
 920 in the entries section(s).
 921 It is used in the
 922 .Nm isdnd
 923 daemon to dynamically enable and disable the IP interfaces to avoid excessive
 924 dialing activities in case of transient failures (such as busy lines).
 925 This parameter is optional and is set to
 926 .Em off
 927 by default.
 928 .It Li usesubaddr
 929 is used to enable the use of subaddresses.
 930 This parameter is optional and is set to
 931 .Em off
 932 by default.
 933 .It Li valid
 934 .Em Note :
 935 this feature is considered experimental!
 936 The parameter to this keyword is a string specifying a time range within
 937 which this entry is valid.
 938 The time specification consists of a list of weekdays and/or a holiday
 939 indicator ( see also the
 940 .Em holidayfile
 941 keyword in the system section ) separated by commas followed by an optional
 942 daytime range specification in the form hh:mm-hh:mm.
 943 The weekdays are specified as numbers from 0 to 6 and the number 7 for
 944 holidays:
 945 .Pp
 946 .Bl -tag -width Ds -compact
 947 .It Ar 0
 948 Sunday
 949 .It Ar 1
 950 Monday
 951 .It Ar 2
 952 Tuesday
 953 .It Ar 3
 954 Wednesday
 955 .It Ar 4
 956 Thursday
 957 .It Ar 5
 958 Friday
 959 .It Ar 6
 960 Saturday
 961 .It Ar 7
 962 a Holiday
 963 .El
 964 .Pp
 965 The following examples describe the "T-ISDN xxl" tariff of the german Telekom:
 966 .Bl -tag -width Ds -compact
 967 .It Ar 1,2,3,4,5,6,09:00-18:00
 968 Monday through Saturday, daytime 9:00 to 18:00
 969 .It Ar 1,2,3,4,5,6,18:00-9:00
 970 Monday through Saturday, nighttime 18:00 to 9:00
 971 .It Ar 0,7
 972 Sunday and on holidays, all 24 hours
 973 .El
 974 .Pp
 975 The use of this keyword is optional.
 976 .El
 977 .El
 978 .Sh IDLETIME CALCULATION AND SHORT-HOLD MODE
 979 .Bl -tag -width "incoming calls
 980 .It Li incoming calls
 981 It is assumed that the calling side knows most about charging structures and
 982 such and as a consequence only the keyword
 983 .Em idletime-incoming
 984 has a function for incoming calls.
 985 .Pp
 986 For incoming calls the line is constantly monitored, and in case there was
 987 not traffic taking place for the time in seconds specified by
 988 .Em idletime-incoming
 989 the call is closed.
 990 .Pp
 991 Typically,
 992 .Em idletime-incoming
 993 is used as a last resort and is therefore set much higher than a charging
 994 unit time: typical values are one to five minutes.
 995 .It Li outgoing calls
 996 Outgoing call disconnect time can be setup in one of three ways:
 997 .Bl -tag -width "shorthold mode
 998 .It Li simple mode
 999 For simple mode, the
1000 .Em idle-algorithm-outgoing
1001 must be
1002 .Em fix-unit-size
1003 and the selected
1004 .Em unitlength
1005 must be 0 (zero) and
1006 .Em idletime-outgoing
1007 greater zero.
1008 .Pp
1009 The outgoing traffic is constantly monitored, and in case there was
1010 not traffic taking place for the time in seconds specified by
1011 .Em idletime-outgoing
1012 the call is closed.
1013 .Pp
1014 Typical values in simple mode are 10 to 30 seconds.
1015 .It Li shorthold mode for fixed unit charging
1016 For shorthold mode, the
1017 .Em idle-algorithm-outgoing
1018 must be
1019 .Em fix-unit-size
1020 and the selected
1021 .Em unitlength
1022 and
1023 .Em idletime-outgoing
1024 must be greater than 0 (zero);
1025 .Em earlyhangup
1026 must be >= 0 (zero).
1027 .Bd -literal
1028 |<unchecked-window>|<checkwindow>|<safetywindow>|
1029 |                  |             |              |
1030 +------------------+-------------+--------------+
1031 |                  |             |              |
1032 |                  |<-idle-time->|<earlyhangup->|
1033 |<--------------unitlength--------------------->|
1034 .Ed
1035 .Pp
1036 During the unchecked window which is (unitlength - (idle-time+earlyhangup))
1037 in length, no idle check is done.
1038 After the unchecked window has ended,
1039 the line is checked for idle-time length if no traffic takes place.
1040 In case
1041 there was traffic detected in the check-window, the same procedure is restarted
1042 at the beginning of the next unit.
1043 In case no traffic was detected during
1044 the check-window, the line is closed at the end of the check window.
1045 .Pp
1046 Notice:
1047 .Em unitlength
1048 must (!) be greater than the sum of
1049 .Em idletime-outgoing
1050 and
1051 .Em earlyhangup !
1052 .It Li shorthold mode for variable unit charging
1053 For shorthold mode, the
1054 .Em idle-algorithm-outgoing
1055 must be
1056 .Em var-unit-size
1057 and the selected
1058 .Em unitlength
1059 and
1060 .Em idletime-outgoing
1061 must be greater than 0 (zero);
1062 .Pp
1063 This shorthold mode is suitable when your calls are billed on
1064 the elapse time of the call plus a fixed connection charge.
1065 For example British Telecom bill this way.
1066 .Pp
1067 Each call is divided into two periods, the first is the
1068 .Em unchecked
1069 period and the second is the
1070 .Em checked .
1071 The
1072 .Em checked
1073 period starts 1 second before the first units time expires.
1074 .Pp
1075 During the
1076 .Em checked
1077 period if there is no traffic for
1078 .Em idle-time
1079 seconds the call is disconnected.
1080 .Pp
1081 .Bd -literal
1082 |<---unchecked------------------>|<------checked------>
1083 +------------------+-------------+
1084 |                  |<-idle-time->|
1085 |<--------------unitlength------->|
1086 .Ed
1087 .Pp
1088 Experience shows that useful values for idle-time are from 15 to 30 seconds.
1089 .Pp
1090 If idle-time is too short an application that is not yet finished with the
1091 network will cause a new call to be placed.
1092 .Pp
1093 .El
1094 .El
1095 .Sh FILES
1096 .Bl -tag -width /etc/isdn/isdnd.rc -compact
1097 .It Pa /etc/isdn/isdnd.rc
1098 The default configuration file for the
1099 .Nm isdnd
1100 ISDN daemon.
1101 .El
1102 .Sh SEE ALSO
1103 .Xr regex 3 ,
1104 .Xr re_format 7 ,
1105 .Xr isdnd 8 ,
1106 .Xr isdnmonitor 8
1107 .Sh AUTHORS
1108 .An -nosplit
1109 The
1110 .Xr isdnd 8
1111 daemon and this manual page were written by
1112 .An Hellmuth Michaelis Aq hm@FreeBSD.org .
1113 .Pp
1114 Additions to this manual page by
1115 .An Barry Scott Aq barry@scottb.demon.co.uk .