Edit

Setting up a DSC SMB pull server

  • Article

Applies To: Windows PowerShell 4.0, Windows PowerShell 5.0

Important

The Pull Server (Windows Feature DSC-Service) is a supported component of Windows Server however there are no plans to offer new features or capabilities. we would like you to know that a newer version of DSC is now generally available, managed by a feature of Azure Policy named guest configuration. The guest configuration service combines features of DSC Extension, Azure Automation State Configuration, and the most commonly requested features from customer feedback. Guest configuration also includes hybrid machine support through Arc-enabled servers.

A DSC SMB pull server is a computer hosting SMB file shares that make DSC configuration files and DSC resources available to target nodes when those nodes ask for them.

To use an SMB pull server for DSC, you have to:

  • Set up an SMB file share on a server running PowerShell 4.0 or higher
  • Configure a client running PowerShell 4.0 or higher to pull from that SMB share

Using the xSmbShare resource to create an SMB file share

There are a number of ways to set up an SMB file share, but let's look at how you can do this by using DSC.

Install the xSmbShare resource

Call the Install-Module cmdlet to install the xSmbShare module.

Note

Install-Module is included in the PowerShellGet module, which is included in PowerShell 5.0. The xSmbShare contains the DSC resource xSmbShare, which can be used to create an SMB file share.

Create the directory and file share

The following configuration uses the File resource to create the directory for the share and the xSmbShare resource to set up the SMB share:

Configuration SmbShare
{
    Import-DscResource -ModuleName PSDesiredStateConfiguration
    Import-DscResource -ModuleName xSmbShare

    Node localhost
    {

        File CreateFolder
        {
            DestinationPath = 'C:\DscSmbShare'
            Type = 'Directory'
            Ensure = 'Present'
        }

        xSMBShare CreateShare
        {
            Name = 'DscSmbShare'
            Path = 'C:\DscSmbShare'
            FullAccess = 'administrator'
            ReadAccess = 'myDomain\Contoso-Server$'
            FolderEnumerationMode = 'AccessBased'
            Ensure = 'Present'
            DependsOn = '[File]CreateFolder'
        }
    }
}

The configuration creates the directory C:\DscSmbShare, if it doesn't already exist, and then uses that directory as an SMB file share. FullAccess should be given to any account that needs to write to or delete from the file share. ReadAccess must be given to any client nodes that get configurations and/or DSC resources from the share.

Note

DSC runs as the system account by default, so the computer itself must have access to the share.

Give file system access to the pull client

Giving ReadAccess to a client node allows that node to access the SMB share, but not to files or folders within that share. You have to explicitly grant client nodes access to the SMB share folder and subfolders. We can do this with DSC by adding using the cNtfsPermissionEntry resource, which is contained in the CNtfsAccessControl module. The following configuration adds a cNtfsPermissionEntry block that grants ReadAndExecute access to the pull client:

Configuration DSCSMB
{
    Import-DscResource -ModuleName PSDesiredStateConfiguration
    Import-DscResource -ModuleName xSmbShare
    Import-DscResource -ModuleName cNtfsAccessControl

    Node localhost
    {

        File CreateFolder
        {
            DestinationPath = 'C:\DscSmbShare'
            Type = 'Directory'
            Ensure = 'Present'
        }

        xSMBShare CreateShare
        {
            Name = 'DscSmbShare'
            Path = 'C:\DscSmbShare'
            FullAccess = 'administrator'
            ReadAccess = 'myDomain\Contoso-Server$'
            FolderEnumerationMode = 'AccessBased'
            Ensure = 'Present'
            DependsOn = '[File]CreateFolder'
        }

        cNtfsPermissionEntry PermissionSet1
        {
            Ensure = 'Present'
            Path = 'C:\DscSmbShare'
            Principal = 'myDomain\Contoso-Server$'
            AccessControlInformation = @(
                cNtfsAccessControlInformation
                {
                    AccessControlType = 'Allow'
                    FileSystemRights = 'ReadAndExecute'
                    Inheritance = 'ThisFolderSubfoldersAndFiles'
                    NoPropagateInherit = $false
                }
            )
            DependsOn = '[File]CreateFolder'
        }
    }
}

Placing configurations and resources

