Network configuration

Commands related to network configuration

SYNOPSIS

package require twapi_network
flush_arp_tables ?INTERFACENAME...?
get_arp_table ?-sort?
get_ipaddr_version IPADDR
get_network_adapter_info NETWORKINTERFACE ?options?
get_network_info ?options?
get_network_adapters
get_network_adapters_detail
get_outgoing_interface DESTADDR
get_route ?options?
get_routing_table ?-sort?
get_system_ipaddrs ?-ipversion IPVERSION? ?-types ADDRTYPELIST?
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
resolve_address IPADDRESS ?-async SCRIPT?
resolve_hostname HOSTNAME ?-async SCRIPT? ?-ipversion IPVERSION?
service_to_port SERVICENAME
terminate_tcp_connections ?options?

DESCRIPTION

This module provides procedures to retrieve network information for IPv4 and IPv6.

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.

Some commands only support IPv4 due to lack of underlying Windows support for the underlying Windows API on Windows XP and Windows 2003. This is noted where applicable.

Commands

flush_arp_tables ?INTERFACENAME...?
Note: This command only affects IPv4 tables

Flushes the ARP tables associated with the specified network interfaces. If no arguments are specified, all interfaces are flushed.
get_arp_table ?-sort?
Note: This command only retrieves IPv4 tables

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. Note the hardware address may be empty, for example when the associated interface is the loopback adapter. If option -sort is specified, returns the entries sorted by interface index, then IP address.
get_ipaddr_version IPADDR
Returns the IP version (4 or 6) of the IP address specified as IPADDR. Returns 0 if IPADDR is not a valid IPv4 or IPv6 address.
get_network_adapter_info NETWORKINTERFACE ?options?
Returns various information about the configuration of a network interface. NETWORKINTERFACE must be the name of a network interface as returned by get_network_adapters.

The information returned depends on the options specified and is in the form of a dictionary whose keys depend on the options specified:

The following options may be specified:
-adaptername Returns the name of the adapter associated with the interface.
-all Returns all option values.
-anycastaddresses Returns list of anycast addresses associated with the interface. Each element in the list is a dictionary, with the key -address containing the address. Other keys in the dictionary should be ignored.
-description Returns a description of the interface.
-dhcpenabled Returns 1 if DHCP is enabled on the interface, else 0.
-dnsservers Returns a list of DNS servers on that interface. Each element in the list is a dictionary, with the key -address containing the address of the server. Other keys in the dictionary should be ignored.
-dnssuffix Returns the DNS suffix for the adapter.
-friendlyname Returns the friendly name of the adapter suitable for display to users.
-ipv4ifindex Returns the IP V4 interface index.
-ipv6ifindex Returns the IP V6 interface index.
-mtu Returns the MTU size for the adapter.
-multicastaddresses Returns list of multicast addresses associated with the interface. Each element in the list is a dictionary, with the key -address containing the address. Other keys in the dictionary should be ignored.
-operstatus Returns the operational status of the interface as defined in RFC2863. Some common values are 1 (up), 2 (down), 3 (testing mode), 4 (unknown state), 5 (dormant), 6 (not present), 7 (lower layer is down).
-physicaladdress Returns the physical address of the network interface.
-prefixes Returns list of address prefixes associated with the interface. Each element in the list is a dictionary, with the key -address containing the address and the key -prefixlength containing the number of bits in the prefix. Other keys in the dictionary should be ignored.
-type Returns the network interface type. This is an integer value as defined by IANA. Some common values are 6 (Ethernet), 9 (token ring), 23 (PPP), 24 (loopback), 71 (802.11 wireless), 131 (tunneling) and 144 (IEEE 1394 Firewire).
-unicastaddresses Returns list of unicast addresses associated with the interface. Each element in the list is a dictionary, with the key -address containing the address. Other keys in the dictionary should be ignored.
-zoneindices Returns list of IPv6 scope IDs.
get_network_info ?options?
Note: This command only returns information related to IPv4 configuration.

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.
get_network_adapters
Returns a list of network interface names.
get_network_adapters_detail
Returns a record array containing detailed information about all the network interfaces on the system. The record array contains the following fields:
-adaptername The name of the adapter.
-anycastaddresses List of anycast addresses associated with the interface. Each element in the list is a dictionary, with the key -address containing the address. Other keys in the dictionary should be ignored.
-description Description of the interface.
-dnsservers Returns a list of DNS servers on that interface. Each element in the list is a dictionary, with the key -address containing the address of the server. Other keys in the dictionary should be ignored.
-dnssuffix The DNS suffix for the adapter.
-flags Undocumented.
-friendlyname The friendly name of the adapter.
-ipv4ifindex The IP V4 interface index.
-ipv6ifindex The IP V6 interface index.
-mtu The MTU size for the adapter.
-multicastaddresses Multicast addresses associated with the interface. Each element in the list is a dictionary, with the key -address containing the address. Other keys in the dictionary should be ignored.
-operstatus Operational status of the interface as defined in RFC2863. Some common values are 1 (up), 2 (down), 3 (testing mode), 4 (unknown state), 5 (dormant), 6 (not present), 7 (lower layer is down).
-physicaladdress Physical address of the network interface.
-prefixes List of address prefixes associated with the interface. Each element in the list is a dictionary, with the key -address containing the address and the key -prefixlength containing the number of bits in the prefix. Other keys in the dictionary should be ignored.
-type Network interface type. This is an integer value as defined by IANA. Some common values are 6 (Ethernet), 9 (token ring), 23 (PPP), 24 (loopback), 71 (802.11 wireless), 131 (tunneling) and 144 (IEEE 1394 Firewire).
-unicastaddresses List of unicast addresses associated with the interface. Each element in the list is a dictionary, with the key -address containing the address. Other keys in the dictionary should be ignored.
-zoneindices List of IPv6 scope IDs.
get_outgoing_interface DESTADDR
Note: This command is only supported for IPv4.

