| Dir : /proc/self/root/opt/saltstack/salt/lib/python3.10/site-packages/salt/utils/ |
| Server: Linux ngx353.inmotionhosting.com 4.18.0-553.22.1.lve.1.el8.x86_64 #1 SMP Tue Oct 8 15:52:54 UTC 2024 x86_64 IP: 209.182.202.254 |
| Dir : //proc/self/root/opt/saltstack/salt/lib/python3.10/site-packages/salt/utils/win_system.py |
"""
Win System Utils
Functions shared with salt.modules.win_system and salt.grains.pending_reboot
.. versionadded:: 3001
"""
# NOTE: DO NOT USE RAW STRINGS IN THIS MODULE! UNICODE_LITERALS DOES NOT PLAY
# NICELY WITH RAW STRINGS CONTAINING \u or \U.
import logging
import salt.utils.win_reg
import salt.utils.win_update
try:
import win32api
import win32con
HAS_WIN32_MODS = True
except ImportError:
HAS_WIN32_MODS = False
log = logging.getLogger(__name__)
# Define the module's virtual name
__virtualname__ = "win_system"
MINION_VOLATILE_KEY = "SYSTEM\\CurrentControlSet\\Services\\salt-minion\\Volatile-Data"
REBOOT_REQUIRED_NAME = "Reboot required"
def __virtual__():
"""
Only works on Windows systems
"""
if not salt.utils.platform.is_windows():
return (
False,
"win_system salt util failed to load: "
"The util will only run on Windows systems",
)
if not HAS_WIN32_MODS:
return (
False,
"win_system salt util failed to load: "
"The util will only run on Windows systems",
)
return __virtualname__
def get_computer_name():
"""
Get the Windows computer name. Uses the win32api to get the current computer
name.
.. versionadded:: 3001
Returns:
str: Returns the computer name if found. Otherwise returns ``False``.
Example:
.. code-block:: python
import salt.utils.win_system
salt.utils.win_system.get_computer_name()
"""
name = win32api.GetComputerNameEx(win32con.ComputerNamePhysicalDnsHostname)
return name if name else False
def 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.
.. versionadded:: 3001
Returns:
str:
Returns the pending name if pending restart. Returns ``None`` if not
pending restart.
Example:
.. code-block:: python
import salt.utils.win_system
salt.utils.win_system.get_pending_computer_name()
"""
current = get_computer_name()
try:
pending = salt.utils.win_reg.read_value(
hive="HKLM",
key="SYSTEM\\CurrentControlSet\\Services\\Tcpip\\Parameters",
vname="NV Hostname",
)["vdata"]
except TypeError:
# This should never happen as the above key and vname are system names
# and should always be present
return None
if pending:
return pending if pending.lower() != current.lower() else None
def get_pending_component_servicing():
"""
Determine whether there are pending Component Based Servicing tasks that
require a reboot.
If any the following registry keys exist then a reboot is pending:
``HKLM:\\\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Component Based Servicing\\RebootPending``
``HKLM:\\\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Component Based Servicing\\RebootInProgress``
``HKLM:\\\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Component Based Servicing\\PackagesPending``
.. versionadded:: 3001
Returns:
bool: ``True`` if there are pending Component Based Servicing tasks,
otherwise ``False``
CLI Example:
.. code-block:: bash
salt '*' system.get_pending_component_servicing
"""
# So long as one of the registry keys exists, a reboot is pending
base_key = "SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Component Based Servicing"
sub_keys = ("RebootPending", "RebootInProgress", "PackagesPending")
for sub_key in sub_keys:
key = "\\".join((base_key, sub_key))
if salt.utils.win_reg.key_exists(hive="HKLM", key=key):
return True
return False
def get_pending_domain_join():
"""
Determine whether there is a pending domain join action that requires a
reboot.
If any the following registry keys exist then a reboot is pending:
``HKLM:\\\\SYSTEM\\CurrentControlSet\\Services\\Netlogon\\AvoidSpnSet``
``HKLM:\\\\SYSTEM\\CurrentControlSet\\Services\\Netlogon\\JoinDomain``
.. versionadded:: 3001
Returns:
bool: ``True`` if there is a pending domain join action, otherwise
``False``
Example:
.. code-block:: python
import salt.utils.win_system
salt.utils.win_system.get_pending_domain_join()
"""
base_key = "SYSTEM\\CurrentControlSet\\Services\\Netlogon"
sub_keys = ("AvoidSpnSet", "JoinDomain")
# If any keys are present then there is a reboot pending.
for sub_key in sub_keys:
key = "\\".join((base_key, sub_key))
if salt.utils.win_reg.key_exists(hive="HKLM", key=key):
return True
return False
def get_pending_file_rename():
"""
Determine whether there are pending file rename operations that require a
reboot.
A reboot is pending if any of the following value names exist and have value
data set:
- ``PendingFileRenameOperations``
- ``PendingFileRenameOperations2``
in the following registry key:
``HKLM:\\\\SYSTEM\\CurrentControlSet\\Control\\Session Manager``
.. versionadded:: 3001
Returns:
bool: ``True`` if there are pending file rename operations, otherwise
``False``
Example:
.. code-block:: python
import salt.utils.win_system
salt.utils.win_system.get_pending_file_rename()
"""
vnames = ("PendingFileRenameOperations", "PendingFileRenameOperations2")
key = "SYSTEM\\CurrentControlSet\\Control\\Session Manager"
for vname in vnames:
reg_ret = salt.utils.win_reg.read_value(hive="HKLM", key=key, vname=vname)
if reg_ret["success"]:
if reg_ret["vdata"] and (reg_ret["vdata"] != "(value not set)"):
return True
return False
def get_pending_servermanager():
"""
Determine whether there are pending Server Manager tasks that require a
reboot.
A reboot is pending if the ``CurrentRebootAttempts`` value name exists and
has an integer value. The value name resides in the following registry key:
``HKLM:\\\\SOFTWARE\\Microsoft\\ServerManager``
.. versionadded:: 3001
Returns:
bool: ``True`` if there are pending Server Manager tasks, otherwise
``False``
Example:
.. code-block:: python
import salt.utils.win_system
salt.utils.win_system.get_pending_servermanager()
"""
vname = "CurrentRebootAttempts"
key = "SOFTWARE\\Microsoft\\ServerManager"
# There are situations where it's possible to have '(value not set)' as
# the value data, and since an actual reboot won't be pending in that
# instance, just catch instances where we try unsuccessfully to cast as int.
reg_ret = salt.utils.win_reg.read_value(hive="HKLM", key=key, vname=vname)
if reg_ret["success"]:
try:
if int(reg_ret["vdata"]) > 0:
return True
except ValueError:
pass
return False
def get_pending_dvd_reboot():
"""
Determine whether the DVD Reboot flag is set.
The system requires a reboot if the ``DVDRebootSignal`` value name exists
at the following registry location:
``HKLM:\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\RunOnce``
.. versionadded:: 3001
Returns:
bool: ``True`` if the above condition is met, otherwise ``False``
Example:
.. code-block:: python
import salt.utils.win_system
salt.utils.win_system.get_pending_dvd_reboot()
"""
# So long as the registry key exists, a reboot is pending.
return salt.utils.win_reg.value_exists(
hive="HKLM",
key="SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\RunOnce",
vname="DVDRebootSignal",
)
def get_pending_update():
"""
Determine whether there are pending updates that require a reboot.
If either of the following registry keys exists, a reboot is pending:
``HKLM:\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\WindowsUpdate\\Auto Update\\RebootRequired``
``HKLM:\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\WindowsUpdate\\Auto Update\\PostRebootReporting``
.. versionadded:: 3001
Returns:
bool: ``True`` if any of the above conditions are met, otherwise
``False``
Example:
.. code-block:: python
import salt.utils.win_system
salt.utils.win_system.get_pending_update()
"""
# So long as any of the registry keys exists, a reboot is pending.
base_key = (
"SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\WindowsUpdate\\Auto Update"
)
sub_keys = ("RebootRequired", "PostRebootReporting")
for sub_key in sub_keys:
key = "\\".join((base_key, sub_key))
if salt.utils.win_reg.key_exists(hive="HKLM", key=key):
return True
return False
def 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.
If the ``Reboot required`` value name exists in the following location and
has a value of ``1`` then the system is pending reboot:
``HKLM:\\\\SYSTEM\\CurrentControlSet\\Services\\salt-minion\\Volatile-Data``
.. versionadded:: 3001
Returns:
bool: ``True`` if the ``Requires reboot`` registry flag is set to ``1``,
otherwise ``False``
Example:
.. code-block:: python
import salt.utils.win_system
salt.utils.win_system.get_reboot_required_witnessed()
"""
value_dict = salt.utils.win_reg.read_value(
hive="HKLM", key=MINION_VOLATILE_KEY, vname=REBOOT_REQUIRED_NAME
)
return value_dict["vdata"] == 1
def 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.
.. versionadded:: 3001
Returns:
bool: ``True`` if successful, otherwise ``False``
Example:
.. code-block:: python
import salt.utils.win_system
salt.utils.win_system.set_reboot_required_witnessed()
"""
return salt.utils.win_reg.set_value(
hive="HKLM",
key=MINION_VOLATILE_KEY,
volatile=True,
vname=REBOOT_REQUIRED_NAME,
vdata=1,
vtype="REG_DWORD",
)
def get_pending_update_exe_volatile():
"""
Determine whether there is a volatile update exe that requires a reboot.
Checks ``HKLM:\\Microsoft\\Updates``. If the ``UpdateExeVolatile`` value
name is anything other than 0 there is a reboot pending
.. versionadded:: 3001
Returns:
bool: ``True`` if there is a volatile exe, otherwise ``False``
Example:
.. code-block:: python
import salt.utils.win_system
salt.utils.win_system.get_pending_update_exe_volatile()
"""
key = "SOFTWARE\\Microsoft\\Updates"
reg_ret = salt.utils.win_reg.read_value(
hive="HKLM", key=key, vname="UpdateExeVolatile"
)
if reg_ret["success"]:
try:
if int(reg_ret["vdata"]) != 0:
return True
except ValueError:
pass
return False
def 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.
.. versionadded:: 3001
Returns:
bool: ``True`` if the Windows Update system reports a pending update,
otherwise ``False``
Example:
.. code-block:: python
import salt.utils.win_system
salt.utils.win_system.get_pending_windows_update()
"""
return salt.utils.win_update.needs_reboot()
def get_pending_reboot():
"""
Determine whether there is a reboot pending.
.. versionadded:: 3001
Returns:
bool: ``True`` if the system is pending reboot, otherwise ``False``
Example:
.. code-block:: python
import salt.utils.win_system
salt.utils.win_system.get_pending_reboot()
"""
# Order the checks for reboot pending in most to least likely.
checks = (
get_pending_update,
get_pending_windows_update,
get_pending_update_exe_volatile,
get_pending_file_rename,
get_pending_servermanager,
get_pending_component_servicing,
get_pending_dvd_reboot,
get_reboot_required_witnessed,
get_pending_computer_name,
get_pending_domain_join,
)
for check in checks:
if check():
return True
return False
def 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.
.. versionadded:: 3001
Returns:
dict: A dictionary of the results of each function that checks for a
pending reboot
Example:
.. code-block:: python
import salt.utils.win_system
salt.utils.win_system.get_pending_reboot_details()
"""
return {
"Pending Component Servicing": get_pending_component_servicing(),
"Pending Computer Rename": get_pending_computer_name() is not None,
"Pending DVD Reboot": get_pending_dvd_reboot(),
"Pending File Rename": get_pending_file_rename(),
"Pending Join Domain": get_pending_domain_join(),
"Pending ServerManager": get_pending_servermanager(),
"Pending Update": get_pending_update(),
"Pending Windows Update": get_pending_windows_update(),
"Reboot Required Witnessed": get_reboot_required_witnessed(),
"Volatile Update Exe": get_pending_update_exe_volatile(),
}