NAME

Device::OUI - Resolve an Organizationally Unique Identifier

SYNOPSIS

use Device::OUI;

my $oui = Device::OUI->new( '00:17:F2' );
printf( "Organization: %s\n", $oui->organization );

DESCRIPTION

This module provides an interface to the IEEE OUI (Organizationally Unique Identifier) registry. The registry contains information on what company an OUI is assigned to. OUIs are used in various networking devices as part of a unique ID method (network MAC addresses and Fiber Channel WWNs in particular, see the Device::MAC and Device::WWN modules for more information).

CONFIGURATION

This module has a handful of configuration options, mostly dealing with where to get the source for the registry data, and where to store the cache.

These configuration options are inherited, and you can change them for the main class, a subclass, or a specific object. Note that changing a configuration option for an object does not change it for other objects of that class (see Class::Accessor::Grouped/get_inherited).

use Device::OUI;
Device::OUI->cache_db( '/tmp/oui_cache' );

Device::OUI->cache_db( $db )

Returns the filename where the cache database should be stored. If given an argument you can change the file to store the cache database in.

The default is C:\device_oui on windows, and /var/cache/device_oui on everything else. Set this to undef to disable the cache database. (Device::OUI->cache_db( undef )).

Note that AnyDBM_File may append an extension (usually '.db') to whatever you use as the filename, depending on which *DBM_File classes are available on your machine.

Device::OUI->cache_file( $filename )

Returns the filename where the oui.txt file should be stored when downloaded from the internet, or where the file can be found if you are downloading it by some other means.

The default is C:\device_oui.txt on windows, and /var/cache/device_oui.txt on everything else. Set this to undef to disable the cache file. (Device::OUI->cache_file( undef )).

Device::OUI->search_url( $url )

The URL for the OUI search page. Normally you don't need to change this, but it is provided as a configuration option in case the page is relocated. You can also set this to undef to disable runtime searches.

This value is used by /search_url_for to create a search url for a specific OUI. The default implementation allows you to include a '%s' token in the URL, in which case the URL will be formatted with perlfunc/sprintf, using the OUI as an argument. If the url provided does not contain a '%s' token, then the OUI will simply be appended to the end (in which case, the URL provided should probably end with something like: ?arg=).

Device::OUI->file_url( $url );

The URL to download the entire oui.txt registry file. Normally you don't need to change this either, but you can set it to undef to disable registry downloading.

CLASS METHODS

my $oui = Device::OUI->new( $oui );

Creates and returns a new Device::OUI object. If an OUI is provided, it will be passed to the oui method detailed below. Creating an object without an oui is not an error, but any method that should return data will croak when you call it if no oui has been provided either at construction time or by calling the /oui method.

Device::OUI->load_cache_from_file( $file );

The /load_cache_from_file method is used to load up the cache database with data from an OUI registry file. If no filename is provided, then the value returned by /cache_file will be used. If /cache_file is not defined and you don't provide a filename when you call this method, then it will simply return without doing anything.

Returns the number of records processed into the cache database, if no cache file can be located, then it will return.

Device::OUI->load_cache_from_web( $url, $file );

The /load_cache_from_web method attempts to download an updated version of the indicated file and load it into the cache database. If no url is provided then the value returned by /file_url will be used. If /file_url is not defined, then either you must provide a url when calling this method, or it will return without doing anything.

This method uses the LWP::Simple/mirror method from LWP::Simple to update the cache file, so it will not download a new registry file if it already has the latest version. This makes it easy to have a cron job that updates the registry file using a command like:

perl -MDevice::OUI -e 'Device::OUI->load_cache_from_web'

Returns undef if the update failed, or no update was necessary. Returns the number of records inserted into the cache database if successful. This method also will not update the cache database if a new file wasn't downloaded. If you want to update the cache database regardless of whether a new file was downloaded or not, try this:

use Device::OUI;
if ( defined Device::OUI->mirror_file ) {
    Device::OUI->load_cache_from_file();
}

cache_handle( $new );

Called with an argument, sets a new object for the cache handle. This object will be treated like a hash, so it either needs to be a hash reference, or a tied hash reference, or something along those lines.

If called without an argument, returns the current cache handle, making a new one if necessary. If it's necessary to create a new handle and /cache_db is set, then a new hash will be created and tied to AnyDBM_File.

