salt.modules.win_system

Module for managing Windows systems and getting Windows system information. Support for reboot, shutdown, join domain, rename

depends:

• pywintypes

• win32api

• win32con

• win32net

• wmi

salt.modules.win_system.get_computer_desc()

Get the Windows computer description.

Returns:

Returns the computer description if found. Otherwise, returns

False.

Return type:

str

CLI Example:

salt 'minion-id' system.get_computer_desc

salt.modules.win_system.get_computer_description()

This function is an alias of get_computer_desc.

Get the Windows computer description.

Returns:

str: Returns the computer description if found. Otherwise, returns

False.

CLI Example:

salt 'minion-id' system.get_computer_desc

salt.modules.win_system.get_computer_name()

Get the Windows computer name

Returns:

Returns the computer name if found. Otherwise, returns False.

Return type:

str

CLI Example:

salt 'minion-id' system.get_computer_name

salt.modules.win_system.get_domain_workgroup()

Get the domain or workgroup the computer belongs to.

New in version 2015.5.7.

New in version 2015.8.2.

Returns:

The name of the domain or workgroup.

Return type:

str

CLI Example:

salt 'minion-id' system.get_domain_workgroup

salt.modules.win_system.get_hostname()

Get the hostname of the windows minion.

New in version 2016.3.0.

Returns:

Returns the hostname of the windows minion

Return type:

str

CLI Example:

salt 'minion-id' system.get_hostname

salt.modules.win_system.get_pending_component_servicing()

Determine whether there are pending Component Based Servicing tasks that require a reboot.

New in version 2016.11.0.

Returns:

True if there are pending Component Based Servicing tasks, otherwise False.

Return type:

bool

CLI Example:

salt '*' system.get_pending_component_servicing

salt.modules.win_system.get_pending_computer_name()

Get a pending computer name. If the computer name has been changed, and the change is pending a system reboot, this function will return the pending computer name. Otherwise, None will be returned. If there was an error retrieving the pending computer name, False will be returned, and an error message will be logged to the minion log.

Returns:

Returns the pending name if pending restart. Returns None if

not pending restart.

Return type:

str

CLI Example:

salt 'minion-id' system.get_pending_computer_name

salt.modules.win_system.get_pending_domain_join()

Determine whether there is a pending domain join action that requires a reboot.

New in version 2016.11.0.

Returns:

True if there is a pending domain join action, otherwise False.

Return type:

bool

CLI Example:

salt '*' system.get_pending_domain_join

salt.modules.win_system.get_pending_file_rename()

Determine whether there are pending file rename operations that require a reboot.

New in version 2016.11.0.

Returns:

True if there are pending file rename operations, otherwise False.

Return type:

bool

CLI Example:

salt '*' system.get_pending_file_rename

salt.modules.win_system.get_pending_reboot()

Determine whether there is a reboot pending.

New in version 2016.11.0.

Returns:

True if the system is pending reboot, otherwise False.

Return type:

bool

CLI Example:

salt '*' system.get_pending_reboot

salt.modules.win_system.get_pending_reboot_details()

Determine which check is signalling that the system is pending a reboot. Useful in determining why your system is signalling that it needs a reboot.

New in version 3001.

Returns:

A dictionary of the results of each system that would indicate a

pending reboot.

Return type:

dict

CLI Example:

salt '*' system.get_pending_reboot_details

salt.modules.win_system.get_pending_servermanager()

Determine whether there are pending Server Manager tasks that require a reboot.

New in version 2016.11.0.

Returns:

True if there are pending Server Manager tasks, otherwise False.

Return type:

bool

CLI Example:

salt '*' system.get_pending_servermanager

salt.modules.win_system.get_pending_update()

Determine whether there are pending updates that require a reboot.

New in version 2016.11.0.

Returns:

True if there are pending updates, otherwise False.

Return type:

bool

CLI Example:

salt '*' system.get_pending_update

salt.modules.win_system.get_pending_windows_update()

Check the Windows Update system for a pending reboot state.

This leverages the Windows Update System to determine if the system is pending a reboot.

New in version 3001.

Returns:

True if the Windows Update system reports a pending update,

otherwise False.

Return type:

bool

CLI Example:

salt '*' system.get_pending_windows_update

salt.modules.win_system.get_reboot_required_witnessed()

Determine if at any time during the current boot session the salt minion witnessed an event indicating that a reboot is required.

