DSC/Configuration/xComputerManagement/xComputerManagement_Documentation.html (456 lines of code) (raw):
<p> </p>
<div id="longDesc"><span style="font-family: Calibri; font-size: medium;">
<h1 style="font-family: Calibri Light; color: #2e74b5; font-size: large;">Introduction</h1>
<p>The<strong> xComputerManagement</strong> 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. This module contains the <strong>xComputer</strong> resource. This DSC Resource allows you to rename a computer and add it to a domain or workgroup.</p>
<p><strong>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. The ""x" in xComputerManagement stands for experimental</strong>, which means that these resources will be <strong>fix forward</strong> and monitored by the module owner(s).</p>
<p>Please leave comments, feature requests, and bug reports in the Q & A tab for this module.</p>
<p>If you would like to modify <strong>xComputerManagement</strong> module, feel free. When modifying, please update the module name, resource friendly name, and MOF class name (instructions below). As specified in the license, you may copy or modify this resource as long as they are used on the Windows Platform.</p>
<p><span style="color: #0000ff;">PowerShell Blog</span> (<a href="http://blogs.msdn.com/b/powershell/archive/2013/11/01/configuration-in-a-devops-world-windows-powershell-desired-state-configuration.aspx"><span style="color: #0000ff;">this</span></a> is a good starting point). There are also great community resources, such as <a href="http://powershell.org/wp/tag/dsc/"> <span style="color: #0000ff;">PowerShell.org</span></a>, or <a href="http://www.powershellmagazine.com/tag/dsc/"> <span style="color: #0000ff;">PowerShell Magazine</span></a>. For more information on the DSC Resource Kit, check out <a href="http://go.microsoft.com/fwlink/?LinkID=389546"><span style="color: #0000ff;">this blog post</span></a>.</p>
<h1 style="color: #2e74b5; font-family: Calibri Light; font-size: large;">Installation</h1>
<p>To install <strong>xComputerManagement</strong> module</p>
<ul style="list-style-type: disc; direction: ltr;">
<li>Unzip the content under $env:ProgramFiles\WindowsPowerShell\Modules folder </li>
</ul>
<p>To confirm installation:</p>
<ul style="list-style-type: disc; direction: ltr;">
<li>Run <strong>Get-DSCResource</strong> to see that <strong>xComputer</strong> is among the DSC Resources listed </li>
</ul>
<h1 style="color: #2e74b5; font-family: Calibri Light; font-size: large;">Requirements</h1>
<p>This module requires the latest version of PowerShell (v4.0, which ships in Windows 8.1 or Windows Server 2012R2). To easily use PowerShell 4.0 on older operating systems, <a href="http://www.microsoft.com/en-us/download/details.aspx?id=40855"><span style="color: #0000ff;">install WMF 4.0</span></a>. Please read the installation instructions that are present on both the download page and the release notes for WMF 4.0</p>
<h1 style="color: #2e74b5; font-family: Calibri Light; font-size: large;">Description</h1>
<p>The <strong>xComputerManagement </strong>module contains the <strong>xComputer</strong> DSC Resource. This DSC Resource allows you to configure a computer by changing its name and modifying its domain or workgroup.</p>
<h1 style="color: #2e74b5; font-family: Calibri Light; font-size: large;">Details</h1>
<p><strong>xComputer</strong> resource has following properties:</p>
<ul style="list-style-type: disc; direction: ltr;">
<li><strong>Name</strong>: The desired computer name </li>
<li><strong>DomainName</strong>: The name of the domain to join </li>
<li><strong>WorkGroupName</strong>: The name of the workgroup </li>
<li><strong>Credential</strong>: Credential to be used to join or leave domain </li>
</ul>
<h1 style="color: #2e74b5; font-family: Calibri Light; font-size: large;">Renaming Requirements</h1>
<p>When making changes to these resources, we suggest the following practice:</p>
<ol style="list-style-type: decimal; direction: ltr;">
<li>Update the following names by replacing MSFT with your company/community name and replacing the <strong>"x"</strong> with <strong>"c"</strong> (short for "Community") or another prefix of your choice:
<ul>
<li><strong>Module name (ex: xComputerManagement</strong> becomes <strong>cComputerManagement</strong>) </li>
<li><strong>Resource folder (ex: MSFT_xComputer</strong> becomes <strong>Contoso_cComputer</strong>) </li>
<li><strong>Resource Name (ex: MSFT_xComputer</strong> becomes <strong>Contoso_cComputer</strong>) </li>
<li><strong>Resource Friendly Name (ex: xComputer</strong> becomes <strong>cComputer</strong>) </li>
<li><strong>MOF class name (ex: MSFT_xComputer</strong> becomes <strong>Contoso_cComputer</strong>) </li>
<li><strong>Filename for the <resource>.schema.mof (ex: MSFT_xComputer</strong>.schema.mof becomes <strong>Contoso_cComputer</strong>.schema.mof) </li>
</ul>
</li>
<li>Update module and metadata information in the module manifest </li>
<li>Update any configuration that use these resources </li>
</ol>
<p><em>We reserve resource and module names without prefixes ("x" or "c") for future use (e.g. "MSFT_Computer" or "Computer"). If the next version of Windows Server ships with a "Computer" resource, we don't want to break any configurations that use any community modifications. Please keep a prefix such as "c" on all community modifications.</em></p>
<h1 style="color: #2e74b5; font-family: Calibri Light; font-size: large;">Versions</h1>
<p>1.0.0.0</p>
</span>
Initial release with the following resources
<ul>
<li>xComputer </li>
</li>
</ul>
<p>1.2</p>
</span>
<ul>
<li>Added functionality to enable moving computer from one domain to another </li>
<li>Modified Test-DscConfiguration logics when testing domain join </li>
</ul>
<p>1.2.2</p>
</span>
<ul>
<li>Added types to Get/Set/Test definitions to allow xResourceDesigner validation to succeed</li>
</ul>
<span style="font-family: Calibri; font-size: medium;">
<h1 style="margin-bottom: 0pt; font-family: Calibri Light; color: #2e74b5; font-size: large;">Example: Change the Name and the Workgroup Name</h1>
This configuration will set a machine name and changes the workgroup it is in.
<div class="scriptcode">
<div class="pluginEditHolder" pluginCommand="mceScriptCode">
<div class="title"><span>PowerShell</span></div>
<div class="pluginLinkHolder"><span class="pluginEditHolderLink">Edit</span>|<span class="pluginRemoveHolderLink">Remove</span></div>
<span class="hidden">powershell</span>
<pre class="hidden">configuration Sample_xComputer_ChangeNameAndWorkGroup
{
param
(
[string[]]$NodeName ='localhost',
[Parameter(Mandatory)]
[string]$MachineName,
[Parameter(Mandatory)]
[string]$WorkGroupName
)
#Import the required DSC Resources
Import-DscResource -Module xComputerManagement
Node $NodeName
{
xComputer NewNameAndWorkgroup
{
Name = $MachineName
WorkGroupName = $WorkGroupName
}
}
}
</pre>
<div class="preview">
<pre class="powershell">configuration Sample_xComputer_ChangeNameAndWorkGroup
{
<span class="powerShell__keyword">param</span>
(
[string[]]<span class="powerShell__variable">$NodeName</span> =<span class="powerShell__string">'localhost'</span>,
[Parameter(Mandatory)]
[string]<span class="powerShell__variable">$MachineName</span>,
[Parameter(Mandatory)]
[string]<span class="powerShell__variable">$WorkGroupName</span>
)
<span class="powerShell__com">#Import the required DSC Resources </span>
Import<span class="powerShell__operator">-</span>DscResource <span class="powerShell__operator">-</span>Module xComputerManagement
Node <span class="powerShell__variable">$NodeName</span>
{
xComputer NewNameAndWorkgroup
{
Name = <span class="powerShell__variable">$MachineName</span>
WorkGroupName = <span class="powerShell__variable">$WorkGroupName</span>
}
}
}
</pre>
</div>
</div>
</div>
<h1 style="margin-bottom: 0pt; font-family: Calibri Light; color: #2e74b5; font-size: large;">Example: Switch from a Workgroup to a Domain</h1>
This configuration sets the machine name and joins a domain.<br /> <em>Note: this requires a credential.</em>
<div class="scriptcode">
<div class="pluginEditHolder" pluginCommand="mceScriptCode">
<div class="title"><span>PowerShell</span></div>
<div class="pluginLinkHolder"><span class="pluginEditHolderLink">Edit</span>|<span class="pluginRemoveHolderLink">Remove</span></div>
<span class="hidden">powershell</span>
<pre class="hidden">configuration Sample_xComputer_WorkgroupToDomain
{
param
(
[string[]]$NodeName="localhost",
[Parameter(Mandatory)]
[string]$MachineName,
[Parameter(Mandatory)]
[string]$Domain,
[Parameter(Mandatory)]
[pscredential]$Credential
)
#Import the required DSC Resources
Import-DscResource -Module xComputerManagement
Node $NodeName
{
xComputer JoinDomain
{
Name = $MachineName
DomainName = $Domain
Credential = $Credential # Credential to join to domain
}
}
}
<#****************************
To save the credential in plain-text in the mof file, use the following configuration data
$ConfigData = @{
AllNodes = @(
@{
NodeName = "localhost"
# Allows credential to be saved in plain-text in the the *.mof instance document.
PSDscAllowPlainTextPassword = $true
}
)
}
Sample_xComputer_WorkgroupToDomain -ConfigurationData $ConfigData -MachineName <machineName> -credential (Get-Credential) -Domain <domainName>
****************************#>
</pre>
<div class="preview">
<pre class="powershell"><span class="powerShell__keyword">comfiguration</span> Sample_xComputer_WorkgroupToDomain
{
<span class="powerShell__keyword">param</span>
(
[string[]]<span class="powerShell__variable">$NodeName</span>=<span class="powerShell__string">"localhost"</span>,
[Parameter(Mandatory)]
[string]<span class="powerShell__variable">$MachineName</span>,
[Parameter(Mandatory)]
[string]<span class="powerShell__variable">$Domain</span>,
[Parameter(Mandatory)]
[pscredential]<span class="powerShell__variable">$Credential</span>
)
<span class="powerShell__com">#Import the required DSC Resources</span>
Import<span class="powerShell__operator">-</span>DscResource <span class="powerShell__operator">-</span>Module xComputerManagement
Node <span class="powerShell__variable">$NodeName</span>
{
xComputer JoinDomain
{
Name = <span class="powerShell__variable">$MachineName</span>
DomainName = <span class="powerShell__variable">$Domain</span>
Credential = <span class="powerShell__variable">$Credential</span> <span class="powerShell__com"># Credential to join to domain</span>
}
}
}
<span class="powerShell__mlcom"><#****************************
To save the credential in plain-text in the mof file, use the following configuration data
$ConfigData = @{
AllNodes = @(
@{
NodeName = "localhost"
# Allows credential to be saved in plain-text in the the *.mof instance document.
PSDscAllowPlainTextPassword = $true
}
)
}
Sample_xComputer_WorkgroupToDomain -ConfigurationData $ConfigData -MachineName <machineName> -credential (Get-Credential) -Domain <domainName>
****************************#></span>
</pre>
</div>
</div>
</div>
<div class="endscriptcode">
<h1 style="margin-bottom: 0pt; color: #2e74b5; font-family: Calibri Light; font-size: large;">Example: Change the Name while staying on the Domain</h1>
This example will change the machines name while remaining on the domain.<br /> <em>Note: this requires a credential.</em>
<div class="scriptcode">
<div class="pluginEditHolder" pluginCommand="mceScriptCode">
<div class="title"><span>PowerShell</span></div>
<div class="pluginLinkHolder"><span class="pluginEditHolderLink">Edit</span>|<span class="pluginRemoveHolderLink">Remove</span></div>
<span class="hidden">powershell</span>
<pre class="hidden">function Sample_xComputer_ChangeNameInDomain
{
param
(
[string[]]$NodeName="localhost",
[Parameter(Mandatory)]
[string]$MachineName,
[Parameter(Mandatory)]
[pscredential]$Credential
)
#Import the required DSC Resources
Import-DscResource -Module xComputerManagement
Node $NodeName
{
xComputer NewName
{
Name = $MachineName
Credential = $Credential # Domain credential
}
}
}
<#****************************
To save the credential in plain-text in the mof file, use the following configuration data
$ConfigData = @{
AllNodes = @(
@{
NodeName = "localhost";
# Allows credential to be saved in plain-text in the the *.mof instance document.
PSDscAllowPlainTextPassword = $true;
}
)
}
Sample_xComputer_ChangeNameInDomain -ConfigurationData $ConfigData -MachineName <machineName> -Credential (Get-Credential)
*****************************#> </pre>
<div class="preview">
<pre class="powershell"><span class="powerShell__keyword">function</span> Sample_xComputer_ChangeNameInDomain
{
<span class="powerShell__keyword">param</span>
(
[string[]]<span class="powerShell__variable">$NodeName</span>=<span class="powerShell__string">"localhost"</span>,
[Parameter(Mandatory)]
[string]<span class="powerShell__variable">$MachineName</span>,
[Parameter(Mandatory)]
[pscredential]<span class="powerShell__variable">$Credential</span>
)
<span class="powerShell__com">#Import the required DSC Resources </span>
Import<span class="powerShell__operator">-</span>DscResource <span class="powerShell__operator">-</span>Module xComputerManagement
Node <span class="powerShell__variable">$NodeName</span>
{
xComputer NewName
{
Name = <span class="powerShell__variable">$MachineName</span>
Credential = <span class="powerShell__variable">$Credential</span> <span class="powerShell__com"># Domain credential</span>
}
}
}
<span class="powerShell__mlcom"><#****************************
To save the credential in plain-text in the mof file, use the following configuration data
$ConfigData = @{
AllNodes = @(
@{
NodeName = "localhost";
# Allows credential to be saved in plain-text in the the *.mof instance document.
PSDscAllowPlainTextPassword = $true;
}
)
}
Sample_xComputer_ChangeNameInDomain -ConfigurationData $ConfigData -MachineName <machineName> -Credential (Get-Credential)
*****************************#></span> </pre>
</div>
</div>
</div>
<h1 style="margin-bottom: 0pt; color: #2e74b5; font-family: Calibri Light; font-size: large;">Example: Change the Name while staying on the Workgroup</h1>
This example will change the machines name while remaining on the workgroup.
<div class="scriptcode">
<div class="pluginEditHolder" pluginCommand="mceScriptCode">
<div class="title"><span>PowerShell</span></div>
<div class="pluginLinkHolder"><span class="pluginEditHolderLink">Edit</span>|<span class="pluginRemoveHolderLink">Remove</span></div>
<span class="hidden">powershell</span>
<pre class="hidden">function Sample_xComputer_ChangeNameInWorkgroup
{
param
(
[string[]]$NodeName="localhost",
[Parameter(Mandatory)]
[string]$MachineName
)
#Import the required DSC Resources
Import-DscResource -Module xComputerManagement
Node $NodeName
{
xComputer NewName
{
Name = $MachineName
}
}
}
</pre>
<div class="preview">
<pre class="powershell"><span class="powerShell__keyword">function</span> Sample_xComputer_ChangeNameInWorkgroup
{
<span class="powerShell__keyword">param</span>
(
[string[]]<span class="powerShell__variable">$NodeName</span>=<span class="powerShell__string">"localhost"</span>,
[Parameter(Mandatory)]
[string]<span class="powerShell__variable">$MachineName</span>
)
<span class="powerShell__com">#Import the required DSC Resources </span>
Import<span class="powerShell__operator">-</span>DscResource <span class="powerShell__operator">-</span>Module xComputerManagement
Node <span class="powerShell__variable">$NodeName</span>
{
xComputer NewName
{
Name = <span class="powerShell__variable">$MachineName</span>
}
}
}
</pre>
</div>
</div>
</div>
<h1 style="margin-bottom: 0pt; color: #2e74b5; font-family: Calibri Light; font-size: large;">Example: Switch from a Domain to a Workgroup</h1>
This example switches the computer from a domain to a workgroup.<br /> <em>Note: this requires a credential</em>.
<div class="scriptcode">
<div class="pluginEditHolder" pluginCommand="mceScriptCode">
<div class="title"><span>PowerShell</span></div>
<div class="pluginLinkHolder"><span class="pluginEditHolderLink">Edit</span>|<span class="pluginRemoveHolderLink">Remove</span></div>
<span class="hidden">powershell</span>
<pre class="hidden">function Sample_xComputer_DomainToWorkgroup
{
param
(
[string[]]$NodeName="localhost",
[Parameter(Mandatory)]
[string]$MachineName,
[Parameter(Mandatory)]
[string]$WorkGroup,
[Parameter(Mandatory)]
[pscredential]$Credential
)
#Import the required DSC Resources
Import-DscResource -Module xComputerManagement
Node $NodeName
{
xComputer JoinWorkgroup
{
Name = $MachineName
WorkGroupName = $WorkGroup
Credential = $Credential # Credential to unjoin from domain
}
}
}
<#****************************
To save the credential in plain-text in the mof file, use the following configuration data
$ConfigData = @{
AllNodes = @(
@{
NodeName = "localhost";
# Allows credential to be saved in plain-text in the the *.mof instance document.
PSDscAllowPlainTextPassword = $true;
}
)
}
Sample_xComputer_DomainToWorkgroup -ConfigurationData $ConfigData -MachineName <machineName> -credential (Get-Credential) -WorkGroup <workgroupName>
****************************#> </pre>
<div class="preview">
<pre class="powershell"><span class="powerShell__keyword">function</span> Sample_xComputer_DomainToWorkgroup
{
<span class="powerShell__keyword">param</span>
(
[string[]]<span class="powerShell__variable">$NodeName</span>=<span class="powerShell__string">"localhost"</span>,
[Parameter(Mandatory)]
[string]<span class="powerShell__variable">$MachineName</span>,
[Parameter(Mandatory)]
[string]<span class="powerShell__variable">$WorkGroup</span>,
[Parameter(Mandatory)]
[pscredential]<span class="powerShell__variable">$Credential</span>
)
<span class="powerShell__com">#Import the required DSC Resources </span>
Import<span class="powerShell__operator">-</span>DscResource <span class="powerShell__operator">-</span>Module xComputerManagement
Node <span class="powerShell__variable">$NodeName</span>
{
xComputer JoinWorkgroup
{
Name = <span class="powerShell__variable">$MachineName</span>
WorkGroupName = <span class="powerShell__variable">$WorkGroup</span>
Credential = <span class="powerShell__variable">$Credential</span> <span class="powerShell__com"># Credential to unjoin from domain</span>
}
}
}
<span class="powerShell__mlcom"><#****************************
To save the credential in plain-text in the mof file, use the following configuration data
$ConfigData = @{
AllNodes = @(
@{
NodeName = "localhost";
# Allows credential to be saved in plain-text in the the *.mof instance document.
PSDscAllowPlainTextPassword = $true;
}
)
}
Sample_xComputer_DomainToWorkgroup -ConfigurationData $ConfigData -MachineName <machineName> -credential (Get-Credential) -WorkGroup <workgroupName>
****************************#></span> </pre>
</div>
</div>
</div>
</div>
</span></div>