.TH  ipExtension.tcl l Cisco ATS

.SH NAME
::ipExtension:: \- an extension to tcllib ip library
.SH SYNOPSIS

.nf

package require ipExtension

.fi

.SH AUTHORS
.PP

.nf
Aamer Akhter / aakhter@cisco.com
.fi

.SH SUPPORT
.PP

.nf
aakhter@cisco.com
.fi

.SH DESCRIPTION
.PP

.nf
A detailed description of the functionality provided by the library.
.fi

.SH REQUIREMENTS
.PP

.nf

package require logger
package require ip

.fi

.SH NOTES

.nf

1.

.fi

.SH PROCEDURES

.nf
::ip::prefixToNative
.fi

.RS

.PP

.nf
convert from dotted from to native (hex) form
.fi

.RS
.PP

.nf

prefixToNative <prefix>

.fi

.RE

Options:

.RS

.nf

<prefix>
    string in the <ipaddr>/<mask> format

.fi

.RE

Return values:

.RS

.nf

<prefix> in native format {<hexip> <hexmask>}

.fi

.RE

Examples:

.RS

.nf

% ip::prefixToNative 1.1.1.0/24
0x01010100 0xffffff00

.fi

.RE

Notes:

.RS

.nf

fixed bug in C extension that modified 
 calling context variable

.fi

.RE

.RE

.nf
::ip::nativeToPrefix
.fi

.RS

.PP

.nf
convert from native (hex) form to dotted form
.fi

.RS
.PP

.nf

nativeToPrefix <nativeList>|<native> [-ipv4]

.fi

.RE

Options:

.RS

.nf

<nativeList> 
    list of native form ip addresses native form is:
<native>
    tcllist in format {<hexip> <hexmask>}
-ipv4
    the provided native format addresses are in ipv4 format (default)

.fi

.RE

Return values:

.RS

.nf

if nativeToPrefix is called with <native> a single (non-listified) address
    is returned
if nativeToPrefix is called with a <nativeList> address list, then 
    a list of addresses is returned

return form is: <ipaddr>/<mask>

.fi

.RE

Examples:

.RS

.nf

% ip::nativeToPrefix {0x01010100 0xffffff00} -ipv4
1.1.1.0/24

.fi

.RE

.RE

.nf
::ip::intToString
.fi

.RS

.PP

.nf
convert from an integer/hex to dotted form
.fi

.RS
.PP

.nf

intToString <integer/hex> [-ipv4]

.fi

.RE

Options:

.RS

.nf

<integer>
    ip address in integer form
-ipv4
    the provided integer addresses is ipv4 (default)

.fi

.RE

Return values:

.RS

.nf

ip address in dotted form

.fi

.RE

Examples:

.RS

.nf

ip::intToString 4294967295
255.255.255.255

.fi

.RE

.RE

.nf
::ip::toInteger
.fi

.RS

.PP

.nf
convert dotted form ip to integer
.fi

.RS
.PP

.nf

toInteger <ipaddr>

.fi

.RE

Options:

.RS

.nf

<ipaddr>
    decimal dotted from ip address

.fi

.RE

Return values:

.RS

.nf

integer form of <ipaddr>

.fi

.RE

Examples:

.RS

.nf

% ::ip::toInteger 1.1.1.0
16843008

.fi

.RE

.RE

.nf
::ip::toHex
.fi

.RS

.PP

.nf
convert dotted form ip to hex
.fi

.RS
.PP

.nf

toHex <ipaddr>

.fi

.RE

Options:

.RS

.nf

<ipaddr>
    decimal dotted from ip address

.fi

.RE

Return values:

.RS

.nf

hex form of <ipaddr>

.fi

.RE

Examples:

.RS

.nf

% ::ip::toHex 1.1.1.0
0x01010100

.fi

.RE

.RE

.nf
::ip::maskToInt
.fi

.RS

.PP

.nf
convert mask to integer
.fi

.RS
.PP

.nf

maskToInt <mask>

.fi

.RE

Options:

.RS

.nf

<mask>
    mask in either dotted form or mask length form (255.255.255.0 or 24)

.fi

.RE

Return values:

.RS

.nf

integer form of mask

.fi

.RE

Examples:

.RS

.nf

::ip::maskToInt 24
4294967040

.fi

.RE

.RE

.nf
::ip::broadcastAddress
.fi

.RS

.PP

