Cisco AnyConnect VPN Client Administrator Guide, Release 2.2
Chapter 5, Customizing and Localizing the AnyConnect Client and Installer
Downloads: This chapterpdf (PDF - 380.0KB) The complete bookPDF (PDF - 4.6MB) | Feedback

Customizing and Localizing the AnyConnect Client and Installer

Table Of Contents

Customizing and Localizing the AnyConnect Client and Installer

Customizing the AnyConnect Client

Customizing an Individual PC

Customizing Using IT Deployment

Customizing Using Security Appliance Deployment

Language Translation for the AnyConnect Client and Installer

Translation Using IT Deployment

Translation Using Security Appliance Deployment

Merging the Template and Translation Table after AnyConnect Upgrade


Customizing and Localizing the AnyConnect Client and Installer


You can customize the AnyConnect VPN client and you can translate the client and the installer program into different languages. This section describes detailed configuration tasks in the following sections:

Customizing the AnyConnect Client

Language Translation for the AnyConnect Client and Installer

If you are deploying the client from the security appliance, remote users connect to the security appliance by establishing a browser-based clientless SSL VPN connection and then download the client. You may want to customize or translate the portal screen of the clientless connection also. For more information, see the Cisco Security Appliance Command Line Configuration Guide for CLI procedures or the ASDM selected topic Displaying Multiple Languages to SSL VPN Users for ASDM procedures.

Customizing the AnyConnect Client

You can customize the AnyConnect VPN client to display your own corporate image to remote users. You can customize the client running on Windows, Linux, and Mac OSX remote PCs.


Note Customization for the AnyConnect client running on a Windows Mobile device is currently not supported.


There are different approaches to customizing the AnyConnect VPN client depending on the way you deploy the client to user PCs:

Individual PC—You can manually replace files of logos and icons in the folders of the installed client. To do this, you need administrator privileges on the PC.
See Customizing an Individual PC.

IT deployment—If you are deploying the client via a corporate software deployment agent, such as Altiris Agent, you can create a transform (Windows only) that customizes the client and deploy it with the AnyConnect client and installer program.
See Customizing Using IT Deployment.

Security Appliance deployment—If you deploy the client using the security appliance, you can use one of three methods to customize:

Import rebranding components, such as the corporate logo and icons, to the security appliance which deploys them to remote PCs with the installer.

Import a transform (Windows only) that you create for more extensive rebranding. The security appliance deploys it with installer.

Import your own program (Windows and Linux only) that uses the AnyConnect API and customizes the GUI or CLI.

See Customizing Using Security Appliance Deployment.

Customizing an Individual PC

You can customize or rebrand certain elements, such as the corporate logo, of the AnyConnect client graphical user interface that the remote user sees upon logging in. You customize the AnyConnect Client user interface by replacing files that affect the interface with your own custom files, thus changing the appearance of the GUI by replacing the displayed images. For example, with a Windows installation, you can change the company logo from the default Cisco logo by replacing the file company_logo.bmp with your own file.

The tables that follow list the files you can replace for each operating system supported by the AnyConnect client.

For Windows

All files for Windows are located in %PROGRAMFILES%\Cisco\Cisco AnyConnect VPN Client\res\. Table 5-1 lists the files that you can replace and the client GUI area affected.


Note %PROGRAMFILES% refers to the environment variable by the same name. In most Windows installation, this is C:\Program Files.


Table 5-1 Customizing the AnyConnect VPN Client for Windows GUI 

Filename in Windows Installation
Client GUI Area Affected

company_logo.bmp

Corporate logo that appears on each tab of the user interface.

ConnectionTab.ico

Icon that appears on the Connection tab.

StatsTab.ico

Icon that appears on the Statistics tab.

AboutTab.ico

Icon that appears on the About tab.

connected.ico

Tray icon that displays when the client is connected.

unconnected.ico

Tray icon that displays when the client is not connected.

disconnecting.ico

Tray icon that displays when the client is in the process of disconnecting.

reconnecting.ico

Tray icon that displays when the client is in the process of reconnecting.


For Linux

All files for Linux are located in /opt/cisco/vpn/pixmaps/. Table 5-2 lists the files that you can replace and the client GUI area affected.

