win_mapped_drive – Map network drives for users — Ansible Documentation

- AnsibleFest
- Products
- Community
- Webinars & Training
- Blog

Documentation

# win_mapped_drive – Map network drives for users

New in version 2.4.

- Synopsis
- Parameters
- Notes
- See Also
- Examples
- Status

## Synopsis

- Allows you to modify mapped network drives for individual users.

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
letter string / required |  | The letter of the network path to map to. This letter must not already be in use with Windows.
password string |  | The password for `username` that is used when testing the initial connection. This is never saved with a mapped drive, use the win_credential module to persist a username and password for a host.
path path |  | The UNC path to map the drive to. This is required if `state=present`. If `state=absent` and path is not set, the module will delete the mapped drive regardless of the target. If `state=absent` and the path is set, the module will throw an error if path does not match the target of the mapped drive.
state string | Choices: absent present ← | If `present` will ensure the mapped drive exists. If `absent` will ensure the mapped drive does not exist.
username string |  | The username that is used when testing the initial connection. This is never saved with a mapped drive, the the win_credential module to persist a username and password for a host. This is required if the mapped drive requires authentication with custom credentials and become, or CredSSP cannot be used. If become or CredSSP is used, any credentials saved with win_credential will automatically be used instead.

## Notes

Note

- You cannot use this module to access a mapped drive in another Ansible task, drives mapped with this module are only accessible when logging in interactively with the user through the console or RDP.
- It is recommend to run this module with become or CredSSP when the remote path requires authentication.
- When using become or CredSSP, the task will have access to any local credentials stored in the user’s vault.
- If become or CredSSP is not available, the username and password options can be used for the initial authentication but these are not persisted.

## See Also

See also

win_credential – Manages Windows Credentials in the Credential Manager
  The official documentation on the win_credential module.

## Examples

    - name: Create a mapped drive under Z
      win_mapped_drive:
        letter: Z
        path: \\domain\appdata\accounting

    - name: Delete any mapped drives under Z
      win_mapped_drive:
        letter: Z
        state: absent

    - name: Only delete the mapped drive Z if the paths match (error is thrown otherwise)
      win_mapped_drive:
        letter: Z
        path: \\domain\appdata\accounting
        state: absent

    - name: Create mapped drive with credentials and save the username and password
      block:
      - name: Save the network credentials required for the mapped drive
        win_credential:
          name: server
          type: domain_password
          username: username@DOMAIN
          secret: Password01
          state: present

      - name: Create a mapped drive that requires authentication
        win_mapped_drive:
          letter: M
          path: \\SERVER\C$
          state: present
      vars:
        # become is required to save and retrieve the credentials in the tasks
        ansible_become: yes
        ansible_become_method: runas
        ansible_become_user: '{{ ansible_user }}'
        ansible_become_pass: '{{ ansible_password }}'

    - name: Create mapped drive with credentials that do not persist on the next logon
      win_mapped_drive:
        letter: M
        path: \\SERVER\C$
        state: present
        username: '{{ ansible_user }}'
        password: '{{ ansible_password }}'

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]

### Authors

- Jordan Borean (@jborean93)

Hint

If you notice any issues in this documentation you can edit this document to improve it.