ansible.windows.win_share module – Manage Windows shares

Note

This module is part of the ansible.windows collection (version 2.5.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install ansible.windows. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: ansible.windows.win_share.

Synopsis
Requirements
Parameters
Examples
Return Values

Synopsis

Add, modify or remove Windows share and set share permissions.

The below requirements are needed on the host that executes this module.

As this module used newer cmdlets like New-SmbShare this can only run on Windows 8 / Windows 2012 or newer.
This is due to the reliance on the WMI provider MSFT_SmbShare https://msdn.microsoft.com/en-us/library/hh830471 which was only added with these Windows releases.

Parameters

Parameter	Comments
caching_mode string	Set the CachingMode for this share. Choices: `"BranchCache"` `"Documents"` `"Manual"` ← (default) `"None"` `"Programs"` `"Unknown"`
change string	Specify user list that should get read and write access on share, separated by comma.
deny string	Specify user list that should get no access, regardless of implied access on share, separated by comma.
description string	Share description.
encrypt boolean	Sets whether to encrypt the traffic to the share or not. Choices: `false` ← (default) `true`
full string	Specify user list that should get full access on share, separated by comma.
list boolean	Specify whether to allow or deny file listing, in case user has no permission on share. Also known as Access-Based Enumeration. Choices: `false` ← (default) `true`
name string / required	Share name.
path path / required	Share directory.
read string	Specify user list that should get read access on share, separated by comma.
rule_action string	Whether to add or set (replace) access control entries. Choices: `"set"` ← (default) `"add"`
scope_name string added in ansible.windows 2.2.0	Specifies the scope name of the share. For use with Windows Server failover cluster file server resources. When defined, path must be located on a cluster shared volume/disk.
state string	Specify whether to add `present` or remove `absent` the specified share. Choices: `"absent"` `"present"` ← (default)

Examples

- name: Add secret share
  ansible.windows.win_share:
    name: internal
    description: top secret share
    path: C:\shares\internal
    list: false
    full: Administrators,CEO
    read: HR-Global
    deny: HR-External

- name: Add public company share
  ansible.windows.win_share:
    name: company
    description: top secret share
    path: C:\shares\company
    list: true
    full: Administrators,CEO
    read: Global

- name: Add failover cluster role share
  ansible.windows.win_share:
    name: backups
    scope_name: FCMSSQL01
    description: SQL Backups
    path: E:\sqlbackup
    list: true
    full: svc.mssql
    read: Global

- name: Remove previously added share
  ansible.windows.win_share:
    name: internal
    state: absent

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
actions list / elements=string	A list of action cmdlets that were run by the module. Returned: success Sample: `["New-SmbShare -Name share -Path C:\\temp"]`

Authors

Hans-Joachim Kliemeck (@h0nIg)
David Baumann (@daBONDi)
Shachaf Goldstein (@Shachaf92)
Joe Zollo (@zollo)

Collection links

© 2012–2018 Michael DeHaan
© 2018–2024 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/ansible/windows/win_share_module.html