6.2 General Usage of vpncmd

This section describes the general usage of the vpncmd commands and how to display help for the command input rules.

6.2.1 Command Input Rules

Input Prompt

When vpncmd is ready to receive command input, the command prompt cursor (">") is displayed, and you can use the keyboard to enter a new command.

There are four prompt statuses, and these can be used to determine in which mode vpncmd is currently operating.

VPN Server Management Mode

This mode manages the entire VPN Server directly after establishing a management connection to VPN Server. The prompt in this mode is as follows.

VPN server>  

In this mode, you can only call the commands for managing the entire destination VPN Server, such as the ServerStatusGet and HubCreate commands. Approximately 60 commands are available in this mode.

By using the Hub command to select the Virtual HUB you want to manage in this mode, you can switch to the Virtual HUB management mode.

VPN Server>Hub VPN
Hub command - Select Virtual HUB to Manage
The Virtual HUB "VPN" was selected.
The command terminated normally.

VPN Server/VPN> 

Virtual HUB Management Mode

The Virtual HUB management mode is the mode in which the Virtual HUB specified when connecting to VPN Server in Virtual HUB management mode or the Virtual HUB selected using the Hub command is selected. The prompt in this mode is as follows.

VPN Server/Virtual Hub Name> 

In this mode, you can also call the commands for managing the Virtual HUB, such as the Online and SetMaxSession commands. In addition, you can call the same commands that are available in VPN Server management mode to manage the entire VPN Server. Approximately 170 commands are available in this mode.

To return to the VPN Server management mode from the Virtual HUB management mode, call the Hub command without adding an argument to the command line.

VPN Server/VPN>Hub
Hub command - Select Virtual HUB to Manage
The Virtual HUB selection was unselected.
The command terminated normally.

VPN Server> 

You can use nearly the same operations as described above for managing VPN Server to manage VPN Bridge. Because there is only one Virtual HUB on VPN Bridge, this Virtual HUB is always managed.

VPN Client Management Mode

When a management connection to VPN Client is established, the following prompt is displayed.

VPN Client>

You can use this mode to execute commands for controlling VPN Client. Approximately 65 commands are available in this mode.

VPN Tools Mode

By starting vpncmd in VPN Tools mode, you can start only the commands that can be executed locally on the computer where vpncmd is executed, without connecting to VPN Server or VPN Client. The following five commands are available in VPN Tools mode.

• About command
• MakeCert command
• TrafficClient command
• TrafficServer command
• Check command

These five commands can also be executed from other modes.

When operating vpncmd in VPN Tools mode, the following prompt is displayed.

VPN Tools> 

Exiting vpncmd

To exit vpncmd, type [exit].

Obtaining a List of Available Commands

To obtain a list of commands available in the current mode, type [Help] or [?].

VPN Tools>?
You can use the following 5 commands:
About - Display the version information
Check - Check if PacketiX VPN Operation is Possible
MakeCert - Create New X.509 Certificate and Private Key
TrafficClient - Execute Communication Throughput Measurement Tool Client
TrafficServer - Execute Communication Throughput Measurement Tool Server

To reference the usage for each respective command, input "command name /?" to display help.
The command terminated normally. 

Entering Commands

Enter commands at the vpncmd prompt as follows.

>command-name argument/parameter-name:argument/parameter-name:argument...

• Command Name
  This is the name of the command you want to call. The command name is not case sensitive. If the command name is too long to type, you can enter part of the command and use the function described later to automatically complete the command name.
• Argument (Parameter)
  You can specify an argument in some commands. There are two types of arguments: arguments without names and arguments with names.
  To specify an argument without a name, describe the argument content as a string after the command name.
  To specify an argument with a name, use the format "/argument-name:" to specify the argument name and colon (:) after the backslash followed by the argument content. You can substitute a hyphen (-) for the backslash. If the argument name is too long to type, you can enter part of the argument name and use the function described later to automatically complete the command name. The argument name is not case sensitive.
  Depending on the command, you can specify several arguments. In this case, separate the arguments with spaces. To include a space in an argument, enclose the argument content in double quotation marks (" ").

