VanDyke Software

Index

Configuring VShell^® for Windows as an SFTP backup server for Cisco Unified Communications Manager (CUCM)

The Backup Server for Cisco Unified Communications Manager (CUCM), formerly known as Cisco CallManager (CCM), has the ability to back up files to a server using the SFTP protocol. VShell provides secure file transfer capabilities, rock solid, reliable performance. This makes VShell for Windows a popular choice as the destination server for CUCM.

Please note: If using CUCM v9.x or later, VShell Workgroup or Enterprise editions may be required to accommodate the number of concurrent connections made by CUCM. It is also recommended that Disconnect idle sessions after ## minutes be enabled in the Common category of VShell's control panel.

Example Scenario

The following table provides the information that will be used within CUCM and VShell as the example scenario is created.

Server Hostname or IP Address	vshellserver.mydomain.com (TCP/IP hostname or IP address of the Windows machine running VShell)
Microsoft Windows Machine Name	VSHELLSERVER This is the name of the machine as it appears in a Microsoft network (a Workgroup or Domain). This name may be different than the TCP/IP hostname.
Username	Backupuser This is the username that will be used to log into VShell. This is a username (a user) that is created in Microsoft Windows.
Destination Folder	C:\CCM\Backup This is the file path on the server where files will be stored.
Folder Alias	CCM This is the name of the folder that CUCM will see, rather than the full name and path of the destination folder on the server.

Configuring VShell versions 4.5 and later

In VShell versions 4.5 and later, the VShell Windows installer includes a wizard that makes configuration of VShell for CUCM even easier.

While running the installer, simply choose the CUCM option on the VShell Usage Scenario page.

After installation is complete, the VShell CUCM Configuration Wizard will guide you through the configuration process.

You will be prompted for the username and password of the account that will upload files from CUCM to VShell. You will also be prompted for the location on the VShell server for CUCM files to be uploaded. During configuration, the wizard logs all changes it makes to a log file, for which you can specify the name and location.

If needed, the VShell CUCM Configuration Wizard can also be run from the command line after VShell is installed. From the VShell installation directory, run:

VShellCP.exe –launch_cucm_wizard

Alternatively, the configuration can be done manually using the VShell Control Panel, by following the instructions provided in the section on Configuring VShell versions 4.4 and earlier.

Configuring VShell versions 4.4 and earlier

In VShell versions 4.4 and earlier, the VShell Control Panel is used to configure the VShell SFTP server to receive backups from CUCM. The following steps show how to configure the VShell server so that the CUCM backup software SFTP client will be placed in the intended directory, lock the server down so that the SFTP client will only see its virtual root directory, not other users' virtual root directories, and lock down the Access Control category to provide only Logon and SFTP access:

1. Open the VShell control panel's Common / Virtual Roots category.
2. Disable the Use single virtual root option so that it's unchecked, as shown below.

3. Create a virtual root by pressing the Add button in VShell's Control Panel, Common / Virtual Roots. In the Virtual Root Path window, fill in the settings as described here:

1. Virtual root: C:\CCM\Backup
2. Alias: CCM
3. Press the Add Windows User/Group... button to add the user to the User/Group list. In our example, the username that the CCM will use to login is named backupuser. You can either type the username, or press the Advanced... button followed by the Find Now... button to select the username from a list.

4. The completed Virtual Root Path window is shown below. Note that your results will be slightly different. The username below appears as VSHELLSERVER\backupuser. That is because VSHELLSERVER is the Microsoft Windows machine name of the machine where the user is defined. If the user had been defined on a domain controller, for example EXAMPLEDOMAIN, then you would see the name of the EXAMPLEDOMAIN\backupuser instead of VSHELLSERVER\backupuser. Press the OK button.

4. Remove access to the <Unrestricted> virtual root for the user and all groups to which the user belongs.

1. Select <Unrestricted> in the Virtual Roots category and press the Edit button.
2. Select the user or group and press the Remove button. The default user allowed access to <Unrestricted> is the Everyone group, shown below.

3. After pressing the Remove button the user or group will not appear in the User/Group list.

5. Select the Common / Access Control category of the VShell control panel. Verify that the account which the Cisco CallManager client is configured to authenticate as is allowed Logon and SFTP permissions.

1. In the Access Control category add the user who will be logging in. This step is the same as step 3.c. Please refer to that section for review of how to add users.
2. Select the user in the Access Control category and enable Logon and SFTP.
3. Remove the Everyone group by selecting the Everyone group in Access Control and pressing the Remove button. The Access Control category should look like the following image if the steps have been followed to this point.

4. Press the Apply button to apply the changes, or the OK button to apply the changes and close the VShell Control Panel.

Configure Cisco Unified Communications Manager for Backup

The following steps are listed on Cisco's website to configure CUCM for SFTP network backup:

1. Log into the Disaster Recovery System of Cisco Unified Communications Manager
2. Choose a Backup Device
3. Click Add New
4. Enter the Network Directory information in the Select Destination section of the Backup Device window, and assign a name for the backup device.
5. Test the connection by initiating a backup from CUCM to VShell.