Table 5-2 Customizing the AnyConnect VPN Client for Linux GIU 

Filename in Linux Installation
Client GUI Area Affected

company-logo.png

Corporate logo that appears on each tab of the user interface.

vpnui48.png

Main program icon.

systray_connected.png

Tray icon that displays when the client is connected.

systray_notconnected.png

Tray icon that displays when the client is not connected.

systray_disconnecting.png

Tray icon that displays when the client is disconnecting.

systray_reconnecting.png

Tray icon that displays when the client is reconnecting.

cvc-info.png

Icon that appears on the Statistics tab.

cvc-disconnect.png

Icon that appears next to the Disconnect button.

cvc-connect.png

Icon that appears next to the Connect button, and on the Connection tab.

cvc-about.png

Icon that appears on the About tab.


For Mac OS X

All files for OS X are located in /Applications/Cisco AnyConnect VPN Client/Contents/Resources. Table 5-3 lists the files that you can replace and the client GUI area affected.

Table 5-3 Customizing the AnyConnect VPN Client for Mac OS X 

Filename in Mac OS X Installation
Client GUI Area Affected

bubble.png

Notification bubble that appears when the client connects or disconnects.

logo.png

Logo icon that appears on main screen in the top right corner.

menu_idle.png

Disconnected idle menu bar icon.

menu_connected.png

Connected state menu bar icon.

menu_reconnecting.png

Reconnection in process menu bar icon.

menu_error.png

Error state menu bar icon.

connected.png

Icon that displays under the disconnect button when the client is connected.

warning.png

Icon that replaces login fields on various authentication/certificate warnings.

vpngui.icns

Mac OS X icon file format that is used for all icon services, such as Dock, Sheets, and Finder.


Customizing Using IT Deployment

For IT deployment on Windows PCs, you can customize the AnyConnect client using a transform. You can rebrand the AnyConnect GUI by replacing the on-disk images displayed in the GUI with your own custom images. These are the same icons and bitmaps listed in Table 5-1, Table 5-2, and Table 5-3. The transform leaves the original security-signed MSI intact. Used in conjunction with the MSI, it provides what are, in effect, overrides to the installation.

To use an MSI transform, you must download and install the free database editor from Microsoft, named Orca. With this tool, you can modify existing installations and even add new files. The Orca tool is part of the Microsoft Windows Installer Software Development Kit (SDK) which is included in the Microsoft Windows SDK. The following link leads to the bundle containing the Orca program:

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/orca_exe.asp.

After you install the SDK, the Orca MSI is located here:

C:\Program Files\Microsoft SDK SP1\Microsoft Platform SDK\Bin\Orca.msi.

Install the Orca software, then access the Orca program from your Start > All Programs menu.

Customizing Using Security Appliance Deployment

You can customize the AnyConnect client by deploying files from the security appliance. You can change individual components on the AnyConnect client GUI (see Table 5-1, Table 5-2, and Table 5-3), deploy your own transform that makes more extensive changes (for Windows only), or deploy an executable file that uses the client API (Windows and Linux only).

The configuration tasks are the same for either of these methods, whether you use ASDM or CLI. For ASDM, go to Network (Client) Access > AnyConnect Customization (Figure 5-1). Then select one of these nodes in the navigation pane, depending on the method you are using.

Figure 5-1 shows the Import AnyConnect Customization Object window that you use to import a file for replacing individual components, such as the corporate logo:

Figure 5-1 Importing a Customization Object

Changing Individual Client Components

To change individual components that change the client appearance, such as the corporate logo, use the Resources node to import the files to change. The components are downloaded with the installer.


Note The filenames of your custom components must match the filenames used by the AnyConnect client GUI. For example, if you want to replace the corporate logo for Windows installations, you must import your corporate logo as company_logo.bmp. If you import it as a different filename, the AnyConnect installer does not change the component. For the filenames of the components used by the client GUI, see Table 5-1, Table 5-2, or Table 5-3.


To import components using CLI, use this command:

import webvpn AnyConnect-customization type resource platform {platform}
name {filename} {URL-of-file-to-import}

Deploying Windows Executables That Use the Client API