For example, the following are the input rules for the BridgeCreate command.

BridgeCreate [hubname] [/DEVICE:device_name] [/TAP:yes|no] 

The BridgeCreate command is called as follows when specifying [TEST] for the [hubname] argument without a name, [Intel(R) PRO/1000 MT Desktop Adapter] for the DEVICE argument, and [no] for the TAP argument

>BridgeCreate TEST /DEVICE:"Intel(R) PRO/1000 MT Desktop Adapter" /TAP:no 

The order of the arguments can be freely changed.

>BridgeCreate /DEVICE:"Intel(R) PRO/1000 MT Desktop Adapter" /TAP:no TEST 

When the above arguments are entered, for example, the same process is executed.

If an Argument is Omitted

In vpncmd, nearly all arguments can be omitted. Even when a required argument is omitted, no error occurs. Instead, a prompt is displayed for entering the contents of the omitted parameter. For example, when starting the abovementioned BridgeCreate command without an argument, the following prompt is displayed, and the user must specify the required items indicated in red below on the prompt.

VPN Server>BridgeCreate
BridgeCreate command - Create Local Bridge Connection
Virtual HUB Name to Create Bridge: TEST

Bridge Destination Device Name: Intel(R) PRO/1000 MT Desktop Adapter 

In the above example, the /TAP argument is not specified and a prompt asking for the contents of the /TAP argument is not displayed. Some arguments, such as this one, normally do not need to be specified. In this case, when a command alone is executed without adding an argument, the default values are used without asking for the contents in the displayed prompt. This type of operation is described in the command help.

For strings, such as passwords, that should not be displayed on the window, the text entered by the user is displayed on the prompt masked with asterisks (*).

Command Name Naming Convention

Over 200 commands can be used in vpncmd. Because it is difficult to remember all the commands, the naming convention of the commands in vpncmd is easy to understand, and you can display a list of commands for operating an object simply by specifying the object of the operation you want to perform. This eliminates the need to spend time learning the commands, as is the case for regular command line programs.

As a basic rule, the names of the commands in vpncmd follow the naming convention "operation-object-name operation-name". (This does not include some commands.)

For example, the command for obtaining server information is ServerInfoGet. The commands in vpncmd follow a naming scheme in which the type or name of the object for operation is followed by a verb indicating the operation, as shown in UserCreate (the command for creating a user), UserGet (the command for obtaining information about an existing user), UserDelete (the command for deleting a user), and UserList (the command for displaying a list of users).

If, for example, you forgot the command for deleting a user and want to display a list of commands for managing the users, you can enter the command shown below to display a list of user management commands and simple descriptions of each command.

VPN Server>user?
"user": The command is ambiguous.
The specified command name matches the following multiple commands.
UserAnonymousSet	- Set Anonymous Authentication for User Authentication Method
UserCertGet	- Get Certificate Registered for Individual Certificate
Authentication User
UserCertSet	- Set Individual Certificate Authentication for User 
Authentication Method and Set Certificate
UserCreate	- Create User
UserDelete	- Delete User
UserExpiresSet	- Set User's Expiration Date
UserGet		- Get User Information
UserList		- Get List of Users
UserNTLMSet	- Set NT Domain Authentication for User Authentication Method
UserPasswordSet	- Set Password Authentication for User Authentication Methodand 
Set Password
UserPolicyRemove	- Delete User Security Policy
UserPolicySet	- Set User Security Policy
UserRadiusSet	- Set RADIUS Authentication for User Authentication Method
UserSet		- Change User Information
UserSignedSet 	- Set Signed Certificate Authentication for User Authentication Method
Please re-specify the command name with more precision. 

Command Name Auto Complete Function (Specified with Prefix Search)

vpncmd has a large number of commands, and many of these commands have long names that are troublesome to enter. In this case, you can use the auto complete function to call a command by entering only part of the command name.

