NAME

Win32::IPConfig - IP Configuration Settings for Windows NT/2000/XP/2003

SYNOPSIS

use Win32::IPConfig;

$host = shift || "";
if ($ipconfig = Win32::IPConfig->new($host)) {
    print "hostname=", $ipconfig->get_hostname, "\n";
    print "domain=", $ipconfig->get_domain, "\n";
    print "nodetype=", $ipconfig->get_nodetype, "\n";

    foreach $adapter ($ipconfig->get_adapters) {
        print "\nAdapter '";
        print $adapter->get_name, "':\n";
        print $adapter->get_description, "\n";

        if ($adapter->is_dhcp_enabled) {
            print "DHCP is enabled\n";
        } else {
            print "DHCP is not enabled\n";
        }

        @ipaddresses = $adapter->get_ipaddresses;
        print "ip addresses=@ipaddresses (", scalar @ipaddresses, ")\n";

        @subnet_masks = $adapter->get_subnet_masks;
        print "subnet masks=@subnet_masks (", scalar @subnet_masks, ")\n";

        @gateways = $adapter->get_gateways;
        print "gateways=@gateways (", scalar @gateways, ")\n";

        print "domain=", $adapter->get_domain, "\n";

        @dns = $adapter->get_dns;
        print "dns=@dns (", scalar @dns, ")\n";

        @wins = $adapter->get_wins;
        print "wins=@wins (", scalar @wins, ")\n";
    }
}

DESCRIPTION

Win32::IPConfig is a module for retrieving TCP/IP network settings from a Windows NT/2000/XP/2003 host machine. Specify the host and the module will retrieve and collate all the information from the specified machine's registry (using Win32::TieRegistry). For this module to retrieve information from a host machine, you must have read and write access to the registry on that machine.

METHODS

$ipconfig = Win32::IPConfig->new($host);

Creates a new Win32::IPConfig object. $host is passed directly to Win32::TieRegistry, and can be a computer name or an IP address.

$ipconfig->get_hostname

Returns a string containing the DNS hostname of the machine.

$ipconfig->get_domain

Returns a string containing the domain name suffix of the machine. For machines running Windows 2000 or later (which can have connection-specific domain name suffixes for each adapter) this is the primary domain name for the machine.

$ipconfig->get_nodetype

Returns the NetBIOS over TCP/IP node type of the machine. The four possible node types are:

B-node - resolve NetBIOS names by broadcast
P-node - resolve NetBIOS names using a WINS server
M-node - resolve NetBIOS names by broadcast, then using a WINS server
H-node - resolve NetBIOS names using a WINS server, then by broadcast

Windows defaults to B-node if no WINS servers are configured, and defaults to H-node if there are.

$ipconfig->get_adapters

The real business of the module. Returns a list of Win32::IPConfig::Adapter objects. (Returns a reference to a list in a scalar context.)

Each adapter object contains the TCP/IP network settings for an individual adapter. See the Win32::IPConfig::Adapter documentation for more information.

$ipconfig->get_configured_adapters

Returns a list of Win32::IPConfig::Adapter objects that have IP addresses configured, whether manually or through DHCP. (Returns a reference to a list in a scalar context.)

$ipconfig->get_adapter($name_or_num)

Returns the Win32::IPConfig::Adapter specified by $name_or_num. If you specify a string (e.g. "Local Area Connection") it will look for an adapter with that name, otherwise it will take the adapter from the list of Win32::IPConfig::Adapter objects with the index value of $name_or_num. Use get_adapter(0) to retrieve the first adapter.

You could use the following code to retrieve the adapter named "Local Area Connection" on Windows 2000 (or later) or the first adapter on Windows NT.

my $adapter = $ipconfig->get_adapter("Local Area Connection") ||
              $ipconfig->get_adapter(0);

EXAMPLES

Displaying the IP Settings for a PC

This example is a variation on the code given in the synopsis; it prints the output in a style closer to the ipconfig command. Specify the target computer's name as the first command line parameter.

It also uses the get_configured_adapters method to filter out adapters that do not have IP addresses.

use Win32::IPConfig;

my $host = shift || Win32::NodeName;

my $ipconfig = Win32::IPConfig->new($host)
    or die "Unable to connect to $host\n";

print "Host Name. . . . . . . . . . . . : ", $ipconfig->get_hostname, "\n";
print "Domain Name (Primary). . . . . . : ", $ipconfig->get_domain, "\n";
print "Node Type  . . . . . . . . . . . : ", $ipconfig->get_nodetype, "\n";