For Windows PCs, you can deploy your own client that uses the AnyConnect client API. You can replace the AnyConnect GUI or the AnyConnect CLI by replacing client binary files vpnui.exe and vpncli.exe, respectively.

For ASDM, use the Binary node to import the files.

To do this with CLI, use this command:

import webvpn AnyConnect-customization type binary platform win
name
{vpnui.exe | vpncli.exe} {URL-of-file-to-import}


Note In order for the security appliance to successfully download your custom Windows client, you must import your client as vpnui.exe or vpncli.exe.


We recommend that you sign your custom Windows client binaries (either GUI or CLI version) that you import to the security appliance. A signed binary has a wider range of functionality available to it. If the binaries are not signed the following functionality is affected:

WEB-Launch—The clientless portal is available and the user can authenticate. However, the behavior surrounding tunnel establishment does not work as expected. Having an unsigned GUI on the client results in the client not starting as part of the clientless connection attempt. And once it detects this condition, it aborts the connection attempt.

SBL—The Start Before Logon feature requires that the client GUI used to prompt for user credentials be signed. If it is not, the GUI does not start.

Auto Upgrade—During the upgrade to a newer version of the client, the old GUI exits, and after the new GUI installs, the new GUI starts. The new GUI does not start unless it is signed. As with Web-launch, the VPN connection terminates if the GUI is not signed. However, the upgraded client remains installed.

Deploying Linux Executables That Use the Client API

For Linux PCs, you can deploy your own client GUI or CLI by replacing client binary files vpnui and vpn, respectively.

For ASDM, use the Binary node to import the files.

To do this with CLI, use this command:

import webvpn AnyConnect-customization type binary platform linux
name
{vpnui | vpn} {URL-of-file-to-import}


Note In order for the security appliance to successfully download your custom Linux client, you must import your client as vpnui or vpn.


Customizing Via a Transform

To import a transform that you create (Windows only), use the Install node in ASDM. The security appliance deploys it with the installer. To import the transform using CLI, use this command:

import webvpn AnyConnect-customization type transform platform win
name {arbitrary-name} {URL-of-file-to-import}

The security appliance deploys the transform with installer.

Language Translation for the AnyConnect Client and Installer

You can display messages displayed by the AnyConnect VPN Client or the client installer program in the language preferred by the remote user. Language translation (localization) methods are different depending on the way you deploy the client to user PCs:

IT deployment—For installer translation, you download a pre-deploy version of a language translation package from the software download page of cisco.com, and you deploy the transforms with the client installer, applying the transform when the .msi is installed. See Translation Using IT Deployment.


Note If you are using IT deployment, you can only translate the installer. You cannot translate the client. Client translation is only available through security appliance deployment.


Security Appliance deployment—You download web-deploy versions of language translation packages from the software download page for the client and the installer. For client translation, you import the applicable translation tables to the security appliance. For installer translation, you import translation transforms. Both are downloaded by the security appliance to the remote PC with the client. See Translation Using Security Appliance Deployment

Translation Using IT Deployment

For IT deployment, you download a pre-deploy version of a language translation package from the software download page of cisco.com, and you copy the installer translation transform (.mst file) to the same folder as the AnyConnect Windows installer file (.msi file). Then you deploy the transforms with a deployment software (such as Altiris Agent) with the client installer, applying the transform when the .msi is installed. These transforms only translate the messages displayed by the client installer, not the AnyConnect GUI.

The MSI transforms (.mst files) are based on translations provided by Advanced Installer and must be applied to the corresponding English language .msi file.

The software download page on cisco.com has four sets of transforms, two for the client and two for the GINA, web-deploy and pre-deploy for each. For IT deployment, you want the pre-deploy files:

anyconnect-gina-win-<VERSION>-pre-deploy-k9-lang.zip
anyconnect-win-<VERSION>-pre-deploy-k9-lang.zip
 
   

In these files, <VERSION> is the version of AnyConnect release (e.g. 2.2.103).

Translation Using Security Appliance Deployment

The security appliance uses translation tables to translate user messages displayed by the AnyConnect client. The translation tables are XML files with strings to insert translated message text. The AnyConnect client package file contains an English language template for AnyConnect messages. The security appliance automatically imports this file when you load an AnyConnect client image. This file contains the latest changes and you can use it to create new translation tables for other languages.

