dfsdsc
Version information
This version is compatible with:
- Puppet Enterprise 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x, 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x
- Puppet >= 6.0.0 < 8.0.0
Start using this module
Add this module to your Puppetfile:
mod 'dsc-dfsdsc', '4.2.0-0-1'
Learn more about managing modules with a PuppetfileDocumentation
Table of Contents
Description
This is an auto-generated module, using the Puppet DSC Builder to vendor and expose the PowerShell module's DSC resources as Puppet resources. The functionality of this module comes entirely from the vendored PowerShell resources, which are pinned at v4.2.0.0. The PowerShell module describes itself like this:
DSC resources for configuring Distributed File System Replication and Namespaces.
For information on troubleshooting to determine whether any encountered problems are with the Puppet wrapper or the DSC resource, see the troubleshooting section below.
Requirements
This module, like all auto-generated Puppetized DSC modules, relies on two important technologies in the Puppet stack: the Puppet Resource API and the puppetlabs/pwshlib Puppet module.
The Resource API provides a simplified option for writing types and providers and is responsible for how this module is structured. The Resource API ships inside of Puppet starting with version 6. While it is technically possible to add the Resource API functionality to Puppet 5.5.x, the DSC functionality has not been tested in this setup. For more information on the Resource API, review the documentation.
The module also depends on the pwshlib module. This Puppet module includes two important things: the ruby-pwsh library for running PowerShell code from ruby and the base provider for DSC resources, which this module leverages.
All of the actual work being done to call the DSC resources vendored with this module is in this file from the pwshlib module. This is important for troubleshooting and bug reporting, but doesn't impact your use of the module except that the end result will be that nothing works, as the dependency is not installed alongside this module!
Usage
You can specify any of the DSC resources from this module like a normal Puppet resource in your manifests. The examples below use DSC resources from from the PowerShellGet repository, regardless of what module you're looking at here; the syntax, not the specifics, is what's important.
For reference documentation about the DSC resources exposed in this module, see the Reference Forge tab, or the REFERENCE.md file.
# Include a meaningful title for your resource declaration
dsc_psrepository { 'Add team module repo':
dsc_name => 'foo',
dsc_ensure => present,
# This location is nonsense, can be any valid folder on your
# machine or in a share, any location the SourceLocation param
# for the DSC resource will accept.
dsc_sourcelocation => 'C:\Program Files',
# You must always pass an enum fully lower-cased;
# Puppet is case sensitive even when PowerShell isn't
dsc_installationpolicy => untrusted,
}
dsc_psrepository { 'Trust public gallery':
dsc_name => 'PSGallery',
dsc_ensure => present,
dsc_installationpolicy => trusted,
}
dsc_psmodule { 'Make Ruby manageable via uru':
dsc_name => 'RubyInstaller',
dsc_ensure => present,
}
For more information about using a built module, check out our narrative documentation.
Properties
Note that the only properties specified in a resource declaration which are passed to Invoke-Dsc are all prepended with dsc.
If a property does _not start with dsc_ it is used to control how Puppet interacts with DSC/other Puppet resources - for example,
specifying a unique name for the resource for Puppet to distinguish between declarations or Puppet metaparameters (notifies,
before, etc).
Troubleshooting
In general, there are three broad categories of problems:
- Problems with the way the underlying DSC resource works.
- Problems with the type definition, where you can't specify a valid set of properties for the DSC resource
- Problems with calling the underlying DSC resource - the parameters aren't being passed correctly or the resource can't be found
Unfortunately, problems with the way the underlying DSC resource works are something we can't help directly with. You'll need to file an issue with the upstream maintainers for the PowerShell module.
Problems with the type definition are when a value that should be valid according to the DSC resource's documentation and code is not accepted by the Puppet wrapper. If and when you run across one of these, please file an issue with the Puppet DSC Builder; this is where the conversion happens and once we know of a problem we can fix it and regenerate the Puppet modules. To help us identify the issue, please specify the DSC module, version, resource, property and values that are giving you issues. Once a fix is available we will regenerate and release updated versions of this Puppet wrapper.
Problems with calling the underlying DSC resource become apparent by comparing <value passed in in puppet>
with <value received by DSC>
.
In this case, please file an issue with the puppetlabs/pwshlib module, which is where the DSC base provider actually lives.
We'll investigate and prioritize a fix and update the puppetlabs/pwshlib module.
Updating to the pwshlib version with the fix will immediately take advantage of the improved functionality without waiting for this module to be reconverted and published.
For specific information on troubleshooting a generated module, check the troubleshooting guide for the puppet.dsc module.
Known Limitations
Currently, because of the way Puppet caches files on agents, use of the legacy puppetlabs-dsc
module is not compatible with this or any auto-generated DSC module.
Inclusion of both will lead to pluginsync conflicts.
Reference
Table of Contents
Resource types
dsc_dfsnamespacefolder
: The DSC DFSNamespaceFolder resource type. Automatically generated from version 4.2.0.0dsc_dfsnamespaceroot
: The DSC DFSNamespaceRoot resource type. Automatically generated from version 4.2.0.0dsc_dfsnamespaceserverconfiguration
: The DSC DFSNamespaceServerConfiguration resource type. Automatically generated from version 4.2.0.0dsc_dfsreplicationgroup
: The DSC DFSReplicationGroup resource type. Automatically generated from version 4.2.0.0dsc_dfsreplicationgroupconnection
: The DSC DFSReplicationGroupConnection resource type. Automatically generated from version 4.2.0.0dsc_dfsreplicationgroupfolder
: The DSC DFSReplicationGroupFolder resource type. Automatically generated from version 4.2.0.0dsc_dfsreplicationgroupmembership
: The DSC DFSReplicationGroupMembership resource type. Automatically generated from version 4.2.0.0
Resource types
dsc_dfsnamespacefolder
The DSC DFSNamespaceFolder resource type. Automatically generated from version 4.2.0.0
Properties
The following properties are available in the dsc_dfsnamespacefolder
type.
dsc_description
Data type: Optional[String]
The description of the DFS Namespace.
dsc_enableinsitereferrals
Data type: Optional[Boolean]
Indicates whether a DFS namespace server provides a client only with referrals that are in the same site as the client.
dsc_enabletargetfailback
Data type: Optional[Boolean]
Indicates whether a DFS namespace uses target failback.
dsc_ensure
Data type: Enum['Present', 'Absent']
Specifies if the DFS Namespace root should exist.
dsc_referralpriorityclass
Data type: Optional[Enum['Global-High', 'SiteCost-High', 'SiteCost-Normal', 'SiteCost-Low', 'Global-Low']]
Specifies the target priority class for a DFS namespace root.
dsc_referralpriorityrank
Data type: Optional[Integer[0, 4294967295]]
Specifies the priority rank, as an integer, for a root target of the DFS namespace.
dsc_state
Data type: Optional[String]
dsc_timetolivesec
Data type: Optional[Integer[0, 4294967295]]
Specifies a TTL interval, in seconds, for referrals.
Parameters
The following parameters are available in the dsc_dfsnamespacefolder
type.
dsc_path
namevar
Data type: String
Specifies a path for the root of a DFS namespace.
dsc_psdscrunascredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
dsc_targetpath
namevar
Data type: String
Specifies a path for a root target of the DFS namespace.
name
namevar
Data type: String
Description of the purpose for this resource declaration.
dsc_dfsnamespaceroot
The DSC DFSNamespaceRoot resource type. Automatically generated from version 4.2.0.0
Properties
The following properties are available in the dsc_dfsnamespaceroot
type.
dsc_description
Data type: Optional[String]
The description of the DFS Namespace.
dsc_enableaccessbasedenumeration
Data type: Optional[Boolean]
Indicates whether a DFS namespace uses access-based enumeration.
dsc_enableinsitereferrals
Data type: Optional[Boolean]
Indicates whether a DFS namespace server provides a client only with referrals that are in the same site as the client.
dsc_enablerootscalability
Data type: Optional[Boolean]
Indicates whether a DFS namespace uses root scalability mode.
dsc_enablesitecosting
Data type: Optional[Boolean]
Indicates whether a DFS namespace uses cost-based selection.
dsc_enabletargetfailback
Data type: Optional[Boolean]
Indicates whether a DFS namespace uses target failback.
dsc_ensure
Data type: Enum['Present', 'Absent']
Specifies if the DFS Namespace root should exist.
dsc_referralpriorityclass
Data type: Optional[Enum['Global-High', 'SiteCost-High', 'SiteCost-Normal', 'SiteCost-Low', 'Global-Low']]
Specifies the target priority class for a DFS namespace root.
dsc_referralpriorityrank
Data type: Optional[Integer[0, 4294967295]]
Specifies the priority rank, as an integer, for a root target of the DFS namespace.
dsc_state
Data type: Optional[String]
dsc_timetolivesec
Data type: Optional[Integer[0, 4294967295]]
Specifies a TTL interval, in seconds, for referrals.
dsc_type
Data type: Enum['Standalone', 'DomainV1', 'DomainV2']
Specifies the type of a DFS namespace as a Type object.
Parameters
The following parameters are available in the dsc_dfsnamespaceroot
type.
dsc_path
namevar
Data type: String
Specifies a path for the root of a DFS namespace.
dsc_psdscrunascredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
dsc_targetpath
namevar
Data type: String
Specifies a path for a root target of the DFS namespace.
name
namevar
Data type: String
Description of the purpose for this resource declaration.
dsc_dfsnamespaceserverconfiguration
The DSC DFSNamespaceServerConfiguration resource type. Automatically generated from version 4.2.0.0
Properties
The following properties are available in the dsc_dfsnamespaceserverconfiguration
type.
dsc_ldaptimeoutsec
Data type: Optional[Integer[0, 4294967295]]
Specifies a time-out value, in seconds, for Lightweight Directory Access Protocol (LDAP) requests for the DFS namespace server.
dsc_syncintervalsec
Data type: Optional[Integer[0, 4294967295]]
This interval controls how often domain-based DFS namespace root servers and domain controllers connect to the PDC emulator to get updates of DFS namespace metadata.
dsc_usefqdn
Data type: Optional[Boolean]
Indicates whether a DFS namespace server uses FQDNs in referrals.
Parameters
The following parameters are available in the dsc_dfsnamespaceserverconfiguration
type.
dsc_issingleinstance
namevar
Data type: Enum['Yes']
Specifies the resource is a single instance, the value must be 'Yes'.
dsc_psdscrunascredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
name
namevar
Data type: String
Description of the purpose for this resource declaration.
dsc_dfsreplicationgroup
The DSC DFSReplicationGroup resource type. Automatically generated from version 4.2.0.0
Properties
The following properties are available in the dsc_dfsreplicationgroup
type.
dsc_contentpaths
Data type: Optional[Array[String]]
An array of DFS Replication Group Content Paths to use for each of the Folders. This can have one entry for each Folder in the Folders parameter and should be set in th same order. If any entry is not blank then the Content Paths will need to be set manually by using the DFSReplicationGroupMembership resource.
dsc_description
Data type: Optional[String]
A description for the DFS Replication Group.
dsc_domainname
Data type: Optional[String]
The AD domain the Replication Group should created in.
dsc_ensure
Data type: Enum['Present', 'Absent']
Specifies whether the DSF Replication Group should exist.
dsc_folders
Data type: Optional[Array[String]]
A list of folders that are replicated in this Replication Group.
dsc_members
Data type: Optional[Array[String]]
A list of computers that are members of this Replication Group. These can be specified using either the ComputerName or FQDN name for each member. If an FQDN name is used and the DomainName parameter is set, the FQDN domain name must match.
dsc_topology
Data type: Optional[Enum['Fullmesh', 'Manual']]
This allows a replication topology to assign to the Replication Group. It defaults to Manual, which will not automatically create a topology. If set to Fullmesh, a full mesh topology between all members will be created.
Parameters
The following parameters are available in the dsc_dfsreplicationgroup
type.
dsc_groupname
namevar
Data type: String
The name of the DFS Replication Group.
dsc_psdscrunascredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
name
namevar
Data type: String
Description of the purpose for this resource declaration.
dsc_dfsreplicationgroupconnection
The DSC DFSReplicationGroupConnection resource type. Automatically generated from version 4.2.0.0
Properties
The following properties are available in the dsc_dfsreplicationgroupconnection
type.
dsc_description
Data type: Optional[String]
A description for the DFS Replication Group connection.
dsc_domainname
Data type: Optional[String]
The name of the AD Domain the DFS Replication Group connection should be in.
dsc_ensure
Data type: Enum['Present', 'Absent']
Specifies whether the DSF Replication Group connection should exist.
dsc_ensureenabled
Data type: Optional[Enum['Enabled', 'Disabled']]
Ensures that connection is either Enabled or Disabled.
dsc_ensurerdcenabled
Data type: Optional[Enum['Enabled', 'Disabled']]
Ensures remote differential compression is Enabled or Disabled.
Parameters
The following parameters are available in the dsc_dfsreplicationgroupconnection
type.
dsc_destinationcomputername
namevar
Data type: String
The name of the Replication Group destination computer for the connection. This can be specified using either the ComputerName or FQDN name for the member. If an FQDN name is used and the DomainName parameter is set, the FQDN domain name must match.
dsc_groupname
namevar
Data type: String
The name of the DFS Replication Group.
dsc_psdscrunascredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
dsc_sourcecomputername
namevar
Data type: String
The name of the Replication Group source computer for the connection. This can be specified using either the ComputerName or FQDN name for the member. If an FQDN name is used and the DomainName parameter is set, the FQDN domain name must match.
name
namevar
Data type: String
Description of the purpose for this resource declaration.
dsc_dfsreplicationgroupfolder
The DSC DFSReplicationGroupFolder resource type. Automatically generated from version 4.2.0.0
Properties
The following properties are available in the dsc_dfsreplicationgroupfolder
type.
dsc_description
Data type: Optional[String]
A description for the DFS Replication Group Folder.
dsc_dfsnpath
Data type: Optional[String]
The DFS Namespace Path to this Replication Group folder is mapped to. This does NOT create the Namespace folders, it only sets the name in the folder object.
dsc_directorynametoexclude
Data type: Optional[Array[String]]
An array of directory names to exclude from replication.
dsc_domainname
Data type: Optional[String]
The name of the AD Domain the DFS Replication Group Folder will be in.
dsc_filenametoexclude
Data type: Optional[Array[String]]
An array of file names to exclude from replication.
Parameters
The following parameters are available in the dsc_dfsreplicationgroupfolder
type.
dsc_foldername
namevar
Data type: String
The name of the DFS Replication Group Folder.
dsc_groupname
namevar
Data type: String
The name of the DFS Replication Group.
dsc_psdscrunascredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
name
namevar
Data type: String
Description of the purpose for this resource declaration.
dsc_dfsreplicationgroupmembership
The DSC DFSReplicationGroupMembership resource type. Automatically generated from version 4.2.0.0
Properties
The following properties are available in the dsc_dfsreplicationgroupmembership
type.
dsc_conflictanddeletedpath
Data type: Optional[String]
The local content and deleted path for the DFS Replication Group Folder.
dsc_contentpath
Data type: Optional[String]
The local content path for the DFS Replication Group Folder.
dsc_domainname
Data type: Optional[String]
The name of the AD Domain the DFS Replication Group this replication group is in.
dsc_primarymember
Data type: Optional[Boolean]
Used to configure this as the Primary Member. Every folder must have at least one primary member for initial replication to take place.
dsc_readonly
Data type: Optional[Boolean]
Specify if this content path should be read only.
dsc_stagingpath
Data type: Optional[String]
The local staging path for the DFS Replication Group Folder.
dsc_stagingpathquotainmb
Data type: Optional[Integer[0, 4294967295]]
The staging path quota size in MB for the DFS Replication Group Folder.
Parameters
The following parameters are available in the dsc_dfsreplicationgroupmembership
type.
dsc_computername
namevar
Data type: String
The computer name of the Replication Group member. This can be specified using either the ComputerName or FQDN name for the member. If an FQDN name is used and the DomainName parameter is set, the FQDN domain name must match.
dsc_foldername
namevar
Data type: String
The name of the DFS Replication Group Folder.
dsc_groupname
namevar
Data type: String
The name of the DFS Replication Group.
dsc_psdscrunascredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
name
namevar
Data type: String
Description of the purpose for this resource declaration.
Versions
Unreleased
4.2.0.0
- Add support for modifying staging quota size in MSFT_DFSReplicationGroupMembership - fixes Issue #77.
- Refactored module folder structure to move resource to root folder of repository and remove test harness - fixes Issue #74.
- Updated Examples to support deployment to PowerShell Gallery scripts.
- Remove exclusion of all tags in appveyor.yml, so all common tests can be run if opt-in.
- Added .VSCode settings for applying DSC PSSA rules - fixes Issue #75.
- Updated LICENSE file to match the Microsoft Open Source Team standard - fixes Issue #79
4.1.0.0
- Added Hub and Spoke replication group example - fixes Issue #62.
- Enabled PSSA rule violations to fail build - fixes Issue #320.
- Allow null values in resource group members or folders - fixes Issue #27.
- Added a CODE_OF_CONDUCT.md with the same content as in the README.md - fixes Issue #67.
4.0.0.0
- BREAKING CHANGE
- Renamed xDFS to DFSDsc - fixes Issue #55.
- Changed all MSFT_xResourceName to MSFT_DFSResourceName.
- Updated DSCResources, Examples, Modules and Tests for new naming.
- Updated Year to 2018 in License and Manifest.
- Changed all Modules\DFSDsc\Examples\Resources to DFSResourceName.
- Added the VS Code PowerShell extension formatting settings that cause PowerShell files to be formatted as per the DSC Resource kit style guidelines.
- Improve layout of badge area in README.MD.
- Disabled MD013 rule checking to enable badge table.
- Updated Year to 2017 in License and Manifest.
- Added .github support files:
- CONTRIBUTING.md
- ISSUE_TEMPLATE.md
- PULL_REQUEST_TEMPLATE.md
- Opted into Common Tests 'Validate Module Files' and 'Validate Script Files'.
- Converted files with UTF8 with BOM over to UTF8 - fixes Issue #47.
- Added
Documentation and Examples
section to Readme.md file - see issue #49. - Prevent unit tests from DSCResource.Tests from running during test execution - fixes Issue #51.
- Updated tests to meet Pester V4 guidelines - fixes Issue #53.
3.2.0.0
- Converted AppVeyor.yml to pull Pester from PSGallery instead of Chocolatey.
- Changed AppVeyor.yml to use default image.
- Converted AppVeyor build process to use AppVeyor.psm1.
- Resolved PSSA violations.
- Resolved Readme.md style violations.
- Converted Integration Tests to use Test Drive and stop using Invoke-Pester.
- Move strings into separate language files.
- Added CodeCov support.
- Clean up manifest file by removing commented out sections.
- Convert Examples to pass tests and meet minimum standards.
- Convert to Wiki and auto-documentation generation.
- Convert to TestHarness test execution method.
- Correct parameter block format to meet guidelines.
- Replaced all type accelerators with full type names.
- Updated Readme.md to contain resource list.
- Fixed xDFSNamespaceServerConfiguration by converting LocalHost to ComputerName instead.
- Added integration test to test for conflicts with other common resource kit modules.
- Prevented ResourceHelper and Common module cmdlets from being exported to resolve conflicts with other resource modules.
3.1.0.0
- MSFT_xDFSNamespaceServerConfiguration- resource added.
- Corrected names of DFS Namespace sample files to indicate that they are setting Namespace roots and folders.
- Removed Pester version from AppVeyor.yml.
3.0.0.0
- RepGroup renamed to ReplicationGroup in all files.
- xDFSReplicationGroupConnection- Changed DisableConnection parameter to EnsureEnabled. Changed DisableRDC parameter to EnsureRDCEnabled.
- xDFSReplicationGroup- Fixed bug where disabled connection was not enabled in Fullmesh topology.
2.2.0.0
- DSC Module moved to MSFT.
- MSFT_xDFSNamespace- Removed.
2.1.0.0
- MSFT_xDFSRepGroup- Fixed issue when using FQDN member names.
- MSFT_xDFSRepGroupMembership- Fixed issue with Get-TargetResource when using FQDN ComputerName.
- MSFT_xDFSRepGroupConnection- Fixed issue with Get-TargetResource when using FQDN SourceComputerName or FQDN DestinationComputerName.
- MSFT_xDFSNamespaceRoot- Added write support to TimeToLiveSec parameter.
- MSFT_xDFSNamespaceFolder- Added write support to TimeToLiveSec parameter.
2.0.0.0
- MSFT_xDFSNamespaceRoot- resource added.
- MSFT_xDFSNamespaceFolder- resource added.
- MSFT_xDFSNamespace- deprecated - use MSFT_xDFSNamespaceRoot instead.
1.5.1.0
- MSFT_xDFSNamespace- Add parameters:
- EnableSiteCosting
- EnableInsiteReferrals
- EnableAccessBasedEnumeration
- EnableRootScalability
- EnableTargetFailback
- ReferralPriorityClass
- ReferralPriorityRank
1.5.0.0
- MSFT_xDFSNamespace- New sample files added.
- MSFT_xDFSNamespace- MOF parameter descriptions corrected.
- MSFT_xDFSNamespace- Rearchitected code.
- MSFT_xDFSNamespace- SMB Share is no longer removed when a namespace or target is removed.
- MSFT_xDFSNamespace- Removed SMB Share existence check.
- Documentation layout corrected.
- MSFT_xDFSRepGroup- Array Parameter output disabled in Get-TargetResource until this issue is resolved.
1.4.2.0
- MSFT_xDFSRepGroup- Fixed "Cannot bind argument to parameter 'DifferenceObject' because it is null." error.
- All Unit tests updated to use *_TestEnvironment functions in DSCResource.Tests\TestHelpers.psm1
1.4.1.0
- MSFT_xDFSNamespace- Renamed Sample_DcFSNamespace.ps1 to Sample_xDFSNamespace.
- MSFT_xDFSNamespace- Corrected Import-DscResouce in example.
1.4.0.0
- Community update by Erik Granneman
- New DSC recource xDFSNameSpace
1.3.2.0
- Documentation and Module Manifest Update only.
1.3.1.0
- xDFSRepGroupFolder- DfsnPath parameter added for setting DFS Namespace path mapping.
1.3.0.0
- xDFSRepGroup- If ContentPaths is set, PrimaryMember is set to first member in the Members array.
- xDFSRRepGroupMembership- PrimaryMembers property added so that Primary Member can be set.
1.2.1.0
- xDFSRepGroup- Fix to ContentPaths generation when more than one folder is provided.
1.2.0.0
- xDFSRepGroup- ContentPaths string array parameter.
1.1.0.0
- xDFSRepGroupConnection- Resource added.
1.0.0.0
- Initial release.
Dependencies
- puppetlabs/pwshlib (>= 0.7.0 < 2.0.0)