for my $adapter ($ipconfig->get_configured_adapters) {
    print "\nAdapter '", $adapter->get_name, "':\n\n";
    print "DHCP Enabled . . . . . . . . . . : ",
        $adapter->is_dhcp_enabled ? "Yes" : "No", "\n";
    print "Domain Name. . . . . . . . . . . : ", $adapter->get_domain, "\n";

    my @ipaddresses = $adapter->get_ipaddresses;
    my @subnet_masks = $adapter->get_subnet_masks;
    for (0..@ipaddresses-1) {
        print "IP Address . . . . . . . . . . . : $ipaddresses[$_]\n";
        print "Subnet Mask. . . . . . . . . . . : $subnet_masks[$_]\n";
    }

    my @gateways = $adapter->get_gateways;
    print "Default Gateway. . . . . . . . . : $gateways[0]\n";
    print "                                   $gateways[$_]\n"
        for (1..@gateways-1);

    my @dns = $adapter->get_dns;
    print "DNS Servers. . . . . . . . . . . : $dns[0]\n";
    print "                                   $dns[$_]\n" for (1..@dns-1);

    my @wins = $adapter->get_wins;
    print "WINS Servers . . . . . . . . . . : $wins[0]\n";
    print "                                   $wins[$_]\n" for (1..@wins-1);
}

Collecting IP Settings for a list of PCs

This example outputs data in CSV format with the hostname and domain followed by the IP configuration settings for the first adapter. (Additional adapters are ignored.)

use Win32::IPConfig;

print "hostname,domain,";
print "dhcp?,ip addresses,subnet masks,gateways,dns servers,wins servers\n";

while (<DATA>) {
    chomp;
    $ipconfig = Win32::IPConfig->new($_);
    print $ipconfig->get_hostname, ",";
    print $ipconfig->get_domain, ",";

    if (@adapters = $ipconfig->get_adapters) {
        $adapter = $adapters[0];
        print $adapter->is_dhcp_enabled ? "Y," : "N,";
        @ipaddresses = $adapter->get_ipaddresses;
        print "@ipaddresses,";
        @subnet_masks = $adapter->get_subnet_masks;
        print "@subnet_masks,";
        @gateways = $adapter->get_gateways;
        print "@gateways,";
        @dns = $adapter->get_dns;
        print "@dns,";
        @wins = $adapter->get_wins;
        print "@wins";
    }
    print "\n";
}

__DATA__
HOST1
HOST2
HOST3

Setting a PC's DNS servers

This example demonstrates how you can change the DNS servers set on a remote host. It reads the target machine name and the IP addresses for the DNS servers from the command line.

use Win32::IPConfig;

my $host = shift;
my $ipconfig = Win32::IPConfig->new($host);
my @dns = @ARGV;
my $adapter = $ipconfig->get_adapter(0);
$adapter->set_dns(@dns);

REGISTRY KEYS USED

IP configuration information is stored in a number of registry keys under HKLM\SYSTEM\CurrentControlSet\Services.

To find adapter-specific configuration information, you need the adapter id, which can be found by examining the list of installed network cards at HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\NetworkCards.

Note that on Windows NT the adapter id will look like a service or driver, while on Windows 2000 and later it will be a GUID.

There are some variations in where the TCP/IP configuration data is stored. For all operating systems, the main keys are:

Tcpip\Parameters
Netbt\Parameters

Adapter-specific settings are stored in:

<adapter_id>\Parameters\Tcpip (Windows NT)
Tcpip\Parameters\Interfaces\<adapter_id> (Windows 2000 and later)

NetBIOS over TCP/IP stores adapter-specific settings in:

Netbt\Adapters\<adapter_id> (Windows NT)
Netbt\Parameters\Interfaces\Tcpip_<adapter_id> (Windows 2000 and later)

NOTES

Windows 2000 and later will use its DNS server setting to resolve Windows computer names, whereas Windows NT will use its WINS server settings first.

For Windows 2000 and later, both the primary and connection-specific domain settings are significant and will be used in this initial name resolution process.

The DHCP Server options correspond to the following registry values:

003 Router              ->  DhcpDefaultGateway
006 DNS Servers         ->  DhcpNameServer
015 DNS Domain Name     ->  DhcpDomain
044 WINS/NBNS Servers   ->  DhcpNameServer/DhcpNameServerList
046 WINS/NBT Node Type  ->  DhcpNodeType

AUTHOR

James Macfarlane, <jmacfarla@cpan.org>

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)