WWWWWW

Current Directory: /opt/saltstack/salt/lib/python3.10/site-packages/salt/states
Viewing File: /opt/saltstack/salt/lib/python3.10/site-packages/salt/states/win_network.py
"""
Configuration of network interfaces on Windows hosts
====================================================

.. versionadded:: 2014.1.0

This module provides the ``network`` state(s) on Windows hosts. DNS servers, IP
addresses and default gateways can currently be managed.

Below is an example of the configuration for an interface that uses DHCP for
both DNS servers and IP addresses:

.. code-block:: yaml

    Local Area Connection #2:
      network.managed:
        - dns_proto: dhcp
        - ip_proto: dhcp

.. note::

    Both the ``dns_proto`` and ``ip_proto`` arguments are required.

Static DNS and IP addresses can be configured like so:

.. code-block:: yaml

    Local Area Connection #2:
      network.managed:
        - dns_proto: static
        - dns_servers:
          - 8.8.8.8
          - 8.8.4.4
        - ip_proto: static
        - ip_addrs:
          - 10.2.3.4/24

.. note::

    IP addresses are specified using the format
    ``<ip-address>/<subnet-length>``. Salt provides a convenience function
    called :mod:`ip.get_subnet_length <salt.modules.win_ip.get_subnet_length>`
    to calculate the subnet length from a netmask.

Optionally, if you are setting a static IP address, you can also specify the
default gateway using the ``gateway`` parameter:

.. code-block:: yaml

    Local Area Connection #2:
      network.managed:
        - dns_proto: static
        - dns_servers:
          - 8.8.8.8
          - 8.8.4.4
        - ip_proto: static
        - ip_addrs:
          - 10.2.3.4/24
        - gateway: 10.2.3.1
"""

import logging

import salt.utils.data
import salt.utils.platform
import salt.utils.validate.net
from salt.exceptions import CommandExecutionError

# Set up logging
log = logging.getLogger(__name__)

__VALID_PROTO = ("static", "dhcp")

# Define the module's virtual name
__virtualname__ = "network"


def __virtual__():
    """
    Confine this module to Windows systems with the required execution module
    available.
    """
    if salt.utils.platform.is_windows() and "ip.get_interface" in __salt__:
        return __virtualname__
    return (False, "ip module could not be loaded")


def _validate(dns_proto, dns_servers, ip_proto, ip_addrs, gateway):
    """
    Ensure that the configuration passed is formatted correctly and contains
    valid IP addresses, etc.
    """
    errors = []
    # Validate DNS configuration
    if dns_proto == "dhcp":
        if dns_servers is not None:
            errors.append(
                "The dns_servers param cannot be set if unless dns_proto is "
                "set to 'static'"
            )
    else:
        if str(dns_servers).lower() in ["none", "[]"]:
            pass
        elif not isinstance(dns_servers, list):
            errors.append("The dns_servers param must be formatted as a list")
        else:
            bad_ips = [
                x for x in dns_servers if not salt.utils.validate.net.ipv4_addr(x)
            ]
            if bad_ips:
                errors.append("Invalid DNS server IPs: {}".format(", ".join(bad_ips)))

    # Validate IP configuration
    if ip_proto == "dhcp":
        if ip_addrs is not None:
            errors.append(
                "The ip_addrs param cannot be set if unless ip_proto is set to 'static'"
            )
        if gateway is not None:
            errors.append(
                "A gateway IP cannot be set if unless ip_proto is set to 'static'"
            )
    else:
        if not ip_addrs:
            errors.append("The ip_addrs param is required to set static IPs")
        elif not isinstance(ip_addrs, list):
            errors.append("The ip_addrs param must be formatted as a list")
        else:
            bad_ips = [x for x in ip_addrs if not salt.utils.validate.net.ipv4_addr(x)]
            if bad_ips:
                errors.append(
                    "The following static IPs are invalid: {}".format(
                        ", ".join(bad_ips)
                    )
                )

            # Validate default gateway
            if gateway is not None:
                if not salt.utils.validate.net.ipv4_addr(gateway):
                    errors.append(f"Gateway IP {gateway} is invalid")

    return errors


def _addrdict_to_ip_addrs(addrs):
    """
    Extracts a list of IP/CIDR expressions from a list of addrdicts, as
    retrieved from ip.get_interface
    """
    return [
        "{}/{}".format(x["IP Address"], x["Subnet"].rsplit("/", 1)[-1]) for x in addrs
    ]


