dsccommunity/xscsma

xSCSMA

The xSCSMA module contains DSC resources for installation of System Center Service Management Automation (SMA).

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Contributing

Please check out common DSC Resources contributing guidelines.

Resources

• xSCSMAPowerShellSetup installs SMA PowerShell
• xSCSMAWebServiceServerSetup installs an SMA Web Service server
• xSCSMARunbookWorkerServerSetup installs an SMA Runbook Worker server
• xRunbookDirectory imports Runbook(s) to an SMA instance
• xSmaVariable Imports SMA variable to an SMA instance
• xSmaCredential Imports SMA Credentials to an SMA instance

xSCSMAPowerShellSetup

• Ensure: (Key) Ensures that the SMA PowerShell components are Present or Absent on the machine.
• SourcePath: (Required) UNC path to the root of the source files for installation.
• SourceFolder: Folder within the source path containing the source files for installation.
• SetupCredential: (Required) Credential to be used to perform the installation.

xSCSMAWebServiceServerSetup

Used for installation of the SMA Web Service server.

• Ensure: (Key) Ensures that the SCSCMA Web Service server components are Present or Absent on the machine.
• SourcePath: (Required) UNC path to the root of the source files for installation.
• SourceFolder: Folder within the source path containing the source files for installation.
• SetupCredential: (Required) Credential to be used to perform the installation.
• FirstWebServiceServer: (Required) Binary value defining if this the first Management Server
• ApPool: (Required) Service account of the web service application pool.
• ApPoolUsername: Output user name of the web service application pool.
• AdminGroupMembers: A comma-separated list of users to add to the IIS Administrators group.
• SqlServer: (Required) Name of the SQL Server for the SMA database.
• SqlInstance: (Required) Name of the SQL Instance for the SMA database.
• SqlDatabase: Name of the SMA database.
• SiteName: Name of the SMA website.
• WebServicePort: Port of the SMA website.
• InstallFolder: Installation folder for SMA.
• UseSSL: { Yes | No } Defining whether or not to use SSL. Default value is Yes.
• SpecifyCertificate: { Yes | No } Specify an existing certificate for the SMA web site. Default value is No.
• CertificateName: Name of the existing certificate to use.
• ETWManifest: { Yes | No } Log to ETW. Default value is Yes.
• SendTelemetryReports: { Yes | No } Usage and Diagnostics Data sent to Microsoft. Default value is No.
• MSUpdate: { Yes | No } Opt in to Microsoft Update. Default value is No.
• ProductKey: Product key for licensed installations.
• RunbookWorkerServers: Array of Runbook Worker servers in this deployment.
• LogMsiInstall: Controlls if MSI installation is logged {True | False}.
• MsiLogPath: Path to put MSI logfile in.
• MsiLogName: Name of MSI log file.

xSCSMARunbookWorkerServerSetup

• Ensure: (Key) Ensures that the SMA Runbook Worker server is Present or Absent on the machine.
• SourcePath: (Required) UNC path to the root of the source files for installation.
• SourceFolder: Folder within the source path containing the source files for installation.
• SetupCredential: (Required) Credential to be used to perform the installation.
• Service: (Required) Service account of the web service application pool.
• ServiceUserName: Output user name of the Service account of the web service application pool.
• SqlServer: (Required) Name of the SQL Server for the SMA database.
• SqlInstance: (Required) Name of the SQL Instance for the SMA database.
• SqlDatabase: Name of the SMA database.
• InstallFolder: Installation folder for SMA.
• ETWManifest: { Yes | No } Log to ETW. Default value is Yes.
• SendTelemetryReports: { Yes | No } Usage and Diagnostics Data sent to Microsoft. Default value is No.
• MSUpdate: { Yes | No } Opt in to Microsoft Update. Default value is No.
• ProductKey: Product key for licensed installations.
• LogMsiInstall: Controlls if MSI installation is logged {True | False}.
• MsiLogPath: Path to put MSI logfile in.
• MsiLogName: Name of MSI log file.

xRunbookDirectory

Imports runbook(s) into an SMA instance. The Workflow name is expected to match the name of the ps1, and will become the name of the Runbooks.

