This is an Internal Installation Guide! This document is written for use by 3Com internal users.

The procedures described are not necessarily suited for field use and are not intended to be performed by customers. Access to 3Com internal networks and accounts on restricted servers may be required. Failure to follow all procedures exactly may result in a VCX server which does not work properly and may not be supported by 3Com.

VCX 7.1 Disk Build HOWTO

Release Date 10/18/2006 This document is intended for use with VCX 7.1 and VCX Linux 5.X. It was last updated for: VCX Linux 5.5.0, VCX build 7_1_29_29. This document is not updated with every new build, but rather when procedures have changed or there is new information. If using an earlier release, please consult the appropriate previous version of this document. If using a later release, check Docushare to see if a newer version is available.

1 Overview.......................................................................................................................................................2 2 FTP Server/File Locations.............................................................................................................................3 3 Starting the Installation (non-W1).................................................................................................................4 4 Starting the Installation (W1 only)................................................................................................................6 5 Installation Procedure....................................................................................................................................9 6 Booting & Configuration.............................................................................................................................10 7 VCX Installation..........................................................................................................................................12 8 Odds and Ends.............................................................................................................................................13 9 Appendix A: Building a FRU disk..............................................................................................................14 Revision History 24-Jan-2006 Brett B. Bonner 08-Feb-2006 18-Oct-2006 Brett B. Bonner Brett B. Bonner

Created based on VCX 7.0 Disk Build HOWTO Add boot options for 306/346 Knoppix 4.0.2, reference UPS Monitoring feature & functional spec Add x3650 support information

VCX 7.1 Disk Build HOWTO Page 1 of 16

1 Overview
This document describes how to build a VCX system disk, including installation of the OS and VCX components. These instructions are suitable for use in building Master Disks for use by customers, as well as for building systems for internal use. In addition, Appendix A describes the procedure for building a FRU disk. A FRU (Field Replaceable Unit) disk is a different form of master disk, which has the ability to be configured to any supported software version and configuration type in the field.

1.1 Whats New for 7.1

1.1.1 New Hardware Support
VCX is now supported on the IBM x306m hardware platform. This is a new IBM model which replaces the venerable x306. The x306m compares to the x306 as follows: The x306m is a "next generation" redesign from IBM. The CPU is still a 3.2GHz "Prescott" CPU, the same as in the x306. There is a different chipset, but this is transparent to VCX The x306m uses faster memory (PC4200 vs. PC2700), which may help performance slightly There is no built in floppy disk. VCX does not use a floppy, so this has no impact. The x306m offers IPMI support (Intelligent Platform Management Interface) - this gives us the capability to monitor hardware status, with the right driver and tools. Support for this is not specified as a 7.1 requirement, however. The disk subsystem is slightly different. The x306m that we are specifying (model 8849-30U) is still a "simple swap SATA" disk but the disk controller (part of the chipset) is different and the disks are not physically interchangeable with the x306 because the carriers are different. We are expecting to move to a larger, 160GB disk on this platform, because the cost is about the same as an 80G disk. Note that other models of x306m offer SAS (Serial Attached SCSI) disks, which use a very different controller. These are not supported for use with VCX. There is a different Ethernet controller - a Broadcom chip is used in place of the x306's Intel e1000.

The x306m has faster PCI/X slots - this doesn't matter to VCX as we do not use any PCI cards. Starting with VCX Linux version 5.5.0, VCX is also supported on the IBM x3650 hardware platform. This is a new IBM model which replaces the x346. The chosen model for VCX is a 7979-51U. The x3650 compares to the x346 as follows: The 3650 offers one or two, dual core, Intel Xeon 5140 Woodcrest processors, with a much faster 1333MHz FSB. This offers the potential of up to four processing cores. The global workhorse model which we are using for VCX uses 2.33GHz processors, but the dual cores, faster FSB, and architecture changes should provide improved performance over the x346. The system uses DDR2-667 PC2-5300 fully buffered memory. Disk drives are SAS (Serial Attached SCSI) instead of U320-SCSI. Note that although some models of x3650 support 2.5 SAS drives, the -51U model uses 3.5 disks. There is no built in floppy disk. There is a different Ethernet controller (Broadcom 5708 NetXtreme II) The system no longer offers legacy PS/2 keyboard and mouse connectors, but expects use of a USB keyboard and mouse. The may affect some users; however, a serial port is still available and will be configured as the default console for customers. As with the x346 and x306m, a BMC (baseboard management controller) with IPMI support is included. See the notes on IPMI under the x306m section, above.

VCX 7.1 Disk Build HOWTO Page 2 of 16

Although the base unit has basic hardware RAID (0/1/10) capability, we do not plan on supporting this for VCX at this time, since the existing VCX RAID implementation offers good performance and the benefit of consistency across all platform types.

