Skip to content

Commit 8600be2

Browse files
vorsvors
committed
Update README.md
1 parent df82806 commit 8600be2

1 file changed

Lines changed: 274 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 274 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,280 @@
22

33
# xComputerManagement
44

5-
{{Description}}
5+
The xComputerManagement module is a part of the Windows PowerShell Desired State Configuration (DSC) Resource Kit, which is a collection of DSC Resources produced by the PowerShell Team.
6+
This module contains the xComputer resource.
7+
This DSC Resource allows you to rename a computer and add it to a domain or workgroup.
8+
9+
All of the resources in the DSC Resource Kit are provided AS IS, and are not supported through any Microsoft standard support program or service.
10+
The ""x" in xComputerManagement stands for experimental, which means that these resources will be fix forward and monitored by the module owner(s).
11+
12+
Please leave comments, feature requests, and bug reports in the Q & A tab for this module.
13+
14+
If you would like to modify xComputerManagement module, feel free.
15+
When modifying, please update the module name, resource friendly name, and MOF class name (instructions below).
16+
As specified in the license, you may copy or modify this resource as long as they are used on the Windows Platform.
17+
18+
PowerShell Blog (this is a good starting point).
19+
There are also great community resources, such as PowerShell.org, or PowerShell Magazine.
20+
For more information on the DSC Resource Kit, check out this blog post.
21+
22+
## Installation
23+
To install xComputerManagement module
24+
25+
Unzip the content under $env:ProgramFiles\WindowsPowerShell\Modules folder
26+
To confirm installation:
27+
28+
Run Get-DSCResource to see that xComputer is among the DSC Resources listed
29+
Requirements
30+
This module requires the latest version of PowerShell (v4.0, which ships in Windows 8.1 or Windows Server 2012R2).
31+
To easily use PowerShell 4.0 on older operating systems, install WMF 4.0.
32+
Please read the installation instructions that are present on both the download page and the release notes for WMF 4.0
33+
34+
## Description
35+
The xComputerManagement module contains the xComputer DSC Resource.
36+
This DSC Resource allows you to configure a computer by changing its name and modifying its domain or workgroup.
37+
38+
## Details
39+
xComputer resource has following properties:
40+
41+
* Name: The desired computer name
42+
* DomainName: The name of the domain to join
43+
* WorkGroupName: The name of the workgroup
44+
* Credential: Credential to be used to join or leave domain
45+
46+
## Versions
47+
### 1.0.0.0
48+
49+
Initial release with the following resources
50+
* xComputer
51+
52+
### 1.2
53+
54+
Added functionality to enable moving computer from one domain to another
55+
Modified Test-DscConfiguration logics when testing domain join
56+
57+
### 1.2.2
58+
59+
Added types to Get/Set/Test definitions to allow xResourceDesigner validation to succeed
60+
61+
62+
## Examples
63+
### Change the Name and the Workgroup Name
64+
65+
This configuration will set a machine name and changes the workgroup it is in.
66+
67+
```powershell
68+
configuration Sample_xComputer_ChangeNameAndWorkGroup
69+
{
70+
param
71+
(
72+
[string[]]$NodeName ='localhost',
73+
74+
[Parameter(Mandatory)]
75+
[string]$MachineName,
76+
77+
[Parameter(Mandatory)]
78+
[string]$WorkGroupName
79+
)
80+
81+
#Import the required DSC Resources
82+
Import-DscResource -Module xComputerManagement
83+
84+
Node $NodeName
85+
{
86+
xComputer NewNameAndWorkgroup
87+
{
88+
Name = $MachineName
89+
WorkGroupName = $WorkGroupName
90+
}
91+
}
92+
}
93+
```
94+
95+
### Switch from a Workgroup to a Domain
96+
This configuration sets the machine name and joins a domain.
97+
Note: this requires a credential.
98+
99+
```powershell
100+
configuration Sample_xComputer_WorkgroupToDomain
101+
{
102+
param
103+
(
104+
[string[]]$NodeName="localhost",
105+
106+
[Parameter(Mandatory)]
107+
[string]$MachineName,
108+
109+
[Parameter(Mandatory)]
110+
[string]$Domain,
111+
112+
[Parameter(Mandatory)]
113+
[pscredential]$Credential
114+
)
115+
116+
#Import the required DSC Resources
117+
Import-DscResource -Module xComputerManagement
118+
119+
Node $NodeName
120+
{
121+
xComputer JoinDomain
122+
{
123+
Name = $MachineName
124+
DomainName = $Domain
125+
Credential = $Credential # Credential to join to domain
126+
}
127+
}
128+
}
129+
130+
<#****************************
131+
To save the credential in plain-text in the mof file, use the following configuration data
132+
133+
$ConfigData = @{
134+
AllNodes = @(
135+
@{
136+
NodeName = "localhost"
137+
# Allows credential to be saved in plain-text in the the *.mof instance document.
138+
139+
PSDscAllowPlainTextPassword = $true
140+
}
141+
)
142+
}
143+
144+
Sample_xComputer_WorkgroupToDomain -ConfigurationData $ConfigData -MachineName <machineName> -credential (Get-Credential) -Domain <domainName>
145+
****************************#>
146+
```
147+
148+
### Change the Name while staying on the Domain
149+
150+
This example will change the machines name while remaining on the domain.
151+
Note: this requires a credential.
152+
153+
```powershell
154+
function Sample_xComputer_ChangeNameInDomain
155+
{
156+
param
157+
(
158+
[string[]]$NodeName="localhost",
159+
160+
[Parameter(Mandatory)]
161+
[string]$MachineName,
162+
163+
[Parameter(Mandatory)]
164+
[pscredential]$Credential
165+
)
166+
167+
#Import the required DSC Resources
168+
Import-DscResource -Module xComputerManagement
169+
170+
Node $NodeName
171+
{
172+
xComputer NewName
173+
{
174+
Name = $MachineName
175+
Credential = $Credential # Domain credential
176+
}
177+
}
178+
}
179+
180+
<#****************************
181+
To save the credential in plain-text in the mof file, use the following configuration data
182+
183+
$ConfigData = @{
184+
AllNodes = @(
185+
@{
186+
NodeName = "localhost";
187+
188+
# Allows credential to be saved in plain-text in the the *.mof instance document.
189+
190+
PSDscAllowPlainTextPassword = $true;
191+
}
192+
)
193+
}
194+
195+
Sample_xComputer_ChangeNameInDomain -ConfigurationData $ConfigData -MachineName <machineName> -Credential (Get-Credential)
196+
197+
*****************************#>
198+
```
199+
200+
### Change the Name while staying on the Workgroup
201+
This example will change the machines name while remaining on the workgroup.
202+
203+
```powershell
204+
function Sample_xComputer_ChangeNameInWorkgroup
205+
{
206+
param
207+
(
208+
[string[]]$NodeName="localhost",
209+
210+
[Parameter(Mandatory)]
211+
[string]$MachineName
212+
)
213+
214+
#Import the required DSC Resources
215+
Import-DscResource -Module xComputerManagement
216+
217+
Node $NodeName
218+
{
219+
xComputer NewName
220+
{
221+
Name = $MachineName
222+
}
223+
}
224+
}
225+
```
226+
227+
### Switch from a Domain to a Workgroup
228+
This example switches the computer from a domain to a workgroup.
229+
Note: this requires a credential.
230+
231+
```powershell
232+
function Sample_xComputer_DomainToWorkgroup
233+
{
234+
param
235+
(
236+
[string[]]$NodeName="localhost",
237+
238+
[Parameter(Mandatory)]
239+
[string]$MachineName,
240+
241+
[Parameter(Mandatory)]
242+
[string]$WorkGroup,
243+
244+
[Parameter(Mandatory)]
245+
[pscredential]$Credential
246+
)
247+
248+
#Import the required DSC Resources
249+
Import-DscResource -Module xComputerManagement
250+
251+
Node $NodeName
252+
{
253+
xComputer JoinWorkgroup
254+
{
255+
Name = $MachineName
256+
WorkGroupName = $WorkGroup
257+
Credential = $Credential # Credential to unjoin from domain
258+
}
259+
}
260+
}
261+
262+
<#****************************
263+
To save the credential in plain-text in the mof file, use the following configuration data
264+
265+
$ConfigData = @{
266+
AllNodes = @(
267+
@{
268+
NodeName = "localhost";
269+
# Allows credential to be saved in plain-text in the the *.mof instance document.
270+
271+
PSDscAllowPlainTextPassword = $true;
272+
}
273+
)
274+
}
275+
276+
Sample_xComputer_DomainToWorkgroup -ConfigurationData $ConfigData -MachineName <machineName> -credential (Get-Credential) -WorkGroup <workgroupName>
277+
****************************#>
278+
```
6279

7280
## Contributing
8281
Please check out common DSC Resources [contributing guidelines](https://github.com/PowerShell/DscResource.Kit/blob/master/CONTRIBUTING.md).

0 commit comments

Comments
 (0)