In R530 of IBM i5/OS, HMC commands can now be sent directly to the HMC by using the 5733SC1 IBM Portable Utilities for i5/OS LPP. This allows i5/OS system administrators to send commands to the HMC from an i5/OS command line, the scheduler or from a program. Public key authentication can be configured to allow the commands to be run in an unattended environment. As an example, a CL program performing a system backup can issue a DLPAR move command to add a tape device to its partition before performing the save.

This document provides a sample CL program that can be used to submit HMC commands and check if they run successfully. It also provides the HMC and i5/OS setup necessary to run the sample.

HMC Setup

Step 1: Enable SSH on the HMC:
a Expand HMC Management > HMC Configuration.
b In the Contents area, click Enable/Disable Remote Command Execution.
c Select the appropriate check box.
d Click OK.

Step 2: Enable SSH in the HMC firewall:
a Expand HMC Management > HMC Configuration.
b In the Contents area, click Customize Network Settings.
c Click the LAN Adapters tab.
d Select the LAN adapter used for the open network (normally eth1), then click the details button.
e Select Secure Shell 22:tcp , and click the allow incoming button.
f Click OK, and click OK.
g The HMC will display a panel stating that the settings will be applied on the next reboot. Click OK. Do not reboot. Firewall settings go into effect immediately.

i5/OS Setup

Step 1: Install and Configure IBM Portable Utilities for i5/OS:

The LPO 5733SC1, IBM Portable Utilities for i5/OS, is now available for V5R3 i5/OS users. The 5733SC1 LPO contains the OpenSSH, OpenSSL, and zlib open source packages that are ported to i5/OS by using the i5/OS PASE runtime environment. The 5733SC1 LPO requires that i5/OS V5R3 and i5/OS Option 33 (i5/OS PASE – Portable Solutions Application Environment) are installed. For further information on installing and configuring this LPP, refer to the following Web site:

http://www-1.ibm.com/servers/enable/site/porting/tools/openssh.html .

Note: The 5733SC1 LPO requires i5/OS V5R3 and also requires that 5722SS1 Option 33 (i5/OS PASE – Portable Solutions Application Environment) be installed. The sample program requires 5722SS1 Option 30 QShell Interpreter.
a Apply current SSH PTFs. For a list of required PTFs, refer to the following Rochester Support Center knowledgebase document:

371780606, OpenSSH PTF List for V5R3: Database ‘Rochester Support Line KnowledgeBase’, View ‘All Documents’, Document ‘OpenSSH PTF List for V5R3’

OpenSSH portion of 5733-SC1 consists of these utilities:

* ssh – a secure telnet replacement that allows an i5/OS user to connect as a client to a server running the sshd daemon
* sftp – a secure ftp replacement
* scp – a secure file copy program — basically an alternative to sftp for copying a single file in the integrated file system (IFS)
* ssh-keygen – a public/private key generation and management tool
* ssh-agent – an authentication agent that can store private keys
* sshd – the daemon that handles incoming ssh connections.

Note:
The sshd daemon utility allows users to connect to i5/OS via an ssh client. In contrast to connecting to i5/OS via telnet and being presented with a 5250 screen interface, users that connect via ssh to an i5/OS system running the sshd daemon will be presented with a character interface and an i5/OS PASE command line.

Hints and Tips for Using OpenSSH:
CRTIMGCLG IMGCLG(SSHCAT) DIR(‘/home/SSHCAT’) CRTDIR(*YES)
ADDIMGCLGE IMGCLG(SSHCAT) FROMFILE(‘/5733sc1/5733sc1.iso’) <=V5R3 CD Lable must be "SC1_CO"
CRTDEVOPT DEVD(OPTVRT01) RSRCNAME(*VRT) ONLINE(*YES) TEXT(‘virtual optical device’)
LODIMGCLG IMGCLG(SSHCAT) DEV(OPTVRT01) OPTION(*LOAD)

To install OpenSSH:
RSTLICPGM LICPGM(5733SC1) DEV(OPTxx) OPTION(*BASE) RSTOBJ(*ALL) LNG(2924)
RSTLICPGM LICPGM(5733SC1) DEV(OPTxx) OPTION(1) RSTOBJ(*PGM)

Step 2: Configure the QSHELL path

The sample assumes the IBM Portable Utilities are added to the QSHELL path. The QSHELL path can be set system wide by adding a path environment variable or by using one of the other methods described in the IBM iSeries Information Center.

To set the path using a system wide environment variable, on the i5/OS command line, type the following:

ADDENVVAR ENVVAR(PATH) VALUE(‘/usr/bin:.:/QOpenSys/usr/bin:/QOpenSys/QIBM/ProdData/SC1/OpenSSH/openssh-3.5p1/bin’) LEVEL(*SYS)

