NOTE: This page is no longer being updated. To install the latest version of DSC Resource Kit, please use the PowerShell Gallery. If you need to report issues or would like to contribute to development, check out our GitHub Repositories.

Introduction

The xSmbShare module is a part of the Windows PowerShell Desired State Configuration (DSC) Resource Kit, which is a collection of DSC Resources produced by the PowerShell Team. This module contains the xSmbShare resource. This DSC Resource allows you to set up and configure a SMB Share.

All of the resources in the DSC Resource Kit are provided AS IS, and are not supported through any Microsoft standard support program or service. The ""x" in xSmbShare stands for experimental, which means that these resources will be fix forward and monitored by the module owner(s).

Please leave comments, feature requests, and bug reports in the Q & A tab for this module.

If you would like to modify xSmbShare module, feel free. When modifying, please update the module name, resource friendly name, and MOF class name (instructions below). As specified in the license, you may copy or modify this resource as long as they are used on the Windows Platform.

For more information about Windows PowerShell Desired State Configuration, check out the blog posts on the PowerShell Blog (this is a good starting point). There are also great community resources, such as PowerShell.org, or PowerShell Magazine. For more information on the DSC Resource Kit, check out this blog post.

Installation

To install xSmbShare module

  • Unzip the content under $env:ProgramFiles\WindowsPowerShell\Modules folder

To confirm installation:

  • Run Get-DSCResource to see that xSmbShare is among the DSC Resources listed

Requirements

This module requires the latest version of PowerShell (v4.0, which ships in Windows 8.1 or Windows Server 2012R2). To easily use PowerShell 4.0 on older operating systems, install WMF 4.0. Please read the installation instructions that are present on both the download page and the release notes for WMF 4.0.

Description

The xSmbShare module contains the xSmbShare DSC Resource. This DSC Resource allows you to create or modify a share, including access rights.

Details

xSmbShare resource has following properties:

  • Name:                                     Name of the SMB Share
  • Path:                                        Path to the share
  • Description:                            Description of the share
  • ChangeAccess:                      Specifies which user will be granted modify permission to access the share
  • ConcurrentUserLimit:          Specifies the maximum number of concurrently connected users that the new SMB share may accommodate. If this parameter is set to zero (0), then the number of users is unlimited. The default value is zero (0).
  •  EncryptData:                          Indicates that the share is encrypted.
  • FolderEnumerationMode Specifies which files and folders in the new SMB share are visible to users.
  • FullAccess:                             Specifies which accounts are granted full permission to access the share.
  • NoAccess:                              Specifies which accounts are denied access to the share.
  •  ReadAccess:                          Specifies which user is granted read permission to access the share.
  • Ensure:                                    Specifies if the share should be added or removed
  • ShareState:                             Specfies the state of the share
  • ShareType:                             Specfies the type of the share
  •  ShadowCopy:                        Specifies if this share is a ShadowCopy
  • Special:                                   Specifies if this share is a Special Share. Admin share, default shares, IPC$ share are examples.

Renaming Requirements

When making changes to these resources, we suggest the following practice:

  1. Update the following names by replacing MSFT with your company/community name and replacing the "x" with "c" (short for "Community") or another prefix of your choice:
    • Module name (ex: xSmbShare becomes cSmbShare)
    • Resource folder (ex: MSFT_xSmbShare becomes Contoso_cSmbShare)
    • Resource Name (ex: MSFT_xSmbShare becomes Contoso_cSmbShare)
    • Resource Friendly Name (ex: xSmbShare becomes cSmbShare)
    • MOF class name (ex: MSFT_xSmbShare becomes Contoso_cSmbShare)
    • Filename for the <resource>.schema.mof (ex: MSFT_xSmbShare.schema.mof becomes Contoso_cSmbShare.schema.mof)
  2. Update module and metadata information in the module manifest
  3. Update any configuration that use these resources

We reserve resource and module names without prefixes ("x" or "c") for future use (e.g. "MSFT_**RealResourceName**" or "**RealResourceName**"). If the next version of Windows Server ships with a "**RealResourceName**" resource, we don't want to break any configurations that use any community modifications. Please keep a prefix such as "c" on all community modifications.

Versions

1.0.0.0

  • Initial release with the following resources
    • xSmbShare

Example: Ensure the a Smb Share exists

This configuration ensures that there is a share with the description of"This is a test SMB Share".
PowerShell
Edit|Remove
Configuration ChangeDescriptionConfig 
{ 
    Import-DscResource -Name MSFT_xSmbShare 
   # A Configuration block can have zero or more Node blocks 
   Node localhost 
   { 
      xSmbShare MySMBShare 
      { 
          Ensure = "Present"  
          Name   = "SMBShare1" 
          Path = "C:\Users\Duser1\Desktop"   
          Description = "This is a test SMB Share"           
      } 
   } 
}  
 
ChangeDescriptionConfig

Example: Ensure Description and Permissions for a share

This configuration ensures that the description and permissions for a share are as specified.
PowerShell
Edit|Remove
Configuration ChangeDescriptionAndPermissionsConfig 
{ 
    Import-DscResource -Name MSFT_xSmbShare 
   # A Configuration block can have zero or more Node blocks 
   Node localhost 
   { 
        # Next, specify one or more resource blocks 
 
      xSmbShare MySMBShare 
      { 
          Ensure = "Present"  
          Name   = "SMBShare1" 
          Path = "C:\Users\Duser1\Desktop"   
          ReadAccess = "User1" 
          NoAccess = @("User3""User4") 
          Description = "This is an updated description for this share" 
      } 
   } 
}  
 
ChangeDescriptionAndPermissionsConfig

Example: Remove the Share

This example ensures that the Smb Share used in the previous examples does not exist.
PowerShell
Edit|Remove
Configuration RemoveSmbShareConfig 
{ 
    Import-DscResource -Name MSFT_xSmbShare 
   # A Configuration block can have zero or more Node blocks 
   Node localhost 
   { 
        # Next, specify one or more resource blocks 
 
      xSmbShare MySMBShare 
      { 
          Ensure = "Absent"  
          Name   = "SMBShare1" 
          Path = "C:\Users\Duser1\Desktop"           
      } 
   } 
}  
 
RemoveSmbShareConfig