Table Of Contents

Using the VPN Client Command-Line Interface

CLI Commands

Displaying a List of VPN Client Commands

Starting a Connection—vpnclient connect

Displaying a Notification—vpnclient notify

Displaying an Automatic VPN Initiation Configuration

Ending a Connection—vpnclient disconnect

Displaying Information About Your Connection—vpnclient stat

Return Codes

Application Example

Using the VPN Client Command-Line Interface

---

This chapter explains how to use the VPN Client command-line interface (CLI) to connect to a Cisco VPN device, generate statistical reports, and disconnect from the device. You can create your own script files that use the CLI commands to perform routine tasks, such as connect to a corporate server, run reports, and then disconnect from the server.

CLI Commands

This section lists each command, its syntax, and gives an example. It is organized by task.

Displaying a List of VPN Client Commands

To get a list of all VPN Client commands, go to the directory that contains the VPN Client software, and enter the vpnclient command at the command-line prompt:

C:\Program Files\Cisco Systems\VPN Client>vpnclient

Cisco Systems VPN Client Version 3.6

Copyright (C) 1998-2002 Cisco Systems, Inc. All Rights Reserved.

Client Type(s): Windows

Running on WinNT

Usage:

vpnclient connect <profile> [user <username>][eraseuserpwd | pwd <password>]

[nocertpwd] [notrayicon | sd] 

vpnclient disconnect

vpnclient stat [reset] [traffic] [tunnel] [route] [firewall] [repeat]

vpnclient notify

vpnclient verify [autoinitconfig]

Starting a Connection—vpnclient connect

To start a connection, enter the following command:

vpnclient connect <profile> [user <username>][eraseuserpwd | pwd <password>]

[nocertpwd] [notrayicon | sd] 

Table 4-1 lists the command options you can use with the vpnclient connect command, includes the task that each option performs, and gives an example of each option.

Table 4-1 Command Line Options

option	Definition	Notes and Examples
profile	Name of the connection entry (.pcf file), that you have previously configured. Required.	If the filename contains spaces, enclose it in double quotes on the command line. Example: vpnclient connect "to work"
user	Specifies a username for authentication; with the pwd option, suppresses the username prompt in authentication dialog. Optional.	Updates the username in the .pcf file with this name. However, if the name supplied is not valid, the VPN Client displays the authentication dialog on a subsequent request. Example: vpnclient connect user robron pwd siltango toVPN
eraseuserpwd	Erases the user password saved on the Client PC thereby forcing the VPN Client to prompt for a password. Optional.	You might have configured a connection with Saved Password to suppress a password prompt when connecting using a batch file. You can then use the eraseuserpwd to return to the more secure state of requiring password input from the console when connecting. Example: vpnclient connect eraseuserpwd toVPN
pwd	Specifies a password for authentication; with the user option on the command line, suppresses the password prompt in authentication dialog. Optional.	If the password supplied is not valid, the VPN Client displays the authentication dialog on a subsequent request. After encrypting and using the password for the connection, the VPN Dialer clears the password in the .pcf file. Using this option on the command line compromises security and is not recommended. Example: vpnclient connect user robron pwd siltango toVPN
nocertpwd	Suppresses prompting for a certificate password. Optional.	Example: vpnclient connect nocertpwd toVPN
notrayicon	Suppresses display of the dialer icon in the Windows system tray (lower right corner of your screen). Optional.	This parameter lets you suppress prompting when the connection is disconnected using the vpnclient connect command (see " Note on Notrayicon Parameter"). If you use this parameter, you cannot use the sd parameter. Example: vpnclient connect notrayicon toVPN
sd	Silent disconnect. Suppresses connection terminating messages, such as "Your IPSec connection has been terminated." Optional.	You can use this parameter to improve the automatic connection process. If you use this parameter, you cannot use the notrayicon parameter. Unlike the notrayicon, the sd option adds the lock icon to the system tray, which provides access to statistics and connection parameters. Example: vpnclient connect sd towork

Note on Notrayicon Parameter

When you connect using the vpnclient disconnect command, the connection icon (lock) displays in the system tray in the lower right corner of your screen. In this case, when you then use the vpnclient connect command to disconnect from the VPN device, the VPN Client displays the message:

Your IPSec connection has been terminated [OK].

You must then click vpnclient disconnect to continue.

However, if you include the Your IPSec connection has been terminated [OK]. argument in your command-line string, no icon appears in the system tray. When you disconnect, the above message does not occur. Also the "Disconnect VPN connection when logging off" feature is not in effect (see first Note).

---

Note When you use the notrayicon option either directly on the command line or in a batch file, make sure that you issue a vpnclient disconnect command before logging off or your VPN connection remains active.

---

---

Note If you click on the VPN Dialer option in the Cisco System VPN Client list of applications, after you have used the notrayicon on the command line, the lock icon appears on the system tray.

---

Example 4-1 vpnclient connect Command

This section shows an example of the vpnclient connect command that connects you to the Documentation Server using the profile name "Docserver."

C:\Program Files\Cisco Systems\VPN Client\vpnclient connect Docserver