.nf
return broadcast address given prefix
.fi

.RS
.PP

.nf

broadcastAddress <prefix> [-ipv4]

.fi

.RE

Options:

.RS

.nf

<prefix>
    route in the form of <ipaddr>/<mask> or native form {<hexip> <hexmask>}
-ipv4
    the provided native format addresses are in ipv4 format (default)
    note: broadcast addresses are not valid in ipv6

.fi

.RE

Return values:

.RS

.nf

ipaddress of broadcast

.fi

.RE

Examples:

.RS

.nf

::ip::broadcastAddress 1.1.1.0/24
1.1.1.255

::ip::broadcastAddress {0x01010100 0xffffff00}
0x010101ff

.fi

.RE

.RE

.nf
::ip::maskToLength
.fi

.RS

.PP

.nf
converts dotted or integer form of mask to length
.fi

.RS
.PP

.nf

maskToLength <dottedMask>|<integerMask>|<hexMask> [-ipv4]

.fi

.RE

Options:

.RS

.nf

<dottedMask>
<integerMask>
<hexMask>
    mask to convert to prefix length format (eg /24)
 -ipv4
    the provided integer/hex format masks are ipv4 (default)

.fi

.RE

Return values:

.RS

.nf

prefix length

.fi

.RE

Examples:

.RS

.nf

::ip::maskToLength 0xffffff00 -ipv4
24

% ::ip::maskToLength 255.255.255.0
24

.fi

.RE

.RE

.nf
::ip::lengthToMask
.fi

.RS

.PP

.nf
converts mask length to dotted mask form
.fi

.RS
.PP

.nf

lengthToMask <maskLength> [-ipv4]

.fi

.RE

Options:

.RS

.nf

<maskLength>
    mask length   
-ipv4
    the provided mask length is ipv4 (default)

.fi

.RE

Return values:

.RS

.nf

mask in dotted form

.fi

.RE

Examples:

.RS

.nf

::ip::lengthToMask 24
255.255.255.0

.fi

.RE

.RE

.nf
::ip::nextNet
.fi

.RS

.PP

.nf
returns next an ipaddress in same position in next network
.fi

.RS
.PP

.nf

nextNet <ipaddr> <mask> [<count>] [-ipv4]

.fi

.RE

Options:

.RS

.nf

<ipaddress>
    in hex/integer/dotted format
<mask>
    mask in hex/integer/dotted/maskLen format
<count>
    number of nets to skip over (default is 1)
-ipv4
    the provided hex/integer addresses are in ipv4 format (default)

.fi

.RE

Return values:

.RS

.nf

ipaddress in same position in next network in hex

.fi

.RE

.RE

.nf
::ip::isOverlap
.fi

.RS

.PP

.nf
checks to see if prefixes overlap
.fi

.RS
.PP

.nf

isOverlap <prefix> <prefix1> <prefix2>...

.fi

.RE

Options:

.RS

.nf

<prefix>
    in form <ipaddr>/<mask> prefix to compare <prefixN> against
<prefixN>
    in form <ipaddr>/<mask> prefixes to compare against

.fi

.RE

Return values:

.RS

.nf

1 if there is an overlap

.fi

.RE

Examples:

.RS

.nf

% ::ip::isOverlap 1.1.1.0/24 2.1.0.1/32
0

::ip::isOverlap 1.1.1.0/24 2.1.0.1/32 1.1.1.1/32
1

.fi

.RE

.RE

.nf
::ip::isOverlapNative
.fi

.RS

.PP

.nf
checks to see if prefixes overlap (optimized native form)
.fi

.RS
.PP

.nf