We also provide translation tables for French and Japanese on the software download page at cisco.com These files may not include the latest changes, but you can conveniently use them instead of creating new translation tables from scratch. You can edit these files with a text or XML editor and then import them, or you can import them first and then edit them using the translation table editor in ASDM.

The security appliance uses transforms to translate the messages displayed by the installer program. Each language has its own transform. You can edit a transform with a transform editor, such as ORCA, and make changes to the message strings.

You import the translation tables and transforms to the security appliance for languages you want displayed. When the user downloads the client, the client detects the preferred language of the PC and applies the appropriate translation table or transform.

For Windows, the client detects the locale specified during installation of the operating system (the LANGUAGE env variable overrides locale). For non-Windows systems, the client detects the LANGUAGE variable.

Translation Templates and Upgrading the AnyConnect Client

Occasionally, we add new messages displayed to AnyConnect users that provide helpful information about the client connection. To enable translation of these new messages, we create new message strings and include them in the translation template packaged with the latest client image. Therefore, if you upgrade to the latest available client, you also receive the template with the new messages. However, if you have created translation tables based on the template included with the previous client, the new messages are not automatically displayed to remote users. You must merge the latest template with your translation table.

Convenient tools exist to help you merge the template and the translation table. The tools and procedure are covered in Merging the Template and Translation Table after AnyConnect Upgrade.

Required Tasks

The following sections describe the steps to import the translation tables and transforms to the security appliance:

Download translation packages (optional).

Import the translation table and transforms.

Customize the translations.


Step 1 Download translation packages (optional).

This step is only necessary if you want to use our translation tables for French and Japanese. Go to the software download page at http://www.cisco.com/cgi-bin/tablebuild.pl/anyconnect. Download the French or Japanese translation kit for the client. The kit includes the AnyConnect.po file, which you will import to the security appliance.


Note Although our pre-translated tables are convenient, they may not include the latest translatable fields of the client GUI. Those fields are included in the English language template file (AnyConnect.po) included with the client image. This file is automatically imported when you load a client image. Therefore, to ensure your translation table includes the latest translatable text, we recommend that you create a new translation table based on the AnyConnect.po file provided with the client image.


If you are also translating the installer program, download the translation package for the installer that is specified for web deployment. Two files are provided, one or the GINA and one for the installer:

anyconnect-gina-win-<VERSION>-web-deploy-k9-lang.zip
anyconnect-win-<VERSION>-web-deploy-k9-lang.zip
 
   

In these files, <VERSION> is the version of AnyConnect release (e.g. 2.2.103).

The package contains transforms (.mst files) for all available translations. You will import the files for the desired languages in the next step.

Step 2 Import the translation table and transforms.

Importing a Translation Table Using ASDM

See Figure 5-2.

Go to: Language Localization > Translation Tables (1). Click Import (2). The Import Language Localization window opens (3).

The AnyConnect.po file translates the AnyConnect client GUI. Specify the language with the same abbreviation used by the browser language options. For example, browsers use fr-ca as the abbreviation for French spoken in Canada. Use the same abbreviation for the translation table.

Specify the Translation Domain as AnyConnect. This ensures the security appliance applies the table to the AnyConnect client GUI.

In the Select a File area, specify the filename AnyConnect.po. Click Import Now to import the file.

Figure 5-2 Importing Translation Tables

Importing a Translation Table Using CLI

To import a translation table, use the import webvpn translation-table command from privileged EXEC mode. For example:

hostname# import webvpn translation-table anyconnect language fr-ca 
tftp://209.165.200.225/anyconnect
hostname# !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

Importing a Transform Using ASDM

Go to: Language Localization > MST Install Translation Tables. Click Import. The Import MST Language Localization window opens.

As with the translation tables, the abbreviation you specify for the language must be the same as the abbreviation in the browser language options. Specify the Translation Domain (formerly Localization Template Name) as AnyConnect. This ensures the security appliance applies the transform to the AnyConnect client installer.

Importing a Transform Using CLI

To import a translation table, use the import webvpn mst-translation command from privileged EXEC mode. For example:

hostname# import webvpn mst-translation anyconnect language fr-ca 
tftp://209.165.200.225/anyconnect
hostname# !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

