Fix for running cli commands through ansible using ssh connection.

Signed-off-by: Shiva Shankar Vaddepally <[email protected]>

Author: Shiva Shankar Vaddepally

README.md

@@ -132,9 +132,122 @@ Refer to the [NetScaler ADM as an API proxy server](https://docs.netscaler.com/e
 Refer to the [sample_playboook](https://github.com/netscaler/ansible-collection-netscaleradc/tree/main/examples) and [playbook_anatomy.md](https://github.com/netscaler/ansible-collection-netscaleradc/blob/main/playbook_anatomy.md). 
 
 
-### SSH_connections 
+### SSH Connection Plugin
 
-Refer to [SSH_connections examples](https://github.com/netscaler/ansible-collection-netscaleradc/tree/main/examples/ssh_connections) to know how `ansible.builtins.` plugins can be used to configure the NetScaler ADC. 
+The collection provides an SSH connection plugin (`netscaler.adc.ssh_netscaler_adc`) that enables direct SSH connectivity to NetScaler ADC devices for executing shell commands and CLI operations.
+
+#### Prerequisites
+
+- SSH key-based authentication must be configured
+- SSH access to the NetScaler ADC device
+- Private SSH key file available on the control machine
+
+#### Inventory Configuration
+
+Configure your inventory file with the required SSH parameters:
+
+**Example 1: Group-based inventory**
+```ini
+[demo_netscaler1]
+demo_netscalers
+
+[demo_netscaler1:vars]
+ansible_host=10.10.10.10
+ansible_user=nsroot
+ansible_ssh_private_key_file=~/.ssh/id_rsa
+nitro_pass=YourPassword
+```
+
+**Example 2: Inline inventory**
+```ini
+[demo_netscalers]
+netscaler_adc ansible_host=10.10.10.10 ansible_user=nsroot ansible_ssh_private_key_file=~/.ssh/id_rsa
+```
+
+**Required inventory parameters:**
+- `ansible_host` - IP address or hostname of NetScaler ADC
+- `ansible_user` - SSH username (typically `nsroot`)
+- `ansible_ssh_private_key_file` - Path to SSH private key
+- `nitro_pass` - Password for nscli commands (required when using CLI commands)
+
+#### Playbook Structure for Shell Commands
+
+To execute FreeBSD shell commands on the NetScaler appliance:
+
+```yaml
+---
+- name: Execute shell commands on NetScaler
+  hosts: demo_netscalers
+  connection: netscaler.adc.ssh_netscaler_adc
+  remote_user: nsroot
+  gather_facts: false
+
+  vars:
+    ansible_python_interpreter: /var/python/bin/python
+
+  tasks:
+    - name: List files in /var/tmp
+      ansible.builtin.command: "ls -lhrt /var/tmp/"
+      register: result
+      changed_when: false
+
+    - name: Display output
+      ansible.builtin.debug:
+        msg: "{{ result.stdout_lines }}"
+```
+
+**Required settings for shell access:**
+- `connection: netscaler.adc.ssh_netscaler_adc` - Use the SSH connection plugin
+- `ansible_python_interpreter: /var/python/bin/python` - Required for shell command execution
+- `gather_facts: false` - Fact gathering is not supported
+
+#### Playbook Structure for NetScaler CLI Commands
+
+To execute NetScaler CLI commands using nscli:
+
+```yaml
+---
+- name: Execute NetScaler CLI commands
+  hosts: demo_netscalers
+  connection: netscaler.adc.ssh_netscaler_adc
+  remote_user: nsroot
+  gather_facts: false
+
+  vars:
+    ansible_python_interpreter: /var/python/bin/python
+    nscli_command: "show ns version"
+
+  tasks:
+    - name: Run NetScaler CLI command
+      ansible.builtin.command: "nscli -s -U :nsroot:{{ nitro_pass }} {{ nscli_command }}"
+      register: cli_result
+      changed_when: false
+
+    - name: Display CLI output
+      ansible.builtin.debug:
+        msg: "{{ cli_result.stdout_lines }}"
+```
+
+**CLI command format:**
+- Use `nscli -s -U :nsroot:{{ nitro_pass }} <command>` to execute NetScaler CLI commands
+- The `-s` flag runs in non-interactive mode
+- The `-U :nsroot:{{ nitro_pass }}` provides authentication credentials
+- Replace `<command>` with any valid NetScaler CLI command (e.g., `show ns ip`, `show lb vserver`)
+
+#### Running the Playbook
+
+```bash
+ansible-playbook playbook.yaml -i inventory.ini
+```
+
+Add `-vvvv` for verbose debugging output if needed:
+```bash
+ansible-playbook playbook.yaml -i inventory.ini -vvvv
+```
+
+#### Additional Examples
+
+For more complete examples and use cases, refer to the [SSH connections examples](https://github.com/netscaler/ansible-collection-netscaleradc/tree/main/examples/ssh_connections) directory. 
 
 ### Authentication
 

plugins/connection/ssh_netscaler_adc.py

@@ -391,25 +391,41 @@ def _return_tuple_manipulate(func):
     def wrapped(self, *args, **kwargs):
         return_tuple = func(self, *args, **kwargs)
         return_tuple = list(return_tuple)
-        subst = ""
+
+        # Decode stdout
+        stdout = codecs.decode(return_tuple[1], errors='ignore')
+
+        # Remove "Done" messages with surrounding newlines
         regex = r"(\r\n|\r|\n|)( Done)(\r\n|\r|\n)+"
-        return_tuple[1] = re.sub(regex, subst, codecs.decode(return_tuple[1]), 0, re.UNICODE)
+        stdout = re.sub(regex, "", stdout, 0, re.UNICODE)
+
+        # Remove Warning messages (multi-line)
+        warning_regex = r"Warning: \[[\s\S]*?\]\s*"
+        stdout = re.sub(warning_regex, "", stdout, 0, re.UNICODE)
 
-        # Ansible needs some data from return_tuple[1](or stdout). So, we are returning the same to ansible
+        # Remove leading "]" characters that might remain
+        stdout = re.sub(r"^\]\s*", "", stdout, re.MULTILINE)
+
+        # Remove extra blank lines
+        stdout = re.sub(r"\n\s*\n", "\n", stdout)
+
+        # Try to extract JSON if present
         regex2 = r'{.*}'
         try:
-            return_tuple[1] = re.findall(regex2, str(return_tuple[1]))[0]
-        except IndexError:
+            json_match = re.findall(regex2, stdout)
+            if json_match:
+                stdout = json_match[0]
+        except (IndexError, AttributeError):
             pass
-            # If no match, return the old `return_tuple[1]` (i.e., stdout)
+            # If no match, use the cleaned stdout
 
+        return_tuple[1] = stdout.encode() if isinstance(return_tuple[1], bytes) else stdout
         return_tuple = tuple(return_tuple)
         return return_tuple
     return wrapped
 
 
 def _manipulate_cmd(func):
-
     @wraps(func)
     def wrapped(self, cmd, *args, **kwargs):
         # Adding the 'shell' command for the citrix adc cli
@@ -455,3 +471,48 @@ def exec_command(self, cmd, in_data=None, sudoable=True):
         ''' run a command on the remote host '''
 
         return super(Connection, self).exec_command(cmd, in_data=in_data, sudoable=sudoable)
+
+    @_return_tuple_manipulate
+    def _bare_run(self, cmd, in_data, sudoable=True, checkrc=True):
+        """
+        Wrapper around parent _bare_run to clean NetScaler output
+        """
+        return super(Connection, self)._bare_run(cmd, in_data, sudoable=sudoable, checkrc=checkrc)
+
+    def put_file(self, in_path, out_path):
+        """
+        Transfer a file from local to remote using piped method due to NetScaler limitations
+        """
+        display.vvv(u"PUT {0} TO {1}".format(in_path, out_path), host=self.host)
+
+        # Force piped transfer for NetScaler
+        # Save original transfer method
+        original_method = self.get_option('ssh_transfer_method')
+
+        try:
+            # Temporarily set to piped
+            self._options['ssh_transfer_method'] = 'piped'
+            return super(Connection, self).put_file(in_path, out_path)
+        finally:
+            # Restore original method
+            if original_method:
+                self._options['ssh_transfer_method'] = original_method
+
+    def fetch_file(self, in_path, out_path):
+        """
+        Fetch a file from remote to local using piped method due to NetScaler limitations
+        """
+        display.vvv(u"FETCH {0} TO {1}".format(in_path, out_path), host=self.host)
+
+        # Force piped transfer for NetScaler
+        # Save original transfer method
+        original_method = self.get_option('ssh_transfer_method')
+
+        try:
+            # Temporarily set to piped
+            self._options['ssh_transfer_method'] = 'piped'
+            return super(Connection, self).fetch_file(in_path, out_path)
+        finally:
+            # Restore original method
+            if original_method:
+                self._options['ssh_transfer_method'] = original_method