--- name: "Net::MAC" section: "3pm" platform: "linux" package: "libnet-mac-perl" version: "2.103622-3" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Net::MAC" --- # Net::MAC(3pm) Perl extension for representing and manipulating MAC addresses ## NAME Net::MAC - Perl extension for representing and manipulating MAC addresses ## VERSION version 2.103622 ## SYNOPSIS ``` use Net::MAC; my $mac = Net::MAC->new('mac' => '08:20:00:AB:CD:EF'); # Example: convert to a different MAC address format (dotted-decimal) my $dec_mac = $mac->convert( 'base' => 10, # convert from base 16 to base 10 'bit_group' => 8, # octet grouping 'delimiter' => '.' # dot-delimited ); print "$dec_mac\n"; # Should print 8.32.0.171.205.239 # Example: find out whether a MAC is base 16 or base 10 my $base = $mac->get_base(); if ($base == 16) { print "$mac is in hexadecimal format\n"; } elsif ($base == 10) { print "$mac is in decimal format\n"; } else { die "This MAC is neither base 10 nor base 16"; } ``` ## DESCRIPTION This is a module that allows you to ``` - store a MAC address in a Perl object - find out information about a stored MAC address - convert a MAC address into a specified format - easily compare two MAC addresses for string or numeric equality ``` There are quite a few different ways that MAC addresses may be represented in textual form. The most common is arguably colon-delimited octets in hexadecimal form. When working with Cisco devices, however, you are more likely to encounter addresses that are dot-delimited 16-bit groups in hexadecimal form. In the Windows world, addresses are usually dash-delimited octets in hexadecimal form. MAC addresses in a Sun ethers file are usually non-zero-padded, colon-delimited hexadecimal octets. And sometimes, you come across dot-delimited octets in decimal form (certain Cisco SNMP MIBS actually use this). Hence the need for a common way to represent and manipulate MAC addresses in Perl. There is a surprising amount of complexity involved in converting MAC addresses between types. This module does not attempt to understand all possible ways of representing a MAC address in a string, though most of the common ways of representing MAC addresses are supported. ## METHODS ### new() method (constructor) The **new()** method creates a new Net::MAC object. Possible arguments are ``` mac a string representing a MAC address base a number corresponding to the numeric base of the MAC possible values: 10 16 delimiter the delimiter in the MAC address string from above possible values: : - . space bit_group the number of bits between each delimiter possible values: 8 16 48 zero_padded whether bit groups have leading zero characters (Net::MAC only allows zero-padding for bit groups of 8 bits) possible values: 0 1 format the name of a MAC address format specification which takes the place of the base,delimiter,bit_group and zero_padded options above verbose write informational messages (useful for debugging) possible values: 0 1 die die() on invalid MAC address (default is to die on invalid MAC) possible values: 0 1 (default is 1) ``` When the **new()** method is called with a 'mac' argument and nothing else, the object will attempt to auto-discover metadata like bit grouping, number base, delimiter, etc. If the MAC is in an invalid or unknown format, the object will call the **croak()** function. If you don't want the object to **croak()**, you can give the **new()** method a die argument, such as: ``` my $m_obj = Net::MAC->new('mac' => '000adf012345', 'die' => 0); ``` There are cases where the auto-discovery will not be able to guess the numeric base of a MAC. If this happens, try giving the **new()** method a hint, like so: ``` # Example: this MAC is actually in decimal-dotted notation, not hex my $mac = Net::MAC->new('mac' => '10.0.0.12.14.8', 'base' => 10); ``` This is necessary for cases like the one above, where the class has no way of knowing that an address is decimal instead of hexadecimal. If you have installed a custom MAC address format into the class (see below) then you can also pass the `"format"` option as a hint: ``` my $mac = Net::MAC->new('mac' => 'ab01~ab01~ab01', 'format' => 'My_Format'); ``` ### class methods ***set\_format\_for()*** When discovering MAC address formats, and converting between different formats (using `"convert"` or `"as_*"`) the module can use predefined common formats or you can install your own for local circumstances. For example consider a fictional device which uses MAC addresses formatted like `"ab01~ab01~ab01"`, which would otherwise not be understood. You can install a new Format for this address style: ``` Net::MAC->set_format_for( 'My_Format_Name' => { base => 16, bit_group => 16, delimiter => '~', }); ``` Now when using either the `"format"` option to `"new()"`, or the `"convert()"` or `"as_*"` methods, the module will recognise this new format `"My_Format_Name"`. The Hashref supplied can include any of the standard options for formats as listed elsewhere in this documentation. ``` my $mac = Net::MAC->new('mac' => 'ab01~ab01~ab01', 'format' => 'My_Format_Name'); ``` Custom formats sharing the same name as one shipping with the module (such as `"Cisco"`) will override that built-in format. ### accessor methods ***get\_mac()*** *method* Returns the MAC address stored in the object. ***get\_base()*** *method* Returns the numeric base of the MAC address. There are two possible return values: ``` 16 hexadecimal (common) 10 decimal (uncommon) ``` ***get\_delimiter()*** *method* Returns the delimiter, if any, in the specified MAC address. A valid delimiter matches the following regular expression: ``` /\:|\-|\.|\s/ ``` In other words, either a colon, a dash, a dot, or a space. If there is no delimiter, this method will return the undefined value (undef). If an invalid delimiter is found (like an asterisk or something), the object will call the **croak()** function. ***get\_bit\_group()*** *method* Returns the number of bits between the delimiters. A MAC address is a 48 bit address, usually delimited into 8 bit groupings (called octets), i.e. ``` 08:20:00:AB:CD:EF ``` Sometimes, MAC addresses are specified with fewer than 5 delimiters, or even no delimiters at all: ``` 0820.00ab.cdef # get_bit_group() returns 16 082000abcdef # get_bit_group() returns 48, no delimiters at all ``` ***get\_zero\_padded()*** *method* Returns a boolean value indicating whether or not the bit groups are zero-padded. A return value of 0 (false) means that the bit groups are not zero-padded, and a return value of 1 (true) means that they are zero-padded: ``` 00.80.02.ac.4f.ff # get_zero_padded() returns 1 0:80:2:ac:4f:ff # get zero_padded() returns 0 0.125.85.122.155.64 # get_zero_padded() returns 0 ``` Net::MAC only allows bit groups of 8 bits to be zero-padded. ### convert() method Convert an already-defined Net::MAC object into a different MAC address format. With this function you can change the delimiter, the bit grouping, or the numeric base. ``` # Example: convert to a different MAC address format (dotted-decimal) my $new_mac_obj = $existing_mac_obj->convert( 'base' => 16, # convert to base 16, if necessary 'bit_group' => 16, # 16 bit grouping 'delimiter' => '.' # dot-delimited ); ``` Note that if any of the above arguments are not provided, they will be set to the following default values: ``` base 16 bit_group 8 (i.e. a delimiter will be used) delimiter : ``` ### Conversion to common formats The most common formats have shortcut conversion methods that can be used instead of the **convert()** method with its many options. ***as\_Cisco()*** *method* Cisco routers seem to usually represent MAC addresses in hexadecimal, dot-delimited, 16 bit groups. ``` my $mac = Net::MAC->new(mac => '00-02-03-AA-AB-FF'); my $cisco_mac = $mac->as_Cisco(); print "$cisco_mac"; # should print 0002.03aa.abff ``` ***as\_IEEE()*** *method* The IEEE 802 2001 specification represents MAC addresses in hexadecimal, colon-delimited, upper case, 8 bit groups. ``` my $mac = Net::MAC->new(mac => '00-02-03-AA-AB-FF'); my $IEEE_mac = Net::MAC->as_IEEE(); print "$IEEE_mac"; # should print 00:02:03:AA:AB:FF ``` ***as\_Microsoft()*** *method* Microsoft usually represents MAC addresses in hexadecimal, dash delimited, upper case, 8 bit groups. ``` my $mac = Net::MAC->new(mac => '00:02:03:AA:AB:FF'); my $microsoft_mac = $mac->as_Microsoft(); print "$microsoft_mac"; # should print 00-02-03-AA-AB-FF ``` ***as\_Sun()*** *method* Sun represents MAC addresses in hexadecimal, colon-delimited, non-zero-padded, lower case, 8 bit groups. ``` my $mac = Net::MAC->new(mac => '00-02-03-AA-AB-FF'); my $sun_mac = $mac->as_Sun(); print "$sun_mac"; # should print 0:2:3:aa:ab:ff ``` ### Stringification The stringification operator "" has been overloaded to allow for the meaningful use of the instance variable in a string. ``` my $mac = Net::MAC->new(mac => '00:0a:23:4f:ff:ef'); print "object created for MAC address $mac"; # Should print: # object created for MAC address 00:0a:23:4f:ff:ef ``` ### MAC address comparison The Perl operators 'eq' and 'ne' (string comparison) and '==' '!=' (numeric comparison) have been overloaded to allow simple, meaningful comparisons of two MAC addresses. Example (two MAC addresses numerically identical but in different formats): ``` my $d = Net::MAC->new(mac => '0.8.1.9.16.16', base => 10); my $h = Net::MAC->new(mac => '00:08:01:0A:10:10', base => 16); if ($d == $h) { print "$d and $h are numerically equal"; } if ($d ne $h) { print " but $d and $h are not the same string"; } ``` ## BUGS ### Malformed MAC addresses Net::MAC can't handle MAC addresses where whole leading zero octets are omitted. Example: ``` 7.122.32.41.5 (should be 0.7.122.32.41.5) ``` Arguably, that's their problem and not mine, but maybe someday I'll get around to supporting that case as well. ### Case is not preserved Net::MAC doesn't reliably preserve case in a MAC address. I might add a flag to the **new()** and **convert()** methods to do this. I might not. Case is however altered when using the **as\_foo()** formatted output methods. ## SEE ALSO Net::MacMap Net::MAC::Vendor ## MAINTAINER Oliver Gorwits \ ## CONTRIBUTORS Oliver Gorwits, Robin Crook, Kevin Brintnall ## AUTHOR Karl Ward \ ## COPYRIGHT AND LICENSE This software is Copyright (c) 2010 by Karl Ward \. This is free software, licensed under: ``` The GNU General Public License, Version 2, June 1991 ```