Other differences, such as PCI slot configuration, exist but are not relevant to VCX usage. VCX Linux and VCX are, of course, still supported on prior platforms including the x306, x346, x345, and V6000 (W1). However, VCX 7.1 will ship on new systems only on the x306m, x346, and V6000. A transition from x346 to x3650 will occur in late 2006/early 2007.

1.1.2 UPS Monitoring

UPS Monitoring is supported in build 7_1_2_2 and newer. This feature allows one or more VCX systems to monitor one or more UPS systems over the network, and to shut down cleanly if the UPS power is running out. See the UPS Monitoring Functional Specification (http://docushare.ne.3com.com/dsweb/Get/Document227074) for details.

1.1.3 Audit Trails changes

VCX Linux now uses the syslog-ng (next generation) daemon for principal system logging including /var/log/messages and /var/log/secure. In accordance with the Audit Trails Functional Specification, a parallel log is kept in XML format for use in presenting these via the Provisioning interface. Additionally: Per the specification, 1 month (5 weeks) of logs are kept. Previously, logrotate was configured to preserve 52 weeks of logs. The Linux Auditing Subsystem (LAuS) is enabled by default.

1.1.4 Backup and Restore

Configuration backup and restore allows all VCX configuration files to be backed up to one file, with a single command. Note that this does not include database or voicemail, which have their own backup commands and procedures. See the VCX 7.1 Configuration Backup/Restore Functional Specification & High Level Design document for details.

1.1.5 Other changes

Shadow passwords are now used in VCX Linux. When VCX Linux 5.x is installed as an upgrade, the passwords will be converted to the shadow format automatically and shadow passwords will be used in the 5.x OS.

1.2 About the Installation

The installation procedure is automated and uses a script to perform nearly all of the operations required for installation. This is fast and easy. Be aware, however, that this script will completely reconfigure the disk and is therefore not suitable for development or other systems which have partitions that must be preserved. In addition to reading this document, please consult the ERRATA.txt file (if one exists) for the current VCX Linux release, which describes changes, known problems and, where possible, solutions/workarounds. This can be retrieved from the same location as the VCX Linux image.

2 FTP Server/File Locations

Several files will be required to perform the VCX Linux installation. These are located on an FTP server and FTP will be used during the installation to retrieve the files. VCX Linux is primarily distributed from the same server (usand006w2k.ne.3com.com) used for distributing VCX builds. Note that access to this server is restricted; a PVT login is required. A Rolling Meadows mirror is available on mselvarag.wan.3com.com. There will be a time lag between the release of a version to usand006w2k and the time it appears on mselvarag. Access to this server requires a Matrix account. VCX Linux may also be mirrored on other servers. However, use of other servers for installation is not qualified by the infrastructure group.

VCX 7.1 Disk Build HOWTO Page 3 of 16

2.1 VCX Linux 5.X

The standard locations for VCX Linux 5.X files are : ftp://usand006w2k.ne.3com.com/vcx/vcx-linux/ ftp://mselvarag.wan.3com.com/var/ftp/pub/vcx-linux/ Beneath this directory are additional directories, one per version of VCX Linux. In this document, the convention <version> will be used to indicate the version you are installing, for example 5.0.0. There is a file, VERSIONS.txt, in the vcx-linux directory which lists which Linux versions correspond to which VCX builds. This file also lists which Linux versions are shipped, which are development, and which are obsolete. It is recommended that any mirrors of VCX Linux follow the same convention, e.g. a vcx-linux directory with per-version subdirectories.

2.2 Oracle
The standard location for Oracle files is : ftp://usand006w2k.ne.3com.com/vcx/oracle/ ftp://mselvarag.wan.3com.com/var/ftp/pub/oracle/ Within this directory may be multiple Oracle rpms. Be sure to retrieve the correct version for your installation. (Typically this is the highest-numbered version.)

2.3 VCX Installation Tarballs

The standard location for VCX installation tarballs is : ftp://usand006w2k.ne.3com.com/vcx/releases/7.1/<build-number> ftp://mselvarag.wan.3com.com/var/ftp/pub/7.1/<build-number> The particular <build-number> directory will vary with the build. Choose the one which corresponds to the build you are installing.

3 Starting the Installation (non-W1)

This section does not apply to the W1 system. If you are installing to a W1, skip to section 4.
It is necessary to first boot the system and configure basic networking using a bootable Linux CD. For VCX 7.1, new versions of the Knoppix CD are in use. Check the table below. Server Type x3650 x306m x306, x346 x345 Min. Knoppix vers. 5.0.1 4.0.2 3.6 3.6 5.0.1 should work but is not yet tested 4.0.2 known to work; 5.0.1 should also work but is not yet tested Newer versions not tested Notes

The Knoppix ISO images can be downloaded via FTP from:

usand006w2k.ne.3com.com/vcx/vcx-linux/bootCDs/KNOPPIX_V3.6-2004-08-16-EN.iso usand006w2k.ne.3com.com/vcx/vcx-linux/bootCDs/KNOPPIX_V4.0.2CD-2005-09-23-EN.iso usand006w2k.ne.3com.com/vcx/vcx-linux/bootCDs/KNOPPIX_V5.0.1CD-2006-06-01-EN.iso mselvarag.wan.3com.com/var/ftp/pub/vcx-linux/bootCDs/KNOPPIX_V3.6-2004-08-16-EN.iso mselvarag.wan.3com.com/var/ftp/pub/vcx-linux/bootCDs/KNOPPIX_V4.0.2CD-2005-09-23-EN.iso mselvarag.wan.3com.com/var/ftp/pub/vcx-linux/bootCDs/KNOPPIX_V5.0.1CD-2006-06-01-EN.iso

VCX 7.1 Disk Build HOWTO Page 4 of 16

3.1 Check that only 1 disk is installed

The VCX Linux install procedure expects to have a single hard disk present in the system. If multiple disks are present (particularly if they also have been used for VCX Linux installations) this may cause the installation to fail. Therefore, especially on platforms with removable disk trays (x306, x306m, x345, x346, x3650), make sure that only one disk is actually installed. It is possible to leave a second disk installed if the partition table is erased using the following command, where <DEVICE> is the physical device (such as /dev/sda): dd if=/dev/zero of=<DEVICE> bs=512 count=1 You can run this in either of two ways: Install and boot the drive to be reused and run the command. WARNING: once the partition table is erased, the drive will no longer be bootable. Install the drive and boot the system from Knoppix, then run the command. (Note that on the x346 you will have to load the correct SCSI driver with the command modprobe aic79xx first.)

Note that VCX Linux 4.2.0 and newer also include an erasePartitionTable command that can be used to zero the partition table in place of the dd command above.

3.2 Check BIOS settings

If installing to a system which has BIOS settings tuned to specific operating systems (such as the HP DL380 server), check that Linux is the selected operating system before starting the installation.

3.3 Initialize SAS disk (x3650 only)

On the x3650 platform, a brand new disk will not be seen by the OS unless it is first initialized from the SAS controller. Press Ctrl-A when prompted during boot to enter the Adaptec BIOS screens. From here, select and initialize the drive.

3.4 Boot from Knoppix CD

The Knoppix CD is actually a full Linux-system-on-a-disk which includes a full desktop GUI and many tools. However, for our purposes we are using it simply as a bootable CD which provides all of the tools needed to install VCX Linux. The Knoppix CD requires some boot options in order to work and properly support various hardware platforms. These must be specified at the boot: prompt. If you try to boot Knoppix without options, it is unlikely to work.

3.4.1 Boot options Knoppix 3.6

The required options for Knoppix 3.6 are as follows: IBM x306, x345, x346, Intellistation M Pro 6230/41U, and most other systems HP DL380, IBM Intellistation Z Pro 6221-10U IBM x306m knoppix26 lang=us atapicd 2 knoppix lang=us nodma 2 NOT SUPPORTED by Knoppix 3.6 Use Knoppix 4.0.2 instead!

For the curious, these options do the following: knoppix26 Selects the Linux 2.6 kernel, which is needed to support newer hardware lang=us Selects US keyboard layout atapicd Needed so that Knoppix works properly with an IDE CDROM under the 2.6 kernel nodma Disables dma, which causes issues on certain systems 2 Selects runlevel 2, which does not start the Knoppix GUI (X Windows) VCX 7.1 Disk Build HOWTO Page 5 of 16

3.4.2 Boot options Knoppix 4.0.2 / 5.0.1

The required options are as follows: IBM x306m, x3650 IBM x306, x346 knoppix lang=us 2 knoppix lang=us atapicd 2

3.4.3 A Note on SCSI disks

The device file to use to access the SCSI or SAS disk is /dev/sda, unless you are installing to an HP DL380 server, in which case the device name is /dev/cciss/c0d0. Also, the DL380 disk partitions are referenced with a p in addition to the number, e.g. /dev/cciss/c0d0p1 is partition 1.

3.5 Configure Networking if necessary

Once the system is up and running on the boot CD, it is necessary that basic networking be operational to perform the rest of the installation. If the network to which the system is connected does not have a DHCP server, you will need to manually configure an IP address for the system to use during the install process. This can be done as follows (substitute your IP parameters where appropriate):
/sbin/ifconfig eth0 192.168.1.1 netmask 255.255.255.0 broadcast 192.168.1.255

/sbin/route add default gw 192.168.1.254

If you are uncertain of the values to use, please contact your network administrator for assistance. If your network has a DHCP server, DHCP may be used during VCX Linux installation. However, in most cases, you will still want a static IP for the installed system. While VCX Linux for VCX 6.0 and later does support DHCP as an option, the implementation is designed for a specific use case and requires special server configuration. Unless you are testing something related to this, it is almost certainly the case that you should use a static IP address. The Knoppix 3.6 CD also includes a utility, network-setup, which can be used to set up networking for purposes of performing the rest of the installation. If you choose to use this, select the netcardconfig option and follow the prompts.

4 Starting the Installation (W1 only)

This section applies only to the W1. If you are installing any other system type, skip to section 5.
The W1 poses particular challenges when it comes to initial installation. Not only does the system not have a CDROM, but its BIOS does not support USB or network booting. This means that building a W1 master disk requires either: An already-built W1 system to use as a host, or Removing the W1 hard disk, connecting it to a PC, and installing the OS and bootloader so that the disk will boot in the W1. Both approaches are covered below.

4.1 Installing using a working W1

The simplest means of building a new W1 disk is to use a working W1 as a host. The working W1 need not be running the same version you wish to install. The basic approach is to use the working W1 disk to bring up the unit (in place of the Knoppix CD typically used on other systems), and then specify the other disk device as the installation target in vcxSetup. The first disk is not modified by this procedure.

VCX 7.1 Disk Build HOWTO Page 6 of 16

4.1.1 Setting Up
Check that power is off on both the W1 you will be using as a host (well call this W1-A) and the W1 whose disk you need to build (W1-B). Wear a grounding wrist strap while working on the W1. The units are very sensitive to ESD and are easily damaged. Loosen the 2 screws and 2 thumbscrews holding the disk in W1-B and pull out the disk module. Remove the blank cover plate on the 2nd disk slot of W1-A (youll find this next to the installed disk, on the back of the unit). Install the disk module in this slot.

4.1.2 Installation
Boot W1-A and login as root. Note: if the W1-B disk previously had VCX installed on it, strange errors may be seen at boot, including messages about duplicate labels, read-only partitions, various [FAILURE] messages, and a long pause while starting syslog. These are the result of the two disks having duplicate partition labels. If this occurs, erase the partition table on the W1-B disk using the command: dd if=/dev/zero of=/dev/hdc bs=512 count=1 and then reboot. Ensure that networking is operational. If not, configure it. cd to the /tmp directory and proceed with the installation as documented in section 5. Be very certain that you specify the correct device this should be /dev/hdc in this case. This instructs the script to install the new VCX Linux version on the 2nd drive, and will not disturb the version already installed on /dev/hda (on which the system is running).

When asked if this is a W1, say yes. Do not reboot once the OS is installed. When Reboot now? is asked, say no and then do a shutdown h now to shut the system down.

4.1.3 Post-installation
Once the OS is installed, remove the W1-B disk module from W1-A and reinstall it in W1-B, being sure to wear your grounding strap. The W1 should now be able to boot from the disk and you can carry on with the rest of the VCX installation.

4.2 Installing using a PC

Installation using a PC requires: A PC with ATA100 or ATA133 IDE controller, network card, and CDROM A W1 hard disk, dismounted from its carrier module A notebook hard drive adapter allowing connection of the 2.5 notebook disk of the W1 to a desktop IDE controller. An ATA100 IDE cable. An ATA100 cable has about twice as many wires in the same width as the older ATA cables, resulting in a more fine grained appearance.

4.2.1 Dismounting the W1 disk

Ensure power is off. Locate the W1 disk module on the back of the unit, next to the CPU. Wear a grounding wrist strap while working on the W1. The units are very sensitive to ESD and are easily damaged. Loosen the two screws and two thumbscrews holding the disk module, and pull it out. Remove the four screws holding the disk in place. Lift it and remove the clip which prevents the ribbon cable from being removed. Gently disconnect the ribbon cable.

VCX 7.1 Disk Build HOWTO Page 7 of 16

4.2.2 Setting up the PC

A grounding wrist strap is recommended while working inside a PC. Disconnect all drives except the CDROM. Locate the other ATA100 connector (the one not used for the CDROM). Connect an ATA100 cable to this connector and to the notebook hard drive adapter. The W1 disk should be the only device on the bus. Connect a spare disk power Molex connector to the power connector on the notebook hard drive adapter. Plug in the W1 disk.

4.2.3 Booting
Enter the BIOS and ensure that the drives are configured to allow booting from the CDROM and access to the IDE bus you have connected the W1 to. The details will vary depending on the PC used! Boot the Knoppix CDROM. If you are not sure which options to use, section 3.4.1 may provide a useful starting point. Configure networking following the instructions in section 3.5.

4.2.4 Installation
Follow the instructions in section 5. The installation device to use varies depending which IDE bus you connected the drive to. If you used the first or primary bus, it is /dev/hda; the secondary bus is /dev/hdc.

When asked if this is a W1, say yes. Do not reboot onto the disk once the OS is installed. When Reboot now? is asked, say no and then do a shutdown h now to shut the system down.

4.2.5 Post Installation

Power down and disconnect the W1 disk from the PC. Remount it to its carrier and reinstall the carrier in the W1 (be sure to wear your grounding strap). The W1 should now be able to boot from the disk and you can carry on with the rest of the VCX installation.

4.3 Copying a W1 master disk using a W1

If you need multiple W1 master disks, it is possible to build one and then copy it. Install the working disk in the first disk module slot (next to the CPU) and the blank disk in the second module slot. Note: if the W1-B disk previously had VCX installed on it, strange errors may be seen at boot, including messages about duplicate labels, read-only partitions, various [FAILURE] messages, and a long pause while starting syslog. These are the result of the two disks having duplicate partition labels. If this occurs, erase the partition table on the W1-B disk using the command: dd if=/dev/zero of=/dev/hdc bs=512 count=1 OR, for VCX linux 4.2.0 and newer, you may use: erasePartitionTable /dev/hdc and then reboot. To carry out the disk copy, you must be in single user mode. To reach single user mode you can either: OR Boot the unit into single-user mode as follows: o Enter the GRUB menu during boot by pressing ESC when the GRUB countdown appears. o o o o Press e to edit the boot options. Move to the 2nd line (beginning with kernel) and press e again to edit the kernel boot options. Add single to the end of the line (without the quotes). Note the space beforehand! Press Enter then press b to boot. VCX 7.1 Disk Build HOWTO Page 8 of 16 Boot the unit, log in as root, and drop to single user mode by issuing the command telinit 1.

Run the command diskCopy, specifying /dev/hda as the source and /dev/hdc as the destination drives. In the event your system has an older version of VCX Linux which does not provide the diskCopy command, download the diskCopy.sh script from: usand006w2k.ne.3com.com/vcx/vcx-linux/utils/diskCopy.sh mselvarag.wan.3com.com/var/ftp/pub/vcx-linux/utils/diskCopy.sh The disk copying process will take most of an hour to complete.

5 Installation Procedure
This procedure uses a shell script which prompts for some minimal information, and takes care of all of the other steps needed to install VCX Linux automatically. It is suited for installing VCX Linux on SATA, IDE, or SCSI based systems which are dedicated to VCX. It must not be used on a development or other system which has partitions that must be preserved, as it will completely repartition and reformat the disk.

5.1 Fetch the installation script

Ensure that you are logged in as root and that networking is configured as described in section 3.5. You may verify that networking is working by trying to ping some other machine on the network. Next retrieve the installation script into the /tmp directory as follows. Notes: 151.104.56.75 is the IP address of usand006w2k; it is unlikely that nameservice will be working at this point, so we simply use the IP address to reach the server. For use of mselvarag, the IP address is 152.67.120.90. Substitute your Matrix login and alternative paths where appropriate. Pay close attention to the specification of username and password; in particular, note that the backslash must be doubled to escape it so that the shell does not interpret it.

cd /tmp wget ftp://pvt\\myusername:mypassword@151.104.56.75/vcx/vcx-linux/<version>/vcxSetup.sh

Alternatively, it is possible to get the script using the lftp utility:

cd /tmp lftp 151.104.56.75 u pvt\\myusername mypassword lftp pvt\mylogin@151.104.56.75:~> get vcx/vcx-linux/<version>/vcxSetup.sh

5.2 Run vcxSetup.sh

Now run the script: sh vcxSetup.sh You will be warned about the impending reconfiguration of your disk and prompted whether you wish to continue. Say yes. You will then be prompted for which device to use. System Type IBM x345, x346, most SCSI IBM x3650 IBM x306, x306m, Intellstation M Pro 6230/41U HP DL380
1

Disk Type SCSI SAS SATA SCSI (SmartArray)

Installation Device /dev/sda /dev/sda1 /dev/sda2 /dev/cciss/c0d0

If you get a message about the device not existing, you probably forgot to initialize the disk from the SAS controller BIOS. See section 3.3. 2 This is not a typo. SATA disks appear as virtual SCSI devices. VCX 7.1 Disk Build HOWTO Page 9 of 16

IBM x305, Intellistation Z Pro 6221/10U, most IDE W1 (using another W1 as host) W1 (using a PC as host) device depends on which bus was used for connection

IDE IDE IDE

/dev/hda /dev/hdc /dev/hda or /dev/hdc

If you specify a nonexistent device the script will give an error and let you retry. If you specify a device that exists but cant be installed to (for example, the CDROM drive) then you will get an error when the script tries to partition it, and you can simply start over if that occurs. If installing to an IDE device, you will be asked if this installation is for a V6000 (W1). Answer yes or no as appropriate. The script will then partition your disk, format the partitions, and prepare to download the VCX Linux image. You will be given a menu of choices of FTP servers. Select one or choose none of these and enter the IP address of the remote server. For the predefined FTP servers you will then be prompted with a default path. Press Enter, or if using some other server, enter the ftp path to retrieve the image. If the remote server does not support anonymous downloads the script will prompt for a user name and password. Note: If downloading from a server within the pvt domain, including usand006w2k, specify the username as pvt\myusername. The password is, of course, your PVT password. The image will then be retrieved and installed to the correct partition. When partimage completes, a dialog will appear indicating that the operation succeeded. Press Enter to continue. The installer will then label the partitions and install the boot loader. If installing a W1 additional modifications will be made automatically. The serial port is used as the console by default and MUST be used for any master disk being built for customer use. If installing to anything other than a W1, you will be asked whether you wish to use the serial port as the console; the default answer is yes. If you say no, then the system will be reconfigured to use the PCs vga/keyboard ports as the console. This should be done only on systems for internal use. If on a SCSI, SAS, or SATA system, fstab will be updated appropriately. Note for those familiar with previous VCX installs: The installer will no longer prompt for whether the installation device is SATA, because the Knoppix 3.6 CD has SATA support and so devices appear by their correct names. You do not need to do anything special here for SATA systems any more. At the end, you will be asked if you want to reboot. Say yes. Note that Hyper-threading must be enabled on systems that support this feature in order for the OS install to complete successfully. To check this: Hit F1 to enter setup when the system starts back up. Select Advanced Setup Select Processor Control If the item Hyper-Threading Technology is available, set it to Enabled.

Exit setup When the system reboots, be sure that the CD is not in the drive.

6 Booting & Configuration

The expectation is that the system will arrive at the customer site in a fully-installed but completelyunconfigured state. The customer runs the vcx-setup3 script, which will:
3

vcx-setup was formerly called (and is still available as) setup. It was renamed for consistency with other vcx- scripts. VCX 7.1 Disk Build HOWTO Page 10 of 16

Select the configuration type which this system is to provide Configure networking using vcx-config-network Write a configuration file for the installed VCX components using vcx-config-services Apply the configuration file to the components (firstboot configuration)

Start up VCX In order to ensure consistent results and proper testing of the entire first-time-setup sequence, all systems should be built as though they are customer disks.

6.1 Before You Reboot

6.1.1 Attach Serial Console
If you selected the default choice of using a serial console, then you must have a terminal device or terminal emulator attached to the serial port when you reboot. All GRUB output, kernel boot messages, and other system output will be directed to this port. If using a PC with terminal emulator (the most common scenario), use a null-modem (crossover) serial cable to connect the VCX serial port to the PCs serial port. A W1 requires use of the AudioCodes three-pin-to-DB9 connector cable. Any terminal emulator capable of proper VT100 emulation should work. On Linux, the minicom program is a good choice. On Windows, hyperterm can be used in a pinch, but there are (much) better choices. Tera Term is one good, and free, alternative; an updated version which supports UTF8 and SSH2 can be found at: http://sleep.mat-yan.jp/~yutaka/windows/index.html . Another decent choice is PuTTY (http://www.chiark.greenend.org.uk/~sgtatham/putty) The port settings are 9600, 8-N-1, no flow control, EXCEPT for the W1, which uses 115200, 8-N-1. Your terminal type must be set to VT100 (or a close cousin such as VT102); note that Windows Hyperterm defaults to an auto terminal type which will not work properly with some applications. If you see strange characters, misformatted output, etc. check the terminal type.

6.1.2 DHCP related warnings

While VCX Linux now supports DHCP as part of automatic remote configuration, the implementation is designed for a very specific use case and requires that the DHCP server be carefully configured to provide the proper options. If you are not specifically testing remote autoconfiguration, you should not attempt to use DHCP on your VCX system. A standard corporate DHCP server will not work. If you are building an actual Master Disk for duplication, you MUST NOT have a DHCP server on your network when you bring up the VCX Linux system. Because the use case is designed for infinite leases, it is possible that a lease left on the disk during Master Disk construction, could interfere with proper operation at a customer site.

6.1.3 No extra hardware

When building a master disk, it is vital that the system be configured just like the customers systems will be. Otherwise, when the disk is duplicated and used in a customer system, kudzu will detect the differences and pop up asking to make appropriate changes, which is something customers should not see. To ensure this is the case, do not have any extra hardware attached, such as a mouse, extra Ethernet card, etc.

6.2 Hardware Detection

This section does not apply to the W1. Upon reboot, the kudzu hardware detection program starts and asks if you want to configure hardware. Enter any key within 30 seconds to do the hardware detection, as it is required. Go through the screens and select remove for any device it asks to remove, and select configure for any device it asks you to configure. (You can press F2 to configure all.) At the prompt would you like to migrate existing network configuration say no One of the devices it finds should be your networking device. Upon completion of hardware detection, startup will continue. VCX 7.1 Disk Build HOWTO Page 11 of 16

6.3 Expected errors on first boot

In order to support LOCSA deployments, systems now default to using DHCP. If no DHCP server is present (see section 6.1.2), network startup will fail. This is OK. In fact, even if a DHCP server is present, DHCP will very likely fail because VCX Linux specifies a number of required fields which are needed for remote deployment, but not commonly provided by DHCP servers. NTP startup will also fail until basic networking is functional, and one or more NTP servers configured.

6.4 Log in
<hostname> login: root Password: pvadmin

6.5 Temporarily Configure Networking

When building a VCX disk, it is necessary to ensure that the system will still have proper default values and no existing configuration at first boot. Therefore: Do not use DHCP. Do not run the setup or vcx-config-network scripts to configure networking. The system will start with default network values. Set up basic network connectivity using the ifconfig and route commands. Substitute the correct values for your network for the ones shown below.

/sbin/ifconfig eth0 192.168.1.1 netmask 255.255.255.0 broadcast 192.168.1.255

/sbin/route add default gw 192.168.1.254 Complete installation of the rest of VCX as documented below. Because the wizard was not run, and the network values were changed interactively rather than by editing configuration files, the system will retain its default values and will come up in a fully-installed but completelyunconfigured state, as it should.

7 VCX Installation
This section contains instructions for installing the rest of the VCX system so that it is ready for initial configuration and use. Because single SKU support means that selection of configuration type is done at first time setup, there are no longer separate instructions for different config types. All systems should use the instructions listed here.

7.1 Retrieve Required Files

Retrieve the vcx-users and Oracle rpms, and the vcx-all tarfile for the version of VCX you are installing, from the FTP server. usand006w2k is used in this example; for mselvarag you must specify the appropriate Matrix login, server name, and paths. cd /opt/installtemp lftp u pvt\\myusername usand006w2k.ne.3com.com mypassword cd vcx/vcx-linux/supportRPMs get vcx-users-1.0.0-1.i386.rpm cd ../../oracle get oracle-9.2.0.4-6.i386.rpm cd ../releases/<current VCX build> get vcx-all-<version>.tar quit

VCX 7.1 Disk Build HOWTO Page 12 of 16

7.2 Install vcx-users and Oracle

Install the vcx-users and Oracle RPMs using the vcx-install command. The oracle rpm contains both oracle and a cwbes database. It is very large and can take a while to install ! cd /opt/installtemp vcx-install vcx-users-1.0.0-1.i386.rpm vcx-install oracle-9.2.0.4-6.i386.rpm

7.3 VCX Applications Installation

tar xfv vcx-all-<version>.tar cd upgrade-<version> ./install-upgrade You may notice some changes from previous versions of install-upgrade: During the install-upgrade script you will be prompted to select an OEM version. Most systems should choose the 3Com OEM package (oem-a). Any testing for the JVCO should use the JVCO OEM package (oem-b). The vcx assembly process is no longer run as part of the initial installation. Assembly is deferred until a configuration type is chosen during first-time setup.

A disk space check is performed prior to installing any packages. Nothing will be installed if there is not enough space for the new RPMs. Note that it is not necessary to reboot after VCX applications are installed.

7.4 W1 Only: Select configuration type

The W1 only supports an all-in-one configuration. Preselect this with the command: vcx-setconfigtype -configtype all (Or alternatively, simply run vcx-setconfigtype and select the IP Telephony and Messaging option.)

7.5 Ready For Use

Installation is now complete. You may start configuration with the vcx-setup command, or shut down and duplicate the disk if you need additional copies for other systems.

8 Odds and Ends

This section contains notes about things that were worthy of inclusion, but did not have a place elsewhere in the document.

8.1 Whats that beeping noise?

The First Time Setup Functional Specification for VCX 6.0 specifies the generation of beep codes to indicate the success or failure of automatic setup at a remote branch, where there is no console attached to the system. Because all systems are configured with DHCP as the default, you will very likely encounter this feature once a VCX assembly is installed. Here are some details about what to expect: Beep codes are generated only on systems with an all-in-one or unknown configuration. The former is because this is the install type used for branches; the latter indicates either a new OS install with no assembly present (common inside 3Com) or an error condition (on a shipped system). Since in VCX 7.0 no configuration type is initially selected, all systems will beep at first boot! All-in-one configurations will generate beep codes whether ROCSA or LOCSA, because at initial boot (prior to configuration) the system does not know whether it will be used in a region or a branch. Systems with static IP addresses (DHCP disabled) will not generate beep codes.

VCX 7.1 Disk Build HOWTO Page 13 of 16

Beep codes are generated only for first-time setup, not upgrades, even on remotely managed branch offices. Continuous beeping indicates a failure of automatic setup. Logging in will stop the beeping. A beep-beep-pause-pause sequence repeated several times indicates successful automatic setup.

8.2 Behavior before configtype is selected

Before a configuration type is first selected, the system is not fully installed. Because many things on the system depend on files within /opt/3com/VCX/... you may note the following behaviors.

8.2.1 No HTTPD
The Apache (httpd) web server is not started when no assembly is present. During the boot sequence (or if /etc/init.d/httpd start is invoked manually) a message is printed which says: Starting httpd: (no active VCX version not started) This is normal behavior. HTTPD will be started when a config type is chosen.

8.2.2 No Common Agent

Common Agent does not run until an assembly is chosen. CA will be started once an assembly is made.

8.2.3 Default firewall (all ports blocked)

The firewall assumes its default configuration with all ports blocked until an assembly (with associated firewall scripts) is chosen.

8.2.4 vcx-showconfigtype
If vcx-showconfigtype is called, instead of printing a config type code (or unknown) it detects the unconfigured state and reports: not-selected : 6 available (Where 6 is the number of possible config types, e.g. selectable VSBOM files.) Once an assembly is made the behavior reverts to normal.

9 Appendix A: Building a FRU disk

This section describes the creation of a FRU disk for VCX. Most readers will not need these procedures FRU disk creation will be of interest only to those who are specifically involved in creating actual FRU disks, or in testing the FRU disk feature.

9.1 What is a FRU disk?

A FRU is a Field Replaceable Unit, and a FRU Disk is a replacement hard drive to be used in the field in the event of a drive failure. VCX has been very difficult to support with FRU disks since each combination of platform + release + configuration type required a different disk. Starting with VCX 7.0 a method has been devised to provide a single disk for each platform, which contains everything required to build a selection of releases and configuration types. In the field, a technician can select the version and config type needed, and the right software will be installed (and the rest deleted). This will greatly reduce the number of disks that must be stocked. As new releases are introduced they will simply be ECOd onto the existing FRU disk.

9.1.1 Differences from a SKU disk

A FRU disk contains a VCX Linux OS in partition A, and a collection of software (RPMs and other content) in a well defined location in /opt. No VCX or Oracle software is installed. The installed OS is used simply to boot the system and run a script which carries out installation of the required OS version (into partition B) and set of third-party and VCX application software. It then switches to OS B and reboots. The procedure to build such a disk is therefore very similar to any other master disk, up until the point the VCX Linux OS is installed.

VCX 7.1 Disk Build HOWTO Page 14 of 16

9.2 Install the OS

The disk must first have VCX Linux 4.X installed onto it following the procedures up to and including section 6. Once the OS is installed, booted, and networking temporarily configured, FRU disk configuration can be done.

9.3 Load software content

9.3.1 Overview
FRU disk creation requires the following steps, which are carried out using an automated script: Create required directory structure Download required content from the Releases server (Oracle, release tarballs, etc.) Arrange required content within the directory structure Tweak the OS to set up for FRU disk use

9.3.2 Directory Structure

The FRU disk content goes in /opt/3com/release-files. Beneath this are a COMMON directory for shared content, and a per-release subdirectory. Each release subdirectory has subdirectories for each configuration type, its associated OS, and preinstall RPMs. Symlinks are generously used to reduce disk usage. In addition, a single XML file per release describes the available configuration types and provides other information needed by the installation scripts. The directory structure is created and populated automatically by setupFruDisk.sh.

9.3.3 DESCRIPTION.xml files

DESCRIPTION.xml files are simple xml files which list the attributes and available configuration types for a given release. These are used by the FRU installation scripts. DESCRIPTION files have been created for those releases which are to be included on the FRU disk and are posted with the corresponding releases on usand006w2k. They are retrieved by setupFruDisk.sh. NOTE: Although one 7.0 release is included, the intention is not to provide an updated DESCRIPTION for each and every 7.0 development build the FRU disks are intended to contain released content, and so although it is necessary to test that 7.0 can be installed, it is not necessary to have the latest 7.0 content every week. The included 7.0 build will be updated occasionally or as-needed, and of course for the final 7.0 release build.

9.3.4 setupFruDisk.sh
setupFruDisk.sh is, like vcxSetup.sh, a separate script which is downloaded and run to perform disk configuration. It takes care of setting up everything necessary on a FRU disk. This script contains release specific information (e.g. which releases are to be put on the FRU disk). Like the DESCRIPTION file, the intention is to update it periodically (but not weekly) during the 7.0 development cycle. setupFruDisk.sh is posted at the following location: ftp://usand006w2k.ne.3com.com/vcx/vcx-linux/utils Download the script and run it with the command: sh setupFruDisk.sh It will be necessary to provide a username and password when prompted, so that the script can access usand006w2k. W1 does not support any release prior to 7.0. If setupFruDisk.sh is run on an IDE system it will ask whether the disk is for a W1. If yes, then no releases before 7.0 will be put on the disk. Once the script has completed the FRU disk is ready for use.

VCX 7.1 Disk Build HOWTO Page 15 of 16

9.4 FRU disk usage

When the FRU disk is booted it will automatically launch vcx-fruinstall, which provides the menu selection and carries out the software installation. If you do not want to carry out the selection process, simply answer no when asked Do you wish to perform configuration now? and the script will exit. You can then log into the system normally. If you later want to configure the disk simply run vcx-fruinstall, or reboot. Note that FRU disk selection is a one time process. Once a selection is made it is not possible to change the selection of version or configuration type.

VCX 7.1 Disk Build HOWTO Page 16 of 16