Step 3 Customize the translations.

You can customize the translation tables or the transforms with your own translated text.

If you are using CLI or ASDM, you can export a translation table, edit the table with an XML or text editor, and reimport the table with your changes. In addition, ASDM has its own translation table editor. You can edit a table directly in the ASDM screen without exporting and reimporting the table.

To customize a transform using CLI or ASDM, you must export the transform, edit the transform with a transform editor, and reimport the transform. ASDM does not include an editor for transforms.

Customizing Translations Using ASDM

To use ASDM to customize a translation table, Go to Language Localization (Figure 5-3). Click Translation Tables (1). Select the translation table for the AnyConnect table and click Edit (2). The Edit Language Localization Entry window displays. Edit messages in this window (3).

Figure 5-3 Customizing a Translation Table

Customizing Translations Using CLI

To customize translations using CLI, you export a translation table or transform, make the changes using an editor, and import the files to the security appliance.

To export or import a translation table, use the export webvpn or import webvpn command with the translation-table keyword. For example:

hostname# export webvpn translation-table anyconnect language fr-ca 
tftp://209.165.200.225/anyconnect_french_canadian
hostname# !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
hostname# import webvpn translation-table anyconnect language fr-ca 
tftp://209.165.200.225/anyconnect_french_canadian
hostname# !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 
   

To export or import a transform, use the export webvpn or import webvpn command with the mst-translation keyword. For example:

hostname# export webvpn mst-translation anyconnect language fr-ca 
tftp://209.165.200.225/anyconnect_installer_french_canadian
hostname# !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
hostname# import webvpn mst-translation anyconnect language fr-ca 
tftp://209.165.200.225/anyconnect_installer_french_canadian
hostname# !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

Merging the Template and Translation Table after AnyConnect Upgrade

If you upgrade the AnyConnect client, and you created translation tables based on the template included with a previous client, the new messages are not automatically displayed to remote users. You must merge the template included with the latest client with the translation table you created previously.

You can use convenient third party tools to perform the merge. Gettext utilities from The GNU Project is available for Windows and runs in the command window. See the GNU website at gnu.org for more information. You can also use a GUI-based utility that uses Gettext, such as Poedit. This software is available at poedit.net. Both methods are covered in the procedure below.


Step 1 Export the latest AnyConnect Translation Template.

This step assumes you have already loaded the latest AnyConnect image package to the security appliance. The template is not available for export until you do.

Using ASDM, go to Remote Access VPN > Language Localization > Translation Tables. Choose Templates and select the AnyConnect template. Click Export and enter the filename as AnyConnect.pot. This filename ensures that the msgmerge.exe program recognizes the file as a message catalog template.

To export the template using CLI, use the export command from global EXEC mode. Export the file as AnyConnect.pot. For example:

hostname# export webvpn translation-table template anyconnect 
tftp://209.165.200.225/AnyConnect.pot
hostname# !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 
   

Step 2 Merge the AnyConnect Template and Translation Table.

If you are using the Gettext utilities for Windows, open a command prompt window and run the following command. The command merges the AnyConnect translation table (.po) and the template (.pot), creating the new AnyConnect_merged.po file:

msgmerge -o AnyConnect_merged.po AnyConnect.po AnyConnect.pot

The following example shows the results of the command:

C:\Program Files\GnuWin32\bin> msgmerge -o AnyConnect_merged.po AnyConnect.po 
AnyConnect.pot
....................................... done.
 
   

If you are using Poedit, first open the AnyConnect.po file; Go to File > Open > <AnyConnect.po>.
Then merge it with the template; go to Catalog > Update from POT file <AnyConnect.pot>.
POedit displays an Update Summary window with both new and obsolete strings. Save the file, which we will import in the next step.

Step 3 Import the Merged Translation Table

Using ASDM, go to Remote Access VPN > Language Localization > Translation Tables. Click Import, enter a Language and enter the Translation Domain as AnyConnect. Specify the new file created by the merge as the file to import.

To import the file using CLI, use the import command from global EXEC mode. For example:

hostname# import webvpn translation-table anyconnect language en 
tftp://209.165.200.225/AnyConnect_merged.po
hostname# !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!