1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
|
#!/usr/bin/python
# -*- coding: utf-8 -*-
# Copyright: (c) 2017, Ansible Project
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
# this is a windows documentation stub, actual code lives in the .ps1
# file of the same name
ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['preview'],
'supported_by': 'community'}
DOCUMENTATION = r'''
---
module: win_mapped_drive
version_added: '2.4'
short_description: Map network drives for users
description:
- Allows you to modify mapped network drives for individual users.
- Also support WebDAV endpoints in the UNC form.
options:
letter:
description:
- The letter of the network path to map to.
- This letter must not already be in use with Windows.
type: str
required: yes
password:
description:
- The password for C(username) that is used when testing the initial
connection.
- This is never saved with a mapped drive, use the M(win_credential) module
to persist a username and password for a host.
type: str
path:
description:
- 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 C(\\hostname\path) and not a URL, see examples for more details.
- To specify a C(https) WebDAV path, add C(@SSL) after the hostname. To
specify a custom WebDAV port add C(@<port num>) after the C(@SSL) or
hostname portion of the UNC path, e.g. C(\\server@SSL@1234) or
C(\\server@1234).
- This is required if C(state=present).
- If C(state=absent) and I(path) is not set, the module will delete the
mapped drive regardless of the target.
- If C(state=absent) and the I(path) is set, the module will throw an error
if path does not match the target of the mapped drive.
type: path
state:
description:
- If C(present) will ensure the mapped drive exists.
- If C(absent) will ensure the mapped drive does not exist.
type: str
choices: [ absent, present ]
default: present
username:
description:
- The username that is used when testing the initial connection.
- This is never saved with a mapped drive, the M(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
M(win_credential) will automatically be used instead.
type: str
notes:
- 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 I(username) and I(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 C(WebDAV-Redirector) feature using
M(win_feature).
seealso:
- module: win_credential
author:
- Jordan Borean (@jborean93)
'''
EXAMPLES = r'''
- 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
'''
RETURN = r'''
'''
|
