THE BPPATCH COMMAND-LINE UTILITY ============================================================================== CONTENTS ------------------------------------------------------------------------------ THE BPPATCH COMMAND-LINE UTILITY 1.0 WHAT IS BPPATCH? 2.0 USING BPPATCH 3.0 HOW BPPATCH WORKS 4.0 SETTING UP BPPATCH 5.0 BPPATCH COMMAND-LINE OPTIONS 6.0 TAGS WITHIN THE BOOT IMAGE FILE 6.1 Adapter-Specific Information 6.2 BOOTP RFC951 Fields 6.3 RFC1048 Vendor Fields 7.0 BPPATCH EXAMPLES 7.1 Example A: Working with a Hosts File 7.2 Example B: Creating a Universal Boot Image 7.3 Example C: bptest.txt 1.0 WHAT IS BPPATCH? ------------------------------------------------------------------------------ The optional BPPATCH command-line utility is used to replace parameters from the BOOTP/DHCP reply packet into text files. BPPATCH allows one common boot image file with BPPATCH variables to be used by several client PCs. The parameters that are unique to each client PC (like the IP address or NDIS driver) are specified in the BOOTPTAB file on the network server and replaced in the writable boot image file when the client PC boots. 2.0 USING BPPATCH ------------------------------------------------------------------------------ The successful implementation of BPPATCH is dependent on the BOOTP or DHCP protocols, a BOOTPTAB file with properly defined tags and values (in BOOTP environments), client PCs with 3Com Managed PC Boot Agents (or other compatible third-party boot ROMs), and writable boot image files that contain batch files that invoke BPPATCH. To use BPPATCH, you must put tags into the boot image's text files (batch files, configuration files, and so on) to indicate the BOOTP/DHCP fields that you want to replace. You then run BPPATCH and specify, in the command line, the files to be patched. You can specify more than one file at a time. For example, if you wanted to patch the files start.bat and pctcp.ini, the command line would be: bppatch start.bat pctcp.ini NOTE: If you need to patch parameters for commands in the autoexec.bat file, you must place these commands in a second batch file so that you can run BPPATCH before the second batch file is executed. For example, if you put all the commands in a file called start.bat, the autoexec.bat file would contain the following commands: bppatch start.bat start NOTE: BPPATCH must be run before FREEMEM. 3.0 HOW BPPATCH WORKS ------------------------------------------------------------------------------ BPPATCH fits into the remoteboot and preboot process in the following way: A.) The end user powers on the client PC. The client PC will request an IP address. B.) BOOTP searches the BOOTPTAB database file for the client PC's unique MAC address. Once the MAC address is found, BOOTP determines the designated IP address, specified boot image file, and other predefined configuration information. C.) BOOTP sends a packet containing the IP address, boot image filename, and unique parameters and values (such as the NDIS driver filename) to the client PC. D.) The client PC requests to download the boot image file using the Trivial File Transfer Protocol (TFTP). E.) TFTP transfers the boot image file and configuration information to the client PC's memory. Then the client PC begins to execute the commands within the boot image file. F.) When the BPPATCH command line is encountered, BPPATCH opens the specified configuration or batch files that contain BPPATCH tags. G.) BPPATCH updates the tags in the batch/configuration file using the parameters (which are stored in the client PC's memory) from the BOOTP/DHCP server. H.) The client PC boots with the assigned and patched parameters. 4.0 SETTING UP BPPATCH ------------------------------------------------------------------------------ Generally, to configure all the relevant components to run BPPATCH: A.) Decide on the elements within the boot image file that you want to replace. These elements might include the NDIS drivers, IP addresses, computer names, and so on that are unique to each client PC. BPPATCH is flexible and can replace almost any variable. B.) Create a batch file or configuration file that contains the BOOTPTAB tags that you want to replace. See section 6 of this document, "Tags within the Boot Image File," for more information. C.) In the autoexec.bat file, enter a command line (with or without one of the three BPPATCH command-line options - see section 5 of this document, "BPPATCH Command-Line Options") that calls BPPATCH and executes the text files that contain the BPPATCH tags. Remember that BPPATCH must be run before FREEMEM. Example AUTOEXEC.BAT @echo off path=a:\net bppatch /i a:\net\system.ini a:\net\protocol.ini bppatch a:\netstart.bat call netstart.bat set comspec=g:\command.com g: freemem.bat FREEMEM.BAT Freemem.com D.) Create a boot diskette that contains the batch file that you created in step B, an autoexec.bat file that calls BPPATCH, and all the standard files that are needed to boot the client PC from the network. E.) With the 3Com Boot Image Editor program, create a writable boot image file from the boot diskette. Consult the Boot Image Editor online help for details on creating boot image files. F.) In BOOTP environments, create a BOOTPTAB file that includes entries for all the applicable client PCs. In each appropriate entry, be sure to specify the tags and the unique values that BPPATCH will replace during the boot process. Consult the BOOTPTAB Editor online help for information on creating BOOTPTAB files. G.) Boot a client PC, which has been preconfigured for remoteboot or preboot activity, to test BPPATCH. Use the Boot Image Editor to perfect the boot image file as needed. 5.0 BPPATCH COMMAND-LINE OPTIONS ------------------------------------------------------------------------------ Three BPPATCH command-line options are available: /s, /v, and /i. /s The /s option is used to display all the available tags and their values. The output is formatted in such a way that it can be redirected to a disk file and then used to set DOS environment variables. Below is a sample output: rem BOOTP Patch v1.4 rem RFC951 BOOTP reply set yip=132.147.175.9 set sip=132.147.160.1 set bfn=/tftpboot/hp.img set typ=56 set iop=0x300 rem RFC1048 vendor fields set smf=255.255.0.0 set tof=18000 set t128="UnixBox" The output can be redirected to a file using the DOS redirection character ">". For example, to redirect the settings to a file called bootp.txt, type the following: bppatch -s >bootp.txt /v The /v option enables verbose mode so that BPPATCH will display messages while it processes the text files. Normally, BPPATCH displays nothing on the screen. /i The /i option replaces periods in IP addresses with spaces for Microsoft clients. For example, using this option, the IP address 141.148.109.2 becomes 141 148 109 2. 6.0 TAGS WITHIN THE BOOT IMAGE FILE ----------------------------------------------------------------------------- All tags within the boot image's text files begin with the character sequence "#@" and are followed by a three-character tag name. Following the tag name are additional "#" characters used to specify the tag length and act as placeholders (for example, #@bfn########). When deciding on the number of # characters to use, consider the following: - The total tag length is counted from the first # character to the last # character. - The tag must be large enough to contain all the characters that may be in the field. - If the field is short, BPPATCH will automatically remove unnecessary trailing spaces or placeholders so that you do not experience alignment or file location problems. NOTE: If the field is larger than the tag length or exceeds the assigned placeholders, the field will be truncated. If the field is truncated, the parameters will not be replaced properly and the client PC may not boot as expected. You can use the following tags with BPPATCH: 6.1 Adapter-Specific Information Tag Field Name Description ---- ----------- ----------- #@iop# Adapter I/O address The I/O address that the 3Com Managed PC Boot Agent used to access the network adapter card. #@shm# Adapter memory address The network adapter RAM address used by the 3Com Managed PC Boot Agent (not used on all network adapter cards). #@typ# 3Com MBA type code The 3Com Managed PC Boot Agent type code for the network adapter card (see the 3Com Managed PC Boot Agent User Guide for a list of type codes). 6.2 BOOTP RFC951 Fields Tag Field Name Description ---- ----------- ----------- #@bfn# Boot file name The name of the boot image file that was initially downloaded by the ROM. #@cha# Client hardware address The Ethernet hardware address for the network adapter card. #@gip# Gateway IP address #@shn# Server host name #@sip# Server IP address #@yip# "Your" IP address The BOOTPTAB ip= field value. 6.3 RFC1048 Vendor Fields In addition to the regular Carnegie Mellon University tags, in BOOTP (rather than with DHCP server) environments, BPPATCH supports custom RFC1048 user-defined fields (tag numbers 128-254). To specify a user-defined field within the boot image file, use the tag "#@t" followed by the field number. For example, to specify user-defined field 129, the tag would be "#@t129####". In the BOOTPTAB file, user-defined field 129 would have the tag "t129=", followed by the appropriate value in quotations and a colon (for example, t129="ELNK3":). Tag Field Name Description ---- ----------- ----------- #@smf# Subnet mask field The BOOTPTAB sm= field value. #@tof# Time offset field The BOOTPTAB to= field value. #@chn# Client host name field The full name of the host, including both the host and domain names. This computer name is specified in the first field of the BOOTPTAB file. #@cno# Client host name only The host name only, as specified in the first field of the BOOTPTAB file. #@cdo# Client domain name only The domain name only, as specified in the first field of the BOOTPTAB file. #@gw?# Gateway IP address* The BOOTPTAB gw= field value. #@ts?# Time server IP address* The BOOTPTAB ts= field value. #@ns?# Name server IP address* The BOOTPTAB ns= field value. #@ds?# Domain name server IP* The BOOTPTAB ds= field value. #@lg?# Log server IP address* The BOOTPTAB lg= field value. #@cs?# Cookie server IP* The BOOTPTAB cs= field value. #@lp?# LRP server IP address* The BOOTPTAB lp= field value. #@im?# Impress server IP* The BOOTPTAB im= field value. #@rl?# RLP server IP address* The BOOTPTAB rl= field value. #@txxx# User-defined number xxx The RFC1048 custom vendor tag and value can range from 128-254. (Refer to the above paragraph for more information). * For IP address fields in which you can specify more than one IP address, you can select the address that you want by including the number in the tag. For example, to indicate the IP address of the first domain name server, the tag would be #@ds0#, the second domain server IP address would be #@ds1#, and so on. 7.0 BPPATCH EXAMPLES ------------------------------------------------------------------------------ The following three examples describe some of the ways you can use BPPATCH in your organization. 7.1 Example A: Working with a Hosts File If you have a hosts file that lists the network server's IP address and the local IP address, you can change the file to be: # hosts Internet address file #@yip########## #@chn############################ #@sip########## #@shn############################ Then after you run BPPATCH in the hosts file, the network server's IP address and name, along with the unique client PC IP address and name will be in the file. For example: Command: bppatch a:\etc\hosts Result: # hosts Internet address file 132.147.170.6 Station1 132.147.160.0 UnixHost 7.2 Example B: Creating a Universal Boot Image In this example, the network administrator has created a single boot image file for multiple client PCs running in a BOOTP environment. BPPATCH is replacing NDIS drivers based on the type of adapter installed at each client PC. Following are excerpts from the BOOTPTAB file and the autoexec.bat, netstart.bat, system.ini, and protocol.ini files within the universal boot image file. REM (or ";") statements explain certain parts of these files. Sample BOOTPTAB File # # Blank lines and lines beginning with "#" are ignored. Each entry in the file # contains a name for the entry and a series of fields, separated by a colon. # Fields are defined by a two character (or numeric user-defined) tag. # # Following are the tags used in this organization. # ha - hardware address # ip - host ip address # hd - home directory # bf - boot image filename # bs - boot server ip address # sm - subnet mask # hn - return host name # to - time offset (seconds) # T128 - client NDIS driver name # # Fields within entries may appear in any order. # Spaces and tabs in lines are ignored. # Lines beginning with # are ignored. # An entry can span more than one line in the file by ending continuing lines # with a backslash. # # Default template used by all hosts/client PCs. default: hn:sm=255.255.0.0: hd=\tftpboot\: bf=universal.img: to=3600: #Client entries Tornado: tc=default: ha=0207010422A7: T128="EL90X": ip=132.147.180.5: PC001: tc=default: ha=0020afb322A7: T128="ELNK3": ip=132.147.180.6: Sample AUTOEXEC.BAT File @echo off path=a:\net REM BPPATCH will patch the system.ini, protocol.ini, and netstart.bat files. REM The /i switch is used to change an ip delimiter from a period (.) REM to a space to support MS Client for DOS. For example, when /i is added to REM the command line, 192.168.1.1 becomes 192 168 1 1. bppatch /i a:\net\system.ini a:\net\protocol.ini bppatch a:\netstart.bat call netstart.bat set comspec = g:\command.com g: freemem.bat Sample NETSTART.BAT File @echo off REM The /s switch displays all the BOOTP tags that BPPATCH received from the REM BOOTP or DHCP server. bppatch /s @echo off a:\net\net initialize a:\net\netbind.com rem a:\net\umb.com a:\net\tcptsr.exe a:\net\tinyrfc.exe a:\net\nmtsr.exe a:\net\emsbfr.exe a:\net\net logon /savepw:no /y REM The remaining commands map drive letters to a share on the boot server REM @shn - boot server name. Note that this tag may not be available in DHCP REM environments. net use g: \\#@shn#############\shared net use h: \\#@shn#############\personal net use z: \\#@shn#############\clients Sample SYSTEM.INI File [network]filesharing=no printsharing=no fautologon=no ; The hostname tag (@chn) is used as the NETBIOS computername in this example ; computername=#@chn################## lanroot=A:\NET username=Administrator workgroup=NT40 reconnect=nodospophotkey=N lmlogon=0 logondomain=NT40 preferredredir=basic autostart=basic maxconnections=8 [network drivers] ; The .dos extension is appended to the NDIS driver tag to ; make up the full name of the NDIS2 driver filename. netcard=#@t128#######.dos transport=tcpdrv.dos,nemm.dos devdir=A:\NET LoadRMDrivers=yes [Password Lists] *Shares=a:\net\Share000.PWL Sample PROTOCOL.INI File [network.setup] version=0x3110 netcard=ms$EL90X,1,MS$EL90X,1 transport=tcpip,TCPIP lana0=ms$EL90X,1,tcpip ; The @t128 tag is used to supply an NDIS drivername. ; Note that the $ character is appended to the end of the tag so that EL90X ; becomes EL90X$ and so on. [ms$EL90X] DRIVERNAME=#@t128#####$ [protman] drivername=PROTMAN$ PRIORITY=MS$NDISHLP ; Finally, the IP address, subnet mask, and gateway address fields are ; updated with the appropriate BOOTP tag information. ; @gip - gateway address; @smf - subnet mask; @yip - your IP address. ; Note that the DisableDHCP option is set to True (1). [tcpip] NBSessions=6 DefaultGateway0=#@gip################## SubNetMask0=#@smf################## IPAddress0=#@yip################### DisableDHCP=1 DriverName=TCPIP$ BINDINGS=ms$EL90X LANABASE=0 7.3 Example C: bptest.txt On the 3Com Managed PC Boot Agent Utility Disk there is a test file called "bptest.txt". The bptest.txt file includes all of the available BPPATCH tags so that you can use it as an example and use it for testing BPPATCH in your environment.