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.
- Also support WebDAV endpoints in the UNC form.

## 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. If pointing to a WebDAV location this must still be in a UNC path in the format `\\hostname\path` and not a URL, see examples for more details. To specify a `https` WebDAV path, add `@SSL` after the hostname. To specify a custom WebDAV port add `@<port num>` after the `@SSL` or hostname portion of the UNC path, e.g. `\\server@SSL@1234` or `\\server@1234`. 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.
- WebDAV paths must have the WebDAV client feature installed for this module to map those paths. This is installed by default on desktop Windows editions but Windows Server hosts need to install the `WebDAV-Redirector` feature using win_feature.

## 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 }}'

    # This should only be required for Windows Server OS'
    - name: Ensure WebDAV client feature is installed
      win_feature:
        name: WebDAV-Redirector
        state: present
      register: webdav_feature

    - name: Reboot after installing WebDAV client feature
      win_reboot:
      when: webdav_feature.reboot_required

    - name: Map the HTTPS WebDAV location
      win_mapped_drive:
        letter: W
        path: \\live.sysinternals.com@SSL\tools  # https://live.sysinternals.com/tools
        state: present

## 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.