Returns the index of the network interface that will be used to send a packet to the IP address specified by DESTADDR
get_route ?options?
Note: This command is only supported for IPv4.

Returns the best route to a specified destination. The following options may be specified:
-dest DESTADDR Specifies the destination address for which the route is to be returned. If unspecified, defaults to 0.0.0.0 which corresponds to the default route.
-source SRCADDR Specifies the source address to be used. This can affect the route selected. Defaults to 0.0.0.0 which indicates the source address should not affect which route is selected.
The returned information is a keyed list with the following fields:
-addr The destination address that together with the -mask field specifies the address range to which the route applies.
-age The age of the route in seconds. This is valid only if the Routing and Remote Access service is running and the protocol is netmgmt.
-ifindex The interface index for this route.
-mask The network mask that together with -dest specifies the address range to which the route applies.
-metric1 A routing protocol specific metric value.
-metric2 A routing protocol specific metric value.
-metric3 A routing protocol specific metric value.
-metric4 A routing protocol specific metric value.
-metric5 A routing protocol specific metric value.
-nexthop The IP address of next hop in the route to the destination.
-nexthopas The autonomous system number of the next hop.
-policy Multi-path route selector condition, typically in IP TOS format as defined in RFC 1354.
-protocol Protocol that generated the route.
-type The type of the route. This is one of local, remote, other or invalid.
get_routing_table ?-sort?
Note: This command is only returns routing information for IPv4.

Returns the network routing table as a list of routes. Each element of the route is in the format described in the get_route command description.
get_system_ipaddrs ?-ipversion IPVERSION? ?-types ADDRTYPELIST?
Returns a list of IP addresses for the system.

If -ipversion is not specified, or IPVERSION is 0, any or all, both IPv4 and IPv6 addresses are returned. If IPVERSION is 4 or inet, only IPv4 addresses are returned and if it is 6 or inet6, only IPv6 addresses are returned.

