salt.modules.win_ip#

The networking module for Windows based systems

salt.modules.win_ip.disable(iface)#

Disable an interface

Parameters:

iface (str) -- The name of the interface to manage

CLI Example:

salt -G 'os_family:Windows' ip.disable 'Local Area Connection #2'
salt.modules.win_ip.enable(iface)#

Enable an interface

Parameters:

iface (str) -- The name of the interface to manage

CLI Example:

salt -G 'os_family:Windows' ip.enable 'Local Area Connection #2'
salt.modules.win_ip.get_all_interfaces()#

Return IP configuration for all network interfaces using the legacy netsh-compatible data format.

Each interface is keyed by its alias and contains ip_addrs, ipv4_gateway, dns_servers, and related fields mirroring the structure formerly produced by netsh interface ip show config. Prefer list_interfaces() with full=True for richer, always- English output.

Returns:

A dictionary keyed by interface name. Each value is a dict with the legacy netsh-style fields.

Return type:

dict

CLI Example:

salt -G 'os_family:Windows' ip.get_all_interfaces
salt.modules.win_ip.get_default_gateway(iface=None)#

Get the Default Gateway on Windows.

Parameters:

iface (str, optional) -- The name or alias of the interface to query (e.g., 'Ethernet'). If provided, the function returns the default gateway specific to that interface. If None (default), it returns the system-wide primary default gateway based on the lowest route metric.

Returns:

The IP address of the default gateway.

Return type:

str

Raises:

CommandExecutionError -- If no default gateway is found.

CLI Example:

# Get the system's primary default gateway
salt 'minion' ip.get_default_gateway

# Get the gateway for a specific interface
salt 'minion' ip.get_default_gateway iface='Local Area Connection'
salt.modules.win_ip.get_interface(iface)#

Return the IP configuration of a single network interface

Parameters:

iface (str) -- The name of the interface

CLI Example:

salt -G 'os_family:Windows' ip.get_interface 'Local Area Connection'
salt.modules.win_ip.get_interface_index(iface, session=None)#

Return the integer ifIndex for the named interface.

Parameters:

  • iface (str) -- The interface name or alias (e.g., 'Ethernet').

  • session (PowerShellSession, optional) -- An existing PowerShellSession to reuse. If None (default), a new session is opened for this call only.

Returns:

The interface index.

Return type:

int

Raises:

CommandExecutionError -- If the interface cannot be found.

CLI Example:

salt -G 'os_family:Windows' ip.get_interface_index 'Ethernet'
salt.modules.win_ip.get_interface_new(iface)#

Retrieves the current configuration of a network interface on Windows.

This function gathers comprehensive data about a network adapter, including administrative status, protocol bindings, IP addresses, DNS servers, gateways, and WINS configuration. The returned dictionary is structured to be directly compatible with the parameters of set_interface.

Data Structures and Round-trip Logic:

  • Addresses: IPs are returned in CIDR notation (e.g., 10.0.0.5/24) to ensure the setter can accurately recreate the subnet mask.

  • Gateways: Returned as a list of dictionaries containing both the IP (ip) and the route-specific metric (metric).

  • Metrics: A value of 0 indicates that the interface is configured for 'Automatic Metric' calculation by Windows.

Parameters:

iface (str) -- The name or alias of the interface (e.g., 'Ethernet'). This is used for the initial hardware lookup to find the permanent InterfaceIndex.

Returns:

A dictionary keyed by the interface name containing:

  • alias (str): The friendly name of the adapter.

  • description (str): Human-readable adapter description (e.g., "Microsoft Loopback Adapter").

  • enabled (bool): Administrative status (True = Up).

  • index (int): The stable InterfaceIndex used internally by all CIM/PowerShell cmdlets.

  • link_status (str): Current link state reported by the driver (e.g., "Up", "Disconnected").

  • mac_address (str): The physical (MAC) address of the adapter.

  • mtu (int): MTU in bytes; defaults to 1500 when the adapter reports no value (4294967295 or None).

  • dns_register (bool): True if the adapter registers its addresses in DNS using the computer's primary DNS suffix.

  • dns_suffix (str): Connection-specific DNS suffix, or None if not set.

  • ipv4_enabled (bool): Status of the IPv4 protocol binding.

  • ipv4_dhcp (bool): True if IPv4 DHCP is enabled.

  • ipv4_metric (int): The IPv4 interface metric (0 = Auto).

  • ipv4_address (list): List of IPv4 addresses in CIDR format.

  • ipv4_gateways (list): List of dicts, each with ip and metric keys, for IPv4 default routes. Always a list — even when only one gateway is configured — because _normalize_gateway_fields() corrects the PowerShell 5.1 behavior of unwrapping single-element arrays.

  • ipv4_dns (list): List of IPv4 DNS server addresses.

  • ipv4_forwarding (bool | None): True if IPv4 forwarding is enabled, None if the IPv4 stack is not bound.

  • ipv4_wins (list): Primary and secondary WINS server addresses (empty list if none configured).

  • ipv4_netbios (str): NetBIOS configuration — "Default", "Enable", or "Disable".

  • ipv6_enabled (bool): Status of the IPv6 protocol binding.

  • ipv6_dhcp (bool): True if IPv6 stateful config is enabled.

  • ipv6_metric (int): The IPv6 interface metric (0 = Auto).

  • ipv6_address (list): List of IPv6 addresses in CIDR format.

  • ipv6_gateways (list): List of dicts, each with ip and metric keys, for IPv6 default routes. Always a list for the same reason as ipv4_gateways.

  • ipv6_dns (list): List of IPv6 DNS server addresses.

  • ipv6_forwarding (bool | None): True if IPv6 forwarding is enabled, None if the IPv6 stack is not bound.

