cisco.radkit.ssh_proxy module – Starts an SSH server proxy to access devices in RADKIT inventory via SSH.
Note
This module is part of the cisco.radkit collection (version 2.0.0).
It is not included in ansible-core.
To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install git+https://wwwin-github.cisco.com/scdozier/cisco.radkit-ansible.git.
You need further requirements to be able to use this module,
see Requirements for details.
To use it in a playbook, specify: cisco.radkit.ssh_proxy.
New in cisco.radkit 2.0.0
Synopsis
This module starts an SSH server that proxies connections to devices in RADKIT inventory.
SSH username format is <device_name>@<radkit_service_serial> to specify the target device.
Supports both shell and exec modes for device interaction.
Key advantage over port forwarding - device credentials remain on the RADKit service, not locally.
RECOMMENDED FOR: Network devices (routers, switches, firewalls) with Ansible network_cli connection.
FOR LINUX SERVERS: Use port_forward module instead - SSH proxy has limitations with SCP/file transfers.
IMPORTANT: Always disable SSH host key checking unless custom host keys are configured (host keys are ephemeral by default).
Password authentication to SSH proxy may not work reliably with Ansible network_cli connection.
For network devices, use without password and rely on RADKit service authentication.
SCP and SFTP file transfers are not supported through SSH proxy - use port_forward for Linux servers.
This module replaces the deprecated network_cli and terminal connection plugins as of version 2.0.0.
Requirements
The below requirements are needed on the host that executes this module.
radkit
Parameters
Parameter |
Comments |
|---|---|
Alternate path to client ca cert for RADKIT If the value is not specified in the task, the value of environment variable RADKIT_ANSIBLE_CLIENT_CA_PATH will be used instead. |
|
Alternate path to client cert for RADKIT If the value is not specified in the task, the value of environment variable RADKIT_ANSIBLE_CLIENT_CERT_PATH will be used instead. |
|
Client certificate password in base64 If the value is not specified in the task, the value of environment variable RADKIT_ANSIBLE_CLIENT_PRIVATE_KEY_PASSWORD_BASE64 will be used instead. |
|
Alternate path to client key for RADKIT If the value is not specified in the task, the value of environment variable RADKIT_ANSIBLE_CLIENT_KEY_PATH will be used instead. |
|
Destroy any existing SSH proxy before starting a new one Choices:
|
|
Custom SSH host private key in PEM format. If not provided, an ephemeral key will be generated. |
|
Identity to authentiate with RADKit (xxxx@cisco.com). If the value is not specified in the task, the value of environment variable RADKIT_ANSIBLE_IDENTITY will be used instead. |
|
Local address to bind the SSH server to Default: |
|
Port on localhost to bind the SSH server |
|
Password for SSH authentication to the proxy server (optional) WARNING: Using password may cause authentication issues with Ansible network_cli connection RECOMMENDED: Leave empty and rely on RADKit service authentication for network devices This password protects access to the SSH proxy itself, not the device credentials Device credentials remain securely on the RADKit service side |
|
Radkit service serial If the value is not specified in the task, the value of environment variable RADKIT_ANSIBLE_SERVICE_SERIAL will be used instead. |
|
Tests your configuration before trying to run in async Choices:
|
|
Maximum time in seconds to keep the SSH server active. If not specified, runs indefinitely until terminated. |
Examples
# Recommended: SSH proxy for network devices without password
# This configuration works reliably with Ansible network_cli connection
---
- name: Setup RADKit SSH Proxy for Network Devices
hosts: localhost
become: no
gather_facts: no
vars:
ssh_proxy_port: 2225
radkit_service_serial: "{{ lookup('env', 'RADKIT_ANSIBLE_SERVICE_SERIAL') }}"
tasks:
- name: Test RADKIT SSH Proxy Configuration (optional)
cisco.radkit.ssh_proxy:
local_port: "{{ ssh_proxy_port }}"
test: True
- name: Start RADKIT SSH Proxy Server
cisco.radkit.ssh_proxy:
local_port: "{{ ssh_proxy_port }}"
async: 300 # Keep running for 5 minutes
poll: 0
- name: Wait for SSH proxy to become available
ansible.builtin.wait_for:
port: "{{ ssh_proxy_port }}"
host: 127.0.0.1
delay: 3
timeout: 30
- name: Execute commands on network devices via SSH proxy
hosts: cisco_devices
become: no
gather_facts: no
connection: ansible.netcommon.network_cli
vars:
ansible_network_os: ios
ansible_port: 2225 # Port where the ssh_proxy is listening
ansible_user: "{{ inventory_hostname }}@{{ lookup('env', 'RADKIT_ANSIBLE_SERVICE_SERIAL') }}"
# IMPORTANT: Disable host key checking - SSH proxy host keys change between sessions
ansible_ssh_common_args: '-o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null'
tasks:
- name: Run show ip interface brief
cisco.ios.ios_command:
commands: show ip interface brief
register: interfaces_output
- name: Display interface information
debug:
var: interfaces_output.stdout_lines
# Inventory configuration for the above playbook:
# [cisco_devices]
# router1 ansible_host=127.0.0.1
#
# [cisco_devices:vars]
# ansible_ssh_common_args='-o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null'
# WARNING: Using password under ssh_proxy module may cause authentication issues
- name: SSH Proxy
hosts: localhost
become: no
gather_facts: no
tasks:
- name: Start RADKIT SSH Proxy with Password
cisco.radkit.ssh_proxy:
local_port: 2222
async: 300
poll: 0
# Manual SSH connection works: ssh device@service@localhost -p 2222
# But Ansible network_cli may fail with authentication errors
# Example with custom host key for consistent fingerprints
- name: SSH Proxy with Custom Host Key
hosts: localhost
become: no
gather_facts: no
vars:
ssh_host_key: |
-----BEGIN OPENSSH PRIVATE KEY-----
b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAAAFwAAAAdzc2gtcn
...
-----END OPENSSH PRIVATE KEY-----
tasks:
- name: Start RADKIT SSH Proxy with Custom Host Key
cisco.radkit.ssh_proxy:
local_port: 2222
host_key: "{{ ssh_host_key }}"
destroy_previous: True
async: 300
poll: 0
# IMPORTANT USAGE NOTES:
#
# 1. FOR NETWORK DEVICES (routers, switches, firewalls):
# - Use ssh_proxy module (this module)
# - Works with ansible.netcommon.network_cli connection
# - No password on SSH proxy recommended
# - Always disable host key checking
#
# 2. FOR LINUX SERVERS:
# - Use port_forward module instead
# - SSH proxy doesn't support SCP/SFTP file transfers
# - Required for Ansible modules that transfer files
#
# 3. DEPRECATED CONNECTION PLUGINS:
# - cisco.radkit.network_cli (deprecated as of 2.0.0)
# - cisco.radkit.terminal (deprecated as of 2.0.0)
# - Use standard ansible.netcommon.network_cli with ssh_proxy instead
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
|---|---|
Information about the SSH server that was started Returned: success |
|
List of addresses the SSH server is bound to Returned: success Sample: |
|
MD5 fingerprint of the SSH host key Returned: success Sample: |
|
SHA256 fingerprint of the SSH host key Returned: success Sample: |
|
Address the SSH server is bound to Returned: success Sample: |
|
Port the SSH server is listening on Returned: success Sample: |
|
Status of the SSH server Returned: success Sample: |