| blob | 8873fe41c18c354f7ad0a9f64516563915677f07 |
1 '\" te
2 .\" To view license terms, attribution, and copyright for IP Filter, the default path is /usr/lib/ipf/IPFILTER.LICENCE. If the Solaris operating environment has been installed anywhere other than the default, modify the given path to access the file at the installed
3 .\" location.
4 .\" Portions Copyright (c) 2008, Sun Microsystems Inc. All Rights Reserved.
5 .\" Portions Copyright (c) 2013, Joyent, Inc. All Rights Reserved.
6 .TH IPMON 1M "Oct 30, 2013"
7 .SH NAME
8 ipmon \- monitors /dev/ipl for logged packets
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBipmon\fR [\fB-abDFhnpstvxX\fR] [\fB-N\fR \fIdevice\fR] [ [o] [NSI]] [\fB-O\fR [NSI]]
13 [\fB-P\fR \fIpidfile\fR] [\fB-S\fR \fIdevice\fR] [\fB-f\fR \fIdevice\fR] [\fB-G\fR | \fB-z\fR \fIzonename\fR] [\fIfilename\fR]
14 .fi
16 .SH DESCRIPTION
17 .LP
18 The \fBipmon\fR command is part of a suite of commands associated with the
19 Solaris IP Filter feature. See \fBipfilter\fR(5).
20 .sp
21 .LP
22 The \fBipmon\fR command opens \fB/dev/ipl\fR for reading and awaits data to be
23 saved from the packet filter. The binary data read from the device is reprinted
24 in human readable form. However, IP addresses are not mapped back to hostnames,
25 nor are ports mapped back to service names. The output goes to standard output,
26 by default, or a filename, if specified on the command line. Should the
27 \fB-s\fR option be used, output is sent instead to \fBsyslogd\fR(1M). Messages
28 sent by means of \fBsyslog\fR have the day, month, and year removed from the
29 message, but the time (including microseconds), as recorded in the log, is
30 still included.
31 .sp
32 .LP
33 Messages generated by \fBipmon\fR consist of whitespace-separated fields.
34 Fields common to all messages are:
35 .RS +4
36 .TP
37 .ie t \(bu
38 .el o
39 The date of packet receipt. This is suppressed when the message is sent to
40 \fBsyslog\fR.
41 .RE
42 .RS +4
43 .TP
44 .ie t \(bu
45 .el o
46 The time of packet receipt. This is in the form
47 \fIHH\fR:\fIMM\fR:\fISS\fR.\fIF\fR, for hours, minutes, seconds, and fractions
48 of a second (which can be several digits long).
49 .RE
50 .RS +4
51 .TP
52 .ie t \(bu
53 .el o
54 The name of the interface on which the packet was processed, for example,
55 \fBib1\fR.
56 .RE
57 .RS +4
58 .TP
59 .ie t \(bu
60 .el o
61 The group and rule number of the rule, for example, \fB@0:17\fR. These can be
62 viewed with \fBipfstat\fR \fB-in\fR for input rules or \fBipfstat\fR \fB-in\fR
63 for output rules. See \fBipfstat\fR(1M).
64 .RE
65 .RS +4
66 .TP
67 .ie t \(bu
68 .el o
69 The action: \fBp\fR for passed, \fBb\fR for blocked, \fBs\fR for a short
70 packet, \fBn\fR did not match any rules, or \fBL\fR for a log rule.
71 .RE
72 .RS +4
73 .TP
74 .ie t \(bu
75 .el o
76 The addresses. This is actually three fields: the source address and port
77 (separated by a comma), the symbol \(->, and the destination address and port.
78 For example: \fB209.53.17.22,80 \(-> 198.73.220.17,1722\fR.
79 .RE
80 .RS +4
81 .TP
82 .ie t \(bu
83 .el o
84 \fBPR\fR followed by the protocol name or number, for example, \fBPR tcp\fR.
85 .RE
86 .RS +4
87 .TP
88 .ie t \(bu
89 .el o
90 \fBlen\fR followed by the header length and total length of the packet, for
91 example, \fBlen 20 40\fR.
92 .RE
93 .sp
94 .LP
95 If the packet is a TCP packet, there will be an additional field starting with
96 a hyphen followed by letters corresponding to any flags that were set. See
97 \fBipf.conf\fR(4) for a list of letters and their flags.
98 .sp
99 .LP
100 If the packet is an ICMP packet, there will be two fields at the end, the first
101 always being \fBicmp\fR, the next being the ICMP message and submessage type,
102 separated by a slash. For example, \fBicmp 3/3\fR for a port unreachable
103 message.
104 .SH OPTIONS
105 .LP
106 The following options are supported:
107 .sp
108 .ne 2
109 .na
110 \fB\fB-a\fR\fR
111 .ad
112 .sp .6
113 .RS 4n
114 Open all of the device logfiles for reading log entries. All entries are
115 displayed to the same output device (stderr or syslog).
116 .RE
118 .sp
119 .ne 2
120 .na
121 \fB\fB-b\fR\fR
122 .ad
123 .sp .6
124 .RS 4n
125 For rules which log the body of a packet, generate hex output representing the
126 packet contents after the headers.
127 .RE
129 .sp
130 .ne 2
131 .na
132 \fB\fB-D\fR\fR
133 .ad
134 .sp .6
135 .RS 4n
136 Cause \fBipmon\fR to turn itself into a daemon. Using subshells or
137 backgrounding of \fBipmon\fR is not required to turn it into an orphan so it
138 can run indefinitely.
139 .RE
141 .sp
142 .ne 2
143 .na
144 \fB\fB-f\fR \fIdevice\fR\fR
145 .ad
146 .sp .6
147 .RS 4n
148 Specify an alternative device/file from which to read the log information for
149 normal IP Filter log records.
150 .RE
152 .sp
153 .ne 2
154 .na
155 \fB\fB-F\fR\fR
156 .ad
157 .sp .6
158 .RS 4n
159 Flush the current packet log buffer. The number of bytes flushed is displayed,
160 even if the result is zero.
161 .RE
163 .sp
164 .ne 2
165 .na
166 \fB\fB-h\fR\fR
167 .ad
168 .sp .6
169 .RS 4n
170 Displays usage information.
171 .RE
173 .sp
174 .ne 2
175 .na
176 \fB\fB-n\fR\fR
177 .ad
178 .sp .6
179 .RS 4n
180 IP addresses and port numbers will be mapped, where possible, back into
181 hostnames and service names.
182 .RE
184 .sp
185 .ne 2
186 .na
187 \fB\fB-N\fR \fIdevice\fR\fR
188 .ad
189 .sp .6
190 .RS 4n
191 Set the logfile to be opened for reading NAT log records from or to
192 \fIdevice\fR.
193 .RE
195 .sp
196 .ne 2
197 .na
198 \fB\fB-o\fR \fIletter\fR\fR
199 .ad
200 .sp .6
201 .RS 4n
202 Specify which log files from which to actually read data. \fBN\fR, NAT logfile;
203 \fBS\fR, state logfile; \fBI\fR, normal IP Filter logfile. The \fB-a\fR option
204 is equivalent to using \fB-o\fR \fBNSI\fR.
205 .RE
207 .sp
208 .ne 2
209 .na
210 \fB\fB-O\fR \fIletter\fR\fR
211 .ad
212 .sp .6
213 .RS 4n
214 Specify which log files you do not wish to read from. This is most commonly
215 used in conjunction with the \fB-a\fR. Letters available as parameters are the
216 same as for \fB-o\fR.
217 .RE
219 .sp
220 .ne 2
221 .na
222 \fB\fB-p\fR\fR
223 .ad
224 .sp .6
225 .RS 4n
226 Cause the port number in log messages always to be printed as a number and
227 never attempt to look it up.
228 .RE
230 .sp
231 .ne 2
232 .na
233 \fB\fB-P\fR \fIpidfile\fR\fR
234 .ad
235 .sp .6
236 .RS 4n
237 Write the PD of the \fBipmon\fR process to a file. By default this is
238 \fB/var/run/ipmon.pid\fR.
239 .RE
241 .sp
242 .ne 2
243 .na
244 \fB\fB-s\fR\fR
245 .ad
246 .sp .6
247 .RS 4n
248 Packet information read in will be sent through \fBsyslogd\fR rather than saved
249 to a file. The default facility when compiled and installed is \fBlocal0\fR.
250 The following levels are used:
251 .sp
252 .ne 2
253 .na
254 \fB\fBLOG_INFO\fR\fR
255 .ad
256 .sp .6
257 .RS 4n
258 Packets logged using the \fBlog\fR keyword as the action rather than \fBpass\fR
259 or \fBblock\fR.
260 .RE
262 .sp
263 .ne 2
264 .na
265 \fB\fBLOG_NOTICE\fR\fR
266 .ad
267 .sp .6
268 .RS 4n
269 Packets logged that are also passed.
270 .RE
272 .sp
273 .ne 2
274 .na
275 \fB\fBLOG_WARNING\fR\fR
276 .ad
277 .sp .6
278 .RS 4n
279 Packets logged that are also blocked.
280 .RE
282 .sp
283 .ne 2
284 .na
285 \fB\fBLOG_ERR\fR\fR
286 .ad
287 .sp .6
288 .RS 4n
289 Packets that have been logged and that can be considered "short".
290 .RE
292 .RE
294 .sp
295 .ne 2
296 .na
297 \fB\fB-S\fR \fIdevice\fR\fR
298 .ad
299 .sp .6
300 .RS 4n
301 Set the logfile to be opened for reading state log records from or to
302 \fIdevice\fR.
303 .RE
305 .sp
306 .ne 2
307 .na
308 \fB\fB-t\fR\fR
309 .ad
310 .sp .6
311 .RS 4n
312 Read the input file/device in the way performed by \fBtail\fR(1).
313 .RE
315 .sp
316 .ne 2
317 .na
318 \fB\fB-v\fR\fR
319 .ad
320 .sp .6
321 .RS 4n
322 Show TCP \fBwindow\fR, \fBack\fR, and \fBsequence\fR fields
323 .RE
325 .sp
326 .ne 2
327 .na
328 \fB\fB-x\fR\fR
329 .ad
330 .sp .6
331 .RS 4n
332 Show the packet data in hex.
333 .RE
335 .sp
336 .ne 2
337 .na
338 \fB\fB-X\fR\fR
339 .ad
340 .sp .6
341 .RS 4n
342 Show the log header record data in hex.
343 .RE
345 .sp
346 .ne 2
347 .na
348 \fB\fB-z\fR \fIzonename\fR\fR
349 .ad
350 .sp .6
351 .RS 4n
352 Monitor packets the specified zone's in-zone filter. If neither this option
353 nor \fB-G\fR is specified, the current zone is used. This command is only
354 available in the Global Zone. See \fBZONES\fR in \fBipf\fR(1m) for more
355 information.
356 .RE
358 .sp
359 .ne 2
360 .na
361 \fB\fB-G\fR \fIzonename\fR\fR
362 .ad
363 .sp .6
364 .RS 4n
365 Monitor packets for the specified zone's global zone controlled filter. If
366 neither this option nor \fB-z\fR is specified, the current zone is used. This
367 command is only available in the Global Zone. See \fBZONES\fR in \fBipf\fR(1m)
368 for more information.
369 .RE
371 .SH FILES
372 .RS +4
373 .TP
374 .ie t \(bu
375 .el o
376 \fB/dev/ipl\fR
377 .RE
378 .RS +4
379 .TP
380 .ie t \(bu
381 .el o
382 \fB/dev/ipnat\fR
383 .RE
384 .RS +4
385 .TP
386 .ie t \(bu
387 .el o
388 \fB/dev/ipstate\fR
389 .RE
390 .SH ATTRIBUTES
391 .LP
392 See \fBattributes\fR(5) for descriptions of the following attributes:
393 .sp
395 .sp
396 .TS
397 box;
398 c | c
399 l | l .
400 ATTRIBUTE TYPE ATTRIBUTE VALUE
401 _
402 Interface Stability Committed
403 .TE
405 .SH SEE ALSO
406 .LP
407 \fBipf\fR(1M), \fBipfstat\fR(1M), \fBipnat\fR(1M), \fBattributes\fR(5),
408 \fBipfilter\fR(5), \fBzones(5)\fR
409 .sp
410 .LP
411 \fI\fR
412 .SH DIAGNOSTICS
413 .LP
414 \fBipmon\fR expects data that it reads to be consistent with how it should be
415 saved and aborts if it fails an assertion which detects an anomaly in the
416 recorded data.