--- name: "Net::Ifconfig::Wrapper" section: "3pm" platform: "linux" package: "libnet-ifconfig-wrapper-perl" version: "0.26-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Net::Ifconfig::Wrapper" --- # Net::Ifconfig::Wrapper(3pm) provides a unified way to configure network interfaces on FreeBSD, OpenBSD, Solaris, Linux, OS X, and WinNT (from Win2K). ## NAME Net::Ifconfig::Wrapper - provides a unified way to configure network interfaces on FreeBSD, OpenBSD, Solaris, Linux, OS X, and WinNT (from Win2K). ## SYNOPSIS ``` use Net::Ifconfig::Wrapper; my $rhInfo = Net::Ifconfig::Wrapper::Ifconfig('list'); ``` ## DESCRIPTION This module provides a unified way to configure the network interfaces on FreeBSD, OpenBSD, Solaris, Linux, OS X, and WinNT (from Win2K) systems. ***Only*** **"inet"** ***(IPv4) and*** **"ether"** ***(MAC) addresses are supported at this time*** On Unix, this module calls the system `"ifconfig"` command to gather the information. On Windows, the functions from IpHlpAPI.DLL are called. For all supported Unixes, `"Net::Ifconfig::Wrapper"` expects the `"ifconfig"` command to be `"/sbin/ifconfig"`. See the top-level README file for a list of tested OSes. *On the MSWin32 family, only Windows NT is supported.* *In the Windows NT family, only Windows 2000 or later is supported.* ## The Net::Ifconfig::Wrapper methods - "Ifconfig(*Command*, *Interface*, *Address*, *Netmask*);" The one and only method of the `"Net::Ifconfig::Wrapper"` module. Does all the jobs. The particular action is described by the `$Command` parameter. `$Command` could be: - 'list' `"Ifconfig('list', '', '', '')"` will return a reference to a hash containing information about interfaces. The structure of this hash is the following: ``` {IfaceName => {'status' => 0|1 # The status of the interface. 0 means down, 1 means up 'ether' => MACaddr, # The ethernet address of the interface if available 'descr' => Description, # The description of the interface if available 'inet' => {IPaddr1 => NetMask, # The IP address and his netmask, both are in AAA.BBB.CCC.DDD notation IPaddr2 => NetMask, ... }, ... }; ``` *Interface*, *Address*, *Netmask* parameters are ignored. The following shows what program is called for each OS: - FreeBSD `"/sbin/ifconfig -a"` - Solaris `"/sbin/ifconfig -a"` - OpenBSD `"/sbin/ifconfig -A"` - Linux `"/sbin/ifconfig -a"` - OS X `"/sbin/ifconfig -a"` - MSWin32 `"GetAdaptersInfo"` function from `"IpHlpAPI.DLL"` Known Limitations: OpenBSD: `"/sbin/ifconfig -A"` command is not returning information about MAC addresses so we are trying to get it from `'/usr/sbin/arp -a'` command (first *'static'* entry). If no one present the *'ff:ff:ff:ff:ff'* address is returned. MSWin32: `"GetAdaptersInfo"` function is not returning information about the interface which has address `127.0.0.1` bound to it, so we have no way to return it. Not a limitation, but a small problem: in MSWin32, interface names are not human-readable, they look like `"{843C2077-30EC-4C56-A401-658BB1E42BC7}"` (on Win2K at least). - 'inet' This function is used to set IPv4 address on interface. It is called as ``` Ifconfig('inet', $IfaceName, $Addr, $Mask); ``` *$IfaceName* is an interface name as displayed by `'list'` command *$Addr* is an IPv4 address in the `"AAA.AAA.AAA.AAA"` notation *$Mask* is an IPv4 subnet mask in the `"MMM.MMM.MMM.MMM"` notation In order to accomplish this, the following actual `"ifconfig"` programs are called: - FreeBSD `"/sbin/ifconfig %Iface% inet %Addr% netmask %Mask% up"` - Solaris `"/sbin/ifconfig %Iface% inet %Addr% netmask %Mask% up"` - OpenBSD `"/sbin/ifconfig %Iface% inet %Addr% netmask %Mask% up"` - Linux `"/sbin/ifconfig %Iface% inet %Addr% netmask %Mask% up"` - OS X `"/sbin/ifconfig %Iface% inet %Addr% netmask %Mask% up"` - MSWin32: nothing :( Known Limitations: MSWin32: I did not find a reliable way to recognize the "main" address on the Win32 network interface, so I have disabled this functionality. If you know how, please let me know. - 'up' Just a synonym for `'inet'` - 'down' This function is used to bring specified interface down. It is called as ``` Ifconfig('inet', $IfaceName, '', ''); ``` *$IfaceName* is an interface name as displayed by `'list'` command Last two arguments are ignored. In order to accomplish this, the following programs are called: - FreeBSD `"/sbin/ifconfig %Iface% down"` - Solaris `"/sbin/ifconfig %Iface% down"` - OpenBSD `"/sbin/ifconfig %Iface% down"` - Linux `"/sbin/ifconfig %Iface% down"` - OS X `"/sbin/ifconfig %Iface% down"` - MSWin32 Sorry, this function is not possible. Known Limitations: MSWin32: I did not find the way to implement the `'up'` command so I did not implement `'down'`. - '+alias' This function is used to set IPv4 alias address on interface. It have to be called as ``` Ifconfig('+alias', $IfaceName, $Addr, $Mask); ``` *$IfaceName* is an interface name as displayed by `'list'` command *$Addr* is an IPv4 address in the `"AAA.AAA.AAA.AAA"` notation *$Mask* is an IPv4 subnet mask in the `"MMM.MMM.MMM.MMM"` notation In order to accomplish this, the following `"ifconfig"` programs are called: - FreeBSD `"/sbin/ifconfig %Iface% inet %Addr% netmask %Mask% alias"` - Solaris `"/sbin/ifconfig %Iface%:%Logic% inet %Addr% netmask %Mask% up"` - OpenBSD `"/sbin/ifconfig %Iface% inet %Addr% netmask %Mask% alias"` - Linux `"/sbin/ifconfig %Iface%:%Logic% inet %Addr% netmask %Mask% up"` - OS X `"/sbin/ifconfig %Iface% inet %Addr% netmask %Mask% alias"` - MSWin32 `"AddIPAddress"` function from `"IpHlpAPI.DLL"` *First available logic interface is taken automatically for Solaris and Linux* - 'alias' Just a synonim for `'+alias'` - '-alias' This function is used to remove IPv4 alias address from interface. It have to be called as ``` Ifconfig('-alias', $IfaceName, $Addr, ''); ``` *$IfaceName* is an interface name as displayed by `'list'` command. *$Addr* is an IPv4 address in the `"AAA.AAA.AAA.AAA"` notation. Last argument is ignored if present. In order to accomplish this, the following `"ifconfig"` programs are called: - FreeBSD `"/sbin/ifconfig %Iface% inet %Addr% -alias"` - Solaris `"/sbin/ifconfig %Iface%:%Logic% down"` - OpenBSD `"/sbin/ifconfig %Iface% inet %Addr% -alias"` - Linux `"/sbin/ifconfig %Iface%:%Logic% down"` - OS X `"/sbin/ifconfig %Iface% inet %Addr% -alias"` - MSWin32 `"DeleteIPAddress"` function from `"IpHlpAPI.DLL"` *Appropriate logic interface is obtained automatically for Solaris and Linux* On success, the `"Ifconfig(...)"` function returns the defined value. Actually, it is a reference to the array containing the output of the actual *"ifconfig"* program called. In case of error, `"Ifconfig(...)"` returns `'undef'` value, and the `$@` variable contains the error message. ### EXPORT None by default. ## AUTHOR Daniel Podolsky, \ As of 2015-11, maintained by Martin Thurn \ ## SEE ALSO [ifconfig(8)](/ifconfig/8.md), *Internet Protocol Helper* in *Platform SDK*.