'\" t
.\" Automatically generated by Pandoc 2.17.1.1
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "ripcalc" "1" "17 April 2025" "ripcalc 0.2.5" "User Manual"
.hy
.SH NAME
.PP
ripcalc - a tool for network addresses
.SH SYNOPSIS
.PP
\f[B]ripcalc 127.0.0.1\f[R]
.PP
\f[B]ripcalc -4/--ipv4 127.0.0.1\f[R]
.PP
\f[B]ripcalc -6/--ipv6 ::1\f[R]
.PP
\f[B]ripcalc -f/--format \[lq]%a/%c\[rq] 127.0.0.1\f[R]
.PP
\f[B]ripcalc -m/--mask 28 127.0.0.1\f[R]
.PP
\f[B]ripcalc -c/--csv path/to/csv [-i/--field network] 127.0.0.1\f[R]
.PP
\f[B]ripcalc -l/--list 127.0.0.1\f[R]
.PP
\f[B]ripcalc -a/--available\f[R]
.PP
\f[B]ripcalc -s/--file [-] 127.0.0.1\f[R]
.PP
\f[B]ripcalc -e/--encapsulating [-s/--file name] [--group CIDR]\f[R]
.PP
\f[B]ripcalc -s/--file name [--inside/--outside] 127.0.0.1\f[R]
.PP
\f[B]ripcalc -b/--base [8, 10, 16 etc]\f[R]
.PP
\f[B]ripcalc -d/--divide [CIDR] 127.0.0.1/24\f[R]
.PP
\f[B]ripcalc \[en]networks [CIDR] 127.0.0.1/24\f[R]
.PP
\f[B]ripcalc -h/--help\f[R]
.SH DESCRIPTION
.PP
\f[B]ripcalc\f[R] can read IPv4/IPv6 addresses from command line or
standard input and output different formats or associated networks from
\f[B]CSV\f[R].
.PP
\f[B]ripcalc\f[R] can format network addresses, find matches in
\f[B]CSV\f[R] or process a list.
.PP
\f[B]ripcalc\f[R] can convert input addresses that are in other number
formats such as hex or octal.
.PP
Given a list of IP addresses, print only those that match the network.
When \f[V]s\f[R] and \f[V]inside\f[R] are used, only addresses from
\f[V]-s\f[R] are printed if they are that are inside of the input IP
network from the command line.
This can be reversed with \f[V]--outside\f[R],
(e.g.\ \f[V]ripcalc -s - --inside 192.168.0.0/16\f[R]).
.PP
When \f[V]-a\f[R] is used, addresses read from \f[V]-s\f[R] will not be
shown when listing \f[V]-l\f[R] a network, showing only available
addresses.
.PP
When \f[V]--reverse\f[R] is used the \f[V]inputs\f[R], \f[V]sources\f[R]
or both can be treated as back-to-front.
.PP
\f[B]ripcalc\f[R] can return a list of subnets when a network is
provided along with the \f[V]--divide\f[R] argument and a subnet CIDR
mask.
.PP
When \f[V]--encapsulating\f[R] is used the containing network will be
returned, use with \f[V]--group\f[R] to limit the range that an
encapsulating network can grow.
.PP
The number (\f[B]%D\f[R]) of subnets can be printed when using the
\f[V]--group\f[R] argument with the \f[B]%N\f[R] formatters.
The argument should be the CIDR mask, see below for example.
.PP
If \f[B]base\f[R] is a negative number, input addresses are treated as
though the input is a signed integer in \f[B]base\f[R].
.SH CSV
.PP
Network matches can be returned from a \f[B]CSV\f[R].
.IP
.nf
\f[C]
$ cat nets.csv
network,range,owner
rfc1918,192.168.0.0/16,bob
rfc1918,172.16.0.0/12,cliff
rfc1918,10.0.0.0/8,mr nobody
$ ripcalc --csv nets.csv -i range --format \[aq]%{owner}\[rs]n\[aq] 192.168.0.0
bob
\f[R]
.fi
.PP
Addresses can be read via file or from stdin (-):
.IP
.nf
\f[C]
$ cat list
127.0.0.1/28
10.0.0.1/28
192.168.1.1/30
172.18.1.1/30
10.0.0.0/30
$ ripcalc --csv nets.csv -i range --format \[aq]%{range} %{owner}\[rs]n\[aq] -s list
10.0.0.0/8 mr nobody
192.168.0.0/16 bob
172.16.0.0/12 cliff
10.0.0.0/8 mr nobody
\f[R]
.fi
.SH FORMAT
.PP
\f[B]%\f[R] denotes a format control character, followed by one of the
following:
.PP
.TS
tab(@);
l l.
T{
placeholder
T}@T{
effect
T}
_
T{
%a
T}@T{
IP address string
T}
T{
%n
T}@T{
Network address string
T}
T{
%s
T}@T{
Subnet address string
T}
T{
%w
T}@T{
Wildcard address string
T}
T{
%b
T}@T{
Broadcast address string
T}
.TE
.PP
Additional characters prefixing the above placeholder can control the
representation:
.PP
.TS
tab(@);
l l.
T{
placeholder
T}@T{
effect
T}
_
T{
%B
T}@T{
Binary address string
T}
T{
%S
T}@T{
Split binary at network boundary string
T}
T{
%l
T}@T{
Unsigned integer string
T}
T{
%L
T}@T{
Signed integer string
T}
T{
%x
T}@T{
Hex address string
T}
.TE
.PP
Other format characters:
.PP
.TS
tab(@);
l l.
T{
placeholder
T}@T{
effect
T}
_
T{
%c
T}@T{
CIDR mask
T}
T{
%C
T}@T{
In encapsulated context, used address count
T}
T{
%t
T}@T{
Network size
T}
T{
%r
T}@T{
Network reservation information (if available)
T}
T{
%d
T}@T{
Matching device interface by IP
T}
T{
%m
T}@T{
Matching media link interface by network
T}
T{
%p
T}@T{
PTR record
T}
T{
%k
T}@T{
RBL/reverse DNS-style format
T}
T{
%D
T}@T{
Network size (--networks)
T}
T{
%N
T}@T{
Number of subnets (--networks)
T}
T{
%%
T}@T{
%
T}
T{
\[rs]n
T}@T{
Line break
T}
T{
\[rs]t
T}@T{
Tab character
T}
.TE
.PP
\f[B]%xa\f[R] gives the address in hex, or \f[B]%Sa\f[R] to return the
binary address, split at the network boundary.
.PP
When using \f[B]CSV\f[R] fields can be matched by \f[B]name\f[R] when
network matched:
.IP
.nf
\f[C]
--format \[aq]%{name}\[aq]
\f[R]
.fi
.SH inside/outside
.PP
When \f[V]--inside\f[R] or \f[V]--outside\f[R] are given addresses that
match \f[V]--file\f[R] are printed.
If no matches are found \f[V]ripcalc\f[R] will exit non-zero.
.SH subnets
.PP
For large networks it can be useful to see the number of subnets, to see
the number of /29 subnets within a /24 network, the command would look
like this:
.IP
.nf
\f[C]
ripcalc --networks 29 192.168.230.0/24
            IP is: 192.168.230.0/24
     Broadcast is: 192.168.230.255
       Network is: 192.168.230.0
        Subnet is: 255.255.255.0
      Wildcard is: 0.0.0.255
    Networks (29): 32
