Archived content. No warranty is made as to technical accuracy. Content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Eric Pearce

Chapter 5 from Windows NT in a Nutshell, published by O'Reilly and Associates, Inc.

The Remote Access Service (RAS) allows computers to make network connections to each other using telephone lines.

Windows 3.11, Windows 95, and Windows NT Workstation and Server can call out to another computer or communications server. Windows NT Workstation and Server can accept calls from any of these OS types. In most cases, the type of connection between the computers will be the Point-to-Point Protocol (PPP) running over an analog phone line, but RAS also supports the Serial Line Internet Protocol (SLIP), X.25, and ISDN connections.

This chapter describes the network protocols used by RAS, and how to install, configure, and start the RAS services. The syntax of RAS scripting languages is documented along with examples of their usage.

On This Page

RAS Protocols
RAS Components
Installing RAS
Overview of a RAS session
Configuring the Network
Debugging PPP
Writing Scripts
Windows 95 SCP Scripts

RAS Protocols

A RAS connection running PPP can support the TCP/IP, IPX/SPX, and NetBEUI protocols simultaneously. For example, you may browse a remote network and share files using NetBEUI, browse the World Wide Web using TCP/IP, and access a Novell NetWare file server using IPX--all over a single dial-up RAS connection.

The SLIP protocol is TCP/IP-only and does not support the multitude of options available in PPP. It has fallen out of favor for these reasons and can be avoided in most situations.

The NetBEUI protocol will not generally be able to run over the RAS connection unless you have a Microsoft operating system at both ends of the connection. NetBIOS functions such as file sharing, printing, and NetBIOS name service can all be made to work over either a TCP/IP-only PPP or a SLIP connection using NetBIOS over TCP/IP (NBT).


NT 4.0 also supports the Point-to-Point Tunneling Protocol (PPTP). This allows the creation of Virtual Private Networks (VPN) using the Internet. PPTP creates a virtual "tunnel" between your computer and a remote NT server (or communications server that understands PPTP). This tunnel is encrypted, enabling you to send sensitive data over the Internet. The main reasons to use PPTP are security and lowering remote access costs. PPTP may save you money if you are able to use the Internet to connect remote sites instead of private leased lines.

RAS Components

You may be confused by how the different components of RAS are named and administered. Previous to NT 4.0, RAS referred to both the client and server side of a connection. Typically, the client side is doing the dialing, and the server side is receiving calls. In NT 4.0, the client side of RAS is called Dial-Up Networking (DUN), which is buried in the Programs-Accessories menu. DUN looks similar to the Windows 95 implementation but is different in operation and configuration. The server side, the Remote Access Service, is administered by the Remote Access Admin tool and the Services-Remote Access Service-Properties menu of the Network control panel. This book uses the term RAS to describe the entire Remote Access functionality, and DUN for the client side of RAS.

Installing RAS

To install RAS under NT Server or Workstation, use the Services-Add button of the Network control panel and select Remote Access Service.

Dial-Up Networking will prompt you to install it the first time you try to run it unless it is already installed.

To install the Point-to-Point Tunneling Protocol (PPTP), use the Protocols-Add button of the Network control panel. Installing PPTP also installs RAS if it is not already installed.

Overview of a RAS session

To illustrate how the DUN side of RAS works, let us assume you are a typical NT user who wants to log in to the Internet using your local ISP. To initiate the connection:

  1. Start Dial-Up Networking.

  2. Select an entry name from the scroll list.

  3. Click on the Dial button.

  4. Enter username and password into the dialog box.

  5. After this point, the local computer should log onto the remote RAS server and start the network connection (see Figure 5-1).


Figure 5-1: RAS session startup

There are several processes needed for a successful start of the DUN session. The first is authentication, the process of proving to the remote site that you are a legitimate user. The second is configuring the network, which usually involves getting network information from the remote site to configure the local computer.

PPP Authentication

If you are using PPP, you should be able to use PPP authentication protocols to authenticate your RAS connection to the remote device. An authentication protocol is a set of standards for exchanging logon name and password information between the two network devices.

The most common PPP authentication protocols are the Password Authentication Protocol (PAP) and the Challenge Handshake Authentication Protocol (CHAP). PAP is a simple protocol that sends your username and password to the remote system. The exchange of passwords between client and server are in clear text and could be snooped by a third party listening in on the connection. CHAP is more secure in that the password information is encrypted before it is sent over the PPP connection. Shiva PAP (SPAP), a Shiva-specific version of PAP, improves on PAP by encrypting the password before sending it to the remote system. Microsoft has its own version of CHAP that encrypts the password using a different scheme. This is called MS-CHAP and is generally available only for Microsoft products. If you do not control both ends of your RAS connection, ask the person in charge of the remote end what PPP authentication protocols are supported.

The PPP client and PPP server negotiate to find a common authentication protocol. You can limit the choices in order to enhance security. The choice of PPP authentication protocol is made in the DUN Security tab, as shown in Table 5-1.

Table 5-1 PPP Authentication Protocol Selection


Allowed authentication protocols

Accept any authentication including clear text


Accept only encryped authentication


Accept only Microsoft encrypted authentication


Authentication Using Scripting