Return type:

dict

Raises:

CommandExecutionError -- If the specified interface cannot be found.

CLI Examples:

# Get details for a specific interface
salt-call --local win_ip.get_interface_new "Ethernet"

# Get details for the loopback test adapter
salt '*' win_ip.get_interface_new "Test-Iface"
salt.modules.win_ip.get_subnet_length(mask)#

Convenience function to convert the netmask to the CIDR subnet length

Parameters:

mask (str) -- A netmask

CLI Example:

salt -G 'os_family:Windows' ip.get_subnet_length 255.255.255.0
salt.modules.win_ip.is_disabled(iface)#

Returns True if interface is disabled, otherwise False

Parameters:

iface (str) -- The name of the interface to manage

CLI Example:

salt -G 'os_family:Windows' ip.is_disabled 'Local Area Connection #2'
salt.modules.win_ip.is_enabled(iface)#

Returns True if interface is enabled, otherwise False

Parameters:

iface (str) -- The name of the interface to manage

CLI Example:

salt -G 'os_family:Windows' ip.is_enabled 'Local Area Connection #2'
salt.modules.win_ip.list_interfaces(full=False)#

Lists the available network interfaces on the system.

Parameters:

full (bool, optional) -- If True, returns a dictionary keyed by interface names with detailed configuration for each adapter. If False, returns a list of interface names only. Defaults to False.

Returns:

When full=False, a list of interface name strings.

dict: When full=True, a dictionary keyed by interface name.

Each value has the same structure as the per-interface dict returned by get_interface_new() — see that function for the full field reference (alias, description, enabled, index, link_status, mac_address, mtu, dns_register, dns_suffix, ipv4_*, ipv6_*).

The entire dataset is collected in a single PowerShell invocation rather than one session per adapter, so it is significantly faster than calling get_interface_new() in a loop.

Return type:

list

CLI Example:

salt -G 'os_family:Windows' ip.list_interfaces
salt -G 'os_family:Windows' ip.list_interfaces full=True
salt.modules.win_ip.raw_interface_configs()#

Return raw configs for all interfaces as returned by netsh. This command is localized and will return different text depending on the locality of the operating system.

CLI Example:

salt -G 'os_family:Windows' ip.raw_interface_configs
salt.modules.win_ip.set_dhcp_all(iface)#

Set both IP Address and DNS to DHCP

Parameters:

iface (str) -- The name of the interface to manage

Returns:

{"Interface": <name>, "DNS Server": "DHCP", "DHCP enabled": "Yes"}

Return type:

dict

Raises:

CommandExecutionError -- If either the IP or DNS cannot be switched to DHCP.

CLI Example:

salt -G 'os_family:Windows' ip.set_dhcp_all 'Local Area Connection'
salt.modules.win_ip.set_dhcp_dns(iface)#

Set DNS source to DHCP on Windows

Parameters:

iface (str) -- The name of the interface to manage

Returns:

{} if DNS was already set to automatic (no static servers configured), otherwise {"Interface": <name>, "DNS Server": "DHCP (Empty)"}.

Return type:

dict

Raises:

CommandExecutionError -- If the DNS reset cannot be verified.

CLI Example:

salt -G 'os_family:Windows' ip.set_dhcp_dns 'Local Area Connection'
salt.modules.win_ip.set_dhcp_ip(iface)#

Set Windows NIC to get IP from DHCP

Parameters:

iface (str) -- The name of the interface to manage

Returns:

{} if DHCP was already enabled, otherwise {"Interface": <name>, "DHCP enabled": "Yes"}.

Return type:

dict