\f[R]
.fi
.PP
Or for a IPv6 /48 network that you want to subnet into /64, you can see
there are 65536 subnets:
.IP
.nf
\f[C]
 ripcalc --networks 64 2001:db8:1::/48
                IP is: 2001:db8:1::/48
         Expanded: 2001:0db8:0001:0000:0000:0000:0000:0000
       Network is: 2001:0db8:0001:0000:0000:0000:0000:0000
Last host address: 2001:0db8:0001:ffff:ffff:ffff:ffff:ffff
        Subnet is: ffff:ffff:ffff:0000:0000:0000:0000:0000
    Networks (64): 65536
\f[R]
.fi
.SH encapsulating
.PP
Suppose a large flood of requests are from a network pattern, to
preserve service you may want to block the whole network that
encapsulates a list:
.IP
.nf
\f[C]
please ip route add blackhole \[ga]ripcalc -e 192.168.56.10 192.168.57.1 192.168.44.47\[ga]
\f[R]
.fi
.PP
Networks can be grouped, in a scenario where you have a list of unwanted
traffic, you can turn this into a list of small networks to block,
supposing you don\[cq]t want to block anything that covers more than a
/19:
.IP
.nf
\f[C]
cat bad_traffic | ripcalc --encapsulating --group 19 --format cidr
\f[R]
.fi
.PP
When using \f[V]group\f[R] the unique IP address count is available in
the \f[V]%C\f[R] format string.
This can give an overview of which networks have most IP sources:
.IP
.nf
\f[C]
cat bad_traffic | ripcalc --encapsulating --group 19 --format \[aq]%C %a/%c\[rs]n\[aq] | sort -rn
\f[R]
.fi
.SH AUTHORS
Ed Neville (ed-ripcalc\[at]s5h.net).