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:

SaltInvocationError -- If addr or gateway is not a valid IPv4 address.
CommandExecutionError -- If the address already exists on the interface.

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

Generated on April 29, 2026 at 18:58:52 UTC.

You are viewing docs for the previous stable release, 3006.24. Switch to docs for the latest stable release, 3007.14, or to a recent doc build from the master branch.

saltproject.io