Deployment Solution

 View Only

Automating PXE Installation Using PXEConfig.exe 

May 28, 2008 04:57 PM

Altiris Deployment Server 6.9 includes an optional PXE server that many customers use to help automate imaging tasks. What many people do not realize (probably because it is not documented) is that the installation and configuration of PXE can be automated using the PXE configuration utility command line options. This article walks through the command line options that are available.

The PXE Configuration options are configured from the PxeConfig.exe file that is located on the Altiris Deployment Server in the folder "program files\altiris\express\deployment server\pxe." Opening a command line and running "PxeConfig.exe /?" will reveal a list of the six main actions available with this command line utility. These options are shown in the screenshot below.

It is important to point out that each of the commands uses a dash to indicate the first characters of the command line for each command. The implication here is that it is not possible to combine several of these commands lines into a single statement. Instead, each command has to be called separately.

Before going through the command line options, keep in mind that the PxeConfig.exe is aware of Deployment Server security configurations. As a result it is necessary to supply a username, password, and possibly a domain name when calling this file from a script. An example of the appropriate syntax for this is "PxeConfig.exe -username "myname" -p "mypassword" -domain "mydomain" ". The use of the -domain switch is optional.

-install

This command is used to install PXE menu items.

The syntax is "PxeConfig.exe -install -OPTIONS"

An example of this command is "PxeConfig.exe -install -dos -linux -winpe" which will install all three of the PXE boot menus for all of the supported platforms.

A PXE menu consists of 3 PXE boot images, based on the platform of CPU. There is a boot image for x86, a boot image for x64, and a boot image for ia64. Depending on the type of pre-automation environment, only certain boot menus will be created. For example if DOS is selected as the pre-boot environment, ia64 and x64 is not an option. The following table shows the supported combinations:

  • Preboot x86 x64 ia64
  • DOS X
  • Windows PE X X
  • Linux X X X

When the "PxeConfig.exe -install" option is run, one to three PXE menu items will be created along with the appropriate boot images. Remember that when Deployment Server is first installed, the administrator is prompted for which pre-boot environments to install. By default the "-install" switch will create menu items for only the pre-boot environments that were selected during the installation. This ensures that extra menus and boot images are not cluttering the menus. In other words, if the administrator only installed DOS as a pre-boot environment, running the "-install" switch will not install the Linux or WinPE boot menus.

While it is generally not recommended, the "-install" switch does allow only specific boot images and menus to be created. The reason this is not recommended is that when jobs in DS are created, the job itself offers control over which pre-boot environment is used. Jobs are defaulted to the option "auto-selected" which tells the PXE server to send down the PXE boot image based on the CPU. The only exception to this rule is if a 64-bit platform connects to a PXE server that does not have any 64-bit boot images, in which case the 32-bit boot image will be delivered. In DS jobs that are not configured to use the "auto-select" option, the administrator picks a specific boot environment that the job will use. However every customer is different and so if boot menus absolutely must be restricted to specific types, this can be done by specifying the exact images desired using the -x86, -x64, or -ia64 switches. For example to create only a Windows PE 64-bit boot menu the command line option would be "PxeConfig.exe -install -winpe -x64".

When calling this command from a script, the "-silent" option is available. However when testing syntax it is useful to add a "-progress" and "-progresscancel" option to the command line. These options will display a progress bar as well as an option to cancel the operation.

During un-scripted configuration of PXE, the Altiris Boot Disk Creator Wizard is used. It is useful to keep in mind the operation of the Wizard when thinking through the command line options.

For example the "-install -cfg" option is used to override the default values for the boot configuration settings by specifying a cfg file that contains the desired settings. A shortcut to creating an appropriate cfg file is to run the Boot Disk Creator Wizard and after completing the wizard a bdc file is created. Open the bdc file in a text editor, making note of the appropriate syntax, making the appropriate edits, and then saving the file as a cfg file.

Keep in mind it is generally not necessary to change many of the default settings. Most customers might add one or two drive mappings, and/or edit the username and password combination to map the drive.

It is important to understand that options specified using the "-install -cfg" are considered temporary overrides in that they are written once and then those changes are discarded. For an illustration of this, use the "-install -cfg" option to make a configuration change and after it has been applied, open the PXE configuration menu, click on the button "Regenerate PXE boot images" and watch as the custom configurations specified are removed.

It helps to think of the "-install -cfg" as a onetime setting, versus a permanent configuration. One option to work around this is to make sure the "-save" option is used which will force the -cfg options to be saved permanently to the configuration.

