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.5 2006/05/26 19:39:40 swildner 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
 183 .In syslog.h ) .
 184 .It Fl t
 185 In conjunction with the
 186 .Fl f
 187 and
 188 .Fl r
 189 options,
 190 .Ar terminaltype
 191 specifies a terminal type or termcap entry name (such as vt220) for the device
 192 used for
 193 .Nm
 194 full-screen output.
 195 This is useful if an unused (no getty running) tty line is
 196 used for full-screen output for which no
 197 .Li TERM
 198 environment variable exists.
 199 .It Fl u
 200 Specifies the length of a charging unit in case the config file entry
 201 keyword
 202 .Em unitlenghtsrc
 203 is set to
 204 .Em cmdl .
 205 .It Fl m
 206 If the isdn daemon is compiled with local or remote monitoring support,
 207 this option disables all monitoring access.
 208 It overrides the config
 209 file option
 210 .Em monitor-allowed .
 211 .El
 212 .Sh INTERACTION WITH THE KERNEL
 213 The
 214 .Nm
 215 utility
 216 communicates with the kernel part of isdn4bsd by receiving status and
 217 event messages
 218 .Xr ( read 2
 219 from device
 220 .Pa /dev/i4b )
 221 and by transmitting commands and responses
 222 .Xr ( ioctl 2
 223 from device
 224 .Pa /dev/i4b ) .
 225 .Pp
 226 The messages and message parameters are documented in the include
 227 file
 228 .In i4b_machine/i4b_ioctl.h .
 229 .Pp
 230 Supported command and response messages (ioctls) to the kernel are:
 231 .Bl -tag -width Ds -compact -offset indent
 232 .It Dv I4B_CDID_REQ
 233 Request a unique Call Description IDentifier (cdid) which identifies
 234 uniquely a single interaction of the local D channel with the exchange.
 235 .It Dv I4B_CONNECT_REQ
 236 Actively request a call setup to a remote ISDN subscriber.
 237 .It Dv I4B_CONNECT_RESP
 238 Respond to an incoming call, either accept, reject or ignore it.
 239 .It Dv I4B_DISCONNECT_REQ
 240 Actively terminate a connection.
 241 .It Dv I4B_CTRL_INFO_REQ
 242 Request information about an installed ISDN controller card.
 243 .It Dv I4B_DIALOUT_RESP
 244 Give information about call setup to driver who requested dialing out.
 245 .It Dv I4B_TIMEOUT_UPD
 246 Update the kernels timeout value(s) in case of dynamically calculated
 247 shorthold mode timing changes.
 248 .It Dv I4B_UPDOWN_IND
 249 Inform the kernel userland drivers about interface soft up/down status
 250 changes.
 251 .It Dv I4B_CTRL_DOWNLOAD
 252 Download firmware to active card(s).
 253 .It Dv I4B_ACTIVE_DIAGNOSTIC
 254 Return diagnostic information from active cards.
 255 .El
 256 .Pp
 257 .Pp
 258 Supported status and event messages from the kernel are:
 259 .Bl -tag -width Ds -compact -offset indent
 260 .It Ar MSG_CONNECT_IND
 261 An incoming call from a remote ISDN user is indicated.
 262 .It Ar MSG_CONNECT_ACTIVE_IND
 263 After an incoming call has been accepted locally or an outgoing call has
 264 been accepted by a remote, the exchange signaled an active connection
 265 and the corresponding B-channel is switched through.
 266 .It Ar MSG_DISCONNECT_IND
 267 A call was terminated.
 268 .It Ar MSG_DIALOUT_IND
 269 A userland interface driver requests the daemon to dial out (typically a
 270 network interface when a packet arrives in its send queue).
 271 .It Ar MSG_IDLE_TIMEOUT_IND
 272 A call was terminated by the isdn4bsd kernel driver because a B-channel
 273 idle timeout occurred.
 274 .It Ar MSG_ACCT_IND
 275 Accounting information from a network driver.
 276 .It Ar MSG_CHARGING_IND
 277 Charging information from the kernel.
 278 .El
 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 .Dv 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 .Dv 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 .Dv I4B_DISCONNECT_REQ
 307 ioctl message, both events are signaled to the
 308 .Nm
 309 by the kernel sending the
 310 .Em MSG_DISCONNECT_IND
 311 message and the CDID corresponding to the call is no longer valid.
 312 .Ss INCOMING CALLS
 313 Incoming calls are signaled to the
 314 .Nm
 315 by the kernel transmitting the
 316 .Em MSG_CONNECT_IND
 317 message to the daemon.
 318 .Pp
 319 With the information contained in this message, the
 320 .Nm
 321 searches the entry section of its configuration database and if a match is
 322 found, it accepts or rejects the call or, if no match is found, it ignores the
 323 call - all by issuing a
 324 .Dv I4B_CONNECT_RESP
 325 ioctl message with the appropriate parameters to the kernel.
 326 .Pp
 327 In case the daemon decided to accept the call, the kernel signals this
 328 by sending a
 329 .Em MSG_CONNECT_ACTIVE_IND
 330 message to the daemon.
 331 .Pp
 332 The call is terminated by either the local side timing out or the remote
 333 side hanging up the connection or the local side actively sending a
 334 .Dv I4B_DISCONNECT_REQ
 335 ioctl message, both events are signaled to the
 336 .Nm
 337 by the kernel sending the
 338 .Em MSG_DISCONNECT_IND
 339 message and the CDID corresponding to the call is no longer valid.
 340 .Sh SIGNALS
 341 Sending a HUP signal to
 342 .Nm
 343 causes all open connections to be terminated and the configuration file is
 344 reread.
 345 In case aliasfile handling was enabled, the aliasfile is also
 346 reread.
 347 .Pp
 348 Sending a USR1 signal to
 349 .Nm
 350 causes the accounting file and the logfile (if logging to a file is used
 351 instead of logging via the
 352 .Xr syslog 3
 353 facility) to be closed and reopened to make logfile rotation possible.
 354 .Sh ENVIRONMENT
 355 The following environment variables affect the execution of
 356 .Nm :
 357 .Bl -tag -width Ds
 358 .It Ev TERM
 359 The terminal type when running in full-screen display mode.
 360 See
 361 .Xr environ 7
 362 for more information.
 363 .El
 364 .Sh FILES
 365 .Bl -tag -width /etc/isdn/isdnd.rates
 366 .It Pa /dev/i4b
 367 The device-file used to communicate with the kernel ISDN driver subsystem.
 368 .It Pa /var/log/messages
 369 A record of the actions in case of syslogd logging support.
 370 .It Pa /var/log/isdnd.acct
 371 The default accounting information filename (if accounting is configured).
 372 .It Pa /var/log/isdnd.log
 373 The default logging filename (if logging to a file is configured).
 374 .It Pa /var/run/isdnd.pid
 375 The process id of the isdn daemon (also known as "lockfile" to isdnd, preventing multiple invocations of it).
 376 .It Pa /usr/local/lib/isdn
 377 .It Pa /etc/isdn
 378 The directory where isdnd expects some supplementary data files and programs
 379 for telephone answering support.
 380 .It Pa /etc/isdn/isdnd.rc
 381 The default runtime configuration file.
 382 .It Pa /etc/isdn/isdnd.rates
 383 The default unit charging rates specification file.
 384 .It Pa /etc/isdn/isdntel.alias
 385 The default table (if aliasing is enabled) to convert phone number to caller's name.
 386 .El
 387 .Sh EXAMPLES
 388 For a first try, the following command should be used to start
 389 .Nm
 390 in foreground mode for better debugging the configuration setup:
 391 .Bd -literal -offset indent
 392 isdnd -d0xf9 -F
 393 .Ed
 394 .Pp
 395 This will start isdnd with reasonable debugging settings and produce
 396 output on the current terminal.
 397 The
 398 .Nm
 399 utility can then be terminated by entering Control-C.
 400 .Pp
 401 Another example, the command:
 402 .Bd -literal -offset indent
 403 isdnd -d0xf9 -f -r /dev/ttyv3 -t vt100
 404 .Ed
 405 .Pp
 406 will start
 407 .Nm
 408 with reasonable debugging messages enabled, full-screen mode of operation,
 409 full-screen display redirected to /dev/ttyv3 and using a termcap entry
 410 for vt100 on this display.
 411 .Sh DIAGNOSTICS
 412 Exit status is 0 on success, 1 on error.
 413 .Sh SEE ALSO
 414 .Xr i4bing 4 ,
 415 .Xr i4bipr 4 ,
 416 .Xr i4bisppp 4 ,
 417 .Xr isdnd.rates 5 ,
 418 .Xr isdnd.rc 5 ,
 419 .Xr isdntel 8 ,
 420 .Xr isdntrace 8 ,
 421 .Xr syslogd 8
 422 .Sh AUTHORS
 423 The
 424 .Nm
 425 utility and this manual page were written by
 426 .An Hellmuth Michaelis Aq hm@FreeBSD.org .
 427 .Sh BUGS
 428 Still one or more left.