Cisco AnyConnect VPN Client Administrator Guide, Release 2.3
Customizing and Localizing the AnyConnect Client and Installer
Downloads: This chapterpdf (PDF - 1.18MB) The complete bookPDF (PDF - 4.44MB) | Feedback

Customizing and Localizing the AnyConnect Client and Installer

Table Of Contents

Customizing and Localizing the AnyConnect Client and Installer

Customizing the AnyConnect Client

Replacing Individual GUI Components with your Custom Components

Deploying Executables That Use the Client API

Customizing the GUI with a Transform

Sample Transform

Information for Creating your Custom Icons and Logos

Changing the Default AnyConnect English Messages

Localizing the AnyConnect Client GUI and Installer

Localizing the AnyConnect GUI

Translating using the ASDM Translation Table Editor

Translating by Exporting the Translation Table for Editing

Localizing the AnyConnect Installer Screens

Merging a Newer Translation Template with your Translation Table


Customizing and Localizing the AnyConnect Client and Installer


You can customize the AnyConnect VPN client and you can localize (translate) the client and the installer program for different languages.

This chapter contains the following sections:

Customizing the AnyConnect Client

Changing the Default AnyConnect English Messages

Localizing the AnyConnect Client GUI and Installer

Customizing the AnyConnect Client

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


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


You can use one of three methods to customize the client:

Rebrand the client by importing individual client GUI components, such as the corporate logo and icons, to the security appliance which deploys them to remote PCs with the installer.

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

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

The following sections describe procedures for these methods:

Replacing Individual GUI Components with your Custom Components

Deploying Executables That Use the Client API

Customizing the GUI with a Transform

Information for Creating your Custom Icons and Logos

Replacing Individual GUI Components with your Custom Components

You can customize the AnyConnect client by importing your own custom files to the security appliance, which deploys the new files with the client. Table 5-2, Table 5-3, and Table 5-4 contain sample images of the original GUI icons and information about their sizes. You can use this information to create your custom files.

To import and deploy your custom files with the client, follow this procedure:


Step 1 Go to Configuration > Remote Access VPN > Network (Client) Access > AnyConnect Customization/Localization > Resources.

Click Import. The Import AnyConnect Customization Object window displays (Figure 5-1).

Figure 5-1 Importing a Customization Object

Step 2 Enter the Name of the file to import. See Table 5-2, Table 5-3, and Table 5-4 for the filenames of all the GUI components that you can replace.


Note The filenames of your custom components must match the filenames used by the AnyConnect client GUI. The filenames of the GUI components are different for each OS and are case sensitive for Mac and Linux. For example, if you want to replace the corporate logo for Windows clients, 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.


Step 3 Select a platform and specify the file to import. Click Import Now. The file now appears in the table (Figure 5-2).

Figure 5-2 The Imported file displays in the Table

Deploying Executables That Use the Client API

For Windows, Linux, or Mac (PPP or Intel-based) PCs, you can deploy your own client that uses the AnyConnect client API. You replace the AnyConnect GUI or the AnyConnect CLI by replacing the client binary files. Table 5-1 lists the filenames of the client executable files for the different operating systems.

Table 5-1

Client OS
Client GUI File
Client CLI File

Windows

vpnui.exe

vpncli.exe

Linux

vpnui

vpn

Mac

Not supported1

vpn

1 Not supported by security appliance deployment. However, you can deploy an executable for the Mac that replaces the client GUI using other means, such as Altiris Agent.


Filenames of Client Executables

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. Because SBL is not supported for the CLI program, this affects only the GUI binary file.

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.

To import your executable to customize the client GUI, follow these steps:


Step 1 Go to Configuration > Remote Access VPN > Network (Client) Access > AnyConnect Customization/Localization > Binary.

Click Import. The Import AnyConnect Customization Objects window displays (Table 5-1).

Figure 5-3 Importing an Executable

Step 2 Enter the Name of the file to import.

The filenames of your executable must match the filenames used by the AnyConnect client GUI. For example, if you want to replace the client GUI for Windows clients, you must import your executable as vpnui.exe. If you import it as a different filename, the AnyConnect installer does not change the executable.

Step 3 Select a platform and specify the file to import. Click Import Now. The file now appears in the table (Figure 5-2).

Figure 5-4 The Imported Executable appears in the table

Customizing the GUI with a Transform

