diff --git a/docs/docsite/rst/reference_appendices/faq.rst b/docs/docsite/rst/reference_appendices/faq.rst index 52faeddfa6a..8e03f4c9f5f 100644 --- a/docs/docsite/rst/reference_appendices/faq.rst +++ b/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 `_ (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 `_ 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 ` or :ref:`group variable ` 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 ` or :ref:`group variable `: ``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