salt.modules.win_system

Module for managing windows systems.

depends:
  • pythoncom
  • pywintypes
  • win32api
  • win32con
  • win32net
  • wmi

Support for reboot, shutdown, etc

salt.modules.win_system.get_computer_desc()

Get the Windows computer description

Returns:The computer description if found, otherwise False
Return type:str

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()

New in version 2016.3.0.

Get the hostname of the windows minion

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 a reboot is pending, 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:The pending name if restart is pending, otherwise returns None.
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 a reboot is pending, 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 a reboot is pending, 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 pending reboot, otherwise False.
Return type:bool

CLI Example:

salt '*' system.get_pending_reboot
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 a reboot is pending, 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 a reboot is pending, otherwise False.
Return type:bool

CLI Example:

salt '*' system.get_pending_update
salt.modules.win_system.get_reboot_required_witnessed()

This tells us if, at any time during the current boot session the salt minion witnessed an event indicating that a reboot is required. (For the time being, this function will return True if an install completed with exit code 3010 during the current boot session and this usage can be extended where appropriate in the future)

New in version 2016.11.0.

Returns:True if reboot required, 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:The system date
Return type:str

CLI Example:

salt '*' system.get_system_date
salt.modules.win_system.get_system_info()

Get system information.

Returns:
Returns a Dictionary containing information about the system to
include name, description, version, etc...
Return type:dict

CLI Example:

salt 'minion-id' system.get_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) -- Number of seconds before halting the system. Default is
  • seconds. (5) --
  • in_seconds (bool) --

    Whether to treat timeout as seconds or minutes.

    New in version 2015.8.0.

Returns:

True if successful, otherwise False

Return type:

bool

CLI Example:

salt '*' system.halt 5
salt.modules.win_system.init(runlevel)

Change the system runlevel on sysV compatible systems

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

Parameters:
  • domain (str) -- The domain to which the computer should be joined, e.g. example.com
  • username (str) -- Username of an account which is authorized to join computers to the specified domain. Need to be either fully qualified like user@domain.tld or simply user
  • password (str) -- Password of the specified user
  • account_ou (str) -- 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
  • account_exists (bool) -- 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) --

    Restarts the computer after a successful join

    New in version 2015.8.2/2015.5.7.

Returns:

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) -- Number of seconds before powering off the system. Default is 5 seconds.
  • in_seconds (bool) -- Whether to treat timeout as seconds or minutes. .. versionadded:: 2015.8.0
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) -- Number of minutes/seconds before rebooting the system. Minutes vs seconds depends on the value of in_seconds. Default is 5 minutes.
  • in_seconds (bool) --

    Whether to treat timeout as seconds or minutes.

    New in version 2015.8.0.

  • wait_for_reboot (bool) --

    Sleeps for timeout + 30 seconds after reboot has been initiated. This may be useful for use in a highstate if a reboot should be performed and the return data of the highstate is not required. If return data is required, consider using the reboot state instead of this module.

    New in version 2015.8.0.

  • only_on_pending_reboot (bool) -- If this is set to True, then the reboot will only proceed if the system reports a pending reboot. To optionally reboot in a highstate, consider using the reboot state instead of this module.
Returns:

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

Return type:

bool

CLI Example:

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

As example of invoking this function from within a final housekeeping state is as follows:

Example:

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) -- The computer description
Returns:True if successful, otherwise False
Return type:bool

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 if
successful. False if not.
Return type:dict

CLI Example:

salt 'minion-id' system.set_computer_name 'DavesComputer'
salt.modules.win_system.set_hostname(hostname)

New in version 2016.3.0.

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

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 this function is being used whenever an install completes with exit code 3010 and this usage can be extended where appropriate in the future.)

New in version 2016.11.0.

Returns:True if registry entry set successfuly, 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

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) -- Years digit, ie: 2015
  • months (int) -- Months digit: 1 - 12
  • days (int) -- Days digit: 1 - 31
  • hours (int) -- Hours digit: 0 - 23
  • minutes (int) -- Minutes digit: 0 - 59
  • seconds (int) -- Seconds digit: 0 - 59
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) -- A message to display to the user before shutting down.
  • timeout (int) --

    The length of time that the shutdown dialog box should be displayed, in seconds. While this dialog box is displayed, the shutdown can be stopped by the 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, displays 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 in the system. The dialog box can be moved but not closed. A timer counts down the remaining time before a forced shutdown.

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

    Default is 5 minutes

  • in_seconds (bool) --

    Whether to treat timeout as seconds or minutes.

    New in version 2015.8.0.

  • force_close (bool) -- True to force close all open applications. False displays a dialog box instructing the user to close the applications.
  • reboot (bool) -- True restarts the computer immediately after shutdown. False caches to disk and safely powers down the system.
  • only_on_pending_reboot (bool) -- If this is set to True, then the shutdown will only proceed if the system reports a pending reboot. To optionally shutdown in a highstate, consider using the shutdown state instead of this module.
Returns:

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

False

Return type:

bool

CLI Example:

salt '*' system.shutdown 5
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 restart.

Parameters:
  • username (str) -- Username of an account which is authorized to manage computer accounts on the domain. Need to be fully qualified like user@domain.tld or domain.tld\user. If domain not specified, the passed domain will be used. If computer account doesn't need to be disabled, can be None.
  • password (str) -- Password of the specified user
  • domain (str) -- The domain from which to unjoin the computer. Can be None.
  • workgroup (str) --

    The workgroup to join the computer to. Default is WORKGROUP

    New in version 2015.8.2/2015.5.7.

  • disable (bool) -- Disable the computer account in Active Directory. True to disable. Default is False
  • restart (bool) --

    Restart the computer after successful unjoin

    New in version 2015.8.2/2015.5.7.

Returns:

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