• RunbookPath: (Key) Path to Runbook(s) to be imported. Accepts wildcards.
• Ensure: (Required) The import state of runbooks found at RunbookPath. This can be Published, Draft, or Absent.
• WebServiceEndpoint: (Key) The web service endpoint of the SMA instance to import the Runbook too.
• Port: Port to reach the web service endpoint. Default value is 9090.

xSmaVariable

• Ensure (Required) Ensures that the SMA variable is Present or Absent at the web service endpoint.
• Name (Key) Name of variable.
• Value (Required) Value of variable.
• Description Description of variable.
• WebServiceEndpoint (Key) Web service endpoint of SMA instance.
• Port Port to reach the web service endpoint. Default value is 9090.

xSmaCredential

• Name (Key) Name of credential.
• Credential (Required) Credential object to be imported.
• Description Description of credential.
• WebServiceEndpoint (Required) Web service endpoint of SMA instance.
• Port Port to reach the web service endpoint.

Versions

Unreleased

2.1.0.0

• 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

2.0.0.0

• Added MSI install logging for MSFT_xSCSMARunbookWorkerServerSetup and MSFT_xSCSMARunbookWorkerServerSetup
• Added missing -Port parameter argument for New-SmaRunbookWorkerDeployment in MSFT_xSCSMARunbookWorkerServerSetup
• Fixed MSFT_xSCSMARunbookWorkerServerSetup and MSFT_xSCSMAWebServiceServerSetup using incorrect executable for version checking
• Remove System Center Technical Preview 5 support. Close issue #18
• Close issue #19 (always install self-signed certificate)
• BREAKING CHANGE: change SendCEIPReports parameter to SendTelemetryReports. Close issue #20
• Added description for new parameters at README.md
• Fix return state of the current SendTelemetryReports
• Fix syntax at source code

1.5.0.0

• Added $IdentifyingNumber for TP5/RTM and small WMI improvements

1.4.0.0

• Converted appveyor.yml to install Pester from PSGallery instead of from Chocolatey.

• Added new example to show how to use xRunbookDirectory to remove all SMA sample Runbooks

• Added new resource xSmaCredential.

1.3.0.0

• Added new resource to manage a single or directory of Runbooks, xRunbookDirectory.
• Added xSmaVariable resource.

1.2.1.0

• Increased timeout for setup process to start to 60 seconds.
• xSCSMAWebServiceServerSetup
  • Fixed bug when using named SQL instance
  • Added SMA service account to admin group.
• xSCSMARunbookWorkerSetup
  • Fixed bug when using named SQL instance.

1.1.0.0

• Initial release with the following resources:
  • xSCSMAPowerShellSetup
  • xSCSMAWebServiceServerSetup
  • xSCSMARunbookWorkerServerSetup

Examples

Three example configurations are included in the Examples folder. All three examples also use the xSQLServer module.

Single Server Installation

SCSMA-SingleServer.ps1 installs all SMA roles including prerequisites and SQL on a single server.

Separate SQL

SCSMA-SeperateSQL.ps1 installs all SMA roles on one server and SQL on a separate server.

Multiple Instances

SCSMA-MultiInstance.ps1 installs all SMA roles including multiple instances of both Web Service and Runbook Worker servers and SQL on a separate server.

Remove Sample Runbooks

RemoveSampleRunbooks.ps1 removes SMA's default sample Runbooks.

Runbook Directory

RunbookDirectory.ps1 imports all Runbooks found in a directory that start with the name "Start-" and publishes them.

SMA Variable

SmaVariable.ps1 adds a variable named "Variable" with value "Value"

Notes:

The Single Server Installation, Separate SQL, and Multiple Instances examples use the exact same Configuration and just modify the behavior based on input ConfigurationData.

In the Examples folder you will see a version of each file with "-TP" appended to the name. These are the equivalent examples for deployment of System Center Technical Preview on Windows Server Technical Preview.

The samples require the use of the Windows Management Framework (WMF) 5.0 Preview.

System Center 2012 R2 Service Management Automation Web Service and Runbook Worker installers have a hard check for PowerShell 4.0. If you are using these resources to install on a system that has WMF 5.0 preview installed, you must copy the transform (MST) files from the Web Service and Runbook Worker DSC resource folders to the SMA installation folder.