Raises:

CommandExecutionError -- If DHCP cannot be enabled.

CLI Example:

salt -G 'os_family:Windows' ip.set_dhcp_ip 'Local Area Connection'
salt.modules.win_ip.set_interface(iface, alias=None, enabled=None, ipv4_enabled=None, ipv4_address=None, ipv4_dhcp=None, ipv4_dns=None, ipv4_forwarding=None, ipv4_gateways=None, ipv4_metric=None, ipv4_wins=None, ipv4_netbios=None, ipv6_enabled=None, ipv6_address=None, ipv6_dhcp=None, ipv6_dns=None, ipv6_forwarding=None, ipv6_gateways=None, ipv6_metric=None, dns_register=None, dns_suffix=None, mtu=None, append=False)#

Configures a network interface on Windows.

This function provides a context-aware interface for managing adapter properties, protocol bindings, and IP configurations. It utilizes the InterfaceIndex to ensure stability during renames.

Understanding Metrics on Windows: Windows calculates route priority by summing the Interface Metric (protocol level) and the Route Metric (gateway level).

  • Interface Metric: Set via ipvX_metric. A value of 0 enables 'Automatic Metric', where Windows assigns priority based on link speed.

  • Route Metric: Set within the ipvX_gateways objects.

  • Total Cost: Interface Metric + Route Metric. The lowest total cost determines the primary route.

Context-Aware Behavior: The function identifies the current state of protocol bindings (IPv4/IPv6) before applying settings.

  • If a protocol is disabled and ipvX_enabled is not passed as True, configuration for that stack (IPs, DNS, etc.) is skipped to prevent errors.

  • If ipvX_dhcp is enabled, static IP and gateway configurations are ignored by the OS; therefore, this function skips applying static addresses unless DHCP is False.

Parameters:

  • iface (str) -- The current name or alias of the interface (e.g., 'Ethernet').

  • alias (str, optional) -- A new name for the interface.

  • enabled (bool, optional) -- Administrative status of the adapter.

  • ipv4_enabled (bool, optional) -- Whether the IPv4 protocol is bound to this adapter. If None, the function discovers current state.

  • ipv4_address (list, optional) --

    An IPv4 address or list of addresses in CIDR notation (e.g., ['192.168.1.5/24']).

    Note

    If a CIDR prefix is not provided, it will default to /24.

  • ipv4_dhcp (bool, optional) -- Set to True to enable DHCP, False for static.

  • ipv4_dns (list, optional) -- A list of IPv4 DNS server addresses. Passing an empty list [] resets DNS to automatic.

  • ipv4_forwarding (bool, optional) -- Enables or disables IP Forwarding for the IPv4 stack. When True, this allows the Windows machine to act as a router, passing traffic between this interface and others. Default is None (no change).

  • ipv4_gateways (list, str, dict) --

    The default gateway(s). Accepts multiple formats:

    • String: A single IP address (e.g., '192.168.1.1').

    • List of Strings: Multiple gateways (e.g., ['1.1.1.1', '1.0.0.1']).

    • Dictionary: A single gateway with a specific route metric (e.g., {'ip': '192.168.1.1', 'metric': 5}).

    • List of Dictionaries: Multiple gateways with individual metrics (e.g., [{'ip': '1.1.1.1', 'metric': 2}, {'ip': '1.0.0.1', 'metric': 10}]).

    If a metric is not specified within a dictionary, or if a string/list of strings is provided, the function falls back to ipv4_metric.

  • ipv4_metric (int, optional) -- The IPv4 interface metric. Use 0 for Automatic.

  • ipv4_wins (list, optional) -- A list of up to two WINS server addresses.

  • ipv4_netbios (str, optional) --

    Configures NetBIOS over TCP/IP behavior via the MSFT_NetIPInterface CIM class.

    • Default (0): Defer to DHCP server settings.

    • Enable (1): Explicitly enable NetBIOS.

    • Disable (2): Explicitly disable NetBIOS.

  • ipv6_enabled (bool, optional) -- Whether the IPv6 protocol is bound.

  • ipv6_address (list, optional) --

    An IPv6 address or list of addresses in CIDR notation (e.g., ['2001:db8::1/64']).

    Note

    If a CIDR prefix is not provided, it will default to /64.

  • ipv6_dhcp (bool, optional) -- Set to True for IPv6 stateful configuration.

  • ipv6_dns (list, optional) -- A list of IPv6 DNS server addresses.

  • ipv6_forwarding (bool, optional) -- Enables or disables IP Forwarding for the IPv6 stack. When True, this allows the Windows machine to act as a router, passing traffic between this interface and others. Default is None (no change).

  • ipv6_gateways (list, optional) --

    The default gateway(s) for IPv6. Accepts multiple formats:

    • String: A single IPv6 address (e.g., '2001:db8::1').

    • List of Strings: Multiple gateways (e.g., ['2001:db8::1', 'fe80::1']).

    • Dictionary: A single gateway with a specific route metric (e.g., {'ip': '2001:db8::1', 'metric': 5}).

    • List of Dictionaries: Multiple gateways with individual metrics (e.g., [{'ip': '2001:db8::1', 'metric': 2}, {'ip': 'fe80::1', 'metric': 10}]).

    If a metric is not specified within a dictionary, or if a string/list of strings is provided, the function falls back to ipv6_metric. Note that link-local gateways (starting with fe80::) are fully supported as Windows scopes them via the interface index.

  • ipv6_metric (int, optional) -- The IPv6 interface metric. Use 0 for Automatic.

  • dns_register (bool, optional) --

    Controls whether the interface's IP addresses are registered in DNS using the computer's primary DNS suffix.

    • True (Default in Windows): Corresponds to "Primary only" in legacy output. The computer will attempt to dynamically update its DNS record (A/AAAA) on the DNS server.

    • False: Corresponds to "None". The computer will not attempt to register its name for this specific connection.

  • dns_suffix (str, optional) -- Sets the Connection-Specific DNS Suffix (e.g., corp.example.com). This value is used in DNS registration and resolution but does not change the global primary DNS suffix of the computer.

  • mtu (int, optional) -- Configures the Maximum Transmission Unit size for the physical adapter. Accepts values between 576 and 9000. Common uses include setting 9000 for Jumbo Frames in iSCSI/Storage networks or lower values for VPN compatibility.

  • append (bool) --

    If True, the provided IPv4 and IPv6 addresses will be added to the interface without removing existing ones. If False (default), all existing IPv4/IPv6 addresses on the interface will be removed before applying the new configuration.

    Note

    This flag only applies to IP addresses. Gateways (Default Routes) are always replaced if a new gateway is provided to ensure routing stability.

