SCP filename validation docs (#55399) (#55489)

* SCP filename validation docs

* Update docs/docsite/rst/reference_appendices/faq.rst

Co-Authored-By: jborean93 <jborean93@gmail.com>

* Update docs/docsite/rst/reference_appendices/faq.rst

Co-Authored-By: jborean93 <jborean93@gmail.com>

* Update docs/docsite/rst/reference_appendices/faq.rst

Co-Authored-By: jborean93 <jborean93@gmail.com>

* edits to scp FAQ entry

* zeut alors I have missed one

* incorporate jborean feedback

* adds link to bug report

(cherry picked from commit 8542f16fa9)

docs/docsite/rst/reference_appendices/faq.rst

@@ -231,11 +231,11 @@ There are a few common errors that one might run into when trying to execute Ans
 
   To get around this limitation, download and install a later version of `python for z/OS <https://www.rocketsoftware.com/zos-open-source>`_ (2.7.13 or 3.6.1) that represents strings internally as ASCII.  Version 2.7.13 is verified to work.
 
-* When ``pipelining = False`` in `/etc/ansible/ansible.cfg` then Ansible modules are transferred in binary mode via sftp however execution of python fails with 
+* When ``pipelining = False`` in `/etc/ansible/ansible.cfg` then Ansible modules are transferred in binary mode via sftp however execution of python fails with
 
   .. error::
       SyntaxError: Non-UTF-8 code starting with \'\\x83\' in file /a/user1/.ansible/tmp/ansible-tmp-1548232945.35-274513842609025/AnsiballZ_stat.py on line 1, but no encoding declared; see http://python.org/dev/peps/pep-0263/ for details
-  
+
   To fix it set ``pipelining = True`` in `/etc/ansible/ansible.cfg`.
 
 * Python interpret cannot be found in default location ``/usr/bin/python`` on target host.
@@ -643,6 +643,32 @@ but you can still access the original via ``hostvars``::
 This works for all overriden connection variables, like ``ansible_user``, ``ansible_port``, etc.
 
 
+.. _scp_protocol_error_filename:
+
+How do I fix 'protocol error: filename does not match request' when fetching a file?
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Newer releases of OpenSSH have a `bug <https://bugzilla.mindrot.org/show_bug.cgi?id=2966>`_ in the SCP client that can trigger this error on the Ansible controller when using SCP as the file transfer mechanism::
+
+    failed to transfer file to /tmp/ansible/file.txt\r\nprotocol error: filename does not match request
+
+In these releases, SCP tries to validate that the path of the file to fetch matches the requested path.
+The validation
+fails if the remote filename requires quotes to escape spaces or non-ascii characters in its path. To avoid this error:
+
+* Use SFTP instead of SCP by setting ``scp_if_ssh`` to ``smart`` (which tries SFTP first) or to ``False``. You can do this in one of four ways:
+    * Rely on the default setting, which is ``smart`` - this works if ``scp_if_ssh`` is not explicitly set anywhere
+    * Set a :ref:`host variable <host_variables>` or :ref:`group variable <group_variables>` in inventory: ``ansible_scp_if_ssh: False``
+    * Set an environment variable on your control node: ``export ANSIBLE_SCP_IF_SSH=False``
+    * Pass an environment variable when you run Ansible: ``ANSIBLE_SCP_IF_SSH=smart ansible-playbook``
+    * Modify your ``ansible.cfg`` file: add ``scp_if_ssh=False`` to the ``[ssh_connection]`` section
+* If you must use SCP, set the ``-T`` arg to tell the SCP client to ignore path validation. You can do this in one of three ways:
+    * Set a :ref:`host variable <host_variables>` or :ref:`group variable <group_variables>`: ``ansible_scp_extra_args=-T``,
+    * Export or pass an environment variable: ``ANSIBLE_SCP_EXTRA_ARGS=-T``
+    * Modify your ``ansible.cfg`` file: add ``scp_extra_args=-T`` to the ``[ssh_connection]`` section
+
+.. note:: If you see an ``invalid argument`` error when using ``-T``, then your SCP client is not performing filename validation and will not trigger this error.
+
 .. _i_dont_see_my_question:
 
 I don't see my question here