Documentation

win_mapped_drive - Map network drives for users

New in version 2.4.

Synopsis

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

Parameters

Parameter Choices/Defaults Comments
letter
required
The letter of the network path to map to.
This letter must not already be in use with Windows.
password
The password for username.
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
    Choices:
  • absent
  • present ←
If present will ensure the mapped drive exists.
If absent will ensure the mapped drive does not exist.
username
Credentials to map the drive with.
The username MUST include the domain or servername like SERVER\user, see the example for more information.

Notes

Note

  • This can only map a network drive for the current executing user and does not allow you to set a default drive for all users of a system. Use other Microsoft tools like GPOs to achieve this goal.
  • 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.

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 local credentials
  win_mapped_drive:
    letter: M
    path: \\SERVER\c$
    username: SERVER\Administrator
    password: Password

- name: Create mapped drive with domain credentials
  win_mapped_drive:
    letter: M
    path: \\domain\appdata\it
    username: DOMAIN\IT
    password: Password

Status

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

Maintenance

This module is flagged as community which means that it is maintained by the Ansible Community. See Module Maintenance & Support for more info.

For a list of other modules that are also maintained by the Ansible Community, see here.

Author

  • Jordan Borean (@jborean93)

Hint

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