ansible.windows.win_share module – Manage Windows shares

Note

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

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.

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

Synopsis

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

Requirements

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:

  • no ← (default)

  • yes

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:

  • no ← (default)

  • yes

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

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: no
    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: yes
    full: Administrators,CEO
    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)