Returns:

True if successful, otherwise raises an exception.

Return type:

bool

CLI Examples:

# Set static IPv4 with a specific metric
salt-call --local win_ip.set_interface "Ethernet" ipv4_dhcp=False \
    ipv4_address="['192.168.1.10/24']" ipv4_metric=10

# Set multiple gateways with different route priorities
salt-call --local win_ip.set_interface "Test-Iface" \
    ipv4_gateways="[{'ip': '10.0.0.1', 'metric': 2}, {'ip': '10.0.0.2', 'metric': 100}]"

# Reset DNS to automatic/DHCP
salt '*' win_ip.set_interface "Wi-Fi" ipv4_dns="[]"

# Rename an interface and enable IPv6
salt-call --local win_ip.set_interface "Ethernet 2" alias="Production" \
    ipv6_enabled=True ipv6_dhcp=True
salt.modules.win_ip.set_static_dns(iface, *addrs)#

Set static DNS configuration on a Windows NIC

Parameters:

  • iface (str) -- The name of the interface to manage

  • addrs (list) -- One or more DNS servers to be added. To clear the list of DNS servers pass an empty list ([]). If undefined or None no changes will be made.

Returns:

A dictionary containing the new DNS settings

Return type:

dict

CLI Example:

salt -G 'os_family:Windows' ip.set_static_dns 'Local Area Connection' '192.168.1.1'
salt -G 'os_family:Windows' ip.set_static_dns 'Local Area Connection' '192.168.1.252' '192.168.1.253'
salt.modules.win_ip.set_static_ip(iface, addr, gateway=None, append=False)#

Set static IP configuration on a Windows NIC

Parameters:

  • iface (str) -- The name of the interface to manage

  • addr (str) -- IP address with subnet length (ex. 10.1.2.3/24). The ip.get_subnet_length function can be used to calculate the subnet length from a netmask.

  • gateway (str, optional) -- If specified, the default gateway will be set to this value. Default is None.

  • append (bool, optional) -- If True, the address will be added as a secondary IP to the interface. If False, all existing IPv4 addresses are cleared first. Defaults to False.

Returns:

A dictionary with the applied settings, e.g.:

{"Address Info": ["192.168.1.5/24"], "Default Gateway": "192.168.1.1"}

Default Gateway is only present when the gateway argument is provided.

Return type:

dict

Raises:

CLI Example:

salt -G 'os_family:Windows' ip.set_static_ip 'Local Area Connection' 10.1.2.3/24 gateway=10.1.2.1
salt -G 'os_family:Windows' ip.set_static_ip 'Local Area Connection' 10.1.2.4/24 append=True