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 sample output for each command. It is organized by task.

Displaying a List of VPN Client Commands

To display 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:

Starting a Connection—vpnclient connect

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 Client 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
cliauth (Windows platforms only)	Prompts for authentication information on the command line. Eliminates the GUI prompt that displays during a connection request from the command line.	The VPN client prompts for username and password. The password is displayed as asterisks. Example: vpnclient connect cliauth towork

This example shows the vpnclient connect command that connects you to the Engineering Server using the profile name "engineering"

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

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

Alternatively, to suppress the User Authentication window shown in Example 4-1, you can use the cliauth parameter. The command line then prompts for username and password. Using the cliauth parameter avoids having a password display in clear text on the command line.

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

Displaying a Notification—vpnclient notify

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

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

Displaying an Automatic VPN Initiation Configuration—Windows Only

The following command shows your auto initiation configuration for one access point.

Suspending/Resuming Stateful Firewall (Windows Only)

The following commands control the setting of the stateful firewall. The first command output shows the response displayed when the stateful firewall is not enabled when the command is executed. The next two commands, executed after enabling the stateful firewall, first suspend the firewall and then resume it.

Ending a Connection—vpnclient disconnect

Displaying Information About Your Connection—vpnclient stat

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

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

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

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

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

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

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

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—Windows Only

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.

`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>.

Table of Contents