This chapter explains how to replace the Cisco Systems brand with your own organization's brand. When you install and launch the VPN Client software, you see your own organization name, program name, and application names on menus, windows, dialogs, and icons.
For the Windows platform, it also explains how to set up the software so that your users can install it automatically without being prompted. This feature is called silent install.
To customize the VPN Client software, you create your own distribution image combining the following elements, which this chapter describes.
For all platforms, you can customize the following:
Cisco Systems image that you receive on the Cisco Systems software distribution CD.
Your own portable network graphics (PNG) (Table 5-2) and icon files to replace the Cisco Systems brand.
For the Windows platform, you can also customize the following:
An oem.ini file that you create. Cisco supplies a sample oem.ini file that you can use as a template and customize.
setup.bmp—a bitmap file that displays on the first InstallShield® window when you install the VPN Client. (InstallShield only)
These elements should all be in the same directory and folder. Because some of the files may be too large to distribute the oem software on diskettes, we recommend that you make a CD ROM distribution image.
Customizing the VPN Client GUI for Windows
This section describes how to customize the VPN Client GUI for the Windows platform. To customize the GUI for the Mac OS X platform, see Customizing the VPN Client GUI for Mac OS X.
Customizing the VPN Client occurs when the VPN Client and installation program see a text file called oem.ini on your distribution image. The oem.ini file is patterned after Microsoft standard initialization files. You create the oem.ini file and supply your own text, PNG files, and icon files. When present, the oem.ini, PNG, and icon files are read when you first start the VPN Client. Since the VPN Client software reads these files when it first starts, the changes to them take effect only after you restart the VPN Client application.
Customizing replaces the following screen text, bitmaps, and icons.
Brand names on dialog boxes
Product names on dialog boxes
Organization logo on all dialog boxes
Graphic at the left end of the title bar
Icons on the system tray (at the bottom right of the screen) and the desktop (shortcut)
Installation Bitmap
The InstallShield uses a bitmap when installing the VPN Client software: the setup bitmap (setup.bmp).
Figure 5-1 shows the setup bitmap that displays as the first screen during installation via InstallShield.
Figure 5-1 Setup Bitmap
Program Menu Titles and Text
After installation, your organization or company, product, and application names appear in the Cisco Systems VPN Client applications menu. (See Figure 5-2.)
Figure 5-2 Applications menu
VPN Client
Figure 5-3 shows a lock image (title_bar.png), window title (AppNameText in the oem.ini file), and organization logo (logo.png file). The oem.ini file can replace the window title, the image at the left end of the title bar, and the organization or company logo in the VPN Client software. It can replace the open lock and closed lock icons in the system tray (see Figure 5-4 and Figure 5-5).
Figure 5-3 Three Types of Branding Changes
1
Title bar lock image (title_bar.png)
3
Organization logo (logo.png)
2
Window title (oem.ini file)
Figure 5-4 Closed Lock Icon on System Tray (connected.ico)
Figure 5-5 Open Lock Icon on the System Tray (unconnected.ico)
Setup Bitmap—setup.bmp
The InstallShield version of VPN Client includes a bitmap on the distribution CD that is not in the oem.ini file: setup.bmp. You can substitute your own image for this .bmp file, as long as you keep the current filename (setup.bmp) and make sure that the file is in the same directory and folder as the oem.ini file. This file displays a logo on the window when you start the InstallShield installation program. The size of the Cisco Systems setup bitmap is 330x330 pixels and it uses 256 colors.
Creating the oem.ini File
Your distribution CD must contain the oem.ini file for customizing. The oem.ini file contains the locations and names of bitmaps, icons, window titles, and screen text needed for customizing, all of which need to be in the same directory. When you install or start the VPN Client, the software checks to see if there is an oem.ini file. If so, the software scans it for bitmaps, icons, and text. If the oem.ini file lacks an element (for example, text for the product name), then the software uses whatever you have specified in the default section of the file. If no oem.ini file exists, the software defaults to Cisco Systems bitmaps, icons, and text.
Use Notepad or another ASCII text editor to create the oem.ini file and enter brand text and the names of your bitmap and icon files. See Table 5-1.
Note You can edit the oem.ini file that Cisco Systems supplies.
The format of the oem.ini file is the same as a standard Windows ini file:
Use a semicolon (;) to begin a comment.
Set values by entering keyword=value.
If you don't specify a value for a keyword, the application uses the default.
Keywords are not case-sensitive, but using upper and lowercase makes them more readable.
Sample oem.ini File
; This is a sample oem.ini file that you can use to overwrite Cisco Systems
; brand name on windows, bitmaps, and icons with your organization's brand
; name.
;
; This file has five sections: [Main],[Brand], [Default], [Dialer], and [SetMTU]
; Each section has keywords designating parts of the interface that the file replaces.
;
; The [Main] section determines whether kerberos uses TCP or UDP (the default).
[Main]
DisableKerberosOverTCP = 1
; The [Brand] section controls window titles during installation and in the
; destination folder for the product and applications.
;
[Brand]
CompanyText = Wonderland University
ProductText = Wonderland Client
;
; The [Default] section establishes the default bitmap and icon to use if
; assignments are left blank. This section also sets up silent installation.
; Silent mode installation proceeds without user intervention.
; The [Dialer] section controls the text and icons for the dialer software.
; AppNameText appears on the application selection menu. DialerBitMap
; appears on connection windows. AllowSBLLaunches controls whether a remote user can
; launch an application before connecting and logging on to a Windows NT platform.
;
[Dialer]
MainIcon=is_install.ico
AppNameText = Wonderland Dialer
AllowSBLLaunches = 0
;
; The [Set MTU] section controls the text and icon for the
; Set MTU applications. AppNameText appears on the application
; selection menu and the title screen. MainIcon appears on the window title.
; bar.
;
[Set MTU]
AppNameText = MTU Setter Application
MainIcon = MtuIcon.ico
AutoSetMtu = 1
SetMtuValue = 1300
MTUAdjustmentOverride = 144
oem.ini File Keywords and Values
Table 5-1 describes each part of the oem.ini file.
Table 5-1 oem.ini File Parameters
Keyword
Description
Value
[Main]
Optional field that identifies a section of the OEM.ini file to address special circumstances.
Keep exactly as shown.
DisableKerberosOverTCP=
InstallShield only
When installing the VPN Client on Windows, the installation program sets a registry value that forces windows to use Kerberos over TCP instead of UDP, the default. Some NAT devices, such as Linksys, do not support out-of-order IP fragments, which breaks Kerberos. With TCP, fragmentation is not required.
After the keyword and equal sign, enter either 1 or 0.
0 = keep the default, which is to force Kerberos to use TCP.
1 = prevent Kerberos from using TCP.
[Brand]
Required field that identifies the branding text that appears on window titles and descriptions throughout the client application.
Keep exactly as shown, as the branding section of the file.
CompanyText=
Identifies the name of your organization. If not present, the default is "Cisco Systems."
After the keyword and equal sign, enter the organization's name. The name can contain spaces and is not case sensitive.
ProductText=
Identifies the name of the application. If not present, the default is "VPN Client."
After the keyword and equal sign, enter the product name. The name can contain spaces and is not case sensitive.
[Default]
Required field that identifies the section that contains names of default bitmap and icon to use if values are blank.
Enter exactly as shown, as the default section of the file.
SilentMode=
InstallShield only
Specifies whether to activate silent installation.
After the keyword and equal sign, enter either 0 or 1. 1 activates silent installation:
0 = prompt the user during installation.
1= do not prompt the user during installation.
InstallPath=
InstallShield only
Identifies the directory into which to install the client software.
After the keyword and equal sign, enter the name of the directory in the suggested format:
root:\programs\company\product
DefGroup=
InstallShield only
Identifies the name of the folder to contain the client software.
After the keyword and equal sign, enter the name of the destination folder in the suggested format:
foldername
Reboot=
InstallShield only
Specifies whether to restart the system after the silent installation. If SilentMode is on (1) and Reboot is 1, the system automatically reboots after installation finishes.
After the keyword and equal sign, enter 0, 1, or 2:
0 = display the reboot dialog.
1 (and SilentMode = 1) = automatically reboot the system when installation finishes.
2 (and SilentMode = 1) = do not reboot after installation finishes.
[Dialer]
Required field that identifies the section that contains the name of the Dialer application, the bitmap to use on the connections window, and the connection icons.
Enter exactly as shown, as the Dialer section of the file.
AppNameText=
Identifies the name of the dialer application.
After the keyword and equal sign, enter the name of the dialer application. The name can contain spaces and is not case sensitive.
MainIcon=
This is used only by InstallShield for shortcuts to the vpngui.exe.
After the keyword and equal sign, enter the name of the icon file.
AllowSBLLaunches
InstallShield only
Specifies whether a VPN Client user is allowed to launch a third party application before logging on to a Windows NT platform.
After the keyword and equal sign, enter 1 to enable or 0 to disable this feature. The default is 0 (to disable). (See Note after table.)
[Set Mtu]
Required field that identifies the section that contains the name of the Set MTU application, the name of the Set MTU icon, and other settings.
Enter exactly as shown; identifies the Set MTU section of the file.
AppNameText=
Identifies the name of the Set MTU application.
After the keyword and equal sign, enter the name you want to give to this application. The name can contain spaces and is not case sensitive.
MainIcon=
Identifies the icon for the Set MTU title bar, About window, and applications menu. There are two sizes used: dimensions are 32x32 and 16x16 pixels; 256 colors.
After the keyword and equal sign, enter the name of the icon (.ico) file for this icon.
AutoSetMtu=
InstallShield only
Identifies whether to automatically set the MTU for all adaptors during installation using SetMTUValue.
After the keyword and equal sign, enter a value 0 or 1:
0 = do not set MTU; do not launch.
1 = set MTU and silently launch during installation. This is the default
SetMTUValue=
InstallShield only
Identifies the value to be used for all adapters bound to TCP/IP
After the keyword and equal sign, enter a value between 64 and 1500, inclusive. The default = 1300.
MTUAdjustOverride=
InstallShield only; Windows NT-based only.
Identifies the DNE MtuAdjustment parameter. This value identifies the amount the NIC's MTU is reduced.
After the keyword and equal sign, set to a value between 0 and 1300, inclusive. To use the SetMTU application to set the MTU for the TCP/IP protocol, set this parameter to 0.
Note When AllowSBLLaunches is 0, "Allow launching of third party applications before logon" under
Windows Logon Properties is unavailable. There might be cases when you need to launch an application
before starting your connection, for example, to authenticate your access credentials. In this case you
can use the following procedure:
In the VPN Dialer program, choose Options > Windows Logon Properties.
Uncheck Disconnect VPN connection when logging off.
Log out.
Log in with cached credentials.
Make your VPN Dialer connection.
Log out.
Log in again while already connected.
Table 5-2 lists the GUI image (portable network graphic) files that the VPN Client uses. If you want to replace any of them with your own image files, you must name your image files exactly as shown in the list; otherwise, the VPN Client GUI does not recognize them.
Table 5-2 Portable Network Graphic Files
PNG File
Description
splash_screen.png
Splash screen that appears for 2 to 5 seconds when the GUI starts. This screen contains a logo, product name and version, and copyright information.
title_bar.png
Image at the left end of the title bar
connected.png
Image next to connection entry when connection is active
logo.png
Organization logo for simple and advanced mode main dialogs
password_logo.png
Organization logo for password dialog (XAuth), group name and password)
profile_logo.png
Organization logo for new/modify profile dialog
status_down_arrow.png
Down arrow on the status bar of advanced mode, used to change the status bar display
cancel.png
Cancel button on advanced mode connection entries toolbar
connect_pressed.png
Connect button pressed on advanced mode connection entries toolbar
disconnect.png
Disconnect button on advanced mode connection entries toolbar
disconnect_pressed.png
Disconnect button pressed on advanced mode connection entries toolbar
new_profile.png
New button on advanced mode connection entries toolbar
new_profile_pressed.png
New button pressed on advanced mode connection entries toolbar
import_profile.png
Import button on advanced mode connection entries toolbar
import_profile_pressed.png
Import button pressed on advanced mode connection entries toolbar
modify_profile.png
Modify button on advanced mode connection entries toolbar
modify_profile_pressed.png
Modify button pressed on advanced mode connection entries toolbar
delete_profile.png
Delete button on advanced mode connection entries toolbar
delete_profile_pressed.png
Delete button pressed on advanced mode view certificates toolbar
import_certificate.png
Import button on advanced mode view certificates toolbar
import_certificate_pressed.png
Import button pressed on advanced mode view certificates toolbar
export_certificate.png
Export button on advanced mode view certificates toolbar
export_certificate_pressed.png
Export button pressed on advanced mode view certificates toolbar
delete_certificate.png
Delete button on advanced mode view certificates toolbar
delete_certificate_pressed.png
Delete button pressed on advanced mode view certificates toolbar
enroll_certificate.png
Enroll button on advanced mode view certificates toolbar
enroll_certificate_pressed.png
Enroll button pressed on advanced mode view certificates toolbar
verify_certificate.png
Verify button on advanced mode view certificates toolbar
verify_certificate_pressed.png
Verify button pressed on advanced mode view certificates toolbar
show_certificate.png
Show button on advanced mode view certificates toolbar
show_certificate_pressed.png
Show button pressed on advanced mode view certificates toolbar
enable_log.png
Enable button on advanced mode connection entries toolbar
enable_log_pressed.png
Enable button pressed on advanced mode view log toolbar
disable_log.png
Disable button on advanced mode view log toolbar
disable_log_pressed.png
Disable button pressed on advanced mode view log toolbar
clear_log.png
Clear button on advanced mode view log toolbar
clear_log_pressed.png
Clear button pressed on advanced mode view log toolbar
options_log.png
Options button on advanced mode view log toolbar
options_log_pressed.png
Options button pressed on advanced mode view log toolbar
show_log.png
Show button on advanced mode view log toolbar
show_log_pressed.png
Show button pressed on advanced mode view log toolbar
arrow_up.png
Up Arrow button in Backup Servers tab of the new/modify profile dialog
arrow_down.png
Down Arrow button in Backup Servers tab of the new/modify profile dialog
You can also replace the following icon files (as long as your icon files have these same names):
connected.ico—the tray icon when connected (also in resource file for vpngui.exe icon)
unconnected.ico—the tray icon when not connected
disconnecting.ico—the tray icon when disconnecting
Customizing the VPN Client Using an MSI Transform
This section describes how to customize VPN Client installation using a transform for the MSI. To customize the applications, you need both a transform and an oem.ini file.
Caution Do not modify the MSI file. To customize MSI, use a transform. Failure to follow recommended procedure will limit the level of support you can expect from Cisco.
Creating the Transform
To create the transform, you edit the vpnclient_en.msi file. You can create the transform with any commercially available MSI installation package, such as Wise or InstallShield. The procedure in this section uses the Microsoft ORCA editor available from the Microsoft Windows Installer SDK. The version used here is from Microsoft Platform SDK November 2001. So before you begin, make sure that ORCA is installed on your system. If you need information on transforms and ORCA, refer to the ORCA documentation.
Note This section does not include instructions on using ORCA. Do not attempt the following procedure
unless you have experience using ORCA. If you are unfamiliar with ORCA, we recommend that use
use an MSI installation package, such as Wise or InstallShield.
Here is the procedure:
Step 1 Start ORCA.
Step 2 Select File > Open and enter vpnclient_en.msi.
Step 3 Select Transform > Apply Transform and select oem.mst, the transform template.
To customize oem.mst, you modify some of the information you see in the tables. The parts to modify have green change bars on the left side of the row. Figure 5-6 shows a partial oem.mst file.
Figure 5-6 Editing the Tables in a Transform File
Table 5-3 outlines the changes to make in the tables in the oem.mst file. The columns in the table are defined as follows:
Table Name—the name of the table to edit
Changes Needed—a list of the changes to make to the table
Install Requirement—the entries that modify the installation software
Client Requirement—the entries that modify the way the VPN Client operates at runtime
Table 5-3 Oem.mst Tables
Table Name
Changes Needed
Modifies Install Parameters
Modifies VPN Client Runtime Parameters
Binary
top16—Add your own 500x63 bitmap for the MSI Install
side16—Add you own 501x314 bitmap for the MSI Install
Yes for both
No for both
Component
CsCoFile_OemFiles—needed to install oem.ini file for custom VPN Clients
CsCoFile_oempngFiles—needed to install icons, bitmaps, and png files
No
Yes
Directory
INSTALLDIR—Change to your own directory
INSTALLDIR2—Change to your own directory
Cisco_Systems_VPN_Client— Change to your own folder name
Yes for all
No for all
Feature Components
Complete | CsCoFile_OemFiles—needed to install oem.ini file for custom VPN Clients
CsCoFile_oempngFiles—needed to install icons, bitmaps, and png files
No
Yes
File
Add the following files for customizing the VPN Client. For examples, see the oem.mst transform and the oem.ini files.
Add the following icon files for customizing the VPN Client. These icons are for shortcuts on the Program Group. For examples, see the oem.mst transform and the oem.ini files.
MainIcon.ico setmtu.ico
No
Yes
Media
Add the following files for customizing the VPN Client. For examples, see the oem.mst transform and the oem.ini files.
ProductName—Supply company and product names for installation.
Manufacturer—Change publisher in the support information screen under Control Panel > Add/Remove Programs.
ARPURLINFOABOUT—Change the web page in the support information screen under Control Panel > Add/Remove Programs.
Yes
No
No
No
Yes
Yes
Shortcut
Dialer—Change the name and the icon for the VPN Dialer application.
SET_MTU—Change the name and the icon for the Set MTU application.
No for all
Yes for all
OEM.INI File and MSI
At run-time, you need an oem.ini file to tell the VPN Client to use OEM company and application names.
Copy your oem.ini file, the custom PNG files, and the custom icons to your distribution media, for example a CD, placing them in the same directory as the vpnclient_en.msi file. Use a transform to install the VPN Client, the oem.ini file, PNG files (Table 5-2), and icons, along with the VPN Client files during installation. For a sample oem.ini file, see "Sample oem.ini File." For more information on the oem.ini file, see Table 5-1.
Table 5-4 lists InstallShield-specific control parameters and how to achieve similar results in MSI. The oem.ini file modifies both InstallShield installation parameters and VPN Client runtime parameters. For MSI all oem.ini parameters are required except the installation-time parameters.
Table 5-4 Oem.ini File Keywords and MSI Equivalents
Keyword
MSI Equivalent
DisableKerberosOverTCP=
Transform Table: Property DISABLEKERBEROSOVERTCP
SilentMode=
Executing MSI installation using the /q switch For example:
Installing the VPN Client Without User Interaction
This section describes how to produce installation without user interaction for both InstallShield installations and MSI installations. Installing the VPN Client without user interaction is called silent mode. In silent mode, no messages or prompts appear on the screen.
Note You can launch silent installation from the command line by using the -sd parameter with the
vpnclient.exe command. For example, vpnclient -sd toVPN. For information on the vpnclient
command, refer to "Using the VPN Client
Command-Line Interface".
Silent Installation Using InstallShield
To implement silent mode with or without customizing the VPN Client applications, you can create an oem.ini file containing only the part that configures silent mode. In this file, you turn silent mode on, identify the pathname and folder to contain the VPN Client software, and reboot the system, all without user interaction.
During silent mode installation, the installation program does not display error messages. The program stores error messages in a log file named VPNLog.txt located in the windows system directory (WINSYSDIR).
Note If the installation program detects a 2.x version of the VPN Client, the program still prompts the user
for input when converting the connection entry profiles.
A sample oem.ini file for implementing silent mode follows:
Identifies whether to activate noninteractive installation.
After the keyword and equal sign, enter either 0 or 1. 1 activates silent installation:
0 = prompt the user during installation.
1= do not prompt the user during installation.
InstallPath=
Identifies the directory for the client software installation.
After the keyword and equal sign, enter the name of the directory in the suggested format:
root:\programs\organization\product
DefGroup=
Identifies the name of the folder to contain the client software.
After the keyword and equal sign, enter the name of the destination folder in the suggested format:
foldername
Reboot=
Identifies whether to restart the system after the silent installation. If SilentMode is on (1) and Reboot is 1, the system automatically reboots after installation finishes.
After the keyword and equal sign, enter 0, 1, or 2:
0 = display the reboot dialog.
1 (and SilentMode = 1) = automatically reboot the system when installation finishes.
2 (and SilentMode = 1) = do not reboot after installation finishes.
Silent Installation Using MSI
To install the VPN Client without dialogs and messages (user interface) displaying on the screen, you can use either of the two following commands on the command line.
msiexec.exe /q [n|b|r|f] /i vpnclient_en.msi
or
vpnclient_en.exe /q [n|b|r|f]
Option
What it Displays
q or qn
No user interface. It is advisable to enable logging to determine whether the installation succeeded, since this option eliminates all information including fatal error messages.
qb
The basic user interface, which is a limited progress dialog that Windows Installer generates. It is advisable to enable logging with this option as well.
qr
Reduced user interface, similar to the full user interface option, but includes only a subset of all dialogs. For example, this option displays the welcome, license agreement, destination folder, and start dialogs, but does not let the user change the destination folder.
qf
Full or complete user interface including all dialogs. This is the default setting.
Launching SetMTU with Silent Installation
The SetMTU utility is automatically launched in silent mode with the value of 1300 for all installed adapters. To disable the SetMTU utility during installation, set the LAUNCHSETMTU property on the command-line to 0. To modify the MTU value, set SETMTUVALUE to value. To override the DNE MtuAdjuistment parameter, which is set to 0, set DNEMTUADJUSTMENT to value.
For example, to disable SetMTU and set the DNE Mtuadjustment to 144, execute the following command:
To customize the VPN Client GUI for the Mac OS X platform, place the custom images in the Resources folder of the installer directory.
Figure 5-7 shows the vpnclient installer directory. This directory contains the installer package and any preconfigured files in the Profiles and Resources folders.
The Resources folder contains all images for the VPN Client.
Figure 5-7 VPN Client Installer Directory
To distribute custom images, replace the image files in the Resources folder with your own custom images. For example:
To customize the logo, replace the file /etc/CiscoSystems/Resources/logo.png with your own custom logo.
To customize the splash screen, replace the file /etc/CiscoSystems/Resources/splash_screen.png with your own custom splash screen.
When the VPN Client is installed, the images in the Resources file are used for the client GUI.
