Module for managing windows systems.
depends: |
|
---|
Support for reboot, shutdown, etc
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_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_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_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.
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: | |
---|---|
Returns: |
|
Return type: |
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: |
|
---|---|
Returns: | Returns a dictionary if successful, otherwise |
Return type: |
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: | |
---|---|
Returns: |
|
Return type: |
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: |
|
---|---|
Returns: |
|
Return type: |
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) -- The computer description |
---|---|
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_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)¶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
|
---|---|
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: | |
---|---|
Returns: |
|
Return type: |
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:
|
---|---|
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: |
|
---|---|
Returns: |
|
Return type: |
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: |
|
---|---|
Returns: | Returns a dictionary if successful, otherwise |
Return type: |
CLI Example:
salt 'minion-id' system.unjoin_domain restart=True
salt 'minion-id' system.unjoin_domain username='unjoinuser' \\
password='unjoinpassword' disable=True \\
restart=True