forked from measurement-factory/ipv4-heatmap
-
Notifications
You must be signed in to change notification settings - Fork 0
/
ipv4-heatmap.1
319 lines (319 loc) · 9.46 KB
/
ipv4-heatmap.1
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
.\"
.\" IPv4 Heatmap
.\" (C) 2011 The Measurement Factory, Inc
.\" Licensed under the GPL, version 2
.\" http://maps.measurement-factory.com/
.\"
.Dd 02 May, 2011
.Dt ipv4-heatmap 1
.Os
.Sh NAME
.Nm ipv4-heatmap
.Nd Create a map of IPv4 address data
.Sh SYNOPSIS
.Nm
.Op Fl dhprm
.Op Fl A Ar float
.Op Fl B Ar float
.Op Fl a Ar file
.Op Fl f Ar font
.Op Fl g Ar seconds
.Op Fl k Ar file
.Op Fl o Ar file
.Op Fl s Ar file
.Op Fl t Ar string
.Op Fl u Ar string
.Op Fl y Ar prefix
.Op Fl z Ar bits
< iplist
.Sh DESCRIPTION
.Nm
is a program that generates a map of IPv4 address data using a
space-filling Hilbert Curve. Inspiration for
.Nm
comes from the xkcd comic (http://www.xkcd.org/195/).
.Pp
The output of
.Nm
is a 4096x4096 PNG image.
Each pixel in the image represents a single /24 network and is assigned
one of 256 colors. Typically, the pixel color
represents the number of hosts within the /24 belonging to a
dataset or having some property, such as being pingable or
being the source of some traffic.
.Pp
Pixel colors range from blue (1 host) to red (256 hosts),
while black represents no data (0 hosts). Of course, the colors
and pixel values may also be used to represent other properties of
IPv4 addresses.
.Pp
The map may be annotated by placing transparent
text labels over specific regions of address space.
.Pp
.Nm
also supports shading of areas specified by CIDR netblocks. This is
useful to show reserved and other special address space, for example.
.Pp
.Nm
can also add an optional legend to the map.
.Pp
.Nm
uses the GD library (libgd) to create the map image.
.Sh COMMAND LINE OPTIONS
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl A Ar logmin
Input data will be scaled logarithmically such that
input values less than or equal to
.Pa logmin
will be set to 1.
.It Fl B Ar logmax
Input data will be scaled logarithmically such that
input values greater than or equal to
.Pa logmax
will be set to 255.
.It Fl C
Values accumulate when using the Exact input mode.
.It Fl a Ar annotations
The
.Pa annotations
file contains a list of annotations for the map. See ANNOTATIONS below
for the format of this file.
.It Fl c Ar color
The color of the annotations (those that appear inside the map). Specified
as 0xRRGGBB.
.It Fl d
increase debugging levels.
.It Fl f Ar font
Specifies the font to use for the legend and annotations. If
libgd was compiled with fontconfig support, then this can be a
fontconfig string such as "Times-12:bold". Otherwise, you can
also specify the pathname to a True Type Font (.ttf) file.
.It Fl g Ar seconds
This option enables animated GIF output mode. A new frame is created for
each
.Pa seconds
interval of the input data file. See the ANIMATED GIFS below for
additional details.
.It Fl h
Attach a horizontal legend to the bottom of the map. Note that
the legend is drawn only if the
.Fl t
option is given.
.It Fl k Ar keyfile
Use
.Pa keyfile
to create the legend scale, rather than the built-in blue-to-red scale.
.It Fl m
Use Morton (aka "Z") Curve ordering instead of Hilbert.
.It Fl o Ar outfile
Output file name. If none is given, the image is saved as map.png by
default.
.It Fl p
Include a section in the legend that shows the size of CIDR prefixes.
Boxes and labels will be drawn to show the size of /8, /12, /16, /20, and /24
prefixes.
.It Fl r
Reverse the background and foreground colors.
.It Fl s Ar shades
The
.Ar shades
file can be used to shade certain areas of the map with specific colors
and transparency levels. See SHADING below for the format of this file.
.It Fl t Ar title
Instructs
.Nm
to draw a legend for the map and place the
.Ar title
string in the top (or right) section.
You may use "\\n" to create multi-line titles. By default the legend
will be drawn vertically and attached to the right side of the map.
Use the
.Fl h
option to create a horizontal legend instead.
.It Fl u Ar string
Instructs
.Nm
to draw a scale in the legend showing the range of colors
and their values.
.Ar string
will be placed above the scale. Currently,
.Nm
always assumes the data represents some kind of utilization
and prints percentages from 0 to 100% next to the scale.
.It Fl y Ar cidr
Specifies the CIDR netblock that should be rendered. The default
is to render the entire IPv4 space (0.0.0.0/0). The "slash" value
must be even so that the output image is square.
The
.Fl y
and
.Fl z
options together determine the size of the output image.
.It Fl z Ar bits
Specifies the number of address space bits assigned to each pixel
in the output image. By default each pixel represents a /24 network,
which corresponds to 8 host bits (i.e., 256 hosts). Specify 0 here
for one pixel per host address.
.El
.Sh INPUT MODES
.Nm
accepts three input modes:
.Bl -enum
.It
Increment mode.
.Pp
In this mode, the input consists of IPv4 addresses only, one
address per line. Each address in the list increments the pixel
value for the corresponding /24.
In this mode, repeated addresses may lead to false results because
.Nm
does not check for uniqueness of the input values. It silently
limits pixels to the maximum value. The user should run the data
through
.Xr sort 1
and
.Xr uniq 1
beforehand, if necessary.
.It
Exact mode.
.Pp
In this mode, the input consists of two whitespace-separated fields:
an IPv4 address and a color index. The color index is an integer
in the range 0--255. Be careful with this mode because later
addresses may overwrite earlier ones in the same /24.
.It
Logarithmic mode.
.Pp
Very similar to Exact mode, except that the second column is
logarithmically scaled to calculate the color index. In order to
use this mode the input must have two fields, and the
.Fl A Ar logmin
and
.Fl B Ar logmax
command line options must be given. Color index
.Vt k
is calculated from input value
.Vt i
according to this formula:
.Bd -literal -offset indent
ln ( i / logmin)
k = 255 * --------------------
ln (logmax / logmin)
.Ed
.El
.Sh ANNOTATIONS
The annotations file consists of two or three TAB-separated fields. The first field
is a CIDR prefix, and the second is the annotation string. The annotation string
is rendered within
the boundary of that prefix, centered both vertically and horizontally.
The third field, if present, is also rendered just below the
annotation text in a fixed-size 12-point font. If the third field is
equal to the string "prefix" then the CIDR prefix (from field 1) is rendered instead.
.Pp
The annotations file might look like this, for example:
.Bd -literal -offset indent
15.0.0.0/8 HP
16.0.0.0/8 DEC
17.0.0.0/8 Apple
.Ed
.Pp
The
.Nm
source code distribution should include a file named iana-labels.txt,
which is based on the list of IPv4 assignments made by IANA.
.Pp
The font can be selected with the
.Fl f
command line option.
At this time, however, the text color and transparency are hard-coded in the
.Nm
program.
.Sh SHADING
Areas of the map can be "shaded" by using the
.Fl s Ar shades
option. This was originally developed simply to highlight address space that
is designated reserved or unallocated, but is also a useful way to
render complex map data. The
.Ar shades
file consists of three TAB-separated fields: prefix, color, and alpha value.
.Pp
The CIDR prefix specifies the area to be shaded. The color should
be specified has a hexadecimal value beginning with "0x". The alpha value
controls the transparency of the shaded area and is passed directly to
the GD library functions. An alpha value of 0 means full transparency, while
a value of 127 means no transparency (full opacity). Here is an example that
shows RFC 1918 address space in a light purple color:
.Bd -literal -offset indent
10.0.0.0/8 0x7F7FFF 64
172.16.0.0/12 0x7F7FFF 64
192.168.0.0/16 0x7F7FFF 64
.Ed
.Sh ANIMATED GIFS
When the
.Fl g
option is given,
.Nm
outputs an animated GIF image file. This feature requires the
.Xr gifsicle 1
program to be installed.
.Pp
This feature also requires timestamps in the input data. Thus, use of the
.Fl g
option changes the input format. Each line of the input must begin with
a timestamp given in Unix epoch time. For example:
.Bd -literal -offset indent
1234567890.123 192.168.1.1
1234567890.234 192.168.1.2
1234567891.456 192.168.1.3
.Ed
.Pp
Note that decimal time values are accepted, although the fractional seconds are
ignored.
.Nm
Assumes that the input timestamps are already sorted. A new output frame
is generated every
.Ar seconds
seconds of the input file.
.Pp
Note that, currently, the data accumulates between frames. That is, any
pixels that are colored at the end of one frame will also be colored at the
start of the next frame.
.Sh HILBERT CURVE
.Nm
uses a 12th-order Hilbert Curve to represnet the entire IPv4 address
space. Locating a particular IP address along the curve can
be confusing at first.
Here is what a 2nd-order Hilbert curve looks like:
.Bd -literal -offset indent
0---1 14--15
| |
3---2 13--12
| |
4 7---8 11
| | | |
5---6 9---10
.Ed
.Pp
The best way to understand how the Hilbert Curve works is to try
drawing your own!
.Sh COPYRIGHT
.Bd -literal -offset indent
IPv4 Heatmap
(C) 2011 The Measurement Factory, Inc
Licensed under the GPL, version 2
http://maps.measurement-factory.com/
.Ed
.Sh SEE ALSO
.Xr gifsicle 1
.Sh AUTHORS
.Nm
was written by Duane Wessels of The Measurement Factory, Inc.
With contributions from: Roy Arends of Nominet UK.
.Sh BUGS
Can't draw IPv6 address maps.
.Pp
The legends don't look all that great. You can use an image editing
program like The Gimp to rearrange the legend and add better-looking
text.