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