/
ntopng.8
339 lines (282 loc) · 11.2 KB
/
ntopng.8
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
.\" This file Copyright 1998-2005 Luca Deri <deri@ntop.org>
.\"
.
.de It
.TP 1.2
.B "\\$1 "
..
.de It2
.TP 1.2
.B "\\$1 | \\$2"
..
.TH NTOP 8 "Jun 2013 (ntopng 1.0)"
.SH NAME
ntopng \- display top network users
.SH SYNOPSIS
.B ntopng
.RB [ filename ]
or
.B ntopng
.RB [ -i
.IR <interface|pcap> ]
.RB [ -d
.IR <data_directory> ]
.RB [ -n
.IR <mode> ]
.RB [ -e ]
.RB [ -w
.IR <http_port> ]
.RB [ -c
.IR <categorization_key> ]
.RB [ -m
.IR <local_subnets> ]
.RB [ -p
.IR <protocols> ]
.RB [ -r
.IR <redis_host:port> ]
.RB [ -s ]
.RB [ -U
.IR <sys_user> ]
.RB [ -l ]
.RB [ -X
.IR <max num flows> ]
.RB [ -B
.IR <filter> ]
.RB [ -C ]
.RB [ -A
.IR <mode> ]
.RB [ -x
.IR <max num hosts> ]
.RB [ -F
.IR <dump-flows> ]
.RB [ -D
.IR <dump-hosts> ]
.RB [ -E
.IR <dump-aggregations> ]
.RB [ -v ]
.RB [ -h ]
.SH DESCRIPTION
.B ntopng
shows the current network usage. It displays a list of hosts that are
currently using the network and reports information concerning the (IP and non-IP)
traffic generated and received by each host.
.B ntop
may operate as a front-end collector or as a stand-alone collector/display program.
A web browser is needed to access the information captured by the
.B ntopng
program.
.B ntopng
is a hybrid layer 2 / layer 3 network monitor, by default it uses the layer 2 Media
Access Control (MAC) addresses AND the layer 3 tcp/ip addresses.
.B ntopng
is capable of associating the two, so that ip and non-ip traffic (e.g. arp, rarp) are combined
for a complete picture of network activity.
.PP
.SH "COMMAND\-LINE OPTIONS"
.It filename
The text of
.B filename
is copied - ignoring line breaks and comment lines (anything following a #) - into the
command line.
.B ntopng
behaves as if all of the text had simply been typed directly on the command line.
For example, if the command line is "ntopng s.conf" and file s.conf contains
just the line '-s', then the effective command line is "ntopng -s".
In case you use a configuration file, the following options on the command line
will be ignored. Example "ntopng /etc/ntopng/ntopng.conf -v" the -v option is ignored.
The configuration file is similar to the command line, with the exception that an equal
sign '=' must be used between key and value. Example:
-i=p1p2
or
--interface=p1p2
For options with no value (e.g. -v) the equal is also necessary. Example: "-v=" must be used.
Remember, most
.B ntopng
options are "sticky", that is they just set an internal flag. Invoking
them multiple times doesn't change the
.B ntopng's
behavior. However, options that set a value, such as --trace-level, will use the LAST value
given: -w 8000 -w 8080 will run as -w 8080.
.It -n|--dns-mode
Sets the DNS address resolution mode:
0 - Decode DNS responses and resolve only local (-m) numeric IPs
1 - Decode DNS responses and resolve all numeric IPs
2 - Decode DNS responses and don't resolve numeric IPs
3 - Don't decode DNS responses and don't resolve numeric IPs
.It -i|--interface
Specifies the network interface or collector endpoint to be used by
.B ntopng
for network monitoring. On Unix you can specify both the interface name (e.g. lo)
or the numeric interface id as shown by ntopng -h. On Windows you must use
the interface number instead. Note that you can specify -i multiple times in order
to instruct
.B ntopng
to create multiple interfaces.
If a collector endpoint is specified,
.B ntopng
open a ZeroMQ connection to the specified endpoint as a subscriber whose format
is "script_name@endpoint". ntopng will connect to the endpoint and let incoming
flows to be handled by script_name that is a lua script present in
scripts/callbacks (relative path). If just the endpoint is specified the script
used will be scripts/callbacks/nprobe-collector.lua
. Example of valid
collector endpoints are "nprobe-collector.lua@tcp://127.0.0.1:5556" or ipc://flows.ipc
If you want you can pass a path of a pcap file (e.g. -i dummy.pcap) and ntopng
will read packets from the specified pcap file.
.B nProbe
can be instructed to act as a publisher delivering flows to a ZeroMQ endpoint using the --zmq <endpoint> parameter.
.It -d|--data-dir
Specifies the data directory (it must be writable). Default directory is ./data
.It -c|--categorization-key
Sets the key used to access host categorization services.
.B ntopng
categorizes hosts using services provided by http://block.si
In order to use these categorization services you need to mail info@block.si and
ask for a test key to be used in ntopng.
For test driving the service please use as key 9hoAtewwpC2tXRMJBfifrY24B
(example ntopng -c 9hoAtewwpC2tXRMJBfifrY24B .....).
.It -e|--daemon
This parameter causes ntop to become a daemon, i.e. a task which runs in the background without connection to a specific terminal. To use ntop other than as a casual monitoring tool, you probably will want to use this option.
.It -w|--http-port
Sets the HTTP port of the embedded web server.
.It -m|--local-networks
.B ntopng
determines the ip addresses and netmasks for each active interface. Any traffic on
those networks is considered local. This parameter allows the user to define additional
networks and subnetworks whose traffic is also considered local in
.B ntopng
reports. All other hosts are considered remote. If not specified the default is
set to 192.168.1.0/24.
Commas separate multiple network values.
Both netmask and CIDR notation may be used, even mixed together, for instance
"131.114.21.0/24,10.0.0.0/255.0.0.0".
.It -p|--ndpi-protocols
This parameter is used to specify a nDPI protocol file.
The format is <tcp|udp>:<port>,<tcp|udp>:<port>,.....@<proto> where
<port> is a port number and <proto> is a name of a protocol supported by nDPI protocol,
or host:"<string>"@<proto> where string is part of an host name.
As example see https://svn.ntop.org/svn/ntop/trunk/nDPI/example/protos.txt
.It -r|--redis
Specifies the redis database host and port. For more information about redis, please refer
to http://redis.io/.
.It -U|--user
Run ntopng with the specified system user instead of 'nobody'.
.It -B|--packet-filter
Specifies the packet filter for the specified interface. For pcap/PF_RING interfaces
the filter has to be specified in BPF format (Berkeley Packet Filter).
.It -C|--dump-timeline
Enable timeline dump on disk (default: disabled).
.It -A|--enable-aggregations <mode>
Enable data aggregations (e.g. Operating System, DNS etc). The available modes are:
0 (disable aggregations, default), 1 (enable aggregations but do not dump on disk
their activity timeline), 2 (enable aggregations and timeline dump on disk).
.It -X|--max-num-flows
Specify the maximum number of active flows that ntopng will handle. If more flows are
detected they will be discarded.
.It -x|--max-num-hosts
Specify the maximum number of active hosts that ntopng will handle. If more hosts are
detected they will be discarded.
.It -s|--dont-change-user
Do not change user (debug only)
.It -l|--disable-login
Disable user login. This is useful for debug purposes or if you want to let everyone access the web gui.
.It -F|--dump-flows
If ntopng is compiled with sqlite support, flows can dumped persistently on disk using this option.
Databases are created daily under <data directory>/<interface>db.
.It -D|--dump-hosts
If ntopng is compiled with sqlite support, hosts contacts can dumped persistently on disk using this option.
Databases are created daily under <data directory>/<interface>/contacts. This options supports three dump
modes: local (dumps only local hosts), remote (dumps only remote hosts), all (dumps all hosts). If not
specified, no hosts are dumped to disk.
.It -E|--dump-aggregations
If ntopng is compiled with sqlite support, hosts contacts can dumped persistently on disk using this option.
Databases are created daily under <data directory>/<interface>/contacts. This options supports three dump
modes: local (dumps only aggregations contacted by local hosts), remote (dumps only aggregations contacted by
remote hosts), all (dumps all aggregations). If not specified, no hosts are dumped to disk.
.It -v|--verbose
Verbose tracing
.It -h|--help
Help
.SH "WEB VIEWS"
While
.B ntopng
is running, multiple users can access the traffic information using their web browsers.
.B ntopng
makes use of JavaScript and LESS CSS.
We do not expect problems with any current web browser, but our ability to test with less
common ones is very limited. Testing has included Safari, Chrome, Firefox and Internet Explorer,
with very limited testing on other current common browsers such as Opera.
.SH NOTES
.B ntop
requires a number of external tools and libraries to operate.
Certain other tools are optional, but add to the program's capabilities.
Required libraries include:
.B libpcap
from http://www.tcpdump.org/, version 1.0 or newer.
The Windows version makes use of
.B WinPcap
(libpcap for Windows) which may be downloaded from
http://winpcap.polito.it/install/default.htm.
.
.B ntopng
requires a POSIX threads library.
.
The
.B rrdtool
library creates 'Round-Robin databases' which are used to store historical data
in a format that permits long duration retention without growing larger over time.
The rrdtool home page is http://people.ee.ethz.ch/~oetiker/webtools/rrdtool/
The
.B LuaJIT
library is a Just-In-Time Compiler for Lua used to execute GUI and periodic scripts.
The
.B mongoose
library is used to implement the HTTP server part of ntopng.
.B zeromq
is a socket library supporting the publish/subscribe pattern used to collect flows from
.B nProbe
.
.B ntopng
includes LuaJIT, mongoose, rrdtool and zeromq in the third-party/ directory. Users of
.B ntopng
should not need to specifically install such libraries.
.
.SH "SEE ALSO"
.BR top (1),
.BR tcpdump (8),
.BR pcap (3).
.
.
.SH PRIVACY NOTICE
By default at startup and at periodic intervals, the
.B ntop
program will retrieve current ntopng program version information.
Retrieving this information allows this
.B ntop
instance to confirm that it is running the most current version.
The retrieval is done using standard http:// requests, which will create log
records on the hosting system. These log records do contain information which
identifies a specific
.B ntop
site. Accordingly, you are being notified that this individually identifiable
information is being transmitted and recorded.
You may request - via the
.B --skip-version-check
run-time option - that this check be eliminated. If you use this option, no
individually identifiable information is transmitted or recorded, because the
entire retrieval and check is skipped.
.SH USER SUPPORT
Please send bug reports to the ntop-dev <ntop-dev@ntop.org> mailing list. The
ntopng <ntop@ntop.org> mailing list is used for discussing ntopng usage issues. In
order to post messages on the lists a (free) subscription is required
to limit/avoid spam. Please do NOT contact the author directly unless this is
a personal question.
Commercial support is available upon request. Please see the ntopng site for further info.
Please send code patches to <patch@ntop.org>.
.SH AUTHOR
ntop's author is Luca Deri (http://luca.ntop.org/) who can be reached at <deri@ntop.org>.
.SH LICENCE
ntopng is distributed under the GNU GPL licence (http://www.gnu.org/).
.SH ACKNOWLEDGMENTS
The author acknowledges the Centro Serra of the University of Pisa, Italy (http://www-serra.unipi.it/) for
hosting the ntopng sites (both web and mailing lists).