From a12bc5ae411c130dc385b2ab48101edc97a697a5 Mon Sep 17 00:00:00 2001 From: twangboy Date: Wed, 18 Oct 2017 16:15:58 -0600 Subject: [PATCH 1/6] Use google style docstrings --- salt/modules/win_system.py | 501 ++++++++++++++++++++----------------- 1 file changed, 265 insertions(+), 236 deletions(-) diff --git a/salt/modules/win_system.py b/salt/modules/win_system.py index 7e3043d38e..2520d51bcb 100644 --- a/salt/modules/win_system.py +++ b/salt/modules/win_system.py @@ -69,33 +69,33 @@ def halt(timeout=5, in_seconds=False): ''' Halt a running system. - :param int timeout: - Number of seconds before halting the system. - Default is 5 seconds. + Args: - :return: True is successful. - :rtype: bool + timeout (int): + Number of seconds before halting the system. Default is 5 seconds. - timeout - The wait time before the system will be shutdown. - in_seconds - Whether to treat timeout as seconds or minutes. + in_seconds (bool): + Whether to treat timeout as seconds or minutes. .. versionadded:: 2015.8.0 + Returns: + bool: True if successful, otherwise False + CLI Example: .. code-block:: bash - salt '*' system.halt 5 + salt '*' system.halt 5 True ''' return shutdown(timeout=timeout, in_seconds=in_seconds) def init(runlevel): # pylint: disable=unused-argument ''' - Change the system runlevel on sysV compatible systems + Change the system runlevel on sysV compatible systems. Not applicable to + Windows CLI Example: @@ -117,20 +117,19 @@ def poweroff(timeout=5, in_seconds=False): ''' Power off a running system. - :param int timeout: - Number of seconds before powering off the system. - Default is 5 seconds. + Args: - :return: True if successful - :rtype: bool + timeout (int): + Number of seconds before powering off the system. Default is 5 + seconds. - timeout - The wait time before the system will be shutdown. + in_seconds (bool): + Whether to treat timeout as seconds or minutes. - in_seconds - Whether to treat timeout as seconds or minutes. + .. versionadded:: 2015.8.0 - .. versionadded:: 2015.8.0 + Returns: + bool: True if successful, otherwise False CLI Example: @@ -146,35 +145,36 @@ def reboot(timeout=5, in_seconds=False, wait_for_reboot=False, # pylint: disabl ''' Reboot a running system. - :param int timeout: - Number of minutes/seconds before rebooting the system. Minutes vs - seconds depends on the value of ``in_seconds``. - Default is 5 minutes. + Args: - :param bool in_seconds: - Whether to treat timeout as seconds or minutes. + timeout (int): + Number of minutes/seconds before rebooting the system. Minutes vs + seconds depends on the value of ``in_seconds``. Default is 5 + minutes. - .. versionadded:: 2015.8.0 + in_seconds (bool): + Whether to treat timeout as seconds or minutes. - :param bool wait_for_reboot: + .. versionadded:: 2015.8.0 - Sleeps for timeout + 30 seconds after reboot has been initiated. - This is useful for use in a highstate for example where - you have many states that could be ran after this one. Which you don't want - to start until after the restart i.e You could end up with a half finished state. + wait_for_reboot (bool) + Sleeps for timeout + 30 seconds after reboot has been initiated. + This is useful for use in a highstate for example where you have + many states that could be ran after this one. Which you don't want + to start until after the restart i.e You could end up with a half + finished state. - .. versionadded:: 2015.8.0 + .. versionadded:: 2015.8.0 - :param bool only_on_pending_reboot: + only_on_pending_reboot (bool): + If this is set to True, then 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*). - If this is set to True, then 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*). - - :return: True if successful (a reboot will occur) - :rtype: bool + Returns: + bool: True if successful (a reboot will occur), otherwise False CLI Example: @@ -195,9 +195,7 @@ def reboot(timeout=5, in_seconds=False, wait_for_reboot=False, # pylint: disabl - name: system.reboot - only_on_pending_reboot: True - order: last - ''' - ret = shutdown(timeout=timeout, reboot=True, in_seconds=in_seconds, only_on_pending_reboot=only_on_pending_reboot) @@ -213,52 +211,56 @@ def shutdown(message=None, timeout=5, force_close=True, reboot=False, # pylint: ''' Shutdown a running system. - :param str message: - A message to display to the user before shutting down. + Args: - :param int timeout: - 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. + message (str): + A message to display to the user before shutting down. - 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. + 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 zero, the computer shuts down without displaying the - dialog box, and the shutdown cannot be stopped by shutdown_abort. + 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. - Default is 5 minutes + If timeout is zero, the computer shuts down without displaying the + dialog box, and the shutdown cannot be stopped by shutdown_abort. - :param bool in_seconds: - Whether to treat timeout as seconds or minutes. + Default is 5 minutes - .. versionadded:: 2015.8.0 + in_seconds (bool): + Whether to treat timeout as seconds or minutes. - :param bool force_close: - True to force close all open applications. False displays a dialog box - instructing the user to close the applications. + .. versionadded:: 2015.8.0 - :param bool reboot: - True restarts the computer immediately after shutdown. - False caches to disk and safely powers down the system. + force_close (bool): + True to force close all open applications. False displays a dialog + box instructing the user to close the applications. - :param bool only_on_pending_reboot: - If this is set to True, then then shutdown will only proceed - if the system reports a pending reboot. + reboot (bool): + True restarts the computer immediately after shutdown. False caches + to disk and safely powers down the system. - :return: True if successful (a shutdown or reboot will occur) - :rtype: bool + only_on_pending_reboot (bool): + If this is set to True, then then shutdown will only proceed if the + system reports a pending reboot. + + Returns: + bool: + True if successful (a shutdown or reboot will occur), otherwise + False CLI Example: .. code-block:: bash - salt '*' system.shutdown 5 + salt '*' system.shutdown "System will shutdown in 5 minutes" ''' timeout = _convert_minutes_seconds(timeout, in_seconds) @@ -284,8 +286,8 @@ def shutdown_hard(): ''' Shutdown a running system with no timeout or warning. - :return: True if successful - :rtype: bool + Returns: + bool: True if successful, otherwise False CLI Example: @@ -301,8 +303,8 @@ def 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 - :return: True if successful - :rtype: bool + Returns: + bool: True if successful, otherwise False CLI Example: @@ -326,8 +328,8 @@ def lock(): ''' Lock the workstation. - :return: True if successful - :rtype: bool + Returns: + bool: True if successful, otherwise False CLI Example: @@ -342,12 +344,15 @@ def set_computer_name(name): ''' Set the Windows computer name - :param str name: - The new name to give the computer. Requires a reboot to take effect. + Args: - :return: - Returns a dictionary containing the old and new names if successful. - False if not. + name (str): + The new name to give the computer. Requires a reboot to take effect. + + Returns: + dict: + Returns a dictionary containing the old and new names if successful. + False if not. CLI Example: @@ -376,9 +381,10 @@ def get_pending_computer_name(): retrieving the pending computer name, ``False`` will be returned, and an error message will be logged to the minion log. - :return: - Returns the pending name if pending restart. Returns none if not pending - restart. + Returns: + str: + Returns the pending name if pending restart. Returns none if not + pending restart. CLI Example: @@ -400,8 +406,8 @@ def get_computer_name(): ''' Get the Windows computer name - :return: - Returns the computer name if found. Otherwise returns False + Returns: + str: Returns the computer name if found. Otherwise returns False CLI Example: @@ -417,10 +423,13 @@ def set_computer_desc(desc=None): ''' Set the Windows computer description - :param str desc: - The computer description + Args: - :return: False if it fails. Description if successful. + desc (str): + The computer description + + Returns: + str: Description if successful, otherwise False CLI Example: @@ -460,10 +469,9 @@ def get_system_info(): ''' Get system information. - :return: - Returns a Dictionary containing information about the system to include + Returns: + dict: Dictionary containing information about the system to include name, description, version, etc... - :rtype: dict CLI Example: @@ -514,8 +522,9 @@ def get_system_info(): def get_computer_desc(): ''' Get the Windows computer description - :return: - Returns the computer description if found. Otherwise returns False + + Returns: + str: Returns the computer description if found. Otherwise returns False CLI Example: @@ -532,12 +541,12 @@ get_computer_description = salt.utils.alias_function(get_computer_desc, 'get_com def get_hostname(): ''' - .. versionadded:: 2016.3.0 - Get the hostname of the windows minion - :return: - Returns the hostname of the windows minion + .. versionadded:: 2016.3.0 + + Returns: + str: Returns the hostname of the windows minion CLI Example: @@ -552,13 +561,16 @@ def get_hostname(): def set_hostname(hostname): ''' + Set the hostname of the windows minion, requires a restart before this will + be updated. + .. versionadded:: 2016.3.0 - Set the hostname of the windows minion, requires a restart before this - will be updated. + Args: + hostname (str): The hostname to set - :param str hostname: - The hostname to set + Returns: + bool: True if successful, otherwise False CLI Example: @@ -582,35 +594,38 @@ def join_domain(domain, ''' Join a computer to an Active Directory domain. Requires reboot. - :param str domain: - The domain to which the computer should be joined, e.g. - ``example.com`` + Args: - :param str username: - 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`` + domain (str): + The domain to which the computer should be joined, e.g. + ``example.com`` - :param str password: - Password of the specified user + 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`` - :param str account_ou: - 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`` + password (str): + Password of the specified user - :param bool account_exists: - 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 + 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`` - :param bool restart: Restarts the computer after a successful join + 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 - .. versionadded:: 2015.8.2/2015.5.7 + restart (bool): + Restarts the computer after a successful join - :returns: Returns a dictionary if successful. False if unsuccessful. - :rtype: dict, bool + .. versionadded:: 2015.8.2/2015.5.7 + + Returns: + dict: Returns a dictionary if successful, otherwise False CLI Example: @@ -680,32 +695,37 @@ def unjoin_domain(username=None, r''' Unjoin a computer from an Active Directory Domain. Requires restart. - :param 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. + Args: - :param str password: - Password of the specified user + 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. - :param str domain: The domain from which to unjoin the computer. Can be None + password (str): + Password of the specified user - :param str workgroup: The workgroup to join the computer to. Default is - ``WORKGROUP`` + domain (str): + The domain from which to unjoin the computer. Can be None - .. versionadded:: 2015.8.2/2015.5.7 + workgroup (str): + The workgroup to join the computer to. Default is ``WORKGROUP`` - :param bool disable: - Disable the computer account in Active Directory. True to disable. - Default is False + .. versionadded:: 2015.8.2/2015.5.7 - :param bool restart: Restart the computer after successful unjoin + disable (bool): + Disable the computer account in Active Directory. True to disable. + Default is False - .. versionadded:: 2015.8.2/2015.5.7 + restart (bool): + Restart the computer after successful unjoin - :returns: Returns a dictionary if successful. False if unsuccessful. - :rtype: dict, bool + .. versionadded:: 2015.8.2/2015.5.7 + + Returns: + dict: Returns a dictionary if successful, otherwise False CLI Example: @@ -772,8 +792,8 @@ def get_domain_workgroup(): .. versionadded:: 2015.5.7 .. versionadded:: 2015.8.2 - :return: The name of the domain or workgroup - :rtype: str + Returns: + str: The name of the domain or workgroup CLI Example: @@ -795,11 +815,14 @@ def _try_parse_datetime(time_str, fmts): ''' Attempts to parse the input time_str as a date. - :param str time_str: A string representing the time - :param list fmts: A list of date format strings + Args: - :return: Returns a datetime object if parsed properly. Otherwise None - :rtype datetime + time_str (str): A string representing the time + + fmts (list): A list of date format strings + + Returns: + datetime: Returns a datetime object if parsed properly, otherwise None ''' result = None for fmt in fmts: @@ -815,8 +838,8 @@ def get_system_time(): ''' Get the system time. - :return: Returns the system time in HH:MM:SS AM/PM format. - :rtype: str + Returns: + str: Returns the system time in HH:MM:SS AM/PM format. CLI Example: @@ -841,15 +864,17 @@ def set_system_time(newtime): ''' Set the system time. - :param str newtime: - 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) + Args: - :return: Returns True if successful. Otherwise False. - :rtype: bool + 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: + bool: Returns True if successful, otherwise False. CLI Example: @@ -881,15 +906,17 @@ def set_system_date_time(years=None, 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) - :param int years: Years digit, ie: 2015 - :param int months: Months digit: 1 - 12 - :param int days: Days digit: 1 - 31 - :param int hours: Hours digit: 0 - 23 - :param int minutes: Minutes digit: 0 - 59 - :param int seconds: Seconds digit: 0 - 59 + Args: - :return: True if successful. Otherwise False. - :rtype: bool + 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: + bool: True if successful, otherwise False. CLI Example: @@ -954,8 +981,8 @@ def get_system_date(): ''' Get the Windows system date - :return: Returns the system date. - :rtype: str + Returns: + str: Returns the system date. CLI Example: @@ -971,14 +998,18 @@ def set_system_date(newdate): ''' Set the Windows system date. Use format for the date. - :param str newdate: - 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 + Args: + 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: + bool: True if successful, otherwise False CLI Example: @@ -1003,8 +1034,8 @@ def start_time_service(): ''' Start the Windows time service - :return: True if successful. Otherwise False - :rtype: bool + Returns: + bool: True if successful, otherwise False CLI Example: @@ -1019,8 +1050,8 @@ def stop_time_service(): ''' Stop the Windows time service - :return: True if successful. Otherwise False - :rtype: bool + Returns: + bool: True if successful, otherwise False CLI Example: @@ -1033,13 +1064,15 @@ def stop_time_service(): def get_pending_component_servicing(): ''' - Determine whether there are pending Component Based Servicing tasks that require a reboot. - - :return: A boolean representing whether there are pending Component Based Servicing tasks. - :rtype: bool + Determine whether there are pending Component Based Servicing tasks that + require a reboot. .. versionadded:: 2016.11.0 + Returns: + bool: True if there are pending Component Based Servicing tasks, + otherwise False + CLI Example: .. code-block:: bash @@ -1062,13 +1095,14 @@ def get_pending_component_servicing(): def get_pending_domain_join(): ''' - Determine whether there is a pending domain join action that requires a reboot. - - :return: A boolean representing whether there is a pending domain join action. - :rtype: bool + Determine whether there is a pending domain join action that requires a + reboot. .. versionadded:: 2016.11.0 + Returns: + bool: True if there is a pending domain join action, otherwise False + CLI Example: .. code-block:: bash @@ -1103,13 +1137,14 @@ def get_pending_domain_join(): def get_pending_file_rename(): ''' - Determine whether there are pending file rename operations that require a reboot. - - :return: A boolean representing whether there are pending file rename operations. - :rtype: bool + Determine whether there are pending file rename operations that require a + reboot. .. versionadded:: 2016.11.0 + Returns: + bool: True if there are pending file rename operations, otherwise False + CLI Example: .. code-block:: bash @@ -1137,13 +1172,14 @@ def get_pending_file_rename(): def get_pending_servermanager(): ''' - Determine whether there are pending Server Manager tasks that require a reboot. - - :return: A boolean representing whether there are pending Server Manager tasks. - :rtype: bool + Determine whether there are pending Server Manager tasks that require a + reboot. .. versionadded:: 2016.11.0 + Returns: + bool: True if there are pending Server Manager tasks, otherwise False + CLI Example: .. code-block:: bash @@ -1176,11 +1212,11 @@ def get_pending_update(): ''' Determine whether there are pending updates that require a reboot. - :return: A boolean representing whether there are pending updates. - :rtype: bool - .. versionadded:: 2016.11.0 + Returns: + bool: True if there are pending updates, otherwise False + CLI Example: .. code-block:: bash @@ -1209,28 +1245,24 @@ REBOOT_REQUIRED_NAME = 'Reboot required' def set_reboot_required_witnessed(): r''' - .. versionadded:: 2016.11.0 - - 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: + 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*. + 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.) + (For the time being, this function is being used whenever an install + completes with exit code 3010 and this usage can be extended where + appropriate in the future.) - :return: A boolean indicating whether or not the salt minion was - able to perform the necessary registry operations. + .. versionadded:: 2016.11.0 - :rtype: bool + Returns: + bool: True if successful, otherwise False CLI Example: @@ -1249,20 +1281,17 @@ def set_reboot_required_witnessed(): def 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) + .. versionadded:: 2016.11.0 - 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) - - :return: a boolean which will be True if the salt-minion reported - a required reboot during the current boot session, otherwise False. - - :rtype: bool + Returns: + bool: True if the ``Requires reboot`` registry flag is set to ``1``, + otherwise False CLI Example: @@ -1281,11 +1310,11 @@ def get_pending_reboot(): ''' Determine whether there is a reboot pending. - :return: A boolean representing whether reboots are pending. - :rtype: bool - .. versionadded:: 2016.11.0 + Returns: + bool: True if the system is pending reboot, otherwise False + CLI Example: .. code-block:: bash From 8e111b413db3f37c48440665bc5b5aedab5b4dc7 Mon Sep 17 00:00:00 2001 From: twangboy Date: Tue, 24 Oct 2017 13:23:52 -0600 Subject: [PATCH 2/6] Fix some of the wording and grammer errors --- salt/modules/win_system.py | 192 +++++++++++++++++++------------------ 1 file changed, 100 insertions(+), 92 deletions(-) diff --git a/salt/modules/win_system.py b/salt/modules/win_system.py index 2520d51bcb..0eb6ef8a04 100644 --- a/salt/modules/win_system.py +++ b/salt/modules/win_system.py @@ -81,7 +81,7 @@ def halt(timeout=5, in_seconds=False): .. versionadded:: 2015.8.0 Returns: - bool: True if successful, otherwise False + bool: ``True`` if successful, otherwise ``False`` CLI Example: @@ -129,7 +129,7 @@ def poweroff(timeout=5, in_seconds=False): .. versionadded:: 2015.8.0 Returns: - bool: True if successful, otherwise False + bool: ``True`` if successful, otherwise ``False`` CLI Example: @@ -148,33 +148,33 @@ def reboot(timeout=5, in_seconds=False, wait_for_reboot=False, # pylint: disabl Args: timeout (int): - Number of minutes/seconds before rebooting the system. Minutes vs - seconds depends on the value of ``in_seconds``. Default is 5 - minutes. + 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): - Whether to treat timeout as seconds or minutes. + ``True`` will cause the ``timeout`` parameter to be in seconds. + ``False`` will be in minutes. Default is ``False``. .. versionadded:: 2015.8.0 wait_for_reboot (bool) - Sleeps for timeout + 30 seconds after reboot has been initiated. - This is useful for use in a highstate for example where you have - many states that could be ran after this one. Which you don't want - to start until after the restart i.e You could end up with a half - finished state. + ``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``. .. versionadded:: 2015.8.0 only_on_pending_reboot (bool): - If this is set to True, then 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*). + If this is set to ``True``, then 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: - bool: True if successful (a reboot will occur), otherwise False + bool: ``True`` if successful (a reboot will occur), otherwise ``False`` CLI Example: @@ -183,14 +183,11 @@ def reboot(timeout=5, in_seconds=False, wait_for_reboot=False, # pylint: disabl 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: + Invoking this function from a final housekeeping state: .. code-block:: yaml - final housekeeping: + final_housekeeping: module.run: - name: system.reboot - only_on_pending_reboot: True @@ -214,47 +211,50 @@ def shutdown(message=None, timeout=5, force_close=True, reboot=False, # pylint: Args: message (str): - A message to display to the user before shutting down. + The 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. + 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, 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. + 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 without displaying the - dialog box, and the shutdown cannot be stopped by shutdown_abort. + 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): - Whether to treat timeout as seconds or minutes. + ``True`` will cause the ``timeout`` parameter to be in seconds. + ``False`` will be in minutes. Default is ``False``. .. versionadded:: 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. + ``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): - True restarts the computer immediately after shutdown. False caches - to disk and safely powers down the system. + ``True`` restarts the computer immediately after shutdown. ``False`` + powers down the system. Default is ``False``. only_on_pending_reboot (bool): - If this is set to True, then then shutdown will only proceed if the - system reports a pending reboot. + If ``True`` the shutdown will only proceed if there is a reboot + pending. ``False`` will shutdown the system. Default is ``False``. Returns: bool: - True if successful (a shutdown or reboot will occur), otherwise - False + ``True`` if successful (a shutdown or reboot will occur), otherwise + ``False`` CLI Example: @@ -287,7 +287,7 @@ def shutdown_hard(): Shutdown a running system with no timeout or warning. Returns: - bool: True if successful, otherwise False + bool: ``True`` if successful, otherwise ``False`` CLI Example: @@ -304,7 +304,7 @@ def shutdown_abort(): displayed to the user. Once the shutdown has initiated, it cannot be aborted Returns: - bool: True if successful, otherwise False + bool: ``True`` if successful, otherwise ``False`` CLI Example: @@ -329,7 +329,7 @@ def lock(): Lock the workstation. Returns: - bool: True if successful, otherwise False + bool: ``True`` if successful, otherwise ``False`` CLI Example: @@ -352,7 +352,7 @@ def set_computer_name(name): Returns: dict: Returns a dictionary containing the old and new names if successful. - False if not. + ``False`` if not. CLI Example: @@ -383,7 +383,7 @@ def get_pending_computer_name(): Returns: str: - Returns the pending name if pending restart. Returns none if not + Returns the pending name if pending restart. Returns ``None`` if not pending restart. CLI Example: @@ -407,7 +407,7 @@ def get_computer_name(): Get the Windows computer name Returns: - str: Returns the computer name if found. Otherwise returns False + str: Returns the computer name if found. Otherwise returns ``False`` CLI Example: @@ -429,7 +429,7 @@ def set_computer_desc(desc=None): The computer description Returns: - str: Description if successful, otherwise False + str: Description if successful, otherwise ``False`` CLI Example: @@ -524,7 +524,8 @@ def get_computer_desc(): Get the Windows computer description Returns: - str: Returns the computer description if found. Otherwise returns False + str: Returns the computer description if found. Otherwise returns + ``False`` CLI Example: @@ -570,7 +571,7 @@ def set_hostname(hostname): hostname (str): The hostname to set Returns: - bool: True if successful, otherwise False + bool: ``True`` if successful, otherwise ``False`` CLI Example: @@ -592,7 +593,7 @@ def join_domain(domain, account_exists=False, restart=False): ''' - Join a computer to an Active Directory domain. Requires reboot. + Join a computer to an Active Directory domain. Requires a reboot. Args: @@ -602,7 +603,7 @@ def join_domain(domain, username (str): Username of an account which is authorized to join computers to the - specified domain. Need to be either fully qualified like + specified domain. Needs to be either fully qualified like ``user@domain.tld`` or simply ``user`` password (str): @@ -617,15 +618,16 @@ def join_domain(domain, 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 + existing account. Default is ``False`` restart (bool): - Restarts the computer after a successful join + ``True`` will restart the computer after a successful join. Default + is ``False`` .. versionadded:: 2015.8.2/2015.5.7 Returns: - dict: Returns a dictionary if successful, otherwise False + dict: Returns a dictionary if successful, otherwise ``False`` CLI Example: @@ -693,22 +695,23 @@ def unjoin_domain(username=None, disable=False, restart=False): r''' - Unjoin a computer from an Active Directory Domain. Requires restart. + Unjoin a computer from an Active Directory Domain. Requires a restart. Args: 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. + 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``. password (str): - Password of the specified user + The password of the specified user domain (str): - The domain from which to unjoin the computer. Can be None + The domain from which to unjoin the computer. Can be ``None`` workgroup (str): The workgroup to join the computer to. Default is ``WORKGROUP`` @@ -716,16 +719,17 @@ def unjoin_domain(username=None, .. versionadded:: 2015.8.2/2015.5.7 disable (bool): - Disable the computer account in Active Directory. True to disable. - Default is False + ``True`` to disable the computer account in Active Directory. + Default is ``False`` restart (bool): - Restart the computer after successful unjoin + ``True`` will restart the computer after successful unjoin. Default + is ``False`` .. versionadded:: 2015.8.2/2015.5.7 Returns: - dict: Returns a dictionary if successful, otherwise False + dict: Returns a dictionary if successful, otherwise ``False`` CLI Example: @@ -813,7 +817,7 @@ def get_domain_workgroup(): def _try_parse_datetime(time_str, fmts): ''' - Attempts to parse the input time_str as a date. + A helper function that attempts to parse the input time_str as a date. Args: @@ -874,7 +878,7 @@ def set_system_time(newtime): - HH:MM (24 hour) Returns: - bool: Returns True if successful, otherwise False. + bool: ``True`` if successful, otherwise ``False`` CLI Example: @@ -916,7 +920,7 @@ def set_system_date_time(years=None, seconds (int): Seconds digit: 0 - 59 Returns: - bool: True if successful, otherwise False. + bool: ``True`` if successful, otherwise ``False`` CLI Example: @@ -982,7 +986,7 @@ def get_system_date(): Get the Windows system date Returns: - str: Returns the system date. + str: Returns the system date CLI Example: @@ -1009,7 +1013,7 @@ def set_system_date(newdate): - YYYY/MM/DD Returns: - bool: True if successful, otherwise False + bool: ``True`` if successful, otherwise ``False`` CLI Example: @@ -1035,7 +1039,7 @@ def start_time_service(): Start the Windows time service Returns: - bool: True if successful, otherwise False + bool: ``True`` if successful, otherwise ``False`` CLI Example: @@ -1051,7 +1055,7 @@ def stop_time_service(): Stop the Windows time service Returns: - bool: True if successful, otherwise False + bool: ``True`` if successful, otherwise ``False`` CLI Example: @@ -1070,8 +1074,8 @@ def get_pending_component_servicing(): .. versionadded:: 2016.11.0 Returns: - bool: True if there are pending Component Based Servicing tasks, - otherwise False + bool: ``True`` if there are pending Component Based Servicing tasks, + otherwise ``False`` CLI Example: @@ -1101,7 +1105,8 @@ def get_pending_domain_join(): .. versionadded:: 2016.11.0 Returns: - bool: True if there is a pending domain join action, otherwise False + bool: ``True`` if there is a pending domain join action, otherwise + ``False`` CLI Example: @@ -1143,7 +1148,8 @@ def get_pending_file_rename(): .. versionadded:: 2016.11.0 Returns: - bool: True if there are pending file rename operations, otherwise False + bool: ``True`` if there are pending file rename operations, otherwise + ``False`` CLI Example: @@ -1178,7 +1184,8 @@ def get_pending_servermanager(): .. versionadded:: 2016.11.0 Returns: - bool: True if there are pending Server Manager tasks, otherwise False + bool: ``True`` if there are pending Server Manager tasks, otherwise + ``False`` CLI Example: @@ -1215,7 +1222,7 @@ def get_pending_update(): .. versionadded:: 2016.11.0 Returns: - bool: True if there are pending updates, otherwise False + bool: ``True`` if there are pending updates, otherwise ``False`` CLI Example: @@ -1255,14 +1262,14 @@ def set_reboot_required_witnessed(): 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 this usage can be extended where - appropriate in the future.) + 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:: 2016.11.0 Returns: - bool: True if successful, otherwise False + bool: ``True`` if successful, otherwise ``False`` CLI Example: @@ -1281,17 +1288,18 @@ def set_reboot_required_witnessed(): def 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) + 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. .. versionadded:: 2016.11.0 Returns: - bool: True if the ``Requires reboot`` registry flag is set to ``1``, - otherwise False + bool: ``True`` if the ``Requires reboot`` registry flag is set to ``1``, + otherwise ``False`` CLI Example: @@ -1313,7 +1321,7 @@ def get_pending_reboot(): .. versionadded:: 2016.11.0 Returns: - bool: True if the system is pending reboot, otherwise False + bool: ``True`` if the system is pending reboot, otherwise ``False`` CLI Example: From cc038c5becaed8b93c14e3fa6fcecc2a89bedab5 Mon Sep 17 00:00:00 2001 From: Justin Findlay Date: Thu, 26 Oct 2017 14:24:39 -0700 Subject: [PATCH 3/6] states.cron identifier defaults to name --- salt/states/cron.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/salt/states/cron.py b/salt/states/cron.py index efd1039baf..e285e97790 100644 --- a/salt/states/cron.py +++ b/salt/states/cron.py @@ -299,7 +299,7 @@ def present(name, identifier Custom-defined identifier for tracking the cron line for future crontab - edits. This defaults to the state id + edits. This defaults to the state name special A special keyword to specify periodicity (eg. @reboot, @hourly...). @@ -386,7 +386,7 @@ def absent(name, identifier Custom-defined identifier for tracking the cron line for future crontab - edits. This defaults to the state id + edits. This defaults to the state name special The special keyword used in the job (eg. @reboot, @hourly...). From 5b10918f02f616b4b39ca8ac11b5c5c2813c8d30 Mon Sep 17 00:00:00 2001 From: Rossen Georgiev Date: Sat, 28 Oct 2017 10:54:47 +0100 Subject: [PATCH 4/6] updated CLI docs for salt-ssh --- doc/ref/cli/salt-ssh.rst | 103 +++++++++++++++++++++++++++++++++++---- 1 file changed, 93 insertions(+), 10 deletions(-) diff --git a/doc/ref/cli/salt-ssh.rst b/doc/ref/cli/salt-ssh.rst index 457f8fa658..c578ed82a7 100644 --- a/doc/ref/cli/salt-ssh.rst +++ b/doc/ref/cli/salt-ssh.rst @@ -19,14 +19,18 @@ Salt SSH allows for salt routines to be executed using only SSH for transport Options ======= +.. program:: salt + +.. include:: _includes/common-options.rst + +.. option:: --hard-crash + + Raise any original exception rather than exiting gracefully. Default: False. + .. option:: -r, --raw, --raw-shell Execute a raw shell command. -.. option:: --priv - - Specify the SSH private key file to be used for authentication. - .. option:: --roster Define which roster system to use, this defines if a database backend, @@ -53,38 +57,117 @@ Options the more running process the faster communication should be, default is 25. +.. option:: --extra-filerefs=EXTRA_FILEREFS + + Pass in extra files to include in the state tarball. + +.. option:: --min-extra-modules=MIN_EXTRA_MODS + + One or comma-separated list of extra Python modulesto be included + into Minimal Salt. + +.. option:: --thin-extra-modules=THIN_EXTRA_MODS + + One or comma-separated list of extra Python modulesto be included + into Thin Salt. + +.. option:: -v, --verbose + + Turn on command verbosity, display jid. + +.. option:: -s, --static + + Return the data from minions as a group after they all + +.. option:: -w, --wipe + + Remove the deployment of the salt files when done executing. + +.. option:: -W, --rand-thin-dir + + Select a random temp dir to deploy on the remote system. The dir + will be cleaned after the execution. + +.. option:: -t, --regen-thin, --thin + + Trigger a thin tarball regeneration. This is needed if custom + grains/modules/states have been added or updated. + +.. option:: --python2-bin=PYTHON2_BIN + + Path to a python2 binary which has salt installed. + +.. option:: --python3-bin=PYTHON3_BIN + + Path to a python3 binary which has salt installed. + +.. option:: --jid=JID + + Pass a JID to be used instead of generating one. + +Authentication Options +---------------------- + +.. option:: --priv=SSH_PRIV + + Specify the SSH private key file to be used for authentication. + .. option:: -i, --ignore-host-keys - Disables StrictHostKeyChecking to relax acceptance of new and unknown - host keys. + By default ssh host keys are honored and connections will ask for + approval. Use this option to disable StrictHostKeyChecking. .. option:: --no-host-keys Fully ignores ssh host keys which by default are honored and connections - would ask for approval. Useful if the host key of a remote server has + would ask for approval. Useful if the host key of a remote server has changed and would still error with --ignore-host-keys. +.. option:: --user=SSH_USER + + Set the default user to attempt to use when authenticating. .. option:: --passwd Set the default password to attempt to use when authenticating. +.. option:: --askpass + + Interactively ask for the SSH password with no echo - avoids password + in process args and stored in history. + .. option:: --key-deploy Set this flag to attempt to deploy the authorized ssh key with all minions. This combined with --passwd can make initial deployment of keys very fast and easy. -.. program:: salt +.. option:: --identities-only -.. include:: _includes/common-options.rst + Use the only authentication identity files configured in the ssh_config + files. See IdentitiesOnly flag in man ssh_config. -.. include:: _includes/target-selection-ssh.rst +.. option:: --sudo + + Run command via sudo. + +Scan Roster Options +------------------- + +.. option:: --scan-ports=SSH_SCAN_PORTS + + Comma-separated list of ports to scan in the scan roster. + +.. option:: --scan-timeout=SSH_SCAN_TIMEOUT + + Scanning socket timeout for the scan roster. .. include:: _includes/logging-options.rst .. |logfile| replace:: /var/log/salt/ssh .. |loglevel| replace:: ``warning`` +.. include:: _includes/target-selection-ssh.rst + .. include:: _includes/output-options.rst From b18f2e5a6d4d34fadd5fccc778562522ac666483 Mon Sep 17 00:00:00 2001 From: Rossen Georgiev Date: Mon, 30 Oct 2017 15:10:11 +0000 Subject: [PATCH 5/6] fix program name and description for --static --- doc/ref/cli/salt-ssh.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/ref/cli/salt-ssh.rst b/doc/ref/cli/salt-ssh.rst index c578ed82a7..1ecbaaad76 100644 --- a/doc/ref/cli/salt-ssh.rst +++ b/doc/ref/cli/salt-ssh.rst @@ -19,7 +19,7 @@ Salt SSH allows for salt routines to be executed using only SSH for transport Options ======= -.. program:: salt +.. program:: salt-ssh .. include:: _includes/common-options.rst @@ -77,7 +77,7 @@ Options .. option:: -s, --static - Return the data from minions as a group after they all + Return the data from minions as a group after they all return. .. option:: -w, --wipe From b65f4ea4ea156e21107116baf9d855932a773e54 Mon Sep 17 00:00:00 2001 From: Daniel Wallace Date: Thu, 2 Nov 2017 10:29:45 -0600 Subject: [PATCH 6/6] switch salt-jenkins over to saltstack --- .kitchen.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.kitchen.yml b/.kitchen.yml index 0c8076e22d..cdcb2ba876 100644 --- a/.kitchen.yml +++ b/.kitchen.yml @@ -31,7 +31,7 @@ provisioner: log_level: info require_chef: false remote_states: - name: git://github.com/gtmanfred/salt-jenkins.git + name: git://github.com/saltstack/salt-jenkins.git branch: 2016.11 repo: git testingdir: /testing