Note: This Guide applies to TouchTerm 2.0.

Click here for the Guide for the current version of TouchTerm.

TouchTerm 2.0 Guide

Connections Screen | Connection Profile screen | Terminal Screen | Entering Commands: Immediate Mode | Entering Commands: Auto-Return Mode | Entering Commands: Batch Mode | Using Command Keys | Clearing the Display | Settings: Text Entry | Settings: Display | Settings: Security | SSH Key Manager | Working with History

Connections Screen

This is the TouchTerm "Home" Screen. The top "Quick Connect" section gives you fast access to the last server that you connected to, or allows you to do a "One-Time Connection" (in case you want to connect to a server but not save a Profile for it).

Below this are your "Saved Connections": simply tap any item to connect to the indicated server.

In order to manage your Connection Profiles, use the two buttons in the toolbar at the top of the screen. The "+" button in the upper right allows you to add a new Connection Profile. Tap this to bring up the Profile Details screen for making a new connection.

The "Edit" button allows you to change any details associated with a Connection Profile, or to delete Connection Profiles.

Tapping a row in Edit mode will bring up the details for the selected profile and allow you to change them.

Connection Profile screen

Use this screen to edit the connection details for new Connection Profiles, or when editing an existing Connection Profile. Enter the server, port, and username in the Connection Details section.

In the Authentication section, you can choose a password for this connection; or, leave it blank if you do not wish to have your password saved. You can also choose an SSH Key to use for this profile; see the "SSH Key Manager" section below for more details about using SSH Keys. Note that passwords can only be stored if you have "Save Passwords" turned on in Settings.

If you've made a connection to this server before, the server's public key fingerprint will be available in the last section.

Terminal Screen

After a successful connection, a new terminal window will come up displaying your shell prompt.

Note that this is a fixed-width window (80 columns), and that it is not restricted to the edges of the device screen. Scroll left and right to reveal different screen areas. For better readability, rotate the device into landscape mode. Or, adjust the Font Size (in Settings) to a smaller font in order to fit more content within the screen boundaries:

The standard pinch zoom gestures are supported in the terminal window. The zoom out is limited by the Font Size; however, if you want to fit more text on to your screen, go to the Settings screen (upper-right button) and lower the font size.

Entering Commands: Immediate Mode

TouchTerm has several ways to communicate with the server. The default mode for entering text is "Immediate Mode". In Immediate ("Raw") Mode, TouchTerm operates in the same way as standard terminal programs: every keypress that you issue is immediately sent to the server. In order to send keystrokes, simply tap once on the terminal output window, which will bring up the keyboard display. As you type keys, you will see that they are sent directly to the server and the output is updated appropriately.

Immediate Mode is most useful when using interactive programs, such as emacs or vi. Some users may even prefer to use Immediate Mode for all tasks.

Entering Commands: Auto-Return Mode

When not in Immediate ("raw") mode, text can be entered one line at a time ("cooked" mode). To enter a command, first tap on the command box that appears directly below the button bar. (Note that you can tap once anywhere on the output window to show and hide the command box.)

The keyboard will raise, allowing you to enter a command into the command box. Note that as you type, nothing is sent to the server. When you tap "return", the entire contents of the command box are sent to the server. When "Auto-Return Mode" is on, this will automatically include a newline character (i.e., the equivalent of hitting the "return" key on a standard keyboard).

This mode is most useful when using the command-line directly. You can enter each command in full, and correct mistakes locally, before sending the command to the server. Also, Auto-Return Mode enables the use of the command history, which allows you to re-issue and/or correct recently issued commands. (See below for more details on using the command history.)

If you just want to send a single newline character without any text, tap the return key when the command box is empty.

If you want to hide the keyboard in order to see more of the output display, simply tap once anywhere on the terminal output window. Once the keyboard is hidden, you can again tap once on the terminal window to hide or show the command box.

Entering Commands: Batch Mode