For example, if the command ServerPasswordSet is too long to type, you can type the first part of the command, and then a prefix search is performed based on the typed string. If the list of available commands is filtered to one command that can be called, that command name is completed and the command is automatically executed. In the case of ServerPasswordSet, typing the first six characters of the command, [ServerP], eliminates all other commands. Therefore, this command can be executed simply by typing [serverp].

If the prefix search results in two or more commands matching the entered command name and the specified command name cannot be filtered to one executable command, the message [The command is ambiguous. The specified command name matches the following multiple commands.] is displayed along with a list of commands matching the entered string and simple descriptions of those commands.

In this case, re-type the command name adding additional characters to filter the command name to a single executable command.

Command Name Auto Complete Function (Specified with Abbreviation)

The abovementioned auto complete function by prefix search can be helpful, but if there are multiple commands with the same long prefix string, then you have to type more characters, which can be inconvenient. By using the auto complete function with the abbreviation specification method, you can reduce the number of characters typed for a command name.

As an example of this method, consider the following three commands.

• RouterIfList [name]
• RouterIfAdd [name] [/HUB:hub] [/IP:ip/mask]
• RouterIfDel [name] [/HUB:hub]

Because the above three commands all start with the string "RouterIf", you have to specify the first eight characters, "routerif", when specifying the command name with the prefix search method.

To specify the commands with the abbreviation method, you can use the following abbreviations.

As can be seen in the above examples, when a vpncmd command consists of both upper and lowercase characters (as is the case for most of the commands), you can identify the command to be executed simply by specifying in order the uppercase characters of the command. (When typing the abbreviation, you can also use lowercase characters.)

Other long commands can also be abbreviated, as shown in the following examples.

In addition, while using the abbreviation method to call a command by its uppercase characters, if a single command to be executed can also be filtered using the prefix search, the command can be recognized simply by entering the first few characters of the abbreviation. For example, to call the LogPacketSaveType command, shown above, you can type the abbreviation [lpst] or the first few characters, [lps] or [lp].

By using these two methods, you can greatly reduce the number of characters you have to type to execute a command, and by learning the abbreviations of commands when executing the same command several times, you can learn how to quickly enter commands with few keystrokes.

Parameter Name Auto Complete Function

Similar to command names, parameter names (argument names) can also be specified with an abbreviation when the prefix search is successful. For example, a parameter specified with the SecureNATHostSet command is defined as follows.

NatSet [/MTU:mtu] [/TCPTIMEOUT:tcp_timeout] [/UDPTIMEOUT:udp_timeout] [/LOG:yes|no] 

In this command, you can specify the four arguments /MTU, /TCPTIMEOUT, /UDPTIMEOUT, and /LOG, but you can call the command with the arguments by specifying a few characters of the argument names that identify the arguments using the prefix search. Therefore, you can specify the four parameters in the example above with the following abbreviations.

Canceling the Displayed String Input Prompt or Password Entry Prompt

All parameters in the commands can be specified as a list of arguments, but when the required argument specifications are abbreviated, an entry prompt for specifying those items is displayed on the window at that time.

To cancel entry on the prompt and execution of that command, press Ctrl + D.

VPN Server>sps
ServerPasswordSet command - Set VPN Server Administrator Password
Please enter the password. To cancel press the Ctrl+D key.

Password: ***
Confirm input:^D
VPN Server> 

In the above example, pressing Ctrl + D cancels execution of the command and returns to the command prompt.

6.2.2 Command Help Display

Command Help

vpncmd has a large number of commands, and this manual contains references for the commands. In addition, vpncmd provides an online help for all commands to provide an understanding of the details of the commands quickly, without having to refer to this manual, in case you should forget the command names, the list of arguments that must be specified for commands, or the command operations when using vpncmd.

Displaying the Online Help for a Specific Command

If you know the command name, you can display the online help for that command by using any of the following methods.

• command-name --help
• command-name -help
• command-name /help
• command-name -?
• command-name /?
• command-name?
• man command-name
• ?command-name

The displayed contents are the same for all of the above methods; therefore, you can display the command help using familiar formats, such as [--help] or [/?].

