Module for working with Windows PowerShell DSC (Desired State Configuration)
This module is Alpha
This module applies DSC Configurations in the form of PowerShell scripts or MOF (Managed Object Format) schema files.
Use the psget
module to manage PowerShell resources.
The idea is to leverage Salt to push DSC configuration scripts or MOF files to the Minion.
PowerShell 5.0
salt.modules.win_dsc.
apply_config
(path, source=None, salt_env='base')¶Run an compiled DSC configuration (a folder containing a .mof file). The
folder can be cached from the salt master using the source
option.
path (str) -- Local path to the directory that contains the .mof configuration file to apply. Required.
source (str) -- Path to the directory that contains the .mof file on the
file_roots
. The source directory will be copied to the path
directory and then executed. If the path and source directories
differ, the source directory will be applied. If source is not
passed, the config located at path
will be applied. Optional.
salt_env (str) -- The salt environment to use when copying your source. Default is 'base'
True if successful, otherwise False
CLI Example:
To apply a config that already exists on the the system
salt '*' dsc.apply_config C:\\DSC\\WebSiteConfiguration
To cache a configuration from the master and apply it:
salt '*' dsc.apply_config C:\\DSC\\WebSiteConfiguration salt://dsc/configs/WebSiteConfiguration
salt.modules.win_dsc.
compile_config
(path, source=None, config_name=None, config_data=None, config_data_source=None, script_parameters=None, salt_env='base')¶Compile a config from a PowerShell script (.ps1
)
path (str) -- Path (local) to the script that will create the .mof
configuration file. If no source is passed, the file must exist
locally. Required.
source (str) -- Path to the script on file_roots
to cache at the
location specified by path
. The source file will be cached
locally and then executed. If source is not passed, the config
script located at path
will be compiled. Optional.
config_name (str) -- The name of the Configuration within the script to
apply. If the script contains multiple configurations within the
file a config_name
must be specified. If the config_name
is
not specified, the name of the file will be used as the
config_name
to run. Optional.
config_data (str) --
Configuration data in the form of a hash table that
will be passed to the ConfigurationData
parameter when the
config_name
is compiled. This can be the path to a .psd1
file containing the proper hash table or the PowerShell code to
create the hash table.
New in version 2017.7.0.
config_data_source (str) --
The path to the .psd1
file on
file_roots
to cache at the location specified by
config_data
. If this is specified, config_data
must be a
local path instead of a hash table.
New in version 2017.7.0.
script_parameters (str) --
Any additional parameters expected by the configuration script. These must be defined in the script itself.
New in version 2017.7.0.
salt_env (str) -- The salt environment to use when copying the source. Default is 'base'
A dictionary containing the results of the compilation
CLI Example:
To compile a config from a script that already exists on the system:
salt '*' dsc.compile_config C:\\DSC\\WebsiteConfig.ps1
To cache a config script to the system from the master and compile it:
salt '*' dsc.compile_config C:\\DSC\\WebsiteConfig.ps1 salt://dsc/configs/WebsiteConfig.ps1
salt.modules.win_dsc.
get_config
()¶Get the current DSC Configuration
A dictionary representing the DSC Configuration on the machine
CommandExecutionError -- On failure
CLI Example:
salt '*' dsc.get_config
salt.modules.win_dsc.
get_config_status
()¶Get the status of the current DSC Configuration
Configuration on the machine
CLI Example:
salt '*' dsc.get_config_status
salt.modules.win_dsc.
get_lcm_config
()¶Get the current Local Configuration Manager settings
on the machine
CLI Example:
salt '*' dsc.get_lcm_config
salt.modules.win_dsc.
remove_config
(reset=False)¶Remove the current DSC Configuration. Removes current, pending, and previous dsc configurations.
New in version 2017.7.5.
reset (bool) --
Attempts to reset the DSC configuration by removing the following
from C:\Windows\System32\Configuration
:
File: DSCStatusHistory.mof
File: DSCEngineCache.mof
Dir: ConfigurationStatus
Default is False
Warning
remove_config
may fail to reset the DSC environment if any
of the files in the ConfigurationStatus
directory. If you
wait a few minutes and run again, it may complete successfully.
True if successful
CommandExecutionError -- On failure
CLI Example:
salt '*' dsc.remove_config True
salt.modules.win_dsc.
restore_config
()¶Reapplies the previous configuration.
New in version 2017.7.5.
Note
The current configuration will be come the previous configuration. If run a second time back-to-back it is like toggling between two configs.
True if successfully restored
CommandExecutionError -- On failure
CLI Example:
salt '*' dsc.restore_config
salt.modules.win_dsc.
run_config
(path, source=None, config_name=None, config_data=None, config_data_source=None, script_parameters=None, salt_env='base')¶Compile a DSC Configuration in the form of a PowerShell script (.ps1) and
apply it. The PowerShell script can be cached from the master using the
source
option. If there is more than one config within the PowerShell
script, the desired configuration can be applied by passing the name in the
config
option.
This command would be the equivalent of running dsc.compile_config
followed by dsc.apply_config
.
path (str) -- The local path to the PowerShell script that contains the DSC Configuration. Required.
source (str) -- The path to the script on file_roots
to cache at the
location specified by path
. The source file will be cached
locally and then executed. If source is not passed, the config
script located at path
will be compiled. Optional.
config_name (str) -- The name of the Configuration within the script to
apply. If the script contains multiple configurations within the
file a config_name
must be specified. If the config_name
is
not specified, the name of the file will be used as the
config_name
to run. Optional.
config_data (str) --
Configuration data in the form of a hash table that
will be passed to the ConfigurationData
parameter when the
config_name
is compiled. This can be the path to a .psd1
file containing the proper hash table or the PowerShell code to
create the hash table.
New in version 2017.7.0.
config_data_source (str) --
The path to the .psd1
file on
file_roots
to cache at the location specified by
config_data
. If this is specified, config_data
must be a
local path instead of a hash table.
New in version 2017.7.0.
script_parameters (str) --
Any additional parameters expected by the configuration script. These must be defined in the script itself.
New in version 2017.7.0.
salt_env (str) -- The salt environment to use when copying the source. Default is 'base'
True if successfully compiled and applied, otherwise False
CLI Example:
To compile a config from a script that already exists on the system:
salt '*' dsc.run_config C:\\DSC\\WebsiteConfig.ps1
To cache a config script to the system from the master and compile it:
salt '*' dsc.run_config C:\\DSC\\WebsiteConfig.ps1 salt://dsc/configs/WebsiteConfig.ps1
salt.modules.win_dsc.
set_lcm_config
(config_mode=None, config_mode_freq=None, refresh_freq=None, reboot_if_needed=None, action_after_reboot=None, refresh_mode=None, certificate_id=None, configuration_id=None, allow_module_overwrite=None, debug_mode=False, status_retention_days=None)¶For detailed descriptions of the parameters see: https://msdn.microsoft.com/en-us/PowerShell/DSC/metaConfig
are:
ApplyOnly
ApplyAndMonitor
ApplyAndAutoCorrect
is checked and applied. Ignored if config_mode is set to ApplyOnly. Default is 15.
refresh_mode (str): How the LCM gets configurations. Valid values are:
Disabled
Push
Pull
configurations. (pull mode only) Default is 30.
configuration is applied. Default is False.
are:
ContinueConfiguration
StopConfiguration
access the configuration: (pull mode)
from a pull server. (pull mode)
ones on the target node.
debug_mode (str): Sets the debug level. Valid values are:
None
ForceModuleImport
All
current config.
Note
Either config_mode_freq
or refresh_freq
needs to be a
multiple of the other. See documentation on MSDN for more details.
True if successful, otherwise False
CLI Example:
salt '*' dsc.set_lcm_config ApplyOnly