The Remote Command Line Function Component (Remote CLFC) enables
command line system calls to be executed on remote machines. The
design and implementation uses the RXA toolkit v2.2 to connect to
remote machines, execute the commands and return the results. The
returned output can then be parsed to be consumed one value at a time
and detect any problems with the executed command.
The Remote CLFC has the ability to connect to remote machines
using any of the following protocols: RSH, REXEC, SSH, AS400 or Windows.
You can select which of the protocols will be used; however, if left
to the default value of 'ANY', the FC will attempt to connect to the
remote machine using each of the available protocols one-by-one until
a successful connection is made.
The RXA libraries used by this FC support interactive
SSH sessions only; non-interactive SSH sessions are not supported.
You will need to provide information about the remote machine including
hostname, username and password. If the connection is being made using
the SSH protocol then you have the option of providing a keystore
name and passphrase instead of using a password for authentication.
Note:
SSH Connections are typically associated
with Linux/UNIX and z/OS hosts. However, by installing Cygwin and
the Cygwin openssh package on the Windows
target machine the SSH protocol can be used with those targets as
well. In addition, z/OS targets can be reached using the SSH protocol
also.
The hostname (address) of the target machine. This is a required
parameter.
Remote User
The name of a user with Administrative privileges on the target
machine.
Password
The password for the user (specified as Remote
User) on the target machine. This parameter may be optional in
the case of SSH connections using a keystore, as well as for RSH connections.
Key File Path
The full path to the OpenSSH private key file. This parameter
is optional, and is used only for SSH connections.
Passphrase
The passphrase that protects your private key, in the keystore
specified by the Keystore Path parameter above.
Connection Protocol
Select from 'ANY', 'SSH', 'RSH', 'REXEC', 'AS400'
and 'WIN'. This designates what protocol to use when connecting to
the remote machine. See Using the FC for more details.
Port
The port to use to connect to the target machine.
Command
The command that is to be executed on the target machine. This
is overridden if an output attribute 'command.line' has been provided.
This is a required parameter, unless the command.line Attribute is
supplied in the Output map.
Stdin source file (local)
The path to the file on the local system that is to be used
as standard input to the command specified. This parameter is optional.
Stdin destination directory (remote)
The path to an existing destination directory on the target
where you want the standard input file, designated by Stdin
source file (local), to be copied. If a value for Stdin
source file (local) has been provided, but no value for the destination
then a random temporary directory will be created on the remote machine.
Note that the file is copied temporarily; once the command has finished
execution, the copy on the remote machine is deleted.
Convert Stdin source file to character set
of target system
If checked, the Stdin source file will be converted to the character
set of the target system; otherwise, the current encoding of file
will be maintained.
Timeout (ms)
The desired CPU timeout period in milliseconds. If the operation
does not complete within the specified duration then the operation
is cancelled. This parameter is optional. An unspecified or 0 (zero)
value indicates Unlimited, that is, no computational time limit.
Note:
The timeout is a measure of the CPU clock time of the Remote
CLFC process, not a measure of the actual time elapsed since process
initiation. Commands that are not computationally intensive will
not timeout in the specified time if they have not reached their computational
time limit.
Initial connection timeout (ms)
An optional Remote CLFC parameter that defines a timeout period
for the initial connection to the target system. This has no effect
on AS400 targets.
Enable SSL for AS400?
This parameter governs whether an SSL connection is enforced
on the AS400 (i5/OS) connection. If checked an SSL connection will
be attempted to the AS400 target (SSL must be installed and configured
on the AS400 target system). The default is unchecked.
AS400 Proxy Server Name
This parameter defines an AS400 proxy server if so required.
Run AS400 Program?
An optional Remote CLFC parameter that defines the type of command
execution to use for an AS400 (i5/OS) connection. AS400 programs have
the extension .PGM. Arguments for these AS400 Programs can be specified
using the Entry Attribute command.args.
The default value
is unchecked.
Enable RXA Internal Logging?
Enabling this will allow the RXA internal logger to generate
log messages in the AssemblyLine log file.
AS400 Command Line Arguments Character Encoding
The character encoding to use for AS400 command line arguments.
The default character encoding of the JVM is used if not specified.
This configuration parameter is optional and only applies when the Run
AS400 Program? parameter is set. Failure to set this value to
the proper encoding of the target AS400 box can cause the command
line parameter strings to be corrupted if the encoding of the JVM
on the remote machine does not match the default encoding of the AS400
machine where the AS400 Program will be run.
Some of the parameters configured in the Configuration screen of
the Remote CLFC can be provided as Attributes mapped from the work
Entry in the Input Map. When present and non-empty, they take precedence
over the parameters in the Configuration screen:
command.line
The command that is to be executed on the target machine. This
attribute has to be defined in the Output map, and will replace the
"Command" parameter defined under the
Config tab.
command.args
A multi-valued Attribute whose values each are command
line arguments. Required when executing AS400 Programs.
command.args.delim
This Attribute specifies the command/Program argument delimiter.
If not specified the default is a single white space character.
stdin.source
This attribute, of type java.io.String, represents the path
to the file on the local machine that is to be used as standard input
for the specified command.
stdin.destination
This attribute, of type java.io.String, represents the path
where the transferred file should be stored on the remote machine.
In other words, if an attribute called command.line is
provided in the input entry object then any command that was entered
in the Config Editor will be disregarded. This allows you to call
the Remote CLFC repeatedly by other components in the AssemblyLine
to perform different commands.
Once the Remote CLFC has executed the command specified by either
the command.line attribute or the Command configuration parameter as discussed above,
the FC makes the following attributes available for attribute mapping:
command.returnCode (int)
The return code that resulted from executing the remote command.
command.error (String)
The standard error message, if any, that was generated when
the command was run.
command.out (String)
The standard output message, if any, that was generated when
the command was run.
The Remote CLFC may be used within an AssemblyLine containing other Tivoli® Directory
Integrator components
such as Connectors and other Function Components. To function correctly,
you must configure the Remote CLFC correctly using the Config Editor.
When it is initialized it will establish a connection with the remote
machine and then when its perform() method is called (normally
when it is reached in the AssemblyLine it is part of), it will execute
its command on the target.
Upon completion, the perform() method will return an
Entry object containing the three output attributes described
above: command.returnCode, command.error and command.out. These attributes will then be available
to other Tivoli Directory
Integrator components further down in the AssemblyLine.
If you use the FC to perform a command that returns a list of messages
in Standard Out such as a directory listing then the Remote CLFC would
need to be used in conjunction with other Tivoli Directory
Integrator components, like a
Parser, in order to extract the individual entries from the command.out String object and process them one
at a time.
Configuring the Target System
The target machines must satisfy the following requirements:
Windows Targets
Using the WIN protocol: Windows XP targets
must have Simple File Sharing disabled for Remote Execution and Access
to work. Simple Networking forces all logins to authenticate as "guest".
A guest login does not have the authorizations necessary for Remote
Execution and Access to function.
To disable Simple File Sharing,
you need to start Windows Explorer and click Tools->Folder
Options. Select the View tab, scroll through
the list of settings until you find Use Simple File
Sharing. Remove the check mark next to Use Simple
File Sharing, then click Apply and OK.
Windows XP includes a built-in firewall
called the Internet Connection Firewall (ICF). By default, ICF is
disabled on Windows XP systems, except on Windows XP Service Pack
2 where it is on by default. If either firewall is enabled on a Windows
XP target, it will block attempted accesses by Remote Execution and
Access. On Service Pack 2, you can select the File and Printer Sharing
box in the Exceptions tab of the Windows Firewall configuration to
allow access.
The target machine must have remote registry
administration enabled (which is the default configuration) in order
for Remote Execution and Access to run commands and execute scripts
on the target machine.
The default hidden administrative disk
shares (such as C$, D$, etc) are required for proper operation of
Remote Execution and Access.
Cygwin Targets
Using the SSH protocol: To use SSH logins
to remote Windows computers, you must download Cygwin from http://cygwin.com and install it on each Windows
machines that your application will target. Complete documentation
for Cygwin is available at http://cygwin.com.
To
use Remote Execution and Access applications on Cygwin targets, you
will need to install up to two additional Cygwin packages that are
not part of the default Cygwin installation. From http://cygwin.com,
download and install openssh, which is in the net category
of Cygwin packages. openssh contains the ssh daemon that is needed
to support SSH logins on Cygwin targets. Another package, cygrunsrv,
which is in the admin category of packages,
provides the ability to run the ssh daemon as a Windows service. If
you do not wish to run the ssh daemon as a service, this package is
optional.
MKS Targets
The MKS toolkit is an alternative to using Cygwin on windows
machines. For more information refer to http://www.mkssoftware.com/.
To use MKS from the windows command line, add the path to MKS_ Installation/bin to
the PATH environment variable. By default in MKS, SSH is configured
to use Username password authentication. To set up passwordless authentication,
a pair of public and private keys must be generated using the ssh-keygen
utility (available with the MKS Toolkit and on most UNIX systems)
and copy them to the machine to which to connect.
If connecting
to a secure shell service or daemon that is derived from the OpenSSH
version of secure shell (such as the secure shell service (sshd) from
MKS Toolkit), the protocol version 1 RSA keys must be appended to
the hosts's ~/.ssh/authorized_keys file
and protocol version 2 RSA and DSA keys to the host's ~/.ssh/authorized_keys2 file where ~/ is the home directory of the account on
the remote host.
UNIX and Linux Targets
Using SSH, RSH or REXEC protocols: The RXA toolkit this FC uses does
not supply SSH code for UNIX machines. You must ensure SSH is installed
and enabled on any target you want to access using SSH protocol. OpenSSH
3.71, or higher, contains security enhancements not available in earlier
releases.
RXA cannot establish connections with any UNIX target
that has all remote access protocols (rsh, rexec, or ssh) disabled.
In
all UNIX environments except Solaris, the Bourne shell (sh) is used
as the target shell in UNIX environments. On Solaris targets, the
Korn shell (ksh) is used instead due to problems encountered with
sh.
In order for RXA to communicate with Linux and other SSH
targets using password authentication, you must edit the file /etc/ssh/sshd_config
file on target machines and set:
PasswordAuthentication yes (the default is 'no')
After
changing this setting, stop and restart the SSH daemon using the following
commands:
/etc/init.d/sshd stop
/etc/init.d/sshd start
When using the rsh / rexec
connection protocol, the Tivoli Directory
Integrator Server must be running as a privileged
user (root on Unix or a user with Administrator privileges on Windows).
The connection will fail if this requirement is not met. The rsh
and rexec connection protocols require that the source port be "trusted"
(port number less than 1024), however these platforms restrict creation
of trusted port connections to privileged users.
For further
details on how to configure SSH between the local machine and the
target, either using password authentication or a keystore, please
refer to the relevant OpenSSH documentation at http://www.openssh.com.
z/OS Targets
Using SSH and z/OS, VMS shell commands can be executed on mainframe
zSeries systems. Commands executed using this type of connection are
very Unix-like as they are run in the simulated Unix shell
environment.
AS400 targets require the IBM Toolbox for Java to be installed
along with a suitable JRE. The IBM Toolbox for Java is also required
on the Tivoli Directory
Integrator server where the JAR files will be placed in the TDI_install_dir/jars/3rdParty/IBM directory. The
commands and programs themselves have to be located under the QSYS
library on the iSeries system.
When enabling the AS400 SSL connection option,
additional configuration is required for self signed certificates.
In this case, the signing certificate must be added to the Java Security
CA Certificate store (jre_directory/lib/security/cacerts).
Further information can be found here: http://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/keytool.html.
Directory Integrator, Version 7.1.1