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