Getting started with SSH under OS/2

This document provides information on how to setup and use SSH under OS/2 ssh to access remote hosts in a secure manner. The document is based on Getting started with SSH by Kimmo Suominen <>


Why SSH ?

SSH offers a method for secure communication in an insecure network. It offers solutions for several common problems in an insecure environment; the most prominent being the authentication process itself and the secure transfer of data.

SSH uses (slow) public key encryption for authentication purposes and one of several (faster) symmetrical encryption methods to encrypt the data stream between your system and the remote systems.

Thus you can use SSH to work over the (insecure) Internet, for example, to log in to your work from home or from a hotel room using about just any Internet provider available. Using the appropriate configuration, you can run telnet, run X Window applications, or read you mail - this all in a secure way since all data traveling from your local machine to the remote machine running the sshd process is encrypted end-to-end.

Installing SSH under OS/2

Get the zip package containing the executables for SSH under OS/2. The most recent version available is 1.2.16 and can be retrieved from my home page as (about 600 KByte).

The file ssh-os2-bin-1.2.16.sig contains the PGP signature for this file. The PGP signature is made with my PGP key (key ID 6223DE0D, H. Michael Stahl <>), see my home page for information on how to obtain my public PGP key.

This zip package contains all executables for SSH, the description you are currently reading, and the manual pages for all distributed programs as HTML files. Unzip it in a directory of your choice and move all executables to a directory on your PATH, preferrably where all other TCP/IP applications are stored (normally this is x:\TCPIP\BIN, where x: is your boot drive).

You also need the emx run time library ddls which you can download from e.g.

Optionally, you might want to get a syslog daemon so that sshd can write its messages to a central log file. If your OS/2 has the DHCP software installed you already have a syslog daemon as part of this software (DHCP is a standard component under Warp 4 and also part ot the more recent TCP/IP CSDs for Warp 3). Alternatively, you can get a complete syslog package containing a syslog daemon ported by Jochen Friedrich <> as (syslog.h and syslog.c are part of this package).

Setting up the working environment

Like many other programs ported from Unix also the SSH programs require some environment variables to be defined. The most comfortable way to define these variables is to add the appropriate set commands into the file config.sys:
Your user name; e.g. set user=mike
The hostname of your OS/2 system (usually already setup by the TCP/IP installation); e.g. set
Your home directory; e.g. set home=d:\mike. The ssh programs will create a subdirectory .ssh in your home directory and store a number of files in this subdirectory.
Defines to the remote system the kind of (emulated) terminal you use to log in; e.g. set term=vt220. Note that ssh comes with a built-in VT220 emulation (copyright by Robert Muchsel, <>).
A directory with TCP/IP configuration files (usually already setup by the TCP/IP installation); set etc=d:\mptn\etc

Using ssh-keygen to create a pair of keys

The very first step after installation is to use ssh-keygen to create the pair of authentication keys for yourself. In most cases the defaults for this command are what you want.

To protect your private key it is encrypted using a a so-called pass phrase before it is stored in the file %HOME%/.ssh/identity. This will prevent other people from abusing it even if they gain access to your files. Therefore always type in pass phrase when prompted for one. It can consist of multiple words (i.e. blanks are just fine within the phrase), so you could choose a sentence which you can remember. Changing some of the words by misspelling them or by changing some of the letters into digits is highly recommended to increase the strength of your pass phrase.

Here is a sample session, your input is shown underlined. Note that the pass phrase - though being shown here - is not echoed back as you type it.

   [D:\mike] ssh-keygen 
   Initializing random number generator... 
   Generating p:  .++ (distance 6) 
   Generating q:  ........++ (distance 110) 
   Computing the keys... 
   Testing the keys... 
   Key generation complete. 
   Enter file in which to save the key ($HOME/.ssh/identity): [RETURN] 
   Enter passphrase (empty for no passphrase): litt1e 1amp jumb3d 
   Enter same passphrase again: litt1e 1amp jumb3d 
   Your identification has been saved in D:/mike/.ssh/identity. 
   Your public key is: 
   1024 37 [lots of numbers] 
   Your public key has been saved in D:/mike/.ssh/ 