Save any configuration MOF files and/or DSC resources that you want client nodes to pull in the SMB share folder.

Any configuration MOF file must be named <ConfigurationID>.mof, where <ConfigurationID> is the value of the ConfigurationID property of the target node's LCM. For more information about setting up pull clients, see Setting up a pull client using configuration ID.

Note

You must use configuration IDs if you are using an SMB pull server. Configuration names are not supported for SMB.

Each resource module needs to be zipped and named according to the following pattern {Module Name}_{Module Version}.zip. For example, a module named xWebAdminstration with a module version of 3.1.2.0 would be named xWebAdministration_3.2.1.0.zip. Each version of a module must be contained in a single zip file. Separate versions of a module in a zip file are not supported. Before packaging up DSC resource modules for use with pull server, you need to make a small change to the directory structure.

The default format of modules containing DSC resource in WMF 5.0 is {Module Folder}\{Module Version}\DscResources\{DSC Resource Folder}\.

Before packaging up for the pull server simply remove the {Module version} folder so the path becomes {Module Folder}\DscResources\{DSC Resource Folder}\. With this change, zip the folder as described above and place these zip files in the SMB share folder.

Creating the MOF checksum

A configuration MOF file needs to be paired with a checksum file so that an LCM on a target node can validate the configuration. To create a checksum, call the New-DSCCheckSum cmdlet. The cmdlet takes a Path parameter that specifies the folder where the configuration MOF is located. The cmdlet creates a checksum file named ConfigurationMOFName.mof.checksum, where ConfigurationMOFName is the name of the configuration mof file. If there are more than one configuration MOF files in the specified folder, a checksum is created for each configuration in the folder.

The checksum file must be present in the same directory as the configuration MOF file ($env:PROGRAMFILES\WindowsPowerShell\DscService\Configuration by default), and have the same name with the .checksum extension appended.

Note

If you change the configuration MOF file in any way, you must also recreate the checksum file.

Setting up a pull client for SMB

To set up a client that pulls configurations and/or resources from an SMB share, you configure the client's Local Configuration Manager (LCM) with ConfigurationRepositoryShare and ResourceRepositoryShare blocks that specify the share from which to pull configurations and DSC resources.

For more information about configuring the LCM, see Setting up a pull client using configuration ID.

Note

For simplicity, this example uses the PSDscAllowPlainTextPassword to allow passing a plaintext password to the Credential parameter. For information about passing credentials more securely, see Credentials Options in Configuration Data. You MUST specify a ConfigurationID in the Settings block of a metaconfiguration for an SMB pull server, even if you are only pulling resources.

$secpasswd = ConvertTo-SecureString "Pass1Word" -AsPlainText -Force
$mycreds = New-Object System.Management.Automation.PSCredential ("TestUser", $secpasswd)

[DSCLocalConfigurationManager()]
configuration SmbCredTest
{
    Node $AllNodes.NodeName
    {
        Settings
        {
            RefreshMode = 'Pull'
            RefreshFrequencyMins = 30
            RebootNodeIfNeeded = $true
            ConfigurationID    = '16db7357-9083-4806-a80c-ebbaf4acd6c1'
        }

         ConfigurationRepositoryShare SmbConfigShare
        {
            SourcePath = '\\WIN-E0TRU6U11B1\DscSmbShare'
            Credential = $mycreds
        }

        ResourceRepositoryShare SmbResourceShare
        {
            SourcePath = '\\WIN-E0TRU6U11B1\DscSmbShare'
            Credential = $mycreds

        }
    }
}

$ConfigurationData = @{
    AllNodes = @(
        @{
            #the "*" means "all nodes named in ConfigData" so we don't have to repeat ourselves
            NodeName="localhost"
            PSDscAllowPlainTextPassword = $true
        })
}

Acknowledgements

Special thanks to the following individuals:

  • Mike F. Robbins, whose posts on using SMB for DSC helped inform the content in this topic. His blog is at Mike F Robbins.
  • Serge Nikalaichyk, who authored the cNtfsAccessControl module. The source for this module is at cNtfsAccessControl.

See also

Windows PowerShell Desired State Configuration Overview

Enacting configurations

Setting up a pull client using configuration ID