If it's necessary to create a new handle and /cache_db is not defined (or the attempt to tie to AnyDBM_File fails), then a new anonymous hash will be used to create an in-memory cache that only lasts for the life of the program.

OBJECT METHODS

$oui->oui( $oui )

Called with no arguments, this returns the OUI that the object represents (in the same format it was originally provided to the object). If given an argument of an OUI, sets or changes the OUI represented by this object.

Any reasonable OUI format should be accepted by this method. The most common formats (00:17:F2, 00-17-f2, 0017f2, 0:17:f2, etc) should be fine with any delimiter between the bytes. If no delimiter is provided (as in the case of '08001B', the argument must be exactly 6 characters long.

$oui->normalized()

Returns a normalized form of the OUI, with upper-case hex bytes zero-padded and separated with dashes (as in 00-17-F2). Also available as $oui->norm.

Device::OUI objects have stringification overloaded to return this value.

$oui->norm()

This is an alias for /normalized;

$oui->is_private()

Returns a true value if the OUI is privately registered (in this case no information is available on the organization that owns it, they are simply listed in the registry file as 'PRIVATE').

$oui->organization()

Returns the organization the OUI is registered to. For private registrations, the organization is set to 'PRIVATE'.

$oui->company_id()

Returns the 'company_id' from the registry file. This is really just the OUI in a slightly different format (0019E3 instead of 00-19-E3).

$oui->address()

Returns the organization address from the registry file as a multiline string.

FUNCTIONS / EXPORTS

Although this module is entirely object oriented, there are a handful of utility functions that you can import from this module if you find a need for them. Nothing is exported by default, so if you want to import any of these, you need to say so explicitly:

use Device::OUI qw( ... );

You can get all of them by importing the ':all' tag:

use Device::OUI ':all';

Exporting is handled by Sub::Exporter, so you can rename the imported methods if necessary.

my $oui = normalize_oui( $input );

Given an OUI, normalizes it into an upper-case, zero padded, dash separated format and returns the normalized OUI.

oui_cmp( $oui, $oui );

This is a convenience method, given two Device::OUI objects, or two OUIs (in any acceptable format) or one of each, will return -1, 0, or 1, depending on whether the first OUI is less than, equal to, or greater than the second one.

Device::OUI objects have cmp and <=> overloaded so that simply comparing them will work as expected.

parse_oui_entry( $entry );

Given a text representation of a single entry from the OUI registry file, this method extracts the information from it and returns a data structure that looks like this:

{
    oui          => '00-17-F2',
    company_id   => '0017F2',
    organization => 'Apple Computer',
    address      => [
        '1 Infinite Loop MS:35GPO',
        'Cupertino CA 95014',
        'UNITED STATES',
    ],
}

my @parts = oui_to_integers( $oui );

Given an OUI in any acceptable format, returns an array of three integers representing the values of the three bytes of the OUI.

INTERNAL METHODS

These are methods used internally, that you shouldn't need to mess with.

$oui->lookup();

Attempts to retireve information from the OUI registry. If another lookup method has already retrieved the information, then that saved structure will simply be returned. If not, then an attempt will be made to load the data from the /cache_db, from the /cache_file or from the internet, using the search interface indicated by /search_url. As a last resort, if /file_url is defined, it will attempt to download it and use it for searching.

Returns a hash reference of the data found, or an empty hash reference if all these things failed.

Device::OUI->cache( $oui, $data )

This method is the main interface to the cache database.

If called with one argument, then it returns the cached data for the OUI provided. If called with two arguments it replaces the existing cached data with the new data provided.

$oui->cache( $data )

If /cache is called as an object method, you don't have to include the OUI as an argument. If there are no arguments, then the OUI of the invocant will be used as the OUI. If there is one argument and it is a reference, then it will be assumed to be $data. If there is one argument and it is not a reference, then it will be assumed to be an OUI. If there are two arguments, then it behaves the same as when called as a class method.

$oui->update_from_web()

This method searches the OUI registry (using the URL configured in /search_url) for it's own OUI, and if successful, updates the cache with the information found.

If a /cache_db is in use, this method will update the cache database.

If the search is successful, this method also returns the data that was found.

$oui->update_from_file()

This method searches the OUI registry file, if you have one and it can be located with /cache_file.

If a /cache_db is in use, this method will update the cache database.

If the search is successful, this method also returns the data that was found.

Device::OUI->dump_cache( $sort )

This method is mostly for debugging purposes. When called, it will dump the contents of the cache database in the same format as the entries appear in the OUI registry file.

Takes one optional argument, if called with a true value, then the entries will be dumped in order, sorted by their OUIs. With sorting turned off, this method runs much faster and returns sooner, but if you turn sorting on then the output file should be round-trippable, meaning you can do this:

# curl -O http://standards.ieee.org/regauth/oui/oui.txt
... Downloading ...
# perl -MDevice::OUI -e 'Device::OUI->load_cache_from_file( "oui.txt" );'
# perl -MDevice::OUI -e 'Device::OUI->dump_cache' > new-oui.txt
# diff oui.txt new-oui.txt
( no differences )

$oui->search_url_for( $oui )

Fills in the URL indicated by /search_url with either the OUI provided as an argument, or the invocants OUI, if called as an object method and no argument is provided.

Device::OUI->have_lwp_simple()

This methods returns true if LWP::Simple is available and false if it is not available. The first time this method is called, an attempt will be made to require LWP::Simple, and a warning will be issued if the require is not successful. This method is used internally by the web access features.

Device::OUI->mirror_file( $url, $file )

This method is a wrapper around LWP::Simple/mirror. It returns 1 if the file was mirrored successfully, 0 if the file was not mirrored because the web server reported that the version of the file already in "cache_file" was the latest version, and undef if no file was downloaded.

If $file is not provided, then the value from /cache_file will be used. If $url is not provided, then the value from /file_url will be used.

Device::OUI->get_url( $url )

This method is a wrapper around LWP::Simple/get. It attempts to load the provided $url and returns the contents of the page if successful. It returns undef if unsucessful or if no URL is provided

overload_cmp

This is just a little wrapper that calls /oui_cmp, rearranging the order of the arguments if necessary.

CACHING INFORMATION

LAZY CACHE LOADING

There are a couple of ways you can use the cache features in this module. If you are only going to lookup a handful of OUIs and don't want to download and process the whole registry file at one time, you can simply let the module create a cache database for you, and populate it with entries one at a time as objects are created that are not already in the cache.

PRE-POPULATING THE CACHE

If you are going to be looking up a lot of OUIs (where a lot should probably be defined as "more than 4 or 5") then you would probably be better off pre-populating the cache, using either the /load_cache_from_web method or the /load_cache_from_file method. The first is the easiest, assuming the machine you are running it on has web access, you can simply run:

perl -MDevice::OUI -e 'Device::OUI->load_cache_from_web'

If you don't have web access, you can transfer the file in whatever manner works for you, and then use it to populate the cache with:

perl -MDevice::OUI -e 'Device::OUI->load_cache_file_file( "filename" )'

PREVENTING CACHING

To keep the module from creating a cache database, set /cache_db to undef before creating any Device::OUI objects:

use Device::OUI;
Device::OUI->cache_db( undef );

If you don't have a cache database, but you do have a cache file, then the caching module will simply look each OUI up in the file every time. This is much slower than having a cache database, but may be necessary in some situations.

PREVENTING NETWORK ACCESS

To keep Device::OUI from attempting to access the network, set the URL configuration options to undef before creating any Device::OUI objects:

use Device::OUI;
Device::OUI->search_url( undef );
Device::OUI->file_url( undef );

Even with these two values set to undef, /load_cache_from_web will still work (and still attempt to access the internet) if you give it a URL as an argument when you call it.

Network access will also be disabled if LWP::Simple is not available.

MODULE HOME PAGE

The home page of this module is http://www.jasonkohles.com/software/device-oui. This is where you can always find the latest version, development versions, and bug reports. You will also find a link there to report bugs.

SEE ALSO

http://www.jasonkohles.com/software/device-oui

http://en.wikipedia.org/wiki/Organizationally_Unique_Identifier

http://standards.ieee.org/regauth/oui/index.shtml

AUTHOR

Jason Kohles <email@jasonkohles.com>

COPYRIGHT AND LICENSE

Copyright (C) 2008, 2009 Jason Kohles

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Device::OUI

perl -MCPAN -e shell
install Device::OUI