From 2467198346af5c69466b995d657987484c5ded23 Mon Sep 17 00:00:00 2001 From: jeanluc Date: Thu, 16 Nov 2023 03:54:27 +0100 Subject: [PATCH] Try to improve wording --- salt/modules/file.py | 56 ++++++++++++++++++++++------------- salt/states/archive.py | 35 ++++++++++++++++------ salt/states/file.py | 67 +++++++++++++++++++++++++++--------------- 3 files changed, 106 insertions(+), 52 deletions(-) diff --git a/salt/modules/file.py b/salt/modules/file.py index 0c57696d8d18..3a9f0669cbef 100644 --- a/salt/modules/file.py +++ b/salt/modules/file.py @@ -812,10 +812,10 @@ def get_source_sum( .. versionadded:: 3002 source_hash_sig - When ``source_hash`` is a file, ensure a valid GPG signature exists on - the source hash file. - Set this to ``true`` for an inline (clearsigned) signature, or to a file URI - retrievable by :py:func:`cp.cache_file ` + When ``source`` is a remote file source and ``source_hash`` is a file, + ensure a valid GPG signature exists on the source hash file. + Set this to ``true`` for an inline (clearsigned) signature, or to a + file URI retrievable by `:py:func:`cp.cache_file ` for a detached one. .. versionadded:: 3007.0 @@ -4766,11 +4766,12 @@ def get_managed( .. versionadded:: 3005 source_hash_sig - When ``source_hash`` is a file and ``skip_verify`` is not true and ``use_etag`` - is not true, ensure a valid GPG signature exists on the source hash file. - Set this to ``true`` for an inline (clearsigned) signature, or to a file URI - retrievable by ``cp.cache_file`` for a detached one. The cached file - will be deleted if the signature verification fails. + When ``source`` is a remote file source, ``source_hash`` is a file, + ``skip_verify`` is not true and ``use_etag`` is not true, ensure a + valid GPG signature exists on the source hash file. + Set this to ``true`` for an inline (clearsigned) signature, or to a + file URI retrievable by `:py:func:`cp.cache_file ` + for a detached one. .. versionadded:: 3007.0 @@ -6258,24 +6259,39 @@ def manage_file( signature Ensure a valid GPG signature exists on the selected ``source`` file. - Set this to true for inline signatures, or to a file URI retrievable by - ``cp.cache_file`` for a detached one. The cached file will be deleted - if the signature verification fails. + Set this to true for inline signatures, or to a file URI retrievable + by `:py:func:`cp.cache_file ` + for a detached one. .. note:: - This signature will be enforced regardless of source type and will be - required on the final output, therefore this does not lend itself well - when templates are rendered. + A signature is only enforced directly after caching the file, + before it is moved to its final destination. Existing target files + (with the correct checksum) will neither be checked nor deleted. + + It will be enforced regardless of source type and will be + required on the final output, therefore this does not lend itself + well when templates are rendered. + The file will not be modified, meaning inline signatures are not + removed. .. versionadded:: 3007.0 source_hash_sig - When ``source_hash`` is a file and ``skip_verify`` is not true and ``use_etag`` - is not true, ensure a valid GPG signature exists on the source hash file. - Set this to ``true`` for an inline (clearsigned) signature, or to a file URI - retrievable by ``cp.cache_file`` for a detached one. The cached file - will be deleted if the signature verification fails. + When ``source`` is a remote file source, ``source_hash`` is a file, + ``skip_verify`` is not true and ``use_etag`` is not true, ensure a + valid GPG signature exists on the source hash file. + Set this to ``true`` for an inline (clearsigned) signature, or to a + file URI retrievable by `:py:func:`cp.cache_file ` + for a detached one. + + .. note:: + + A signature on the ``source_hash`` file is enforced regardless of + changes since its contents are used to check if an existing file + is in the correct state - but only for remote sources! + As for ``signature``, existing target files will not be modified, + only the cached source_hash and source_hash_sig files will be removed. .. versionadded:: 3007.0 diff --git a/salt/states/archive.py b/salt/states/archive.py index 72ae729b90c2..25ca6549dbf1 100644 --- a/salt/states/archive.py +++ b/salt/states/archive.py @@ -725,32 +725,49 @@ def extracted( signature Ensure a valid GPG signature exists on the selected ``source`` file. - This needs to be a file URI retrievable by ``cp.cache_file`` which + This needs to be a file URI retrievable by + `:py:func:`cp.cache_file ` which identifies a detached signature. - This signature will be enforced regardless of source type. + + .. note:: + + A signature is only enforced directly after caching the file, + before it is extracted to its final destination. Existing files + at the target will never be modified. + + It will be enforced regardless of source type. .. versionadded:: 3007.0 source_hash_sig - When ``source_hash`` is a file and ``skip_verify`` is not true and ``use_etag`` - is not true, ensure a valid GPG signature exists on the source hash file. - Set this to ``true`` for an inline (clearsigned) signature, or to a file URI - retrievable by ``cp.cache_file`` for a detached one. The cached file - will be deleted if the signature verification fails. + When ``source`` is a remote file source, ``source_hash`` is a file, + ``skip_verify`` is not true and ``use_etag`` is not true, ensure a + valid GPG signature exists on the source hash file. + Set this to ``true`` for an inline (clearsigned) signature, or to a + file URI retrievable by `:py:func:`cp.cache_file ` + for a detached one. + + .. note:: + + A signature on the ``source_hash`` file is enforced regardless of + changes since its contents are used to check if an existing file + is in the correct state - but only for remote sources! + As for ``signature``, existing target files will not be modified, + only the cached source_hash and source_hash_sig files will be removed. .. versionadded:: 3007.0 signed_by_any When verifying signatures either on the managed file or its source hash file, require at least one valid signature from one of a list of key fingerprints. - This is passed to ``gpg.verify``. + This is passed to :py:func:`gpg.verify `. .. versionadded:: 3007.0 signed_by_all When verifying signatures either on the managed file or its source hash file, require a valid signature from each of the key fingerprints in this list. - This is passed to ``gpg.verify``. + This is passed to :py:func:`gpg.verify `. .. versionadded:: 3007.0 diff --git a/salt/states/file.py b/salt/states/file.py index 0fcb04565db9..4ab618fffbf1 100644 --- a/salt/states/file.py +++ b/salt/states/file.py @@ -2912,39 +2912,53 @@ def managed( signature Ensure a valid GPG signature exists on the selected ``source`` file. - Set this to true for inline signatures, or to a file URI retrievable by - ``cp.cache_file`` for a detached one. + Set this to true for inline signatures, or to a file URI retrievable + by `:py:func:`cp.cache_file ` + for a detached one. .. note:: - This signature will be enforced regardless of source type and will be - required on the final output, therefore this does not lend itself well - when templates are rendered. + A signature is only enforced directly after caching the file, + before it is moved to its final destination. Existing target files + (with the correct checksum) will neither be checked nor deleted. + + It will be enforced regardless of source type and will be + required on the final output, therefore this does not lend itself + well when templates are rendered. The file will not be modified, meaning inline signatures are not removed. .. versionadded:: 3007.0 source_hash_sig - When ``source_hash`` is a file and ``skip_verify`` is not true and ``use_etag`` - is not true, ensure a valid GPG signature exists on the source hash file. - Set this to ``true`` for an inline (clearsigned) signature, or to a file URI - retrievable by ``cp.cache_file`` for a detached one. The cached file - will be deleted if the signature verification fails. + When ``source`` is a remote file source, ``source_hash`` is a file, + ``skip_verify`` is not true and ``use_etag`` is not true, ensure a + valid GPG signature exists on the source hash file. + Set this to ``true`` for an inline (clearsigned) signature, or to a + file URI retrievable by `:py:func:`cp.cache_file ` + for a detached one. + + .. note:: + + A signature on the ``source_hash`` file is enforced regardless of + changes since its contents are used to check if an existing file + is in the correct state - but only for remote sources! + As for ``signature``, existing target files will not be modified, + only the cached source_hash and source_hash_sig files will be removed. .. versionadded:: 3007.0 signed_by_any When verifying signatures either on the managed file or its source hash file, require at least one valid signature from one of a list of key fingerprints. - This is passed to ``gpg.verify``. + This is passed to :py:func:`gpg.verify `. .. versionadded:: 3007.0 signed_by_all When verifying signatures either on the managed file or its source hash file, require a valid signature from each of the key fingerprints in this list. - This is passed to ``gpg.verify``. + This is passed to :py:func:`gpg.verify `. .. versionadded:: 3007.0 @@ -8968,25 +8982,32 @@ def cached( .. versionadded:: 3005 source_hash_sig - When ``source_hash`` is a file and ``skip_verify`` is not true and ``use_etag`` - is not true, ensure a valid GPG signature exists on the source hash file. - Set this to ``true`` for an inline (clearsigned) signature, or to a file URI - retrievable by ``cp.cache_file`` for a detached one. The cached file - will be deleted if the signature verification fails. + When ``name`` is a remote file source, ``source_hash`` is a file, + ``skip_verify`` is not true and ``use_etag`` is not true, ensure a + valid GPG signature exists on the source hash file. + Set this to ``true`` for an inline (clearsigned) signature, or to a + file URI retrievable by `:py:func:`cp.cache_file ` + for a detached one. + + .. note:: + + A signature on the ``source_hash`` file is enforced regardless of + changes since its contents are used to check if an existing file + is in the correct state - but only for remote sources! .. versionadded:: 3007.0 signed_by_any - When verifying signatures either on the managed file or its source hash file, - require at least one valid signature from one of a list of key fingerprints. - This is passed to ``gpg.verify``. + When verifying ``source_hash_sig``, require at least one valid signature + from one of a list of key fingerprints. This is passed to + :py:func:`gpg.verify `. .. versionadded:: 3007.0 signed_by_all - When verifying signatures either on the managed file or its source hash file, - require a valid signature from each of the key fingerprints in this list. - This is passed to ``gpg.verify``. + When verifying ``source_hash_sig``, require a valid signature from each + of the key fingerprints in this list. This is passed to + :py:func:`gpg.verify `. .. versionadded:: 3007.0