Skip to content

Commit e711dde

Browse files
zjalexanderzjalexander
committed
Merge pull request #1 from PowerShell/master
syncing with PSDocs
2 parents d970c40 + 4f440d5 commit e711dde

File tree

98 files changed

+5495
-12
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

98 files changed

+5495
-12
lines changed

‎README.md‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,11 @@
11
# PowerShell Documentation
22

3-
Welcome to the PowerShell-Docs repository, housing the official PowerShell documentation [available on MSDN](https://msdn.microsoft.com/powershell/dsc/overview).
3+
Welcome to the PowerShell-Docs repository, housing the official Windows PowerShell documentation [available on MSDN](https://msdn.microsoft.com/powershell/dsc/overview).
44

5-
> **Note**: right now, this repo is only intended for PowerShell Desired State Configuration (DSC) content.
6-
In the future, it may be expanded to include a greater set of PowerShell documentation.
5+
> **Note**: Currently, this repository is intended only for PowerShell [Desired State Configuration (DSC)](https://msdn.microsoft.com/en-us/powershell/dsc/overview) content and [Windows Management Framework (WMF) release notes](https://msdn.microsoft.com/en-us/powershell/wmf/releasenotes). In the future, the repo will be expanded to include a wider range of PowerShell documentation.
76
87
## Contributing
98

10-
We will be actively merging contributions into this repository via pull request.
11-
Please note that before contributing, you must [sign a Contribution License Agreement](https://cla.microsoft.com/) to ensure that the community is free to use your contributions.
9+
We actively merge contributions into this repository via [pull request](https://help.github.com/articles/using-pull-requests/).
10+
Please note that before you submit a pull request you must [sign a Contribution License Agreement](https://cla.microsoft.com/) to ensure that the community is free to use your submissions.
1211
For more information on contributing, read our [contributions guide](CONTRIBUTING.md).

‎dsc/TOC.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
# [Configurations](configurations.md)
44
## [Enacting configurations](enactingConfigurations.md)
55
## [Configuration data](configData.md)
6+
### [Credential options in configuration data](configDataCredentials.md)
67
## [Securing the configuration MOF file](secureMOF.md)
78
## [Partial Configurations](partialConfigs.md)
89
# [Resources](resources.md)
@@ -24,6 +25,7 @@
2425
#### [MOF-based resource in C#](authoringResourceMofCS.md)
2526
### [Class-based custom resouces](authoringResourceClass.md)
2627
### [Composite resources](authoringResourceComposite.md)
28+
### [Debugging DSC resources](debugResource.md)
2729

2830
# [Configuring the Local Configuration Manager (LCM)](metaConfig.md)
2931
## [Configuring the LCM in PowerShell 4.0](metaConfig4.md)

‎dsc/authoringResourceClass.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ To implement a DSC custom resource with a PowerShell class, create the following
1616

1717
```
1818
$env: psmodulepath (folder)
19-
|- MyDscResources (folder)
19+
|- MyDscResource (folder)
2020
|- MyDscResource.psm1
2121
MyDscResource.psd1
2222
```

‎dsc/configDataCredentials.md‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
# Credentials Options in Configuration Data
2+
>Applies To: Windows PowerShell 5.0
3+
4+
## Plain Text Passwords and Domain Users
5+
6+
DSC configurations containing a credential without encryption will generate an error messages about plain text passwords.
7+
Also, DSC will generate a warning when using domain credentials.
8+
These error and warning messages can be silenced using the DSC configuration data keywords:
9+
* **PsDscAllowPlainTextPassword**
10+
* **PsDscAllowDomainUser**
11+
12+
## Handling Credentials in DSC
13+
14+
DSC configuration resources run as `Local System` by default.
15+
However, some resources require a credential, like when the `Package` resource needs to install software under a specific user account.
16+
17+
Earlier resources used a hard-coded `Credential` property name to handle this.
18+
WMF 5.0 added an automatic `PsDscRunAsCredential` property for all resources.
19+
Newer resources and custom resources can use this automatic property instead of creating their own property for credentials.
20+
21+
*Note that some resources are designed to use multiple credentials for a specific reason, and they will have their own credential properties.*
22+
23+
To identify the available credential properties on a resource use either `Get-DscResource -Name ResourceName -Syntax` or the Intellisense in the ISE (`CTRL+SPACE`).
24+
25+
```PowerShell
26+
PS C:\> Get-DscResource -Name Group -Syntax
27+
Group [String] #ResourceName
28+
{
29+
GroupName = [string]
30+
[Credential = [PSCredential]]
31+
[DependsOn = [string[]]]
32+
[Description = [string]]
33+
[Ensure = [string]{ Absent | Present }]
34+
[Members = [string[]]]
35+
[MembersToExclude = [string[]]]
36+
[MembersToInclude = [string[]]]
37+
[PsDscRunAsCredential = [PSCredential]]
38+
}
39+
```
40+
41+
This example uses a [Group](https://msdn.microsoft.com/en-us/powershell/dsc/groupresource) resource from the `PSDesiredStateConfiguration` built-in DSC resource module.
42+
It can create local groups and add or remove members.
43+
It accepts both the `Credential` property and the automatic `PsDscRunAsCredential` property.
44+
However, it is coded to only use the `Credential` property.
45+
Read more about `PsDscRunAsCredential` in the [WMF Release Notes](https://msdn.microsoft.com/en-us/powershell/wmf/dsc_runas).
46+
47+
## Example: The Group resource Credential property
48+
49+
DSC runs under `Local System`, so it already has permissions to modify local users and groups.
50+
If the member to be added is a local account, then no credential is required.
51+
If the `Group` resource adds a domain account to the local group, then a credential is required.
52+
53+
Anonymous queries to Active Directory are not allowed.
54+
The `Credential` property of the `Group` resource is the domain account used to query Active Directory.
55+
For most purposes this can be a generic user account, because by default users can *read* most of the objects in Active Directory.
56+
57+
## Example Configuration
58+
59+
The following example code uses DSC to populate a local group with a domain user:
60+
61+
```PowerShell
62+
Configuration DomainCredentialExample
63+
{
64+
param(
65+
[PSCredential]$DomainCredential
66+
)
67+
Import-DscResource -ModuleName PSDesiredStateConfiguration
68+
69+
node localhost
70+
{
71+
Group DomainUserToLocalGroup
72+
{
73+
GroupName = 'ApplicationAdmins'
74+
MembersToInclude = 'contoso\alice'
75+
Credential = $DomainCredential
76+
}
77+
}
78+
}
79+
80+
$cred = Get-Credential -UserName contoso\genericuser -Message "Password please"
81+
DomainCredentialExample -DomainCredential $cred
82+
```
83+
84+
This code generates both an error and warning message:
85+
86+
```
87+
ConvertTo-MOFInstance : System.InvalidOperationException error processing
88+
property 'Credential' OF TYPE 'Group': Converting and storing encrypted
89+
passwords as plain text is not recommended. For more information on securing
90+
credentials in MOF file, please refer to MSDN blog:
91+
http://go.microsoft.com/fwlink/?LinkId=393729
92+
93+
At line:11 char:9
94+
+ Group
95+
At line:297 char:16
96+
+ $aliasId = ConvertTo-MOFInstance $keywordName $canonicalizedValue
97+
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
98+
+ CategoryInfo : InvalidOperation: (:) [Write-Error], InvalidOperationException
99+
+ FullyQualifiedErrorId : FailToProcessProperty,ConvertTo-MOFInstance
100+
101+
WARNING: It is not recommended to use domain credential for node 'localhost'.
102+
In order to suppress the warning, you can add a property named
103+
'PSDscAllowDomainUser' with a value of $true to your DSC configuration data
104+
for node 'localhost'.
105+
```
106+
107+
This example has two issues:
108+
1. An error explains that plain text passwords are not recommended
109+
2. A warning advises against using a domain credential
110+
111+
## PsDscAllowPlainTextPassword
112+
113+
The first error message has a URL with documentation.
114+
This link explains how to encrypt passwords using a [ConfigurationData](https://msdn.microsoft.com/en-us/powershell/dsc/configdata) structure and a certificate.
115+
For more information on certificates and DSC [read this post](http://aka.ms/certs4dsc).
116+
117+
To force a plain text password, the `PsDscAllowPlainTextPassword` keyword is required in the configuration data section as follows:
118+
119+
```PowerShell
120+
Configuration DomainCredentialExample
121+
{
122+
param(
123+
[PSCredential]$DomainCredential
124+
)
125+
Import-DscResource -ModuleName PSDesiredStateConfiguration
126+
127+
node localhost
128+
{
129+
Group DomainUserToLocalGroup
130+
{
131+
GroupName = 'ApplicationAdmins'
132+
MembersToInclude = 'contoso\alice'
133+
Credential = $DomainCredential
134+
}
135+
}
136+
}
137+
138+
$cd = @{
139+
AllNodes = @(
140+
@{
141+
NodeName = 'localhost'
142+
PSDscAllowPlainTextPassword = $true
143+
}
144+
)
145+
}
146+
147+
$cred = Get-Credential -UserName contoso\genericuser -Message "Password please"
148+
DomainCredentialExample -DomainCredential $cred -ConfigurationData $cd
149+
```
150+
151+
*Note that `NodeName` cannot equal asterisk. It must be a specific node name.*
152+
153+
**Microsoft advises to avoid plain text passwords due to the significant security risk.**
154+
155+
## Domain Credentials
156+
157+
Running the example configuration script again (with or without encryption), still generates the warning that using a domain account for a credential is not recommended.
158+
Using a local account eliminates potential exposure of domain credentials that can be used on other servers.
159+
160+
**When using credentials with DSC resources, prefer a local account over a domain account when possible.**
161+
162+
If there is a '\' or '@' in the `Username` property of the credential, then DSC will treat it as a domain account.
163+
An exception is made for "localhost", "127.0.0.1", and "::1" in the domain portion of the user name.
164+
165+
## PSDscAllowDomainUser
166+
167+
In the DSC `Group` resource example above, querying an Active Directory domain *requires* the use of a domain account.
168+
In this case add the `PSDscAllowDomainUser` property to the `ConfigurationData` block as follows:
169+
170+
```PowerShell
171+
$cd = @{
172+
AllNodes = @(
173+
@{
174+
NodeName = 'localhost'
175+
PSDscAllowDomainUser = $true
176+
# PSDscAllowPlainTextPassword = $true
177+
CertificateFile = "C:\PublicKeys\server1.cer"
178+
}
179+
)
180+
}
181+
```
182+
183+
Now the configuration script will generate the MOF file with no errors or warnings.

‎dsc/debugResource.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Debugging DSC resources
2+
3+
> Applies To: Windows PowerShell 5.0
4+
5+
In PowerShell 5.0, a new feature was introduced in Desired State Configuraiton (DSC) that allows you to debug a DSC resource as a configuration is being applied.
6+
7+
## Enabling DSC debugging
8+
Before you can debug a resource, you have to enable debugging by calling the [Enable-DscDebug](https://technet.microsoft.com/en-us/library/mt517870.aspx) cmdlet. This cmdlet takes a mandatory parameter, **BreakAll**. You can verify that debugging has been enabled by looking at the result of a call to [Get-DscLocalConfigurationManager](https://technet.microsoft.com/en-us/library/dn407378.aspx). The following PowerShell output shows the result of enabling debugging:
9+
10+
11+
```powershell
12+
PS C:\DebugTest> $LCM = Get-DscLocalConfigurationManager
13+
14+
PS C:\DebugTest> $LCM.DebugMode
15+
NONE
16+
17+
PS C:\DebugTest> Enable-DscDebug -BreakAll
18+
19+
PS C:\DebugTest> $LCM = Get-DscLocalConfigurationManager
20+
21+
PS C:\DebugTest> $LCM.DebugMode
22+
ForceModuleImport
23+
ResourceScriptBreakAll
24+
25+
PS C:\DebugTest>
26+
```
27+
28+
29+
## Starting a configuration with debug enabled
30+
To debug a DSC resource, you start a configuration that calls that resource. For this example, we'll look at a simple configuration that calls the [WindowsFeature](windowsfeatureResource.md) resource to ensure that the "WindowsPowerShellWebAccess" feature is installed:
31+
32+
```powershell
33+
Configuration PSWebAccess
34+
{
35+
Import-DscResource -ModuleName 'PsDesiredStateConfiguration'
36+
Node localhost
37+
{
38+
WindowsFeature PSWA
39+
{
40+
Name = 'WindowsPowerShellWebAccess'
41+
Ensure = 'Present'
42+
}
43+
}
44+
}
45+
PSWebAccess
46+
```
47+
After compiling the configuration, start it by calling [Start-DscConfiguration](https://technet.microsoft.com/en-us/library/dn521623.aspx). The configuration will stop when the
48+
Local Configuration Manager (LCM) calls into the first resoure in the configuration. If you use the `-Verbose` and `-Wait` parameters, the output displays the lines you need to enter
49+
to start debugging.
50+
51+
```powershell
52+
PS C:\DebugTest> Start-DscConfiguration .\PSWebAccess -Wait -Verbose
53+
VERBOSE: Perform operation 'Invoke CimMethod' with following parameters, ''methodName' = SendConfigurationApply,'className' = MSFT_DSCLocalConfiguration
54+
Manager,'namespaceName' = root/Microsoft/Windows/DesiredStateConfiguration'.
55+
VERBOSE: An LCM method call arrived from computer TEST-SRV with user sid S-1-5-21-2127521184-1604012920-1887927527-108583.
56+
VERBOSE: An LCM method call arrived from computer TEST-SRV with user sid S-1-5-21-2127521184-1604012920-1887927527-108583.
57+
VERBOSE: [TEST-SRV]: LCM: [ Start Set ]
58+
WARNING: [TEST-SRV]: [DSCEngine] Warning LCM is in Debug 'ResourceScriptBreakAll' mode. Resource script processing will
59+
be stopped to wait for PowerShell script debugger to attach.
60+
VERBOSE: [TEST-SRV]: [DSCEngine] Importing the module C:\WINDOWS\system32\WindowsPowerShell\v1.0\Modules\PSDesiredStateCo
61+
nfiguration\DscResources\MSFT_RoleResource\MSFT_RoleResource.psm1 in force mode.
62+
VERBOSE: [TEST-SRV]: LCM: [ Start Resource ] [[WindowsFeature]PSWA]
63+
VERBOSE: [TEST-SRV]: LCM: [ Start Test ] [[WindowsFeature]PSWA]
64+
VERBOSE: [TEST-SRV]: [[WindowsFeature]PSWA] Importing the module MSFT_RoleResource in force mode.
65+
WARNING: [TEST-SRV]: [[WindowsFeature]PSWA] Resource is waiting for PowerShell script debugger to attach. Use the follow
66+
ing commands to begin debugging this resource script:
67+
Enter-PSSession -ComputerName TEST-SRV -Credential <credentials>
68+
Enter-PSHostProcess -Id 9000 -AppDomainName DscPsPluginWkr_AppDomain
69+
Debug-Runspace -Id 9
70+
```
71+
At this point, the LCM has called the resource, and come to the first break point. The last three lines in the output show you how to attach to the process and start debugging the resource script.
72+
73+
## Debugging the resource script
74+
75+
Start a new instance of the PowerShell ISE. In the console pane, enter the last three lines of output from the `Start-DscConifiguration` output as commands, replacing `<credentials>` with
76+
valid user credentials. Here is the resulting output.
77+
78+
79+

‎dsc/images/enableDebug.png‎

-10.5 KB
Binary file not shown.

‎dsc/lnxGettingStarted.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -168,4 +168,4 @@ The following log files are generated for DSC for Linux messages.
168168
|Log file|Directory|Description|
169169
|---|---|---|
170170
|omiserver.log|/opt/omi/var/log/|Messages relating to the operation of the OMI CIM server.|
171-
|dsc.log|/opt/omi/var/log/|Messages relating to the operation of the Local Configuration Manager (LCM) and DSC resource operations.|
171+
|dsc.log|/opt/omi/var/log/|Messages relating to the operation of the Local Configuration Manager (LCM) and DSC resource operations.|

0 commit comments

Comments
 (0)