How to Configure and Use SSH on IBM i

A Secure Shell (SSH) command line provides the best PASE environment for installing, managing, and running open source software.

This article explains how to set up SSH on IBM i. Navigate to a specific part of the setup process using these quick links:

• SSH Setup
  •   Ensuring you have the SSH server running
  •   Choosing an SSH client
  •   Connecting to your IBM i system using PuTTY or OpenSSH
  •   Trusting on first login
• Setting up private keys (recommended) using PuTTY or Open SSH
  •   Placing the public key on your IBM i
• Further SSH server configuration (advanced)
• Why SSH?
• Using QP2TERM as a Fallback

SSH Setup

Ensuring you have the SSH server running

Where to get SSH server: SSH, SFTP, and related programs are provided by the 5733-SC1 Licensed Program Product. SC1 is usually installed as part of the operating system.

If you don’t have the SC1 LPP, you can get it from IBM.

Is SSH server running? NETSTAT *CNN will show activity on port 22 or whatever port you have configured. Furthermore,WRKACTJOB should show jobs running function PGM-sshd

Starting SSH server: Type STRTCPSVR *SSHD

Ending SSH server: Type ENDTCPSVR *SSHD

To start SSH automatically on IPL (system restart): CHGTCPSVR *SSHD AUTOSTART(*YES)

Choosing an SSH client

We recommend OpenSSH.

• macOS and Linux: OpenSSH is included – just open a terminal and type ssh.
• Windows: Since fall 2018, Windows 10 has included OpenSSH, available via the command prompt and the ssh command. If you don’t have OpenSSH or prefer not to use it, we recommend PuTTY.
• IBM i as SSH client (for example, copying from one IBM i to another): SC1 provides the OpenSSH client. Runsshfrom any PASE-enabled terminal, such as QP2TERM, QSH, or another open SSH session.

Long user profiles: If you get an error such as “access denied,” and your user profile is more than 8 characters long, you will need to set PASE_USRGRP_LIMITED=N in the SSH config file. Please find instructions under Further SSH server configuration (advanced) later in this article.

Connecting to your IBM i system

An easy way to launch your SSH client is by clicking the “SSH Terminal” option from Access Client Solutions (ACS). This option will launch an SSH client with settings to connect to your IBM i server.

If the ACS “SSH Terminal” link does not work for you, you can open an SSH session manually using your chosen SSH client.

PuTTY (Windows systems without OpenSSH)

PuTTY main window

When you have the PuTTY main window open, make sure the session type is set to SSH, then enter user@ibmihostname in the Host Name box. For example, if your system was called ibmi.example.com (or an IPv4/v6 address), and your user was alans, you would enter alans@ibmi.example.com. If you didn’t enter a username, PuTTY will prompt you for one when you connect. Click Open, enter your password, and you’ll be logged in.

OpenSSH (Mac, Linux, updated Windows 10, or IBM i)

From a terminal/command prompt, enter the following command:

ssh user@ibmihostname

For example, if your system was called example.com (or an IPv4/v6 address), and your user was alans, you would enter:

ssh alans@example.com

If you didn’t enter a username, OpenSSH will default to the same username you use on your own computer. Enter your password, and you’ll be logged in.

Trusting on first login

When connecting to a host through SSH for the first time, you might get a message like this:

$ ssh 10.12.0.1
The authenticity of host '10.12.0.1 (10.12.0.1)' can't be established.
ECDSA key fingerprint is SHA256:3GeQFLWbHYoyG2t9RkwicsN1ywoWmg5l+MCWL+We+6I.
Are you sure you want to continue connecting (yes/no/[fingerprint])?

PuTTY trust on first use dialog

SSH employs a “trust on first use” model. When you enter “yes” here, SSH will remember the host’s fingerprint and keep trusting it. If the host’s fingerprint changes, SSH will warn you and refuse to connect, in case the server is an impostor.

If you are not sure whether to trust the address you were given, you can run ssh localhost (since SC1 uses OpenSSH) on the IBM i from QP2TERM or QSHELL and make sure the fingerprint matches. Alternatively, if you’re using OpenSSH from another system, you can use the -v flag and look for the “Server host key” line.

Setting up private keys (recommended)

SSH keys provide a convenient and secure way to log in without passwords. Key files contain more data than a password, so they are harder to crack. If you have the key file, you can log on. For password-protected keys, a program on your computer called the agent will remember the passphrase for you for a period of time so you don’t have to retype it every time to log in.

The key is in two parts: the private key, kept on the client systems you want to log in from, and the public key, copied to the users on server systems you want to log in as. The private key should be kept secret since losing it can be a security issue, but the public key can be distributed as needed.

PuTTY

PuTTYgen