The following is an example of help displayed for the BridgeCreate command.

Displaying a List of Available Command Names

If you are unsure of the names of available commands, you display a list of available command names in the current management mode by typing the following.

• man
• help
• ?

For example, the following displays the list of available command names in VPN Server management mode.

VPN Server>help
You can use the following 178 commands:
About - Display the version information
AcAdd - Add Rule to IP Access Control List
AcDel - Delete Rule from IP Access Control List
AcList - Get List of Rule Items of IP Access Control List
AccessAdd - Add Access List Rules
AccessDelete - Delete Rule from Access List
.
.(Abbreviation )
.
 UserSet - Change User Information
UserSignedSet - Set Signed Certificate Authentication for User A
uthentication Method

To reference the usage for each respective command, input "command name /?" to d
isplay help.
VPN Server>

If you know the first few characters of a command name, or the type of the object for operation, you can display a list of commands starting with that string by typing the following.

• prefix-string --help
• prefix-string -help
• prefix-string /help
• prefix-string -?
• prefix-string /?
• prefix-string?
• man prefix-string
• ?prefix-string

For example, to display a list of commands for cascade connection-related operations, type [cascade?].

VPN Server>help
You can use the following 178 commands:
About - Display the version information
AcAdd - Add Rule to IP Access Control List
AcDel - Delete Rule from IP Access Control List
AcList - Get List of Rule Items of IP Access Control List
AccessAdd - Add Access List Rules
AccessDelete - Delete Rule from Access List
.
.(Abbreviation )
.
 UserSet - Change User Information
UserSignedSet - Set Signed Certificate Authentication for User A
uthentication Method

To reference the usage for each respective command, input "command name /?" to d
isplay help.
VPN Server>

6.2.3 Command Line Parameters When Starting a vpncmd Command

You can also start a vpncmd command by adding any number of arguments. Normally, when vpncmd is started, a prompt for entering the IP address of the destination server or management mode is displayed, but by starting vpncmd with an added command line argument, you can automatically connect to a specified VPN Server and even execute a specified command and have the result written to a file.

6.2.4 Batch Processing Mode

Automation of Management and Necessity of Batch Processing

When a vpncmd command is started, normally a prompt for entering the command is displayed, and by entering the command in the prompt, you can then operate the destination VPN Server or VPN Bridge. In addition, VPN Client end users can start vpncmd and enter commands to control VPN Client.

These functions can be automated depending on the PacketiX VPN operation method. For example, with a large list of employee names in a CSV file, you can batch create an account for each individual in the Virtual HUB. Normally, this type of repetitive task using a GUI would take a significant amount of time, but by using the vpncmd batch processing function, you can execute several pre-defined commands at once.

In addition, you can call vpncmd from a separate program and automatically manage VPN Server. For example, you can call vpncmd to set the Virtual HUB of VPN Server online at a specified time and periodically save and record a snapshot of the summary of the session connected to the Virtual HUB to a text file.

Calling a Single Command Specified to vpncmd

After starting vpncmd, establishing a management connection to the service of the connection target, and calling a command, use the /CMD argument at vpncmd startup to perform simple operations, such as terminating the connection.

When the /CMD argument is specified to vpncmd, after connecting to VPN Server, VPN Client, or VPN Bridge, you can execute a command described later, instead of /CMD, to immediately exit vpncmd after that command is executed. For example, to connect to the "DEFAULT" Virtual HUB on VPN Server and create user "ABC", type the following and start vpncmd.

vpncmd /server Server Name /password:password /adminhub:DEFAULT
          /cmd UserCreate ABC /GROUP:none /REALNAME:none /NOTE:none

When this is performed, the command specified with /CMD is automatically executed and vpncmd is exited, as shown below.

Calling Multiple Commands Specified to vpncmd

To call one command, as described above, vpncmd must be started each time. Using this method to execute 1,000 commands at the same time, for example, requires high overhead processing in which the software has to start vpncmd 1,000 times, automatically connect to the server to be managed, execute the commands, and then terminate the connection and exit vpncmd, requiring a vast amount of time and making ineffective use of CPU and network resources.

