DSCResources/DSC_SmbShare/DSC_SmbShare.psm1
|
$modulePath = Join-Path -Path (Split-Path -Path (Split-Path -Path $PSScriptRoot -Parent) -Parent) -ChildPath 'Modules' # Import the ComputerManagementDsc Common Modules Import-Module -Name (Join-Path -Path $modulePath ` -ChildPath (Join-Path -Path 'ComputerManagementDsc.Common' ` -ChildPath 'ComputerManagementDsc.Common.psm1')) -Force Import-Module -Name (Join-Path -Path $modulePath -ChildPath 'DscResource.Common') # Import Localization Strings $script:localizedData = Get-LocalizedData -DefaultUICulture 'en-US' <# .SYNOPSIS Returns the current state of the SMB share. .PARAMETER Name Specifies the name of the SMB share. .PARAMETER Path Specifies the path of the SMB share. Not used in Get-TargetResource. #> function Get-TargetResource { [CmdletBinding()] [OutputType([System.Collections.Hashtable])] param ( [Parameter(Mandatory = $true)] [System.String] $Name, [Parameter(Mandatory = $true)] [System.String] $Path ) Write-Verbose -Message ($script:localizedData.GetTargetResourceMessage -f $Name) $returnValue = @{ Ensure = 'Absent' Name = $Name Path = [System.String] $null Description = [System.String] $null ConcurrentUserLimit = 0 EncryptData = $false FolderEnumerationMode = [System.String] $null CachingMode = [System.String] $null ContinuouslyAvailable = $false ShareState = [System.String] $null ShareType = [System.String] $null ShadowCopy = $false Special = $false ScopeName = [System.String] $null } $accountsFullAccess = [system.string[]] @() $accountsChangeAccess = [system.string[]] @() $accountsReadAccess = [system.string[]] @() $accountsNoAccess = [system.string[]] @() $smbShare = Get-SmbShare -Name $Name -ErrorAction 'SilentlyContinue' if ($smbShare) { $returnValue['Ensure'] = 'Present' $returnValue['Name'] = $smbShare.Name $returnValue['Path'] = $smbShare.Path $returnValue['Description'] = $smbShare.Description $returnValue['ConcurrentUserLimit'] = $smbShare.ConcurrentUserLimit $returnValue['EncryptData'] = $smbShare.EncryptData $returnValue['FolderEnumerationMode'] = $smbShare.FolderEnumerationMode.ToString() $returnValue['CachingMode'] = $smbShare.CachingMode.ToString() $returnValue['ContinuouslyAvailable'] = $smbShare.ContinuouslyAvailable $returnValue['ShareState'] = $smbShare.ShareState.ToString() $returnValue['ShareType'] = $smbShare.ShareType.ToString() $returnValue['ShadowCopy'] = $smbShare.ShadowCopy $returnValue['Special'] = $smbShare.Special $returnValue['ScopeName'] = $smbShare.ScopeName $currentSmbShareAccessPermissions = Get-SmbShareAccess -Name $Name foreach ($access in $currentSmbShareAccessPermissions) { switch ($access.AccessRight) { 'Change' { if ($access.AccessControlType -eq 'Allow') { $accountsChangeAccess += @($access.AccountName) } } 'Read' { if ($access.AccessControlType -eq 'Allow') { $accountsReadAccess += @($access.AccountName) } } 'Full' { if ($access.AccessControlType -eq 'Allow') { $accountsFullAccess += @($access.AccountName) } if ($access.AccessControlType -eq 'Deny') { $accountsNoAccess += @($access.AccountName) } } } } } else { Write-Verbose -Message ($script:localizedData.ShareNotFound -f $Name) } <# This adds either an empty array, or a populated array depending if accounts with the respectively access was found. #> $returnValue['FullAccess'] = [System.String[]] $accountsFullAccess $returnValue['ChangeAccess'] = [System.String[]] $accountsChangeAccess $returnValue['ReadAccess'] = [System.String[]] $accountsReadAccess $returnValue['NoAccess'] = [System.String[]] $accountsNoAccess return $returnValue } <# .SYNOPSIS Creates or removes the SMB share. .PARAMETER Name Specifies the name of the SMB share. .PARAMETER Path Specifies the path of the SMB share. .PARAMETER Description Specifies the description of the SMB share. .PARAMETER 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). .PARAMETER EncryptData Indicates that the SMB share is encrypted. .PARAMETER FolderEnumerationMode Specifies which files and folders in the new SMB share are visible to users. { AccessBased | Unrestricted } .PARAMETER CachingMode Specifies the caching mode of the offline files for the SMB share. { 'None' | 'Manual' | 'Programs' | 'Documents' | 'BranchCache' } .PARAMETER ContinuouslyAvailable Specifies whether the SMB share should be continuously available. .PARAMETER FullAccess Specifies which accounts are granted full permission to access the SMB share. .PARAMETER ChangeAccess Specifies which accounts will be granted modify permission to access the SMB share. .PARAMETER ReadAccess Specifies which accounts is granted read permission to access the SMB share. .PARAMETER NoAccess Specifies which accounts are denied access to the SMB share. .PARAMETER Ensure Specifies if the SMB share should be added or removed. .PARAMETER ScopeName Specifies the scope in which the share should be created. .PARAMETER Force Specifies if the SMB share is allowed to be dropped and recreated (required when the path changes). #> function Set-TargetResource { [CmdletBinding()] param ( [Parameter(Mandatory = $true)] [System.String] $Name, [Parameter(Mandatory = $true)] [System.String] $Path, [Parameter()] [System.String] $Description, [Parameter()] [System.UInt32] $ConcurrentUserLimit, [Parameter()] [System.Boolean] $EncryptData, [Parameter()] [ValidateSet('AccessBased', 'Unrestricted')] [System.String] $FolderEnumerationMode, [Parameter()] [ValidateSet('None', 'Manual', 'Programs', 'Documents', 'BranchCache')] [System.String] $CachingMode, [Parameter()] [System.Boolean] $ContinuouslyAvailable, [Parameter()] [System.String[]] $FullAccess, [Parameter()] [System.String[]] $ChangeAccess, [Parameter()] [System.String[]] $ReadAccess, [Parameter()] [System.String[]] $NoAccess, [Parameter()] [ValidateSet('Present', 'Absent')] [System.String] $Ensure = 'Present', [Parameter()] [System.String] $ScopeName = '*', [Parameter()] [System.Boolean] $Force ) Assert-AccessPermissionParameters @PSBoundParameters <# Copy the $PSBoundParameters to a new hash table, so we have the original intact. #> $smbShareParameters = @{} + $PSBoundParameters $currentSmbShareConfiguration = Get-TargetResource -Name $Name -Path $Path if ($currentSmbShareConfiguration.Ensure -eq 'Present') { Write-Verbose -Message ($script:localizedData.IsPresent -f $Name) if ($Ensure -eq 'Present') { if ( ($currentSmbShareConfiguration.Path -ne $Path -or $currentSmbShareConfiguration.ScopeName -ne $ScopeName) -and $Force ) { Write-Verbose -Message ($script:localizedData.RecreateShare -f $Name) try { Remove-SmbShare -Name $Name -Force -ErrorAction Stop New-SmbShare -Name $Name -Path $Path -ErrorAction Stop } catch { Write-Error -Message ($script:localizedData.RecreateShareError -f $Name, $_) } } else { Write-Warning -Message ( $script:localizedData.NoRecreateShare -f $Name, $currentSmbShareConfiguration.Path, $Path ) } Write-Verbose -Message $script:localizedData.UpdatingProperties $parametersToRemove = $smbShareParameters.Keys | Where-Object -FilterScript { $_ -in ('ChangeAccess','ReadAccess','FullAccess','NoAccess','Ensure','Path','Force') } $parametersToRemove | ForEach-Object -Process { $smbShareParameters.Remove($_) } # Use Set-SmbShare for performing operations other than changing access Set-SmbShare @smbShareParameters -Force -ErrorAction 'Stop' $smbShareAccessPermissionParameters = @{ Name = $Name } if ($PSBoundParameters.ContainsKey('FullAccess')) { $smbShareAccessPermissionParameters['FullAccess'] = $FullAccess } if ($PSBoundParameters.ContainsKey('ChangeAccess')) { $smbShareAccessPermissionParameters['ChangeAccess'] = $ChangeAccess } if ($PSBoundParameters.ContainsKey('ReadAccess')) { $smbShareAccessPermissionParameters['ReadAccess'] = $ReadAccess } if ($PSBoundParameters.ContainsKey('NoAccess')) { $smbShareAccessPermissionParameters['NoAccess'] = $NoAccess } # We should only pass the access collections that the user wants to enforce. Remove-SmbShareAccessPermission @smbShareAccessPermissionParameters Add-SmbShareAccessPermission @smbShareAccessPermissionParameters } else { Write-Verbose -Message ($script:localizedData.RemoveShare -f $Name) Remove-SmbShare -name $Name -Force -ErrorAction 'Stop' } } else { if ($Ensure -eq 'Present') { $smbShareParameters.Remove('Ensure') $smbShareParameters.Remove('Force') Write-Verbose -Message ($script:localizedData.CreateShare -f $Name) <# Remove access collections that are empty, since empty collections are not allowed to be provided to the cmdlet New-SmbShare. #> foreach ($accessProperty in ('ChangeAccess','ReadAccess','FullAccess','NoAccess')) { if ($smbShareParameters.ContainsKey($accessProperty) -and -not $smbShareParameters[$accessProperty]) { $smbShareParameters.Remove($accessProperty) } } New-SmbShare @smbShareParameters -ErrorAction 'Stop' } } } <# .SYNOPSIS Determines if the SMB share is in the desired state. .PARAMETER Name Specifies the name of the SMB share. .PARAMETER Path Specifies the path of the SMB share. .PARAMETER Description Specifies the description of the SMB share. .PARAMETER 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). .PARAMETER EncryptData Indicates that the SMB share is encrypted. .PARAMETER FolderEnumerationMode Specifies which files and folders in the new SMB share are visible to users. { AccessBased | Unrestricted } .PARAMETER CachingMode Specifies the caching mode of the offline files for the SMB share. { 'None' | 'Manual' | 'Programs' | 'Documents' | 'BranchCache' } .PARAMETER ContinuouslyAvailable Specifies whether the SMB share should be continuously available. .PARAMETER FullAccess Specifies which accounts are granted full permission to access the SMB share. .PARAMETER ChangeAccess Specifies which accounts will be granted modify permission to access the SMB share. .PARAMETER ReadAccess Specifies which accounts is granted read permission to access the SMB share. .PARAMETER NoAccess Specifies which accounts are denied access to the SMB share. .PARAMETER Ensure Specifies if the SMB share should be added or removed. .PARAMETER ScopeName Specifies the scope in which the share should be created. .PARAMETER Force Specifies if the SMB share is allowed to be dropped and recreated (required when the path changes). #> function Test-TargetResource { [CmdletBinding()] [OutputType([System.Boolean])] param ( [Parameter(Mandatory = $true)] [System.String] $Name, [Parameter(Mandatory = $true)] [System.String] $Path, [Parameter()] [System.String] $Description, [Parameter()] [System.UInt32] $ConcurrentUserLimit, [Parameter()] [System.Boolean] $EncryptData, [Parameter()] [ValidateSet('AccessBased', 'Unrestricted')] [System.String] $FolderEnumerationMode, [Parameter()] [ValidateSet('None', 'Manual', 'Programs', 'Documents', 'BranchCache')] [System.String] $CachingMode, [Parameter()] [System.Boolean] $ContinuouslyAvailable, [Parameter()] [System.String[]] $FullAccess, [Parameter()] [System.String[]] $ChangeAccess, [Parameter()] [System.String[]] $ReadAccess, [Parameter()] [System.String[]] $NoAccess, [Parameter()] [ValidateSet('Present', 'Absent')] [System.String] $Ensure = 'Present', [Parameter()] [System.String] $ScopeName = '*', [Parameter()] [System.Boolean] $Force ) $null = $PSBoundParameters.Remove('Force') Assert-AccessPermissionParameters @PSBoundParameters Write-Verbose -Message ($script:localizedData.TestTargetResourceMessage -f $Name) $resourceRequiresUpdate = $false $currentSmbShareConfiguration = Get-TargetResource -Name $Name -Path $Path if ($currentSmbShareConfiguration.Ensure -eq $Ensure) { if ($Ensure -eq 'Present') { Write-Verbose -Message ( '{0} {1}' -f ` ($script:localizedData.IsPresent -f $Name), $script:localizedData.EvaluatingProperties ) <# Using $VerbosePreference so that the verbose messages in Test-DscParameterState is outputted, if the user requested verbose messages. #> $resourceRequiresUpdate = Test-DscParameterState ` -CurrentValues $currentSmbShareConfiguration ` -DesiredValues $PSBoundParameters ` -SortArrayValues ` -Verbose:$VerbosePreference } else { Write-Verbose -Message ($script:localizedData.IsAbsent -f $Name) $resourceRequiresUpdate = $true } } return $resourceRequiresUpdate } <# .SYNOPSIS Removes the access permission for accounts that are no longer part of the respectively access collections (FullAccess, ChangeAccess, ReadAccess, and NoAccess). .PARAMETER Name The name of the SMB share for which to remove access permission. .PARAMETER FullAccess A string collection of account names that _should have_ full access permission. The accounts not in this collection will be removed from the SMB share. .PARAMETER ChangeAccess A string collection of account names that _should have_ change access permission. The accounts not in this collection will be removed from the SMB share. .PARAMETER ReadAccess A string collection of account names that _should have_ read access permission. The accounts not in this collection will be removed from the SMB share. .PARAMETER NoAccess A string collection of account names that _should be_ denied access to the SMB share. The accounts not in this collection will be removed from the SMB share. .NOTES The access permission is only removed if the parameter was passed into the function. #> function Remove-SmbShareAccessPermission { param ( [Parameter(Mandatory = $true)] [System.String] $Name, [Parameter()] [System.String[]] $FullAccess, [Parameter()] [System.String[]] $ChangeAccess, [Parameter()] [System.String[]] $ReadAccess, [Parameter()] [System.String[]] $NoAccess ) $currentSmbShareAccessPermissions = Get-SmbShareAccess -Name $Name <# First all access must be removed for accounts that should not have permission, or should be unblocked (those that was denied access). After that we can add new accounts using the function Add-SmbShareAccessPermission. #> foreach ($smbShareAccess in $currentSmbShareAccessPermissions) { switch ($smbShareAccess.AccessControlType) { 'Allow' { $shouldRevokeAccess = $false foreach ($accessRight in 'Change','Read','Full') { $accessRightVariableName = '{0}Access' -f $accessRight $shouldRevokeAccess = $shouldRevokeAccess ` -or ( $smbShareAccess.AccessRight -eq $accessRight ` -and $PSBoundParameters.ContainsKey($accessRightVariableName) ` -and $smbShareAccess.AccountName -notin $PSBoundParameters[$accessRightVariableName] ) } if ($shouldRevokeAccess) { Write-Verbose -Message ($script:localizedData.RevokeAccess -f $smbShareAccess.AccountName, $Name) Revoke-SmbShareAccess -Name $Name -AccountName $smbShareAccess.AccountName -Force -ErrorAction 'Stop' } } 'Deny' { if ($smbShareAccess.AccessRight -eq 'Full') { if ($PSBoundParameters.ContainsKey('NoAccess') -and $smbShareAccess.AccountName -notin $NoAccess) { Write-Verbose -Message ($script:localizedData.UnblockAccess -f $smbShareAccess.AccountName, $Name) Unblock-SmbShareAccess -Name $Name -AccountName $smbShareAccess.AccountName -Force -ErrorAction 'Stop' } } } } } } <# .SYNOPSIS Add the access permission to the SMB share for accounts, in the respectively access collections (FullAccess, ChangeAccess, ReadAccess, and NoAccess), that do not yet have access. .PARAMETER Name The name of the SMB share to add access permission to. .PARAMETER FullAccess A string collection of account names that should have full access permission. The accounts in this collection will be added to the SMB share. .PARAMETER ChangeAccess A string collection of account names that should have change access permission. The accounts in this collection will be added to the SMB share. .PARAMETER ReadAccess A string collection of account names that should have read access permission. The accounts in this collection will be added to the SMB share. .PARAMETER NoAccess A string collection of account names that should be denied access to the SMB share. The accounts in this collection will be added to the SMB share. #> function Add-SmbShareAccessPermission { param ( [Parameter(Mandatory = $true)] [System.String] $Name, [Parameter()] [System.String[]] $FullAccess, [Parameter()] [System.String[]] $ChangeAccess, [Parameter()] [System.String[]] $ReadAccess, [Parameter()] [System.String[]] $NoAccess ) $currentSmbShareAccessPermissions = Get-SmbShareAccess -Name $Name $accessRights = @{ ReadAccess = 'Read' ChangeAccess = 'Change' FullAccess = 'Full' } foreach ($accessRight in $accessRights.GetEnumerator()) { if ($PSBoundParameters.ContainsKey($accessRight.Key)) { # Get already added account names. $smbShareAccessObjects = $currentSmbShareAccessPermissions | Where-Object -FilterScript { $_.AccessControlType -eq 'Allow' -and $_.AccessRight -eq $accessRight.Value } # Get a collection of just the account names. $accessAccountNames = @($smbShareAccessObjects.AccountName) $newAccountsToHaveAccess = $PSBoundParameters[$accessRight.Key] | Where-Object -FilterScript { $_ -notin $accessAccountNames } # Add new accounts that should have permission. $newAccountsToHaveAccess | ForEach-Object -Process { Write-Verbose -Message ($script:localizedData.GrantAccess -f $accessRight.Value, $_, $Name) Grant-SmbShareAccess -Name $Name -AccountName $_ -AccessRight $accessRight.Value -Force -ErrorAction 'Stop' } } } if ($PSBoundParameters.ContainsKey('NoAccess')) { # Get already added account names. $smbShareNoAccessObjects = $currentSmbShareAccessPermissions | Where-Object -FilterScript { $_.AccessControlType -eq 'Deny' -and $_.AccessRight -eq 'Full' } # Get a collection of just the account names. $noAccessAccountNames = @($smbShareNoAccessObjects.AccountName) $newAccountsToHaveNoAccess = $NoAccess | Where-Object -FilterScript { $_ -notin $noAccessAccountNames } # Add new accounts that should be denied permission. $newAccountsToHaveNoAccess | ForEach-Object -Process { Write-Verbose -Message ($script:localizedData.DenyAccess -f $_, $Name) Block-SmbShareAccess -Name $Name -AccountName $_ -Force -ErrorAction 'Stop' } } } <# .SYNOPSIS Assert that not only empty collections are passed in the respectively access permission collections (FullAccess, ChangeAccess, ReadAccess, and NoAccess). .PARAMETER Name The name of the SMB share to add access permission to. .PARAMETER FullAccess A string collection of account names that should have full access permission. The accounts in this collection will be added to the SMB share. .PARAMETER ChangeAccess A string collection of account names that should have change access permission. The accounts in this collection will be added to the SMB share. .PARAMETER ReadAccess A string collection of account names that should have read access permission. The accounts in this collection will be added to the SMB share. .PARAMETER NoAccess A string collection of account names that should be denied access to the SMB share. The accounts in this collection will be added to the SMB share. .PARAMETER RemainingParameters Container for the rest of the potentially splatted parameters from the $PSBoundParameters object. .NOTES The group 'Everyone' is automatically given read access by the cmdlet New-SmbShare if all access permission parameters (FullAccess, ChangeAccess, ReadAccess, NoAccess) is set to @(). For that reason we need neither of the parameters, or at least one to specify an account. #> function Assert-AccessPermissionParameters { param ( [Parameter()] [System.String[]] $FullAccess, [Parameter()] [System.String[]] $ChangeAccess, [Parameter()] [System.String[]] $ReadAccess, [Parameter()] [System.String[]] $NoAccess, [Parameter(ValueFromRemainingArguments)] [System.Collections.Generic.List`1[System.Object]] $RemainingParameters ) <# First check if ReadAccess is monitored (part of the configuration). If it is not monitored, then we don't need to worry if Everyone is added. #> if ($PSBoundParameters.ContainsKey('ReadAccess') -and -not $ReadAccess) { $fullAccessIsEmpty = $PSBoundParameters.ContainsKey('FullAccess') -and -not $FullAccess $changeAccessIsEmpty = $PSBoundParameters.ContainsKey('ChangeAccess') -and -not $ChangeAccess $noAccessIsEmpty = $PSBoundParameters.ContainsKey('NoAccess') -and -not $NoAccess <# If ReadAccess should have no members, then we need at least one member in one of the other access permission collections. #> if ($fullAccessIsEmpty -and $changeAccessIsEmpty -and $noAccessIsEmpty) { New-InvalidArgumentException -Message $script:localizedData.InvalidAccessParametersCombination -ArgumentName 'FullAccess, ChangeAccess, ReadAccess, NoAccess' } } } |