usr.sbin/i4b/isdntrace/isdntrace.8

   1 .\"
   2 .\" Copyright (c) 1997, 2000 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: isdntrace.8,v 1.14 2000/02/13 15:26:52 hm Exp $
  26 .\"
  27 .\" $FreeBSD: src/usr.sbin/i4b/isdntrace/isdntrace.8,v 1.9.2.6 2003/03/11 21:13:50 trhodes Exp $
  28 .\" $DragonFly: src/usr.sbin/i4b/isdntrace/isdntrace.8,v 1.3 2006/02/17 19:40:15 swildner Exp $
  29 .\"
  30 .\"     last edit-date: [Wed Nov  1 15:52:28 2000]
  31 .\"
  32 .Dd November 1, 2000
  33 .Dt ISDNTRACE 8
  34 .Os
  35 .Sh NAME
  36 .Nm isdntrace
  37 .Nd isdn4bsd ISDN protocol trace utility
  38 .Sh SYNOPSIS
  39 .Nm
  40 .Op Fl a
  41 .Op Fl b
  42 .Op Fl d
  43 .Op Fl f Ar filename
  44 .Op Fl h
  45 .Op Fl i
  46 .Op Fl l
  47 .Op Fl n Ar number
  48 .Op Fl o
  49 .Op Fl p Ar filename
  50 .Op Fl r
  51 .Op Fl u Ar number
  52 .Op Fl x
  53 .Op Fl B
  54 .Op Fl F
  55 .Op Fl P
  56 .Op Fl R Ar unit
  57 .Op Fl T Ar unit
  58 .Sh DESCRIPTION
  59 The
  60 .Nm
  61 utility is part of the isdn4bsd package and is used to provide the user with a
  62 mnemonic display of the layers 1, 2 and 3 protocol activities on
  63 the D channel and hex dump of the B channel(s) activities.
  64 .Pp
  65 Together with two passive supported cards and an easy to build cable it can
  66 also be used to monitor the complete traffic on a S0 bus providing S0 bus
  67 analyzer features.
  68 .Pp
  69 The
  70 .Nm
  71 utility is only available for passive supported cards.
  72 .Pp
  73 .Em Note
  74 .Pp
  75 All filenames, user specified or default, get a date and time stamp string
  76 added in the form -yyyymmdd-hhmmss: a hyphen, four digits year, two digits
  77 month and day, a hyphen and two digits hour, minutes and seconds.
  78 Tracefiles no longer get overwritten.
  79 In case a new filename is needed within a second, the filename-generating
  80 mechanism sleeps one second.
  81 .Pp
  82 In case the program is sent a USR1 signal, a new user specified or default
  83 filename with a new date and timestamp is generated and opened.
  84 .Pp
  85 The following options can be used:
  86 .Bl -tag -width Ds
  87 .It Fl a
  88 Run
  89 .Nm
  90 in analyzer mode by using two passive cards and a custom cable which can
  91 be build as described in the file
  92 .Em cable.txt
  93 in the isdn4bsd source distribution. One card acts as a receiver for the
  94 transmitting direction on the S0 bus while the other card acts as a receiver
  95 for the receiving direction on the S0 bus. Complete traffic monitoring is
  96 possible using this setup.
  97 .It Fl b
  98 switch B channel tracing on (default off).
  99 .It Fl d
 100 switch D channel tracing off (default on).
 101 .It Fl f
 102 Use
 103 .Ar filename
 104 as the name of a file into which to write tracing output (default filename is
 105 isdntrace<n> where n is the number of the unit to trace).
 106 .It Fl h
 107 switch display of header off (default on).
 108 .It Fl i
 109 print layer 1 (I.430) INFO signals to monitor layer 1 activity (default off).
 110 .It Fl l
 111 switch displaying of Layer 2 (Q.921) frames off (default on).
 112 .It Fl n
 113 This option takes a numeric argument specifying the minimum
 114 frame size in octets a frame must have to be displayed. (default 0)
 115 .It Fl o
 116 switch off writing trace output to a file (default on).
 117 .It Fl p
 118 Use
 119 .Ar filename
 120 as the name of a file used for the -B and -P options (default filename
 121 is isdntracebin<n> where n is the number of the unit to trace).
 122 .It Fl r
 123 Switch off printing a raw hexadecimal dump of the packets preceding
 124 the decoded protocol information (default on).
 125 .It Fl u
 126 Use
 127 .Ar number
 128 as the unit number of the controller card to trace (default 0).
 129 .It Fl x
 130 Switch on printing of packets with a non-Q.931 protocol discriminator.
 131 (default off).
 132 .It Fl B
 133 Write undecoded binary trace data to a file for later or remote
 134 analyzing (default off).
 135 .It Fl F
 136 This option can only be used when option -P (playback from binary data file)
 137 is used. The -F option causes playback not to stop at end of file but rather
 138 to wait for additional data to be available from the input file.
 139 .Pp
 140 This option is useful when trace data is accumulated in binary format (to
 141 save disk space) but a monitoring functionality is desired.
 142 (default off).
 143 .It Fl P
 144 Read undecoded binary trace data from file instead from device (default off).
 145 .It Fl R
 146 Use
 147 .Ar unit
 148 as the receiving interface unit number in analyze mode.
 149 .It Fl T
 150 Use
 151 .Ar unit
 152 as the transmitting interface unit number in analyze mode.
 153 .El
 154 .Pp
 155 When the USR1 signal is sent to a
 156 .Nm
 157 process, the currently used logfiles are reopened, so that logfile
 158 rotation becomes possible.
 159 .Pp
 160 The trace output should be obvious. It is very handy to have the following
 161 standard texts available when tracing ISDN protocols:
 162 .Pp
 163 .Bl -tag -width Ds -compact -offset indent
 164 .It Ar I.430
 165 ISDN BRI layer 1 protocol description.
 166 .It Ar Q.921
 167 ISDN D-channel layer 2 protocol description.
 168 .It Ar Q.931
 169 ISDN D-channel layer 3 protocol description.
 170 .It Ar 1TR6
 171 German-specific ISDN layer 3 protocol description. (NOTICE: decoding
 172 of the 1TR6 protocol is included but not supported since i dont have
 173 any longer access to a 1TR6 based ISDN installation.)
 174 .El
 175 .Pp
 176 The
 177 .Nm
 178 utility
 179 automatically detects the layer 3 protocol being used by looking at the
 180 Protocol Discriminator (see: Q.931/1993 pp. 53).
 181 .Sh FILES
 182 .Bl -tag -width daddeldi -compact
 183 .It Pa /dev/i4btrc<n>
 184 The devicefile(s) used to get the trace messages for ISDN card unit <n>
 185 out of the kernel.
 186 .El
 187 .Sh EXAMPLES
 188 The command:
 189 .Bd -literal -offset indent
 190 isdntrace -f /var/tmp/isdn.trace
 191 .Ed
 192 .Pp
 193 will start D channel tracing on passive controller 0 with all except B
 194 channel tracing enabled and logs everything into the output file
 195 /var/tmp/isdn.trace-yyyymmdd-hhmmss (where yyyymmdd and hhmmss are replaced
 196 by the current date and time values).
 197 .Sh SEE ALSO
 198 .Xr isdnd 8
 199 .Sh STANDARDS
 200 ITU Recommendations I.430, Q.920, Q.921, Q.930, Q.931
 201 .Pp
 202 FTZ Richtlinie 1TR3, Band III
 203 .Pp
 204 ITU Recommendation Q.932 (03/93), Q.950 (03/93)
 205 .Pp
 206 ETSI Recommendation ETS 300 179 (10/92), ETS 300 180 (10/92)
 207 .Pp
 208 ETSI Recommendation ETS 300 181 (04/93), ETS 300 182 (04/93)
 209 .Pp
 210 ITU Recommendation X.208, X.209
 211 .Sh AUTHORS
 212 .An -nosplit
 213 The
 214 .Nm
 215 utility was written by
 216 .An Gary Jennejohn Aq gj@FreeBSD.org
 217 and
 218 .An Hellmuth Michaelis Aq hm@FreeBSD.org .
 219 .Pp
 220 This manual page was written by
 221 .An Hellmuth Michaelis .
 222 .Sh BUGS
 223 Still some or more left.