This function will return True if an install completed with exit code 3010 during the current boot session and can be extended where appropriate in the future.

New in version 2016.11.0.

Returns:

True if the Requires reboot registry flag is set to 1, otherwise False.

Return type:

bool

CLI Example:

salt '*' system.get_reboot_required_witnessed

salt.modules.win_system.get_system_date()

Get the Windows system date

Returns:

Returns the system date.

Return type:

str

CLI Example:

salt '*' system.get_system_date

salt.modules.win_system.get_system_info()

Get system information.

Note

Not all system info is available across all versions of Windows. If it is not available on an older version, it will be skipped

Returns:

Dictionary containing information about the system to include name, description, version, etc...

Return type:

dict

CLI Example:

salt 'minion-id' system.get_system_info

salt.modules.win_system.get_system_time()

Get the system time.

Returns:

Returns the system time in HH:MM:SS AM/PM format.

Return type:

str

CLI Example:

salt 'minion-id' system.get_system_time

salt.modules.win_system.halt(timeout=5, in_seconds=False)

Halt a running system.

Parameters:

• timeout (int, optional) --

  Number of minutes/seconds before halting the system.

  Default is 5 minutes.

• in_seconds (bool, optional) --

  Whether to treat timeout as seconds or minutes.

  Default is True.

  New in version 2015.8.0.

Returns:

True if successful, otherwise False.

Return type:

bool

CLI Example:

salt '*' system.halt 5 True

salt.modules.win_system.init(runlevel)

Change the system runlevel on sysV compatible systems. Not applicable to Windows

CLI Example:

salt '*' system.init 3

salt.modules.win_system.join_domain(domain, username=None, password=None, account_ou=None, account_exists=False, restart=False)

Join a computer to an Active Directory domain. Requires a reboot.

Parameters:

• domain (str) -- The domain to which the computer should be joined, e.g. example.com.

• username (str, optional) --

  Username of an account which is authorized to join computers to the specified domain. Needs to be either fully qualified like user@domain.tld or simply user.

  Default is None.

• password (str, optional) --

  Password of the specified user.

  Default is None.

• account_ou (str, optional) --

  The DN of the OU below which the account for this computer should be created when joining the domain, e.g. ou=computers,ou=departm_432,dc=my-company,dc=com.

  Default is None.

• account_exists (bool, optional) --

  If set to True the computer will only join the domain if the account already exists. If set to False, the computer account will be created if it does not exist, otherwise it will use the existing account.

  Default is False.

• restart (bool, optional) --

  True will restart the computer after a successful join.

  Default is False.

  New in version 2015.5.7,2015.8.2.

Returns:

Returns a dictionary if successful, otherwise False

Return type:

dict

CLI Example:

salt 'minion-id' system.join_domain domain='domain.tld' \
                 username='joinuser' password='joinpassword' \
                 account_ou='ou=clients,ou=org,dc=domain,dc=tld' \
                 account_exists=False, restart=True

salt.modules.win_system.lock()

Lock the workstation.

Returns:

True if successful, otherwise False.

Return type:

bool

CLI Example:

salt 'minion-id' system.lock

salt.modules.win_system.poweroff(timeout=5, in_seconds=False)

Power off a running system.

Parameters:

• timeout (int, optional) --

  Number of minutes/seconds before powering off the system.

  Default is 5 minutes.

• in_seconds (bool, optional) --

  Whether to treat timeout as seconds or minutes.

  New in version 2015.8.0.

  Default is False.

Returns:

True if successful, otherwise False.

Return type:

bool

CLI Example:

salt '*' system.poweroff 5

salt.modules.win_system.reboot(timeout=5, in_seconds=False, wait_for_reboot=False, only_on_pending_reboot=False)

Reboot a running system.

Parameters:

• timeout (int, optional) --

  The number of minutes/seconds before rebooting the system. Use of minutes or seconds depends on the value of in_seconds.

  Default is 5 minutes.

• in_seconds (bool, optional) --

  True will cause the timeout parameter to be in seconds. False will be in minutes.

  Default is False.

  New in version 2015.8.0.

• wait_for_reboot (bool, optional) --

  True will sleep for timeout + 30 seconds after reboot has been initiated. This is useful for use in a highstate. For example, you may have states that you want to apply only after the reboot.

  Default is False.

  New in version 2015.8.0.

