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

REGISTRY KEYS USED
NOTES
SEE ALSO
AUTHOR
COPYRIGHT AND LICENSE

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";

        my @searchlist = $ipconfig->get_searchlist;
        print "searchlist=@searchlist (", scalar @searchlist, ")\n";

        print "nodetype=", $ipconfig->get_nodetype, "\n";

        print "IP routing enabled=", $ipconfig->is_router ? "Yes" : "No", "\n";

        print "WINS proxy enabled=",
            $ipconfig->is_wins_proxy ? "Yes" : "No", "\n";

        print "LMHOSTS enabled=",
            $ipconfig->is_lmhosts_enabled ? "Yes" : "No", "\n";

        print "DNS enabled for netbt=",
            $ipconfig->is_dns_enabled_for_netbt ? "Yes" : "No", "\n";

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

            print "Description=", $adapter->get_description, "\n";

            print "DHCP enabled=",
                $adapter->is_dhcp_enabled ? "Yes" : "No", "\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 access to the registry on that machine.

Important Note: The functionality of this module has been superseded by WMI (Windows Management Instrumentation).

METHODS

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

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

$access should be set to 'rw' if write access is required. This is only necessary if you intend to use the set_domain, set_dns, or set_wins methods of the Win32::IPConfig::Adapter object. If $access is not set, it will default to 'ro', or read-only access.

$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_searchlist

Returns a list of domain name suffixes added during DNS name resolution. They are only used if the initial DNS name lookup fails. (Returns a reference to a list in a scalar context.)

$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->is_router

Returns 1 if the host is configured to route packets between its network adapters; returns 0 if it is not. Only applicable to machines with more than one adapter. By default, this is set to 0 (no routing).

$ipconfig->is_wins_proxy

Returns 1 if the host is configured to be a WINS proxy for NetBIOS over TCP/IP name resolution; returns 0 if it is not. By default, this is set to 0 (do not act as a WINS proxy). A WINS proxy will answer broadcast name queries it detects on its subnet. It is only required in networks where there are hosts that cannot be configured to use WINS servers.

$ipconfig->is_lmhosts_enabled

Returns 1 if the host is configured to use the LMHOSTS file for NetBIOS over TCP/IP name resolution; returns 0 if it is not. By default, this is set to 1 (use LMHOSTS). The LMHOSTS file does not exist unless created by an administrator at %SystemRoot%\system32\drivers\etc\LMHOSTS.

$ipconfig->is_dns_enabled_for_netbt

Returns 1 if the host is configured to use DNS for NetBIOS over TCP/IP name resolution; returns 0 if it is not. By default, this is set to 0 (do not use DNS). DNS will only be used for NetBIOS over TCP/IP name resolution after all standard methods have failed (cache, WINS, broadcast, LMHOSTS).

This setting has little relevance to Windows 2000 and later, as these operating systems were designed to work without WINS servers and already use DNS (through ``direct hosting'') to resolve Windows computer names.

$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 strict;
    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";
    my @searchlist = $ipconfig->get_searchlist;
    print "Search List. . . . . . . . . . . : $searchlist[0]\n";
    print "                                   $searchlist[$_]\n"
        for (1..@searchlist-1);
    print "Node Type  . . . . . . . . . . . : ", $ipconfig->get_nodetype, "\n";
    print "IP Routing Enabled . . . . . . . : ",
        $ipconfig->is_router ? "Yes" : "No", "\n";
    print "WINS Proxy Enabled . . . . . . . : ",
        $ipconfig->is_wins_proxy ? "Yes" : "No", "\n";
    print "LMHOSTS Enabled. . . . . . . . . : ",
        $ipconfig->is_lmhosts_enabled ? "Yes" : "No", "\n";
    print "DNS Enabled for NetBT. . . . . . : ",
        $ipconfig->is_dns_enabled_for_netbt ? "Yes" : "No", "\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 strict;
    use Win32::IPConfig;

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

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

            if (my $adapter = $ipconfig->get_adapter(0)) {
                print $adapter->is_dhcp_enabled ? "Y," : "N,";
                my @ipaddresses = $adapter->get_ipaddresses;
                print "@ipaddresses,";
                my @subnet_masks = $adapter->get_subnet_masks;
                print "@subnet_masks,";
                my @gateways = $adapter->get_gateways;
                print "@gateways,";
                my @dns = $adapter->get_dns;
                print "@dns,";
                my @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 strict;
    use Win32::IPConfig;

    my $host = shift or die "You must specify a host\n";
    if (my $ipconfig = Win32::IPConfig->new($host, 'rw')) {
        if (my $adapter = $ipconfig->get_adapter("Local Area Connection") ||
                          $ipconfig->get_adapter(0)) {
            if (! $adapter->is_dhcp_enabled) {
                $adapter->set_dns(@ARGV);
                my @dns = $adapter->get_dns;
                if (@dns) {
                    print "Set to @dns\n";
                } else {
                    print "Cleared\n";
                }
            } else {
                warn "Adapter is configured for DHCP\n";
            }
        } else {
            warn "Could not find an adapter to configure\n";
        }
    } else {
        warn "Host '$host' is down or you do not have Administrator access\n";
    }

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 TCP/IP 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 DNS and WINS to resolve Windows computer names, whereas Windows NT will use WINS and only use DNS if configured to do so (see the is_dns_enabled_for_netbt method).

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>

COPYRIGHT AND LICENSE

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

THIS PACKAGE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

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