IBM Support

Sending HMC Commands from a CL Program

Technote (troubleshooting)


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 or from a program. This document provides a sample CL program that can be used to submit HMC commands and check if they run successfully.

Resolving the problem

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:

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:

New, OpenSSH PTF List for V5R3:

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):


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

wrklnk <HOMEDIR value>

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 <hmc host name>

where <hmc host name> 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 <user>@<hmc host name>

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 (' 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 <home>/.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/
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 <filename>

where <filename> is the public key file name ( 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 file. Do not include any extra carriage return, line feed or space. See the example below.
a To obtain additional command input lines in the shell (needed for longer keys), type the number of desired lines on the command line (for example type 10) then press F14 (Shift+F2).
b 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
c 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
d 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 <user@hostname>

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?                                                  

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')

Qshell redirection can be used to pipe output to a file; for example:
QSH CMD('ssh -Tn ddilling@cs6hmcb "lshmcusr" >/tmp/output.txt')

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:

'chhwres -r io -m CS6520 -o a -p RCHASCS6B -l 2102000A '
' ' '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 (<homedir>/.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                                                            */
/*                                           ' '      ' '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                                          */
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)                              
   ELSE DO                                                                      
      CHGVAR VAR(&CMD) VALUE('ssh ' *CAT &USER +                                
         *TCAT '@' *CAT &HOST)                                                  
   /*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 )                                                
   /*Append the command  */                                                    
   CHGVAR VAR(&CMD) VALUE(&CMD *TCAT  +                                        
           ' "' *CAT &HMCCMD *CAT '"' )                                        
   /* execute the command */                                                    
   QSH        CMD(&CMD)                                                        
   MONMSG     MSGID(CPF9999)  EXEC(DO)                                          
      SNDPGMMSG  MSG('Unable to execute the ssh command.  +                    
                Review joblog for details.')                                    
      GOTO EXIT                                                                
   /* Check the status code */                                                  
   RCVMSG     MSGTYPE(*COMP) RMV(*NO) MSGDTA(&BIN4) +                          
   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')                                              
   /* 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')            

Historical Number


Document information

More support for: Server Firmware, HMC and SDMC

Software version: 5.3.0, 5.3.5, 5.4.0, 5.4.5, 6.1.0, 6.1.1

Operating system(s): IBM i

Reference #: N1019126

Modified date: 18 July 2012

Translate this page: