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
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
|
|
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.
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.8/modules/win_mapped_drive_module.html