Exporting and Importing the VShell for Windows Configuration

If you're a VShell administrator, you might need to export VShell configuration settings for a number of reasons, including:

To move VShell from one Windows machine to another.
To build a backup server.
To save a backup configuration prior to an upgrade.
To provide details needed by the VanDyke support team to help troubleshoot a problem you have reported.
To create a file that you can edit in order to specify desired subconfiguration settings for a particular user, group, or host.

When VShell's configuration is exported, it is saved as an XML file. When an export or import is done, a log file with the extension .log is generated in the same location as the XML file; it will contain any warnings or errors generated during the export or import process.

If you are running version 4.2 or later, you can export and import the VShell configuration directly from the Control Panel. With earlier versions, you will need to use the command-line utility VShellConfig.

Note: VShell configuration settings are stored in the Windows registry. You cannot export or import VShell configuration settings without Administrator privileges.

Complete vs. Partial Exports: To Export Sensitive Data or Not?

Before exporting VShell configuration settings, you must decide whether or not to include sensitive data such as private host keys, user database credentials, certificate files, and so on.

If you are writing out the VShell configuration in order to move or back up your server (e.g., reasons 1-3 above), you should do a complete export which includes sensitive data.

Starting with VShell version 4.2, you are required to enter a passphrase when performing a complete configuration export. VShell uses this passphrase to encrypt the sensitive data in the exported XML file. VShell requires that the same passphrase is provided when importing the configuration, so it is critical to be sure that the passphrase is kept securely and not lost.

With VShell versions earlier than 4.2, sensitive data in the configuration export is not encrypted. Therefore, it is very important to ensure that this file is not disclosed to any unauthorized persons.

However, if you are exporting the configuration to send to VanDyke, or to use as a basis for a subconfiguration file (e.g., reasons 4 and 5 above) you should do a partial export which does not include sensitive data.

Exporting VShell Configuration Settings

+ Instructions for VShell 4.2.0 and later

Select the Common category of the VShell Control Panel.
Press the Export… button.
When the Export VShell Configuration Settings dialog appears, choose either Partial or Complete depending on your objective (see previous section).
In the text box under Export to XML file:, specify the full path and filename for the XML file to be created.
Press the Export... button and wait for the export process to complete.

+ Instructions for VShell 3.0 through 4.1.x

Open an Administrator: Command Prompt window by right-clicking CMD and choosing Run as administrator.

Within the Administrator: Command Prompt window, run the VShellConfig executable using the export command as shown in one of the command examples below to create a file called MyConfig.xml in the current working directory.

Note: The VShell Installer installs VShellConfig into your VShell installation directory, and adds this directory to your path.

The general format for the command is:

vshellconfig [operation]

The syntax changed slightly in VShell version 3.9.2 to include or omit sensitive data.

+ VShellConfig command example for VShell 3.9.2 through 4.1.x

To do a complete export of the configuration from VShell 3.9.2 through 4.1.x including sensitive data:

vshellconfig export --include all MyConfig.xml

To do a partial export of the configuration from VShell 3.9.2 through 4.1.x without sensitive data:

vshellconfig export MyConfig.xml

+ VShellConfig command example VShell 3.0.0 through 3.9.1

To do a complete export of the configuration from VShell 3.9.1 and earlier including sensitive data:

vshellconfig export MyConfig.xml

To do a partial export in VShell 3.9.1 and earlier without sensitive data:

vshellconfig export --include registry MyConfig.xml

There are numerous VShellConfig options for including or excluding various settings and files during import or export. For example, if you are installing VShell on multiple servers and want to avoid installing the same host key on all machines, you can exclude the host keys during export by using the following command:

vshellconfig export --exclude host-keys MyConfig.xml

See the VShell Help file for details.

Importing VShell Configuration Settings

+ Instructions for VShell 4.2.0 and later

Select the Common category of the VShell Control Panel
Press the Import… button.
On the Import VShell Configuration Settings dialog specify the VShell configuration *.xml file that you exported earlier.
If the *.xml file contains a complete export, you will be required to enter the passphrase that was used when it was created.

+ Instructions for VShell 3.9.2 through 4.1.x

Open an Administrator: Command Prompt window by right-clicking CMD and choosing Run as administrator. Run the VShellConfig executable using the import command:

vshellconfig import --overwrite --include all myfilename.xml

Warning: the --overwrite flag will cause all files included in the xml file (potentially including the server hostkey) to replace those files on the current system, if they exist. The --overwrite flag should be omitted if this is not desired.

+ Instructions for VShell 3.0.0 through 3.9.1

Open an Administrator: Command Prompt window by right-clicking CMD and choosing Run as administrator. Run the VShellConfig executable using the import command:

vshellconfig import myfilename.xml

VanDyke Software