salt.modules.win_system¶

Module for managing windows systems.

depends:	win32net

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

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

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

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.

CLI Example:

salt 'minion-id' system.get_pending_computer_name

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:	Returns a Dictionary containing information about the system to include name, description, version, etc...
Return type:	dict

salt.modules.win_system.get_system_time()¶

Get the system time.

Returns:	Returns the system time in HH:MM AM/PM format.
Return type:	str

salt.modules.win_system.halt(timeout=5)¶

Halt a running system.

Parameters:	timeout (int) -- Number of seconds before halting the system. Default is 5 seconds.
Returns:	True is successful.
Return type:	bool

CLI Example:

salt '*' system.halt

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:

Parameters:	domain (str) -- The domain to which the computer should be joined, e.g. `my-company.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) -- Needs to be set to `True` to allow re-using an existing account restart (bool) -- Restarts the computer after a successful join

domain (str) -- The domain to which the computer should be joined, e.g. my-company.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) -- Needs to be set to True to allow re-using an existing account
restart (bool) -- Restarts the computer after a successful join

New in version 2015.5.7.

New in version 2015.8.2.

Returns:	Returns a dictionary if successful. False if unsuccessful.
Return type:	dict, bool

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
Return type:	bool

salt.modules.win_system.poweroff(timeout=5)¶

Power off a running system.

Parameters:	timeout (int) -- Number of seconds before powering off the system. Default is 5 seconds.
Returns:	True if successful
Return type:	bool

CLI Example:

salt '*' system.poweroff

salt.modules.win_system.reboot(timeout=5)¶

Reboot a running system.

Parameters:	timeout (int) -- Number of seconds before rebooting the system. Default is 5 seconds.
Returns:	True if successful
Return type:	bool

CLI Example:

salt '*' system.reboot

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

Set the Windows computer description

Parameters:	desc (str) -- The computer description
Returns:	False if it fails. Description if successful.

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.

CLI Example:

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

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:	Returns True if successful. Otherwise False.
Return type:	bool

salt.modules.win_system.shutdown(message=None, timeout=5, force_close=True, 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 dwTimeout 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 dwTimeout is zero, the computer shuts down without displaying the dialog box, and the shutdown cannot be stopped by shutdown_abort. Default is 5 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.
Returns:	True if successful
Return type:	bool

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
Return type:	bool

salt.modules.win_system.shutdown_hard()¶

Shutdown a running system with no timeout or warning.

Parameters:	timeout (int) -- Number of seconds before shutting down the system. Default is 5 seconds.
Returns:	True if successful
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:

Parameters:	username -- 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

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

New in version 2015.8.2.

Parameters:	disable (bool) -- Disable the user account in Active Directory. True to disable. restart (bool) -- Restart the computer after successful unjoin

New in version 2015.5.7.

New in version 2015.8.2.

Returns:	Returns a dictionary if successful. False if unsuccessful.
Return type:	dict, bool

CLI Example:

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

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

You are viewing docs for the previous stable release, 2015.5.11. Switch to docs for the latest stable release, 2016.3.2, or to a recent doc build from the develop branch.

saltstack.com