Network configuration

Commands related to network configuration

SYNOPSIS

package require twapi

address_to_hostname IPADDRESS ?-async SCRIPT? ?-flushcache? flush_arp_table INTERFACEINDEX get_arp_table ?options? get_ip_addresses get_netif_count get_netif_indices get_netif_info NETWORKINTERFACE ?options? get_network_info ?options? get_tcp_connections ?options? get_udp_connections ?options? hostname_to_address HOSTNAME ?-async SCRIPT? ?-flushcache? hwaddr_to_ipaddr HWADDR ?VARNAME? ipaddr_to_hwaddr IPADDR ?VARNAME? port_to_service PORTNUMBER service_to_port SERVICENAME terminate_tcp_connections ?options?

DESCRIPTION

This module provides procedures to retrieve network information

Overview

This module provides commands to retrieve various network-related data for the local system including DNS and DHCP information, type and configuration of network interfaces, traffic statistics and various other information. The module also provides some client side name resolution lookup functions including nonblocking name and address lookups. Many of these commands and some options are not available on all platforms as noted in each command description.

Commands

address_to_hostname IPADDRESS ?-async SCRIPT? ?-flushcache?

Attempts to map the specified Internet address IPADDRESS to its fully qualified DNS name (FQDN).

If the -async option is not specified, the command returns the FQDN if available and the empty string otherwise. Note that this is a blocking call and the Tcl event loop will not be run until the command returns.

If the -async option is specified, the command returns right away. The address resolution is done in the background and when completed, SCRIPT is called at the global scope. Three additional arguments are appended to the script before it is executed - IPADDRESS, status success or fail and either the FQDN (when the status is success) or the Winsock error code (when the status is fail). The Winsock error code may be translated to an error string using the map_windows_error command. If no names are found, the status is success but the third argument will be an empty string.

Internally, the command maintains a cache of address to hostname mappings so as to avoid unnecessary lookups. The result is normally returned from here if available. However, if the -flushcache option is specified, the cache entry is deleted and an explicit lookup up is done.

flush_arp_table INTERFACEINDEX

Flushes the ARP table associated with the specified network interface.

get_arp_table ?options?

Returns the entries in the system's ARP table. Each entry is a sublist consisting of four elements - the interface index, the hardware address, the IP address and the type. The type is one of dynamic, static, other or invalid.

The following options control the returned data:

-ifindex INTERFACEINDEX	Limits the returned entries to those in the ARP table for the specified network interface with index INTERFACEINDEX.
-sort	Returns the entries sorted by IP address.
-validonly	Skips entries that are marked invalid.

get_ip_addresses

Returns a list of IP addresses for the system.

get_netif_count

Returns the number of network interfaces in the system.

get_netif_indices

Network interfaces in the system are identified by integer indices. This command retrieves the list of network interfaces in the system.

Example: Show network interface information

get_netif_info NETWORKINTERFACE ?options?

Returns various information about the configuration of a network interface. On Windows NT 4.0 NETWORKINTERFACE must be the index of a network interface. On Windows 2000 and later, it may also be a name identifying the interface.

On Windows NT 4.0 SP3 and earlier, this command is not implemented On later versions of Windows NT 4.0, a subset of the options are not implemented. In both cases, a Tcl error will be raised unless the -unknownvalue option is specified. On Windows 2000 and later, all options are supported.

The information returned depends on the options specified and is in the form of a flat list of the form "option1 value1 ...". The following options may be specified:

