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