README-zos-rexx-connection-plugin.md

Ansible z/OS Connection Plugin

Since EBCDIC encoding is used on z/OS, custom plugins are needed to determine the correct transport method when targeting a z/OS system.

• Ansible z/OS Connection Plugin
  • Summary of Changes
    • Action Plugin: normal.py, forked from the Ansible normal.py action plugin
    • Connection Plugin: zos_ssh.py, forked from the Ansible ssh.py connection plugin
  • Getting Started
    • Prerequisites
      • Ansible Host
      • REXX Module Configuration

Summary of Changes

Action Plugin: normal.py, forked from the Ansible normal.py action plugin

The normal.py action plugin is called when preparing for module execution. normal.py defines the ActionModule class which inherits from ActionBase.

ActionBase has a method, _configure_module() which is called during module configuration. One of the return values of _configure_module() is the shebang line for the module.

Since REXX does not have an ordinary shebang line like shell or python, a shebang line is not found when using REXX modules. After _configure_module() is called, an exception is raised if no shebang line is found.

Our fork of normal.py overrides _configure_module() by calling the parent method and adding a single space in place of an empty shebang line value. A single space must be added in place of an empty string because python conditionals treat an empty string as a NoneType.

Connection Plugin: zos_ssh.py, forked from the Ansible ssh.py connection plugin

The zos_ssh.py connection plugin is a fork of the default ssh.py plugin with added functionality for checking if a module is written in REXX.

Since REXX scripts need to be in EBCDIC encoding to run, they need to be handled differently during transfer. If the string __ANSIBLE_ENCODE_EBCDIC__ is found on the first line of the module, the module is transferred to the target system using SCP. Otherwise, SFTP is used. SCP treats files as text, automatically encoding as EBCDIC at transfer time. SFTP treats files as binary, performing no encoding changes.

Getting Started

This repo includes any plugins written or modified to account for our use case. When running a playbook, Ansible searches the working directory for action_plugin and connection_plugin folders. If a plugin in one of these folders matches the name of a plugin Ansible is looking for, is it used in place of the installation's version.

Prerequisites

Ansible Host

• Ansible 2.9 is the version the changes were based on, other versions may work but are untested.
  • Reference Ansible's Installation Guide for OS specific installatoin instructions.
• Python 2.7 or 3.7

REXX Module Configuration

1. Ensure REXX modules first line is a comment containing the following:
   1. The string rexx, this value is case insensitive.
      • When running a REXX script from USS CLI, the word rexx needs to appear on the first line for interpreter recognition.
   2. The string __ANSIBLE_ENCODE_EBCDIC__, this value is case sensitive.

   • Example REXX module:

     /* rexx  __ANSIBLE_ENCODE_EBCDIC__  */
     x = 55
     SAY '{"SYSTEM_VERSION":"' x '"}'
     RETURN 0

Copyright

© Copyright IBM Corporation 2020