isOverlap <hexipaddr> <hexmask> {{<hexipaddr1> <hexmask1>} {<hexipaddr2> <hexmask2>...}

.fi

.RE

Options:

.RS

.nf

-all
    return all overlaps rather than the first one
-inline
    rather than returning index values, return the actual overlap prefixes
<hexipaddr>
    ipaddress in hex/integer form
<hexMask>
    mask in hex/integer form
-ipv4
    the provided native format addresses are in ipv4 format (default)

.fi

.RE

.nf
isOverlapNative is avaliabel both as a C extension and in a native tcl form
if the extension is loaded (tried automatically), isOverlapNative will be
linked to isOverlapNativeC. If an extension is not loaded, then isOverlapNative
will be linked to the native tcl proc: ipOverlapNativeTcl.
.fi

Return values:

.RS

.nf

non-zero if there is an overlap, value is element # in list with overlap

.fi

.RE

Examples:

.RS

.nf

% ::ip::isOverlapNative 0x01010100 0xffffff00 {{0x02010001 0xffffffff}}
0

%::ip::isOverlapNative 0x01010100 0xffffff00 {{0x02010001 0xffffffff} {0x01010101 0xffffffff}}
2

.fi

.RE

.RE

.nf
::ip::ipToLayer2Multicast
.fi

.RS

.PP

.nf
converts ipv4 address to a layer 2 multicast address
.fi

.RS
.PP

.nf

ipToLayer2Multicast <ipaddr>

.fi

.RE

Options:

.RS

.nf

<ipaddr>
    ipaddress in dotted form

.fi

.RE

Return values:

.RS

.nf

mac address in xx.xx.xx.xx.xx.xx form

.fi

.RE

Examples:

.RS

.nf

% ::ip::ipToLayer2Multicast 224.0.0.2
01.00.5e.00.00.02

.fi

.RE

.RE

.nf
::ip::ipHostFromPrefix
.fi

.RS

.PP

.nf
gives back a host address from a prefix
.fi

.RS
.PP

.nf

::ip::ipHostFromPrefix <prefix> [-exclude <list of prefixes>]

.fi

.RE

Options:

.RS

.nf

<prefix>
    prefix is <ipaddr>/<masklen>
-exclude <list of prefixes>
    list if ipprefixes that host should not be in

.fi

.RE

Return values:

.RS

.nf

ip address

.fi

.RE

Examples:

.RS

.nf

%::ip::ipHostFromPrefix  1.1.1.5/24
1.1.1.1

%::ip::ipHostFromPrefix  1.1.1.1/32
1.1.1.1

.fi

.RE

.RE

.nf
::ip::reduceToAggregates
.fi

.RS

.PP

.nf
finds nets that overlap and filters out the more specifc nets
.fi

.RS
.PP

.nf

::ip::reduceToAggregates <prefixList>

.fi

.RE

Options:

.RS

.nf

<prefixList>
    prefixList a list in the from of
    is <ipaddr>/<masklen> or native format

.fi

.RE

Return values:

.RS

.nf

non-overlapping ip prefixes

.fi

.RE

Examples:

.RS

.nf


  % ::ip::reduceToAggregates {1.1.1.0/24 1.1.0.0/8  2.1.1.0/24 1.1.1.1/32 }
  1.0.0.0/8 2.1.1.0/24

.fi

.RE

.RE

.nf
::ip::longestPrefixMatch
.fi

.RS

.PP

.nf
given host IP finds longest prefix match from set of prefixes
.fi

.RS
.PP

.nf

::ip::longestPrefixMatch <ipaddr> <prefixList> [-ipv4]

.fi

.RE

Options:

.RS

.nf

<prefixList>
    is list of <ipaddr> in native or dotted form
<ipaddr>
    ip address in <ipprefix> format, dotted form, or integer form
-ipv4
    the provided integer format addresses are in ipv4 format (default)

.fi

.RE

Return values:

.RS

.nf

<ipprefix> that is the most specific match to <ipaddr>

.fi

.RE

Examples:

.RS

.nf

% ::ip::longestPrefixMatch 1.1.1.1 {1.1.1.0/24 1.0.0.0/8  2.1.1.0/24 1.1.1.0/28 }
1.1.1.0/28

.fi

.RE

.RE

.nf
::ip::cmpDotIP
.fi

.RS

.PP

.nf
helper function for dotted ip address for use in lsort
.fi

.RS
.PP

.nf

::ip::cmpDotIP <ipaddr1> <ipaddr2>

.fi

.RE

Options:

.RS

.nf

<ipaddr1> <ipaddr2>
    prefix is in dotted ip address format

.fi

.RE

Return values:

.RS

.nf

-1 if ipaddr1 is less that ipaddr2
 1 if ipaddr1 is more that ipaddr2
 0 if ipaddr1 and ipaddr2 are equal

.fi

.RE

Examples:

.RS

.nf

% lsort -command ip::cmpDotIP {1.0.0.0 2.2.0.0 128.0.0.0 3.3.3.3}
1.0.0.0 2.2.0.0 3.3.3.3 128.0.0.0

.fi

.RE

.RE