Difference between revisions of "Freeside:3:Documentation:Developer/FS/IP Mixin"

Latest revision as of 13:35, 27 June 2014

NAME

FS::IP_Mixin - Mixin class for objects that have IP addresses assigned.

INTERFACE

The inheritor may provide the following methods:

ip_addr [ ADDRESS ]

Get/set the IP address, as a string. If the inheritor is also an FS::Record subclass and has an 'ip_addr' field, that field will be used. Otherwise an ip_addr method must be defined.

addr_block [ BLOCK ]

Get/set the address block, as an FS::addr_block object. By default, the 'blocknum' field will be used.

router [ ROUTER ]

Get/set the router, as an FS::router object. By default, the 'routernum' field will be used. This is strictly optional; if present the IP address can be assigned from all those available on a router, rather than in a specific block.

_used_addresses [ BLOCK ]

Return a list of all addresses in use (within BLOCK, if it's specified). The inheritor should cache this if possible.

_is_used ADDRESS

Test a specific address for availability. Should return an empty string if it's free, or else a description of who or what is using it.

METHODS

ip_check

The method that should be called from check() in the subclass. This does the following:

- In an auto_router situation, sets the router and block to match the object's IP address. - Otherwise, if the router and IP address are both set, validate the choice of router and set the block correctly. - Otherwise, if the router is set, assign an address (in the selected block if there is one). - Check the IP address for availability.

Returns an error if this fails for some reason (an address can't be assigned from the requested router/block, or the requested address is unavailable, or doesn't seem to be an IP address).

If router and IP address are both empty, this will do nothing. The object's check() method should decide whether to allow a null IP address.

assign_ip_addr

Set the IP address to a free address in the selected block (addr_block) or router (router) for this object. A block or router MUST be selected. If the object already has an IP address and it is in that block/router's address space, it won't be changed.

assign_router

If the IP address is set, set the router and block accordingly. If there is no block containing that address, returns an error.

check_ip_addr

Validate the IP address. Returns an empty string if it's correct and available (or null), otherwise an error message.

used_addresses [ BLOCK ]

Returns a list of all addresses (in BLOCK, or in all blocks) that are in use. If called as an instance method, excludes that instance from the search.

is_used ADDRESS

Returns a string describing what object is using ADDRESS, or an empty string if it's not in use.

BUGS

We can't reliably check for duplicate addresses across tables. A more robust implementation would be to put all assigned IP addresses in a single table with a unique index. We do a best-effort check anyway, but it has a race condition.