| blob | c32e3e0d155f23276bfb69afb182f95fc5295188 |
1 .\" $NetBSD: isdntrace.8,v 1.5 2002/07/29 00:54:45 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: isdntrace.8,v 1.6 2003/09/11 14:14:31 pooka Exp $
27 .\"
28 .\" $FreeBSD$
29 .\"
30 .\" last edit-date: [Sun Feb 13 14:38:42 2000]
31 .\"
32 .Dd February 13, 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 isdntrace
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 .Nm
60 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 .br
74 All filenames, user specified or default, get a date and time stamp string
75 added in the form -yymmdd-hhmmss: a hyphen, two digits year, month, day,
76 a hyphen and two digits hour, minutes and seconds.
77 Trace files no longer get overwritten.
78 In case a new filename is needed within a second, the filename-generating
79 mechanism sleeps one second.
80 .br
81 In case the program is sent a USR1 signal, a new user specified or default
82 filename with a new date and time stamp 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. One card acts as a receiver for the
93 transmitting direction on the S0 bus while the other card acts as a receiver
94 for the receiving direction on the S0 bus. Complete traffic monitoring is
95 possible using this setup.
96 .It Fl b
97 switch B channel tracing on (default off).
98 .It Fl d
99 switch D channel tracing off (default on).
100 .It Fl f
101 Use
102 .Ar filename
103 as the name of a file into which to write tracing output (default filename is
104 isdntrace\*[Lt]n\*[Gt] where n is the number of the unit to trace).
105 .It Fl h
106 switch display of header off (default on).
107 .It Fl i
108 print layer 1 (I.430) INFO signals to monitor layer 1 activity (default off).
109 .It Fl l
110 switch displaying of Layer 2 (Q.921) frames off (default on).
111 .It Fl n
112 This option takes a numeric argument specifying the minimum
113 frame size in octets a frame must have to be displayed. (default 0)
114 .It Fl o
115 switch off writing trace output to a file (default on).
116 .It Fl p
117 Use
118 .Ar filename
119 as the name of a file used for the -B and -P options (default filename
120 is isdntracebin\*[Lt]n\*[Gt] where n is the number of the unit to trace).
121 .It Fl r
122 Switch off printing a raw hexadecimal dump of the packets preceding
123 the decoded protocol information (default on).
124 .It Fl u
125 Use
126 .Ar number
127 as the unit number of the controller card to trace (default 0).
128 .It Fl x
129 Switch on printing of packets with a non-Q.931 protocol discriminator.
130 (default off).
131 .It Fl B
132 Write undecoded binary trace data to a file for later or remote
133 analyzing (default off).
134 .It Fl F
135 This option can only be used when option -P (playback from binary data file)
136 is used. The -F option causes playback not to stop at end of file but rather
137 to wait for additional data to be available from the input file.
138 .Pp
139 This option is useful when trace data is accumulated in binary format (to
140 save disk space) but a monitoring functionality is desired.
141 (default off).
142 .It Fl P
143 Read undecoded binary trace data from file instead from device (default off).
144 .It Fl R
145 Use
146 .Ar unit
147 as the receiving interface unit number in analyze mode.
148 .It Fl T
149 Use
150 .Ar unit
151 as the transmitting interface unit number in analyze mode.
152 .El
153 .Pp
154 When the USR1 signal is sent to a
155 .Nm
156 process, the currently used logfiles are reopened, so that logfile
157 rotation becomes possible.
158 .Pp
159 The trace output should be obvious. It is very handy to have the following
160 standard texts available when tracing ISDN protocols:
161 .Pp
162 .Bl -tag -width Ds -compact -offset indent
163 .It Ar I.430
164 ISDN BRI layer 1 protocol description.
165 .It Ar Q.921
166 ISDN D-channel layer 2 protocol description.
167 .It Ar Q.931
168 ISDN D-channel layer 3 protocol description.
169 .It Ar 1TR6
170 German-specific ISDN layer 3 protocol description. (NOTICE: decoding
171 of the 1TR6 protocol is included but not supported since i dont have
172 any longer access to a 1TR6 based ISDN installation.)
173 .El
174 .Pp
175 .Nm
176 automatically detects the layer 3 protocol being used by looking at the
177 Protocol Discriminator (see: Q.931/1993 pp. 53).
178 .Sh FILES
179 .Bl -tag -width daddeldi -compact
180 .It Pa /dev/isdntrc\*[Lt]n\*[Gt]
181 The device file(s) used to get the trace messages for ISDN card unit \*[Lt]n\*[Gt]
182 out of the kernel.
183 .El
184 .Sh EXAMPLES
185 The command:
186 .Bd -literal -offset indent
187 isdntrace -f /var/tmp/isdn.trace
188 .Ed
189 .Pp
190 will start D channel tracing on passive controller 0 with all except B
191 channel tracing enabled and logs everything into the output file
192 /var/tmp/isdn.trace-yymmdd-hhmmss (where yymmdd and hhmmss are replaced
193 by the current date and time values).
194 .Sh SEE ALSO
195 .Xr isdnd 8
196 .Sh STANDARDS
197 ITU Recommendations I.430, Q.920, Q.921, Q.930, Q.931
198 .Pp
199 FTZ Richtlinie 1TR3, Band III
200 .Pp
201 ITU Recommendation Q.932 (03/93), Q.950 (03/93)
202 .Pp
203 ETSI Recommendation ETS 300 179 (10/92), ETS 300 180 (10/92)
204 .Pp
205 ETSI Recommendation ETS 300 181 (04/93), ETS 300 182 (04/93)
206 .Pp
207 ITU Recommendation X.208, X.209
208 .Sh AUTHORS
209 The
210 .Nm
211 utility was written by
212 .An Gary Jennejohn
213 and
214 .An Hellmuth Michaelis .
215 .Pp
216 This manual page was written by
217 .An Hellmuth Michaelis Aq hm@kts.org .