Giter Site home page Giter Site logo

dsccommunity / wsmandsc Goto Github PK

View Code? Open in Web Editor NEW
18.0 4.0 8.0 342 KB

DSC resources for configuring WS-Management and PowerShell Remoting.

Home Page: https://dsccommunity.org

License: MIT License

PowerShell 100.00%
dsc-resources ws-man-listener ws-man-service powershell-dsc powershell-remoting dsc

wsmandsc's Introduction

WSManDsc

Build Status Code Coverage Azure DevOps tests PowerShell Gallery (with prereleases) PowerShell Gallery codecov

The WSManDsc module contains DSC resources for configuring WS-Management and PowerShell Remoting.

  • WSManListener: Create, edit or remove WS-Management HTTP/HTTPS listeners.
  • WSManConfig: Configure general WS-Man settings.
  • WSManServiceConfig: Configure the WS-Man Service.

Code of Conduct

This project has adopted this Code of Conduct.

Releases

For each merge to the branch main a preview release will be deployed to PowerShell Gallery. Periodically a release version tag will be pushed which will deploy a full release to PowerShell Gallery.

Contributing

Please check out common DSC Community contributing guidelines.

Quality

This module should meet the PowerShell DSC Resource Kit High Quality Resource Module Guidelines.

Documentation and Examples

For a full list of resources in WSManDsc and examples on their use, check out the WSManDsc wiki.

Change log

A full list of changes in each version can be found in the change log.

wsmandsc's People

Contributors

corydwood avatar dscbot avatar johlju avatar plagueho avatar x-guardian avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar

wsmandsc's Issues

Set Optional Failure Flags for all PSSA Tests

Add the following opt-in settings to enable CI failure on violation of these PSSA rule types:

  • Common Tests - Required Script Analyzer Rules
  • Common Tests - Flagged Script Analyzer Rules
  • Common Tests - New Error-Level Script Analyzer Rules
  • Common Tests - Custom Script Analyzer Rules

Update CI Pipeline Files from Latest Pattern

Copy the latest patterns for the build.yml, build.ps1 and azure-pipelines.yml from the PR:
dsccommunity/ExchangeDsc#471

build.yml

####################################################
#      DscResource.DocGenerator Configuration      #
####################################################
DscResource.DocGenerator:
  Generate_Conceptual_Help:
    MarkdownCodeRegularExpression:
      - '\`(.+?)\`' # Match inline code-block
      - '\\(\\)' # Match escaped backslash
      - '\[[^\[]+\]\((.+?)\)' # Match markdown URL
      - '_(.+?)_' # Match Italic (underscore)
      - '\*\*(.+?)\*\*' # Match bold
      - '\*(.+?)\*' # Match Italic (asterisk)
  publish:
    - publish_module_to_gallery
    - Publish_Release_To_GitHub
    - Publish_GitHub_Wiki_Content
    - Create_ChangeLog_GitHub_PR
  • Also add updated issue templates and related files:
  • .github\ISSUE_TEMPLATE
  • .github\CONTRIBUTING.md
  • .github\PULL_REQUEST_TEMPLATE.md
  • .github\ISSUE_TEMPLATE\General.md
  • .github\ISSUE_TEMPLATE\Problem_with_resource.yml
  • .github\ISSUE_TEMPLATE\Resource_proposal.yml
  • .github\ISSUE_TEMPLATE\config.yml

Add SECURITY.md as well.

Also, update GitVersion task.

Fix Build Failures due to Pester 5.x

Pester 5.x has been released and both Sampler and DSCResource.Test has been updated to support it, however, Code Coverage support is not available. To solve this, pin Pester to 4.10.1.

Update GitVersion.yml to use latest pattern

Update GitVersion.yml branches section to:

branches:
  master:
    tag: preview
    regex: ^main$
  pull-request:
    tag: PR
  feature:
    tag: useBranchName
    increment: Minor
    regex: f(eature(s)?)?[\/-]
    source-branches: ['master']
  hotfix:
    tag: fix
    increment: Patch
    regex: (hot)?fix(es)?[\/-]
    source-branches: ['master']