Cisco Systems VPN Client Version 3.6

Copyright <C> 1998-2002 Cisco Systems, Inc. All Rights Reserved.

Client Type<s>: Windows

Running on WinNT

Initializing the IPSec link.

Contacting the security gateway at 10.10.10.1

Authenticating user.

At this point, the VPN Client displays an authentication dialog box that prompts for your username and password.

Figure 4-1 Authenticating a User

After you enter your name and password, authentication succeeds, and the command continues executing.

Contacting the security gateway at 10.10.10.1

Negotiating security policies.

Securing communication channel.

Your link is secure.

Example 4-2 vpnclient connect Command Using Parameters

The following command connects to the remote network without user interaction. Notice that the password appears on the command line in clear text.

C:\Program Files\Cisco Systems\VPN Client\vpnclient connect Docserver user ronrob pwd 
silvertango

Cisco Systems VPN Client Version 3.6

Copyright <C> 1998-2002 Cisco Systems, Inc. All Rights Reserved.

Client Type<s>: Windows, WinNT

Running on: 4.0.1381

Initializing the IPSec link.

Contacting the security gateway at 10.10.10.1

Authenticating user.

Contacting the security gateway at 10.10.10.1

Negotiating security policies.

Securing communication channel.

Your link is secure.

Displaying a Notification—vpnclient notify

When you connect using the notrayicon option, you can display a notification using the vpnclient notify command:

vpnclient notify

Example 4-3 vpnclient notify Command

The following session shows how to use the vpnclient notify command to display a notification from a network administrator.

C:\Program Files\Cisco Systems\VPN Client\vpnclient connect notrayicon Docserver

Cisco Systems VPN Client Version 3.6

Copyright <C> 1998-2002 Cisco Systems, Inc. All Rights Reserved.

Client Type<s>: Windows

Running on:  4.0.1381

Initializing the IPSec link.

Contacting the security gateway at 10.10.10.1

Authenticating user.

Contacting the security gateway at 10.10.10.1

Negotiating security policies.

Securing communication channel.

Your link is secure.

C:\Program Files\Cisco Systems\Vpn Client\vpnclient notify

Cisco Systems VPN Client Version 3.6

Copyright <C> 1998-2002 Cisco Systems, Inc. All Rights Reserved.

Client Type<s>: Windows

Running on:  4.0.1381

Notification:

Your network administrator has placed an update of the Cisco Systems VPN Client at the 
following location:

http://www.mycompany.com/clientupdate

Displaying an Automatic VPN Initiation Configuration

To display your configuration for auto initiation, enter the following command:

vpnclient verify autoinitconfig

---

Note If the mask in the output display does not match the value in the profile, then the mask is invalid. An invalid mask is displayed as 255.255.255.255

---

Example 4-4 vpnclient verify Command

The following command shows your auto initiation configuration for three access points.

c:\Program Files\Cisco Systems\VPN Client>vpnclient verify autoinitconfig

Cisco Systems VPN Client Version 3.6

Copyright <C> 1998-2002 Cisco Systems, Inc. All Rights Reserved.

Client Type<s>: Windows, WinNT

Running on: 4.0.1381

Auto-initiation Configuration Information.

Enable:	1

Retry Interval:	2

List Entry 0:	Network:	10.10.10.10

	Mask:	255.0.0.0

	Connection Entry:	"SalesA"

List Entry 1:	Network:	20.20.20.20

	Mask:	255.0.0.0

	Connection Entry:	"SalesB"

List Entry 2:	Network:	30.30.30.30

	Mask:	255.0.0.0

	Connection Entry:	"SalesC"

Ending a Connection—vpnclient disconnect

To disconnect from your session, enter the following command:

vpnclient disconnect

Example 4-5 vpnclient disconnect Command

The following command disconnects you from your secure connection.

C:\Program Files\Cisco Systems\VPN Client\vpnclient disconnect

Cisco Systems VPN Client Version 3.6

Copyright <C> 1998-2002 Cisco Systems, Inc. All Rights Reserved.

Client Type<s>: Windows

Running on:  4.0.1381

Disconnecting the IPSEC link.

Your IPSec link has been disconnected.

Displaying Information About Your Connection—vpnclient stat

To generate status information about your connection, enter the following command:

vpnclient stat [reset] [traffic] [tunnel] [route] [firewall] [repeat]

When entered without any of the optional parameters, the OK command displays all status information. The following parameters are optional:

notrayicon	Restarts all connection counts from zero. SA stats are not reset.
vpnclient notify	Displays a summary of bytes in and out, packets encrypted and decrypted, packets bypassed, and packets discarded.
vpnclient disconnect	Displays IPSec tunneling information.
vpnclient stat [reset] [traffic] [tunnel] [route] [firewall] [repeat]	Displays configured routes.
firewall	Identifies the type of filewall in use and displays information generated by the firewall configuration.
vpnclient stat	Provides a continuous display, refreshing it every few seconds. To end the display, press <ctrl-C>.

The following examples show sample output from the reset command. For more information on statistical output, see VPN Client User Guide for Windows.

Example 4-6 vpnclient stat Command

