Initialize a new Vagrant VM.

    This inputs all the information needed to start a Vagrant VM.  These settings are stored in
    a Salt sdb database on the Vagrant host minion and used to start, control, and query the
    guest VMs. The salt_id assigned here is the key field for that database and must be unique.

    :param name: The salt_id name you will use to control this VM
    :param cwd: The path to the directory where the Vagrantfile is located
    :param machine: The machine name in the Vagrantfile. If blank, the primary machine will be used.
    :param runas: The username on the host who owns the Vagrant work files.
    :param start: (default: False) Start the virtual machine now.
    :param vagrant_provider: The name of a Vagrant VM provider (if not the default).
    :param vm: Optionally, all the above information may be supplied in this dictionary.
    :return: A string indicating success, or False.

    CLI Example:

    .. code-block:: bash

        salt <host> vagrant.init <salt_id> /path/to/Vagrantfile
        salt my_laptop vagrant.init x1 /projects/bevy_master machine=quail1

def init(name,  # Salt_id for created VM
         cwd=None,  # path to find Vagrantfile
         machine='',  # name of machine in Vagrantfile
         runas=None,  # username who owns Vagrant box
         start=False,  # start the machine when initialized
         vagrant_provider='',  # vagrant provider (default=virtualbox)
         vm=None,  # a dictionary of VM configuration settings
         ):
    '''
    Initialize a new Vagrant VM.

    This inputs all the information needed to start a Vagrant VM.  These settings are stored in
    a Salt sdb database on the Vagrant host minion and used to start, control, and query the
    guest VMs. The salt_id assigned here is the key field for that database and must be unique.

    :param name: The salt_id name you will use to control this VM
    :param cwd: The path to the directory where the Vagrantfile is located
    :param machine: The machine name in the Vagrantfile. If blank, the primary machine will be used.
    :param runas: The username on the host who owns the Vagrant work files.
    :param start: (default: False) Start the virtual machine now.
    :param vagrant_provider: The name of a Vagrant VM provider (if not the default).
    :param vm: Optionally, all the above information may be supplied in this dictionary.
    :return: A string indicating success, or False.

    CLI Example:

    .. code-block:: bash

        salt <host> vagrant.init <salt_id> /path/to/Vagrantfile
        salt my_laptop vagrant.init x1 /projects/bevy_master machine=quail1
    '''
    vm_ = {} if vm is None else vm.copy()  # passed configuration data
    vm_['name'] = name
    # passed-in keyword arguments overwrite vm dictionary values
    vm_['cwd'] = cwd or vm_.get('cwd')
    if not vm_['cwd']:
        raise SaltInvocationError('Path to Vagrantfile must be defined by "cwd" argument')
    vm_['machine'] = machine or vm_.get('machine', machine)
    vm_['runas'] = runas or vm_.get('runas', runas)
    vm_['vagrant_provider'] = vagrant_provider or vm_.get('vagrant_provider', '')
    _update_vm_info(name, vm_)

    if start:
        log.debug('Starting VM %s', name)
        ret = _start(name, vm_)
    else:
        ret = 'Name {} defined using VM {}'.format(name, vm_['machine'] or '(default)')
    return ret