Secure Shell (SSH) provides the best environment for installing, managing, and running open source software on IBM i. Among SSH’s advantages over QSHELL and QP2TERM: IBM i’s SSH command line works just like SSH on Linux or Windows, helping the IBM i platform appeal to younger developers and admins. Supporting a wide range of Unix programs and open source software, such as
git, SSH is our go-to terminal interface for open source and PASE. This article covers how to set up SSH and use it to connect to IBM i servers.
Ensure you have the SSH server running
Where to get the 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, but it doesn’t hurt to check.
Starting and ending SSH server: If
NETSTAT *CNN does not show activity on port 22, you can start SSH with the command
STRTCPSVR *SSHD. Typing
WRKACTJOB should now show jobs running function “PGM-sshd.” To end SSH, type
Choosing an SSH client program
We recommend the
ssh program from the popular OpenSSH package.
- macOS and Linux: OpenSSH’s
sshprogram is included in the built-in terminal.
- Windows: Since fall 2018, Windows 10 has included OpenSSH, available as
sshvia the command prompt. If you don’t have OpenSSH or prefer not to use it, we recommend PuTTY; however, we cover only OpenSSH in this blog post.
- IBM i as SSH client (useful when copying files from one IBM i to another): SC1 provides the OpenSSH client. Run
sshfrom any PASE-enabled terminal, such as QP2TERM, QSH, or another open SSH session.
Connecting to your IBM i system
The easiest way to start a SSH session is with the Access Client Solutions (ACS) “SSH Terminal” option, which will launch a properly configured SSH client. If the ACS “SSH Terminal” link does not work for you, you can open an SSH session manually. From a terminal/command prompt, enter the following command:
For example, if your system were called
ibmi.contoso.com (or an IPv4/v6 address), and your user were
alans, you would enter:
If you didn’t enter a username, OpenSSH would default to the same username you used 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])?
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.
TIP: 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
QSH 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.
If you logged in successfully, you can now use PASE commands (ls, cd, cat, etc.), yum (if installed), and the full range of open source software available on your IBM i.
Advanced: Setting up private keys
SSH keys provide a convenient and secure way to log in without needing 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.
If you don’t have any keys already, run
ssh-keygen. Keys are placed in the
.ssh directory in your home folder (for example:
C:\Users\Alan on Windows,
/Users/alan on macOS,
/home/alan on Linux); 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.
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
*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.
Automatically restart the SSH server
You can get the server to start on IPL with the following CL command:
CHGTCPSVR *SSHD AUTOSTART(*YES)
Advanced: Configuring the SSH server
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 show you its location. ) 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:
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 update clients to be aware of this.
If using ACS, go to “System Configurations” and edit the connection you’re using. On the “Connection” tab, change the port being used.
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
SSH is your portal to innovation
Once you switch to SSH, you’ll find new possibilities for innovation on your IBM i, as well as attracting and retaining talent in your organization and on the platform. Use modern tools for modern applications. Get in touch if you would like to discuss training or other assistance.
Edited: Thanks to Kevin Adler for pointing out some additional tricks.