If you are using SLIP or are logging in to a remote device which does not support a PPP authentication protocol, you are going to need a script to provide the authentication information.

A script fools a remote computer or device into thinking that you are typing in a username, password, or other logon information, while it is actually done by your computer. Scripting automates the logon procedure and makes it possible for your computer to reconnect a failed connection without user intervention; or, it can even establish connections via the at command scheduler service.

Normally, getting DUN to log in to a Microsoft RAS server is simple and pretty much works out of the box. Configuration is done by clicking on a few checkboxes and typing in names and phone numbers for the remote sites.

The situation becomes more complicated if you are trying to use a non-Microsoft product on one side of the connection. For example, most Internet Service Providers (ISPs) are not using Microsoft NT RAS servers to provide dial-up connectivity for their customers. They typically use specialized "comm-servers" that run vendor-specific and proprietary operating systems. Some of these comm-servers are starting to support RAS, but there are still a huge number that offer generic PPP dial-up support. Some of these authenticate PPP users by using a UNIX-like login and password prompts.

For example:

Login: <username>
Password: <password>
<ppp session starts>

These prompts were originally intended to be used by humans who were logging in to character-based terminal sessions. Then programs such as UNIX UUCP (UNIX-to-UNIX Copy) started to use the same authentication mechanism to login, but did so by pretending to be a human user and entering the username and password via a program.

As the login/password prompts varied among different systems and vendors, a scripting "language" was used to describe the different login/password procedures for each remote computer. In UUCP terminology, the scripting functionality is called a chat script. Chat scripts are similar in function to macros or scripts that terminal emulators or Comm programs provide to automate the login to a BBS or other remote computer system.

Microsoft supports two different scripting languages in NT 4.0. The first consists of the SWITCH.INF-style scripts that appeared in NT 3.5x. The second is the Windows 95-style scripts contained in files with the .SCP extension. If you have existing scripts from NT 3.51 or Windows 95, you should not need to modify them for NT 4.0. If you are writing a script from scratch on 4.0, it is probably better to use the Windows 95-style .SCP scripting language, as it has many more features. For example, the SWITCH.INF language has no time-out functionality, so it will wait forever if something goes wrong. The .SCP scripting language also has more traditional program-flow structures that should be familiar to even the casual programmer. If you are logging in to an ISP or company remote-access facility, chances are that someone else has already written a script in one of the languages that you can use.

If you are setting up Dial-Up Networking to log in to a non-Microsoft PPP server for the first time, it is worth seeing if the Microsoft-supplied Generic Login script will work without any further customization. It should handle the most common login name and password prompts.

Note that it is possible to hardcode your username and password into the scripts themselves. This would eliminate having to type the information each time you use DUN, but your account would be wide open to anyone who gains access to the script files.

Configuring the Network

Your computer has to obtain several pieces of information before it can start communicating via TCP/IP with other computers. This information includes an IP address for the client side of the connection, a list of DNS servers, and possibly a list of WINS servers.

PPP has the ability to obtain an IP address from a PPP server and give it to the dial-in client, but getting DNS and WINS server information to the client requires functionality external to PPP.

IP addresses are usually handed out dynamically by the device you are calling. This means that your IP address (and possibly the TCP/IP hostname) could be different each time you dial in. The IP addresses can come either from a pool of addresses handed out by the remote PPP device or via DHCP.

In order to look up hostnames on the Internet (such as when using a web browser) you also need the address of one or more DNS servers. Some communications servers (including NT RAS) supply this automatically to the dial-in clients via DHCP, and others require you to type the information into DUN using the Server-TCP/IP tab.

If you want to browse the remote network you are dialing into using Microsoft networking, you need a WINS server IP address in the Server-TCP/IP tab. You can either type one in or have it supplied by DHCP.

Debugging PPP

When a PPP connection is first started, the two ends of the connection negotiate lots of options, trying to find a common set that they both support. If you are having trouble connecting with PPP, there are several tools available for debugging. The first is a logfile generated by DUN that records all PPP packets going to and from the local computer and the remote device. The second is the Network Monitor application, which can "listen" on the PPP interface and record all traffic going over the PPP link.

In order to understand the PPP information, you have to have a detailed explanation of PPP readily available. Good sources for descriptions of the protocol are the Internet Request For Comments (RFC) documents available on the Internet. The following Internet RFCs cover PPP:

RFC1661 The Point to Point Protocol (PPP) RFC1700 Assigned Numbers (PPP Protocol Field Assignments section)

You should easily be able to find RFCs on many web and ftp sites. One of the official sites is https://internic.net/. The Southwest Free Software Organization site at https://www.freesoft.org has an especially nice RFC display.

You really do not have to understand the protocol completely in order to spot problems. If you cannot find the error, at least you will be able to produce a logfile that you can show to someone who does understand PPP.

PPP Logging

Locate the key SYSTEM\CurrentControlSet\Services\RasMan\PPP and change Logging from 0 to 1. This will create a file called PPP.LOG in the <winnt root>\SYSTEM32\RAS directory.

To debug a PPP session, first enable logging and then initiate the PPP connection. When the connection fails or exits, examine PPP.LOG to see what happened.

