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.

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 [?].

Entering Commands

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

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.

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.

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.

VPN Server>server "server": The command is ambiguous. The specified command name matches the following multiple commands. ServerCertGet - Get SSL Certificate of VPN Server ServerCertSet - Set SSL Certificate and Private Key of VPN Server ServerCipherGet - Get the Encrypted Algorithm Used for VPN Communication. ServerCipherSet - Set the Encrypted Algorithm Used for VPN Communication. ServerInfoGet - Get server information ServerKeyGet - Get SSL Certificate Private Key of VPN Server ServerPasswordSet - Set VPN Server Administrator Password ServerStatusGet - Get Current Server Status Please re-specify the command name more strictly.

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.

Command Name

Abbreviation Example

RouterIfList

RIL

RouterIfAdd

RIA

RouterIfDel

RID

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.

Command Name

Abbreviation Example

LogPacketSaveType

lpst

RadiusServerSet

rss

SetMaxSession

sms

ClusterMemberInfoGet

cmig

ServerStatusGet

ssg

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.

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.

Argument Name

Abbreviation Example

/MTU

/M

/TCPTIMEOUT

/T

/UDPTIMEOUT

/U

/LOG

/L

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.

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.

[Description] Use this to create a new local bridge connection on the VPN Server. By using a local bridge, you can configure a Layer 2 bridge connection betwe en a Virtual Hub operating on this VPN server and a physical Ethernet Device (Network Adapter). You can create a tap device (virtual network interface) on the system and co nnect a bridge between Virtual Hubs (the tap device is only supported by Lin ux versions). It is possible to establish a bridge to an operating network adapter of your choice for the bridge destination Ethernet device (network adapter), but in high load environments, we recommend you prepare a network adapter dedicate d to serve as a bridge. To execute this command, you must have VPN Server administrator privileges.

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

[Parameter] hubname - Specify the Virtual Hub to create bridge. To get a list of Virtual Hubs, you can use the HubList command. It is not essential that y ou specify a Virtual Hub that is currently operating. If you speci fy a Virtual Hub name that is not currently operating or that does not exist, the local bridge connection will become enabled when t he actual operation of that Virtual Hub begins. /DEVICE - Specify the bridge destination Ethernet device (network adapter) o r tap device name. You can get the list of Ethernet device names b y using the BridgeDeviceList command. /TAP - Specify yes if you are using a tap device rather than a network ad apter for the bridge destination (only supported for Linux version s). When this is omitted, it will be treated the same as when no i s specified. VPN Server>

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.

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.

The brief of vpncmd command is described below.

vpncmd Command Reference

Command Name

vpncmd

Outline of Command

SoftEther VPN Command Line Management Utility

Explanation

Vpncmd program is a utility that allows you to manage SoftEther VPN software by using command lines. By using vpncmd, you can connect to a VPN Client, a VPN Server or VPN Bridge that is running on a local or remote computer and manage these services. Moreover, by using VPN Tools mode, you can call the speed measurement function, certificate creation function. These can be used even when not connected to the VPN Server or VPN Client. When using vpncmd, if the file name is specified by using the /IN and /OUT parameter, the command can be executed in a batch according to a file in which the executable commands are enumerated and the execution results can be written to a file. Normally a command prompt will appear after vpncmd is launched but when an input file is specified by the /IN parameter, the program will automatically terminate after the execution of all lines in the input file is complete. Also, when a command to execute is specified by the /CMD parameter, the program will automatically terminate after the execution of that command is complete. You cannot specify the /IN parameter and the /CMD parameter at the same time. The termination code of the vpncmd program will be the error code of the last executed command (0 in the case of successful execution). Under a Windows environment, when vpncmd is launched once or more by a user with administrator privileges, it is possible to simply input 'vpncmd' to a Windows command prompt or [Run...] window to launch vpncmd. To achieve the same result under a UNIX system, you manually set, as appropriate, the PATH environment variable.

By specifying parameters in the format [host name:port number], a connection will automatically be made to that host. If this is not specified, a prompt will appear to input the connection destination. When connecting to a VPN Client, you cannot specify a port number.

/CLIENT

This will connect to VPN Client to do management. You cannot specify to do this together with /SERVER.

/SERVER

This will connect to VPN Server or VPN Bridge to do management. You cannot specify to do this together with /CLIENT.

/TOOLS

This will enables use of VPN Tools commands. VPN Tools include a simple certificate creation tool (MakeCert command) and a communication speed measurement tool (SpeedTest command).

/Hub

When connecting to the VPN Server by [Virtual Hub Admin Mode], this specifies the Virtual Hub name 'hub'. If you specify the host name but not the /Hub parameter, connection will be by [Server Admin Mode].

/ADMINHUB

This will specify the name of the Virtual Hub 'adminhub' that is automatically selected after connecting to the VPN Server. If the /Hub parameter was specified, the Virtual Hub will be selected automatically and this specification will not be necessary.

/PASSWORD

If the administrator password is required when connecting, specify the password 'password'. When the password is not specified, a prompt to input the password will be displayed.

/IN

This will specify the text file 'infile' that contains the list of commands that are automatically executed after the connection is completed. If the /IN parameter is specified, the vpncmd program will terminate automatically after the execution of all commands in the file are finished. If the file contains multiple-byte characters, the encoding must be Unicode (UTF-8). This cannot be specified together with /CMD (if /CMD is specified, /IN will be ignored).

/OUT

You can specify the text file 'outfile' to write all strings such as onscreen prompts, message, error and execution results. Note that if the specified file already exists, the contents of the existing file will be overwritten. Output strings will be recorded using Unicode (UTF-8) encoding.

/CMD

If the optional command 'command_line...' is included after /CMD, that command will be executed after the connection is complete and the vpncmd program will terminate after that. This cannot be specified together with /IN (if specified together with /IN, /IN will be ignored). Specify the /CMD parameter after all other vpncmd parameters.

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

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.

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.

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.

6.2.7 Character Encoding

Character Encoding in Windows Version

The character encoding when the Windows version of the VPN program and other SoftEther 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 SoftEther 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 VPN Project 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 SoftEther VPN software, check that the LANG environment variable is correctly set.

6.2.8 Calling vpncmd in Windows

After SoftEther VPN software is installed in Windows, starting the vpncmd.exe program installed in the installation directory (such as C:\Program Files\SoftEther 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 VPN Project 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.