NAME

Net::BGP4::Update - Class encapsulating BGP4 UPDATE message

SYNOPSIS

    use Net::BGP4::Update qw( :origin );

    # Constructor
    $update = new Net::BGP4::Update(
        Aggregator      => [ 64512, '10.0.0.1' ],
        AsPath          => [ 64512, 64513, 64514 ],
        AtomicAggregate => 1,
        Communities     => [ qw( 64512:10000 64512:10001 ) ],
        LocalPref       => 100,
        MED             => 200,
        NLRI            => [ qw( 10/8 172.168/16 ) ],
        NextHop         => '10.0.0.1',
        Origin          => INCOMPLETE,
        Withdraw        => [ qw( 192.168.1/24 172.10/16 192.168.2.1/32 ) ]
    );

    # Accessor Methods
    $aggregator_ref   = $update->aggregator($aggregator_ref);
    $as_path_ref      = $update->as_path($as_path_ref);
    $atomic_aggregate = $update->atomic_aggregate($atomic_aggregate);
    $communities_ref  = $update->communities($communities_ref);
    $local_pref       = $update->local_pref($local_pref);
    $med              = $update->med($med);
    $next_hop         = $update->next_hop($next_hop);
    $nlri_ref         = $update->nlri($nlri_ref);
    $origin           = $update->origin($origin);
    $withdrawn_ref    = $update->withdrawn($withdrawn_ref);

DESCRIPTION

This module encapsulates the data contained in a BGP4 UPDATE message. It provides a constructor, and accessor methods for each of the message fields and well-known path attributes of an UPDATE. Whenever a Net::BGP4::Peer sends an UPDATE message to its peer, it does so by passing a Net::BGP4::Update object to the peer object's update() method. Similarly, when the peer receives an UPDATE message from its peer, the UPDATE callback is called and passed a reference to a Net::BGP4::Update object. The callback function can then examine the UPDATE message fields by means of the accessor methods.

CONSTRUCTOR

new() - create a new Net::BGP4::Update object

    $update = new Net::BGP4::Update(
        Aggregator      => [ 64512, '10.0.0.1' ],
        AsPath          => [ 64512, 64513, 64514 ],
        AtomicAggregate => 1,
        Communities     => [ qw( 64512:10000 64512:10001 ) ],
        LocalPref       => 100,
        MED             => 200,
        NLRI            => [ qw( 10/8 172.168/16 ) ],
        NextHop         => '10.0.0.1',
        Origin          => INCOMPLETE,
        Withdraw        => [ qw( 192.168.1/24 172.10/16 192.168.2.1/32 ) ]
    );

This is the constructor for Net::BGP4::Update objects. It returns a reference to the newly created object. The following named parameters may be passed to the constructor. See RFC 1771 for the semantics of each path attribute.

Aggregator

This parameter corresponds to the AGGREGATOR path attribute. It is expressed as an array reference, the first element of which is the AS number (in the range of an 16-bit unsigned integer) of the route aggregator, and the second element is the aggregator's IP address expressed in dotted-decimal notation as a string. It may be omitted, in which case no AGGREGATOR path attribute will be attached to the UPDATE message.

AsPath

This parameter corresponds to the AS_PATH path attribute. It is expressed as an array reference of AS path numbers, each in the range of a 16-bit unsigned integer. This path attribute is mandatory and this parameter must always be provided to the constructor.

AtomicAggregate

This parameter corresponds to the ATOMIC_AGGREGATE path attribute. It is a boolean value so any value which perl interprets as true/false may be used. It may be omitted, in which case no ATOMIC_AGGREGATE path attribute will be attached to the UPDATE message.

Communities

This parameter corresponds to the COMMUNITIES attribute defined in RFC 1997. It is expressed as an array reference of communities which apply to the route(s). The communities are encoded in a special format: AAAA:CCCC, where AAAA corresponds to the 16-bit unsigned integer AS number, and CCCC is a 16-bit unsigned integer of arbitrary value. But see RFC 1997 for the semantics of several reserved community values. This attribute may be omitted, in which case no COMMUNITIES attribute will be attached to the UPDATE message.

LocalPref

This parameter corresponds to the LOCAL_PREF path attribute. It is expressed as a 32-bit unsigned integer scalar value. It may be omitted, in which case no LOCAL_PREF path attribute will be attached to the UPDATE message.

MED

This parameter corresponds to the MULTI_EXIT_DISC path attribute. It is expressed as a 32-bit unsigned integer scalar value. It may be omitted, in which case no MULTI_EXIT_DISC path attribute will be attached to the UPDATE message.

NLRI

This parameter corresponds to the Network Layer Reachability Information (NLRI) field of an UPDATE message. It represents the route(s) being advertised in this particular UPDATE. It is expressed as an array reference of route prefixes which are encoded in a special format as perl strings: XXX.XXX.XXX.XXX/XX. The part preceding the slash is a dotted-decimal notation IP prefix. Only as many octets as are significant according to the mask need to be specified. The part following the slash is the mask which is an integer in the range [0,32] which indicates how many bits are significant in the prefix. At least one of either the NLRI or Withdraw parameters is mandatory and must always be provided to the constructor.

NextHop

This parameter corresponds to the NEXT_HOP path attribute. It is expressed as a dotted-decimal IP address as a perl string. This path attribute is mandatory and the parameter must always be provided to the constructor.

Origin

This parameter corresponds to the ORIGIN path attribute. It is expressed as an integer scalar value, which can take the following enumerated values: IGP, EGP, or INCOMPLETE. The preceding symbols can be imported into the program namespace individually or by the :origin export tag. This path attribute is mandatory and the parameter must always be provided to the constructor.

Withdraw

This parameter corresponds to the Withdrawn Routes field of an UPDATE message. It represents route(s) advertised by a previous UPDATE message which are now being withdrawn by this UPDATE. It is expressed in the same way as the NLRI parameter. At least one of either the NLRI or Withdraw parameters is mandatory and must always be provided to the constructor.

ACCESSOR METHODS

aggregator()

as_path()

atomic_aggregate()

communities()

local_pref()

med()

next_hop()

nlri()

origin()

withdrawn()

These accessor methods return the value(s) of the associated UPDATE message field or path attribute if called with no arguments. If called with arguments, they set the associated field. The representation of parameters and return values is the same as described for the corresponding named constructor parameters above.

EXPORTS

The module exports the following symbols according to the rules and conventions of the Exporter module.

:origin IGP, EGP, INCOMPLETE

AUTHOR

Stephen J. Scheck <code@neurosphere.com>

Net::BGP4::Update - Class encapsulating BGP4 UPDATE message