AggregateIP Element Documentation

AggregateIP -- Click element; sets aggregate annotation based on IP packet field

AggregateIP(FIELD, KEYWORDS)

Ports: 1 input, 1-2 outputs
Processing: agnostic, but output 1 is push
Drivers: userlevel
Package: analysis (core)

AggregateIP sets the aggregate annotation on every passing packet to a portion of that packet's IP header, transport header, or payload, depending on the value of the FIELD argument. FIELD can be the name of a header field, like "ip tos", or a general offset-length specification, like "ip[8:2]". Either form can be modified with a mask, such as "ip src/8" or "ip[8:2] & 0x3F0". The aggregate annotation value uses host byte order. Valid header field names are "ip vers", "ip hl", "ip tos", "ip dscp", "ip ecn", "ip len", "ip id", "ip off" (the entire fragmentation offset field), "ip rf", "ip df", "ip mf", "ip fragoff" (just the fragmentation offset value, without the RF, DF, and MF bits), "ip ttl", "ip proto", "ip sum", "ip src", "ip dst", "udp sport", "udp dport", "udp len", "udp sum", "tcp sport", "tcp dport", "tcp seq", "tcp ack", "tcp hl", "tcp flags", "tcp fin", "tcp syn", "tcp rst", "tcp psh", "tcp ackf", "tcp urg", "tcp win", "tcp sum", "tcp urp", "icmp type", "icmp code", and "icmp sum". General offset-length specifications begin with "ip", "transp", or "data", depending on whether the offset should be measured relative to the IP header, transport header, or payload. (The names "tcp", "udp", and "icmp" act like "transp", but enforce the specified IP protocol.) Next comes the offset and length, which can take several forms:

[OFFSET:LENGTH]

The LENGTH bytes starting at byte OFFSET.

[OFFSET1-OFFSET2]

From byte OFFSET1 to byte OFFSET2, inclusive.

[OFFSET]

The single byte at OFFSET.

{OFFSET:LENGTH}, {OFFSET1-OFFSET2}, {OFFSET}

Similar, but OFFSETs and LENGTHs are measured in bits. Finally, the mask can equal either `/NUM', which means take the top NUM bits of the field, or `& MASK', which means bitwise-and the field with MASK. (MASK must contain exactly one set of contiguous 1 bits.) Keyword arguments are:

INCREMENTAL

Boolean. If true, then incrementally update the aggregate annotation: given a field N bits wide with value V, and an old aggregate annotation of O, the new aggregate annotation will equal (O * 2^N) + V. Default is false.

UNSHIFT_IP_ADDR

Boolean. If true, and the aggregated field lies within either the IP source or destination address, then set the aggregate annotation to the masked portion of that address without shifting. For example, consider a packet with source address 1.0.0.0, and aggregate field "ip src/8". Without UNSHIFT_IP_ADDR, the packet will get aggregate annotation 1; with UNSHIFT_IP_ADDR, it will get aggregate annotation 16777216. Default is false.

Packets lacking the specified field are pushed onto output 1, or dropped if there is no output 1. A packet may lack a field because it is too short, it is a fragment, or it has the wrong protocol. ("tcp sport", for example, is relevant only for first-fragment TCP packets; "data" specifications work only for first-fragment TCP and UDP.) The simple specifications "sport" and "dport" (no "ip", "tcp", or "udp") apply to either TCP or UDP packets.

Here are a bunch of equivalent ways to ask for the top 8 bits of the IP source address:

        AggregateIP(ip src/8)
        AggregateIP(ip src & 0xFF000000)
        AggregateIP(ip[12])
        AggregateIP("ip[12, 1]")        // protect comma
        AggregateIP("ip{96, 8}")
        AggregateIP(ip{96-103})

header (read-only)

Returns the header type AggregateIP is using: either "ip", "transp", or "payload".

bit_offset (read-only)

Returns the offset into the header of the start of the aggregated field, in bits.

bit_length (read-only)

Returns the length of the aggregated field, in bits.

AggregateLength, AggregateIPFlows, AggregateCounter, AggregatePaint

Generated by 'click-elem2man' from '../elements/analysis/aggregateip.hh' on 24/May/2007.