more < PPP.LOG
Line up event occurred on port 0
FsmInit called for protocol = c021, port = 0
FsmReset called for protocol = c021, port = 0
FsmThisLayerStarted called for protocol = c021, port = 0
<PPP packet sent at 02/06/1997 11:14:12:436
<Protocol = LCP, Type = Configure-Req, Length = 0x26, Id = 0x0, Port = 0
<C0 21 01 00 00 24 02 06 00 00 00 00 05 06 00 00 |.!...$..........|
<5B D5 07 02 08 02 0D 03 06 11 04 06 4E 13 09 03 |[...........N...|
<00 AA 00 A5 84 EF                               |......          |
>PPP packet received at 02/06/1997 11:14:12:597
>Protocol = LCP, Type = Configure-Req, Length = 0x24, Id = 0x1, Port = 0
>C0 21 01 01 00 22 01 04 05 F2 02 06 00 0A 00 00 |.!..."..........|
>03 0C C0 27 01 00 00 03 00 00 00 0E 05 06 64 03 |...'..........d.|
>1E 2A 08 02                                     |.*..            |
<PPP packet sent at 02/06/1997 11:14:12:597
<Protocol = LCP, Type = Configure-Nak, Length = 0xe, Id = 0x1, Port = 0
<C0 21 03 01 00 0C 03 08 C0 27 01 00 00 01       |.!.......'....  |
>PPP packet received at 02/06/1997 11:14:12:597
>Protocol = LCP, Type = Configure-Reject, Length = 0x16, Id = 0x0, Port = 0
>C0 21 04 00 00 14 0D 03 06 11 04 06 4E 13 09 03 |.!..........N...|
>00 AA 00 A5 84 EF                               |......          |

What you are seeing is a trace of every PPP packet going to and from your computer to the remote PPP device. The Protocol and Type fields tell you what is going on. The data in the packets is presented in both hexadecimal and ASCII.

One of the most common failures you may have when setting up a new PPP connection is with the negotiation of an authentication Protocol. This is controlled on the client side of RAS by the Security tab of Dial-Up Networking. Both ends of the PPP connection try to find a common mechanism for authentication. The Dial-Up Networking Security tab places various restrictions on the allowable authentication protocols.

The PPP session should try to negotiate the most secure protocol first, and if this fails, try the second best, and so on. In reality, not every device that speaks PPP handles the authentication protocol negotiation gracefully, leading to interoperability problems between different vendor devices.

Use the most secure protocol, which will normally be Accept only encrypted authentication. If both ends are Microsoft products, you could use MS-CHAP.

For authentication failures, the most interesting part of the PPP.LOG file is going to be the section starting with Authentication phase. For example:

Authenticating phase started
<PPP packet sent at 02/06/1997 15:05:04:169
<Protocol = SHIVA PAP, Type = Protocol specific, Length = 0x28, Id = 0x0, Port = 0
<C0 27 06 00 00 26 01 05 65 61 70 02 15 31 5C 5C |.'...&..eap..1\\|
<0B 11 3D 73 9F C7 2A 49 EB 67 64 7C A4 89 D5 5D |..=s..*I.gd|...]|
<03 04 00 01 04 04 00 01                         |........        |
>PPP packet received at 02/06/1997 15:05:04:389
>Protocol = SHIVA PAP, Type = Protocol specific, Length = 0x8, Id = 0x0, Port = 0
>C0 27 02 00 00 06 00 00                         |.'......        |
FsmThisLayerUp called for protocol = c027, port = 0

This DUN client is configured with the Accept only encryption authentication option, which accepts either SPAP, CHAP, or MS-CHAP. From this sequence, you can see that the local computer tried using the SPAP (Shiva PAP) authentication protocol, and the remote PPP device accepted it. You can see that protocol c027 succeeded from the lines' referrals to Shiva PAP and FsmThisLayerUp. In RFC 1700, c027 is listed as the Shiva Password Authentication Protocol or SPAP.

c021            Link Control Protocol
c023            Password Authentication Protocol
c025            Link Quality Report
c027            Shiva Password Authentication Protocol
c029            CallBack Control Protocol (CBCP)
c081            Container Control Protocol
c223            Challenge Handshake Authentication Protocol
c225            RSA Authentication Protocol
c227            Extensible Authentication Protocol
c26f            Stampede Bridging Authorization Protocol
c281            Proprietary Authentication Protocol
c283            Proprietary Authentication Protocol
c481            Proprietary Node ID Authentication Protocol

The next example shows a failure:

Authenticating phase started
>PPP packet received at 02/06/1997 14:28:11:617
>Protocol = CHAP, Type = Protocol specific, Length = 0x1a, Id = 0x1, Port = 0
>C2 23 01 01 00 18 08 32 F9 F9 ED 00 1E 4D 60 6F |.#.....2.....M`o|
>70 60 2F 74 66 73 74 2D 6E 62                   |ora-login:.     |
<PPP packet sent at 02/06/1997 14:28:11:617
<Protocol = CHAP, Type = Protocol specific, Length = 0x21, Id = 0x1, Port = 0
<C2 23 02 01 00 1F 10 94 40 30 22 05 A5 DF 43 1E |.#......@0"...C.|
<E0 85 54 8B 0F CA 64 48 4F 4D 45 5C 70 63 65 61 |..T...dHOMEcea|
<70                                              |p               |
>PPP packet received at 02/06/1997 14:28:11:757
>Protocol = CHAP, Type = Protocol specific, Length = 0x1b, Id = 0x1, Port = 0
>C2 23 04 01 00 19 49 6E 76 61 6C 69 64 20 43 48 |.#....Invalid CH|
>41 50 20 72 65 73 70 6F 6E 73 65                |AP response     |
Auth Protocol c223 terminated with error 7
FsmThisLayerDown called for protocol = c021, port = 0

