Context sensitive help is available on every screen of Internet/scripttelnet so this document describes how it works and how to use it. We suggest you try ScriptTelnet on a simple service that you know works and you understand pretty well before you use it for real.

ScriptTelnet is Telnet testing on steroids.

Many technical people know they can use telnet to interact with certain Internet services, for example HTTP (web servers), SMTP (email), POP and IMAP (PC email clients), cosign, IPP, IRC, XMPP, SIP, XML-RPC, REST/SOAP, etc. If you search for how to diagnose problems with these services, the answer often describes how to use telnet to troubleshoot.

Some of those same people know they can use openssl to interact with certain Internet services that encrypt some or all of the traffic, for example HTTPS, SMTPS, POPS and IMAPS, etc. openssl, like telnet, comes up in searches for how to diagnose SSL problems.

Using telnet or openssl to debug a remote server is very exacting. The lines you type in have to be in the correct order with no typos, and they have to be typed quickly before the remote server, which usually is talking to another computer, times out and disconnects you.

When you go to telnet to a remote server, you usually have to go lookup the command sequence, then you enter them several times as you work through your problem. Not to mention having to restart every time you type even just one letter wrong.

ScriptTelnet does telnet and openssh, and it lets you build scripts that do the typing for you, with no errors. Rather than typing everything from the beginning each time you re-run a test, the script stores your telnet/openssl typing. You change just what you want to change and re-run the whole thing.

Because ScriptTelnet does openssh, it looks inside encrypted data and shows it to you in plain text. It will send and receive binary data. See below for how to escape non-printable characters when sending, and binary data received is similarly escaped on output.

Our Templates give you an outline of the commands to use for specific services. We do the lookup of what commands to send and how to format them for you. ScriptTelnet has these templates:

SMTP(25)

Simple Internet Email

ESMTP(25)

Extended SMTP

ESMTP-TLS(25)

ESMTP with TLS

SMTPS(465)

Secure SMTP

ESMTPS(465)

Secure ESMTP

SUBMISSION(587)

SMTP alt port

ESUBMISSION(587)

ESMTP alt port

ESUBMISSION-TLS(587)

ESMTP alt port with TLS

POP3(110)

Post Office Protocol

POP3S(995)

Secure POP

IMAP(143)

Internet Message Access Protocol

IMAPS(993)

Secure IMAP

HTTP(80)

Hyper Text Transport Protocol (web server)

HTTPS(443)

Secure HTTP

We do not store your test on our servers: neither the Script nor the output. Between runs, the only place this data exists is in the browser window on your PC. Still, we recommend using test data rather than real, high security data when using ScriptTelnet. We have NO RESPONSIBILITY to protect the data in ScriptTelnet. If you use real data, you should remove it as soon as possible. Better safe than sorry.

Start a New Script

When you start a new ScriptTelnet project, it asks you to choose a Template. You can build your Script from scratch, but it's almost always easier to start with one of our frameworks. The Template becomes your Script, which you edit to point to the right remote server and to execute the right commands.

Once you select a Template, or start your Script from scratch by inserting a new Step, ScriptTelnet goes into iterative mode. Iterative mode lets you repeatedly modify your Script and run it as you learn/fix the service and the Script. Each run displays the your input and the remote service output below your Script, making it easy to repeat.

Work with a Script

Scripts are a series of Steps. Each Step defines an interaction with the remote server. A Step is one of "Send", "Read", or "Do", which respectively send a command or data to the service, read something from the service, or change something about the connection.

Steps are listed in a table on your screen:

A "Send" step sends the Data string to the service.

A "Read" step reads output from the service until it finds the string in Data, or until the TimeOut seconds have passed. Technically, the Read string is a java Regular Expression with MULTILINE turned on. For simple testing, you can skip the string (i.e. leave Data blank on the "Read" Step) and just use the TimeOut to end the read. Thirty (30) seconds usually works. Your test will take 30 seconds between Steps, but it will work.

For faster tests or where the TimeOut is not sufficient, you can enter a string (regex) into the Data field. The test will stop reading as soon as it finds that text in a line from the service (i.e. the regex matches). The string (regex) you enter does not have to be at the end of the line -- just find a unique word or string in the last line of what the service sends. Because most services return just one line per command step, oftentimes it is sufficient to use just "\n" (without the quotes) as the wait-for string. See the various Templates for examples.

The valid "Do" actions are:

StartTLS

switches the connection from plain text to SSL/TLS encryption

StartBinary

prevents ScriptTelnet from escaping non-printable characters (e.g. "\n")

EndBinary

return to displaying non-printable characters in a print-able way (e.g. "\n")

SetStepTimeOut

sets the default Read timeout (seconds) (can be overridden on a specific Read Step)

SetTestTimeOut

sets how long the whole test can take (seconds) (limited to 5 minutes)

Output

The output shows the commands your Script sent and the responses from the service. Commands and data sent from you are prefixed with "-->", and responses sent from the server are prefixed with "<--".

Raw mode

Raw mode give you more control over the exact strings that ScriptTelnet sends to the remote server. With Raw mode off (the default), ScriptTelnet ends each Send Step with "\r\n", i.e. a carriage-return decimal 13 hex 0d and a line-feed decimal 10 hex 0a. This string is the standard end-of-line for most Internet services.

With Raw mode on, you must put your own line termination character(s) in. As described below, ScriptTelnet expects binary (non-printable) characters to be escaped and will "un-escape" them before sending them.

These two lines are the same, the first is not in Raw mode and the second is in Raw mode: GET / HTTP/1.1 GET / HTTP/1.1\r\n

Special (non-printing) Characters

In both Send and Read strings, simple escape sequences are used for newlines, control characters, etc. These are "\n" for newline, "\r" for return, "\t" for tab, and "\x00" for any other non-printing character, where 00 is the hex code for the character. To send an SMTP "HELP" command, the Data would be "HELP\r\n". For example, if the service sends a control-C, it would show up in the output as "\x03". And you would match the control-C in a Read with the same string. Again see the Templates for more examples.

XML and Saving Scripts

Internally, ScriptTelnet uses XML for your Script. You can switch to XML mode and work directly with the XML, however XML is persnickety and we do not recommend working with it directly.

What XML mode does let you save a Script to your PC and re-load it later. To save a Script, switch to XML Mode and copy/paste the XML to a text file on your PC. Windows Notepad works fine.

To restore a Script and start working on it again, instead of loading a Template when you first start ScriptTelnet, switch to XML Mode and copy/paste the XML from your PC. You can then switch to Table Mode and work with your Script Steps.

If you develop a Script that you think may be useful to someone else, please email us the XML with a description of what your Script does. We'll publish it on the site, or even make it into a Template. You are welcome to include <!-- comments --> in your XML and we'll keep them there.