Salt Proxy Minion¶

Configuration parameters¶

Proxy minions require no configuration parameters in /etc/salt/master.

Salt's Pillar system is ideally suited for configuring proxy-minions (though they can be configured in /etc/salt/proxy as well). Proxies can either be designated via a pillar file in pillar_roots, or through an external pillar. External pillars afford the opportunity for interfacing with a configuration management system, database, or other knowledgeable system that that may already contain all the details of proxy targets. To use static files in pillar_roots, pattern your files after the following examples, which are based on the diagram above:

/srv/pillar/top.sls

base:
  net-device1:
    - net-device1
  net-device2:
    - net-device2
  net-device3:
    - net-device3
  i2c-device4:
    - i2c-device4
  i2c-device5:
    - i2c-device5
  433wireless-device6:
    - 433wireless-device6
  smsgate-device7:
    - device7

/srv/pillar/net-device1.sls

proxy:
  proxytype: networkswitch
  host: 172.23.23.5
  username: root
  passwd: letmein

/srv/pillar/net-device2.sls

proxy:
  proxytype: networkswitch
  host: 172.23.23.6
  username: root
  passwd: letmein

/srv/pillar/net-device3.sls

proxy:
  proxytype: networkswitch
  host: 172.23.23.7
  username: root
  passwd: letmein

/srv/pillar/i2c-device4.sls

proxy:
  proxytype: i2c_lightshow
  i2c_address: 1

/srv/pillar/i2c-device5.sls

proxy:
  proxytype: i2c_lightshow
  i2c_address: 2

/srv/pillar/433wireless-device6.sls

proxy:
  proxytype: 433mhz_wireless

/srv/pillar/smsgate-device7.sls

proxy:
  proxytype: sms_serial
  deventry: /dev/tty04

Note the contents of each minioncontroller key may differ widely based on the type of device that the proxy-minion is managing.

In the above example

• net-devices 1, 2, and 3 are network switches that have a management interface available at a particular IP address.

• i2c-devices 4 and 5 are very low-level devices controlled over an i2c bus. In this case the devices are physically connected to machine 'minioncontroller2', and are addressable on the i2c bus at their respective i2c addresses.

• 433wireless-device6 is a 433 MHz wireless transmitter, also physically connected to minioncontroller2

• smsgate-device7 is an SMS gateway connected to machine minioncontroller3 via a serial port.

Because of the way pillar works, each of the salt-proxy processes that fork off the proxy minions will only see the keys specific to the proxies it will be handling.

Proxies can be configured in /etc/salt/proxy or with files in /etc/salt/proxy.d as of Salt's 2016.11.0 release.

Also, in general, proxy-minions are lightweight, so the machines that run them could conceivably control a large number of devices. To run more than one proxy from a single machine, simply start an additional proxy process with --proxyid set to the id to which you want the proxy to bind. It is possible for the proxy services to be spread across many machines if necessary, or intentionally run on machines that need to control devices because of some physical interface (e.g. i2c and serial above). Another reason to divide proxy services might be security. In more secure environments only certain machines may have a network path to certain devices.

Proxymodules¶

