Getting Started with SSH for IBM i

SSH for IBM iSecure 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.

SSH Setup

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 ENDTCPSVR *SSHD.

Choosing an SSH client program

We recommend the ssh program from the popular OpenSSH package.

  • macOS and Linux: OpenSSH’s ssh program is included in the built-in terminal.
  • Windows: Since fall 2018, Windows 10 has included OpenSSH, available as ssh via 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 ssh from 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:

ssh user@ibmihostname

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

ssh alans@ibmi.contoso.com

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 QP2TERM or 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.

You’re in!

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 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.

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:

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 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.

ACS SSH port setup

ACS SSH port setup

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.

 

3 replies
  1. Anand Khekale
    Anand Khekale says:

    Excellent article! Aptly encourages the use of SSH over QSH/QP2TERM.

    If you change your default shell to bash, you have many advantages of retrieving/searching your commands and use keyboard shortcuts.
    Endless possibilities.

    Great work! Thanks for sharing.

    Reply

Leave a Reply

Want to join the discussion?
Feel free to contribute!

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.