# salt.modules.win_dsc

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.

depends:

  - 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.

  Parameters:

    - 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'

  Returns:

    True if successful, otherwise False

  Return type:

    bool

  CLI Example:

  To apply a config that already exists on 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`)

  Parameters:

    - 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.

      Added 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.

      Added in version 2017.7.0.

    - script_parameters (str) --

      Any additional parameters expected by the configuration script. These must be defined in the script itself.

      Added in version 2017.7.0.

    - salt_env (str) -- The salt environment to use when copying the source. Default is 'base'

  Returns:

    A dictionary containing the results of the compilation

  Return type:

    dict

  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

  Returns:

    A dictionary representing the DSC Configuration on the machine

  Return type:

    dict

  Raises:

    CommandExecutionError -- On failure

  CLI Example:

      salt '*' dsc.get_config

salt.modules.win_dsc.get_config_status()

  Get the status of the current DSC Configuration

  Returns:

    A dictionary representing the status of the current DSC

      Configuration on the machine

  Return type:

    dict

  CLI Example:

      salt '*' dsc.get_config_status

salt.modules.win_dsc.get_lcm_config()

  Get the current Local Configuration Manager settings

  Returns:

    A dictionary representing the Local Configuration Manager settings

      on the machine

  Return type:

    dict

  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.

  Added in version 2017.7.5.

  Parameters:

    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 are in use. If you wait a few minutes and run again, it may complete successfully.

  Returns:

    True if successful

  Return type:

    bool

  Raises:

    CommandExecutionError -- On failure

  CLI Example:

      salt '*' dsc.remove_config True

salt.modules.win_dsc.restore_config()

  Reapplies the previous configuration.

  Added 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.

  Returns:

    True if successfully restored

  Return type:

    bool

  Raises:

    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`.

  Parameters:

    - 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.

      Added 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.

      Added in version 2017.7.0.

    - script_parameters (str) --

      Any additional parameters expected by the configuration script. These must be defined in the script itself. Note that these are passed to the script (the outermost scope), and not to the dsc configuration inside the script (the inner scope).

      Added in version 2017.7.0.

    - salt_env (str) -- The salt environment to use when copying the source. Default is 'base'

  Returns:

    True if successfully compiled and applied, otherwise False

  Return type:

    bool

  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

  To cache a config script to the system from the master and compile it, passing in script_parameters:

      salt '*' dsc.run_config path=C:\\DSC\\WebsiteConfig.ps1 source=salt://dsc/configs/WebsiteConfig.ps1 script_parameters="-hostname 'my-computer' -ip '192.168.1.10' -DnsArray '192.168.1.3','192.168.1.4','1.1.1.1'"

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

  config_mode (str): How the LCM applies the configuration. Valid values

    are:

    - ApplyOnly

    - ApplyAndMonitor

    - ApplyAndAutoCorrect

  config_mode_freq (int): How often, in minutes, the current configuration

    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

  refresh_freq (int): How often, in minutes, the LCM checks for updated

    configurations. (pull mode only) Default is 30.

  reboot_if_needed (bool): Reboot the machine if needed after a

    configuration is applied. Default is False.

  action_after_reboot (str): Action to take after reboot. Valid values

    are:

    - ContinueConfiguration

    - StopConfiguration

  certificate_id (guid): A GUID that specifies a certificate used to

    access the configuration: (pull mode)

  configuration_id (guid): A GUID that identifies the config file to get

    from a pull server. (pull mode)

  allow_module_overwrite (bool): New configs are allowed to overwrite old

    ones on the target node.

  debug_mode (str): Sets the debug level. Valid values are:

  > - None

  > - ForceModuleImport

  > - All

  status_retention_days (int): Number of days to keep status of the

    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.

  Returns:

    True if successful, otherwise False

  Return type:

    bool

  CLI Example:

      salt '*' dsc.set_lcm_config ApplyOnly

salt.modules.win_dsc.test_config()

  Tests the current applied DSC Configuration

  Returns:

    True if successfully applied, otherwise False

  Return type:

    bool

  CLI Example:

      salt '*' dsc.test_config