-adapterdescription	Returns a description of the adapter associated with the interface. This option is supported on Windows 2000 and higher.
-adapterindex	Returns the index of the adapter associated with the interface. This option is supported on Windows 2000 and higher.
-adaptername	Returns the name of the adapter associated with the interface. This option is supported on Windows 2000 and higher.
-adminstatus	Returns 1 or 0 depending on whether the interface has been administratively enabled or not. This option is supported on Windows NT 4.0 SP4 and higher.
-all	Returns all option values.
-autoconfigactive	Returns 1 if the interface has been autoconfigured with an address, and 0 otherwise. This option is supported on Windows 2000 and higher.
-autoconfigenabled	Returns 1 if autoconfiguration is enabled on the interface if a DHCP server cannot be found, and 0 otherwise. This option is supported on Windows 2000 and higher.
-defaultgateway	Returns the address of the default gateway on the interface. This option is supported on Windows 2000 and higher.
-description	Returns a description of the interface. This option is supported on Windows NT 4.0 SP4 and higher.
-dhcpenabled	Returns 1 if DHCP is enabled on the interface, else 0. This option is supported on Windows 2000 and higher.
-dhcpleaseend	Returns the time, in seconds since Jan 1, 1970, that the DHCP lease will expire. This option is supported on Windows 2000 and higher.
-dhcpleasestart	Returns the time, in seconds since Jan 1, 1970, that the DHCP lease was obtained. This option is supported on Windows 2000 and higher.
-dhcpserver	Returns the address of the DHCP server on the network interface. This option is supported on Windows 2000 and higher.
-dnsservers	Returns a list of DNS servers on that interface. This option is supported on Windows 2000 and higher.
-havewins	Returns 1 if the interface uses WINS, else 0. This option is supported on Windows 2000 and higher.
-ifindex	Returns the interface index. This is the same as INTERFACEINDEX unless the latter is specified as a name on Windows 2000 and later. This option is supported on Windows NT 4.0 SP4 and higher.
-ifname	Returns the name of the network interface. This option is supported on Windows 2000 and higher.
-inbytes	Returns the number of bytes received through this interface. This option is supported on Windows NT 4.0 SP4 and higher.
-indiscards	Returns the number of incoming packets on this interface that were discarded even though they had no errors. This option is supported on Windows NT 4.0 SP4 and higher.
-inerrors	Returns the number of incoming packets on this interface that were discarded because of errors. This option is supported on Windows NT 4.0 SP4 and higher.
-innonunicastpkts	Returns the number of broadcast or multicast packets received through this interface. This option is supported on Windows NT 4.0 SP4 and higher.
-inunicastpkts	Returns the number of unicast packets received through this interface. This option is supported on Windows NT 4.0 SP4 and higher.
-inunknownprotocols	Returns the number of incoming packets on this interface that were discarded because of the protocol was unknown. This option is supported on Windows NT 4.0 SP4 and higher.
-laststatuschange	Returns the last time the operational status changed. This option is supported on Windows NT 4.0 SP4 and higher.
-ipaddresses	Returns a list sublists containing the IP addresses and masks for the interface. This option is supported on Windows NT 4.0 SP4 and higher.
-mtu	Returns the maximum transmission unit of the interface. This option is supported on Windows NT 4.0 SP4 and higher.
-operstatus	Returns the operational status of the interface. This is one of the values nonoperational, wanunreachable, disconnected, wanconnecting, wanconnected, operational. This option is supported on Windows NT 4.0 SP4 and higher.
-outbytes	Returns the number of bytes transmitted through this interface. This option is supported on Windows NT 4.0 SP4 and higher.
-outdiscards	Returns the number of outgoing packets on this interface that were discarded even though they had no errors. This option is supported on Windows NT 4.0 SP4 and higher.
-outerrors	Returns the number of outgoing packets on this interface that were discarded because of errors. This option is supported on Windows NT 4.0 SP4 and higher.
-outnonunicastpkts	Returns the number of broadcast or multicast packets transmitted through this interface. This option is supported on Windows NT 4.0 SP4 and higher.
-outqlen	Returns the output queue length on this interface. This option is supported on Windows NT 4.0 SP4 and higher.
-outunicastpkts	Returns the number of unicast packets transmitted through this interface. This option is supported on Windows NT 4.0 SP4 and higher.
-physicaladdress	Returns the physical address of the network interface. This option is supported on Windows NT 4.0 SP4 and higher.
-primarywins	Returns the address of the primary WINS server, if any. This option is supported on Windows 2000 and higher.
-reassemblysize	Returns the maximum size of a reassembled packet that is supported by the interface. This option is supported on Windows NT 4.0 SP4 and higher.
-secondarywins	Returns the address of the secondary WINS server, if any. This option is supported on Windows 2000 and higher.
-speed	Returns the speed of the network interface in bits per second. This option is supported on Windows NT 4.0 SP4 and higher.
-type	Returns the network interface type. This is one of ethernet, tokenring, fddi, ppp, loopback, slip or other. This option is supported on Windows NT 4.0 SP4 and higher.

Example: Show network interface information

Example: Show network statistics

get_network_info ?options?

Returns various information about network configuration. The information returned depends on the options specified and is in the form of a flat list of the form "option1 value1 ...". The following options may be specified:

-all	Returns all values.
-arpproxyenabled	Returns 1 if ARP proxying is enabled and 0 otherwise.
-dhcpscopeid	Returns the DHCP scope id.
-dnsenabled	Returns 1 if DNS name resolution is enabled on the system and 0 otherwise.
-dnsservers	Returns a list of DNS server addresses used for name resolution.
-domain	Returns the system domain.
-hostname	Returns the host name of the system.
-routingenabled	Returns 1 if routing is enabled on the system and 0 otherwise.

On Windows NT 4.0, this command is not available and will raise a Tcl error.

get_tcp_connections ?options?

Retrieves information about currently active TCP connections similar to the Windows netstat command. The return value is a list of sublists, each corresponding to a single connection.

The information returned for each connection is a flat list of the form "option1 value1 ...". The information returned for each connection is controlled through the following options:

-all	Returns all fields for a connection. This option is assumed if no other field option is specified.
-localaddr	Returns the local address being used for the connection.
-localport	Returns the local port number being used for the connection.
-pid	Returns the PID of the process communicating on the port. On some platforms, this may not be available in which case, an empty string is returned for the value.
-remoteaddr	Returns the address of the remote end of the connection.
-remoteport	Returns the port number of the remote end of the connection.
-state	Returns the connection state. This is one of closed, listen, syn_sent, syn_rcvd, estab, fin_wait1, fin_wait2, close_wait, closing, last_ack, time_wait or delete_tcb.

