TouchTerm 2.3 Guide

What's New in Update 2.3 | 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 | Settings: Advanced | TouchTerm Information | SSH Key Manager | Working with History | SSH URL Handling | Using the Application Lock

What's New in Update 2.3

• Application Lock: see the Application Lock section.
• Three Font Options, offering better readability at smaller font sizes.
• Detailed Connection Diagnostics for failed connections, including better stability when encountering unexpected connection errors.
• Ability to export public and private authentication keys: see the SSH Key Management section.
• Added menu-level navigation to make it easier to work with Settings.

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 zoom level is controlled by the Font Size, available on the Settings screen (upper-right button). Use a low value to fit lots of text, or a higher value for easier readability.

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.

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.

See the Application Lock section below for more information about configuring and using the Application Lock and working with the the App Password.

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

Advanced Settings

Use the first option to enable Persistent Connections using GNU screen. When this option is enabled, TouchTerm will attempt to use GNU screen on the remote host in order to persist terminal sessions across multiple sessions; in practice, this ends up behaving as though TouchTerm has 're-connected' to the same, pre-existing session when re-launched. Since the iPhone SDK does not currently support maintaining connections after TouchTerm has terminated, this is an effective alternative for most situations.

In order for this option to work, the remote host must have GNU screen installed and available at '/usr/bin/screen'.

Please note that due to incompatibilities between GNU screen and the VT100 standard used by TouchTerm, there may be some terminal emulation problems when using screen-based applications such as emacs and vi. We also recommend that you set the 'Allow Scrollback' option to Off when using any screen-based application with Persistent Connections enabled, as this tends to reduce errors caused by the emulation incompatibility. However, if you make frequent use of such programs, we recommend that you leave this option disabled.

Also note that any changes in this option will not take effect until the next time a new Connection is established.

The next setting controls the character encoding used when transmitting and displaying text. Note that you may need to ensure that your server's locale settings are properly configured in order this option to work properly.

The "Use SSH Protocol 1" allows you to force TouchTerm to use SSH protocol version 1 when connecting to the remote host (equivalent to the "-1" option in command-line ssh). Use this if you are having trouble connecting to an older server or network appliance.

The "Carrier Activation" allows you to disabled TouchTerm's automatic carrier activation technique. When connecting over the carrier (EDGE/3G) network, TouchTerm initiates a request to an empty web page at startup: this "activates" the carrier network, allowing subsequent connections to succeed. If you prefer to disable this behavior, you may turn off this option; note that, however you may have to manually activate the carrier network (using, eg, Safari), before TouchTerm will be able to connect.

Finally, the "Incoming Data Lock" option allows you to control TouchTerm's behavior when there is lots of incoming data. By default, TouchTerm locks the screen against drawing updates when there is a large amount data incoming. This usually helps with performance and responsiveness during high data transmission, and provides user feedback in the form of an activity spinner. However, some users may prefer to disable this option, and have TouchTerm continuously update and redraw the screen for all new incoming data. Be warned, however, that in certain situations this can require TouchTerm to do lots of screen re-drawing, and therefore become unresponsive.

TouchTerm Information

The final section in the Settings screen provides more information about TouchTerm on the web, including a link to this online help guide. There's also a link for more information about our TouchTerm Pro product, and information about the version of TouchTerm that you are using.

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.

If you access the Key Manager from within an active terminal session, you can also use the Key Detail page to export the contents your public or private keys directly into the session:

Note that these will send the key contents directly to the remote host, so be sure you are in a text editor or some other appropriate environment for receiving the key contents!

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.

Finally, it is also possible to clear the command history using the "Clear" button in the upper-right corner.

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

URL Handling

TouchTerm 2.2 adds the ability to handle "ssh://" URLs. These can be used by other apps to automatically launch TouchTerm when needing to connect to SSH sessions, or be used by creating webpage-links that will luanch TouchTerm with the indicated information.

TouchTerm supports URLs that conform to RFC 1808, of the form:

     ssh://{user@}host{:port}

In other words, you may optionally specify the username and/or the port of the server you wish to connect to. Also, instead of using a hostname, you may use a profile name for the host part of the URL, and TouchTerm will use that stored profile (if it is available).

If enough information is provided, TouchTerm will automatically initiate the connection to the indicated URL; otherwise, TouchTerm will launch into the "One-Time Connection" screen to request the other information that is required.

Finally, TouchTerm will also scan your saved connection profiles for any profile with server settings that match the indicated parameters. If a match is found, TT will use the saved profile to connect (which may include using your saved password, or associated SSH authentication key).

Using the Application Lock

The Application Lock can be configured to password-protect all access to the TouchTerm application. If enabled, the Lock screen will be displayed on startup:

The Application Lock option is available under the Security Options. In addition, there is also the Allow Password Reset option, which controls whether a "Reset" button is available from the Application Lock screen. For most situations, leaving this Option turned On is safe, and ensures that you will not have to re-install the application (and lose all of your settings!) if you forget the Application Password. On the other hand, for improved security, turn this option Off -- this will prevent any access to TT without the password.

To change the Application Lock password, use the Set App Lock Password option.