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 disconnect` 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 connect 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 disconnect command to disconnect from the VPN device, the VPN Client displays the message:

Your IPSec connection has been terminated [OK].

You must then click OK to continue.

However, if you include the notrayicon 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 vpnclient stat command displays all status information. The following parameters are optional:


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

The following examples show sample output from the vpnclient stat 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

Table Of Contents