xscsma's Issues

Failed SMA install, rollback does not uninstall SQL database

ISSUE TITLE: MSFT_xSCSMAWebServiceServerSetup SMA install fails, every other time resource fails because of existing database

ISSUE DESCRIPTION:
SMA install fails for various reasons and is the FirstWebServiceServer. The next time DSC runs it will fail because the database is already created. The rollback of the install does not seem to remove the database. 

Details of the scenario you tried and the problem that is occurring

SMA install was failing. Fixed the website folder issue and ran DSC again.
Once it ran again the resource would fail with a generic error, "Set-TargetResource failed". Looking in the logs it was failing because the database was already created.

Deleted the database, ran DSC again and SMA installed.

Verbose logs showing the problem

Suggested solution to the issue

It may be possible to delete the database on a fail install so that the database is no longer there on sequential runs.

The DSC configuration that is used to reproduce the issue (as detailed as possible)

N/A but FirstWebServiceServer is set to True

The operating system the target node is running

OsName : Microsoft Windows Server 2012 R2 Standard
OsOperatingSystemSKU : StandardServerEdition
OsArchitecture : 64-bit
WindowsBuildLabEx : 9600.19358.amd64fre.winblue_ltsb_escrow.190505-1600
OsLanguage : en-US
OsMuiLanguages : {en-US}

Version and build of PowerShell the target node is running

Name Value
PSVersion 5.1.14409.1018
PSEdition Desktop
PSCompatibleVersions {1.0, 2.0, 3.0, 4.0...}
BuildVersion 10.0.14409.1018
CLRVersion 4.0.30319.42000
WSManStackVersion 3.0
PSRemotingProtocolVersion 2.3
SerializationVersion 1.1.0.1

Version of the DSC module that was used ('dev' if using current dev branch)

dev

Wrong path in MSFT_xSCSMARunbookWorkerServerSetup.psm1

On line 56 & 176:
$Path = Join-Path -Path (Join-Path -Path $SourcePath -ChildPath $SourceFolder) -ChildPath "\SMA\WebServiceSetup.exe"

As this is the setup for RunbookWorker I asume this should be:
"\SMA\WorkerSetup.exe"

Avoid using the Win32_Product WMI class

This repository has reference to Win32_Product WMI class. As reported in issue PowerShell/DscResources#108, if possible then avoid using the Win32_Product.

If you are using a group policy with the WMIFilter that queries Win32_Product, modify the filter to use Win32reg_AddRemovePrograms
...
Win32reg_AddRemovePrograms is a much lighter and effective way to do this, which avoids the calls to do a resiliency check, especially in a locked down environment. So when using Win32reg_AddRemovePrograms we will not be calling on msiprov.dll and will not be initiating a resiliency check.
https://support.microsoft.com/en-us/kb/974524

There might not be possible to avoid using it, but for someone to determine that an issue is opened in very repository that has a reference to Win32_Product WMI class.

Unknown version numbers?!

I'm a bit mystified by your version numbers in MSFT_xSCSMAPowerShellSetup.
When I download System Center 2016 Orchestrator from MVLS, the version I get for SetupOrchestrator.exe is 7.3.149.0?!? (the other resources are correct - e.g. 7.3.345.0)

Best,
-Brian

xSCSMA: Converting to new CI pipeline

Work need to be done to convert this repository to use the new CI pipeline.

https://dsccommunity.org/blog/convert-a-module-for-continuous-delivery/

Examples for installing SMA using SC2016

Hey,
Can you post some examples of DSC configuration scripts for installing SMA using System Center Orchestrator 2016?

Wrong path in MSFT_xSCSMAWebServiceServerSetup.psm1

On line 81 & 236:
$Path = Join-Path -Path (Join-Path -Path $SourcePath -ChildPath $SourceFolder) -ChildPath "\SMA\WorkerSetup.exe"

As this is the setup for RunbookWorker I asume this should be:
"\SMA\WebServiceSetup.exe"

System Center 2016 use SendTelemetryReports instead SendCEIPReports