Press the Enter key.

Step 3: Verify the i5/OS user profile home directory:
a For each i5/OS user profile running the program under their account, verify the home directory. Use the DSPUSRPRF command to verify the i5/OS user’s home directory (HOMEDIR field):

DSPUSRPRF

Press the Enter key. The default is /home/.
b Verify the directory exists:

wrklnk

Press the Enter key.
c Use the mkdir command to create the directory or alter the profile to the desired existing home directory as desired. This directory is used to store the user ssh configuration information such as known_hosts and the private/public key pairs.

Step 4: Verify the DNS configuration and network connectivity:
a The HMC host name must be configured in the DNS server or a local host entry must exist for the HMC (CFGTCP Option 10). To verify network connectivity and DNS resolution, type the following command on the i5/OS command line:

ping

where is the HMC’s short host name. Verify that the ping is successful.
b Type the following command:

nslookup ‘w.x.y.z’

where ‘w.x.y.z’ is the HMC’s TCP/IP address. This must return the HMC’s fully qualified host name.
c If the HMC host name or TCP/IP address cannot be correctly resolved, then correct the DNS configuration or add a local hosts entry for the HMC to the i5/OS partition. To add the HMC to the partition hosts list use the following command:

ADDTCPHTE INTNETADR(‘w.x.y.z’) HOSTNAME((‘myhmc’) (‘myhmc.mydomain’))

where ‘w.x.y.z’ is the HMC TCP/IP address used on the open network (usually eth1) and myhmc and myhmc.mydomain are the HMC host name and HMC host name.domain name as configured in the HMC network configuration.

Step 5: Verify the ssh connection:
a Start QSHELL using the command STRQSH .
b At the QSHELL prompt, verify the ssh connection by using the following command:

ssh -T @

It will prompt for password.

Note: The -T is optional. If not specified, the user receives the warning message tcgetattr: A system call received a parameter that is not valid. This warning can be ignored.
c Verify that the user can log on the HMC and run a command such as ls /usr/hmcrbin .

Note: The first time a ssh connection is made to the HMC the user is prompted to verify the authenticity of the hmc:

The authenticity of host ‘cs6hmc (9.5.32.12)’ can’t be established.
. key fingerprint is RSA.
Are you sure you want to continue connecting (yes/no)?

The user must answer yes. The HMC’s public key will then be stored in the user’s /.ssh/known_hosts file and the user will not be prompted again. The known_hosts file must be configured for each i5/OS user profile that the CL program will run under.
d Log off the HMC. Use the command exit to end the ssh session.

Step 6: Generate a private public key pair on the i5/OS partition.

These instructions can also be found in the eServer Information Center web site. The commands used in the i5/OS setup can be entered from QSHELL (STRQSH ) or from the PASE terminal session (call qp2term ).
a Generate a key pair for the i5/OS partition by using the ssh command ssh-keygen . Run the following command from the partition Qshell or PASE terminal session. Do not type a passphrase when prompted (press the Enter key).

ssh-keygen -t rsa

