docs: def get_ssh_config(name, network_mask='', get_private_key=False):
      r'''
      Retrieve hints of how you might connect to a Vagrant VM.
  
      :param name: the salt_id of the machine
      :param network_mask: a CIDR mask to search for the VM's address
      :param get_private_key: (default: False) return the key used for ssh login
      :return: a dict of ssh login information for the VM
  
      CLI Example:
  
      .. code-block:: bash
  
          salt <host> vagrant.get_ssh_config <salt_id>
          salt my_laptop vagrant.get_ssh_config quail1 network_mask=10.0.0.0/8 get_private_key=True
  
      The returned dictionary contains:
  
      - key_filename:  the name of the private key file on the VM host computer
      - ssh_username:  the username to be used to log in to the VM
      - ssh_host:  the IP address used to log in to the VM.  (This will usually be `127.0.0.1`)
      - ssh_port:  the TCP port used to log in to the VM.  (This will often be `2222`)
      - \[ip_address:\]  (if `network_mask` is defined. see below)
      - \[private_key:\]  (if `get_private_key` is True) the private key for ssh_username
  
      About `network_mask`:
  
      Vagrant usually uses a redirected TCP port on its host computer to log in to a VM using ssh.
      This redirected port and its IP address are "ssh_port" and "ssh_host".  The ssh_host is
      usually the localhost (127.0.0.1).
      This makes it impossible for a third machine (such as a salt-cloud master) to contact the VM
      unless the VM has another network interface defined.  You will usually want a bridged network
      defined by having a `config.vm.network "public_network"` statement in your `Vagrantfile`.
  
      The IP address of the bridged adapter will typically be assigned by DHCP and unknown to you,
      but you should be able to determine what IP network the address will be chosen from.
      If you enter a CIDR network mask, Salt will attempt to find the VM's address for you.
      The host machine will send an "ifconfig" command to the VM (using ssh to `ssh_host`:`ssh_port`)
      and return the IP address of the first interface it can find which matches your mask.
      '''
      vm_ = get_vm_info(name)
  
      ssh_config = _vagrant_ssh_config(vm_)
  
      try:
          ans = {'key_filename': ssh_config['IdentityFile'],
                 'ssh_username': ssh_config['User'],
                 'ssh_host': ssh_config['HostName'],
                 'ssh_port': ssh_config['Port'],
                 }
  
      except KeyError:
          raise CommandExecutionError(
              'Insufficient SSH information to contact VM {}. '
              'Is it running?'.format(vm_.get('machine', '(default)')))
  
      if network_mask:
          #  ask the new VM to report its network address
          command = 'ssh -i {IdentityFile} -p {Port} ' \
                    '-oStrictHostKeyChecking={StrictHostKeyChecking} ' \
                    '-oUserKnownHostsFile={UserKnownHostsFile} ' \
                    '-oControlPath=none ' \
                    '{User}@{HostName} ifconfig'.format(**ssh_config)
  
          log.info(
              'Trying ssh -p %s %s@%s ifconfig',
              ssh_config['Port'], ssh_config['User'], ssh_config['HostName']
          )
          reply = __salt__['cmd.shell'](command)
          log.info('--->\n%s', reply)
          target_network_range = ipaddress.ip_network(network_mask, strict=False)
  
          for line in reply.split('\n'):
              try:  # try to find a bridged network address
                  # the lines we are looking for appear like:
                  #    "inet addr:10.124.31.185  Bcast:10.124.31.255  Mask:255.255.248.0"
                  # or "inet6 addr: fe80::a00:27ff:fe04:7aac/64 Scope:Link"
                  tokens = line.replace('addr:', '', 1).split()  # remove "addr:" if it exists, then split
                  found_address = None
                  if "inet" in tokens:
                      nxt = tokens.index("inet") + 1
                      found_address = ipaddress.ip_address(tokens[nxt])
                  elif "inet6" in tokens:
                      nxt = tokens.index("inet6") + 1
                      found_address = ipaddress.ip_address(tokens[nxt].split('/')[0])
                  if found_address in target_network_range:
                      ans['ip_address'] = six.text_type(found_address)
                      break  # we have located a good matching address
              except (IndexError, AttributeError, TypeError):
                  pass  # all syntax and type errors loop here
                  # falling out if the loop leaves us remembering the last candidate
          log.info('Network IP address in %s detected as: %s',
                   target_network_range, ans.get('ip_address', '(not found)'))
  
      if get_private_key:
          # retrieve the Vagrant private key from the host
          try:
              with salt.utils.files.fopen(ssh_config['IdentityFile']) as pks:
                  ans['private_key'] = salt.utils.stringutils.to_unicode(pks.read())
          except (OSError, IOError) as e:
              raise CommandExecutionError("Error processing Vagrant private key file: {}".format(e))
      return ans