A proxy module encapsulates all the code necessary to interface with a device. Proxymodules are located inside the salt.proxy module, or can be placed in the _proxy directory in your file_roots (default is /srv/salt/_proxy. At a minimum a proxymodule object must implement the following functions:

__virtual__(): This function performs the same duty that it does for other types of Salt modules. Logic goes here to determine if the module can be loaded, checking for the presence of Python modules on which the proxy depends. Returning False will prevent the module from loading.

init(opts): Perform any initialization that the device needs. This is a good place to bring up a persistent connection to a device, or authenticate to create a persistent authorization token.

initialized(): Returns True if init() was successfully called.

shutdown(): Code to cleanly shut down or close a connection to a controlled device goes here. This function must exist, but can contain only the keyword pass if there is no shutdown logic required.

ping(): While not required, it is highly recommended that this function also be defined in the proxymodule. The code for ping should contact the controlled device and make sure it is really available.

alive(opts): Another optional function, it is used together with the proxy_keep_alive option (default: True). This function should return a boolean value corresponding to the state of the connection. If the connection is down, will try to restart (shutdown followed by init). The polling frequency is controlled using the proxy_keep_alive_interval option, in minutes.

grains(): Rather than including grains in /srv/salt/_grains or in the standard install directories for grains, grains can be computed and returned by this function. This function will be called automatically if proxy_merge_grains_in_module is set to True in /etc/salt/proxy. This variable defaults to True in the release code-named 2017.7.0.

Pre 2015.8 the proxymodule also must have an id() function. 2015.8 and following don't use this function because the proxy's id is required on the command line.

Here is an example proxymodule used to interface to a very simple REST server. Code for the server is in the salt-contrib GitHub repository.

This proxymodule enables "service" enumeration, starting, stopping, restarting, and status; "package" installation, and a ping.

# -*- coding: utf-8 -*-
"""
This is a simple proxy-minion designed to connect to and communicate with
the bottle-based web service contained in https://github.com/saltstack/salt-contrib/tree/master/proxyminion_rest_example
"""
from __future__ import absolute_import

# Import python libs
import logging
import salt.utils.http

HAS_REST_EXAMPLE = True

# This must be present or the Salt loader won't load this module
__proxyenabled__ = ["rest_sample"]


# Variables are scoped to this module so we can have persistent data
# across calls to fns in here.
GRAINS_CACHE = {}
DETAILS = {}

# Want logging!
log = logging.getLogger(__file__)


# This does nothing, it's here just as an example and to provide a log
# entry when the module is loaded.
def __virtual__():
    """
    Only return if all the modules are available
    """
    log.debug("rest_sample proxy __virtual__() called...")
    return True


def _complicated_function_that_determines_if_alive():
    return True


# Every proxy module needs an 'init', though you can
# just put DETAILS['initialized'] = True here if nothing
# else needs to be done.


def init(opts):
    log.debug("rest_sample proxy init() called...")
    DETAILS["initialized"] = True

    # Save the REST URL
    DETAILS["url"] = opts["proxy"]["url"]

    # Make sure the REST URL ends with a '/'
    if not DETAILS["url"].endswith("/"):
        DETAILS["url"] += "/"


def alive(opts):
    """
    This function returns a flag with the connection state.
    It is very useful when the proxy minion establishes the communication
    via a channel that requires a more elaborated keep-alive mechanism, e.g.
    NETCONF over SSH.
    """
    log.debug("rest_sample proxy alive() called...")
    return _complicated_function_that_determines_if_alive()


def initialized():
    """
    Since grains are loaded in many different places and some of those
    places occur before the proxy can be initialized, return whether
    our init() function has been called
    """
    return DETAILS.get("initialized", False)


def grains():
    """
    Get the grains from the proxied device
    """
    if not DETAILS.get("grains_cache", {}):
        r = salt.utils.http.query(
            DETAILS["url"] + "info", decode_type="json", decode=True
        )
        DETAILS["grains_cache"] = r["dict"]
    return DETAILS["grains_cache"]


def grains_refresh():
    """
    Refresh the grains from the proxied device
    """
    DETAILS["grains_cache"] = None
    return grains()


def fns():
    return {
        "details": "This key is here because a function in "
        "grains/rest_sample.py called fns() here in the proxymodule."
    }


def service_start(name):
    """
    Start a "service" on the REST server
    """
    r = salt.utils.http.query(
        DETAILS["url"] + "service/start/" + name, decode_type="json", decode=True
    )
    return r["dict"]


def service_stop(name):
    """
    Stop a "service" on the REST server
    """
    r = salt.utils.http.query(
        DETAILS["url"] + "service/stop/" + name, decode_type="json", decode=True
    )
    return r["dict"]


def service_restart(name):
    """
    Restart a "service" on the REST server
    """
    r = salt.utils.http.query(
        DETAILS["url"] + "service/restart/" + name, decode_type="json", decode=True
    )
    return r["dict"]


def service_list():
    """
    List "services" on the REST server
    """
    r = salt.utils.http.query(
        DETAILS["url"] + "service/list", decode_type="json", decode=True
    )
    return r["dict"]


def service_status(name):
    """
    Check if a service is running on the REST server
    """
    r = salt.utils.http.query(
        DETAILS["url"] + "service/status/" + name, decode_type="json", decode=True
    )
    return r["dict"]


def package_list():
    """
    List "packages" installed on the REST server
    """
    r = salt.utils.http.query(
        DETAILS["url"] + "package/list", decode_type="json", decode=True
    )
    return r["dict"]


def package_install(name, **kwargs):
    """
    Install a "package" on the REST server
    """
    cmd = DETAILS["url"] + "package/install/" + name
    if kwargs.get("version", False):
        cmd += "/" + kwargs["version"]
    else:
        cmd += "/1.0"
    r = salt.utils.http.query(cmd, decode_type="json", decode=True)
    return r["dict"]


def fix_outage():
    r = salt.utils.http.query(DETAILS["url"] + "fix_outage")
    return r


def uptodate(name):
    """
    Call the REST endpoint to see if the packages on the "server" are up to date.
    """
    r = salt.utils.http.query(
        DETAILS["url"] + "package/remove/" + name, decode_type="json", decode=True
    )
    return r["dict"]


def package_remove(name):
    """
    Remove a "package" on the REST server
    """
    r = salt.utils.http.query(
        DETAILS["url"] + "package/remove/" + name, decode_type="json", decode=True
    )
    return r["dict"]


def package_status(name):
    """
    Check the installation status of a package on the REST server
    """
    r = salt.utils.http.query(
        DETAILS["url"] + "package/status/" + name, decode_type="json", decode=True
    )
    return r["dict"]


def ping():
    """
    Is the REST server up?
    """
    r = salt.utils.http.query(DETAILS["url"] + "ping", decode_type="json", decode=True)
    try:
        return r["dict"].get("ret", False)
    except Exception:
        return False


def shutdown(opts):
    """
    For this proxy shutdown is a no-op
    """
    log.debug("rest_sample proxy shutdown() called...")

Grains are data about minions. Most proxied devices will have a paltry amount of data as compared to a typical Linux server. By default, a proxy minion will have several grains taken from the host. Salt core code requires values for kernel, os, and os_family--all of these are forced to be proxy for proxy-minions.

To add others to your proxy minion for a particular device, create a file in salt/grains named [proxytype].py and place inside it the different functions that need to be run to collect the data you are interested in. Here's an example. Note the function below called proxy_functions. It demonstrates how a grains function can take a single argument, which will be set to the value of __proxy__. Dunder variables are not yet injected into Salt processes at the time grains are loaded, so this enables us to get a handle to the proxymodule so we can cross-call the functions therein used to communicate with the controlled device.

Note that as of 2016.3, grains values can also be calculated in a function called grains() in the proxymodule itself. This might be useful if a proxymodule author wants to keep all the code for the proxy interface in the same place instead of splitting it between the proxy and grains directories.

This function will only be called automatically if the configuration variable proxy_merge_grains_in_module is set to True in the proxy configuration file (default /etc/salt/proxy). This variable defaults to True in the release code-named 2017.7.0.

Connection Setup¶

The init() method is responsible for connection setup. It uses the host, username and password config variables defined in the pillar data. The prompt kwarg can be passed to SSHConnection if your SSH server's prompt differs from the example's prompt (Cmd). Instantiating the SSHConnection class establishes an SSH connection to the ssh server (using Salt VT).

Command execution¶

The package_* methods use the SSH connection (established in init()) to send commands out to the SSH server. The sendline() method of SSHConnection class can be used to send commands out to the server. In the above example we send commands like pkg_list or pkg_install. You can send any SSH command via this utility.

Output parsing¶

Output returned by sendline() is a tuple of strings representing the stdout and the stderr respectively. In the toy example shown we simply scrape the output and convert it to a python dictionary, as shown in the parse method. You can tailor this method to match your parsing logic.

Connection teardown¶

The shutdown method is responsible for calling the close_connection() method of SSHConnection class. This ends the SSH connection to the server.

For more information please refer to class SSHConnection.