Generating public/private rsa key pair.
Enter file in which to save the key (/ddilling/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /ddilling/.ssh/id_rsa.
Your public key has been saved in /ddilling/.ssh/id_rsa.pub.
The key fingerprint is: 86:57:44:54:f6:2c:9f:fa:88:fd:97:2e:b4:53:c0:f8 ddilling@RCHASCLC.RCHLAND.IBM.COM
b Copy the public key to the clipboard. List the public key that was generated:

cat

where is the public key file name (id_rsa.pub) from the previous step. The output will be a long string such as the following:

ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAIEAuF8Uq/GG4CdFdDUXl+ggSleo96SbGZEkGtKD721r+hCPya9iy3tCYijCFs9SMjovHdlGmzX5FFbOuYDnlk2yvhBfXvx/V7TmmmsvQlvsz8a8ulm/Z+dzwJiUV+rHv9moeRnLVksafsuHCo034qITqYDMKlS27jVtc4/HG+VF1c8= ddilling@RCHASCLC.RCHLAND.IBM.COM
Example of using Qshell to list and copy the public key:

Screen shot of QSH Command Entry screen,
Caution : The IBM Personal Communications emulator paste function will append a carriage return and line feed character to the end of each line if it is used to paste into a Microsoft Windows program (such as Notepad) or a Windows ssh client (such as PuTTY). Be careful to remove the extra control characters when pasting to a Windows program.

Step 7: Type the public key into the HMC:

The public key generated in Step 6 must be entered into the HMC user’s ~/.ssh/authorized_keys2 file using the HMC mkauthkeys command. These instructions can also be found in the eServer Information Center web site. The mkauthkeys command can be run on the local HMC or any ssh session connected to the HMC. The example below uses Qshell as the ssh client.

Note: Type or copy/paste the key string exactly as it is stored in the id_rsa.pub file. Do not include any extra carriage return, line feed or space. See the example below.
a Open a ssh session to the HMC or a restricted shell on the local HMC.

Example of using Qshell to ssh to the HMC (same as step 5 above):

Screen shot of QSH Command Entry
b Register the public key using the mkauthkeys command. Type the command mkauthkeys –add on the first line. Position the cursor at the start of the next line . Paste the key onto the next few lines. Insert a single quote at the beginning and end of the string as shown below:

Screen shot of QSH Command Entry for mkauthkeys
c Position the cursor at the end of the line and carefully remove the spaces that were inserted by the paste operation using the delete key. Press the Enter key to run the command.
Another screen shot of QSH Command Entry for mkauthkeys

Step 8: Verify the secure script configuration:

If the keys match, then running the ssh command from the partition will no longer prompt for a user or password (the terminal type prompt can be suppressed using the -T option). Exit any existing ssh session to the HMC, the connect again from Qshell or the PASE command shell. There should not be any prompt for password.

ssh

tcgetattr: The specified device does not exist.
Last login: Thu Jun 30 17:26:51 2005 from localhost.localdomain
tset: unknown terminal type unknown
Terminal type?
vt100
vt100
ddilling@cs6hmc:~>

If that fails, verify that the key was entered correctly. The output of the following HMC command must contain the key exactly as shown in Step 6b. If multiple systems have configured secure script, then more than one entry can exist.

cat .ssh/authorized_keys2

ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAIEAuF8Uq/GG4CdFdDUXl+ggSleo96SbGZEkGtKD721r+hCPya9iy3tCYijCFs9SMjovHdlGmzX5FFbOuYDnlk2yvhBfXvx/V7TmmmsvQlvsz8a8ulm/Z+dzwJiUV+rHv9moeRnLVksafsuHCo034qITqYDMKlS27jVtc4/HG+VF1c8= ddilling@RCHASCLC.RCHLAND.IBM.COM

Common Error Messages

1) ssh: w.x.y.z: Hostname and service name not provided or found

When you connect using a TCP/IP address, ssh expects to be able to perform a DNS reverse-lookup for the address provided. If the host name cannot be resolved, this error is returned. To resolve the problem, correctly register the HMC in the DNS (and enable reverse name look-up) or add a host table entry for the HMC address to the IBM eServer™ i5 partition’s host table. The following command creates a host table entry in i5/OS:

ADDTCPHTE INTNETADR(‘w.x.y.z’) HOSTNAME((somehostname)

Press the Enter key.

2) ssh-keygen fails with error “not enough entropy in RNG”

The fix for SE19413 is missing. See the recommended PTF list above.

3) “You don’t exist, go away!”.

The i5/OS user profile that the ssh command runs under must be 8 characters or less in length.

Running HMC Commands

Once ssh and private/public key authorization is configured, HMC commands can be run directly without prompting for password.

To run a Qshell command from the i5/OS command line or a CL program, use the QSH command; for example:

QSH CMD(‘ssh -T ddilling@cs6hmc lshmc -V’)

HMC commands can also be added to the scheduler; for example:

ADDJOBSCDE JOB(SSHCMD) CMD(QSH CMD(‘ssh -T ddilling@cs6hmc lshmc -V’)) FRQ(*ONCE) SCDTIME(’20:00:00′)

To run several commands at one time, it may be easier to create a shell script which runs the commands and then invoke the script from the i5/OS.

CL Sample

The following sample CL program shows how to invoke QSHELL to run the ssh command. The sample accepts a HMC name, command to run, optional parameters for the identity file and user, then runs the command on the remote HMC. Finally, it retrieves the return code of the command that was run to determine if the command succeeded.

The example calls the CL program and runs a DLPAR add operation to add the specified IO slot to the target i5/OS partition. The program checks the exit status of the HMC command to determine if the command succeeded. If run in batch, the standard out from the HMC is directed to a spooled file for the job. For more complex operations, it may be easier to wrapper the HMC commands in a QSHELL script and run the script from the CL program.

Example Call:

CALL PGM(HMCCL) PARM(
‘chhwres -r io -m CS6520 -o a -p RCHASCS6B -l 2102000A ‘
‘9.5.32.12 ‘ ‘ddilling2 ‘ ‘/ddilling/.ssh/id_rsa ‘)

