xscsma
Documentation
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 v2.1.0.0. The PowerShell module describes itself like this:
Module with DSC Resources for deployment and configuration of Microsoft System Center Service Management Automation.
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_runbookdirectory
: The DSC RunbookDirectory resource type. Automatically generated from version 2.1.0.0dsc_smavariable
: The DSC SmaVariable resource type. Automatically generated from version 2.1.0.0dsc_xscsmapowershellsetup
: The DSC xSCSMAPowerShellSetup resource type. Automatically generated from version 2.1.0.0dsc_xscsmarunbookworkerserversetup
: The DSC xSCSMARunbookWorkerServerSetup resource type. Automatically generated from version 2.1.0.0dsc_xscsmawebserviceserversetup
: The DSC xSCSMAWebServiceServerSetup resource type. Automatically generated from version 2.1.0.0dsc_xsmacredential
: The DSC xSmaCredential resource type. Automatically generated from version 2.1.0.0
Resource types
dsc_runbookdirectory
The DSC RunbookDirectory resource type. Automatically generated from version 2.1.0.0
Properties
The following properties are available in the dsc_runbookdirectory
type.
dsc_ensure
Data type: Enum['Published', 'Draft', 'Absent']
The import state of runbooks found at RunbookPath. This can be Published, Draft, or Absent
dsc_matches
Data type: Optional[Boolean]
Describes the validity of the imported Runbook(s).
dsc_port
Data type: Optional[Integer[0, 4294967295]]
Port of the SMA web site. Defaults to the SMA default of 9090.
Parameters
The following parameters are available in the dsc_runbookdirectory
type.
dsc_psdscrunascredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
dsc_runbookpath
namevar
Data type: String
Path to Runbook(s) to be imported. Accepts wildcards.
dsc_webserviceendpoint
namevar
Data type: String
URL of SMA's web service endpoint.
name
namevar
Data type: String
Description of the purpose for this resource declaration.
dsc_smavariable
The DSC SmaVariable resource type. Automatically generated from version 2.1.0.0
Properties
The following properties are available in the dsc_smavariable
type.
dsc_description
Data type: Optional[String]
Description of SMA variable.
dsc_ensure
Data type: Enum['Present', 'Absent']
Desired state of SMA variable
dsc_port
Data type: Optional[Integer[0, 4294967295]]
Port to reach the web service endpoint. Defaults to the SMA default of 9090.
dsc_set
Data type: Optional[Boolean]
Set is true if existing SMA variable matches configuration.
dsc_value
Data type: String
Value of SMA variable.
Parameters
The following parameters are available in the dsc_smavariable
type.
dsc_name
namevar
Data type: String
Name of SMA variable.
dsc_psdscrunascredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
dsc_webserviceendpoint
namevar
Data type: String
Web service endpoint of SMA instance.
name
namevar
Data type: String
Description of the purpose for this resource declaration.
dsc_xscsmapowershellsetup
The DSC xSCSMAPowerShellSetup resource type. Automatically generated from version 2.1.0.0
Properties
The following properties are available in the dsc_xscsmapowershellsetup
type.
dsc_sourcefolder
Data type: Optional[String]
Folder within the source path containing the source files for installation.
dsc_sourcepath
Data type: String
UNC path to the root of the source files for installation.
Parameters
The following parameters are available in the dsc_xscsmapowershellsetup
type.
dsc_ensure
namevar
Data type: Enum['Present', 'Absent']
An enumerated value that describes if SMA PowerShell is expected to be installed on the machine. Present {default}
Absent
dsc_psdscrunascredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
dsc_setupcredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
Credential to be used to perform the installation.
name
namevar
Data type: String
Description of the purpose for this resource declaration.
dsc_xscsmarunbookworkerserversetup
The DSC xSCSMARunbookWorkerServerSetup resource type. Automatically generated from version 2.1.0.0
Properties
The following properties are available in the dsc_xscsmarunbookworkerserversetup
type.
dsc_etwmanifest
Data type: Optional[String]
Log to ETW.
dsc_installfolder
Data type: Optional[String]
Installation folder for SMA.
dsc_logmsiinstall
Data type: Optional[String]
Set to activate logging during install of MSI.
dsc_msilogname
Data type: Optional[String]
Logfile name for MSI install.
dsc_msilogpath
Data type: Optional[String]
Path to log file for MSI install.
dsc_msupdate
Data type: Optional[String]
Use Microsoft Update.
dsc_productkey
Data type: Optional[String]
Product key for licensed installations.
dsc_sendtelemetryreports
Data type: Optional[String]
Usage and Diagnostics Data sent to Microsoft.
dsc_serviceusername
Data type: Optional[String]
Output username of the Service account of the web service application pool.
dsc_sourcefolder
Data type: Optional[String]
Folder within the source path containing the source files for installation.
dsc_sourcepath
Data type: String
UNC path to the root of the source files for installation.
dsc_sqldatabase
Data type: Optional[String]
Name of the SMA database.
dsc_sqlinstance
Data type: String
Name of the SQL Instance for the SMA database.
dsc_sqlserver
Data type: String
Name of the SQL Server for the SMA database.
Parameters
The following parameters are available in the dsc_xscsmarunbookworkerserversetup
type.
dsc_ensure
namevar
Data type: Enum['Present', 'Absent']
An enumerated value that describes if the SMA Runbook Worker server is expected to be installed on the machine. Present {default} Absent
dsc_psdscrunascredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
dsc_service
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
Service account of the web service application pool.
dsc_setupcredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
Credential to be used to perform the installation.
name
namevar
Data type: String
Description of the purpose for this resource declaration.
dsc_xscsmawebserviceserversetup
The DSC xSCSMAWebServiceServerSetup resource type. Automatically generated from version 2.1.0.0
Properties
The following properties are available in the dsc_xscsmawebserviceserversetup
type.
dsc_admingroupmembers
Data type: Optional[String]
A comma-separated list of users to add to the IIS Administrators group.
dsc_appoolusername
Data type: Optional[String]
Output username of the web service application pool.
dsc_certificatename
Data type: Optional[String]
Name of the existing certificate to use.
dsc_etwmanifest
Data type: Optional[String]
Log to ETW.
dsc_firstwebserviceserver
Data type: Boolean
Is this the first Management Server?
dsc_installfolder
Data type: Optional[String]
Installation folder for SMA.
dsc_logmsiinstall
Data type: Optional[String]
Set to activate logging during install of MSI.
dsc_msilogname
Data type: Optional[String]
Logfile name for MSI install.
dsc_msilogpath
Data type: Optional[String]
Path to log file for MSI install
dsc_msupdate
Data type: Optional[String]
Use Microsoft Update.
dsc_productkey
Data type: Optional[String]
Product key for licensed installations.
dsc_runbookworkerservers
Data type: Optional[Array[String]]
Array of Runbook Worker servers in this deployment.
dsc_sendtelemetryreports
Data type: Optional[String]
Usage and Diagnostics Data sent to Microsoft.
dsc_sitename
Data type: Optional[String]
Name of the SMA web site.
dsc_sourcefolder
Data type: Optional[String]
Folder within the source path containing the source files for installation.
dsc_sourcepath
Data type: String
UNC path to the root of the source files for installation.
dsc_specifycertificate
Data type: Optional[String]
Specify an existing certificate for the SMA web site.
dsc_sqldatabase
Data type: Optional[String]
Name of the SMA database.
dsc_sqlinstance
Data type: String
Name of the SQL Instance for the SMA database.
dsc_sqlserver
Data type: String
Name of the SQL Server for the SMA database.
dsc_usessl
Data type: Optional[String]
Use SSL?
dsc_webserviceport
Data type: Optional[Integer[0, 65535]]
Port of the SMA web site.
Parameters
The following parameters are available in the dsc_xscsmawebserviceserversetup
type.
dsc_appool
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
Service account of the web service application pool.
dsc_ensure
namevar
Data type: Enum['Present', 'Absent']
An enumerated value that describes if the SMA Web Service server is expected to be installed on the machine. Present {default} Absent
dsc_psdscrunascredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
dsc_setupcredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
Credential to be used to perform the installation.
name
namevar
Data type: String
Description of the purpose for this resource declaration.
dsc_xsmacredential
The DSC xSmaCredential resource type. Automatically generated from version 2.1.0.0
Properties
The following properties are available in the dsc_xsmacredential
type.
dsc_description
Data type: Optional[String]
Description of credential.
dsc_port
Data type: Optional[Integer[0, 4294967295]]
Port to reach the web service endpoint.
dsc_username
Data type: Optional[String]
User name of credential found within SMA
dsc_webserviceendpoint
Data type: String
Web service endpoint of SMA instance.
Parameters
The following parameters are available in the dsc_xsmacredential
type.
dsc_credential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
Credential object to be imported.
dsc_name
namevar
Data type: String
Name of credential.
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.
- Update appveyor.yml to use the default template.
- Added default template files .codecov.yml, .gitattributes, and .gitignore, and .vscode folder.
- Closed issue 29 - Web bindings fail due to hardcoded WSE
- Switched from Get-WmiObject Win32_Product to Get-ItemProperty for identifer number
Dependencies
- puppetlabs/pwshlib (>= 0.7.0 < 2.0.0)