The "Protocol = CHAP" and the message "Invalid CHAP response" are clues to what is wrong. From looking at RFC1700, you can tell that "Auth Protocol c223" is CHAP. The next step is to examine the remote device you are calling and find out why it does not speak CHAP.

Network Monitor and PPP

The Network Monitor is normally used to capture network traffic from a LAN interface, such as an Ethernet adapter. It is also possible to use it as a "WAN Analyzer" by listening on serial interface used by RAS and capturing packets from the PPP session. It is most useful during the initial negotiation between DUN and the remote device, as this is where errors are likely to occur. Follow these steps to locate errors:

  1. Start Network Monitor.

  2. Select interface to capture traffic from. Under the Capture-Networks menu, click on the Ethernet interface with all zeros for the Current Address (see Figure 5-2).


    Figure 5-2: Selecting serial interface in Network Monitor

  3. Start the capture. Select Capture-Start.

  4. Start DUN.

  5. Dial the entry that is to be debugged.

  6. When the connection fails, go back to Network Monitor and select Capture-Stop and View.

  7. Step through each packet and look for errors, especially with "Reject" in the Description field (see Figure 5-3).


    Figure 5-3: Capture of PPP traffic from RAS session

    Keep in mind that the PPP device that you are calling in to is likely to have an ability to debug the PPP negotiation process, enabling the PPP connection to be debugged from either side of the conversation.

    Also realize that you are unlikely to be the first person to discover a new PPP problem between devices and you should search the Internet, web sites, and Usenet newsgroups before paying for help.

Writing Scripts

Writing a script is pretty easy most of the time. These steps outline the process:

  1. Connect to the remote system using Terminal Window or Hyperterminal.

  2. Write down what the remote system sends and what you have to type.

  3. Create the script in SWITCH.INF or .SCP language.

  4. Associate the script with the dial-up entry by using the Script tab and selecting the script name from the Run this script scroll list.

  5. Test the script.

  6. If the script fails, turn on DEVICE.LOG debugging and correct errors.

The following example shows how scripts can log into a Shiva LanRover using prompts to authenticate and start the PPP session. Have the manual available, so you know what to type at each prompt. (The LanRover can be configured to authenticate and start PPP automatically, but this configuration illustrates script features nicely.)

  1. A new phonebook entry is created by starting up Dial-Up Networking, selecting New, and filling out the form.

  2. Under the Script tab, select Pop up a terminal window.

  3. Dial entry.

  4. When the connection is made, the terminal window appears, but no prompt is seen from the remote system.

  5. After hitting ENTER twice, the login prompt appears:

@ Userid:

  1. Type your username and hit ENTER. If the script fails, turn on DEVICE.LOG debugging and correct errors (see "Debugging Scripts" for the procedure).

  2. The next prompt appears:


  1. Type your password and hit ENTER.

  2. Another prompt appears:

Shiva LanRover/8E, Version 4.0.2 96/05/07 lanrover>

  1. Type in ppp and hit ENTER.

  2. The PPP session then starts:

Exiting shell, starting PPP @3~$#$&~$#$#$%#^$#

  1. At this point, you can continue to logon by clicking the Done button.

From information collected during the terminal session, a script can be created. The following is a sample SWITCH.INF script:

; interactive lanrover entry
; needs two returns before prompt appears
; have to explicitly start ppp
; ignore anything from here on

And here is a sample .SCP script:

proc main
transmit "^M"
transmit "^M"
waitfor "Userid:"
transmit $USERID
transmit "^M"
waitfor "assword?"
transmit $PASSWORD
transmit "^M"
waitfor "anrover>"
transmit "ppp^M"

Either of these scripts can be associated with the phonebook entry by using the Script tab and selecting the script name from the Run this script scroll list.

Debugging Scripts

Unlike Windows 95, NT does not supply a "step through script" function that allows you to execute your script one line at a time and watch it interact with the remote system. When running .SCP scripts, it does pop up the terminal window as the script executes, but this usually exits too quickly for you to catch the reason for failures. DUN does offer a form of post mortem analysis by recording the interaction between the client (your NT machine running dial-up networking) and the server (the comm-server you are logging into) in a log file, called <winnt root>\SYSTEM32\RAS\DEVICE.LOG. You have to specifically enable logging in the Registry in order for this to work.

In KEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\RasMan\Parameters, change the value for Logging from 0 to 1. You do not need to reboot the system for this to take effect, just exit and restart Dial-Up Networking.

Try dialing the entry you are debugging. After it fails or terminates, examine the DEVICE.LOG file:

Remote Access Service Device Log  01/09/1997  09:54:55
Port: Command to Device:
Port: Response from Device:netblazer login:
Port: Command to Device:eap
Port: Echo from Device :eap
Port: Response from Device:
Port: Command to Device:foo
Port: Echo from Device :
Port: Response from Device:gin incorrect.
netblazer login:

The "Command to Device" lines are text being sent from your computer to the remote computer. The "Response from Device" is what the remote computer sends back. The "Echo from Device" is simply the text you are sending being echoed back by the remote device. The actual exchange would look like this:

Your Computer        Remote Computer
                   netblazer login:
                   Login incorrect.

The echo is normally turned on for everything except passwords. This is another holdover from human interaction, where you expect to see what you are typing. The "Login incorrect" message coming from the comm-server in the "Response from Device" indicates that either the username or password is incorrect and this is the reason the script is failing. Keep in mind that the DEVICE.LOG file may contain your password in clear-text (the password is "foo" in the example).


The SWITCH.INF file contains multiple scripts in the scripting language first introduced in NT 3.x.

Section header

Section headers are used to delineate individual scripts within the SWITCH.INF. This is different from the Windows 95 scripting language, where each script is stored in a separate .SCP file. The header is simply a name enclosed in brackets:


Anything following the header is assumed to be script commands until the next header or the end of file.

The name within the brackets appears in the scroll list Run this script in the Script tab of Dial-Up Networking.


COMMAND is used to send text to the remote computer or device. It does not add a carriage-return character, so one must be added with the <cr> macro.


As each COMMAND statement takes about two seconds to execute, an empty statement such as:


serves as a way to insert time delays into the script.

The sequence:


is equivalent to:


but each character is separated by a two-second delay in the first sequence. This method could be used to communicate with extremely slow devices.


The OK command's main purpose is to look for a specific response from the remote computer or device. Most of the time this will be a prompt for the username or password.


This OK command will try to match the string "ogin:" in any response coming from the remote device. The <match> macro is case-sensitive, so using the string "ogin:" will match either "Login:" or "login:".


The LOOP command is usually combined with the OK command and has the effect of a conditional loop. The LOOP ignores any text coming from the remote device until something matching the OK command is found.


This OK and LOOP combination is useful for skipping through greeting messages or other text irrelevant to the login process. For example, if your Internet provider has a message of the day that is printed before the login prompt:

                   Welcome to Joe Bob's ISP
                    System down at 5pm tonight for repairs

The OK/LOOP combination would ignore all the text until it found the "login:" prompt.

Response Commands

The response commands deal with processing output from the remote device.

CONNECT=response <macro>

The CONNECT command looks for a connect message from the communications device, indicating a successful connection. This is primarily used when talking to PAD devices in the PAD.INF file.

ERROR=response <macro>

If the script is looking for a specific error message, the ERROR keyword will tell DUN to look for this error message and notify the user that an error has occurred.

ERROR_DIAGNOSTICS=response <diagnostics>

If the script encounters an error message, RAS will try to interpret what it means and inform the user.


Do not expect any response from the remote device.


Macros are used to match or send special characters when sending text to or receiving text from the remote device.


Send carriage return character.


Send line feed character.


Look for string in output from remote device and exit loop. The <match> macro will find the string anywhere in the output (it does not have to be by itself) and is case-sensitive. For these reasons, <match>Login: would fail to match "login:", but using "ogin:" matches either case.


Wildcard character for <match> macro that matches any single character. For example, <match>"<?>ogin:" could be used to match "Login:" or "login:".


Refer to character via position in ASCII character set by hex number (XX). This is useful for describing non-printing characters, such as NUL, which could be matched with <h00>. The ASCII code for a carriage return is CR, which is 13 in base 10 and 0D in base 16. This could be represented by <h0d> in a script.


Ignore the responses from the remote system.


Interpret response from the remote system as an error diagnostic message and display it to user.


Supply username from Connect To dialog box. Not supported in SLIP sessions.


Supply password from Connect To dialog box. Not supported in SLIP sessions.


Comments can be used to annotate scripts to make them easier to maintain. A comment is started by a semicolon as the first character on the line:

; LanRover requires 2 carriage-returns before prompting for username
; (expecting PPP/ARA?)

Further Info

There are several files in the <winnt root>\SYSTEM32\RAS directory:


Windows Help file for RAS


Sample scripts for modems and ISDN TAs


Sample scripts for PAD/X.25 devices

Windows 95 SCP Scripts

The Windows 95 Dial-Up Networking scripting language is supported under NT 4.0. In fact, you should be able to reuse any scripts you wrote for Windows 95 on NT 4.0 without modification.

The Windows 95 scripting language uses separate files ending with the extension .SCP for each script. This different than the SWITCH.INF scripting language, which stores multiple scripts within the same file.

The Windows 95 scripting language is "richer" in that it is more like a traditional programming language, with program-flow structures, variables, types, and so on. Another advantage over SWITCH.INF-scripts is a time-out capability that permits the script writer to handle unresponsive connections and other communications failure conditions gracefully.

Script Structure

All scripts must have a main procedure, delimited by proc and endproc, that can contain variable declaration and commands.

proc main
    variable declaration


Variables are either user- or system-defined names for holding values during the execution of the script. Variable names must begin with a letter or underscore character, but can contain mixed-case letters, numbers, and underscores. Be sure to avoid using any of the scripting language commands as variable names. These are called "reserved words," in that they are unavailable for use within the script.