Run the PuTTYgen program that comes with PuTTY. Generate a new key. Save the private key somewhere you can find it, and copy the OpenSSH public key; this is the public key that gets put on your IBM i.

PuTTY auth section

PuTTY can be told to use the SSH key under SSH->Auth in the session settings, or you can use the PuTTY agent, Pageant. Start Pageant and add your private key, and PuTTY will automatically use it.

Note for ACS users: ACS takes an OpenSSH format key. You can export an OpenSSH compatible private key for use with ACS from the “Conversions” menu. When using keys with ACS, use that file instead of the PPK file.

OpenSSH

If you don’t have any keys already, run ssh-keygen on your PC. Keys are placed in the .ssh directory in your home folder; the .pub file is the public key that gets put on your IBM i.

The private key gets used automatically, and most systems will automatically start the agent as needed.

Placing the public key on your IBM i

Public keys get put in the .ssh/authorized_keys file in your home directory (stored as UTF-8 text). This file doesn’t exist by default, so it must be created. Each public key gets its own line, so you can use multiple keys. You can use whatever text editor you prefer to insert them. If you used ssh-keygen, the contents of the .pub file can be copied and pasted as a line in the authorized keys file. If you used PuTTYgen, the top of the window has the line to copy and paste into the authorized keys file.

The key, the .ssh folder, and your home directory must be exclusively under your control to prevent snooping/tampering; this means that your home directory and .ssh under it must be chmod 700/*RWX and authorized_keys has chmod 600/*RW for yourself with no other users having permission.

Alternatively, if you’re using OpenSSH on the client system, then you can just run ssh-copy-id. It’ll do the work to copy the public keys from your computer to the IBM i for you.

Further SSH server configuration (advanced)

The SSH server is configured using a file called sshd_config, this is usually at /QOpenSys/QIBM/ProdData/SC1/OpenSSH/etc/sshd_config. (If you aren’t certain, running sshd -ddt will cause SSH to make sure the server configuration works and to log where it is.) This is a standard OpenSSH server configuration file, so advice for other operating systems generally applies.

For IBM i older than 7.4: If your user profile is more than 8 characters long, you will need to edit sshd_config. In that case, add this line:

ibmpaseforienv PASE_USRGRP_LIMITED=N

Other reasons to edit sshd_config: disabling QSECOFR login over SSH, disabling password authentication (to mandate keys), changing the port number SSH listens on (be sure to change your PuTTY/OpenSSH command settings to match), etc.

To apply your changes, end and then start the SSH server.

ENDTCPSVR SERVER(*SSHD)
STRTCPSVR SERVER(*SSHD)

When you change the SSH port

If you changed the port that the SSH server runs on, you need to configure client software with the new port.

If using ACS, go to “System Configurations” and edit the connection you’re using. On the “Connection” tab, find the “Ports” setting for SSH Connections and change the port number. If you do not see “Ports,” please upgrade your installation of ACS.

ACS SSH port setup

If using PuTTY, change the port number in the setup window before you connect.

PuTTY main window

If using OpenSSH, use the “-p” flag for “ssh” and “-P” for SCP/SFTP. For example, if you changed the SSH server to listen to port 1234:

ssh -p 1234 user@host
sftp -P 1234 user@host
scp -P 1234 file1 user@host:file1

APPENDIX 1: Why SSH?

SSH (and to a lesser extent, QP2TERM) has many advantages over QSHELL or similar for PASE:

• Multi-threaded programs will work out of the box without having to set any environment variables. Multi-threading on some programs is mandatory, so using an environment with it set up already can reduce confusion. (also QP2TERM)
• All shell commands will be real Unix ones, not the ersatz QSHELL imitations on the ILE; they operate on ASCII data as expected without conversions or defaulting to EBCDIC. (also QP2TERM)
• Unix programs expect a character terminal, not a 5250 emulating a dumb terminal for the sake of Unix programs. Programs that draw on the screen like Midnight Commander or text editors will work as expected. Control characters work as expected.
• It provides secure communications without TLS, enables SFTP (secure file transfer protocol), and other programs like rsync (file sync) and Git to use it as a transport protocol.

APPENDIX 2: Using QP2TERM as a Fallback

QP2TERM is built into IBM i. You can start it from 5250 by running CALL QP2TERM. It will drop you into the default PASE shell.

Because QP2TERM doesn’t provide as superior an experience for PASE as SSH and a terminal suited for it, we don’t recommend using it. However, it can work in a pinch if for some reason SSH can’t be used. It’s also worth noting that unlike QP2SHELL and many other ways to start PASE from non-PASE programs, QP2TERMautomatically supports multi-threading.

Edited: Thanks to Kevin Adler for pointing out some additional tricks.