def _changes(cur, dns_proto, dns_servers, ip_proto, ip_addrs, gateway):
    """
    Compares the current interface against the desired configuration and
    returns a dictionary describing the changes that need to be made.
    """
    changes = {}
    cur_dns_proto = "static" if "Statically Configured DNS Servers" in cur else "dhcp"
    if cur_dns_proto == "static":
        if isinstance(cur["Statically Configured DNS Servers"], list):
            cur_dns_servers = cur["Statically Configured DNS Servers"]
        else:
            cur_dns_servers = [cur["Statically Configured DNS Servers"]]
        if set(dns_servers or ["None"]) != set(cur_dns_servers):
            changes["dns_servers"] = dns_servers
    elif "DNS servers configured through DHCP" in cur:
        cur_dns_servers = cur["DNS servers configured through DHCP"]
        if dns_proto == "static":
            # If we're currently set to 'dhcp' but moving to 'static', specify the changes.
            if set(dns_servers or ["None"]) != set(cur_dns_servers):
                changes["dns_servers"] = dns_servers

    cur_ip_proto = "static" if cur["DHCP enabled"] == "No" else "dhcp"
    cur_ip_addrs = _addrdict_to_ip_addrs(cur.get("ip_addrs", []))
    cur_gateway = cur.get("Default Gateway")

    if dns_proto != cur_dns_proto:
        changes["dns_proto"] = dns_proto
    if ip_proto != cur_ip_proto:
        changes["ip_proto"] = ip_proto
    if set(ip_addrs or []) != set(cur_ip_addrs):
        if ip_proto == "static":
            changes["ip_addrs"] = ip_addrs
    if gateway != cur_gateway:
        if ip_proto == "static":
            changes["gateway"] = gateway
    return changes