You can perform more extensive customizing of the AnyConnect client GUI (Windows only) by creating your own transform that deploys with the client installer program. You import the transform to the security appliance, which deploys it with the installer program.

To create an MSI transform, you can 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.

To import your transform, follow these steps:


Step 1 Go to Configuration > Remote Access VPN > Network (Client) Access > AnyConnect Customization/Localization > Customized Installer Transforms. Click Import. The Import AnyConnect Customization Objects windows displays (Figure 5-5).

Figure 5-5 Importing a Customizing Transform

Step 2 Enter the Name of the file to import. Unlike the names of other customizing objects, the name is not significant to the security appliance and is for your own convenience.

Step 3 Select a platform and specify the file to import. Click Import Now. The file now appears in the table (Figure 5-6).


Note Windows is the only valid choice for applying a transform.


Figure 5-6 The Customizing Transform Appears in the Table

Sample Transform

While offering a tutorial on creating transforms is beyond the scope of this document, we provide the text below as representative of some entries in a transform. These entries replace company_logo.bmp with a local copy and install the custom profile MyProfile.xml.

DATA CHANGE - Component Component ComponentId
+ MyProfile.xml {39057042-16A2-4034-87C0-8330104D8180}

Directory_ Attributes Condition KeyPath
Profile_DIR 0 MyProfile.xml

DATA CHANGE - FeatureComponents Feature_ Component_
  + MainFeature MyProfile.xml

DATA CHANGE - File File Component_ FileName FileSize Version Language Attributes Sequence
  + MyProfile.xml MyProfile.xml MyProf~1.xml|MyProfile.xml 601 8192 35
 <> company_logo.bmp 37302{39430} 8192{0}

DATA CHANGE - Media DiskId LastSequence DiskPrompt Cabinet VolumeLabel Source
  + 2 35

Information for Creating your Custom Icons and Logos

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


Note If you create your own custom images to replace the client icons, your images must be the same size as the original Cisco images.


For Windows

All files for Windows are located in %PROGRAMFILES%\Cisco\Cisco AnyConnect VPN Client\res\. Table 5-2 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-2 Icon Files for AnyConnect Client for Windows

Filename in Windows Installation
Client GUI Area Affected
Image Size (pixels, l x h)

AboutTab.ico

Icon that appears on the About tab.

16 x 16

company_logo.bmp

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

142 x 92

connected.ico

Tray icon that displays when the client is connected.

16 x 16

ConnectionTab.ico

Icon that appears on the Connection tab.

16 x 16

disconnecting.ico

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

16 x 16

GUI.ico

Icon that appears on the Windows Vista start-before-login screen.

48 x 48
32 x 32
24 x 24
16 x 16

reconnecting.ico

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

16 x 16

StatsTab.ico

Icon that appears on the Statistics tab.

16 x 16

unconnected.ico

Tray icon that displays when the client is not connected.

16 x 16


For Linux

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

Table 5-3 Icon Files for AnyConnect Client for Linux 

Filename in Linux Installation
Client GUI Area Affected
Image Size (pixels, l x h)

company-logo.png

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

142 x 92

cvc-about.png

Icon that appears on the About tab.

16 x 16

cvc-connect.png

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

16 x 16

cvc-disconnect.png

Icon that appears next to the Disconnect button.

16 x 16

cvc-info.png

Icon that appears on the Statistics tab.

16 x 16

systray_connected.png

Tray icon that displays when the client is connected.

16 x 16

systray_notconnected.png

Tray icon that displays when the client is not connected.

16 x 16

systray_disconnecting.png

Tray icon that displays when the client is disconnecting.

16 x 16

systray_reconnecting.png

Tray icon that displays when the client is reconnecting.

16 x 16

vpnui48.png

Main program icon.

48 x 48


For Mac OS X

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

Table 5-4 Icon Files for AnyConnect Client for Linux Mac OS X 

Filename in Mac OS X Installation
Client GUI Area Affected
Image Size (pixels, l x h)

bubble.png

Notification bubble that appears when the client connects or disconnects.

142 x 92

connected.png

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

32 x 32

logo.png

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

50 x 33

menu_connected.png

Connected state menu bar icon.

16 x 16

menu_error.png

Error state menu bar icon.

16 x 16

menu_idle.png

Disconnected idle menu bar icon.

16 x 16

menu_reconnecting.png

Reconnection in process menu bar icon.

16 x 16

warning.png

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

40 x 40

vpngui.icns

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

128 x 128