The following Cisco Unified Communications Manager Backup Server configuration window shows the client settings that would be used to connect to the VShell server with settings shown above.

Troubleshooting Tips

The following troubleshooting tips will help discover the cause of any problems encountered when the connection is tested. Before diagnosing problems, always enable Debug messages in the VShell control panel's Logging category.

1. Wrong home directory. Files aren't placed in the desired location. An example log file entry may resemble:
   Using home directory 'C:\Users\backupuser\Documents' for user vshell\backupuser

• This happens after the user successfully authenticates, but the user not being placed in the intended virtual root folder (e.g. C:\CCM) for the SFTP connection.
• Cause: The user (or a group that the user is a member of - such as the Everyone group) having access to the <Unrestricted> virtual root.
• Typical solution: Remove the Everyone group from the <Unrestricted> virtual root, in the VShell Control Panel's Common / Virtual Roots category, as discussed in step 4 of the Configure the VShell Server section above.

2. Unable to create files in backup directory on the VShell machine; VShell log states "Using home directory '{The virtual root}' for user ...

• This message appears following user authentication, when the CUCM/CCM client attempts to upload a file to the current directory on the VShell machine.
• Cause: VShell "Use single virtual root" option is enabled, placing the user in {The virtual root} which is a non-existent folder used to facilitate navigation among multiple virtual roots. Files cannot be written to this non-existent location.
• Typical solution: Disable Use single virtual root option in the VShell control panel's Common / Virtual Roots category, as discussed in step 2 of the Configure the VShell Server section above.

3. "The system cannot find the file specified" message appears as root cause of backup failure. The VShell log file entry may resemble the following two entries which often occur together:
   SFTP root alias 'CCM' maps to 'CCM' at 'C:\CCM\Backup' can not be accessed by user VSHELLSERVER\backupuser: The system cannot find the file specified.
   
   The user VSHELLSERVER\backupuser does not have any roots specified; the channel is being closed"

• This error occurs after successful authentication, immediately following initialization of the SFTP subsystem.
• Cause: Destination directory for the configured virtual root does not exist.
• Typical solution: Using the example from this document, the first step would be to verify that C:\CCM\Backup exists in the Microsoft Windows file system (e.g.: DIR C:\CCM\Backup).

4. Unable to create files in the backup directory: Access is denied ({The virtual root} does not appear in VShell's log file with Debug messages enabled). An example log file entry may resemble the following two consecutive entries which often occur together:
   SFTP root alias 'CCM' maps to 'CCM' at 'C:\CCM\Backup' can not be accessed by user VSHELLSERVER\backupuser: Access is denied.
   
   The user VSHELLSERVER\backupuser does not have any roots specified; the channel is being closed

• This error occurs after the user successfully authenticated and is being placed in a virtual root location.
• Cause: This is a file system error. VShell is reporting that the user does not have permission to access the real directory or file pointed to by the virtual root configuration.
• Typical solution: Verify that the Windows user account (e.g. VSHELLSERVER\backupuser) has NTFS permissions to access the folder.

5. Failed to stat file, Access is denied. VShell log file information may resemble the following pattern associated with the CUCM client's transfer attempt:
   Failed to stat file: './.' as user: backupuser System Error: Access is denied.
   Or
   Failed to stat file: '/CCM/.' as user: backupuser System Error: Access is denied.

• This error occurs after authentication, as the user is being placed in a virtual root.
• Cause: In VShell 3.8 and newer, file and directory permissions have been added to the Virtual Root Path window. Configured permissions here may not be set properly.
• Typical solution: Verify that the user has not been denied access to the virtual root folder in VShell's Virtual Root Path window by making sure that the user has a checkmark in the List, Create, Delete permission settings.

6. Unknown username or bad password, password rejected. An example VShell log file entry may display the following pair of messages.
   Authentication for VSHELLSERVER\backupuser failed: Logon failure: unknown user name or bad password.
   
   password for user VSHELLSERVER\backupuser rejected

• This error occurs during the authentication attempt
• Cause: The username is wrong, or the password is incorrect as configured in the CUCM client application setting.
• Typical solution: Verify the Windows user account's password. In CUCM "User name" configuration field you may need to scope the username as domain\username if it is a domain account.

Cisco Unified Operating System Administration and VShell

Cisco's Unified CallManager also provides an interface named Cisco Unified Operating System Administration. Cisco Unified Operating System Administration provides an Install/Upgrade option which may interact with VShell for Windows through SFTP. The Cisco Unified Operating System Administration tool connects to an SFTP server and performs a directory listing. It currently requires that the SFTP server it connects to report the directory listing in a "Unix" format. The Unix format is not the format proposed in the SFTP draft standard, but it is required by the client. In order to accommodate the Cisco Unified Operating System Administration Install/Upgrade client, the VShell administrator must make the following registry change.

Note: The VShell control panel must be closed before registry changes.

1. Start Regedit.exe
2. Open HKEY_LOCAL_MACHINE\Software\VanDyke\VShell\Server
3. Edit the registry option Use UNIX Format for SFTP File Listing
4. Change if needed to ensure the value is set to 1