In addition, the connections for which information is returned may be filtered through the following options. Only those connections that match the specified criteria are returned.

-matchlocaladdr IPADDR	Only returns those connections whose local address is bound to IPADDR.
-matchlocalport PORTNUMBER	Only returns those connections whose local port is the specified number.
-matchpid PID	Only returns those connections owned by the process with the specified PID. On platforms where the PID is not available, specifying this option will generate an error.
-matchremoteaddr IPADDR	Only returns those connections whose remote address is bound to IPADDR.
-matchremoteport PORTNUMBER	Only returns those connections whose remote port is PORTNUMBER.
matchstate STATELIST	Only returns those connections whose state is one those specified in STATELIST which should be a list of connection state values (see above).

get_udp_connections ?options?

Retrieves information about currently active UDP sockets similar to the Windows netstat command. The return value is a list of sublists, each corresponding to a single open socket.

The information returned for each connection is a flat list of the form "option1 value1 ...". The fields returned for each connection is controlled through the following options:

-all	Returns all fields for a connection. This option is assumed if no other field option is specified.
-localaddr	Returns the local address being used for the connection.
-localport	Returns the local port number being used for the connection.
-pid	Returns the PID of the process communicating on the port. On some platforms, this may not be available in which case, an empty string is returned for the value.

In addition, the connections for which information is returned may be filtered through the following options. Only those connections that match the specified criteria are returned.

-matchlocaladdr IPADDR	Only returns those connections whose local address is bound to IPADDR.
-matchlocalport PORTNUMBER	Only returns those connections whose local port is the specified number.
-matchpid PID	Only returns those connections owned by the process with the specified PID. On platforms where the PID is not available, specifying this option will generate an error.

hostname_to_address HOSTNAME ?-async SCRIPT? ?-flushcache?

Attempts to map the specified host name to its IP addresses. Note there may be more than one address associated with a host name.

If the -async option is not specified, the command returns the list of IP addresses corresponding to the host if available and an empty list otherwise. Note that this is a blocking call and the Tcl event loop will not be run until the command returns.

If the -async option is specified, the command returns right away. The name resolution is done in the background and when completed, SCRIPT is called at the global scope. Three additional arguments are appended to the script before it is executed - HOSTNAME, status success or fail and either the list of IP addresses (when the status is success) or the Winsock error code (when the status is fail). The Winsock error code may be translated to an error string using the map_windows_error command. If no addresses are found, the status is success but the third argument will be an empty list.

Internally, the command maintains a cache of address to hostname mappings so as to avoid unnecessary lookups. The result is normally returned from here if available. However, if the -flushcache option is specified, the cache entry is deleted and an explicit lookup up is done.

hwaddr_to_ipaddr HWADDR ?VARNAME?

Returns the IP address corresponding to the given hardware address. If VARNAME is specified, the command stores the result in a variable of that name in the caller's context if a mapping can be found and returns 1. Otherwise the command returns 0 without affecting the variable. If VARNAME is not specified, the command returns the IP address if a mapping is found and generates a Tcl exception otherwise.

ipaddr_to_hwaddr IPADDR ?VARNAME?

Returns the hardware address corresponding to the given IP address. If VARNAME is specified, the command stores the result in a variable of that name in the caller's context if a mapping can be found and returns 1. Otherwise the command returns 0 without affecting the variable. If VARNAME is not specified, the command returns the hardware address if a mapping is found and generates a Tcl exception otherwise.

Example: Map an IP address to a physical address

port_to_service PORTNUMBER

Returns the service name (e.g. http) corresponding to the specified port number. If no corresponding service name exists, an empty string is returned.

service_to_port SERVICENAME

Returns the port number corresponding to the specified service name (e.g. http). If the service name is not defined, an empty string is returned. If SERVICENAME is a port number, it is returned.

terminate_tcp_connections ?options?

Terminates all connections that match all the options specified. Any options that are not specified are assumed to match. The valid matching options are:

-matchlocaladdr IPADDR	Only matches those connections whose local address is bound to IPADDR.
-matchlocalport PORTNUMBER	Only matches those connections whose local port is the specified number.
-matchpid PID	Only matches those connections owned by the process with the specified PID. On platforms where the PID is not available, specifying this option will generate an error.
-matchremoteaddr IPADDR	Only matches those connections whose remote address is bound to IPADDR.
-matchremoteport PORTNUMBER	Only matches those connections whose remote port is PORTNUMBER.
matchstate STATELIST	Only matches those connections whose state is one those specified in STATELIST which should be a list of connection state values. See get_tcp_connections for a list of valid values.

COPYRIGHT

Copyright © 2004-2006, Ashok P. Nadkarni