Another ("cooked") alternative to Immediate Mode is "Batch Mode". To enable this, tap the Settings button (rightmost on the toolbar) and set both Auto-Return Mode and Immediate Mode to "OFF". Batch Mode is similar to Auto-Return Mode: you type characters into the command box, and when you are finished you tap "return" to send those characters to the server. However, in Batch Mode, a newline character is NOT automatically added: just the characters that you typed are sent.

This is most often useful when interacting with programs that do not expect a return key, or for using tab completion and other shell features. For example: to use tab completion in Batch Mode, you would enter a partial command into the command box, tap "return", and then tap the Tab button.

In Batch Mode, if you need to enter a single newline character, you can do so by tapping "return" when the command box is empty.

Note that because partial commands will often be entered, the command history is not updated in Batch Mode.

Using Command Keys

TouchTerm supports the most commonly used special characters, using the buttons in the toolbar. Note that the "Tab" and "Esc" buttons always send the keystrokes immediately to the server, even in Batch Mode or Auto-Return Mode.

Tapping the "Ctrl" button initiates a Control-key command. This will raise the keyboard (if it's not visible already), and the next character pressed will be submitted as a control sequence. For example, to send a Ctrl-C (break), tap the "Ctrl" button and then tap the "C" key.

If you tap the Ctrl button and then decide you don't want to send a control character, you can tap the Ctrl button again to cancel.

TouchTerm also supports arrow (cursor) keys. To show or hide the cursor keys, tap the "Arrows" button in the toolbar -- the second button from the right. This will display the four arrow keys, overlaid on the terminal output window.

The arrow keys are translucent, so that you can see the text behind them even when they're up. Tap the "Arrows" button again to hide them.

Finally, TouchTerm also supports the backquote character "`", which is not available on the iPhone keyboard. You can enter a backquote by tapping the "dot" key: this is found on US English keyboards by tapping "?.123", then "#+=", then it's in the second row at the right side of the keyboard. (Note that this is not the same as the "period" key.)

Clearing the Display

The "Clear" button in the upper-left can be used for clearing the terminal window output buffer. TouchTerm will not clear any terminal output unless explicitly requested using this key. This way, you can scroll back up through large amounts of text, and use clear to prune it when you no longer need it.

Settings: Text Entry

From the Settings tab, TouchTerm allows you to control several attributes of the terminal display and operation. The first section allows you to configure the Immediate Mode, Auto-Return Mode, and Batch Mode as described above.

Also, here you can configure Auto-Scroll to be on or off. When Auto-Scroll is on, whenever you are typing, TouchTerm will auto-scroll the window's contents so that the cursor is visible. Of course, you can still adjust the scrolling manually while the keyboard is up. TouchTerm will not Auto-Scroll when the keyboard is not visible. If Auto-Scroll is turned off, TouchTerm will never scroll the window automatically. This is sometimes useful when using applications where the cursor jumps around.

Settings: Display

This section controls display settings. First, the "Allow Scrollback" setting determines whether or not TouchTerm displays content that is "above" the normal screen size (80x24). When Allow Scrollback is on (the default), TouchTerm displays all output that has been viewed. So, for example, if you execute a long "ls -lR" command, TouchTerm will allow you to scroll back through all of the results.

When Allow Scrollback is turned off, then only the 80x24 screen size is displayed. This is most useful when using screen-based programs like emacs and vi; in this case, scrollback is limited so that only the usable screen area is displayed.

The next settings allow the font size, text color, background color, and cursor color to be customized. Use the Font Size slider to control the default (non-zoomed) size of the output text in the terminal window. Note that this effectively sets the minimum size of the text; from the terminal window, you can use the standard pinch gestures to zoom in and magnify text.

Finally, the "Disable Sleep" setting allows you to disable the iPhone's automatic sleep function when connected to a server. This is useful if you want to make sure your connections are not interrupted by the device going to sleep when it thinks it has been idle for too long. Note that turning this on may have an impact on battery life.

Settings: Security

The Save Passwords switch controls whether or not TouchTerm allows you to store passwords in saved Connection Profiles. Note that if this is turned on, you can still choose to save passwords in only some of the Connection Profiles, but when it is off you will not be able to save passwords in any of them.

"Manage SSH Keys" allows you to create and work with SSH public-key authentication. See below for more details on working with SSH keys.

The Host Key Notification controls whether or not TouchTerm displays notifications whenever new or unknown keys are encountered when connecting to hosts. When this is enabled and you first connect to a server from your device, a dialog will be displayed, informing you of the Host Key's fingerprint:

Note that even if this is turned off, TouchTerm manages host public keys and will notify you in the case that a changed key is discovered. Also note that public key fingerprints are available for all servers that have been connected to from a saved profile, in the Connection Profile details screen.

Finally, the "Reset Host Key List" button allows you to clear TouchTerm's host key ("known hosts") database. Note that if you do this, all public keys that have been seen will be discarded. You should generally only use this if you understand the implications and have a specific need to; for example, if a server in your Connection Profile has changed its public key.

SSH Key Manager

The Key Manager is accessed via the Settings screen. On this screen, you can create new SSH keys for your device, and also remove any keys you've previously created.

Note: Public key authentication is a somewhat advanced procedure that not all users will require. If you're unsure about what key-based authentication is, or why you'd want to use it, then we recommended reading one of the many tutorials available on the internet.

Tap "Create New Key" to create a new key, or tap on any of your previously created keys to view the key details.

When creating a new key, specify a descriptive name for your key, and choose the key type and bit length. TouchTerm supports RSA (SSH Protocol 1 and 2) and DSA (SSH Protocol 2) keys. Note that DSA keys must be 1024 bits, and RSA keys can be between 768 and 4096 bits. (Also note that generation of large RSA keys make take a long time -- please be patient!)

You may optionally specify a passphrase for your new key. If you do this, whenever the key is to be used to establish a connection, TouchTerm will first require this passphrase before sending the key to the server. When you associate a key with a connection on a Connection Profile page (see above), if the "save passwords" setting is on, you can also enter its passphrase there (into the "password" field) to be saved such that when you open that particular connection you aren't prompted for the passphrase for the key. Note that there is NO way to recover a passphrase that has been associated with a key if you lose or forget it.

From the Key Manager screen, you can tap on any of the keys you've created to bring up the key details. This screen will display information about the type and bit length of the key (but not the passphrase!), as well as an action button to e-mail the public key contents. Tap this button to distribute your public key via email, either to yourself or your system administrator for installation on the server(s) you wish to connect to.

After the public key is properly installed on the remote system, you can use the Connection Profile screen to associate your saved key with a particular server (and optionally remember the passphrase). After this, TouchTerm will use your saved key to authenticate to the remote server.

Working with History

When using Auto-Return Mode, all commands (well, anything longer than two characters) are stored in the command history. To access the command history, tap the blue disclosure button to the right of the command box. This will bring up the History screen. Commands in the history are ordered with the most recent command at the top. Duplicates are only shown once at the spot where they were most recently used.

To select a history item, simply tap the corresponding row: that command will then be entered into the command box, and you will be returned to the Terminal screen. Note that TouchTerm then allows you to edit the command before sending it off to the server; this is useful for correcting typos.

The command history can be used in either Auto-Return Mode or Batch Mode. However, note that in Batch Mode, new entries are not added to the history list. Command history is not available in Immediate Mode.

One thing to note is that in Auto-Return Mode, all commands sent to the server are added to the command history -- even if they are not sent to the command-line shell. One place this might matter is for passwords: if you enter a password while in Auto-Return Mode, it will be saved in your command history. This is probably not desired; one way to work around this for now is to set TouchTerm to Immediate Mode whenever you have to enter a password. (We're planning to add more sophisticated password management to TouchTerm and TT Pro!)