README
1/**************************************************************************/
2/* */
3/* miruo README */
4/* */
5/* Copyright (C) 2011 KLab Inc. */
6/**************************************************************************/
7
8[What is miruo]
9miruo is a packet capture type TCP session monitor.
10miruo can
11- show packets grouped by TCP sessions
12- show only connect-disconnect info in simple & neat style
13- show TCP sessions with which segments were resent
14- show TCP sessions which exceeds certain time.
15- show TCP sessions which were terminated by RST
16- show segments where IP fragmentation occured
17- utilize files saved by tcpdump -w
18- is light & run with high speed
19
20[Installation]
21 $ tar zxvf miruo-x.y.z.tar.gz
22 $ cd miruo-x.y.z
23 $ ./configure
24 $ make
25 $ sudo make install
26
27* miruo is tested on Linux only.
28
29[Usage]
30usage: miruo [option] [expression]
31 option
32 -h, --help # help
33 -V, --version # version
34 -i, --interface=dev # eth0,bond0,any...
35 -v, --view-data=NUM #
36 -T, --long-connect=time[ms] # Threshold of connection time for lookup. Default 0ms(off)
37 -t, --long-delay=time[ms] # Threshold of long delay time for lookup. Default 0ms(off)
38 -r, --retransmit=time[ms] # Threshold of retransmit time for lookup. Default 1000ms
39 -s, --stat=interval[sec] # statistics view interval. Default 0sec(off)
40 -f, --file=file # read file(for tcpdump -w)
41 -S, --syn=[0|1] # syn retransmit lookup mode.default=1. 0=ignore 1=lookup
42 -R, --rst=[0|1|2] # rst lookup mode.default=1. (see README)
43 -F, --fragment=[0|1] # ip fragmentation lookup. default=1
44 -C, --color=[0|1] # color 0=off 1=on
45 -L, --session-limit=NUM # active session limit. Default 1024
46 -l, --segment-limit=NUM # active segment limit. Default 65536
47 -m, --dpi-mode=mode # deep packet inspection mode. (now support only http)
48 -q, --quiet #
49 --all # all session lookup
50 --live # live mode(all segment lookup)
51
52On [expression] part, you can set filter with same way as TCPdump.
53However, if you set filter like "tcp[13] & 2 != 0", which filter some parts of TCP packets, you will not be able to track TCP sessions.
54For filter format, please refer to man of tcpdump.
55
56Sample for valid filter)
57 # miruo -T3000 host dbserver and port 3306
58This will show sessions which are connected to MYSQL more than 3 sec.
59
60Sample for invalid filter)
61 # miruo -T3000 dst host dbserver and dst port 3306
62Since it can not capture SYN/BACK, it can not trace TCP
63
64【Options】
65
66 -h, --help
67 shows help
68
69 -V, --version
70 shows version info
71
72 -i, --interface=dev
73 specify network interface. "any" is also valid.
74
75 -v, --view-data=NUM
76 when this is 0, it only shows packets that are resent/delayed and packets of connections and disconnections.
77 otherwise specified, it shows other packets depends on the specified number.
78 default is 0.
79
80 -T, --long-connect=time[ms]
81 sessions with connection time (from connected time to disconnected time) more than specified time will be shown.
82 default is 0. Then it shows info regardless of connection time.
83
84 -t, --long-delay=time[ms]
85 shows packets with arrival time more than specified.
86 default is 0. Then it shows info regardless of arrival time.
87
88 -r, --retransmit=time[ms]
89 when 0, resent TCP segments will be ignored.
90 otherwise specified,it shows segments that were resent with more than specified time (milliseconds)
91 default is 1000 (milliseconds)
92
93 -s, --stat=interval[sec]
94 outputs statics periodically to stderr.
95 default is 0. Then no outputs.
96
97 -f, --file=file
98 Specifies file that is saved with tcpdump -w
99
100 -S, --syn=[0|1]
101 Detection for resending of SYN or SYN/ACK.
102 0: Detection is invalid
103 1: Detection is valid
104
105 This detection works independently of "r" option.
106 regardless of "r" option, when 1 is specified here, it will detect resending, while it will not detect when 1 is specified.
107
108 -R, --rst=[0|1|2]
109 Detection for sessions which was terminated with RST flag.
110 0: Detection is invalid
111 1: Detection is valid. However it does not detect RST after FIN is sent.
112 2: Detect all RST
113 default is 1
114
115 -F, --fragment=[0|1]
116 Detection for IP fragmentation
117 0: Detection is invalid
118 1: Detection is valid
119 default is 1
120
121 -C, --color=[0|1]
122 color display will be off when specifid 0.
123 Default is 1. However it will be 0 when stdout is saved as files or stdout is sent to other commands with pipes.
124 You need to specify 1 when you want color display while using pipes to send info to grep commands.
125
126 -L, --session-limit=NUM
127 Specify concurrent session numbers miruo holds.
128 This option specify the max number of miruo's internal buffer.
129 It prevents miruo from using too much memories(server resources), unintentionally by user.
130 Default is 1024. If dropSession value of stats is 0, there will be no need to increase this number.
131
132 -l, --segment-limit=NUM
133 Specifies the concurrent number of segments.
134 This option specify the max number of miruo's internal buffer.
135 It prevents miruo from using too much memories(server resources), unintentioned by a user.
136 Default is 65536. If dropSegment value of stats is 0, there will be no need to increase this number.
137
138 -m, --dpi-mode=mode
139 If you want to analyze payload of segments to show protocol specific information, specify the mode (protocol name).
140 http: shows HTTP request response information
141
142 -q, --quiet
143 shows simple version of display
144 If you prefer width shorter than 80 characters, you may want to use this option.
145
146 --all
147 shows all sessions
148
149 --live
150 shows all packets in real time
151
152[Statics]
153With s option, miruo outputs stats periodically to stderr.
154Detail of each columns are as below.
155
156===== Session Statistics =====
157Captcha Time : 00:01:03 elapsed time
158Total Sessions : 0 the number of sessions tracked
159 Lookup : 0 the number of TCP sessions showed
160 LongConnect : 0 the number of sessions exceeded LongConnectTime
161 LongDelay : 0 the number of sessions exceeded LongDelayTime
162 Retransmit : 0 the number of sessions resent
163 Timeout : 0 the number of sessions timeout
164 Error : 0 the number of error with unable to track
165 RST : 0 the number of sessions reset by RST
166 fragment : 0 the number of sessions with IP fragmented
167------------------------------
168LongConnectTime : 0 [ms] -T option set value
169LongDelayTime : 0 [ms] -t option set value
170RetransmitTime : 1000 [ms] -r option set value
171------------------------------
172ActiveSession : 0 the number of TCP sessions being tracked
173ActiveSessionMax: 0 the max number of TCP sessions tracked concurrently
174ActiveSessionLim: 1024 the max number of TCP sessions can be tracked concurrently( with -L option)
175ActiveSegment : 0 the number of active TCP segment
176ActiveSegmentMax: 0 the max number of active TCP segments required
177ActiveSegmentLim: 65536 the max number of segments miruo can hold (with -l option)
178DropSession : 0 the number of TCP sessions miruo disposed
179DropSegment : 0 the number of TCP segments miruo disposed
180------------------------------
181CPU : 0.0% CPU usage of miruo
182VSZ : 6100KB size of virtual memory that miruo holds
183RSS : 2932KB size of physical memory that miruo uses
184
185===== libpcap Statistics =====
186recv : 89 the number of packets libpcap captured
187drop : 0 the number of packets libpcap dropped
188ifdrop: 0 the number of packets a interface dropped
189===== Header Error Count =====
190L2 : 0 the number of times it failed to analyze datalink layer headers
191IP : 0 the number of times it failed to analyze IP headers
192TCP : 0 the number of times it failed to analyze TCP headers
193==============================
194
195[Explanation on displayed result]
196-------------------------------------------------------------------------------
1973615 2.196 | 192.168.61.88:38001 == 192.168.56.136:3306 | Total 92 segments, 43278 bytes
1983615:0000 17:57:19.193 | SYN_SENT >----S-> SYN_RECV | 5C503355/00000000 74 - <mss=1460, sackOK, timestamp 898447130 0, wscale=7>
1993615:0001 17:57:19.193 | ESTABLISHED <-A--S-< SYN_RECV | 6BCBB846/5C503356 74 - <mss=1460, sackOK, timestamp 899636678 898447130, wscale=7>
2003615:0002 17:57:19.193 | ESTABLISHED >-A----> ESTABLISHED | 5C503356/6BCBB847 66 - <timestamp 898447130 899636678>
2013615:0003 17:57:19.193 | ESTABLISHED <-AP---< ESTABLISHED | 6BCBB847/5C503356 126 - <timestamp 899636678 898447130>
2023615:0004 17:57:19.193 | ESTABLISHED >-A----> ESTABLISHED | 5C503356/6BCBB883 66 - <timestamp 898447130 899636678>
2033615:0005 17:57:19.193 | ESTABLISHED >-AP---> ESTABLISHED | 5C503356/6BCBB883 150 - <timestamp 898447130 899636678>
2043615:**** | |
2053615:0085 17:57:19.265 | ESTABLISHED <-A----< ESTABLISHED | 6BCC1685/5C505E8E 1514 - <timestamp 899636696 898447148>
2063615:0086 17:57:19.265 | ESTABLISHED <-AP---< ESTABLISHED | 6BCC1C2D/5C505E8E 687 - <timestamp 899636696 898447148>
2073615:0087 17:57:19.265 | ESTABLISHED >-A----> ESTABLISHED | 5C505E8E/6BCC1E9A 66 - <timestamp 898447148 899636696>
2083615:0088 17:57:21.389 | ESTABLISHED >-AP---> ESTABLISHED | 5C505E8E/6BCC1E9A 71 - <timestamp 898447679 899636696>
2093615:0089 17:57:21.389 | FIN_WAIT1 >-A---F> ESTABLISHED | 5C505E93/6BCC1E9A 66 - <timestamp 898447679 899636696>
2103615:0090 17:57:21.389 | FIN_WAIT2 <-A---F< LAST_ACK | 6BCC1E9A/5C505E94 66 - <timestamp 899637227 898447679>
2113615:0091 17:57:21.389 | TIME_WAIT >-A----> CLOSED | 5C505E94/6BCC1E9B 66 - <timestamp 898447679 899637227>
212-------------------------------------------------------------------------------
213The number on left "3615" is called "Session ID".
214This value itself does not hold any meanings. Everytime new session is started, miruo will allocate a new number, incremented internally.
215The next number delimited by a colon is called "Packet ID".
216The first SYN is 0 and it will increase as new packet arrives.
217 "Session ID" and "Packet ID" are unrelated parameters to TCP or IP protocols, just internally used by miruo.
218So those values do not have any special meanings.
219However, with sample above, it allows you to say,
220"The packet of Session ID 3615, Packet ID 88 seems to take more than 2 sec to arrive"
221It would make it easier to communicate with others on trouble shootings.
222
223Next is the time of packet capture.
224The first line is session time (from connected time to disconnected time). When it exceeds the time that was set by -T option, it will be displayed.
225
226The center part is self explanatory.
227
2285C503355/00000000 or 6BCBB846/5C503356 mean sequence number/response number of TCP header.
229
23074 or 66 or 1514 mean packet size.
231On some environments, it may be a value over 1514. This would be due to TOE(TCP Offload Engine), not troubles or bugs.
232
233'-' parts shows 'F' when IP fragmentation occurs. it will not show it so when F option is set to 0.
234
235The last parts, enclosed with <> are TCP header option.
236
237
README.ja
1/**************************************************************************/
2/* */
3/* miruo README.ja */
4/* */
5/* Copyright (C) 2011 KLab Inc. */
6/**************************************************************************/
7
8【はじめに】
9 miruoはパケットキャプチャ型のTCPセッションモニタです。
10 以下のような特徴があります。
11
12 - TCPセッション単位でパケットをまとめて表示できます
13 - TCPの接続、切断部分のみをコンパクトに表示できます
14 - セグメントが再送されたTCPセッションを発見できます
15 - 通信に時間がかかったTCPセッションを発見できます
16 - RSTで中断されたTCPセッションを発見できます
17 - IPでフラグメントされたセグメントを発見できます
18 - tcpdumpの-wで保存されたファイルを利用できます
19 - 軽量で高速に動作します
20
21【インストール方法】
22 $ tar zxvf miruo-x.y.z.tar.gz
23 $ cd miruo-x.y.z
24 $ ./configure
25 $ make
26 $ sudo make install
27
28 注意)
29 Linux以外での動作確認はしていません。ごめんなさい。
30
31【使い方】
32usage: miruo [option] [expression]
33 option
34 -h, --help # help
35 -V, --version # version
36 -i, --interface=dev # eth0,bond0,any...
37 -v, --view-data=NUM #
38 -T, --long-connect=time[ms] # Threshold of connection time for lookup. Default 0ms(off)
39 -t, --long-delay=time[ms] # Threshold of long delay time for lookup. Default 0ms(off)
40 -r, --retransmit=time[ms] # Threshold of retransmit time for lookup. Default 1000ms
41 -s, --stat=interval[sec] # statistics view interval. Default 0sec(off)
42 -f, --file=file # read file(for tcpdump -w)
43 -S, --syn=[0|1] # syn retransmit lookup mode.default=1. 0=ignore 1=lookup
44 -R, --rst=[0|1|2] # rst lookup mode.default=1. (see README)
45 -F, --fragment=[0|1] # ip fragment lookup. default=1
46 -C, --color=[0|1] # color 0=off 1=on
47 -L, --session-limit=NUM # active session limit. Default 1024
48 -l, --segment-limit=NUM # active segment limit. Default 65536
49 -m, --dpi-mode=mode # deep packet inspection mode. (now support only http)
50 -q, --quiet #
51 --all # all session lookup
52 --live # live mode(all segment lookup)
53
54expressionにはTCPダンプと同じ書式でフィルタを記述できます。
55ただし、"tcp[13] & 2 != 0"などのような、TCPの一部のパケットのみを抽出するルール
56を書いてしまうと、TCPセッションを追跡できなくなるので注意してください。フィルタ
57の書式についてはtcpdumpのmanを参照してください。
58
59良い例)
60 # miruo -T3000 host dbserver and port 3306
61 MySQLに3秒以上接続しているセッションを表示します
62
63悪い例)
64 # miruo -T3000 dst host dbserver and dst port 3306
65 SYN/ACKなどをキャプチャできないのでTCPを追跡できなくなります
66
67
68【オプションの詳細】
69
70 -h, --help
71 ヘルプを表示します。
72
73 -V, --version
74 バージョンを表示します。
75
76 -i, --interface=dev
77 ネットワークインターフェイスを指定します。
78 anyも指定できます。
79
80 -v, --view-data=NUM
81 この値が0の場合は、再送や遅延したパケットと、接続や切断に関するパケットのみを表
82 示します。0以外の値を指定すると、指定された数だけ他のパケットも表示されるように
83 なります。デフォルト値は0です。
84
85 -T, --long-connect=time[ms]
86 接続から切断までの時間が、ここで指定した時間以上だったセッションを表示するよう
87 に指示します。デフォルト値は0で、接続時間による抽出は行いません。
88
89 -t, --long-delay=time[ms]
90 ここで指定した時間よりも、長い時間をかけて到達したパケットを発見します。
91 デフォルト値は0で、到達時間による抽出は行いません。
92
93 -r, --retransmit=time[ms]
94 0を指定すると、再送されたTCPセグメントを無視します。
95 0以外の値を指定すると、指定された時間(ミリ秒単位)以上の時間をかけて再送された
96 セグメントを表示します。デフォルトは1000(ミリ秒)です。
97
98 -s, --stat=interval[sec]
99 定期的にstderrへ統計情報を出力します。
100 デフォルト値は0で、統計情報を表示しません。
101
102 -f, --file=file
103 tcpdump -w で保存したファイルを利用したい時にファイル名を指定してください。
104
105 -S, --syn=[0|1]
106 SYNもしくはSYN/ACKの再送を検出するかどうかを指定します。
107 0: 検出しません
108 1: 検出します
109 SYNとSYN/ACKの再送検出は、rオプションとは独立して処理されます。
110 rオプションの指定内容に関わらず、ここで1を指定すると再送を検出しますし、0を指
111 定すると検出しなくなります。
112
113 -R, --rst=[0|1|2]
114 RSTフラグで中断されたセッションを検出するかどうかを指定します。
115 0: 検出しません
116 1: 検出はしますが、FINを送った後のRSTは検出しません
117 2: 全てのRSTを検出します
118 デフォルト値は1です。
119
120 -F, --fragment=[0|1]
121 IPフラグメントを検出するかどうか指定します。
122 0: 検出しません。
123 1: 検出します。
124 デフォルト値は1です。
125
126 -C, --color=[0|1]
127 カラー表示をしたくない場合は0を指定してください。
128 デフォルトは1ですが、標準出力をファイルに落とす場合や、パイプで他のコマンドに
129 渡す場合は0になります。パイプでgrepなどに渡したいけど、カラー表示をしたいよう
130 な時には明示的に1を指定してください
131
132 -L, --session-limit=NUM
133 同時に保持できるセッション数を指定します。
134 これは、miruoの内部バッファの最大値を指定するオプションで、意図せずに大量のメ
135 モリ（サーバリソース）を使い過ぎないように制限するためのものです。
136 デフォルト値は1024ですが、統計情報(後述)の DropSessionの項目が0ならば増やす必
137 要はないでしょう。
138
139 -l, --segment-limit=NUM
140 同時に保持できるセグメント数を指定します。
141 これは、miruoの内部バッファの最大値を指定するオプションで、意図せずに大量のメ
142 モリ（サーバリソース）を使い過ぎないように制限するためのものです。
143 デフォルト値は65536ですが、統計情報(後述)の DropSegment の項目が0ならば増やす
144 必要はないでしょう。
145
146 -m, --dpi-mode=mode
147 セグメントのペイロードを解析してプロトコル固有の情報を表示したい場合は以下の
148 モード（プロトコル名）を指定します。
149 http: HTTPリクエスト・レスポンスの情報を表示します
150
151 -q, --quiet
152 シンプルな表示になります。
153 横幅が80文字以内じゃないと我慢出来ない場合に指定するとよいかもです。
154
155 --all
156 すべてのセッションを表示します。
157
158 --live
159 すべてのパケットをリアルタイムに表示します。
160
161
162[統計情報]
163
164sオプションを指定すると、定期的にstderrへ統計情報を出力するようになります。
165各項目の意味は以下のとおりです。
166
167===== Session Statistics =====
168Captcha Time : 00:01:03 開始してからの経過時間
169Total Sessions : 0 追跡したTCPセッションの数
170 Lookup : 0 表示したTCPセッションの数
171 LongConnect : 0 LongConnectTimeを超えたセッションの数
172 LongDelay : 0 LongDelayTimeを超えたセッションの数
173 Retransmit : 0 再送が発生したセッションの数
174 Timeout : 0 タイムアウトしたセッションの数
175 Error : 0 追跡しきれなくてエラーになった数
176 RST : 0 RSTでリセットされたセッションの数
177 fragment : 0 IPフラグメントされたセッションの数
178------------------------------
179LongConnectTime : 0 [ms] -Tオプションの設定値
180LongDelayTime : 0 [ms] -tオプションの設定値
181RetransmitTime : 1000 [ms] -rオプションの設定値
182------------------------------
183ActiveSession : 0 現在追跡しているTCPセッションの数
184ActiveSessionMax: 0 同時に追跡したTCPセッションの最大数
185ActiveSessionLim: 1024 同時に追跡可能なTCPセッションの最大数(-Lオプションで指定)
186ActiveSegment : 0 現在保持しているTCPセグメントの数
187ActiveSegmentMax: 0 同時に保持する必要があったセグメントの最大数
188ActiveSegmentLim: 65536 同時に保持可能なセグメントの最大数(-lオプションで指定)
189DropSession : 0 保持しきれなくて捨ててしまったTCPセッションの数
190DropSegment : 0 保持しきれなくて捨ててしまったTCPセグメントの数
191------------------------------
192CPU : 0.0% miruoのCPU使用率
193VSZ : 6100KB miruoが確保した仮想メモリサイズ
194RSS : 2932KB miruoが利用している物理メモリサイズ
195===== libpcap Statistics =====
196recv : 89 libpcapがキャプチャできたパケット数
197drop : 0 libpcapがドロップしたパケット数
198ifdrop: 0 インターフェイスがドロップしたパケット数
199===== Header Error Count =====
200L2 : 0 データリンク層のヘッダ解析に失敗した数
201IP : 0 IPヘッダの解析に失敗した数
202TCP : 0 TCPヘッダの解析に失敗した数
203==============================
204
205
206[表示結果の説明]
207-------------------------------------------------------------------------------
2083615 2.196 | 192.168.61.88:38001 == 192.168.56.136:3306 | Total 92 segments, 43278 bytes
2093615:0000 17:57:19.193 | SYN_SENT >----S-> SYN_RECV | 5C503355/00000000 74 - <mss=1460, sackOK, timestamp 898447130 0, wscale=7>
2103615:0001 17:57:19.193 | ESTABLISHED <-A--S-< SYN_RECV | 6BCBB846/5C503356 74 - <mss=1460, sackOK, timestamp 899636678 898447130, wscale=7>
2113615:0002 17:57:19.193 | ESTABLISHED >-A----> ESTABLISHED | 5C503356/6BCBB847 66 - <timestamp 898447130 899636678>
2123615:0003 17:57:19.193 | ESTABLISHED <-AP---< ESTABLISHED | 6BCBB847/5C503356 126 - <timestamp 899636678 898447130>
2133615:0004 17:57:19.193 | ESTABLISHED >-A----> ESTABLISHED | 5C503356/6BCBB883 66 - <timestamp 898447130 899636678>
2143615:0005 17:57:19.193 | ESTABLISHED >-AP---> ESTABLISHED | 5C503356/6BCBB883 150 - <timestamp 898447130 899636678>
2153615:**** | |
2163615:0085 17:57:19.265 | ESTABLISHED <-A----< ESTABLISHED | 6BCC1685/5C505E8E 1514 - <timestamp 899636696 898447148>
2173615:0086 17:57:19.265 | ESTABLISHED <-AP---< ESTABLISHED | 6BCC1C2D/5C505E8E 687 - <timestamp 899636696 898447148>
2183615:0087 17:57:19.265 | ESTABLISHED >-A----> ESTABLISHED | 5C505E8E/6BCC1E9A 66 - <timestamp 898447148 899636696>
2193615:0088 17:57:21.389 | ESTABLISHED >-AP---> ESTABLISHED | 5C505E8E/6BCC1E9A 71 - <timestamp 898447679 899636696>
2203615:0089 17:57:21.389 | FIN_WAIT1 >-A---F> ESTABLISHED | 5C505E93/6BCC1E9A 66 - <timestamp 898447679 899636696>
2213615:0090 17:57:21.389 | FIN_WAIT2 <-A---F< LAST_ACK | 6BCC1E9A/5C505E94 66 - <timestamp 899637227 898447679>
2223615:0091 17:57:21.389 | TIME_WAIT >-A----> CLOSED | 5C505E94/6BCC1E9B 66 - <timestamp 898447679 899637227>
223-------------------------------------------------------------------------------
224一番左の3615を、「セッションID」と呼びます。値自体には意味はなく、新しいTCPセッ
225ションが開始される度にmiruoが内部でインクリメントして割り当てていきます。その隣
226のコロンで区切られた数値を「パケットID」と呼びます。最初のSYNを0番とし、パケッ
227トが到着する度にインクリメントしていきます。「セッションID」と「パケットID」は、
228TCPやIPのプロトコルとは全く無関係なパラメータで、miruoの内部で利用している管理
229用のIDです。そのため、値自体は特別な意味を持ちませんが、上記の表示例の場合だと、
230
231「3615の88番のパケットが、到着するまでに2秒以上かかっているみたい」
232
233などと表現できるので、問題点を他の人と共有する際に便利だと思います。
234
235次に表示しているのはパケットをキャプチャした時刻です。
236先頭の行は接続時間（接続から切断までの経過時間）を表しており、この時間がTオプシ
237ョンで指定した値を超えたセッションが表示されます。
238
239中央の広い部分は、見ての通りなので説明は割愛します(^^;
240
2415C503355/00000000 や 6BCBB846/5C503356 はTCPヘッダのシーケンス番号/応答番号です。
242
24374とか66とか1514の数値はパケットサイズです。
244環境によっては1514以上の値が表示される場合があるかもしれませんが、それはきっと、
245故障でもバグでもなく、TOE(TCP Offload Engine)の影響だと思います。
246
247'-'と表示されている部分には、IPのフラグメントが発生している場合に'F'と表示される
248ようになります。Fオプションに0を指定すると、この項目は表示されません。
249
250最後の<>で囲まれている部分は、TCPヘッダのオプションです。
251
252
README.md
1[](https://travis-ci.org/KLab/miruo)
2
3# はじめに
4 miruo はパケットキャプチャ型の TCP セッションモニタです。
5 以下のような特徴があります。
6
7 - TCP セッション単位でパケットをまとめて表示できます
8 - TCP の接続、切断部分のみをコンパクトに表示できます
9 - セグメントが再送された TCP セッションを発見できます
10 - 通信に時間がかかった TCP セッションを発見できます
11 - RST で中断された TCP セッションを発見できます
12 - IP でフラグメントされたセグメントを発見できます
13 - tcpdump の -w で保存されたファイルを利用できます
14 - 軽量で高速に動作します
15
16## インストール方法
17
18 $ tar zxvf miruo-x.y.z.tar.gz
19 $ cd miruo-x.y.z
20 $ ./configure
21 $ make
22 $ sudo make install
23
24# 使い方
25
26 usage: miruo [option] [expression]
27
28 option
29 -h, --help # help
30 -V, --version # version
31 -i, --interface=dev # eth0,bond0,any...
32 -v, --view-data=NUM #
33 -T, --long-connect=time[ms] # Threshold of connection time for lookup. Default 0ms(off)
34 -t, --long-delay=time[ms] # Threshold of long delay time for lookup. Default 0ms(off)
35 -r, --retransmit=time[ms] # Threshold of retransmit time for lookup. Default 1000ms
36 -s, --stat=interval[sec] # statistics view interval. Default 0sec(off)
37 -f, --file=file # read file(for tcpdump -w)
38 -S, --syn=[0|1] # syn retransmit lookup mode.default=1. 0=ignore 1=lookup
39 -R, --rst=[0|1|2] # rst lookup mode.default=1. (see README)
40 -F, --fragment=[0|1] # ip fragment lookup. default=1
41 -C, --color=[0|1] # color 0=off 1=on
42 -L, --session-limit=NUM # active session limit. Default 1024
43 -l, --segment-limit=NUM # active segment limit. Default 65536
44 -m, --dpi-mode=mode # deep packet inspection mode. (now support only http)
45 -q, --quiet #
46 --all # all session lookup
47 --live # live mode(all segment lookup)
48
49`expression` には tcpdump と同じ書式でフィルタを記述できます。
50
51ただし、`tcp[13] & 2 != 0` などのような、TCP の一部のパケットのみを抽出するルールを書いてしまうと、TCP セッションを追跡できなくなるので注意してください。フィルタの書式については tcpdump の man を参照してください。
52
53**良い例**
54
55 # miruo -T3000 host dbserver and port 3306
56
57 *MySQL に3秒以上接続しているセッションを表示します*
58
59**悪い例**
60
61 # miruo -T3000 dst host dbserver and dst port 3306
62
63 *SYN/ACK などをキャプチャできないので TCP を追跡できなくなります*
64
65## オプションの詳細
66
67<dl>
68 <dt>-h, --help</dt>
69 <dd>ヘルプを表示します。</dd>
70
71 <dt>-V, --version</dt>
72 <dd>バージョンを表示します。</dd>
73
74 <dt> -i, --interface=dev</dt>
75 <dd>ネットワークインターフェイスを指定します。
76 <code>any</code> も指定できます。</dd>
77
78 <dt>-v, --view-data=NUM</dt>
79 <dd>この値が <code>0</code> の場合は、再送や遅延したパケットと、接続や切断に関するパケットのみを表示します。
80 <code>0</code> 以外の値を指定すると、指定された数だけ他のパケットも表示されるようになります。
81 デフォルト値は <code>0</code> です。</dd>
82
83 <dt>-T, --long-connect=time[ms]</dt>
84 <dd>接続から切断までの時間が、ここで指定した時間以上だったセッションを表示するように指示します。
85 デフォルト値は <code>0</code> で、接続時間による抽出は行いません。</dd>
86
87 <dt>-t, --long-delay=time[ms]</dt>
88 <dd>ここで指定した時間よりも、長い時間をかけて到達したパケットを発見します。
89 デフォルト値は <code>0</code> で、到達時間による抽出は行いません。</dd>
90
91 <dt>-r, --retransmit=time[ms]</dt>
92 <dd><code>0</code> を指定すると、再送されたTCPセグメントを無視します。
93 <code>0</code> 以外の値を指定すると、指定された時間（ミリ秒単位）以上の時間をかけて再送されたセグメントを表示します。
94 デフォルトは <code>1000</code>（ミリ秒）です。</dd>
95
96 <dt>-s, --stat=interval[sec]</dt>
97 <dd>定期的にstderrへ統計情報を出力します。
98 デフォルト値は <code>0</code> で、統計情報を表示しません。</dd>
99
100 <dt>-f, --file=file</dt>
101 <dd><code>tcpdump -w</code> で保存したファイルを利用したい時にファイル名を指定してください。</dd>
102
103 <dt>-S, --syn=[0|1]</dt>
104 <dd>
105 SYN もしくは SYN/ACK の再送を検出するかどうかを指定します。<br/>
106 <ul>
107 <li><strong>0:</strong> 検出しません</li>
108 <li><strong>1:</strong> 検出します</li>
109 </ul>
110 SYN と SYN/ACK の再送検出は、<code>-r</code> オプションとは独立して処理されます。
111 <code>-r</code> オプションの指定内容に関わらず、ここで <code>1</code> を指定すると再送を検出しますし、<code>0</code> を指定すると検出しなくなります。
112 </dd>
113
114 <dt>-R, --rst=[0|1|2]</dt>
115 <dd>
116 RST フラグで中断されたセッションを検出するかどうかを指定します。<br/>
117 <ul>
118 <li><strong>0:</strong> 検出しません</li>
119 <li><strong>1:</strong> 検出はしますが、FINを送った後のRSTは検出しません</li>
120 <li><strong>2:</strong> 全てのRSTを検出します</li>
121 </ul>
122 デフォルト値は <code>1</code> です。
123 </dd>
124
125 <dt>-F, --fragment=[0|1]</dt>
126 <dd>
127 IP フラグメントを検出するかどうか指定します。<br/>
128 <ul>
129 <li><strong>0:</strong> 検出しません</li>
130 <li><strong>1:</strong> 検出します</li>
131 </ul>
132 デフォルト値は <code>1</code> です。
133 </dd>
134
135 <dt>-C, --color=[0|1]</dt>
136 <dd>カラー表示をしたくない場合は <code>0</code> を指定してください。
137 デフォルトは <code>1</code> ですが、標準出力をファイルに落とす場合や、パイプで他のコマンドに渡す場合は <code>0</code> になります。
138 パイプで grep などに渡したいけど、カラー表示をしたいような時には明示的に <code>1</code> を指定してください</dd>
139
140 <dt>-L, --session-limit=NUM</dt>
141 <dd>同時に保持できるセッション数を指定します。
142 これは、miruo の内部バッファの最大値を指定するオプションで、意図せずに大量のメモリ（サーバリソース）を使い過ぎないように制限するためのものです。
143 デフォルト値は <code>1024</code> ですが、統計情報（後述）の <code>DropSession</code> の項目が <code>0</code> ならば増やす必要はないでしょう。</dd>
144
145 <dt>-l, --segment-limit=NUM</dt>
146 <dd>同時に保持できるセグメント数を指定します。
147 これは、miruo の内部バッファの最大値を指定するオプションで、意図せずに大量のメモリ（サーバリソース）を使い過ぎないように制限するためのものです。
148 デフォルト値は <code>65536</code> ですが、統計情報（後述）の <code>DropSegment</code> の項目が <code>0</code> ならば増やす必要はないでしょう。</dd>
149
150 <dt>-m, --dpi-mode=mode</dt>
151 <dd>
152 TCP セグメントのペイロードを解析してプロトコル固有の情報を表示したい場合は以下のモード（プロトコル名）を指定します。<br/>
153 <ul>
154 <li><strong>http:</strong> HTTPリクエスト・レスポンスの情報を表示します</li>
155 </ul>
156 </dd>
157
158 <dt>-q, --quiet</dt>
159 <dd>シンプルな表示になります。
160 横幅が <code>80</code> 文字以内じゃないと我慢出来ない場合に指定するとよいかもです。</dd>
161
162 <dt>--all</dt>
163 <dd>すべてのセッションを表示します。</dd>
164
165 <dt>--live</dt>
166 <dd>すべてのパケットをリアルタイムに表示します。</dd>
167</dl>
168
169## 統計情報
170
171`-s` オプションを指定すると、定期的に `stderr` へ統計情報を出力するようになります。
172各項目の意味は以下のとおりです。
173
174 ===== Session Statistics =====
175 Captcha Time : 00:01:03 開始してからの経過時間
176 Total Sessions : 0 追跡したTCPセッションの数
177 Lookup : 0 表示したTCPセッションの数
178 LongConnect : 0 LongConnectTimeを超えたセッションの数
179 LongDelay : 0 LongDelayTimeを超えたセッションの数
180 Retransmit : 0 再送が発生したセッションの数
181 Timeout : 0 タイムアウトしたセッションの数
182 Error : 0 追跡しきれなくてエラーになった数
183 RST : 0 RSTでリセットされたセッションの数
184 fragment : 0 IPフラグメントされたセッションの数
185 ------------------------------
186 LongConnectTime : 0 [ms] -Tオプションの設定値
187 LongDelayTime : 0 [ms] -tオプションの設定値
188 RetransmitTime : 1000 [ms] -rオプションの設定値
189 ------------------------------
190 ActiveSession : 0 現在追跡しているTCPセッションの数
191 ActiveSessionMax: 0 同時に追跡したTCPセッションの最大数
192 ActiveSessionLim: 1024 同時に追跡可能なTCPセッションの最大数(-Lオプションで指定)
193 ActiveSegment : 0 現在保持しているTCPセグメントの数
194 ActiveSegmentMax: 0 同時に保持する必要があったセグメントの最大数
195 ActiveSegmentLim: 65536 同時に保持可能なセグメントの最大数(-lオプションで指定)
196 DropSession : 0 保持しきれなくて捨ててしまったTCPセッションの数
197 DropSegment : 0 保持しきれなくて捨ててしまったTCPセグメントの数
198 ------------------------------
199 CPU : 0.0% miruoのCPU使用率
200 VSZ : 6100KB miruoが確保した仮想メモリサイズ
201 RSS : 2932KB miruoが利用している物理メモリサイズ
202 ===== libpcap Statistics =====
203 recv : 89 libpcapがキャプチャできたパケット数
204 drop : 0 libpcapがドロップしたパケット数
205 ifdrop: 0 インターフェイスがドロップしたパケット数
206 ===== Header Error Count =====
207 L2 : 0 データリンク層のヘッダ解析に失敗した数
208 IP : 0 IPヘッダの解析に失敗した数
209 TCP : 0 TCPヘッダの解析に失敗した数
210 ==============================
211
212
213***表示結果の説明***
214
215 -------------------------------------------------------------------------------
216 3615 2.196 | 192.168.61.88:38001 == 192.168.56.136:3306 | Total 92 segments, 43278 bytes
217 3615:0000 17:57:19.193 | SYN_SENT >----S-> SYN_RECV | 5C503355/00000000 74 - <mss=1460, sackOK, timestamp 898447130 0, wscale=7>
218 3615:0001 17:57:19.193 | ESTABLISHED <-A--S-< SYN_RECV | 6BCBB846/5C503356 74 - <mss=1460, sackOK, timestamp 899636678 898447130, wscale=7>
219 3615:0002 17:57:19.193 | ESTABLISHED >-A----> ESTABLISHED | 5C503356/6BCBB847 66 - <timestamp 898447130 899636678>
220 3615:0003 17:57:19.193 | ESTABLISHED <-AP---< ESTABLISHED | 6BCBB847/5C503356 126 - <timestamp 899636678 898447130>
221 3615:0004 17:57:19.193 | ESTABLISHED >-A----> ESTABLISHED | 5C503356/6BCBB883 66 - <timestamp 898447130 899636678>
222 3615:0005 17:57:19.193 | ESTABLISHED >-AP---> ESTABLISHED | 5C503356/6BCBB883 150 - <timestamp 898447130 899636678>
223 3615:**** | |
224 3615:0085 17:57:19.265 | ESTABLISHED <-A----< ESTABLISHED | 6BCC1685/5C505E8E 1514 - <timestamp 899636696 898447148>
225 3615:0086 17:57:19.265 | ESTABLISHED <-AP---< ESTABLISHED | 6BCC1C2D/5C505E8E 687 - <timestamp 899636696 898447148>
226 3615:0087 17:57:19.265 | ESTABLISHED >-A----> ESTABLISHED | 5C505E8E/6BCC1E9A 66 - <timestamp 898447148 899636696>
227 3615:0088 17:57:21.389 | ESTABLISHED >-AP---> ESTABLISHED | 5C505E8E/6BCC1E9A 71 - <timestamp 898447679 899636696>
228 3615:0089 17:57:21.389 | FIN_WAIT1 >-A---F> ESTABLISHED | 5C505E93/6BCC1E9A 66 - <timestamp 898447679 899636696>
229 3615:0090 17:57:21.389 | FIN_WAIT2 <-A---F< LAST_ACK | 6BCC1E9A/5C505E94 66 - <timestamp 899637227 898447679>
230 3615:0091 17:57:21.389 | TIME_WAIT >-A----> CLOSED | 5C505E94/6BCC1E9B 66 - <timestamp 898447679 899637227>
231 -------------------------------------------------------------------------------
232
233一番左の 3615 を、`セッションID` と呼びます。値自体には意味はなく、新しいTCPセッションが開始される度に miruo が内部でインクリメントして割り当てていきます。その隣のコロンで区切られた数値を `パケットID` と呼びます。最初の SYN を 0番とし、パケットが到着する度にインクリメントしていきます。`セッションID` と `パケットID` は、TCP や IP のプロトコルとは全く無関係なパラメータで、miruo の内部で利用している管理用の ID です。そのため、値自体は特別な意味を持ちませんが、上記の表示例の場合だと、
234
235> 3615の88番のパケットが、到着するまでに2秒以上かかっているみたい
236
237などと表現できるので、問題点を他の人と共有する際に便利だと思います。
238
239次に表示しているのはパケットをキャプチャした時刻です。
240先頭の行は接続時間（接続から切断までの経過時間）を表しており、この時間が `-T` オプションで指定した値を超えたセッションが表示されます。
241
242中央の広い部分は、見ての通りなので説明は割愛します(^^;
243
244`5C503355/00000000` や `6BCBB846/5C503356` はTCPヘッダのシーケンス番号/応答番号です。
245
24674 とか 66 とか 1514 の数値はパケットサイズです。
247環境によっては 1514 以上の値が表示される場合があるかもしれませんが、それはきっと、故障でもバグでもなく、`TOE（TCP Offload Engine）` の影響だと思います。
248
249`-` と表示されている部分には、IP のフラグメントが発生している場合に `F` と表示されるようになります。`-F` オプションに <code>0</code> を指定すると、この項目は表示されません。
250
251最後の `<>` で囲まれている部分は、TCP ヘッダのオプションです。
252
253# ライセンス
254Copyright (C) 2011-2015 KLab Inc.
255
256このプログラムは `GNU General Public License version 3（GNU GPLv3）` の下で自由に配布することが出来ます。
257
258`GNU GPLv3` の詳細は、http://www.gnu.org/licenses/gpl-3.0.txt をご覧ください。
259
){kind=link}