As per: dsccommunity/dsccommunity.org#162

Enable Override of HostName in WSManListener

From Issue #8 raised by @ttdgcp:

I've been testing with the latest version you've released, and am seeing the following error when using a certificate thumbprint:
The WinRM client cannot process the request. The certificate CN and the hostname that were provided do not match.

I am using the following configuration:
Ensure = "Present"
Transport = "HTTPS"
CertificateThumbprint = "$thumbprinthere"

I believe this is because I cannot specify (and write) the HostName parameter that the WinRM client demands. If we could add the hostname parameter to be able to write, I believe that would solve my use case.

We're able to bind the certificate to a WSMan listener with the following command:
New-WSManInstance winrm/config/Listener -SelectorSet @{ Address="*";Transport="HTTPS"} -ValueSet @{Hostname="devOps";CertificateThumbprint=$thumbprint}

It's certainly a bit unorthodox, but it fits our use case.

Let me know if I can help any further- thank you for supporting this!

WSManListener: Incorrect Find-Certificate Verbose Messages

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

The following verbose messages in the Find-Certificate function of the WSManListener resource have got the issuer and subject parameters transposed.

  • FindCertificateMessage
  • FindCertificateAlternateMessage

Verbose logs showing the problem

[[WSManListener]DirectResourceAccess] Find-Certificate: Looking for machine server certificate with subject 'Issuer' issued by 'CN=T1MS02-EUW1S'.

Suggested solution to the issue

Swap the $Issuer and $Subject parameters of the relevant Write-Verbose commands in the Find-Certificate function.

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

Invoke-DscResource -Name WSManListener -ModuleName WSManDsc -Method Set -Property @{Transport='https';Ensure='Present';Issuer='Issuer'} -Verbose

The operating system the target node is running

OsName               : Microsoft Windows Server 2019 Datacenter
OsOperatingSystemSKU : DatacenterServerEdition
OsArchitecture       : 64-bit
WindowsVersion       : 1809
WindowsBuildLabEx    : 17763.1.amd64fre.rs5_release.180914-1434
OsLanguage           : en-US
OsMuiLanguages       : {en-US}

Version and build of PowerShell the target node is running

Name                           Value
----                           -----
PSVersion                      5.1.17763.771
PSEdition                      Desktop
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0...}
BuildVersion                   10.0.17763.771
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)

ModuleType Version    Name                                ExportedCommands
---------- -------    ----                                ----------------
Manifest   2.4.1.173  WSManDsc

xWSManConfig Resource to manage winrm/config

Hi, it seems very nice if there are xWSManConfig resource to manage winrm/config.

There are some circumstance that exceed max envelope size with DSC, Test-DscConfiguration or others. One possible solution is just double limitation but it should be better make it so with DSC.

Set-WSManInstance -ValueSet @{MaxEnvelopeSizekb = "1000"} -ResourceURI winrm/config

WSManListener for HTTPS should support certificates using a DN as the subject

The code for WSManListener assumes that the certificate's subject will only contain the CN of the server (e.g. CN=server.mydomain.local). Some organizations issue certificates with a DN as the subject (eg. CN=server.mydomain.local, O=Some Company, ST=Pennsylvania, C=US).

Can this resource be updated to support this scenario?

WSManListener parameter DN should be BaseDN

In X.500 parlance, the Distinguished Name (DN) is the fully-qualified object path.1,2 For example, CN=example.com, O=IANA, C=US is a DN. In the WSManListener resource, however, the DN parameter specifies only the path part, O=IANA, C=US, better known as the Base DN.2,3 Misnamed parameters like this create cognitive dissonance and poor usability. The documentation should be updated to note that it references the Base DN, not a DN, and the parameter name should be updated to BaseDN.

On a personal note/to give a real-world example, this has cost me time and frustration. I initially ignored the parameter because of the documentation, but when it didn't work I had to trace the code to find the problem. It's difficult for me to submit patches due to my job's legal requirements, but let me know if you have any questions.

