.. Document meta

:orphan:

.. |antsibull-internal-nbsp| unicode:: 0xA0
    :trim:

.. meta::
  :antsibull-docs: 2.21.0

.. Anchors

.. _ansible_collections.amnesh.soodar.libssh_connection:

.. Anchors: short name for ansible.builtin

.. Title

amnesh.soodar.libssh connection -- Run tasks using libssh for ssh connection
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

.. Collection note

.. note::
    This connection plugin is part of the `amnesh.soodar collection <https://soodar.ir>`_ (version 1.0.0).

    It is not included in ``ansible-core``.
    To check whether it is installed, run :code:`ansible-galaxy collection list`.

    To install it, use: :code:`ansible\-galaxy collection install https://soodar.ir/ansible/amnesh.soodar.tar.gz`.

    To use it in a playbook, specify: :code:`amnesh.soodar.libssh`.

.. version_added

.. rst-class:: ansible-version-added

New in amnesh.soodar 1.1.0

.. contents::
   :local:
   :depth: 1

.. Deprecated


Synopsis
--------

.. Description

- Use the ansible\-pylibssh python bindings to connect to targets
- The python bindings use libssh C library (https://www.libssh.org/) to connect to targets
- This plugin borrows a lot of settings from the ssh plugin as they both cover the same protocol.


.. Aliases


.. Requirements






.. Options

Parameters
----------

.. tabularcolumns:: \X{1}{3}\X{2}{3}

.. list-table::
  :width: 100%
  :widths: auto
  :header-rows: 1
  :class: longtable ansible-option-table

  * - Parameter
    - Comments

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-config_file"></div>

      .. _ansible_collections.amnesh.soodar.libssh_connection__parameter-config_file:

      .. rst-class:: ansible-option-title

      **config_file**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-config_file" title="Permalink to this option"></a>

      .. ansible-option-type-line::

        :ansible-option-type:`path`

      :ansible-option-versionadded:`added in amnesh.soodar 5.1.0`





      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Alternate SSH config file location


      .. rst-class:: ansible-option-line

      :ansible-option-configuration:`Configuration:`

      - INI entry:

        .. code-block:: ini

          [libssh_connection]
          config_file = VALUE


      - Environment variable: :envvar:`ANSIBLE\_LIBSSH\_CONFIG\_FILE`

      - Variable: ansible\_libssh\_config\_file


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-host_key_auto_add"></div>

      .. _ansible_collections.amnesh.soodar.libssh_connection__parameter-host_key_auto_add:

      .. rst-class:: ansible-option-title

      **host_key_auto_add**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-host_key_auto_add" title="Permalink to this option"></a>

      .. ansible-option-type-line::

        :ansible-option-type:`boolean`




      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      TODO: write it


      .. rst-class:: ansible-option-line

      :ansible-option-choices:`Choices:`

      - :ansible-option-choices-entry:`false`
      - :ansible-option-choices-entry:`true`


      .. rst-class:: ansible-option-line

      :ansible-option-configuration:`Configuration:`

      - INI entry:

        .. code-block:: ini

          [libssh_connection]
          host_key_auto_add = VALUE


      - Environment variable: :envvar:`ANSIBLE\_LIBSSH\_HOST\_KEY\_AUTO\_ADD`


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-host_key_checking"></div>

      .. _ansible_collections.amnesh.soodar.libssh_connection__parameter-host_key_checking:

      .. rst-class:: ansible-option-title

      **host_key_checking**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-host_key_checking" title="Permalink to this option"></a>

      .. ansible-option-type-line::

        :ansible-option-type:`boolean`




      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Set this to "False" if you want to avoid host key checking by the underlying tools Ansible uses to connect to the host


      .. rst-class:: ansible-option-line

      :ansible-option-choices:`Choices:`

      - :ansible-option-choices-entry:`false`
      - :ansible-option-choices-entry-default:`true` :ansible-option-choices-default-mark:`← (default)`


      .. rst-class:: ansible-option-line

      :ansible-option-configuration:`Configuration:`

      - INI entries:

        .. code-block:: ini

          [defaults]
          host_key_checking = true



        .. code-block:: ini

          [libssh_connection]
          host_key_checking = true


      - Environment variable: :envvar:`ANSIBLE\_HOST\_KEY\_CHECKING`

      - Environment variable: :envvar:`ANSIBLE\_SSH\_HOST\_KEY\_CHECKING`

      - Environment variable: :envvar:`ANSIBLE\_LIBSSH\_HOST\_KEY\_CHECKING`

      - Variable: ansible\_host\_key\_checking

      - Variable: ansible\_ssh\_host\_key\_checking

      - Variable: ansible\_libssh\_host\_key\_checking


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-look_for_keys"></div>

      .. _ansible_collections.amnesh.soodar.libssh_connection__parameter-look_for_keys:

      .. rst-class:: ansible-option-title

      **look_for_keys**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-look_for_keys" title="Permalink to this option"></a>

      .. ansible-option-type-line::

        :ansible-option-type:`boolean`




      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      TODO: write it


      .. rst-class:: ansible-option-line

      :ansible-option-choices:`Choices:`

      - :ansible-option-choices-entry:`false`
      - :ansible-option-choices-entry-default:`true` :ansible-option-choices-default-mark:`← (default)`


      .. rst-class:: ansible-option-line

      :ansible-option-configuration:`Configuration:`

      - INI entry:

        .. code-block:: ini

          [libssh_connection]
          look_for_keys = true


      - Environment variable: :envvar:`ANSIBLE\_LIBSSH\_LOOK\_FOR\_KEYS`


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-password"></div>

      .. _ansible_collections.amnesh.soodar.libssh_connection__parameter-password:

      .. rst-class:: ansible-option-title

      **password**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-password" title="Permalink to this option"></a>

      .. ansible-option-type-line::

        :ansible-option-type:`string`




      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Secret used to either login the ssh server or as a passphrase for ssh keys that require it

      Can be set from the CLI via the :literal:`\-\-ask\-pass` option.


      .. rst-class:: ansible-option-line

      :ansible-option-configuration:`Configuration:`

      - Variable: ansible\_password

      - Variable: ansible\_ssh\_pass

      - Variable: ansible\_ssh\_password

      - Variable: ansible\_libssh\_pass

      - Variable: ansible\_libssh\_password


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-password_prompt"></div>

      .. _ansible_collections.amnesh.soodar.libssh_connection__parameter-password_prompt:

      .. rst-class:: ansible-option-title

      **password_prompt**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-password_prompt" title="Permalink to this option"></a>

      .. ansible-option-type-line::

        :ansible-option-type:`string`

      :ansible-option-versionadded:`added in amnesh.soodar 3.1.0`





      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Text to match when using keyboard\-interactive authentication to determine if the prompt is for the password.

      Requires ansible\-pylibssh version \>= 1.0.0


      .. rst-class:: ansible-option-line

      :ansible-option-configuration:`Configuration:`

      - Variable: ansible\_libssh\_password\_prompt


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-proxy_command"></div>

      .. _ansible_collections.amnesh.soodar.libssh_connection__parameter-proxy_command:

      .. rst-class:: ansible-option-title

      **proxy_command**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-proxy_command" title="Permalink to this option"></a>

      .. ansible-option-type-line::

        :ansible-option-type:`string`




      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Proxy information for running the connection via a jumphost.

      Also this plugin will scan 'ssh\_args', 'ssh\_extra\_args' and 'ssh\_common\_args' from the 'ssh' plugin settings for proxy information if set.


      .. rst-class:: ansible-option-line

      :ansible-option-default-bold:`Default:` :ansible-option-default:`""`

      .. rst-class:: ansible-option-line

      :ansible-option-configuration:`Configuration:`

      - INI entry:

        .. code-block:: ini

          [libssh_connection]
          proxy_command = ""


      - Environment variable: :envvar:`ANSIBLE\_LIBSSH\_PROXY\_COMMAND`

      - Variable: ansible\_paramiko\_proxy\_command

      - Variable: ansible\_libssh\_proxy\_command


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-pty"></div>

      .. _ansible_collections.amnesh.soodar.libssh_connection__parameter-pty:

      .. rst-class:: ansible-option-title

      **pty**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-pty" title="Permalink to this option"></a>

      .. ansible-option-type-line::

        :ansible-option-type:`boolean`




      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      TODO: write it


      .. rst-class:: ansible-option-line

      :ansible-option-choices:`Choices:`

      - :ansible-option-choices-entry:`false`
      - :ansible-option-choices-entry-default:`true` :ansible-option-choices-default-mark:`← (default)`


      .. rst-class:: ansible-option-line

      :ansible-option-configuration:`Configuration:`

      - INI entry:

        .. code-block:: ini

          [libssh_connection]
          pty = true


      - Environment variable: :envvar:`ANSIBLE\_LIBSSH\_PTY`


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-remote_addr"></div>

      .. _ansible_collections.amnesh.soodar.libssh_connection__parameter-remote_addr:

      .. rst-class:: ansible-option-title

      **remote_addr**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-remote_addr" title="Permalink to this option"></a>

      .. ansible-option-type-line::

        :ansible-option-type:`string`




      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Address of the remote target


      .. rst-class:: ansible-option-line

      :ansible-option-default-bold:`Default:` :ansible-option-default:`"inventory\_hostname"`

      .. rst-class:: ansible-option-line

      :ansible-option-configuration:`Configuration:`

      - Variable: inventory\_hostname

      - Variable: ansible\_host

      - Variable: ansible\_ssh\_host

      - Variable: ansible\_libssh\_host


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-remote_user"></div>

      .. _ansible_collections.amnesh.soodar.libssh_connection__parameter-remote_user:

      .. rst-class:: ansible-option-title

      **remote_user**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-remote_user" title="Permalink to this option"></a>

      .. ansible-option-type-line::

        :ansible-option-type:`string`




      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      User to login/authenticate as

      Can be set from the CLI via the :literal:`\-\-user` or :literal:`\-u` options.


      .. rst-class:: ansible-option-line

      :ansible-option-configuration:`Configuration:`

      - INI entries:

        .. code-block:: ini

          [defaults]
          remote_user = VALUE



        .. code-block:: ini

          [libssh_connection]
          remote_user = VALUE


      - Environment variable: :envvar:`ANSIBLE\_REMOTE\_USER`

      - Environment variable: :envvar:`ANSIBLE\_LIBSSH\_REMOTE\_USER`

      - Variable: ansible\_user

      - Variable: ansible\_ssh\_user

      - Variable: ansible\_libssh\_user


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-ssh_args"></div>

      .. _ansible_collections.amnesh.soodar.libssh_connection__parameter-ssh_args:

      .. rst-class:: ansible-option-title

      **ssh_args**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-ssh_args" title="Permalink to this option"></a>

      .. ansible-option-type-line::

        :ansible-option-type:`string`

      :ansible-option-versionadded:`added in amnesh.soodar 3.2.0`





      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Arguments to pass to all ssh CLI tools.

      ProxyCommand is the only supported argument.

      This option is deprecated in favor of :emphasis:`proxy\_command`.


      .. rst-class:: ansible-option-line

      :ansible-option-configuration:`Configuration:`

      - INI entry:

        .. code-block:: ini

          [ssh_connection]
          ssh_args = VALUE


      - Environment variable: :envvar:`ANSIBLE\_SSH\_ARGS`

      - CLI argument: \-\-ssh\-args

      - Variable: ansible\_ssh\_args


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-ssh_common_args"></div>

      .. _ansible_collections.amnesh.soodar.libssh_connection__parameter-ssh_common_args:

      .. rst-class:: ansible-option-title

      **ssh_common_args**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-ssh_common_args" title="Permalink to this option"></a>

      .. ansible-option-type-line::

        :ansible-option-type:`string`

      :ansible-option-versionadded:`added in amnesh.soodar 3.2.0`





      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Common extra arguments for all ssh CLI tools.

      ProxyCommand is the only supported argument.

      This option is deprecated in favor of :emphasis:`proxy\_command`.


      .. rst-class:: ansible-option-line

      :ansible-option-configuration:`Configuration:`

      - INI entry:

        .. code-block:: ini

          [ssh_connection]
          ssh_common_args = VALUE


      - Environment variable: :envvar:`ANSIBLE\_SSH\_COMMON\_ARGS`

      - CLI argument: \-\-ssh\-common\-args

      - Variable: ansible\_ssh\_common\_args


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-ssh_extra_args"></div>

      .. _ansible_collections.amnesh.soodar.libssh_connection__parameter-ssh_extra_args:

      .. rst-class:: ansible-option-title

      **ssh_extra_args**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-ssh_extra_args" title="Permalink to this option"></a>

      .. ansible-option-type-line::

        :ansible-option-type:`string`

      :ansible-option-versionadded:`added in amnesh.soodar 3.2.0`





      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Extra arguments exclusive to the 'ssh' CLI tool.

      ProxyCommand is the only supported argument.

      This option is deprecated in favor of :emphasis:`proxy\_command`.


      .. rst-class:: ansible-option-line

      :ansible-option-configuration:`Configuration:`

      - INI entry:

        .. code-block:: ini

          [ssh_connection]
          ssh_extra_args = VALUE


      - Environment variable: :envvar:`ANSIBLE\_SSH\_EXTRA\_ARGS`

      - CLI argument: \-\-ssh\-extra\-args

      - Variable: ansible\_ssh\_extra\_args


      .. raw:: html

        </div>

  * - .. raw:: html

        <div class="ansible-option-cell">
        <div class="ansibleOptionAnchor" id="parameter-use_persistent_connections"></div>

      .. _ansible_collections.amnesh.soodar.libssh_connection__parameter-use_persistent_connections:

      .. rst-class:: ansible-option-title

      **use_persistent_connections**

      .. raw:: html

        <a class="ansibleOptionLink" href="#parameter-use_persistent_connections" title="Permalink to this option"></a>

      .. ansible-option-type-line::

        :ansible-option-type:`boolean`




      .. raw:: html

        </div>

    - .. raw:: html

        <div class="ansible-option-cell">

      Toggles the use of persistence for connections


      .. rst-class:: ansible-option-line

      :ansible-option-choices:`Choices:`

      - :ansible-option-choices-entry-default:`false` :ansible-option-choices-default-mark:`← (default)`
      - :ansible-option-choices-entry:`true`


      .. rst-class:: ansible-option-line

      :ansible-option-configuration:`Configuration:`

      - INI entry:

        .. code-block:: ini

          [defaults]
          use_persistent_connections = false


      - Environment variable: :envvar:`ANSIBLE\_USE\_PERSISTENT\_CONNECTIONS`


      .. raw:: html

        </div>


.. note::

    Configuration entries listed above for each entry type (Ansible variable, environment variable, and so on) have a low to high priority order.
    For example, a variable that is lower in the list will override a variable that is higher up.
    The entry types are also ordered by precedence from low to high priority order.
    For example, an ansible.cfg entry (further up in the list) is overwritten by an Ansible variable (further down in the list).

.. Attributes


.. Notes


.. Seealso


.. Examples



.. Facts


.. Return values


..  Status (Presently only deprecated)


.. Authors

Authors
~~~~~~~

- Ansible Networking Team (@ansible-network)


.. Extra links

Collection links
~~~~~~~~~~~~~~~~

.. ansible-links::

  - title: "Issue Tracker"
    url: "http://soodar.ir/issue/tracker"
    external: true
  - title: "Homepage"
    url: "http://soodar.ir"
    external: true
  - title: "Repository (Sources)"
    url: "https://192.168.222.222/amnesh/soodar/soosible"
    external: true


.. Parsing errors