• only_on_pending_reboot (bool, optional) --

  If this is set to True, then the reboot will only proceed if the system reports a pending reboot. Setting this parameter to True could be useful when calling this function from a final housekeeping state intended to be executed at the end of a state run (using order: last).

  Default is False.

Returns:

True if successful (a reboot will occur), otherwise False.

Return type:

bool

CLI Example:

salt '*' system.reboot 5
salt '*' system.reboot 5 True

Invoking this function from a final housekeeping state:

final_housekeeping:
  module.run:
    - name: system.reboot
    - only_on_pending_reboot: True
    - order: last

salt.modules.win_system.set_computer_desc(desc=None)

Set the Windows computer description.

Parameters:

desc (str, optional) --

The computer description.

Default is None.

Returns:

Description if successful, otherwise False.

Return type:

str

CLI Example:

salt 'minion-id' system.set_computer_desc 'This computer belongs to Dave!'

salt.modules.win_system.set_computer_description(desc=None)

This function is an alias of set_computer_desc.

Set the Windows computer description.

Args:

desc (str, optional): The computer description.

Default is None.

Returns:

str: Description if successful, otherwise False.

CLI Example:

salt 'minion-id' system.set_computer_desc 'This computer belongs to Dave!'

salt.modules.win_system.set_computer_name(name)

Set the Windows computer name

Parameters:

name (str) -- The new name to give the computer. Requires a reboot to take effect.

Returns:

Returns a dictionary containing the old and new names. bool: False if failed to set computer name

Return type:

dict

CLI Example:

salt 'minion-id' system.set_computer_name 'DavesComputer'

salt.modules.win_system.set_domain_workgroup(workgroup)

Set the domain or workgroup the computer belongs to.

New in version 3001.

Parameters:

workgroup (str) -- The name of the domain or workgroup.

Returns:

True if successful, otherwise False.

Return type:

bool

CLI Example:

salt 'minion-id' system.set_domain_workgroup LOCAL

salt.modules.win_system.set_hostname(hostname)

Set the hostname of the windows minion, requires a restart before this will be updated.

New in version 2016.3.0.

Parameters:

hostname (str) -- The hostname to set.

Returns:

True if successful, otherwise False.

Return type:

bool

CLI Example:

salt 'minion-id' system.set_hostname newhostname

salt.modules.win_system.set_reboot_required_witnessed()

This function is used to remember that an event indicating that a reboot is required was witnessed. This function relies on the salt-minion's ability to create the following volatile registry key in the HKLM hive:

SYSTEM\CurrentControlSet\Services\salt-minion\Volatile-Data

Because this registry key is volatile, it will not persist beyond the current boot session. Also, in the scope of this key, the name 'Reboot required' will be assigned the value of 1.

For the time being, this function is being used whenever an install completes with exit code 3010 and can be extended where appropriate in the future.

New in version 2016.11.0.

Returns:

True if successful, otherwise False.

Return type:

bool

CLI Example:

salt '*' system.set_reboot_required_witnessed

salt.modules.win_system.set_system_date(newdate)

Set the Windows system date. Use <mm-dd-yy> format for the date.

Parameters:

newdate (str) --

The date to set. Can be any of the following formats

• YYYY-MM-DD

• MM-DD-YYYY

• MM-DD-YY

• MM/DD/YYYY

• MM/DD/YY

• YYYY/MM/DD

Returns:

True if successful, otherwise False.

Return type:

bool

CLI Example:

salt '*' system.set_system_date '03-28-13'

salt.modules.win_system.set_system_date_time(years=None, months=None, days=None, hours=None, minutes=None, seconds=None)

Set the system date and time. Each argument is an element of the date, but not required. If an element is not passed, the current system value for that element will be used. For example, if you don't pass the year, the current system year will be used. (Used by set_system_date and set_system_time)

Parameters:

• years (int, optional) --

  Years digit, ie: 2015

  Default is None.

• months (int, optional) --

  Months digit: 1 - 12

  Default is None.

• days (int, optional) --

  Days digit: 1 - 31

  Default is None.

• hours (int, optional) --

  Hours digit: 0 - 23

  Default is None.

• minutes (int, optional) --

  Minutes digit: 0 - 59

  Default is None.

• seconds (int, optional) --

  Seconds digit: 0 - 59

  Default is None.

Returns:

True if successful, otherwise False.

Return type:

bool

CLI Example:

salt '*' system.set_system_date_ time 2015 5 12 11 37 53

salt.modules.win_system.set_system_time(newtime)