Variable Data Types

The Windows 95 scripting language variables support the concept of type, which defines the kind of data contained in the variable and operations that can be performed on it.




A negative or positive number


One or more characters enclosed in double quotation marks


Only possible values are TRUE or FALSE

Variable declaration and assignment

Variables are declared with a type the first time they appear in the script:

integer            timeout

Variables are assigned values using an expression:

timeout    =    10

Variables can also be declared and assigned in the same statement:

integer       timeout = 10

Predefined variables

The system provides several variables as a way for scripts to check for a common condition at run-time. They are read-only, meaning that you can query their value, but not alter it.






The username of the account making the connection. This is taken from the User field of the Connect To dialog box.



The password of the account making the connection. This is taken from the Password field of the Connect To dialog box.



If a script command succeeds, this is set to TRUE, otherwise it is FALSE.



If a script command fails, this is set to TRUE, otherwise it is FALSE.

String literals

String literals are used to represent characters or strings that would be difficult to use because they contain nonprinting characters or characters that may be interpreted by the scripting language (instead of taken literally).





Caret translation

Used to represent non-printing ASCII characters.


Carriage return



Line feed



Double quotation mark

Protects or quotes the double quotation mark from being interpreted as the beginning or end of a string.


Prevents character following carat from being interpreted as a caret translation.



Less-than sign



Single backslash



Expressions are operations that yield a result which can be assigned to a variable or evaluated.



Valid Data Types


Unary minus



One's complement







Integer, string (+ only)




== !=


Integer, string, boolean


Logical AND



Logical OR



The comment character for scripts is the semi-colon. Anything following the comment character is ignored by the script processor.

; Here is a comment


Keywords define the structure of the script and declare variable type.


proc name
Beginning of procedure. Scripts must have at least a main procedure.
proc main


End of procedure. Has effect of ending script processing.


integer name[=value]
Declare name as type integer and optionally assign it a value.
integer nLoginTimeout = 3


string name[=value]
Declare name as type string and optionally assign it a value.
string szPW = "password:"


boolean name[=value]
Declare name as type boolean and optionally assign a value.
boolean bUseSlip = FALSE


Commands control the flow of the script or perform some function on a variable.


Execute commands if condition is TRUE.
if condition then
if FALSE == $SUCCESS then
goto TryAgain


goto label
Jump to label and resume execution. Used to escape out of program flow structures.
goto label
goto Bailout
more commands...
; Something isn't responding. Halt the script
; and let the user handle it manually.
set screen keyboard on


Pause script execution for seconds seconds.
delay seconds
; Delay for 2 seconds first to make sure the
; host doesn't get confused when we send the
; two carriage returns.
delay 2
transmit "^M^M"


A form of a case statement that waits for output from remote device and jumps to labels based on the output or a timeout. The system variable $SUCCESS is set to TRUE if a label is matched by output and set to FALSE if time expires before any output is received.
waitforstring [,matchcase][then label
{, string [matchcase] then label } ]
[ until time ]
; Wait for the login prompt before entering
; the user ID, timeout after x seconds
waitfor szLogin then DoLogin
until nLoginTimeout


Execute commands while condition is TRUE.
while condition do
; Attempt to login at most 'nTries' times
while 0 < nTries do
transmit "^M"
nTries = nTries - 1 ; decrement nTries


Cease executing script, without terminating terminal window.
; Something isn't responding. Halt the script
; and let the user handle it manually.
set screen keyboard on



getip [value]
Obtain IP address from remote device. If multiple IPs are received, parse output using position to index the list.
Optional index into array of IP addresses.
set ipaddr getip 2

set port

set port [options]
Set communications parameters of terminal window session, overriding current settings for phonebook entry.
databits bits
Set number of databits to 5, 6, 7, or 8.
parity type
Set parity to none, odd, even, mark, or space.
stopbits bits
Set stopbits to 1 or 2.
; Set the port settings so we can wait for
; non-gibberish text.
set port databits 7
set port parity even

set screen keyboard

set screen keyboard value
Either allow or disallow keyboard input in terminal window during script execution.
on | off
Toggle keyboard input on or off.
set screen keyboard on

set ipaddr

set ipaddr value
Set IP address for current session.
IP address or variable containing IP address.
set ipaddr getip 2


Send string to remote device.
string [,raw]
Optional raw keyword is used when string contains characters
that could be interpreted by script.
transmit $USERID, raw
transmit "/go:pppconnect^M"

Reserved Words

The following reserved words are part of the script language and cannot be used as variable names:

  and boolean databits delay do endif endproc endwhile even FALSE
   getip goto halt if integer ipaddr keyboard mark matchcase none
   odd off on or parity port proc raw string then transmit TRUE
   until waitfor while

Further Info

There are several files in the <winnt root>\SYSTEM32\RAS directory:


Windows Help file for RAS.


Script documentation in Word format.


Sample SCP scripts.


The Point-to-Point Tunneling Protocol can be used to create encrypted tunnels between computers separated by networks, enabling sites and users to connect in a low-cost and secure manner.