WsManListener: does not overwrite Hostname/CertificateThumbprint

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

We are using this module in order to configure the WinRM HTTPS listener in an unorthodox manner-- utilizing a self-signed certificate with the same "Hostname" across all machines. This has worked well for us!

What I have discovered is that if we the HTTPS listener is already configured with a different certificate/hostname, the DSC resource will not overwrite the existing listener with the specified hostrname/thumbprint.

The DSC configuration that is using the resource (as detailed as possible):

In this case, we are using DSC within Chef-- but the same action occurs when using vanilla DSC:

  resource :WSManListener
  property :Transport, 'HTTPS'
  property :Ensure, 'Present'
  property :CertificateThumbprint, node['winrm']['certificate']['thumbprint']
  property :Hostname, 'Hostname'
end

In order to replicate:

Configure WinRM HTTPS listener with a self-signed certificate:

Remove-Item -Path WSMan:\Localhost\listener\listener* -Recurse

Set-Item WSMan:\localhost\MaxTimeoutms 1800000
Set-Item WSMan:\localhost\Service\Auth\Basic $true

$Cert = New-SelfSignedCertificate -CertstoreLocation Cert:\LocalMachine\My -DnsName "packer"
New-Item -Path WSMan:\LocalHost\Listener -Transport HTTPS -Address * -CertificateThumbPrint $Cert.Thumbprint -Force

# WinRM
write-output "Setting up WinRM"
write-host "(host) setting up WinRM"

cmd.exe /c winrm quickconfig -q
cmd.exe /c winrm set "winrm/config" '@{MaxTimeoutms="1800000"}'
cmd.exe /c winrm set "winrm/config/winrs" '@{MaxMemoryPerShellMB="1024"}'
cmd.exe /c winrm set "winrm/config/service" '@{AllowUnencrypted="true"}'
cmd.exe /c winrm set "winrm/config/client" '@{AllowUnencrypted="true"}'
cmd.exe /c winrm set "winrm/config/service/auth" '@{Basic="true"}'
cmd.exe /c winrm set "winrm/config/client/auth" '@{Basic="true"}'
cmd.exe /c winrm set "winrm/config/service/auth" '@{CredSSP="true"}'
cmd.exe /c winrm set "winrm/config/listener?Address=*+Transport=HTTPS" "@{Port=`"5986`";Hostname=`"packer`";CertificateThumbprint=`"$($Cert.Thumbprint)`"}"
cmd.exe /c netsh advfirewall firewall set rule group="remote administration" new enable=yes
cmd.exe /c netsh firewall add portopening TCP 5986 "Port 5986"
cmd.exe /c net stop winrm
cmd.exe /c sc config winrm start= auto
cmd.exe /c net start winrm

Then use DSC to try to overwrite those values:

{
    param
    (
        [Parameter()]
        [System.String[]]
        $NodeName = 'localhost'
    )

    Import-DscResource -Module WSManDsc

    Node $NodeName
    {
        WSManListener HTTPS
        {
            Transport             = 'HTTPS'
            Ensure                = 'Present'
            CertificateThumbprint = 'F2BE91E92AF040EF116E1CDC91D75C22F47D7BD6'
            Hostname              = 'Hostname'
        } # End of WSManListener Resource
    } # End of Node
} # End of Configuration

DSC will complete successfully and indicate everything is up to date, but will not overwrite the existing listener with the new values.

Version of the Operating System and PowerShell the DSC Target Node is running:

Server 2016, PowerShell 5.1

Version of the DSC module you're using, or 'dev' if you're using current dev branch:
2.2.0.84

Any help is greatly appreciated-- thanks for your excellent work on this module!

Update CI Deploy Stage

Replace with:

  - stage: Deploy
    dependsOn: Test
    condition: |
      and(
        succeeded(),
        or(
          eq(variables['Build.SourceBranch'], 'refs/heads/master'),
          startsWith(variables['Build.SourceBranch'], 'refs/tags/')
        ),
        contains(variables['System.TeamFoundationCollectionUri'], 'dsccommunity')
      )

xWSMan resources available that might add more functionality, but need community assistance

