Add attribute to accept passphrase, when using a private key file. (#722)

* add attribute to accept passphrase

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* add updates pre-commit

* fix test

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: KB-perByte

.pre-commit-config.yaml

@@ -6,7 +6,7 @@ repos:
       - id: update-docs
 
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v5.0.0
+    rev: v6.0.0
     hooks:
       - id: check-merge-conflict
       - id: debug-statements
@@ -15,25 +15,25 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/pycontribs/mirrors-prettier
-    rev: "v3.3.3"
+    rev: "v3.6.2"
     hooks:
       - id: prettier
         additional_dependencies:
           - prettier
           - prettier-plugin-toml
 
   - repo: https://github.com/PyCQA/isort
-    rev: 5.13.2
+    rev: 6.0.1
     hooks:
       - id: isort
         args: ["--filter-files"]
 
   - repo: https://github.com/psf/black
-    rev: 24.10.0
+    rev: 25.1.0
     hooks:
       - id: black
 
   - repo: https://github.com/pycqa/flake8
-    rev: 7.1.1
+    rev: 7.3.0
     hooks:
       - id: flake8

changelogs/fragments/fix_721_private_key.yml

@@ -0,0 +1,3 @@
+bugfixes:
+  - "Added support for private key passphrase in libssh connection plugin, when using encrypted private keys specified by the C(ansible_private_key_file) attribute."
+  - "Set libssh logging level to DEBUG when Ansible verbosity is greater than 3, to aid in troubleshooting connection issues."

docs/ansible.netcommon.libssh_connection.rst

@@ -196,6 +196,26 @@ Parameters
                         <div>Requires ansible-pylibssh version &gt;= 1.0.0</div>
                 </td>
             </tr>
+            <tr>
+                <td colspan="1">
+                    <div class="ansibleOptionAnchor" id="parameter-"></div>
+                    <b>private_key_passphrase</b>
+                    <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a>
+                    <div style="font-size: small">
+                        <span style="color: purple">string</span>
+                    </div>
+                </td>
+                <td>
+                </td>
+                    <td>
+                                <div>var: ansible_private_key_password</div>
+                                <div>var: ansible_private_key_passphrase</div>
+                    </td>
+                <td>
+                        <div>Passphrase used to unlock the private key specified by the <code>ansible_private_key_file</code> attribute.</div>
+                        <div>This is required if the private key is encrypted with a passphrase.</div>
+                </td>
+            </tr>
             <tr>
                 <td colspan="1">
                     <div class="ansibleOptionAnchor" id="parameter-"></div>

plugins/connection/libssh.py

@@ -65,6 +65,14 @@
         vars:
           - name: ansible_libssh_password_prompt
         version_added: 3.1.0
+      private_key_passphrase:
+        description:
+          - Passphrase used to unlock the private key specified by the C(ansible_private_key_file) attribute.
+          - This is required if the private key is encrypted with a passphrase.
+        type: string
+        vars:
+            - name: ansible_private_key_password
+            - name: ansible_private_key_passphrase
       host_key_auto_add:
         description: 'TODO: write it'
         env: [{name: ANSIBLE_LIBSSH_HOST_KEY_AUTO_ADD}]
@@ -389,7 +397,7 @@ def _connect_uncached(self):
         self.ssh = Session()
 
         if display.verbosity > 3:
-            self.ssh.set_log_level(logging.INFO)
+            self.ssh.set_log_level(logging.DEBUG)
 
         self.keyfile = os.path.expanduser("~/.ssh/known_hosts")
 
@@ -432,6 +440,7 @@ def _connect_uncached(self):
                 password=self.get_option("password"),
                 password_prompt=self.get_option("password_prompt"),
                 private_key=private_key,
+                private_key_password=self.get_option("private_key_passphrase"),
                 timeout=self._play_context.timeout,
                 port=port,
                 **ssh_connect_kwargs,

plugins/module_utils/cli_parser/cli_parsertemplate.py

@@ -9,7 +9,7 @@
 # Simplified BSD License (see LICENSES/BSD-2-Clause.txt or https://opensource.org/licenses/BSD-2-Clause)
 # SPDX-License-Identifier: BSD-2-Clause
 
-""" A shim class for the NetworkTemplate
+"""A shim class for the NetworkTemplate
 this was done in case there is a need to
 modify the resource module parser class
 or extend it a split it from the cli parsers.

plugins/sub_plugins/cli_parser/pyats_parser.py

@@ -137,5 +137,5 @@ def parse(self, *_args, **_kwargs):
             parsed = device.parse(command, output=cli_output)
         except Exception as exc:
             msg = "The pyats library return an error for '{cmd}' for '{os}'. Error: {err}."
-            return {"errors": [(msg.format(cmd=command, os=network_os, err=to_native(exc)))]}
+            return {"errors": [msg.format(cmd=command, os=network_os, err=to_native(exc))]}
         return {"parsed": parsed}

tests/unit/plugins/connection/test_libssh.py

@@ -58,6 +58,7 @@ def test_libssh_connect(conn, monkeypatch):
         look_for_keys=True,
         password="test",
         password_prompt=None,
+        private_key_password=None,
         port=8080,
         timeout=60,
         user="user1",