r'''
    Defines and starts a new VM with specified arguments, or restart a
    VM (or group of VMs). (Runs ``vagrant up``.)

    :param name: the Salt_id node name you wish your VM to have.

    If ``name`` contains a "?" or "*"  then it will re-start a group of VMs
    which have been paused or stopped.

    Each machine must be initially started individually using this function
    or the vagrant.init execution module call.

    \[NOTE:\] Keyword arguments are silently ignored when re-starting an existing VM.

    Possible keyword arguments:

    - cwd: The directory (path) containing the Vagrantfile
    - machine: ('') the name of the machine (in the Vagrantfile) if not default
    - vagrant_runas: ('root') the username who owns the vagrantbox file
    - vagrant_provider: the provider to run the VM (usually 'virtualbox')
    - vm: ({}) a dictionary containing these or other keyword arguments

    .. code-block:: yaml

        node_name:
          vagrant.running

    .. code-block:: yaml

        node_name:
          vagrant.running:
            - cwd: /projects/my_project
            - vagrant_runas: my_username
            - machine: machine1

def running(name, **kwargs):
    r'''
    Defines and starts a new VM with specified arguments, or restart a
    VM (or group of VMs). (Runs ``vagrant up``.)

    :param name: the Salt_id node name you wish your VM to have.

    If ``name`` contains a "?" or "*"  then it will re-start a group of VMs
    which have been paused or stopped.

    Each machine must be initially started individually using this function
    or the vagrant.init execution module call.

    \[NOTE:\] Keyword arguments are silently ignored when re-starting an existing VM.

    Possible keyword arguments:

    - cwd: The directory (path) containing the Vagrantfile
    - machine: ('') the name of the machine (in the Vagrantfile) if not default
    - vagrant_runas: ('root') the username who owns the vagrantbox file
    - vagrant_provider: the provider to run the VM (usually 'virtualbox')
    - vm: ({}) a dictionary containing these or other keyword arguments

    .. code-block:: yaml

        node_name:
          vagrant.running

    .. code-block:: yaml

        node_name:
          vagrant.running:
            - cwd: /projects/my_project
            - vagrant_runas: my_username
            - machine: machine1

    '''
    if '*' in name or '?' in name:

        return _vagrant_call(name, 'start', 'restarted',
                             "Machine has been restarted", "running")

    else:

        ret = {'name': name,
               'changes': {},
               'result': True,
               'comment': '{0} is already running'.format(name)
               }

        try:
            info = __salt__['vagrant.vm_state'](name)
            if info[0]['state'] != 'running':
                __salt__['vagrant.start'](name)
                ret['changes'][name] = 'Machine started'
                ret['comment'] = 'Node {0} started'.format(name)
        except (SaltInvocationError, CommandExecutionError):
            #  there was no viable existing machine to start
            ret, kwargs = _find_init_change(name, ret, **kwargs)
            kwargs['start'] = True
            __salt__['vagrant.init'](name, **kwargs)
            ret['changes'][name] = 'Node defined and started'
            ret['comment'] = 'Node {0} defined and started'.format(name)

        return ret