Details of the scenario you tried and the problem that is occurring:
A module for WSMan is available but needs assistance from the community. Review, tests, and docs.
https://github.com/robwi/xWSMan

This was initially submitted in the issue PowerShell/DscResources#215, but if there are any functionality that can be gained by these resource, they should be added here. If there are no functionality that can be reused, then please close this issue.

The DSC configuration that is using the resource (as detailed as possible):
n/a

Version of the Operating System and PowerShell the DSC Target Node is running:
n/a

Version of the DSC module you're using, or 'dev' if you're using current dev branch:
n/a

WSManListener: Not returning all the properties in Get-TargetResource

Details of the scenario you tried and the problem that is occurring:
Looking at the resource WSManListener and the Get-TargetResource it doesn't return all the properties that are in the schema.mof.

https://github.com/PlagueHO/WSManDsc/blob/1fa63e590299af76a7a38e24dd5de3daae2707ae/Modules/WSManDsc/DSCResources/DSR_WSManListener/DSR_WSManListener.psm1#L65-L73

Also when the listener is absent, only one property is returned, and not the rest.

https://github.com/PlagueHO/WSManDsc/blob/1fa63e590299af76a7a38e24dd5de3daae2707ae/Modules/WSManDsc/DSCResources/DSR_WSManListener/DSR_WSManListener.psm1#L84-L86

The DSC configuration that is using the resource (as detailed as possible):
n/a

Version of the Operating System and PowerShell the DSC Target Node is running:
n/a

Version of the DSC module you're using, or 'dev' if you're using current dev branch:
Dev

Add new resource for configuring Wsman:\localhost\* items

The current resource WSManServiceConfig only configures settings in the wsman:\localhost\service* path. We should create a new resource that manages the items in the Wsman:\localhost* path called WSManConfig.

This would also imply a resource should be created called WSManClientConfig and WSManShellConfig.

These new resources would be copied from WSManServiceConfig with the data files changed. Although combining these properties into the existing WSManServiceConfig would be a simple approach too (with some modification) it would result in the name needing to be changed to correctly indicate the purpose of the resource - which would result in a breaking change.

So implementing multiple resources seems to be the best approach.

See https://github.com/PlagueHO/WSManDsc/issues/2#issuecomment-532773432

Tagging @fullenw1

@johlju - any thoughts on this one?

Update GitVersion Fix Regex

Update GitVersion Fixes Regex:

  feature:
    tag: useBranchName
    increment: Minor
    regex: f(eature(s)?)?[\/-]
    source-branches: ['master']
  hotfix:
    tag: fix
    increment: Patch
    regex: (hot)?fix(es)?[\/-]
    source-branches: ['master']

WSManListener: target CertificateThumbprint and write

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

I am trying to use WSManListener to create an HTTPS listener with a certificate that only has "CN=devOps"; it is not issued by the local machine. Is there any way to pass a thumbprint directly to the Find-Certificate cmdlet instead of having it search through issuers and DN and forcing the issuer to be the local computer hostname? I noticed the CertificateThumbprint parameter, but it is only configured for read operations and not write?

The DSC configuration that is using the resource (as detailed as possible):

I am primarily attempting to use this resource via Chef, but I have tested locally with DSC and have the same issue:

Configuration Example
{
    param
    (
        [Parameter()]
        [System.String[]]
        $NodeName = 'localhost'
    )
    Import-DscResource -Module WSManDsc
    Node $NodeName
    {
        WSManListener HTTPS
        {
            Transport = 'HTTPS'
            Ensure    = 'Present'
            Issuer    = 'CN=devOps'
        } # End of WSManListener Resource
    } # End of Node
} # End of Configuration

The relevant details of the certificate:

Issuer                   : CN=devOps
Subject                  : CN=devOps

Version of the Operating System and PowerShell the DSC Target Node is running:
Server 2016, PowerShell 5.1

Version of the DSC module you're using, or 'dev' if you're using current dev branch:
2.0.0.51

If you need any more details, please let me know; thanks for your excellent work on this module.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.