cisco.radkit.port_forward module – Forwards a port on a device in RADKIT inventory to localhost port.

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.port_forward.

New in cisco.radkit 0.3.0

Synopsis

  • This module forwards a port on a device in RADKIT inventory to local port so that connections can be made with other modules by changing port.

  • Exposed local ports are unprotected (there is no way to add an authentication layer, as these are raw TCP sockets).

  • In the case of port forwarding, no credentials are used from the RADKit service and must be configured locally on ansible client side.

Requirements

The below requirements are needed on the host that executes this module.

  • radkit

Parameters

Parameter

Comments

client_ca_path

string

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.

client_cert_path

string

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_key_password_b64

aliases: radkit_client_private_key_password_base64

string / required

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.

client_key_path

string

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.

destination_port

integer / required

Port on remote device to connect. Port must be configured to be forwarded in RADKIT inventory.

device_name

string / required

Name of device as it shows in RADKit inventory

identity

aliases: radkit_identity

string / required

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_port

integer / required

Port on localhost to open

service_serial

aliases: radkit_serial, radkit_service_serial

string / required

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.

test

boolean

Tests your configuration before trying to run in async

Choices:

  • false ← (default)

  • true

timeout

integer

Maximum time in seconds to keep the port forward active. If not specified, runs indefinitely until terminated. Not needed to use with as

Examples

# The idea of this module is to start the module once and run on localhost for duration of the play.
# Any other module running on the localhost can utilize it to connect to devices over the opened port.
#
# This example utilizes port forwarding to connect to multiple hosts at a time. Each host will have ssh
# port forwarded to a port on the localhost (host 1 = 4000, host 2, 4001, etc). The port must be allowed
# for forwarding in the RADKIT inventory.
---
- hosts: all
  become: no
  gather_facts: no
  vars:
    # This is the base port, each host will be 4000 + index (4000, 4001, etc)
    local_port_base_num: 4000
    # in this example, we will forward ssh port
    destination_port: 22
    ansible_ssh_host: 127.0.0.1
  pre_tasks:
    - name: Get a host index number from ansible_hosts
      set_fact:
        host_index: "{{ lookup('ansible.utils.index_of', data=ansible_play_hosts, test='eq', value=inventory_hostname, wantlist=True)[0] }}"
      delegate_to: localhost

    - name: Create local_port var
      set_fact:
        local_port: "{{ local_port_base_num|int + host_index|int }}"
        ansible_ssh_port: "{{ local_port_base_num|int + host_index|int }}"
      delegate_to: localhost

    - name: Test RADKIT Port Forward To Find Potential Config Errors (optional)
      cisco.radkit.port_forward:
        device_name: "{{ inventory_hostname }}"
        local_port: "{{ local_port }}"
        destination_port: "{{ destination_port }}"
        test: True
      delegate_to: localhost

    - name: Start RADKIT Port Forward And Leave Running for 300 Seconds (adjust time based on playbook exec time)
      cisco.radkit.port_forward:
        device_name: "{{ inventory_hostname }}"
        local_port: "{{ local_port }}"
        destination_port: "{{ destination_port }}"
      async: 300
      poll: 0
      delegate_to: localhost

    - name: Wait for local port to become open (it takes a little bit for forward to start)
      ansible.builtin.wait_for:
        port: "{{ local_port }}"
        delay: 3
      delegate_to: localhost
  tasks:

    - name: Example linux module 1 (note; credentials are passed locally)
      service:
        name: sshd
        state: started

    - name: Example linux module 2 (note; credentials are passed locally)
      shell: echo $HOSTNAME

Authors

  • Scott Dozier (@scdozier)