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