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

  • 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:

  • 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)