Changing the Default AnyConnect English Messages

You can make changes to the English messages displayed on the AnyConnect client GUI by adding an English translation table and changing message text within an editing window of ASDM.

The following procedure describes how to change the default English messages:


Step 1 Go to: Configuration > Remote Access VPN > Network (Client) Access > AnyConnect Customization/Localization > GUI Text and Messages. Click Add. The Add Language Localization Entry window displays (Figure 5-9).

Figure 5-7 Adding an English Translation Table

Step 2 Click the Language drop-list and specify the language as English (en). The translation table for English displays in the list of languages in the pane.

Step 3 Click Edit to begin editing the messages. The Edit Language Localization Entry window displays (Figure 5-8). The text between the quotes of msgid is the default English text displayed by the client, and must not be changed. The msgstr string contains text the client uses to replace the default text in msgid. You can replace the msgstr text with your own, custom text.

In the example below, we added "Call your network administrator at 800-553-2447".

Figure 5-8 Editing the Message Text

Step 4 Click Ok, and then Apply in the GUI Text and Messages pane to save you changes.

Localizing the AnyConnect Client GUI and Installer

You can translate messages displayed by the AnyConnect VPN Client or the client installer program in the language preferred by the remote user.


Note If you are deploying the AnyConnect client using a corporate IT deployment software, such as Altiris Agent, you can only translate the installer. You cannot translate the client. Client translation is only available when the security appliance deploys the client.


The following sections contain information and procedures for configuring this feature using the CLI or ASDM:

Localizing the AnyConnect GUI

Localizing the AnyConnect Installer Screens

Merging a Newer Translation Template with your Translation Table

Localizing the AnyConnect GUI

The security appliance uses translation tables to translate user messages displayed by the AnyConnect client. The translation tables are text files with strings to insert translated message text. The AnyConnect client package file for Windows contains an English language template for AnyConnect messages. The security appliance automatically imports this file when you load the client image. The file contains the latest changes to message strings 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 for the AnyConnect client. These files may not include the latest messages added by Cisco software engineers, but you can conveniently use them instead of creating new translation tables for these languages from scratch. You can edit these files with a text or translation editor like Poedit and then import them, or you can import them first and then edit them using the translation table editor in ASDM.

When the remote user connects to the security appliance and downloads the client, the client detects the preferred language of the PC and applies the appropriate translation table. The client detects the locale specified during installation of the operating system. For more information about language options for Windows, go to these URLs:

http://www.microsoft.com/windowsxp/using/setup/winxp/yourlanguage.mspx
http://www.microsoft.com/globaldev/reference/win2k/setup/changeUI.mspx


Note If you are not deploying the client with the security appliance, and are using a corporate software deployment system such as Altiris Agent, you can manually convert the AnyConnect translation table (anyconnect.po) to a .mo file using a catalog utility such as Gettext, and install the .mo file to the proper folder on the client PC.


The following sections contain detailed procedures for two different methods of translating GUI text:

Translating using the ASDM Translation Table Editor

Translating by Exporting the Translation Table for Editing

Translating using the ASDM Translation Table Editor

The following procedure describes how to localize the AnyConnect client GUI using ASDM:

Step 5 Go to: Configuration > Remote Access VPN > Language Localization. Click Add. The Add Language Localization Entry window displays (Figure 5-9).

Figure 5-9 Language Localization Pane

Step 6 Click the Translation Domain drop-list and choose AnyConnect (Figure 5-10). This ensures only the messages relating to the AnyConnect GUI appear for editing purposes.

Figure 5-10 Translation Domain

Step 7 Specify a language for this translation table (Figure 5-11). ASDM tags this table with the standard abbreviations recognized for languages by Windows and browsers (for example, es for Spanish).

Figure 5-11 Choosing a Language

Step 8 The translation table now displays in the list of languages in the pane (es in our example). However, it has no translated messages. To begin adding translated text, click Edit. The Edit Language Localization Entry window displays (Figure 5-12).

Add your translated text between the quotes of the message strings (msgstr). In the example below, we insert Connectado, the Spanish word for Connected, between the quotes of its message string.

Be sure to click Ok, and then Apply in the Language Localization pane to save you changes.

Figure 5-12 Editing the Translation Table

Translating by Exporting the Translation Table for Editing

This procedure shows you how to export the AnyConnect translation template to a remote PC, where you can edit the table using an editor or using third party tools such as Gettext or Poedit.

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.


