Note: This Guide applies to TouchTerm 2.1.

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

TouchTerm 2.1 Guide

What's New in Update 2.1 | 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: Terminal | Settings: Display | Settings: Security | SSH Key Manager | Working with History

What's New in Update 2.1

• Full-Screen terminal usage and UI Transparency control: see the Terminal Settings section.
• Two new overlay keyboards: one for "Control Keys" (including Ctrl, Alt, Tab, Esc, Return, and a Control-C shortcut); and one for Function keys F1-F12. See the Command Keys section.
• Unicode support: international characters using the UTF-8 encoding are now properly displayed and transmitted. Note that some shells will require proper environment setup (e.g., the LANG and LC_* environment variables) in order for UTF-8 encoding to work.

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. Note that you can also edit a Connection Profile by tapping on the blue disclosure button (even when not in "Edit" mode).

Tapping a row in Edit mode (or tapping the blue disclosure button) 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 overlay keyboards that can be displayed or hidden using buttons in the toolbar. Note that the keyboards can have their transparency adjusted using the "UI Transparency" setting -- see below.

Tapping the "Ctrl..." button alternately shows or hides the "Control Keys" keyboard.

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.

The "Alt" button functions in the same way as the Control key, and is used to send Alt (Meta) character chords.

Note that the "Tab" (Tab key), "Esc" (Escape key), "Ret" (Return key), and "^C" (Control-C, or Break) keys send their corresponding keystrokes to the sever immediately -- even in Auto-Return Mode or Batch Mode.

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

The "Fn" Toolbar button is used to display or hide the Function Keys keyboard. Use this keyboard to transmit the F1-F12 keys to the server.

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.

Finally, there is the "Allow Scrollback" setting, which 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.

Settings: Terminal

This section provides control over the main Terminal screen interface. Different users will have very different preferences when using these options; our goal has been to make things as configurable as possible, so that you can use TouchTerm in the way that most suits you.

The first setting is "Full Screen Mode". Turning on the Full-Screen Mode setting has two consequences: first, the device Status Bar is hidden (this is the area on the top of the screen which usually shows the time, battery level, connection status, etc); and second, the Toolbar becomes affected by the "UI Transparency" setting (see below), so that output content can be displayed behind the Toolbar. This provides the entire device screen for viewing terminal output. Below is an example of Full-Screen Mode.

The "Translucent KB" setting controls whether the keyboard is affected by the "UI Transparency" setting. When "Off", the keyboard behaves like it usually does in other applications. When "On", the keyboard becomes translucent, and Terminal output is displayed behind the keyboard. This allows Full-Screen terminal usage even when typing.

The "UI Transparency" slider allows detailed control over the level of transparency of overlaid interface elements. This always affects the transparency of the Arrow, Control, and Function keyboads. When Full-Screen Mode is set, this also controls the transparency of the top Toolbar; and when Translucent KB is on, this also affects the transparency of the keyboard. For illustration, we've included screenshots with the UI Transparency set to its highest and lowest levels:

Note that when the UI Transparency is set to a sufficiently low value, terminal output will not be displayed behind the Toolbar or Keyboard. So, if you prefer using non-transparent interface elements with the extra real estate offered by removing the Status Bar, then turn Full-Screen mode on and set the UI Transparency to the minimum.

Note: we've done lots of testing, and we think we've come up with a good start for taking advantage of transparency in the iPhone interface. But we'd definitely like to hear your feedback: for example, if you'd like more flexibility in controlling the transparency of different interface elements independently; and of course, if you have other suggestions or requests! Please don't hesitate to contact us.

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: Display

This section controls display settings: specifically, the font size, text color, background color, and cursor color can 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.

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