Merge branch 'develop' into develop

Bryce Larson · web-flow · commit e036ac225fb0 · 2019-08-15T22:18:16.000-06:00
diff --git a/salt/modules/slsutil.py b/salt/modules/slsutil.py
@@ -279,13 +279,11 @@ def banner(width=72, commentchar='#', borderchar='#', blockstart=None, blockend=
     :param newline: Boolean value to indicate whether the comment block should
         end with a newline. Default is ``False``.
 
-    This banner can be injected into any templated file, for example:
+    **Example 1 - the default banner:**
 
     .. code-block:: jinja
 
-        {{ salt['slsutil.banner'](width=120, commentchar='//') }}
-
-    The default banner:
+        {{ salt['slsutil.banner']() }}
 
     .. code-block:: none
 
@@ -296,6 +294,42 @@ def banner(width=72, commentchar='#', borderchar='#', blockstart=None, blockend=
         # The contents of this file are managed by Salt. Any changes to this   #
         # file may be overwritten automatically and without warning.           #
         ########################################################################
+
+    **Example 2 - a Javadoc-style banner:**
+
+    .. code-block:: jinja
+
+        {{ salt['slsutil.banner'](commentchar=' *', borderchar='*', blockstart='/**', blockend=' */') }}
+
+    .. code-block:: none
+
+        /**
+         ***********************************************************************
+         *                                                                     *
+         *              THIS FILE IS MANAGED BY SALT - DO NOT EDIT             *
+         *                                                                     *
+         * The contents of this file are managed by Salt. Any changes to this  *
+         * file may be overwritten automatically and without warning.          *
+         ***********************************************************************
+         */
+
+    **Example 3 - custom text:**
+
+    .. code-block:: jinja
+
+        {{ set copyright='This file may not be copied or distributed without permission of SaltStack, Inc.' }}
+        {{ salt['slsutil.banner'](title='Copyright 2019 SaltStack, Inc.', text=copyright, width=60) }}
+
+    .. code-block:: none
+
+        ############################################################
+        #                                                          #
+        #              Copyright 2019 SaltStack, Inc.              #
+        #                                                          #
+        # This file may not be copied or distributed without       #
+        # permission of SaltStack, Inc.                            #
+        ############################################################
+
     '''
 
     if title is None:
@@ -304,18 +338,26 @@ def banner(width=72, commentchar='#', borderchar='#', blockstart=None, blockend=
     if text is None:
         text = ('The contents of this file are managed by Salt. '
                 'Any changes to this file may be overwritten '
-                'automatically and without warning')
+                'automatically and without warning.')
 
     # Set up some typesetting variables
-    lgutter = commentchar.strip() + ' '
-    rgutter = ' ' + commentchar.strip()
+    ledge = commentchar.rstrip()
+    redge = commentchar.strip()
+    lgutter = ledge + ' '
+    rgutter = ' ' + redge
     textwidth = width - len(lgutter) - len(rgutter)
-    border_line = commentchar + borderchar[:1] * (width - len(commentchar) * 2) + commentchar
+
+    # Check the width
+    if textwidth <= 0:
+        raise salt.exceptions.ArgumentValueError('Width is too small to render banner')
+
+    # Define the static elements
+    border_line = commentchar + borderchar[:1] * (width - len(ledge) - len(redge)) + redge
     spacer_line = commentchar + ' ' * (width - len(commentchar) * 2) + commentchar
-    wrapper = textwrap.TextWrapper(width=(width - len(lgutter) - len(rgutter)))
-    block = list()
 
     # Create the banner
+    wrapper = textwrap.TextWrapper(width=textwidth)
+    block = list()
     if blockstart is not None:
         block.append(blockstart)
     block.append(border_line)
diff --git a/salt/modules/x509.py b/salt/modules/x509.py
@@ -590,7 +590,7 @@ def read_certificate(certificate):
 
 def read_certificates(glob_path):
     '''
-    Returns a dict containing details of a all certificates matching a glob
+    Returns a dict containing details of all certificates matching a glob
 
     glob_path:
         A path to certificates to be read and returned.
@@ -651,8 +651,8 @@ def read_crl(crl):
 
     :depends:   - OpenSSL command line tool
 
-    csl:
-        A path or PEM encoded string containing the CSL to read.
+    crl:
+        A path or PEM encoded string containing the CRL to read.
 
     CLI Example:
 
@@ -747,17 +747,17 @@ def write_pem(text, path, overwrite=True, pem_type=None):
         PEM string input to be written out.
 
     path:
-        Path of the file to write the pem out to.
+        Path of the file to write the PEM out to.
 
     overwrite:
-        If True(default), write_pem will overwrite the entire pem file.
+        If ``True`` (default), write_pem will overwrite the entire PEM file.
         Set False to preserve existing private keys and dh params that may
-        exist in the pem file.
+        exist in the PEM file.
 
     pem_type:
         The PEM type to be saved, for example ``CERTIFICATE`` or
         ``PUBLIC KEY``. Adding this will allow the function to take
-        input that may contain multiple pem types.
+        input that may contain multiple PEM types.
 
     CLI Example:
 
@@ -871,22 +871,22 @@ def create_crl(  # pylint: disable=too-many-arguments,too-many-locals
     :depends:   - PyOpenSSL Python module
 
     path:
-        Path to write the crl to.
+        Path to write the CRL to.
 
     text:
         If ``True``, return the PEM text without writing to a file.
         Default ``False``.
 
     signing_private_key:
         A path or string of the private key in PEM format that will be used
-        to sign this crl. This is required.
+        to sign the CRL. This is required.
 
     signing_private_key_passphrase:
         Passphrase to decrypt the private key.
 
     signing_cert:
         A certificate matching the private key that will be used to sign
-        this crl. This is required.
+        the CRL. This is required.
 
     revoked:
         A list of dicts containing all the certificates to revoke. Each dict
@@ -1119,9 +1119,9 @@ def create_certificate(
         Default ``False``.
 
     overwrite:
-        If True(default), create_certificate will overwrite the entire pem
+        If ``True`` (default), create_certificate will overwrite the entire PEM
         file. Set False to preserve existing private keys and dh params that
-        may exist in the pem file.
+        may exist in the PEM file.
 
     kwargs:
         Any of the properties below can be included as additional
@@ -1131,7 +1131,7 @@ def create_certificate(
         Request a remotely signed certificate from ca_server. For this to
         work, a ``signing_policy`` must be specified, and that same policy
         must be configured on the ca_server (name or list of ca server). See ``signing_policy`` for
-        details. Also the salt master must permit peers to call the
+        details. Also, the salt master must permit peers to call the
         ``sign_remote_certificate`` function.
 
         Example:
@@ -1192,7 +1192,7 @@ def create_certificate(
 
     public_key:
         The public key to be included in this certificate. This can be sourced
-        from a public key, certificate, csr or private key. If a private key
+        from a public key, certificate, CSR or private key. If a private key
         is used, the matching public key from the private key will be
         generated before any processing is done. This means you can request a
         certificate from a remote CA using a private key file as your
@@ -1256,7 +1256,7 @@ def create_certificate(
             X509v3 Subject Alternative Name
 
         crlDistributionPoints:
-            X509v3 CRL distribution points
+            X509v3 CRL Distribution points
 
         issuingDistributionPoint:
             X509v3 Issuing Distribution Point
@@ -1316,7 +1316,7 @@ def create_certificate(
     signing_policy:
         A signing policy that should be used to create this certificate.
         Signing policies should be defined in the minion configuration, or in
-        a minion pillar. It should be a yaml formatted list of arguments
+        a minion pillar. It should be a YAML formatted list of arguments
         which will override any arguments passed to this function. If the
         ``minions`` key is included in the signing policy, only minions
         matching that pattern (see match.glob and match.compound) will be
@@ -1717,7 +1717,7 @@ def verify_private_key(private_key, public_key, passphrase=None):
 
     public_key:
         The public key to verify, can be a string or path to a PEM formatted
-        certificate, csr, or another private key.
+        certificate, CSR, or another private key.
 
     passphrase:
         Passphrase to decrypt the private key.
@@ -1743,7 +1743,7 @@ def verify_signature(certificate, signing_pub_key=None,
 
     signing_pub_key:
         The public key to verify, can be a string or path to a PEM formatted
-        certificate, csr, or private key.
+        certificate, CSR, or private key.
 
     signing_pub_key_passphrase:
         Passphrase to the signing_pub_key if it is an encrypted private key.
@@ -1883,7 +1883,7 @@ def will_expire(certificate, days):
             ret['cn'] = _parse_subject(cert.get_subject())['CN']
             ret['will_expire'] = _expiration_date.strftime(ts_pt) <= _check_time.strftime(ts_pt)
         except ValueError as err:
-            log.debug('Unable to return details of a sertificate expiration: %s', err)
+            log.debug('Unable to return details of a certificate expiration: %s', err)
             log.trace(err, exc_info=True)
 
     return ret
diff --git a/salt/states/x509.py b/salt/states/x509.py
@@ -6,7 +6,7 @@
 
 :depends: M2Crypto
 
-This module can enable managing a complete PKI infrastructure including creating private keys, CA's,
+This module can enable managing a complete PKI infrastructure including creating private keys, CAs,
 certificates and CRLs. It includes the ability to generate a private key on a server, and have the
 corresponding public key sent to a remote CA to create a CA signed certificate. This can be done in
 a secure manner, where private keys are always generated locally and never moved across the network.
@@ -117,7 +117,7 @@
 
 
 This state will instruct all minions to trust certificates signed by our new CA.
-Using jinja to strip newlines from the text avoids dealing with newlines in the rendered yaml,
+Using Jinja to strip newlines from the text avoids dealing with newlines in the rendered YAML,
 and the  :mod:`sign_remote_certificate <salt.states.x509.sign_remote_certificate>` state will
 handle properly formatting the text before writing the output.
 
@@ -267,7 +267,7 @@ def private_key_managed(name,
         Cipher for encrypting the private key.
 
     new:
-        Always create a new key. Defaults to False.
+        Always create a new key. Defaults to ``False``.
         Combining new with :mod:`prereq <salt.states.requsities.preqreq>`, or when used as part of a
         `managed_private_key` can allow key rotation whenever a new certificiate is generated.
 
@@ -285,7 +285,7 @@ def private_key_managed(name,
 
     Example:
 
-    The jinja templating in this example ensures a private key is generated if the file doesn't exist
+    The Jinja templating in this example ensures a private key is generated if the file doesn't exist
     and that a new private key is generated whenever the certificate that uses it is to be renewed.
 
     .. code-block:: jinja
@@ -404,7 +404,7 @@ def certificate_managed(name,
         Manages the private key corresponding to the certificate. All of the
         arguments supported by :py:func:`x509.private_key_managed
         <salt.states.x509.private_key_managed>` are supported. If `name` is not
-        speicified or is the same as the name of the certificate, the private
+        specified or is the same as the name of the certificate, the private
         key and certificate will be written together in the same file.
 
     append_certs:
@@ -627,14 +627,14 @@ def crl_managed(name,
         Path to the certificate
 
     signing_private_key
-        The private key that will be used to sign this crl. This is
+        The private key that will be used to sign the CRL. This is
         usually your CA's private key.
 
     signing_private_key_passphrase
         Passphrase to decrypt the private key.
 
     signing_cert
-        The certificate of the authority that will be used to sign this crl.
+        The certificate of the authority that will be used to sign the CRL.
         This is usually your CA's certificate.
 
     revoked
@@ -650,8 +650,8 @@ def crl_managed(name,
         of pyOpenSSL less than 0.14.
 
     days_remaining : 30
-        The crl should be automatically recreated if there are less than
-        ``days_remaining`` days until the crl expires. Set to 0 to disable
+        The CRL should be automatically recreated if there are less than
+        ``days_remaining`` days until the CRL expires. Set to 0 to disable
         automatic renewal.
 
     include_expired : False
diff --git a/tests/unit/modules/test_slsutil.py b/tests/unit/modules/test_slsutil.py
@@ -32,6 +32,7 @@ def test_banner(self):
         self.check_banner(width=20)
         self.check_banner(commentchar='//', borderchar='-')
         self.check_banner(title='title here', text='text here')
+        self.check_banner(commentchar=' *')
 
     def check_banner(self, width=72, commentchar='#', borderchar='#', blockstart=None, blockend=None,
                      title=None, text=None, newline=True):
@@ -42,7 +43,7 @@ def check_banner(self, width=72, commentchar='#', borderchar='#', blockstart=Non
         for line in result:
             self.assertEqual(len(line), width)
             self.assertTrue(line.startswith(commentchar))
-            self.assertTrue(line.endswith(commentchar))
+            self.assertTrue(line.endswith(commentchar.strip()))
 
     def test_boolstr(self):
         '''