The tunnel can create a path for several protocols to run over a protocol of a different type. This is called encapsulation, as the network traffic entering one end of the tunnel is encapsulated within the protocol native to the intermediate network and unencapsulated on the other end of the tunnel. The most common example of tunneling would be carrying IPX, NetBEUI, and TCP/IP over a TCP/IP-only network (such as the Internet). See figure 5-4 for a diagram of this example.


Figure 5-4: Tunneling over the Internet using PPTP


If you are using your own dedicated ("leased") lines between sites or dialing into your company RAS server, you are not likely to be worried about a third party intercepting traffic. The act of sending traffic over the Internet brings up potential security problems. If you were conducting business or transferring sensitive data between sites using the Internet, someone could intercept the traffic and analyze it. PPTP encrypts traffic, preventing the packets from being read if they are snooped by a third party.


Many companies have created large and complex in-house dial-up facilities for remote workers to dial into. Some companies use dedicated lines to link their sites, resulting in large, recurring facilities costs. Tunneling over the Internet may allow remote workers or sites to use the Internet in place of expensive company-owned facilities.

Dial-Up Versus Dedicated

Nearly all descriptions of PPTP describe its use only in regard to dial-up situations. It is possible to use PPTP over a previously existing network connection, such as a dedicated connection to the Internet. If you can reach a PPTP server, you simply "dial" into it using its IP address. The PPTP session runs on top of the existing connection.

Installing PPTP

PPTP is installed as a protocol using the Protocol-Add button of the Network control panel. The only installation option is the number of Virtual Private Network (VPN) ports. Each end of each PPTP session requires a VPN port. VPN ports do not have to have a corresponding physical RAS port (COM port). They exist in software only. If you have only one PPTP session on your computer, you need only one VPN port. A RAS server requires as many VPN ports as might possibly be in use simultaneously, both incoming and outgoing.

Once you have installed a VPN port, RAS and DUN treat it as if it were a physical port. The only difference is that an IP address or hostname is used instead of a phone number when calling the remote site.

Using PPTP

In most cases, you will being using PPTP over a dial-up RAS connection to an ISP. You should first establish the RAS session to the ISP using DUN to dial the modem or ISDN entry. Once you are connected to the ISP, you can use DUN to dial the PPTP entry, which runs on top of the conventional RAS session.

If you have a dedicated connection to the Internet or use a device that behaves as if it were permanently connected, you can skip the modem dialing entirely, and initiate the PPTP session on top of the existing Internet connection.

Using PPTP over a dedicated connection means using RAS, even though you are not using RAS to create the initial connection. It may look a little silly to have the RAS modem monitor lights flashing and a baud rate of 10,000,000 when using PPTP over an Ethernet LAN.

Other Tunnel Products

The market has yet not selected a winner in the tunnel area. Microsoft is pushing PPTP and several vendors are adding support for it, including US Robotics, Ascend, and 3Com. The main competition for PPTP is L2F (Layer 2 Forwarding), promoted by Cisco Systems, Shiva, and Nortel. Digital Equipment Corporation also has a tunneling product for Windows NT and Windows 95, called AltaVista Tunnel.

Files Used by RAS

There are several files that RAS uses to accomplish the logon procedure. They are stored in the directory <winnt root>\SYSTEM32\RAS.

  • When DUN is started, it reads the system phonebook file (RASPHONE.PBK) or a user-specified phonebook for a list of possible entries to dial. The phonebook file supplies all the settings for the particular entry to DUN, including the device being used to dial, the phone number, the networking and authentication protocols, and so on.

  • If the device being used to connect is a modem, the modem type is looked up in the MODEM.INF file. Any commands or features unique to the particular modem are found here.

  • If the device is a PAD (used for packet networks such as x.25) the Network or PAD type is looked up in the PAD.INF file.

  • When dialing into a non-RAS computer or communications server using a script, the script associated with the phonebook entry is read from either the SWITCH.INF file or a standalone script in a amp;.SCP file.

For the RAS server side of the connection, accepting calls from remote computers, the RAS service reads the MODEM.INF file for any modems it has configured. The permissions for users allowed to dial in is maintained by either Remote Access Admin or User Manager for Domains.


The role of the MODEM.INF file is to abstract interaction with modems so software can control modem characteristics in a generic manner, without the user supplying details about the specific brand, model, or type of modem.

Previous to NT 4.0, all modems had to be described in the MODEM.INF file. In NT 4.0, the Universal Modem Driver (Unimodem) is used if the modem supports it. NT 4.0 still supports the MODEM.INF for backwards compatibility with non-Unimodem capable modems.

Note: You can manually configure RAS to use MODEM.INF instead of Unimodem by editing the Registry. See KB article #150808.

If your modem does not support Unimodem or is not listed in MODEM.INF, check if the modem manufacturer distributes a MODEM.INF entry on media that came with the modem or from a web site or BBS. You could also add your own entries to MODEM.INF, but you should think seriously about buying a new modem or one that complies with industry standards.

File Description

Most modems made today still use the original AT command set that came from Hayes. The big problem is that each manufacturer has expanded on the original command set in their own proprietary way. There is also the concept of registers, which are general purpose NVRAM settings that can be used to store highly modem-specific settings. The meaning of the registers may change between firmware revisions of the same modem!

For example, here is a fragment of the MODEM.INF that describes the US Robotics Sportster:

[US Robotics Sportster 14400]
DETECT_RESPONSE=Sportster 14,400
COMMAND_INIT=AT&F&C1&D2 V1 S0=0 S2=128 S7=55<cr>
CONNECT=\<cr><lf>CONNECT <carrierbps><cr><lf>
CONNECT_EC=\<cr><lf>CONNECT <carrierbps>/ARQ<cr><lf>

By assigning tags to various functions, such as turning compression on or off with compression_on and compression_off, software using the modem does not have to know that the USR Sportster uses &K1 for this function, while the Cardinal 14400 uses %C0.

Software can also dynamically detect the type of installed modem using the DETECT_STRING. If it sends the ATI3 command to the modem and gets Sportster 14,400 back, it knows what type of modem is installed. This creates a plug and play capability for modems.

The COMMAND_INIT string is similar to the init strings required by comm programs or fax software. The COMMAND_INIT typically resets the modem to the factory defaults (usually &F) and then changes anything that should be different from the factory default setting. By returning to the factory defaults each time you use it, the modem always starts with a clean configuration.

The modem can tell the software what speed and type of connection it has made with the CONNECT message. This allows DUN or RAS to inform the user about the baud rate, bits per second (BPS), compression, error control, and so forth used during the connection to a remote computer or device. The CONNECT message is the same one you see when dialing a modem manually.


The RASPHONE.PBK (RAS phonebook) file contains entries that describe sites to which Dial-Up Networking can connect. Each phonebook entry contains phone numbers, security, and network settings. Users can create multiple phonebook files and they are available to Dial-Up Networking as long as they have the .PBK filename extension. The file RASPHONE.PBK is the default phonebook and will be used unless you specify an alternative. You can select alternative phonebooks in the GUI version of Dial-Up Networking by selecting More-User Preferences and the Phonebook tab. From the command line, you can dial using alternate phonebooks with the rasphone or rasdial commands.

For example, assume the alternate phonebook file is called MYOWN.PBK and the entry name is ora. The rasphone command can specify an alternate phonebook using the -f flag and the phonebook entry using the -d flag:

 rasphone -f myown.pbk -d ora

The rasdial command takes the entry name, followed by the /phonebook: flag and the name of the alternate phonebook.

 rasdial ora /phonebook:myown.pbk

File Description

You should be able modify anything you need in the phonebook by using the DUN GUI. As the phonebook file is just a text file, it is possible to edit it by hand. It is safer to modify an existing entry than to try to create your own from scratch. If you do modify the phonebook file directly using an editor, you will have to quit and restart DUN for your changes to take effect.

Entries in the phonebook file are started by an entry name in brackets. The entry name is followed by a list of parameters and values that have been set by the Dial-Up Networking GUI:

Description=This is a comment

Most values are toggled on or off by setting them to 1 or 0. The Ip values are expected to be supplied dynamically at connection time.

This is followed by MEDIA and DEVICE sections that describe the communications device to be used for the connection:

Device=Courier V.Everything

If the entry uses a script, there is another DEVICE entry that has either the pathname of a Windows 95-style script:


or the name of an entry in the SWITCH.INF file:


An entry for PPTP has the following MEDIA and DEVICE fields:



The PAD.INF file contains descriptions of various PAD (Packet Assembler/Deassembler) devices and networks that RAS can connect to, which are typically X.25.

The PAD.INF file use the same scripting language as SWITCH.INF. The following is a script to connect to the SprintNet packet network:

[SprintNet, Standard]
; The next two lines ignore logon banners.
; The @ characters sets the SprintNet PAD for 8 databit communication.
; The D character requests a 9600 speed.
; We don't care about the response, so we ignore it (unless modem has hung up).
; A carriage return to initialize the PAD read/write buffers.
; Set the first half of X.3 settings on the PAD which make it work well with RAS.
COMMAND=SET 1:0,2:0,3:0,4:1,5:0,6:1,7:0,8:0,9:0,10:0<cr>
; Set the other half of X.3 parameters.
COMMAND=SET 12:0,13:0,14:0,15:0,16:0,17:0,18:0,19:0,20:0,22:0<cr>
; Finally try to call RAS X25 server.
COMMAND=C <x25address>*<UserData><cr>

About the Author

Eric Pearce is a system and network administrator for O'Reilly & Associates. He specializes in networking, as it provides a challenging mix of protocols, platforms, and vendors. A coauthor of the X Window System Administrator's Guide, Eric has written articles for a number of trade magazines and several O'Reilly publications.

Copyright © 1997 by O'Reilly & Associates, Inc.

We at Microsoft Corporation hope that the information in this work is valuable to you. Your use of the information contained in this work, however, is at your sole risk. All information in this work is provided "as -is", without any warranty, whether express or implied, of its accuracy, completeness, fitness for a particular purpose, title or non-infringement, and none of the third-party products or information mentioned in the work are authored, recommended, supported or guaranteed by Microsoft Corporation. Microsoft Corporation shall not be liable for any damages you may sustain by using this information, whether direct, indirect, special, incidental or consequential, even if it has been advised of the possibility of such damages. All prices for products mentioned in this document are subject to change without notice. International rights = English only.

International rights = English only.

Click to order