7f0e19d9b46ba72381193e97ca27b22f71d0103c
[dragonfly.git] / usr.sbin / i4b / isdnd / isdnd.8
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 .\"     $Id: isdnd.8,v 1.29 2000/05/02 11:50:28 hm Exp $
26 .\"
27 .\" $FreeBSD: src/usr.sbin/i4b/isdnd/isdnd.8,v 1.9.2.7 2003/03/11 21:13:49 trhodes Exp $
28 .\" $DragonFly: src/usr.sbin/i4b/isdnd/isdnd.8,v 1.2 2003/06/17 04:29:54 dillon Exp $
29 .\"
30 .\"     last edit-date: [Wed May  2 10:48:30 2001]
31 .\"
32 .Dd May 2, 2001
33 .Dt ISDND 8
34 .Os
35 .Sh NAME
36 .Nm isdnd
37 .Nd isdn4bsd ISDN connection management daemon
38 .Sh SYNOPSIS
39 .Nm
40 .Op Fl c Ar configfile
41 .Op Fl d Ar debuglevel
42 .Op Fl f
43 .Op Fl F
44 .Op Fl l
45 .Op Fl L Ar logfile
46 .Op Fl P
47 .Op Fl r Ar device
48 .Op Fl s Ar facility
49 .Op Fl t Ar terminaltype
50 .Op Fl u Ar charging unit length
51 .Op Fl m
52 .Sh DESCRIPTION
53 The
54 .Nm
55 utility
56 is the isdn4bsd package daemon which manages all ISDN related connection
57 and disconnection of ISDN devices supported by the package.
58 .Pp
59 The options are as follows:
60 .Bl -tag -width Ds
61 .It Fl c
62 Use
63 .Ar configfile
64 as the name of the runtime configuration filename for
65 .Nm
66 instead of the default file
67 .Li /etc/isdn/isdnd.rc .
68 .It Fl d
69 If debugging support is compiled into
70 .Nm
71 this option is used to specify the debugging level, or better which kind
72 of debugging messages are displayed.
73 The debugging level is the sum of the
74 following values:
75 .Pp
76 .Bl -tag -width Ds -compact -offset indent
77 .It Ar 0x001
78 general debugging.
79 .It Ar 0x002
80 rates calculation.
81 .It Ar 0x004
82 timing calculations.
83 .It Ar 0x008
84 state transitions.
85 .It Ar 0x010
86 retry handling.
87 .It Ar 0x020
88 dialing.
89 .It Ar 0x040
90 process handling.
91 .It Ar 0x080
92 isdn4bsd kernel i/o calls.
93 .It Ar 0x100
94 controller and channel busy/free messages.
95 .It Ar 0x200
96 isdnd.rc configuration file processing.
97 .It Ar 0x400
98 outgoing call budget handling.
99 .It Ar 0x800
100 valid keyword and holiday file processing.
101 .El
102 .Pp
103 The value can be specified in any number base supported by the
104 .Xr sscanf 3
105 library routine.
106 .Pp
107 In addition, this option accepts also the character 'n' as an argument to
108 disable displaying debug messages on the full-screen display.
109 .Pp
110 .It Fl f
111 Specifying this option causes
112 .Nm
113 to enter the full-screen mode of operation.
114 When operating in this mode,
115 entering the control character
116 .Em Control-L
117 causes the display to be refreshed and entering
118 .Em Carriage-Return
119 or
120 .Em Enter
121 will pop-up a command window.
122 Because the
123 .Nm
124 utility will not listen to messages while the command window is active,
125 this command window will disappear automatically after 5 seconds without
126 any command key press.
127 .Pp
128 While the command window is active,
129 .Em Tab
130 or
131 .Em Space
132 advances to the next menu item.
133 To execute a command, press
134 .Em Return
135 or
136 .Em Enter
137 for the highlighted menu item, or enter the number corresponding to the
138 item to be executed or enter the capitalized character in the menu item
139 description.
140 .It Fl l
141 If this option is set, logging is not done via the
142 .Xr syslogd 8
143 facility but instead is appended to a file.
144 .It Fl L
145 Specifies the name of the logfile which is used when the option
146 .Em -l
147 is set.
148 See also the keyword
149 .Em rotatesuffix
150 in the system section of
151 .Xr isdnd.rc 5 .
152 .It Fl P
153 This option prints out the parsed and verified isdnd configuration in the same
154 format as the isdnd.rc file.
155 This output can be used as an isdnd.rc file.
156 This
157 feature is especially useful when debugging an isdnd.rc file to see, what the
158 default settings of options are when they are not set in the isdnd.rc input
159 file.
160 .Pp
161 The
162 .Nm
163 exits after the printout is done.
164 .It Fl F
165 This option prevents
166 .Nm
167 to detach from the controlling tty and become a daemon.
168 .It Fl r
169 In conjunction with the
170 .Fl t
171 option,
172 .Ar device
173 specifies a terminal device which becomes the controlling tty for
174 .Nm
175 and on which the full-screen mode output is displayed.
176 .It Fl s
177 This option may be used to specify the logging facility in case
178 .Xr syslog 3
179 logging is configured and another facility than the default LOCAL0
180 facility shall be used.
181 The facility is to be specified as an integer in
182 the range 0-11 or 16-23 (see the file /usr/include/syslog.h).
183 .It Fl t
184 In conjunction with the
185 .Fl f
186 and
187 .Fl r
188 options,
189 .Ar terminaltype
190 specifies a terminal type or termcap entry name (such as vt220) for the device
191 used for
192 .Nm
193 full-screen output.
194 This is useful if an unused (no getty running) tty line is
195 used for full-screen output for which no
196 .Li TERM
197 environment variable exists.
198 .It Fl u
199 Specifies the length of a charging unit in case the config file entry
200 keyword
201 .Em unitlenghtsrc
202 is set to
203 .Em cmdl .
204 .It Fl m
205 If the isdn daemon is compiled with local or remote monitoring support,
206 this option disables all monitoring access.
207 It overrides the config
208 file option
209 .Em monitor-allowed .
210 .El
211 .Sh INTERACTION WITH THE KERNEL
212 The
213 .Nm
214 utility
215 communicates with the kernel part of isdn4bsd by receiving status and
216 event messages
217 .Xr ( read 2
218 from device
219 .Pa /dev/i4b )
220 and by transmitting commands and responses
221 .Xr ( ioctl 2
222 from device
223 .Pa /dev/i4b ) .
224 .Pp
225 The messages and message parameters are documented in the include
226 file
227 .Em /usr/include/machine/i4b_ioctl.h .
228 .Pp
229 Supported command and response messages (ioctls) to the kernel are:
230 .Bl -tag -width Ds -compact -offset indent
231 .It Ar I4B_CDID_REQ
232 Request a unique Call Description IDentifier (cdid) which identifies
233 uniquely a single interaction of the local D channel with the exchange.
234 .It Ar I4B_CONNECT_REQ
235 Actively request a call setup to a remote ISDN subscriber.
236 .It Ar I4B_CONNECT_RESP
237 Respond to an incoming call, either accept, reject or ignore it.
238 .It Ar I4B_DISCONNECT_REQ
239 Actively terminate a connection.
240 .It Ar I4B_CTRL_INFO_REQ
241 Request information about an installed ISDN controller card.
242 .It Ar I4B_DIALOUT_RESP
243 Give information about call setup to driver who requested dialing out.
244 .It Ar I4B_TIMEOUT_UPD
245 Update the kernels timeout value(s) in case of dynamically calculated
246 shorthold mode timing changes.
247 .It Ar I4B_UPDOWN_IND
248 Inform the kernel userland drivers about interface soft up/down status
249 changes.
250 .It Ar I4B_CTRL_DOWNLOAD
251 Download firmware to active card(s).
252 .It Ar I4B_ACTIVE_DIAGNOSTIC
253 Return diagnostic information from active cards.
254 .El
255 .Pp
256 .Pp
257 Supported status and event messages from the kernel are:
258 .Bl -tag -width Ds -compact -offset indent
259 .It Ar MSG_CONNECT_IND
260 An incoming call from a remote ISDN user is indicated.
261 .It Ar MSG_CONNECT_ACTIVE_IND
262 After an incoming call has been accepted locally or an outgoing call has
263 been accepted by a remote, the exchange signaled an active connection
264 and the corresponding B-channel is switched through.
265 .It Ar MSG_DISCONNECT_IND
266 A call was terminated.
267 .It Ar MSG_DIALOUT_IND
268 A userland interface driver requests the daemon to dial out (typically a
269 network interface when a packet arrives in its send queue).
270 .It Ar MSG_IDLE_TIMEOUT_IND
271 A call was terminated by the isdn4bsd kernel driver because a B-channel
272 idle timeout occurred.
273 .It Ar MSG_ACCT_IND
274 Accounting information from a network driver.
275 .It Ar MSG_CHARGING_IND
276 Charging information from the kernel.
277 .El
278 .Pp
279 .Ss OUTGOING CALLS
280 Currently the only possibility to trigger an outgoing call is that an
281 isdn4bsd network driver
282 .Em (ipr<n>)
283 sends a
284 .Em MSG_DIALOUT_IND
285 to the
286 .Nm
287 utility.
288 .Pp
289 The daemon requests a new CDID from the kernel by using the
290 .Em I4B_CDID_REQ
291 ioctl message, this CDID is now used in all interactions with the kernel
292 to identify this single call until a disconnect occurs.
293 .Pp
294 After getting the CDID, the daemon looks up several additional information
295 in its entry section of the configuration corresponding to that connection
296 and issues a
297 .Em I4B_CONNECT_REQ
298 ioctl message to the kernel.
299 The kernel now dials the remote side and
300 if the remote side accepts the call, the kernel sends a
301 .Em MSG_CONNECT_ACTIVE_IND
302 to the daemon.
303 .Pp
304 The call is terminated by either the local side timing out or the remote
305 side hanging up the connection or the local side actively sending a
306 .Em I4B_DISCONNECT_REQ
307 ioctl message, both events are signaled to the
308 .Nm
309 by the kernel sending the
310 .Em I4B_DISCONNECT_IND
311 message and the CDID corresponding to the call is no longer valid.
312 .Pp
313 .Ss INCOMING CALLS
314 Incoming calls are signaled to the
315 .Nm
316 by the kernel transmitting the
317 .Em MSG_CONNECT_IND
318 message to the daemon.
319 .Pp
320 With the information contained in this message, the
321 .Nm
322 searches the entry section of its configuration database and if a match is
323 found, it accepts or rejects the call or, if no match is found, it ignores the
324 call - all by issuing a
325 .Em I4B_CONNECT_RESP
326 ioctl message with the appropriate parameters to the kernel.
327 .Pp
328 In case the daemon decided to accept the call, the kernel signals this
329 by sending a
330 .Em MSG_CONNECT_ACTIVE_IND
331 message to the daemon.
332 .Pp
333 The call is terminated by either the local side timing out or the remote
334 side hanging up the connection or the local side actively sending a
335 .Em I4B_DISCONNECT_REQ
336 ioctl message, both events are signaled to the
337 .Nm
338 by the kernel sending the
339 .Em I4B_DISCONNECT_IND
340 message and the CDID corresponding to the call is no longer valid.
341 .Sh SIGNALS
342 Sending a HUP signal to
343 .Nm
344 causes all open connections to be terminated and the configuration file is
345 reread.
346 In case aliasfile handling was enabled, the aliasfile is also
347 reread.
348 .Pp
349 Sending a USR1 signal to
350 .Nm
351 causes the accounting file and the logfile (if logging to a file is used
352 instead of logging via the
353 .Xr syslog 3
354 facility) to be closed and reopened to make logfile rotation possible.
355 .Sh ENVIRONMENT
356 The following environment variables affect the execution of
357 .Nm :
358 .Bl -tag -width Ds
359 .It Ev TERM
360 The terminal type when running in full-screen display mode.
361 See
362 .Xr environ 7
363 for more information.
364 .El
365 .Sh FILES
366 .Bl -tag -width /etc/isdn/isdnd.rates
367 .It Pa /dev/i4b
368 The device-file used to communicate with the kernel ISDN driver subsystem.
369 .It Pa /var/log/messages
370 A record of the actions in case of syslogd logging support.
371 .It Pa /var/log/isdnd.acct
372 The default accounting information filename (if accounting is configured).
373 .It Pa /var/log/isdnd.log
374 The default logging filename (if logging to a file is configured).
375 .It Pa /var/run/isdnd.pid
376 The process id of the isdn daemon (also known as "lockfile" to isdnd, preventing multiple invocations of it).
377 .It Pa /usr/local/lib/isdn
378 .It Pa /etc/isdn
379 The directory where isdnd expects some supplementary data files and programs
380 for telephone answering support.
381 .It Pa /etc/isdn/isdnd.rc
382 The default runtime configuration file.
383 .It Pa /etc/isdn/isdnd.rates
384 The default unit charging rates specification file.
385 .It Pa /etc/isdn/isdntel.alias
386 The default table (if aliasing is enabled) to convert phone number to caller's name.
387 .El
388 .Sh EXAMPLES
389 For a first try, the following command should be used to start
390 .Nm
391 in foreground mode for better debugging the configuration setup:
392 .Bd -literal -offset indent
393 isdnd -d0xf9 -F
394 .Ed
395 .Pp
396 This will start isdnd with reasonable debugging settings and produce
397 output on the current terminal.
398 The
399 .Nm
400 utility can then be terminated by entering Control-C.
401 .Pp
402 Another example, the command:
403 .Bd -literal -offset indent
404 isdnd -d0xf9 -f -r /dev/ttyv3 -t vt100
405 .Ed
406 .Pp
407 will start
408 .Nm
409 with reasonable debugging messages enabled, full-screen mode of operation,
410 full-screen display redirected to /dev/ttyv3 and using a termcap entry
411 for vt100 on this display.
412 .Sh DIAGNOSTICS
413 Exit status is 0 on success, 1 on error.
414 .Sh SEE ALSO
415 .Xr i4bing 4 ,
416 .Xr i4bipr 4 ,
417 .Xr i4bisppp 4 ,
418 .Xr isdnd.rates 5 ,
419 .Xr isdnd.rc 5 ,
420 .Xr isdntel 8 ,
421 .Xr isdntrace 8 ,
422 .Xr syslogd 8
423 .Sh BUGS
424 Still one or more left.
425 .Sh AUTHORS
426 The
427 .Nm
428 utility and this manual page were written by
429 .An Hellmuth Michaelis Aq hm@FreeBSD.org .