Table of Contents

1. Description
2. Requirements
3. Usage
4. Troubleshooting

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 v1.0.0.0. The PowerShell module describes itself like this:

This module can be used to manage configuration of a Windows Event Forwarding server in a Colelctor role.

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:

1. Problems with the way the underlying DSC resource works.
2. Problems with the type definition, where you can't specify a valid set of properties for the DSC resource
3. 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_xwefcollector: The DSC xWEFCollector resource type. Automatically generated from version 1.0.0.0
• dsc_xwefsubscription: The DSC xWEFSubscription resource type. Automatically generated from version 1.0.0.0

Resource types

dsc_xwefcollector

The DSC xWEFCollector resource type. Automatically generated from version 1.0.0.0

Properties

The following properties are available in the dsc_xwefcollector type.

dsc_ensure

Data type: Optional[Enum['Present', 'Absent']]

Determines whether the Collector service should be enabled or disabled

Parameters

The following parameters are available in the dsc_xwefcollector type.

dsc_name

namevar

Data type: String

Provide a unique name for the setting

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_xwefsubscription

The DSC xWEFSubscription resource type. Automatically generated from version 1.0.0.0

Properties

The following properties are available in the dsc_xwefsubscription type.

dsc_address

Data type: Optional[Array[String]]

Expects an array of source node FQDNs, default source.wef.test to prevent errors when only staging test subscription

dsc_allowedsourcedomaincomputers

Data type: Optional[String]

In Source Initiated scenario this SDDL determines who can push events, default O:NSG:NSD:(A;;GA;;;DC)(A;;GA;;;NS) which equates to Domain Computers and Network Service

dsc_allowedsourcenondomaincomputers

Data type: Optional[Array[String]]

This parameter has not been fully implemented, only required for source initiated scenarios, provide XML to set IssuerCAList, AllowedSubjectList, or DeniedSubjectList if this will be used, default empty string

dsc_contentformat

Data type: Optional[String]

Format that event logs will be submitted in, default RenderedText

dsc_credentialstype

Data type: Optional[Enum['Default', 'Basic', 'Negotiate', 'Digest']]

Sets the credential type used for authenticating to WinRM, default Default

dsc_deliverymode

Data type: Optional[Enum['Push', 'Pull']]

Configures whether the collector will pull events from source nodes or if the source nodes will push events to the collector, default push

dsc_description

Data type: Optional[String]

Description of the Collector subscription

dsc_enabled

Data type: Optional[Enum['true', 'false']]

Sets whether the subscription will be enabled, default true

dsc_ensure

Data type: Optional[Enum['Present', 'Absent']]

Determines whether to validate or remove the scubscription

dsc_heartbeatinterval

Data type: Optional[Integer[0, 18446744073709551615]]

Frequency to verify connectivity, default 20000

dsc_locale

Data type: Optional[String]

Sets the subscription Locale, default en-US

dsc_logfile

Data type: Optional[String]

Sets the event log that the collected events will be written to, default ForwardedEvents

dsc_maxitems

Data type: Optional[Integer[-2147483648, 2147483647]]

The number of events that can occur on the source before they are submitted to the collector, default 1

dsc_maxlatencytime

Data type: Optional[Integer[0, 18446744073709551615]]

The maximum amount of time that can pass before events are submitted to the collector, default 20000

dsc_query

Data type: Optional[Array[String]]

Expects an array of hashtables that set which events should be collected, default is all application and system logs

dsc_readexistingevents

Data type: Optional[Enum['true', 'false']]

Should the collector read existing or only new events, default false

dsc_subscriptiontype

Data type: Enum['CollectorInitiated', 'SourceInitiated']

Type of Subscription to create

dsc_transportname

Data type: Optional[Enum['HTTP', 'HTTPS']]

Determines whether to require SSL, default HTTP

dsc_transportport

Data type: Optional[String]

Set the port number that WinRM should use to make a connection, default 5985

Parameters

The following parameters are available in the dsc_xwefsubscription type.

dsc_psdscrunascredential

Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]

dsc_subscriptionid

namevar

Data type: String

Name of the Subscription

name

namevar

Data type: String

Description of the purpose for this resource declaration.

Changelog

All notable changes to this project will be documented in this file.

Release 0.1.0

Features

Bugfixes

Known Issues