Step 1 Export the AnyConnect translation template.

Go to Configuration > Remote Access VPN > Language Localization. The language localization pane displays (Figure 5-13). Click the Templates link to display a table of available templates. Select the AnyConnect template and click Export. The Export Language Localization window displays. Choose a method to export and provide a filename. In Figure 5-13, we export to a local PC with the filename AnyConnect_translation_table.

Figure 5-13 Exporting a Translation Template

Step 2 Edit the translation table.

The following example shows a portion of the AnyConnect template. The end of this output includes a message ID field (msgid) and a message string field (msgstr) for the message Connected, which appears on the AnyConnect client GUI when the client establishes a VPN connection (the complete template contains many pairs of message fields):

# SOME DESCRIPTIVE TITLE.
# Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
# This file is distributed under the same license as the PACKAGE package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2006-11-01 16:39-0700\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=CHARSET\n"
"Content-Transfer-Encoding: 8bit\n"

msgid "Connected"
msgstr ""

The msgid contains the default translation. The msgstr that follows msgid provides the translation. To create a translation, enter the translated text between the quotes of the msgstr string. For example, to translate the message "Connected" with a Spanish translation, insert the Spanish text between the quotes:

msgid "Connected"
msgstr "Conectado"

Be sure to save the file.

Step 3 Import the translation template as a new translation table for a specific language.

Go to Configuration > Remote Access VPN > Language Localization. The language localization pane displays (Figure 5-13). Click Import. The Import Language Localization window displays.

Step 4 Choose a language for this translation table. Click the Language drop-list to display languages and their industry-recognized abbreviations. If you enter the abbreviation manually, be sure to use an abbreviation recognized by browsers and operating systems.

Step 5 Specify the Translation Domain as AnyConnect, choose a method to import, and provide a filename. Click Export Now. A message displays saying you successfully import the table.

Be sure to click Apply to save your changes.

In Figure 5-13, we specify the language as Spanish (es) and import the same file we exported in Step 1 (AnyConnect_translation_table). Figure 5-15 shows the new translation table for Spanish in the list of Languages for AnyConnect.

Figure 5-14 Importing a Translation Template as a new Translation Table

Figure 5-15 New Language Displayed in Language Table

Localizing the AnyConnect Installer Screens

As with the AnyConnect client GUI, you can translate messages displayed by the client installer program. The security appliance uses transforms to translate the messages displayed by the installer. The transform alters the installation, but leaves the original security-signed MSI intact. These transforms only translate the installer screens and do not translate the client GUI screens.

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. Then you import the transform to the security appliance. When the user downloads the client, the client detects the preferred language of the PC (the locale specified during installation of the operating system) and applies the appropriate transform.

We currently offer transforms for 30 languages. These transforms are available in the following .zip file on the AnyConnect client software download page at cisco.com:

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

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

The package contains the transforms (.mst files) for the available translations. If you need to provide a language to remote users that is not one of the 30 languages we provide, you can create your own transform and import it to the security appliance as a new language. With Orca, the database editor from Microsoft, you can modify existing installations and new files. Orca 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.

The following procedure shows how to import a transform to the security appliance using ASDM:


Step 1 Import a Transform. Go to: Configuration > Remote Access VPN > Network (Client) Access > AnyConnect Customization/Localization > Localized Installer Transforms. Click Import. The Import MST Language Localization window opens (Figure 5-16).

Figure 5-16 Importing a Transform to Translate the Installer Program

Step 2 Choose a language for this transform. Click the Language drop-list to display languages and their industry-recognized abbreviations. If you enter the abbreviation manually, be sure to use an abbreviation recognized by browsers and operating systems.

Step 3 Click Export Now. A message displays saying you successfully import the table.

Be sure to click Apply to save your changes.

In Figure 5-16, we specify the language as Spanish (es). Figure 5-17 shows the new transform for Spanish in the list of Languages for AnyConnect.

Figure 5-17 Imported Transform Displays in the Table

Merging a Newer Translation Template with your Translation Table

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 to ensure your translation table has these new messages.

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 from Remote Access VPN > Language Localization > Templates. Export the template with the filename as AnyConnect.pot. This filename ensures that the msgmerge.exe program recognizes the file as a message catalog template.


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


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 from Remote Access VPN > Language Localization. Click Import, specify a language, and select AnyConnect as the Translation Domain. Specify the file to import as AnyConnect_merged.po.