Set the system time.

Parameters:

newtime (str) --

The time to set. Can be any of the following formats:

• HH:MM:SS AM/PM

• HH:MM AM/PM

• HH:MM:SS (24 hour)

• HH:MM (24 hour)

Returns:

True if successful, otherwise False.

Return type:

bool

CLI Example:

salt 'minion-id' system.set_system_time 12:01

salt.modules.win_system.shutdown(message=None, timeout=5, force_close=True, reboot=False, in_seconds=False, only_on_pending_reboot=False)

Shutdown a running system.

Parameters:

• message (str, optional) --

  The message to display to the user before shutting down.

  Default is None.

• timeout (int, optional) --

  The length of time (in seconds) that the shutdown dialog box should be displayed. While this dialog box is displayed, the shutdown can be aborted using the system.shutdown_abort function.

  If timeout is not zero, InitiateSystemShutdown displays a dialog box on the specified computer. The dialog box displays the name of the user who called the function, the message specified by the lpMessage parameter, and prompts the user to log off. The dialog box beeps when it is created and remains on top of other windows (system modal). The dialog box can be moved but not closed. A timer counts down the remaining time before the shutdown occurs.

  If timeout is zero, the computer shuts down immediately without displaying the dialog box and cannot be stopped by system.shutdown_abort.

  Default is 5 minutes

• in_seconds (bool, optional) --

  True will cause the timeout parameter to be in seconds.

  False will be in minutes.

  Default is False.

  New in version 2015.8.0.

• force_close (bool, optional) --

  True will force close all open applications. False will display a dialog box instructing the user to close open applications.

  Default is True.

• reboot (bool, optional) --

  True restarts the computer immediately after shutdown. False powers down the system.

  Default is False.

• only_on_pending_reboot (bool, optional) --

  If True the shutdown will only proceed if there is a reboot pending. False will shutdown the system. To optionally shutdown in a highstate, consider using the shutdown state instead of this module.

  Default is False.

Returns:

True if successful (a shutdown or reboot will occur),

otherwise False

Return type:

bool

CLI Example:

salt '*' system.shutdown 'System will shutdown in 5 minutes'

salt.modules.win_system.shutdown_abort()

Abort a shutdown. Only available while the dialog box is being displayed to the user. Once the shutdown has initiated, it cannot be aborted.

Returns:

True if successful, otherwise False.

Return type:

bool

CLI Example:

salt 'minion-id' system.shutdown_abort

salt.modules.win_system.shutdown_hard()

Shutdown a running system with no timeout or warning.

Returns:

True if successful, otherwise False.

Return type:

bool

CLI Example:

salt '*' system.shutdown_hard

salt.modules.win_system.start_time_service()

Start the Windows time service.

Returns:

True if successful, otherwise False.

Return type:

bool

CLI Example:

salt '*' system.start_time_service

salt.modules.win_system.stop_time_service()

Stop the Windows time service.

Returns:

True if successful, otherwise False.

Return type:

bool

CLI Example:

salt '*' system.stop_time_service

salt.modules.win_system.unjoin_domain(username=None, password=None, domain=None, workgroup='WORKGROUP', disable=False, restart=False)

Unjoin a computer from an Active Directory Domain. Requires a restart.

Parameters:

• username (str, optional) --

  Username of an account which is authorized to manage computer accounts on the domain. Needs to be a fully qualified name like user@domain.tld or domain.tld\user. If the domain is not specified, the passed domain will be used. If the computer account doesn't need to be disabled after the computer is unjoined, this can be None.

  Default is None.

• password (str, optional) --

  The password of the specified user.

  Default is None.

• domain (str, optional) --

  The domain from which to unjoin the computer. Can be None.

  Default is None.

• workgroup (str, optional) --

  The workgroup to join the computer to.

  Default is WORKGROUP.

  New in version 2015.5.7,2015.8.2.

• disable (bool, optional) --

  True to disable the computer account in Active Directory.

  Default is False

• restart (bool, optional) --

  True will restart the computer after successful unjoin.

  Default is False.

  New in version 2015.5.7,2015.8.2.

Returns:

Returns a dictionary if successful, otherwise False.

Return type:

dict

CLI Example:

salt 'minion-id' system.unjoin_domain restart=True

salt 'minion-id' system.unjoin_domain username='unjoinuser' \
                 password='unjoinpassword' disable=True \
                 restart=True