When installing WebServiceInstaller.msi and WorkerInstaller.msi, use 'SendCEIPReports' parameter with System Center 2012 R2 and 'SendTelemetryReports' parameter with System Center 2016.

System Center 2016 command line parameters

Incorporate changes from robwi repo

Additions have been made to this module in a separate repo:
https://github.com/robwi/xSCSMA

HELP WANTED

If someone would like to review this work and incorporate changes back to the resource kit as a new PR, that would be a great project.

xSCSMAWebServiceServerSetup: always install self-signed certificate

1. 'SpecifyCertificate' parameter isn't transferred when installing WebServiceInstaller.msi. Default is 'No'.
2. Using 'CertificateSerialNumber' instead of 'CertificateSerial'.
3. Hard-coded 'UseSSL=Yes' when install MSI.

Install Service Management Automation from a Command Prompt window

Add a resource for loading credentials

BLOCKER: PSSA Errors Need to Be Fixed

Errors from PS script analyzer are causing the tests to fail like this.
This resource module cannot be released until these errors are fixed or suppressed and the tests are passing.

MSFT_xSCSMAWebServiceServerSetup: 'https://localhost' hardcoded in the Get/Set/Test functions, which breaks the resource when trying to set bindings

Details of the scenario you tried and the problem that is occurring

When attempting to harden the SMA IIS site by specifying the hostname and IP address for the site's bindings after the service is installed, the resource fails when executing Get/New-SmaRunbookWorkerDeployment, because the Web Service Endpoint is hardcoded in the resource as https://localhost (and does not specify the port either).

Verbose logs showing the problem

Suggested solution to the issue

I managed to solve the problem by replacing the hard-coded value with the $CertificateName variable value, which is ($env:COMPUTERNAME + "." + (Get-WmiObject -Class Win32_ComputerSystem).Domain) by default, which could become problematic on a non-domain deployment. There will need to be logic added to check for domain first, with error handling to attempt the hard-coded value (https://localhost) as a last resort.

The DSC configuration that is used to reproduce the issue (as detailed as possible)

xSCSMAWebServiceServerSetup SMAWebService
{
    Ensure = 'Present'
    SourcePath = 'C:\source'
    SourceFolder = 'SystemCenter2016'
    FirstWebServiceServer = $true
    ApPool = $SMAWebServiceAccount
    SqlServer = 'SQL'
    SqlInstance = 'SMA'
    SqlDatabase = 'SMA'
    RunbookWorkerServers = 'SQL'
    InstallFolder = 'C:\Program Files\Microsoft System Center 2016\Orchestrator\Web Service'
    SpecifyCertificate = 'Yes'
    PsDscRunAsCredential = $ServerAdmin
    DependsOn = '[xSCSMAPowerShellSetup]SMAPowerShell'
}

xWebsite SMABinding
{
    Name = 'SMA'
    State = 'Started'
    BindingInfo = MSFT_xWebBindingInformation 
    {
        Protocol              = 'HTTPS'
        CertificateThumbprint = $certThumbprint
        CertificateStoreName  = 'My'
        Port                  = '9090'
        HostName              = "$ComputerName.$DomainName"
        IPAddress             = $BindingIPaddress
    }
    DependsOn = '[xSCSMAWebServiceServerSetup]SMAWebService'
}

The operating system the target node is running

OsName               : Microsoft Windows Server 2012 R2 Standard
OsOperatingSystemSKU : StandardServerEdition
OsArchitecture       : 64-bit
WindowsBuildLabEx    : 9600.17415.amd64fre.winblue_r4.141028-1500
OsLanguage           : en-US
OsMuiLanguages       : {en-US}

Version and build of PowerShell the target node is running

Name                           Value                                                                                                                              
----                           -----                                                                                                                              
PSVersion                      5.1.14409.1005                                                                                                                     
PSEdition                      Desktop                                                                                                                            
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0...}                                                                                                            
BuildVersion                   10.0.14409.1005                                                                                                                    
CLRVersion                     4.0.30319.34014                                                                                                                    
WSManStackVersion              3.0                                                                                                                                
PSRemotingProtocolVersion      2.3                                                                                                                                
SerializationVersion           1.1.0.1 

Version of the DSC module that was used ('dev' if using current dev branch)

dev