******************************************************************************/
/* HMC ssh Sample */
/* */
/* HMCCMD CHAR(122) HMC command to execute padded to 122 chars */
/* HOST CHAR(15) HMC hostname or ip address */
/* USER CHAR(10) [optional] HMC user profile name */
/* IDENTITY CHAR(48) [optional] Identity file name */
/* */
/* Parmaters map to the ssh command being run as */
/* ssh host | user@host [-i identity] hmccmd */
/* where optional parameters with values of all blanks are treated as missing.*/
/* */
/* – Requires 5733-SC1 — IBM Portable Utilities for i5/OS */
/* – Secure script execution between the i5/OS partition and the HMC */
/* must be configured for the hmc profile being used. */
/* – if PARM3 is omitted (all blanks), ssh defaults to using the i5/OS user */
/* profile the program is running under (or name specified in user config */
/* file). */
/* – PARM4 can be omitted (all blanks) if the default location for the */
/* identity file is used (/.ssh) */
/* – Assumes QOpenSys/QIBM/ProdData/SC1/OpenSSH/openssh-3.5p1/bin */
/* has been added to the path. */
/* */
/* Example (as entered in call qcmd). Verify parameters are padded to the */
/* correct length. */
/* ===> CALL PGM(HMCCL)PARM( */
/*’ls /usr/hmcrbin */
/* ‘ ‘9.5.32.12 ‘ ‘ddilling ‘ */
/*’/ddilling/.ssh/id_rsa ‘) */
/* */
/* 6/28/2005 1.4 user profile parameter */
/* 7/05/2005 1.5 bug fix */
/* 12/05/2005 1.6 -T */
/* V1.6 ddilling@us.ibm.com */
/******************************************************************************/
PGM PARM(&HMCCMD &HOST &USER &IDENTITY)
DCL VAR(&HMCCMD) TYPE(*CHAR) LEN(122)
DCL VAR(&HOST) TYPE(*CHAR) LEN(15) /*HMC host name/ip */
DCL VAR(&USER) TYPE(*CHAR) LEN(10) /*HMC userprofile */
DCL VAR(&IDENTITY) TYPE(*CHAR) LEN(48) /*Identity file */

DCL VAR(&CMD) TYPE(*CHAR) LEN(256)
DCL VAR(&USERLEN) TYPE(*INT)
DCL VAR(&X) TYPE(*INT)
/* return status parms */
DCL VAR(&BIN4) TYPE(*CHAR) LEN(4)
DCL VAR(&EXITCODED) TYPE(*DEC) LEN(8 0)
DCL VAR(&EXITCODEC) TYPE(*CHAR) LEN(8)
DCL VAR(&MSGID) TYPE(*CHAR) LEN(7)

/* Build the qshell command to execute */
/* adding the user profile as needed. */
IF (%SST(&USER 1 1) *EQ ‘ ‘) THEN(DO)
CHGVAR VAR(&CMD) VALUE(‘ssh -T ‘ *CAT &HOST)
ENDDO
ELSE DO
CHGVAR VAR(&CMD) VALUE(‘ssh ‘ *CAT &USER +
*TCAT ‘@’ *CAT &HOST)
ENDDO

/*Add identity file if needed. */
IF (%SST(&IDENTITY 1 1) *NE ‘ ‘) THEN(DO)
/* Add the -i option to specify the identity file name */
/* Ex: -i /ddilling/.ssh/id_rsa */
CHGVAR VAR(&CMD) VALUE(&CMD *TCAT +
‘ -i ‘ *CAT &IDENTITY )
ENDDO
/*Append the command */
CHGVAR VAR(&CMD) VALUE(&CMD *TCAT +
‘ “‘ *CAT &HMCCMD *CAT ‘”‘ )

/* execute the command */
QSH CMD(&CMD)
MONMSG MSGID(CPF9999) EXEC(DO)
UNKNOWN:
SNDPGMMSG MSG(‘Unable to execute the ssh command. +
Review joblog for details.’)
GOTO EXIT
ENDDO

/* Check the status code */
RCVMSG MSGTYPE(*COMP) RMV(*NO) MSGDTA(&BIN4) +
MSGID(&MSGID)
CHGVAR VAR(&EXITCODED) VALUE(%BINARY(&BIN4))
CHGVAR VAR(&EXITCODEC) VALUE(&EXITCODED)
/* 0 is command worked */
IF COND(&EXITCODED=0) THEN(DO)
SNDPGMMSG MSG(‘HMC command executed successfully, exit +
code 0′)
ENDDO
/* 1 is command execution failed */
/* 2 is command syntax error */
/* 255 Unable to connect */
/* ELSE CMD(IF COND(&EXITCODD=1) THEN(DO */
ELSE CMD(DO)
SNDPGMMSG MSG(‘HMC command was executed but failed +
with a non-zero exit code of ‘ *CAT +
&EXITCODEC *CAT ‘. View stdout for details’)
ENDDO

EXIT:
ENDPGM