By default, only unicast addresses are returned. If the -types option is specified, ADDRTYPELIST should be a list of one or more of the following: all, unicast, multicast or anycast. In that case, only addresses matching one of those types (or all types in the case of all) are returne.
get_tcp_connections ?options?
Retrieves information about currently active TCP connections similar to the Windows netstat command. The return value is a record array whose fields are controlled through the following options:
-all Returns all fields for a connection. This option is assumed if no other field option is specified.
-bindtime Returns the time at which the last bind operation was done on the socket, or 0 if no bind has been done. This may not be available in which case, an empty string is returned for the value. Deprecated
-localaddr Returns the local address being used for the connection.
-localport Returns the local port number being used for the connection.
-modulename Returns the name of the process module that owns the socket. This may not be available in which case, an empty string is returned for the value. This value is always the empty string for IPv6 to work around a Windows bug. Deprecated
-modulepath Returns the path to the process module that owns the socket. This may not be available in which case, an empty string is returned for the value. This value is always the empty string for IPv6 to work around a Windows bug. Deprecated
-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.
-ipversion IPVERSION If IPVERSION is 0 (default), any or all, both IPv4 and IPv6 connections are returned. If IPVERSION is 4 or inet, only IPv4 connections are returned and if it is 6 or inet6, only IPv6 connections are returned.
-matchlocaladdr HOSTLIST Only returns those connections whose local address is one of those specified in HOSTLIST. Each element of HOSTLIST may be either an IP address or a host name.
-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 HOSTLIST Only returns those connections whose remote address is one of those specified in HOSTLIST. Each element of HOSTLIST may be either an IP address or a host name.
-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 record array whose fields are controlled through the following options:
-all Returns all fields for a connection. This option is assumed if no other field option is specified.
-bindtime Returns the time at which the last bind operation was done on the socket, or 0 if no bind has been done. This may not be available in which case, an empty string is returned for the value. Deprecated
-localaddr Returns the local address being used for the connection.
-localport Returns the local port number being used for the connection.
-modulename Returns the name of the process module that owns the socket. This may not be available in which case, an empty string is returned for the value. This value is always the empty string for IPv6 to work around a Windows bug. Deprecated
-modulepath Returns the path to the process module that owns the socket. This may not be available in which case, an empty string is returned for the value. This value is always the empty string for IPv6 to work around a Windows bug. Deprecated
-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.
-ipversion IPVERSION If IPVERSION is 0 (default), any or all, both IPv4 and IPv6 connections are returned. If IPVERSION is 4 or inet, only IPv4 connections are returned and if it is 6 or inet6, only IPv6 connections are returned.
-matchlocaladdr HOSTLIST Only returns those connections whose local address is one of those specified in HOSTLIST. Each element of HOSTLIST may be either an IP address or a host name.
-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?
This command is deprecated in favor of resolve_hostname. It only returns IPv4 addresses.
hwaddr_to_ipaddr HWADDR ?VARNAME?
Note: This command is only supported for IPv4.

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?
Note: This command is only supported for IPv4.

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.
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.
resolve_address IPADDRESS ?-async SCRIPT?
Attempts to map the specified Internet address IPADDRESS to its fully qualified DNS name (FQDN). IPADDRESS may be an IPv4 or IPv6 address.

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.

Note the -async option requires a threaded build of Tcl and will raise an exception on non-threaded builds.

Note the address to hostname mapping is no longer cached internally by TWAPI as in older releases. Applications can do the caching themselves if desired.
resolve_hostname HOSTNAME ?-async SCRIPT? ?-ipversion IPVERSION?
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 -ipversion is not specified, or IPVERSION is 0, any or all, both IPv4 and IPv6 addresses are returned. If IPVERSION is 4 or inet, only IPv4 addresses are returned and if it is 6 or inet6, only IPv6 addresses are returned.

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. Note that on some platforms, if no addresses are found, callback may be invoked with a status of success and an empty list for the third argument, or it may be invoked with a status of fail and an appropriate error code.

Note the -async option requires a threaded build of Tcl and will raise an exception on non-threaded builds.
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?
Note: This command is only supported for IPv4 connections

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.
The system attempts to terminate the specified connections but no error is raised if the connection cannot be terminated. Caller should retrieve the list of connections to check if the termination was successful.

COPYRIGHT

Copyright © 2004-2014, Ashok P. Nadkarni

Tcl Windows API 4.2b9