A word of caution is necessary when scripting this operation. It is possible to provide names for the PXE boot menus. For example the first time "PxeConfig.exe -install -winpe: "My New WinPE Menu"" is run, it will create a new menu named "My New WinPE Menu". The second time this command is run, instead of creating a new menu with the same name, the existing PXE menu item will be regenerated. There is a "-install -new" option but this will also not generate a new menu with the same name - this will instead force all of the prior settings to be erased and reset to the default configuration.

As a final note, keep in mind that there is no way to specify additional lmhosts entries using this command.

-create

This command is used to create PXE menu items and is similar to the -install option.

The syntax is "PxeConfig.exe -create -PrebootOS "Name of Item" "

An example of this command is "PxeConfig.exe -create -winpe "WinPE Managed"" which will create a menu item named "WinPE Managed" using the Windows PE pre-boot environment.

In rare cases, there may be a need to have PXE boot menus that were manually created from other non-Altiris PXE servers be made available through the Altiris PXE Server. For this case, the "PxeConfig.exe -create -other(os)" command can be used. As Altiris has no knowledge of what OS type the menu would apply to, it would also be necessary to specify the processor type as either "-x86"," -x64", "-ia64" as well as the "-path" command which would point to where the pxe boot menu is created. For example "PxeConfig.exe -create -other(os) -x64 -path[x86] <"C:\temp\mycustombootmenu">".

-regen

This command is used to regenerate PXE menu items.

The syntax is "PxeConfig.exe -regen "Name of Item""

An example of this command is "PxeConfig.exe -regen "DOS Managed" -progress -save" which will regenerate the DOS Managed preboot and show the progress dialog wizard.

There are three methods available for regenerating PXE images:

  1. All known images will be regenerated.

    Example: "PxeConfig.exe -regen *"

  2. Only the default PXE images will be regenerated. The default images include DOS Managed, Linux Managed, WinPE Managed, or (Menu Option IDs 129, 130, and 131)

    Example: "PxeConfig.exe -regen"

  3. A single PXE image will be regenerated.

    Example: "PxeConfig.exe -regen -dos"

Regardless of the mode used, the idea is to reprocess all of the configuration information and create a new configuration. The assumption for this is that the pre-boot environment must be installed.

For example it is not possible to regenerate a Linux pre-boot if the Linux pre-boot environment is not installed. When regeneration happens, a new directory is created and all of the information that needs to be regenerated is copied from its original location to the new folder. Once the copy is complete, the original folder is deleted, and the newly created folder is renamed. If customizations were done to the boot image directory that is being regenerated, these will not be maintained after regeneration.

To specify a pre-boot environment this command supports the "-dos", "-linux", or "-winpe" command line options.

The "name" or "nnn" option is used in place of the OS type in order to allow only one image to be re-generated. Think of a scenario where there are four different DOS boot menus and only one of them is corrupted. Using the "name" allows only the specific menu to be regenerated.

One interesting trick with this command is the use of an asterisk (*) which will regenerated all images in all OS groups.

-delete

This command is used to delete PXE menu items.

The syntax is "PxeConfig.exe -delete -OS -CPU"

An example of this command is "PxeConfig.exe -delete -linux -x86 -ia64" which will delete the Linux preboot environment.

As with any delete command use caution with this command. This command allows the deletion of either a single image, a group of images or all of the images. The order items are listed in the command line is not important unless the use of the "name" or "nnn" fields are used. When using the "name" and "nnn" fields, always use these first and remember that only one can be used at a time.

There is another caveat to this command line which is that if there have been any jobs created that are pointed to the PXE menu item that needs to be deleted, this command will not remove them.

In this scenario, a return code of 7 will be returned. Altiris KB 23829 provides a SQL statement that can be run to help identify this scenario. A combination of the SQL from the KB as well as the command lines can be used to successfully script the deletion.

The use of the "-dos", "-linux" ,"-winpe", or "-other(os)" commands will mark any image in that OS group to be deleted.

It should also be noted that if scripting this operation, a return code of 4 will be used if no PXE image is found that matches the command line options provided.

-find

This command is used to find PXE menu items.

The syntax is "PxeConfig.exe -find -OS"

An example of this command is "PxeConfig.exe -find -winpe 131"

The purpose of the find utility is to be able to search the available PXE menu options to identify the PXE Menu IDs, or to verify that a PXE menu exists. Where this command becomes useful is in the scenario where an external job has been created and needs to be imported into the Deployment Server database.

Each time a PXE menu is created the Deployment Server assigns the menu a Menu Option ID. Menu Option IDs range from 100 to 255. In order to import the job there has to be a way to match the numbers used by each DS server to the corresponding menu item and so the -find option becomes useful.

Similar to the rest of the PxeConfig.exe command line options; there are also three methods available for finding PXE boot menus.