The comment at the end of the output of the public key which looks like a mail address (here is composed of the values found in the environment variables USER and HOSTNAME. It is transferred to the remote system when you log in using SSH and is used to find a matching public key on that system.

If you have multiple accounts you might want to create a separate key on each of them. For example, you might have separate keys for

This allows you to limit access between these organizations, e.g. not allowing the university account to access the ISP account or the machines in the office. This enhances the overall security in the case any of the authentication keys should be compromised for some reason.

Changing your pass phrase

You can at any time change the pass phrase using the -p option of ssh-keygen.
   [D:\mike] ssh-keygen -p 
   Enter file in which the key is ($HOME/.ssh/identity): [RETURN] 
   Enter old passphrase: litt1e 1amp jumb3d 
   Key has comment '' 
   Enter new passphrase (empty for no passphrase): br0wn cow 3ats grass 
   Enter same passphrase again: br0wn cow 3ats grass 
   Your identification has been saved with the new passphrase. 
The pass phrases are not echoed as you type them.

Accessing remote systems

Authorizing access on remote systems

To allow access to a remote system for a given identity you must transfer your public key from your local OS/2 system to the remote (Unix) system and place it in your ~/.ssh/authorized_keys file on that system. All keys listed in that file are allowed access.
   remote% cd ~/.ssh 
   remote% cat >> authorized_keys      
You could now copy the ~/.ssh/authorized_keys file to other systems to allow access from the OS/2 system. One way to copy the file is to use the ftp command.

Use a text editor to add more keys to the file. If you use cut and paste to copy a key make sure each key entry is a single line in the file. The keys to add are always the public keys (from files with the .pub extension).

NOTE: To gain access to restricted systems you might need to send your public key in an electronic mail message to the administrator of that system. Just include the contents of the %HOME%/.ssh/ file in the message.

Using ssh to log in to remote systems

To establish an interactive connection to a remote system you use the ssh command. The only parameter is the host name of the remote system. As always, the pass phrase is not echoed back to you when you type it.
   [d:\mike] ssh
   Enter passphrase for RSA key '': litt1e 1amp jumb3d 
   Last login: Wed Oct 16 20:37:00 1996 from
   [more output from the remote machine]
You can avoid to type in the pass phrase for each session you start on the remote system if you use ssh-agent to keep the authentication keys in memory. You need to type the pass-phrase only once when you use ssh-add to add a key to memory.

If your account name on the remote system differs from the one on the local system (the system you are connecting from) you can use the -l switch to specify the remote account name.

   [d:\mike] ssh -l Maik 
   Enter passphrase for RSA key '': litt1e 1amp jumb3d 
   Last login: Wed Oct 16 20:37:00 1996 from 
   [more output from the remote machine]

Running commands on remote systems

The ssh command can also be used to run commands on remote systems without logging in. The output of the command is displayed and control returns to the local system. Here is an example which will display all the users logged in on the remote system.
   [d:\mike] ssh who
   christos ttyp8    Oct 17 20:42  (milou)
If you are using the X Window System you can use this feature to start an interactive session on the remote system:
   [d:\mike] ssh -n xterm 
A new X terminal window from the remote system should appear shortly on your display. Note that the OS/2 session you started ssh in will not be usable for further command input as long as ssh is running.

Using SCP to copy files between systems

You can copy files from the local system to a remote system or vice versa, or even between two remote systems using the scp command. To specify a file on a remote system simply prefix it with the name of the remote host followed by a colon.

If you leave off the filename of the copy or specify a directory only the name of the source file will be used. An easy way of retrieving a copy of a remote file into the current directory while keeping the name of the source file is to use a single dot as the destination.

   [d:\mike] scp -p remote:aliases .
The -p option is not required. It indicates that the modification and access times as well as modes of the source file should be preserved on the copy. This is usually desirable.

You can copy several files in a single command if the destination is a directory.

   [d:\mike] scp -p remote:.login remote:.logout
Relative filenames resolve differently on the local system than on the remote system. On the local system the current directory is assumed (as usual with all commands). On the remote system the command runs in the home directory! Thus relative filenames will be relative to the home directory of the remote account.

NOTE: When you specify remote machines in both the source and the destination the connection to copy the files is made directly between those hosts. The files are not copied through the local system. Sometimes this makes a difference in a firewalled or otherwise restricted environment.

Keeping authentication keys in memory

If you frequently open connections to remote systems you can run your session under the ssh-agent. The agent will provide decrypted authentication keys to all the commands when new connections are created.

Starting the authentication agent ssh-agent

When you start ssh-agent you need to provide a command to spawn. This is usually the OS/2 command interpreter (CMD or 4OS2).
   [d:\mike] ssh-agent cmd 
   OS/2 Command Interpreter Version 3

When you exit from this command interpreter all keys will be removed from memory:
   [d:\mike] exit
   Authentication agent exiting.


Using ssh-add to manage keys in memory

Before your connections can be authenticated without prompts for a pass phrase you have to use ssh-add to add the necessary keys to memory. To add the default key on the current system to memory no options are needed. The pass-phrase is prompted for to decrypt the key. It is not echoed back as you type it.
   [d:\mike] ssh-add
   Need passphrase for d:/mike/.ssh/identity (
   Enter passphrase: litt1e 1amp jumb3d
   Identity added: d:/mike/.ssh/identity (
You can specify the file that contains the key if you want to add an identity other than the default. You must specify the file with the private key i.e. the one that does not have the .pub extension.

The -d option will have the key deleted from memory. There is no ssh-delete command.

   [d:\mike] ssh-add -d %HOME%/.ssh/isp
To list all keys currently in memory use the -l option.
   [d:\mike] ssh-add -l
   1024 37 [lots of numbers]
You can delete all keys from memory at once with the -D option.
   [d:\mike] ssh-add -D
   All identities removed.
This is useful if you have added keys into memory on remote systems and don't want to reconnect just to delete the keys.

Changing default settings

The defaults for the ssh-related commands can be altered for each account in a configuration file %HOME%/.ssh/config (there is also a system-wide file, usually x:/mptn/etc/ssh_config). Each entry starts with a Host keyword. You can use wildcards to match all the appropriate systems: Usual keywords include (defaults in parenthesis):
Compression yes/no (no)
Controls whether compression is used on the connection.
CompressionLevel 1-9 (6)
Level of compression: 1 is fastest, 9 is slowest (achieves best compression). Compression is good for slow links (saves bandwidth) and fast machines.
FallBackToRsh yes/no (yes)
If a secure connection to the remote system cannot be established the commands can try unsecure connections (a warning will be displayed if this happens). On highly secure systems this could be disabled in the system-wide configuration.
KeepAlive yes/no (yes)
Controls whether TCP keepalive messages are used. When enabled it is possible to detect network outages and automatically close your connections (which is good). However, if you are connected over a dialup link that automatically dials when there is traffic, you will want to turn this off to avoid unnecessarily bringing up the line.
User account (local account)
Specify the remote account name. Add this to avoid having to use the -l option when issuing commands.
Here is an example %HOME%/.ssh/config file.
	Host *
	  User mike
	  Compression no

	Host mailhost
          # Forward POP (110) and SMTP (25) to target host
          LocalForward 110
          LocalForward 25

	Host *
	  FallBackToRsh no

	Host *
	  Compression yes
	  CompressionLevel 9
	  FallBackToRsh yes
	  KeepAlive no
Options are accumulated over entries, but a more specific entry will override a less specific one. E.g. in the above compression will not be used for hosts that match * but will be used for hosts that match * (and all other hosts since the * entry matches all hosts).

This example also shows how to use LocalForward to forward the ports 110 (POP) and 25 (SMTP) from the remote host to the local host. If we specify localhost:110 and localhost:25 for the POP and SMTP host:port combination when setting up our local POP mail client, we can read and write our mail in a secure way - since it will be tunneled through SSH's encrypted comunication channel.

For a complete list of options please refer to the manual pages of both ssh and sshd.

Using the SSH server sshd under OS/2

The binary distribution also contains sshd, the SHH server process for OS/2. This is more meant for testing SSH but you can also use it to provide secure access to your OS/2 machine. However, only use it yourself: since there is no user identity based file protection under OS/2 whoever has access to your system - be with SSH or without - can read all files and the security of your system will be compromised immediately.

How to generate SSH for OS/2

Required base

My adaptation of SSH to OS/2 is based on the following software which you need to obtain first:


I adapted the following files of the 1.2.16 distribution of ssh:
All changes are bracketed by #ifdef OS2 and #endif /* OS2 */. (If I could convince the authors of ssh to incorporate the changes into the sources one would have less work adapting to the next source distributions.)

I had to change the makefiles by hand since I do not have all components to run the configure script supplied with the ssh distribution.

I also added the following files taken from other sources:
The files syslog.h and syslog.c are part of the
syslog package by Jochen Friedrich <>.

The VT220 emulator contained in vt220.h and vt220.c was written by Robert Muchsel <>) and are part of a previous port of ssh to OS/2 which can be found e.g. as
Obtaining the changed source files You can get the changed source file from here:

  1. zip file with ssh sources for OS/2 (130 K; only contains my changes)
  2. ssh-os2-src-1.2.16.sig contains the PGP signature for this file
The PGP signature is made with my PGP key (key ID 6223DE0D, H. Michael Stahl <>), see my home page for information on how to obtain my public PGP key.

How to regenerate

If you want to regenerate the software using for example a newer version of the ssh distribution you probably have to redo the changes to the sourcefiles and edit the makefiles :-(

To regenerate the library libgmp.a, change directory to gmp-2.0.2\mpn, copy all assembler file from x86 and all C files from generic. Then delete all copied C files which have an assembler counterpart. Copy bsd.h to sysdep.h . Edit Makefile and add -D__STDC__ to CDEFS. Then run make in the subdirectories mpn, mpf, mpq and mpz. Finally do a

   ar rc libgmp.a mpn/*.o mpf/*.o mpq/*.o mpz/*.o *.o
to generate the library.

Regeneration fo library libz.a is a bit easier: change directory to zlib-1.0.3, edit the Makefile, set CC to gcc, and then run make.

Once the libraries exist the rest is easy: run make in the main directory and all components will be generated.

Sources of more information

Last edited on 13 January 1997 by