-
VPN Client Administrator Guide, Release 4.6
-
Preface
-
Configuration Information for an Administrator
-
Preconfiguring the VPN Client for Remote Users
-
Updating VPN Client Software
-
Configuring Automatic VPN Initiation-- Windows Only
-
Using the VPN Client Command-Line Interface
-
Managing Digital Certificates from the Command Line
-
Customizing the VPN Client Software
-
Troubleshooting and Programmer Notes
-
Windows Installer (MSI) Information
-
Index
-
Table Of Contents
Troubleshooting and Programmer Notes
Troubleshooting the VPN Client
Getting Information About Severity 1 Events
Gathering System Information for Customer Support
If Your Operating System is Windows 98, 98 SE, ME, 2000, or XP
If Your Operating System is Windows NT or Windows 2000
If Your Operating System is Mac OS X
Booting Automatically Starts up Dial-up Networking on Windows 95
Changing the MTU Size—Linux, Solaris, and Mac OS X
Setting the MTU from the Command Line
Configuring Delete with Reason on the VPN Concentrator
Start Before Logon and GINAs—Windows Only
Command Line Switches for vpngui Command—Windows Only
Unit Client Application Program Interface
Troubleshooting and Programmer Notes
This chapter contains information to help you resolve problems installing or running the VPN Client. It also contains notes helpful for writing programs for special needs.
This chapter includes the following main topics:
•
Troubleshooting the VPN Client
•
Troubleshooting the VPN Client
This section describes how to perform the following tasks:
•
•
Gathering VPN Client Logs
The Logs folder in the VPN Client install directory stores log files of VPN Client sessions. Log files are text files with names in the format Log-yyyy-MM-dd-hh-mm-ss.txt. For information on log files and logging, refer to VPN Client User Guide for Windows, Chapter 7 "Managing the VPN Client" or VPN Client User Guide for Mac OS X, Chapter 7, "Managing the VPN Client."
You can obtain these log files for analysis and send them to Customer Support, when necessary.
Getting Information About Severity 1 Events
When severity 1 events occur, the VPN Client logs them in a text file named faultlog.txt.This file exists in the installation directory of the VPN Client. This event logging occurs whether the logviewer application is running or not. For example errors occurring during service initialization cannot be logged to the log viewer, because these errors occur before the service has attached itself to the log viewer. Therefore, you can open the faultlog.txt file to read these severity 1 events. This log file provides a useful tool to help you analyze what is happening and gives you information to report to customer support if you need to contact your customer support representative.
Gathering System Information for Customer Support
If you are having problems running the VPN Client on your PC, you can gather system information that is helpful to a customer support representative and e-mail it to us. We recommend that you do the following before you contact us.
If Your Operating System is Windows 98, 98 SE, ME, 2000, or XP
Go to the Start menu and select Programs > Accessories > System Tools > System Information.
Windows displays the Microsoft System Information screen, such as the one in Figure 8-1.
Figure 8-1 System Information Screen on Windows 98
Select a category and the screen displays details for that category. You can then execute the Export command and choose a name and destination. Windows creates a text file, which you can attach to an e-mail message and send to the support center.
If Your Operating System is Windows NT or Windows 2000
On the Windows NT or Windows 2000 operating system, you can run a utility named WINMSD from a command-line prompt. WINMSD generates a file containing information about your system configuration, and the software and drivers installed.
To use this utility, perform the following steps:
Step 1
This action displays a window with a DOS prompt, such as c:\.
Step 2
C:\>winmsd /a /fwhere /a = all and /f = write to file.
This command generates a text (.txt) file with the name of your computer and places the file in the directory from which you run the command. For example, if the name of your machine is SILVER and you execute the command from the c: drive (as shown above), the text file name is silver.txt.
If you open the file with a text editor, such as Notepad, you see a file such as the one shown in
Figure 8-2, which was from a Windows NT system.Figure 8-2 System Text File
You can attach this file to an e-mail message and send it to the support center.
If Your Operating System is Mac OS X
Step 1
ifconfig -a uname -a kextstatCopy the output from the above commands, paste it into an e-mail message, and send it to Support.
Solving Common Problems
This section describes some common problems and what to do about them.
Shutting Down on Windows 98
You may experience a problem with your Windows 98 system shutting down when the VPN Client software is installed. If so, you need to disable the fast shutdown feature, as follows:
Step 1
Microsoft displays a Properties page.
Step 2
Step 3
Booting Automatically Starts up Dial-up Networking on Windows 95
Some versions of Internet Explorer silently control startup options in Windows 95 so that every time you start your system, Dial-Up Networking launches. If this occurs, as it does in Internet Explorer 3.0, go to View > Options > Connections and uncheck the option Connect to the Internet as needed.
Changing the MTU Size
The Set MTU option is used primarily for troubleshooting connectivity problems.
Note
The maximum transmission unit (MTU) parameter determines the largest packet size in bytes that the client application can transmit through the network. If the MTU size is too large, the packets may not reach their destination. Adjusting the size of the MTU affects all applications that use the network adapter. Therefore the MTU setting you use can affect your PC's performance on the network.
MTU sizing affects fragmentation of IPSec and IPSec through NAT mode packets to your connection destination, because IPSec encapsulation increases packet size. A large size (for example, over 1300) can increase fragmentation. Using 1300 or smaller usually prevents fragmentation. Fragmentation and reassembly of packets at the destination causes slower tunnel performance. Also, many firewalls do not let fragments through.
Changing the MTU Size—Windows
To change the size of the MTU for Windows, use the following procedure:
Step 1
The Set MTU window appears.
Figure 8-3 Setting MTU Size on Windows NT
Step 2
Step 3
Step 4
You must restart your system for your change to take effect.
Changing the MTU Size—Linux, Solaris, and Mac OS X
To change the MTU size:
Step 1
Step 2
sudo ifconfig en0 mtu 1200(Replace the en0 with the appropriate interface, and replace 1200 with the desired mtu.)
Step 3
Setting the MTU from the Command Line
You can use the SetMTU command at the command-line prompt to set the MTU size. The syntax of the SetMTU command follows:
setmtu /switch value
where switch can be one of the following:
The new setting remains in effect the next time a tunnel is established.
Delete With Reason
When a disconnect occurs, the VPN Client displays a reason code or reason text. The VPN Client supports the delete with reason function for client-initiated disconnects, concentrator-initiated disconnects, and IPSec deletes.
•
•
•
Note
Table 8-1 describes the reason codes and the corresponding messages.
All text messages for client-initiated disconnects begin with "Secure VPN Connection terminated terminated locally by the client".
All text messages for concentrator-initiated disconnects begin with "Secure VPN Connection terminated by Peer X.X.X.X", where X.X.X.X is the IP address of the concentrator.
The translated reason code or the reason text follows.
Configuring Delete with Reason on the VPN Concentrator
To receive disconnect information from a 4.0 or greater VPN Concentrator, you must configure the feature as follows:
Step 1
Step 2
Step 3
Step 4
Start Before Logon and GINAs—Windows Only
The VPN Client can load prior to logging in to a Windows NT platform (Windows NT 4.0, Windows 2000, and Windows XP). This feature lets remote users establish a VPN connection to a private network where they can successfully log in to a domain. When start before logon (SBL) is enabled on a Windows NT platform, the VPN Client tries to replace the standard Microsoft logon dialog box (the same one that appears after you press Ctrl+Alt+Del when booting your PC, called a GINA). The name of the Microsoft GINA is msgina.dll and you can find it in the registry at the location:
HKLM\Software\Microsoft\Windows NT\CurrentVersion\WinlogonGinaDLL = msgina.dllThe VPN Client replaces the msgina.dll with the VPN Client's GINA (csgina.dll), and then points to it so that you can still see and use the MS GINA. When you start your PC and press Ctrl+Alt+Del, you are launching the VPN Client Dialer application and the MS logon dialog box. The VPN Client detects whether the necessary Windows services are running and if not, displays a message asking you to wait.
If you look in the VPN Client registry, you see the following parameters and values:
HKLM\Software\Cisco Systems\VPN Client\GinaInstalled = 1PreviousGinaPath = msgina.dll
Note
Fallback Mode
In some cases a third-party program replaces the MS GINA, and in some of these cases the VPN Client works with the third-party program, while in other cases, it does not. The VPN Client maintains a list of incompatible GINAs that it does not work with, and does not replace the GINA file in use. This is called fallback mode. The list of incompatible GINAs resides in the vpnclient.ini file, and the VPN Client refers to the list only during installation. The following entry is an example.
IncompatibleGinas=PALgina.dll,nwgina.dll,logonrem.dll,ngina.dllIn fallback mode, the VPN Client performs differently when start before logon is in use. Instead of loading when you press Ctrl+Alt+Del, the VPN Dialer loads as soon as the VPN service starts. When operating in fallback mode, the VPN Client does not check to see if the necessary Windows services have started. As a result, the VPN connection could fail if initiated too quickly. In fallback mode, when the VPN connection succeeds, you then press Ctrl+Alt+Del to get to the Microsoft logon dialog box. In this mode, you see the following VPN Client registry parameters and values:
HKLM\Software\Cisco Systems\VPN Client\GinaInstalled = 0PreviousGinaPath = msgina.dllIncompatible GINAs
If a new problem GINA is discovered after the VPN Client is released, you can add the GINA to the incompatible GINA list in the vpnclient.ini file. Adding the GINA to this list places it in the IncompatibleGinas list in the registry when you install the VPN Client and puts the VPN Client into fallback mode, thus avoiding possible conflicts (see section "oem.ini File Keywords and Values").
Programmer Notes
This section contains information to aid a programmer in writing programs that perform routine tasks.
Testing the Connection
As part of a program, you might want to test a connection to see if it is active before performing the tasks that are the purpose of the program. To test the connection, you can poll the TunnelEstablished entry in the HKEY_LOCAL_MACHINE registry.
To see this entry, bring up the Registry Editor and go to SOFTWARE > Cisco Systems > VPN Client. (See Figure 8-4.) In the list of entries, you see TunnelEstablished. This entry can have only two values: 1 or 0. If the connection is working, the value is 1; if not, the value is 0.
Figure 8-4 Cisco Systems VPN Client Registry Entries
Command Line Switches for vpngui Command—Windows Only
The vpngui command starts a connection from the command line by bringing up the VPN Client GUI application. You can use switches to specify parameters with this command. You must precede a switch with a forward slash (/) or hyphen (-). Non-Windows platforms allow only a hyphen prefix.
Table 8-2 lists the switches you can include in the vpngui command and describes the task that each switch performs. If the connection entry name contains spaces or other special characters, you must enclose the name in quotes. In the following examples, towork is the name of the connection entry.
IKE Proposals
Table 8-3 lists the IKE proposals that the VPN Client supports.
Table 8-3 Valid VPN Client IKE Proposals
Table 8-4 lists phase 2 proposals that the VPN Client sends.
Unit Client Application Program Interface
The VPN Client software includes an API that customers can use to perform VPN Client tasks without using the standard command-line or graphical interfaces that Cisco provides. The API comprises a shared library that programmers can link into their application, which allows it to:
•
•
•
•
The API comes with a programmer's user guide VPN Client: API Overview. This guide contains information enabling a programmer not familiar with the code base to use the API. The programmer's guide describes functions and data types, an overview of how to accomplish specific tasks, and easy to follow example programs.