But by describing multiple commands to execute at the same time as a text file in advance and specifying the file name of the text file as the /IN argument when starting vpncmd, you can automatically execute all commands described in the text file. After all commands are executed, vpncmd is exited.

For example, create the following file and save it with the file name [batch.txt]. When including multibyte characters (hiragana, kanji, etc.) in the file, as shown in this example, be sure to save the file in UTF-8 format.

Hub DEFAULT
UserCreate jiro /GROUP:none /REALNAME:"Tanaka" /NOTE:none
UserCreate yas /GROUP:none /REALNAME:"Shinjou" /NOTE:none
UserCreate idai /GROUP:none /REALNAME:"Kamishima" /NOTE:none
UserCreate yokote /GROUP:none /REALNAME:"Yokote" /NOTE:none
UserCreate ihihihi /GROUP:none /REALNAME:"Kinsei" /NOTE:none
UserCreate yuta /GROUP:none /REALNAME:"Yuta" /NOTE:none

Next, add a command line argument, as shown below, and start vpncmd.

vpncmd /server Server Name /in:batch.txt 

vpncmd starts, the commands in all lines are automatically executed in order, and then vpncmd is exited. After the commands in the above examples are executed, the users are registered at the same time.

Figure 6-2-1 Users Registered After Executing the batch.txt File

6.2.5 Saving a Log

When a file name is specified in the /OUT parameter as a command line argument at the time vpncmd is started, all output results displayed by vpncmd are saved to that file. This enables you to write the results of commands executed on vpncmd to an external file, and thereby record the vpncmd results and create an automated program for processing based on those results.

6.2.6 vpncmd Process Return Values

The vpncmd process returns the error code of the execution results for last executed command to the parent process. If a command is completed successfully, [0] is returned. For information about the error codes, please refer to 「12.5 Error Codes」.

6.2.7 Character Encoding

Character Encoding in Windows Version

The character encoding when the Windows version of the VPN program and other PacketiX VPN programs display messages and operation results and receive input from the user is automatically selected according to the operating system when a process is started or the regional options selected by the user.

Character Encoding in Unix Version

The character encoding when the Linux and other Unix versions of the VPN program and other PacketiX VPN programs display messages and operation results and receive input from the user is determined by the value of the LANG environment variable when a process is started. SoftEther Corporation guarantees operation only when the LANG environment variable is set to the following values.

• ja_JP.eucJP
• ja_JP.shift_jis
• ja_JP.UTF-8

When the LANG environment variable is not set or is not correctly recognized even if set, EUC-JP encoding is used. Before starting a process with PacketiX VPN software, check that the LANG environment variable is correctly set.

6.2.8 Calling vpncmd in Windows

After PacketiX VPN software is installed in Windows, starting the vpncmd.exe program installed in the installation directory (such as C:\Program Files\PacketiX VPN Server) starts vpncmd.

When vpncmd is started once with administrative rights, vpncmd can be started the next time by typing [vpncmd] in the command prompt or [Run...] dialog box.

In Unix operating systems, you can achieve the same effect by manually configuring the PATH environment variable or by configuring vpncmd and hamcore.se2 in a program folder, such as /usr/local/bin.

6.2.9 Stand-Alone Installation of vpncmd

Normally, vpncmd is automatically installed on the same computer on which VPN Server, VPN Client, or VPN Bridge is installed. However, you can use vpncmd as a stand-alone program on a separate computer by copying the files below to another computer. SoftEther Corporation recommends that instead of manually copying these files, you extract the exe-only version of VPN Bridge on Windows or the normal version of VPN Bridge on Unix operating systems to the computer on which you want to use vpncmd.

• vpncmd. exe executable file
  (vpncmd file in Unix version)
• hamcore.se2 file

PacketiX VPN 2.0 Online Manual 2.20.5320
Copyright © 2004-2007 SoftEther Corporation. All Rights Reserved.
 Contact Plat'Home for inquiries. | Support | Notes