Following is an example of the information that the vpnclient stat command displays.

Example 4-7 vpnclient stat reset Command

The vpnclient stat reset command resets all connection counters.

Example 4-8 vpnclient stat traffic Command

Here is a sample of the information that the vpnclient stat traffic command generates.

Example 4-9 vpnclient stat tunnel Command

To display only tunneling information, use the vpnclient stat tunnel command. Here is a sample.

Example 4-10 vpnclient stat route Command

The vpclient stat route command displays information similar to the following display.

Example 4-11 vpnclient stat firewall Command

The vpnclient stat firewall command displays information similar to the following display.

Return Codes

This section lists the error levels (return codes) that you can receive when using the VPN Client command-line interface.

Return Code	Message	Meaning
200	SUCCESS_START	The VPN Client connection started successfully.
201	SUCCESS_STOP	The VPN Client connection has ended.
202	SUCCESS_STAT	The VPN Client has generated statistical information successfully.
203	SUCCESS_ENUMPPP	The enumppp command has succeeded. This command lists phone book entries when connecting to the Internet via dial-up.
1	ERR_UNKNOWN	An unidentifiable error has occurred during command-line parsing.
2	ERR_MISSING_COMMAND	Command is missing from command-line input.
3	ERR_BAD_COMMAND	There is an error in the command entered; check spelling.
4	ERR_MISSING_PARAMS	The command-line input is missing required parameter(s).
5	ERR_BAD_PARAMS	The parameter(s) in the command input are incorrect; check spelling.
6	ERR_TOO_MANY_PARAMS	The command-line input contains too many parameters.
7	ERR_NO_PARAMS_NEEDED	The command entered does not require parameters.
8	ERR_ATTACH_FAILED	Interprocess communication error occurred attaching to the generic interface.
9	ERR_DETACH_FAILED	Interprocess communication error occurred detaching from the generic interface.
10	ERR_NO_PROFILE	The VPN Client failed to read the profile.
11	ERR_PWD_MISMATCHED	Reserved
12	ERR_PWD_TOO_LONG	The password contains too many characters. The group password limit is 32 characters; the certificate password limit is 255 characters.
13	ERR_TOO_MANY_TRIES	Attempts to enter a valid password have exceed the amount allowed. The limit is three times.
14	ERR_START_FAILED	The connection attempt has failed; unable to connect.
15	ERR_STOP_FAILED	The disconnect action has failed; unable to disconnect.
16	ERR_STAT_FAILED	The attempt to display connection status has failed.
17	ERR_ENUM_FAILED	Unable to list phonebook entries.
18	ERR_COMMUNICATION_FAILED	A serious interprocess communication error has occurred.
19	ERR_SET_HANDLER_FAILED	Set console control handler failed.
20	ERR_CLEAR_HANDLER_FAILED	Attempt to clean up after a user break failed.
21	ERR_OUT_OF_MEMORY	Out of memory. Memory allocation failed.
22	ERR_BAD_INTERFACE	Internal display error.
23	ERR_UNEXPECTED_CALLBACK	In communicating with the Connection Manager, an unexpected callback (response) occurred.
24	ERR_DO_NOT_CONTINUE	User quit at a banner requesting "continue?"
25	ERR_GUI_RUNNING	Cannot use the command-line interface when connected through the graphical interface dialer application.
26	ERR_SET_WORK_DIR_FAILED	The attempt to set the working directory has failed. This is the directory where the program files reside.
27	ERR_NOT_CONNECTED	Attempt to display status has failed because there is no connection in effect.
28	ERR_BAD_GROUP_NAME	The group name configured for the connection is too long. The limit is 128 characters.
29	ERR_BAD_GROUP_PWD	The group password configured for the connection is too long. The limit is 32 characters.
30	ERR_BAD_AUTHTYPE	The authentication type configured for the connection is invalid.
31	RESERVED_01	Reserved.
32	RESERVED_02	Reserved.
33	ERR_COMMUNICATION_TIMED_OUT	Interprocess communication timed out.
34	ERR_BAD_3RD_PARTY_DIAL	Failed to launch a third-party dialer.
35	ERR_DAEMON_NOT_RUNNING (CVPND.EXE)—Non-Windows only	Connection needs to be established for command to execute.
36	ERR_DAEMON_ALREADY_RUNNING (CVPND.EXE)—Non-Windows only	Command cannot work because connection is already established.

Application Example

Here is an example of a DOS batch file (.bat) that uses CLI commands to connect to the corporate office from a branch office, run an application, and then disconnect from the corporate site.

runxls.bat

rem assume you have generated a report in the middle of the night that needs 

rem to be sent to the corporate office.

rem .. generate report.xls . .

rem connect to the home office

vpnclient connect sd myprofile

rem check return code from vpnclient call....

if %errorlevel% neq 200 goto failed

rem if okay continue and copy report

copy report.xls \\mycorpserver\directory\overnight_reports /v

rem now disconnect the VPN connection

vpnclient disconnect

echo Spreadsheet uploaded

goto end

:failed

echo failed to connect with error = %errorlevel%

:end