{"id":15203035,"url":"https://github.com/puppetlabs-toy-chest/puppetlabs-dsc","last_synced_at":"2025-10-02T19:30:23.086Z","repository":{"id":18044016,"uuid":"21090303","full_name":"puppetlabs-toy-chest/puppetlabs-dsc","owner":"puppetlabs-toy-chest","description":"Puppet module for PowerShell Desired State Configuration (DSC) integration","archived":true,"fork":false,"pushed_at":"2022-07-14T09:42:44.000Z","size":17450,"stargazers_count":69,"open_issues_count":0,"forks_count":81,"subscribers_count":161,"default_branch":"main","last_synced_at":"2024-05-16T17:43:13.706Z","etag":null,"topics":["module","supported"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/puppetlabs-toy-chest.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null}},"created_at":"2014-06-22T09:42:33.000Z","updated_at":"2024-03-06T11:02:15.000Z","dependencies_parsed_at":"2022-08-25T13:51:06.576Z","dependency_job_id":null,"html_url":"https://github.com/puppetlabs-toy-chest/puppetlabs-dsc","commit_stats":null,"previous_names":["puppetlabs/puppetlabs-dsc"],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs-toy-chest%2Fpuppetlabs-dsc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs-toy-chest%2Fpuppetlabs-dsc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs-toy-chest%2Fpuppetlabs-dsc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs-toy-chest%2Fpuppetlabs-dsc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/puppetlabs-toy-chest","download_url":"https://codeload.github.com/puppetlabs-toy-chest/puppetlabs-dsc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235038205,"owners_count":18926234,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["module","supported"],"created_at":"2024-09-28T04:22:46.864Z","updated_at":"2025-10-02T19:30:16.386Z","avatar_url":"https://github.com/puppetlabs-toy-chest.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dsc\n\n[wmf-5.0]: https://www.microsoft.com/en-us/download/details.aspx?id=50395\n[DSCResources]: https://github.com/powershell/DSCResources\n[wmf5-blog-post]: https://msdn.microsoft.com/en-us/powershell/wmf/5.1/release-notes\n[wmf5-blog-incompatibilites]: https://msdn.microsoft.com/en-us/powershell/wmf/5.1/productincompat\n\n#### Table of Contents\n\n1. [Description - What is the dsc module and what does it do](#module-description)\n2. [Prerequisites](#windows-system-prerequisites)\n3. [Setup](#setup)\n4. [Usage](#usage)\n  * [Using DSC Resources with Puppet](#using-dsc-resources-with-puppet)\n  * [Handling Reboots with DSC](#handling-reboots-with-dsc)\n  * [Installing Packages with DSC](#installing-packages-with-dsc)\n  * [Using Credentials](#using-credentials)\n  * [Setting Registry Values](#setting-registry-values)\n  * [Adding or Removing Windows Features](#adding-or-removing-windows-features)\n  * [Website Installation Example](#website-installation-example)\n5. [Reference](#reference)\n6. [Limitations](#limitations)\n  * [Known Issues](#known-issues)\n  * [Running Puppet and DSC without Administrative Privileges](#running-puppet-and-dsc-without-administrative-privileges)\n7. [Development - Guide for contributing to the module](#development)\n8. [Places to Learn More About DSC](#places-to-learn-more-about-dsc)\n9. [License](#license)\n\n## Description\n\nThe Puppet dsc module manages Windows PowerShell DSC (Desired State Configuration) resources.\n\nThis module generates Puppet types based on DSC Resources MOF (Managed Object Format) schema files.\n\nIn this version, the following DSC Resources are already built and ready for use:\n\n- All base DSC resources found in PowerShell 5 ([WMF 5.0][wmf-5.0]).\n- All DSC resources found in the [Microsoft PowerShell DSC Resource Kit][DSCResources]\n\n## Windows System Prerequisites\n\n - PowerShell 5, which is included in [Windows Management Framework 5.0][wmf-5.0].\n   - Note: PowerShell version as obtained from `$PSVersionTable` must be 5.0.10586.117 or greater.\n - [Windows 2003 is not supported](#known-issues).\n\n## Setup\n\n~~~bash\npuppet module install puppetlabs-dsc\n~~~\n\nSee [known issues](#known-issues) for troubleshooting setup.\n\n## Usage\n\n### Using DSC Resources with Puppet\n\nYou can use a DSC Resource by prefixing each DSC Resource name and parameter with 'dsc_' and lowercasing the values.\n\nSo a DSC resource specified in PowerShell...\n\n~~~powershell\nWindowsFeature IIS {\n  Ensure = 'present'\n  Name   = 'Web-Server'\n}\n~~~\n\n...would look like this in Puppet:\n\n~~~puppet\ndsc_windowsfeature {'IIS':\n  dsc_ensure =\u003e 'present',\n  dsc_name   =\u003e 'Web-Server',\n}\n~~~\n\nAll DSC Resource names and parameters have to be in lowercase, for example: `dsc_windowsfeature` or `dsc_name`.\n\nYou can use either `ensure =\u003e` (Puppet's `ensure`) or `dsc_ensure =\u003e` (DSC's `Ensure`) in your manifests for Puppet DSC resource types. If you use both in a Puppet DSC resource, `dsc_ensure` overrides the value in `ensure`, so the value for `ensure` is essentially ignored.\n\nWe recommend that you use `dsc_ensure` instead of `ensure`, as it is a closer match for converting the DSC properties to Puppet DSC resources. It also overrides `ensure`, so there is less confusion if both are accidentally included.\n\n\u003e Note: While you can use either `ensure =\u003e` (Puppet's `ensure`) or `dsc_ensure =\u003e` (DSC's `Ensure`) in your manifests, there is currently a known issue where `ensure =\u003e absent` reports success but does nothing. See [MODULES-2966](https://tickets.puppet.com/browse/MODULES-2966) for details. **Until this issue is resolved, we recommend using `dsc_ensure` exclusively.**\n\n### Handling Reboots with DSC\n\nAdd the following `reboot` resource to your manifest. It must have the name `dsc_reboot` for the `dsc` module to find and use it.\n\n~~~puppet\nreboot { 'dsc_reboot' :\n  message =\u003e 'DSC has requested a reboot',\n  when    =\u003e 'pending',\n  onlyif  =\u003e 'pending_dsc_reboot',\n}\n~~~\n\n### Installing Packages with DSC\n\nInstall MSIs or EXEs with DSC using the Puppet type `dsc_package`, which maps to the `Package` DSC Resource.\n\n~~~puppet\ndsc_package{'installpython'\n  dsc_ensure    =\u003e 'Present',\n  dsc_name      =\u003e 'Python 2.7.10',\n  dsc_productid =\u003e 'E2B51919-207A-43EB-AE78-733F9C6797C2'\n  dsc_path      =\u003e 'C:\\\\python.msi',\n}\n~~~\n\nThe `Package` DSC Resource requires the following information to install an MSI:\n\n- ProductName: The `Name` of product being installed.\n- ProductId: The `ProductCode` property of the MSI, which is a unique identifier for the particular product release, represented as a GUID string. For more information see the [MSDN ProductCode property](https://msdn.microsoft.com/en-us/library/aa370854.aspx) documentation page.\n\nYou can obtain this information in a variety of ways.\n\n- Use a tool such as Orca to open the MSI file and inspect the `Name` and `ProductCode`.\n- Install the product on a test system, and inspect the `Name` and `ProductCode` in the Windows Add/Remove Programs Control Panel.\n- Use a script to query the MSI file for the `Name` and `ProductCode`, as in the example PowerShell script below, which was adapted from [Stack Overflow](http://stackoverflow.com/a/8743878/1083).\n\n~~~powershell\nfunction Get-MsiDatabaseInfo{\n  param ([IO.FileInfo]$FilePath)\n\n  $productName = Invoke-MSIQuery -FilePath $filePath.FullName -Query \"SELECT Value FROM Property WHERE Property = 'ProductName'\"\n  $productCode = Invoke-MSIQuery -FilePath $filePath.FullName -Query \"SELECT Value FROM Property WHERE Property = 'ProductCode'\"\n\n  return [PSCustomObject]@{\n    FullName    = $FilePath.FullName\n    ProductName = ([string]$productName).TrimStart()\n    ProductCode = ([string]$productCode).Replace(\"{\",\"\").Replace(\"}\",\"\").TrimStart()\n  }\n}\n\nfunction Invoke-MSIQuery{\n  param($FilePath, $Query)\n  try{\n    $windowsInstaller = New-Object -com WindowsInstaller.Installer\n    $database = $windowsInstaller.GetType().InvokeMember(\"OpenDatabase\", \"InvokeMethod\", $Null, $windowsInstaller, @($FilePath, 0))\n  }catch{\n    throw \"Failed to open MSI file. The error was: {0}.\" -f $_\n  }\n\n  try{\n    $View = $database.GetType().InvokeMember(\"OpenView\", \"InvokeMethod\", $Null, $database, ($query))\n    $View.GetType().InvokeMember(\"Execute\", \"InvokeMethod\", $Null, $View, $Null)\n\n    $record = $View.GetType().InvokeMember(\"Fetch\", \"InvokeMethod\", $Null, $View, $Null)\n    $property = $record.GetType().InvokeMember(\"StringData\", \"GetProperty\", $Null, $record, 1)\n\n    $View.GetType().InvokeMember(\"Close\", \"InvokeMethod\", $Null, $View, $Null)\n\n    return $property\n  }catch{\n    throw \"Failed to read MSI file. The error was: {0}.\" -f $_\n  }\n}\n~~~\n\n### Using Hashes\n\nSupply a hash to any parameter that accepts PowerShell hashes, and Puppet handles creating the appropriate values for you.\n\n~~~puppet\ndsc_example_resource { 'examplefoo':\n  dsc_ensure         =\u003e present,\n  dsc_hash_parameter =\u003e {\n    'key1' =\u003e 'value1',\n    'key2' =\u003e 'value2'\n  },\n}\n~~~\n\n### Using Credentials\n\nDSC uses `MSFT_Credential` objects to pass credentials to DSC Resources. Supply a hash to any `credential` parameter, and Puppet handles creating the `credential` object for you.\n\nOptionally use the Puppet [Sensitive type](https://puppet.com/docs/puppet/latest/lang_data_sensitive.html) to ensure logs and reports redact the password.\n\n~~~puppet\ndsc_user { 'jane-doe':\n  dsc_username             =\u003e 'jane-doe',\n  dsc_description          =\u003e 'Jane Doe user',\n  dsc_ensure               =\u003e present,\n  dsc_password             =\u003e {\n    'user' =\u003e 'jane-doe',\n    'password' =\u003e Sensitive('jane-password')\n  },\n  dsc_passwordneverexpires =\u003e false,\n  dsc_disabled             =\u003e true,\n}\n~~~\n\n### Setting Registry Values\n\nCreating and modifying Registry keys and values is done with the `dsc_registry` Puppet type which maps to the `Registry` DSC Resource.\n\n#### Registry Example: Simple\n\nSet simple values by specifying key-value pairs.\n\n~~~puppet\ndsc_registry {'registry_test':\n  dsc_ensure    =\u003e 'Present'\n  dsc_key       =\u003e 'HKEY_LOCAL_MACHINE\\SOFTWARE\\ExampleKey'\n  dsc_valuename =\u003e 'TestValue'\n  dsc_valuedata =\u003e 'TestData'\n}\n~~~\n\n#### Registry Example: Binary\n\nThe 'Binary' data type expects hexadecimal in a single string.\n\n~~~puppet\ndsc_registry {'registry_test':\n  dsc_ensure =\u003e 'Present',\n  dsc_key =\u003e 'HKEY_LOCAL_MACHINE\\SOFTWARE\\TestKey',\n  dsc_valuename =\u003e 'TestBinaryValue',\n  dsc_valuedata =\u003e 'BEEF',\n  dsc_valuetype =\u003e 'Binary',\n}\n~~~\n\n#### Registry Example: Dword and Qword\n\nThe 'Dword' and 'Qword' data types expect signed integer values, as opposed to hexadecimal or unsigned.\n\n~~~puppet\ndsc_registry {'registry_test':\n  dsc_ensure =\u003e 'Present',\n  dsc_key =\u003e 'HKEY_LOCAL_MACHINE\\SOFTWARE\\TestKey',\n  dsc_valuename =\u003e 'TestDwordValue',\n  dsc_valuedata =\u003e '-2147483648',\n  dsc_valuetype =\u003e 'Dword',\n}\n~~~\n\n*Note*: DSC Resources are executed under the SYSTEM context by default, which means you are unable to access any user level Registry key without providing alternate credentials.\n\n### Adding or Removing Windows Features\n\nYou can add or remove Windows Features using Puppet type `dsc_windowsfeature` which maps to the `WindowsFeature` DSC Resource.\n\n#### Add a Windows Feature\n\n~~~puppet\ndsc_windowsfeature {'featureexample':\n  dsc_ensure = 'present'\n  dsc_name = 'Web-Server'\n}\n~~~\n\n#### Remove a Windows Feature\n\n~~~puppet\ndsc_windowsfeature {'featureexample':\n  dsc_ensure = 'absent'\n  dsc_name = 'Web-Server'\n}\n~~~\n\n#### Finding Windows Feature Names\n\nYou can find the name to use when adding or removing Windows Features by executing the `Get-WindowsFeature` cmdlet and using the `Name` property.\n\n~~~powershell\n[PS]\u003e Get-WindowsFeature\n~~~\n\n### Website Installation Example\n\nAn end-to-end example installation of a test website.\n\n~~~puppet\nclass fourthcoffee(\n  $websitename        = 'FourthCoffee',\n  $zipname            = 'FourthCoffeeWebSiteContent.zip',\n  $sourcerepo         = 'https://github.com/msutter/fourthcoffee/raw/master',\n  $destinationpath    = 'C:\\inetpub\\FourthCoffee',\n  $defaultwebsitepath = 'C:\\inetpub\\wwwroot',\n  $zippath            = 'C:\\tmp'\n){\n\n  $zipuri  = \"${sourcerepo}/${zipname}\"\n  $zipfile = \"${zippath}\\\\${zipname}\"\n\n  # Install the IIS role\n  dsc_windowsfeature {'IIS':\n    dsc_ensure =\u003e 'present',\n    dsc_name   =\u003e 'Web-Server',\n  } -\u003e\n\n  # Install the ASP .NET 4.5 role\n  dsc_windowsfeature {'AspNet45':\n    dsc_ensure =\u003e 'present',\n    dsc_name   =\u003e 'Web-Asp-Net45',\n  } -\u003e\n\n  # Stop an existing website (set up in Sample_xWebsite_Default)\n  dsc_xwebsite {'Stop DefaultSite':\n    dsc_ensure       =\u003e 'present',\n    dsc_name         =\u003e 'Default Web Site',\n    dsc_state        =\u003e 'Stopped',\n    dsc_physicalpath =\u003e $defaultwebsitepath,\n  } -\u003e\n\n  # Create tmp folder\n  dsc_file {'tmp folder':\n    dsc_ensure          =\u003e 'present',\n    dsc_type            =\u003e 'Directory',\n    dsc_destinationpath =\u003e $zippath,\n  } -\u003e\n\n  # Download the site content\n  dsc_xremotefile {'Download WebContent Zip':\n    dsc_destinationpath =\u003e $zipfile,\n    dsc_uri             =\u003e $zipuri,\n  } -\u003e\n\n  # Extract the website content \n  dsc_archive {'Unzip and Copy the WebContent':\n    dsc_ensure      =\u003e 'present',\n    dsc_path        =\u003e $zipfile,\n    dsc_destination =\u003e $destinationpath,\n  } -\u003e\n\n  # Create a new website\n  dsc_xwebsite {'BackeryWebSite':\n    dsc_ensure       =\u003e 'present',\n    dsc_name         =\u003e $websitename,\n    dsc_state        =\u003e 'Started',\n    dsc_physicalpath =\u003e $destinationpath,\n  }\n}\n~~~\n\nAs you can see, you can mix and match DSC resources with common Puppet resources.\nAll [Puppet metaparameters](https://docs.puppet.com/references/latest/metaparameter.html) are also supported.\n\n## Reference\n\n### Types\n\nA comprehensive list of all types included in the dsc module is available in the [types document](https://github.com/puppetlabs/puppetlabs-dsc/blob/master/types.md). This list maps each Puppet resource (for example, `dsc_xcertreq`) to the corresponding DSC resource.\n\nBecause types are built from the source code of each DSC Resources MOF schema files, the name of the DSC resource in the types document links to a local copy of that resource code (in this case, `xCertReq`), so that you can see how the code is applied to your system.\n\nWhere available, a link to the external GitHub repo of each resource is also included. The DSC resources are third-party resources that may or may not be documented in their repositories. Available DSC resources and parameters are subject to change.\n\n## Limitations\n\n- DSC Composite Resources are not supported.\n\n- DSC requires PowerShell `Execution Policy` for the `LocalMachine` scope to be set to a less restrictive setting than `Restricted`. If you see the error below, the subsequent Puppet code will set it to RemoteSigned. See [MODULES-2500](https://tickets.puppet.com/browse/MODULES-2500) for more detailed information.\n\n  ~~~\n  Error: /Stage[main]/Main/Dsc_xgroup[testgroup]: Could not evaluate: Importing module MSFT_xGroupResource failed with\n  error - File C:\\Program\n  Files\\WindowsPowerShell\\Modules\\PuppetVendoredModules\\xPSDesiredStateConfiguration\\DscResources\\MSFT_xGroupR\n  esource\\MSFT_xGroupResource.psm1 cannot be loaded because running scripts is disabled on this system. For more\n  information, see about_Execution_Policies at http://go.microsoft.com/fwlink/?LinkID=135170.\n  ~~~\n  \n  ~~~puppet\n  exec { 'Set PowerShell execution policy RemoteSigned':\n    command  =\u003e 'Set-ExecutionPolicy RemoteSigned',\n    unless   =\u003e 'if ((Get-ExecutionPolicy -Scope LocalMachine).ToString() -eq \"RemoteSigned\") { exit 0 } else { exit 1 }',\n    provider =\u003e powershell\n  }\n  ~~~\n\n- You cannot use forward slashes for the MSI `Path` property for the `Package` DSC Resource. The underlying implementation does not accept forward slashes instead of backward slashes in paths, and it throws a misleading error that it could not find a Package with the Name and ProductId provided. [MODULES-2486](https://tickets.puppet.com/browse/MODULES-2486) has more examples and information on this subject.\n- `dsc_ensure` overrides and ignores the value in `ensure` if both are present in a Puppet DSC resource. See [Using DSC Resources with Puppet](#using-dsc-resources-with-puppet).\n- Use of this module with the 3.8.x x86 version of Puppet is highly discouraged, though supported.  Normally, this module employs a technique to dramatically improve performance by reusing a PowerShell process to execute DSC related commands.  However, due to the Ruby 1.9.3 runtime used with the 3.8.x x86 version of Puppet, this technique must be disabled, resulting in at least a 2x slowdown.\n\n### Known Issues\n\n- The DSC Local Configuration Manager (LCM) `RefreshMode` **must** be set to either `Push` or `Disabled` for the Puppet `dsc` module to function. The default value for `RefreshMode` in WMF 5.0 and WMF 5.1 is `Push` — there is no action needed on your part. Changing the value is only needed if the `RefreshMode` has been set to any value other than `Push`. The Puppet `dsc` module uses the `Invoke-DscResource` cmdlet to invoke DSC Resources of the target machine. If the `RefreshMode` is set to `Pull`, DSC Resources will only run from a DSC Pull Server — in this setting DSC does not allow any DSC Resources to be run interactively on the host.\n\n\n- The `WaitFor*` type of DSC Resources may not work with this module. These DSC Resources use sleeps, timers, or locking to 'wait' for other resources to be in a specified state. These waits would 'pause' a Puppet run for an amount of time that varies between DSC Resource implementations, which may cause unintended problems in the Puppet run. Puppet cannot test all possible interactions from these `WaitFor*` DSC Resources, and does not support them at this time.\n\n- The `dsc_log` resource might not appear to work. The [\"Log\" resource](https://technet.microsoft.com/en-us/library/Dn282117.aspx) writes events to the 'Microsoft-Windows-Desired State Configuration/Analytic' event log, which is [disabled by default](https://technet.microsoft.com/en-us/library/Cc749492.aspx).\n\n- You might have issues if you attempt to use `dsc_ensure =\u003e absent` with `dsc_service` with services that are not running.\n\n  When setting resources to absent, you might normally specify a minimal statement such as:\n\n  ~~~puppet\n  dsc_service{'disable_foo':\n    dsc_ensure =\u003e absent,\n    dsc_name =\u003e 'foo'\n  }\n  ~~~\n\n  However, due to the way the Service DSC Resource sets its defaults, if the service is not currently running, the above statement erroneously reports that the service is already absent. To work around this, specify that `State =\u003e 'Stopped'` as well as `Ensure =\u003e absent'`. The following example works:\n\n  ~~~puppet\n  dsc_service{'disable_foo':\n    dsc_ensure =\u003e absent,\n    dsc_name   =\u003e 'foo',\n    dsc_state  =\u003e 'stopped'\n  }\n  ~~~\n\n  [MODULES-2512](https://tickets.puppet.com/browse/MODULES-2512) has more details.\n\n- You might have issues attempting to use `dsc_ensure =\u003e absent` with `dsc_xservice` with services that are already not present. To work around this problem, always specify the path to the executable for the service when specifying `absent`. [MODULES-2512](https://tickets.puppet.com/browse/MODULES-2512) has more details. The following example works:\n\n  ~~~puppet\n  dsc_xservice{'disable_foo':\n    dsc_ensure =\u003e absent,\n    dsc_name   =\u003e 'foo',\n    dsc_path   =\u003e 'c:\\\\Program Files\\\\Foo\\\\bin\\\\foo.exe'\n  }\n  ~~~\n\n- Use `ensure` instead of `dsc_ensure` - `ensure =\u003e absent` will report success while doing nothing - see [MODULES-2966](https://tickets.puppet.com/browse/MODULES-2966) for details. Also see [Using DSC Resources with Puppet](#using-dsc-resources-with-puppet).\n\n- When installing the module on Windows you might run into an issue regarding long file names (LFN) due to the long paths of the generated schema files. If you install your module on a Linux master, and then use plugin sync you will likely not see this issue. If you are attempting to install the module on a Windows machine using `puppet module install puppetlabs-dsc` you may run into an error that looks similar to the following:\n\n  ~~~puppet\n  Error: No such file or directory @ rb_sysopen - C:/ProgramData/PuppetLabs/puppet/cache/puppet-module/cache/tmp-unpacker20150713-...mof\n  Error: Try 'puppet help module install' for usage\n  ~~~\n\n  For Puppet 4.2.2+ (and 3.8.2) we've decreased the possibility of the issue occurring based on the fixes in [PUP-4854](https://tickets.puppet.com/browse/PUP-4854). A complete fix is plannd in a future version of Puppet that incorporates [PUP-4866](https://tickets.puppet.com/browse/PUP-4866).\n\n  If you are affected by this issue:\n  - Use the `--module_working_dir` parameter to set a different temporary directory which has a smaller length, for example;\n    `puppet module install puppetlabs-dsc --module_working_dir C:\\Windows\\Temp`\n  - Download the `.tar.gz` from the [Forge](https://forge.puppet.com/puppetlabs/dsc) and use `puppet module install` using the downloaded file, rather than directly installing from the Forge.\n\n- Windows Server 2003 is not supported. **If this module is present on the master, it breaks Windows 2003 agents.**\n\n  When installed on a Puppet master to the default `production` environment, this module causes pluginsync to **fail** on Windows 2003 agents because of an issue with [LFN (long file names)](https://tickets.puppet.com/browse/PUP-4866). To work around this issue, host your Windows 2003 nodes on a [Puppet environment](https://docs.puppet.com/puppet/latest/reference/environments.html) that is separate from `production` and that does **not** have the DSC module installed.\n\n- `--noop` mode, `puppet resource` and property change notifications are currently not implemented - see [MODULES-2270](https://tickets.puppet.com/browse/MODULES-2270) for details.\n\n- [Known WMF 5.0 Product Incompatibilites][wmf5-blog-incompatibilites]\n\n  Systems that are running the following server applications should not run Windows Management Framework 5.0 at this time:\n   - Microsoft Exchange Server 2013\n   - Microsoft Exchange Server 2010 SP3\n   - Microsoft SharePoint Server 2013\n   - Microsoft SharePoint Server 2010\n   - System Center 2012 Virtual Machine Manager\n\n- The `Registry` DSC Resource continually changes state, even if the system state matches the desired state, when using a HEX value. See issue [#237](https://github.com/puppetlabs/puppetlabs-dsc/issues/237) for more information.\n\n- The Puppet DSC module hangs on systems with WMF 5.1 installed. This is being addressed in [MODULES-3690](https://tickets.puppetlabs.com/browse/MODULES-3690).\n\n- If you create files with the `dsc_file` resource, the resulting file on disk will be UTF-8 with BOM. This can be a problem if you use tools that are not UTF-8 BOM aware. This is by design for Microsoft PowerShell DSC. More information can be found in [MODULES-3178](https://tickets.puppetlabs.com/browse/MODULES-3178).\n\n### Running Puppet and DSC without Administrative Privileges\n\nWhile there are avenues for using Puppet with a non-administrative account, DSC is limited to only accounts with administrative privileges. The underlying CIM implementation DSC uses for DSC Resource invocation requires administrative credentials to function.\n\n- Using the Invoke-DscResource cmdlet requires administrative credentials\n\nThe Puppet agent on a Windows node can run DSC with a normal default install. If the Puppet agent was configured to use an alternate user account, that account must have administrative privileges on the system in order to run DSC.\n\n## Troubleshooting\n\nWhen Puppet runs, the dsc module takes the code supplied in your puppet manifest and converts that into PowerShell code that is sent to the DSC engine directly using `Invoke-DscResource`. You can see both the commands sent and the result of this by running puppet interactively, e.g. `puppet apply --debug`. It will output the PowerShell code that is sent to DSC to execute and the return data from DSC. For example:\n\n```puppet\nNotice: Compiled catalog for win2012r2 in environment production in 0.82 seconds\nDebug: Creating default schedules\nDebug: Loaded state in 0.03 seconds\nDebug: Loaded state in 0.05 seconds\nInfo: Applying configuration version '1475264065'\nDebug: Reloading posix reboot provider\nDebug: Facter: value for uses_win32console is still nil\nDebug: PowerShell Version: 5.0.10586.117\n$invokeParams = @{\n  Name          = 'ExampleDSCResource'\n  Method        = 'test'\n  Property      = @{\n    property1 = 'value1'\n    property2 = 'value2'\n  }\n  ModuleName = @{\n    ModuleName      = \"C:/puppetlabs/modules/dsc/lib/puppet_x/dsc_resources/ExampleDSCResource/ExampleDSCResource.psd1\"\n    RequiredVersion = \"1.0\"\n  }\n}\n############### SNIP ################\nDebug: Waited 50 milliseconds...\n############### SNIP ################\nDebug: Waited 500 total milliseconds.\nDebug: Dsc Resource returned: {\"rebootrequired\":false,\"indesiredstate\":false,\"errormessage\":\"\"}\nDebug: Dsc Resource Exists?: false\nDebug: ensure: present\n############### SNIP ################\n$invokeParams = @{\n  Name          = 'ExampleDSCResource'\n  Method        = 'set'\n  Property      = @{\n    property1 = 'value1'\n    property2 = 'value2'\n  }\n  ModuleName = @{\n    ModuleName      = \"C:/puppetlabs/modules/dsc/lib/puppet_x/dsc_resources/ExampleDSCResource/ExampleDSCResource.psd1\"\n    RequiredVersion = \"1.0\"\n  }\n}\n############### SNIP ################\\\nDebug: Waited 100 total milliseconds.\nDebug: Create Dsc Resource returned: {\"rebootrequired\":false,\"indesiredstate\":true,\"errormessage\":\"\"}\nNotice: /Stage[main]/Main/Dsc_exampledscresource[foober]/ensure: created\nDebug: /Stage[main]/Main/Dsc_exampledscresource[foober]: The container Class[Main] will propagate my refresh event\nDebug: Class[Main]: The container Stage[main] will propagate my refresh event\nDebug: Finishing transaction 56434520\nDebug: Storing state\nDebug: Stored state in 0.10 seconds\n############### SNIP ################\n```\n\nThis shows us that there wasn't any problem parsing your manifest and turning it into a command to send to DSC. It also shows that there are two commands/operations for every DSC Resource executed, a SET and a test. DSC operates in two stages, it first tests if a system is in the desired state, then it sets the state of the system to the desired state. You can see the result of each operation in the debug log.\n\nBy using the debug logging of a puppet run, you can troubleshoot the application of DSC Resources during the development of your puppet manifests.\n\n## Development\n\nAcceptance tests for this module leverage [puppet_litmus](https://github.com/puppetlabs/puppet_litmus).\nTo run the acceptance tests follow the instructions [here](https://github.com/puppetlabs/puppet_litmus/wiki/Tutorial:-use-Litmus-to-execute-acceptance-tests-with-a-sample-module-(MoTD)#install-the-necessary-gems-for-the-module).\nYou can also find a tutorial and walkthrough of using Litmus and the PDK on [YouTube](https://www.youtube.com/watch?v=FYfR7ZEGHoE).\n\nIf you run into an issue with this module, or if you would like to request a feature, please [file a ticket](https://tickets.puppetlabs.com/browse/MODULES/).\nEvery Monday the Puppet IA Content Team has [office hours](https://puppet.com/community/office-hours) in the [Puppet Community Slack](http://slack.puppet.com/), alternating between an EMEA friendly time (1300 UTC) and an Americas friendly time (0900 Pacific, 1700 UTC).\n\nIf you have problems getting this module up and running, please [contact Support](http://puppetlabs.com/services/customer-support).\n\nIf you submit a change to this module, be sure to regenerate the reference documentation as follows:\n\n```bash\npuppet strings generate --format markdown --out REFERENCE.md\n```\n\n* The Puppet types are built from the source code of each DSC Resources MOF schema files. If you want to build the types, read the [Building DSC Resources readme](https://github.com/puppetlabs/puppetlabs-dsc/blob/master/README_BUILD.md).\n* If you want the build Puppet types for your own custom DSC Resources, read [Building Puppet Types from Custom DSC Resources](https://github.com/puppetlabs/puppetlabs-dsc/blob/master/README_BUILD.md#building-puppet-types-from-custom-dsc-resources) readme.\n\n### Version Strategy\n\nThis module generally follows [Semantic Versioning](http://semver.org/) for choosing an appropriate release version number with the following exception:\n\n* Minor, for example from version 2.0.0 to 2.1.0\n\nA minor change may also include [rebuilding the DSC resource types](https://github.com/puppetlabs/puppetlabs-dsc/blob/master/README_BUILD.md). Puppet wants to keep pace with the released DSC Resources from the PowerShell team repository, but this engenders risk as Puppet adopts third party code. Normally this would mean making major version bumps, but since this is anticipated to be frequent that would be too much churn.\n\n### Contributors\n\nTo see who's already involved, see the [list of contributors.](https://github.com/puppetlabs/puppetlabs-dsc/graphs/contributors)\n\n## Learn More About DSC\n\nYou can learn more about PowerShell DSC from the following online resources:\n\n- [Microsoft PowerShell Desired State Configuration Overview](https://msdn.microsoft.com/en-us/PowerShell/dsc/overview) - Starting point for DSC topics\n- [Microsoft PowerShell DSC Resources page](https://msdn.microsoft.com/en-us/powershell/dsc/resources) - For more information about built-in DSC Resources\n- [Microsoft PowerShell xDSCResources Github Repo](https://github.com/PowerShell/DscResources) -  For more information about xDscResources\n- [Windows PowerShell Blog](http://blogs.msdn.com/b/powershell/archive/tags/dsc/) - DSC tagged posts from the Microsoft PowerShell Team\n- [Puppet Inc Windows DSC \u0026 WSUS Webinar 9-17-2015 webinar](https://puppet.com/webinars/windows-dsc-wsus-webinar-09-17-2015) - How DSC works with Puppet\n- [Better Together: Managing Windows with Puppet, PowerShell and DSC - PuppetConf 10-2015 talk](https://www.youtube.com/watch?v=TP0zqe-yQto) and [slides](https://speakerdeck.com/iristyle/better-together-managing-windows-with-puppet-powershell-and-dsc)\n- [PowerShell.org](http://powershell.org/wp/tag/dsc/) - Community based DSC tagged posts\n- [PowerShell Magazine](http://www.powershellmagazine.com/tag/dsc/) - Community based DSC tagged posts\n\nThere are several books available as well. Here are some selected books for reference:\n\n- [Learning PowerShell DSC](http://bit.ly/learndsc) - James Pogran is a member of the team here at Puppet Inc working on the DSC/Puppet integration\n- [The DSC Book](https://www.penflip.com/powershellorg/the-dsc-book) - Powershell.org community contributed content\n- [Windows PowerShell Desired State Configuration Revealed](http://www.apress.com/9781484200179) - Ravikanth Chaganti\n\n## License\n\n* Copyright (c) 2014 Marc Sutter, original author\n* Copyright (c) 2015 - Present Puppet Inc\n* License: [Apache License, Version 2.0](https://github.com/puppetlabs/puppetlabs-dsc/blob/master/LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs-toy-chest%2Fpuppetlabs-dsc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpuppetlabs-toy-chest%2Fpuppetlabs-dsc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs-toy-chest%2Fpuppetlabs-dsc/lists"}