def managed(
    name,
    dns_proto=None,
    dns_servers=None,
    ip_proto=None,
    ip_addrs=None,
    gateway=None,
    enabled=True,
    **kwargs,
):
    """
    Ensure that the named interface is configured properly.

    Args:

        name (str):
            The name of the interface to manage

        dns_proto (str): None
            Set to ``static`` and use the ``dns_servers`` parameter to provide a
            list of DNS nameservers. set to ``dhcp`` to use DHCP to get the DNS
            servers.

        dns_servers (list): None
            A list of static DNS servers. To clear the list of DNS servers pass
            an empty list (``[]``). ``None`` will make no changes.

        ip_proto (str): None
            Set to ``static`` and use the ``ip_addrs`` and (optionally)
            ``gateway`` parameters to provide a list of static IP addresses and
            the default gateway. Set to ``dhcp`` to use DHCP.

        ip_addrs (list): None
            A list of static IP addresses with netmask flag, ie: 192.168.0.11/24

        gateway (str): None
            The gateway to set for the interface

        enabled (bool): True
            Set to ``False`` to ensure that this interface is disabled.

    Returns:
        dict: A dictionary of old and new settings

    Example:

    .. code-block:: yaml

        Ethernet1:
          network.managed:
            - dns_proto: static
            - dns_servers:
              - 8.8.8.8
              - 8.8.8.4
            - ip_proto: static
            - ip_addrs:
              - 192.168.0.100/24

    Clear DNS entries example:

    .. code-block:: yaml

        Ethernet1:
          network.managed:
            - dns_proto: static
            - dns_servers: []
            - ip_proto: dhcp
    """
    ret = {
        "name": name,
        "changes": {},
        "result": True,
        "comment": f"Interface '{name}' is up to date",
    }

    dns_proto = str(dns_proto).lower()
    ip_proto = str(ip_proto).lower()

    errors = []
    if dns_proto not in __VALID_PROTO:
        ret["result"] = False
        errors.append(
            "dns_proto must be one of the following: {}".format(
                ", ".join(__VALID_PROTO)
            )
        )

    if ip_proto not in __VALID_PROTO:
        errors.append(
            "ip_proto must be one of the following: {}".format(", ".join(__VALID_PROTO))
        )

    if errors:
        ret["result"] = False
        ret["comment"] = "\n".join(errors)
        return ret

    try:
        currently_enabled = __salt__["ip.is_enabled"](name)
    except CommandExecutionError:
        currently_enabled = False

    if not enabled:
        if currently_enabled:
            if __opts__["test"]:
                ret["result"] = None
                ret["comment"] = f"Interface '{name}' will be disabled"
            else:
                ret["result"] = __salt__["ip.disable"](name)
                if not ret["result"]:
                    ret["comment"] = f"Failed to disable interface '{name}'"
        else:
            ret["comment"] += " (already disabled)"
        return ret
    else:
        if not currently_enabled:
            if __opts__["test"]:
                ret["result"] = None
                ret["comment"] = f"Interface '{name}' will be enabled"
            else:
                if not __salt__["ip.enable"](name):
                    ret["result"] = False
                    ret["comment"] = (
                        f"Failed to enable interface '{name}' to make changes"
                    )
                    return ret

        errors = _validate(dns_proto, dns_servers, ip_proto, ip_addrs, gateway)
        if errors:
            ret["result"] = False
            ret["comment"] = (
                "The following SLS configuration errors were detected:\n- {}".format(
                    "\n- ".join(errors)
                )
            )
            return ret

        old = __salt__["ip.get_interface"](name)
        if not old:
            ret["result"] = False
            ret["comment"] = (
                f"Unable to get current configuration for interface '{name}'"
            )
            return ret

        changes = _changes(old, dns_proto, dns_servers, ip_proto, ip_addrs, gateway)

        # If dns_servers is the default `None` make no changes
        # To clear the list, pass an empty dict
        if str(dns_servers).lower() == "none":
            changes.pop("dns_servers", None)

        if not changes:
            return ret

        if __opts__["test"]:
            comments = []
            if "dns_proto" in changes:
                comments.append(
                    "DNS protocol will be changed to: {}".format(changes["dns_proto"])
                )
            if dns_proto == "static" and "dns_servers" in changes:
                if len(changes["dns_servers"]) == 0:
                    comments.append("The list of DNS servers will be cleared")
                else:
                    comments.append(
                        "DNS servers will be set to the following: {}".format(
                            ", ".join(changes["dns_servers"])
                        )
                    )
            if "ip_proto" in changes:
                comments.append(
                    "IP protocol will be changed to: {}".format(changes["ip_proto"])
                )
            if ip_proto == "static":
                if "ip_addrs" in changes:
                    comments.append(
                        "IP addresses will be set to the following: {}".format(
                            ", ".join(changes["ip_addrs"])
                        )
                    )
                if "gateway" in changes:
                    if changes["gateway"] is None:
                        comments.append("Default gateway will be removed")
                    else:
                        comments.append(
                            "Default gateway will be set to {}".format(
                                changes["gateway"]
                            )
                        )

            ret["result"] = None
            ret["comment"] = (
                "The following changes will be made to interface '{}':\n- {}".format(
                    name, "\n- ".join(comments)
                )
            )
            return ret

        if changes.get("dns_proto") == "dhcp":
            __salt__["ip.set_dhcp_dns"](name)

        elif "dns_servers" in changes:
            if len(changes["dns_servers"]) == 0:
                # To clear the list of DNS servers you have to pass []. Later
                # changes gets passed like *args and a single empty list is
                # converted to an empty tuple. So, you have to add [] here
                changes["dns_servers"] = [[]]

            __salt__["ip.set_static_dns"](name, *changes["dns_servers"])

        if changes.get("ip_proto") == "dhcp":
            __salt__["ip.set_dhcp_ip"](name)
        elif (
            changes.get("ip_addrs")
            or changes.get("gateway")
            or changes.get("ip_proto") == "static"
        ):
            if changes.get("gateway") and not changes.get("ip_addrs"):
                changes["ip_addrs"] = ip_addrs
            if changes.get("ip_proto") == "static" and not changes.get("ip_addrs"):
                changes["ip_addrs"] = ip_addrs
            for idx in range(len(changes["ip_addrs"])):
                if idx == 0:
                    __salt__["ip.set_static_ip"](
                        name, changes["ip_addrs"][idx], gateway=gateway, append=False
                    )
                else:
                    __salt__["ip.set_static_ip"](
                        name, changes["ip_addrs"][idx], gateway=None, append=True
                    )

        new = __salt__["ip.get_interface"](name)
        ret["changes"] = salt.utils.data.compare_dicts(old, new)
        if _changes(new, dns_proto, dns_servers, ip_proto, ip_addrs, gateway):
            ret["result"] = False
            ret["comment"] = (
                "Failed to set desired configuration settings "
                "for interface '{}'".format(name)
            )
        else:
            ret["comment"] = (
                f"Successfully updated configuration for interface '{name}'"
            )
        return ret
F1l3 Manager