There are three methods available for regenerating PXE images:

  1. Return the first non-zero Menu Option ID that is found.

    Example: "PxeConfig.exe -find"

  2. Return the menu option ID for all pxe boot images that match based on the image name

    Example: "PxeConfig.exe -find "text string""

  3. Return a specific job ID

    Example: "PxeConfig.exe -regen -dos"

Keep in mind that name searches are the best method to use if searching multiple PXE servers. It also helps to remember that each time the "-find" command is called; a return value is available to the script running the find. If nothing is found that matches the search string, a return code of 13 is used. A return code of 12 means some other error happened and is a catch all return code.

-status

This command opens the PXE Configuration utility in interactive mode and displays the Status tab.

The syntax is "PxeConfig.exe -status"

An example of this command is "PxeConfig.exe -status -u "administrator" -p "mypassword" -d "mydomain.com" "

If Deployment Server is configured with role based security, a username and password must be supplied. There is not a lot to say about this mode, which in short provides no management capability or event options. It is a view of the status tab. If anyone has a good example of why this might be useful post a comment with this article.

-default

This command sets the default PXE boot menu

The syntax is "PxeConfig.exe -default "Name" "Option" "

An example of this command is "PxeConfig.exe -default "Linux Managed""

This command is useful in scenarios where there are multiple deployment servers and the Altiris administrator has decided that it is time to move from DOS to Windows PE for the default automation environment. This option will set both the Default boot option and the Initial Deployment boot option to the same value.

The shipping versions of the PXE menus will correspond to the command line "-defaultdos" , "-defaultlinux" , or "-defaultwinpe". Should the configuration not match one of the default menu options use "name" as the command line. For example "PxeConfig.exe -default MyOtherBootMenu".

-set

This command is used to modify the PXEManager.ini file.

The syntax is "PxeConfig.exe -Set" or "PxeConfig.exe -Setvalue"

An example of this command is "PxeConfig.exe -setvalue [PXEServer\\Shared\\DS] InitDeployTimeoutType 0"

The set and setvalue command can be useful in setting specific configuration values. Keep in mind that this is one of the more destructive command line options so make sure a backup copy of PXEManager.ini file exits before experimenting with this command line option.

It is critical that the command line options be in the proper order. The proper order for the command is SECTION, followed by ITEM, followed by VALUE.

In the example above, one of the most commonly changed areas is the Default Boot Options, Initial Deployment Boot Options, the IP address of the Deployment Server, and several other values that often require updates. Keep in mind that any option that includes spaces must be delimited using quotes. An example of this would be to correctly specify an IP address, the value would need to be "192.168.1.15" and include the quotes.

Return values of 0 for this command indicate success. Any other error will return a value of 11 which means one of the input options is incorrect.

A few additional notes on syntax for this command are:

  • Numeric values will be entered without quotes
  • Alphabetic values will be entered with quotes
  • Boolean values must be entered as True or False

One other thing to be cautions of is that if the value portion of the command line is left empty, the value in the PXEManager.ini file will be changed to "". There is no way to delete items using this command and so if this condition happens, it will be necessary to stop the PXE Manager service, edit the PXEManager.ini file by hand and then restart the service.

For all of the command line options above, the table below describes the Return codes and a brief description of what each one means.

Return Codes Description
0 Success
1 Operation cancelled by user
2 Another instance of pxeconfig already running
3 PXE menu item already exists
4 Menu item name / Menu item number does not match
5 Some of the menu items were not regenerated since they contained User Supplied or Floppy generated PXE images
6 Attempt to change OS type or boot image type for existing PXE menu item
7 Error deleting PXE menu item or boot image
8 Pre-boot OS files for specified processor type have not been installed
9 Command line syntax error
10 Error regenerating one or more items
11 Error setvalue section, item not found
12 Error Find input values are not valid
13 Valid return value Find Menu Option not found
100 - 255 Valid return Menu Option IDs from Find

Happy scripting!

Statistics
0 Favorited
1 Views
0 Files
0 Shares
0 Downloads

Tags and Keywords

Comments

Jun 11, 2008 08:08 AM

Instead of trying to copy it, use the create command that is there to build a new one on the other server.

May 28, 2008 05:18 PM

Good food for thought.
I was wondering if these commands could be used to copy a PXE menu item from one server to another.
We have a DOS menu item that is customized and it would be great to creat it on the main server and then run a job on the other servers to replicate this.
Unfortunately we can't do PXE redirection or sharing so each DS server has it's own PXE server in it's own subnet we use at different locations.
Sure would be easier than having to log on to each server to make a global change.

Related Entries and Links

No Related Resource entered.