ZFD Image Engine Command-line parameters and Troubleshooting Tips.
(Last modified: 30Sep2005)
This document (10053996) is provided subject to the disclaimer at the end of this document.
goal
ZFD Image Engine Command-line parameters and Troubleshooting Tips.
fact
Novell ZENworks for Desktops 3.0
Novell ZENworks for Desktops 4.0.1 - ZfD4.0.1
Novell ZENworks 6.5 Desktop Management - ZfD6.5
Novell ZENworks 7 Desktop Management - ZfD7
Novell ZENworks Imaging
fix
The purpose of this document is to acquaint the reader with the command-line options available in the imaging engine (internal version a.0.g). For other Linux commands you can use in troubleshooting the Imaging process, see Simple Linux Command Reference.
FEATURE LEVELS
The image engine has two levels of features: standard and power user.
The standard features makes assumptions about the way most imaging operations should be handled. When making image archives. All partitions (except protected partitions) are included, and on restoration, all partitions are either restored to their original size or shrunk to fit on the current hard drive.
The power user features allow the user to write scripts to control almost every aspect of the imaging process.
BASIC MODES OF OPERATION
There are several basic modes of operation, which are detailed in this section: help, information, partition dump, automated, partitions manipulation, creating archives, restoring archives, and multicast. This section will briefly describe the standard features and syntax for each mode of operation.
HELP
This operation is the default mode if any syntax errors are encountered, or if no parameters are given. It is not currently implemented. The syntax will be:
Img help
It is not necessary to type 'help' in full. Just enough to make it distinct from any other possible command
INFORMATION
This operation will display the detected hardware, and some of the image-safe data. This operation will allow the user to see what information is being sent to the proxy servers for resolution of policies. The syntax is:
Img information
It is not necessary to type 'information' in full, just enough to unique.
PARTITION DUMPS
This operation will display the partitions detected by the imaging engine. This operation is extremely critical, since it will show the partition numbers that should be used in most of the power user features and in the partition manipulation operations.
There is an optional parameter in this operation that will also display all detected devices on the system. The syntax is:
Img dump [geo]
It is not necessary to type these options in full, just enough to be unique. Additionally, a shortcut for both options is:
Img dg
AUTOMATED
This operation will query the designated proxy for any pending imaging tasks. When this operation starts, the image engine gathers information on the computer's hardware, and the image-safe data and sends it to the proxy server and waits for a response.
(The proxy server it will attempt to communicate with is designated by the environment variable PROXYADDR and can be set in a script using the export command, or by changing the settings.txt file.)
If the proxy determines that there are no pending tasks, then the image engine returns with an error code of 0 to the Linux operating system.
If there are pending jobs, then they are executed immediately, and appropriate return codes are returned to the operating system:
0 Successful imaging task completed. No changes to the hard drive.
0 No imaging tasks attempted.
1 Successfully received one or more images. The hard drive has been altered.
Other Error codes.
The syntax for this operation is:
Img auto
It is not necessary to type `auto' in full, just enough to be unique.
PARTITION MANIPULATION
This operation encompasses three related tasks: creating partitions, deleting partitions and setting partitions active (ie making them bootable partitions). This operation is invoked by having the first letter of the parameter a 'p.'
The second letter controls which operation will be invoked.
C will create a new partition in an empty slot.
D will delete an existing partition.
A will set the specified partition as the active partition.
The last character in this parameter must be the partition number that will receive the action. The syntax is:
Img p<c|d|a><partition number>
<Partition number> is the number given by the partition dump operation.
If you want to create a new partition, extra parameters must be specified:
Img pc<partition number> <partition type> [partition size] [c<cluster size>]
Partition type must be a fully supported partition type (FAT12, FAT16, FAT32, or NTFS).
Partition sizes are given in Megabytes. If a partition size is not specified, the largest valid size for that partition type is created in the space indicated.
The cluster size parameter is only supported by the NTFS file system (The cluster sizes for FAT file systems are determined by the size of the partition).
All partitions are automatically sized according to the specific geometry of the hard drives involved.
When the partitions are created, they are also pre-formatted. The pre-formatting process is dependent upon the actual file system being created. It is usually a subset of the formatting process performed on new partitions by the various operating systems, but is not enough to be recognized as a valid partition by those operating systems.
For example, if I create a new FAT16 partition, the imaging engine will pre-format it, but neither DOS nor Windows will allow you to use it for file storage.
However, the pre-format process is enough to allow the imaging engine to start inserting files into the partition.
In order for other operating systems to recognize it as a valid partition, at least one base image must be placed in the new partition.
See the power user features for further information.
CREATING IMAGE ARCHIVES
This operation is used to manually create image archives. Any local (writeable) destination and file name may be specified. You may also specify locations on servers running image proxy services. A local archive is specified by appending an `l' after `make' (ie `makel'). An archive on the proxy is specified by appending a 'p' after 'make' (ie 'makep'). Since it is not necessary to use the entire word `make' these commands are usually shortened to 'ml' and 'mp,' respectively.
As they each have different command-line syntax, they are given separately.
Local syntax:
Img ml[partition number] <path>
The optional partition number is the partition slot number of a FAT partition where the archive is to be stored. This partition is excluded from the image archive. If no partition number is given, then the archive will be created on the Linux partition.
Proxy syntax:
Img mp <proxy IP address> <uncPath>
Currently, the proxy IP address must be the actual IP address, but we are looking tino providing hosts file and DNS lookup. You are asked to specify a target proxy so that you can place an archive onto a proxy other than the one pointed to by PROXYADDR. Be aware, however, that logging information will still be sent only to the PROXYADDR proxy.
The UNC path provided must resolve to a valid path on the indicated proxy. Directories will not be created, and any existing file at that path will be overwritten.
RESTORING IMAGE ARCHIVES
This operation is used to restore an image archive onto the computer. All current (non-protected) partitions will be overwritten.
The syntax is identical as the operations to create an image archive, except that you use 'restore' instead of 'make.' For abbreviated command-line, use 'r' instead of 'm.'
The restoration operation can take an additional parameter as well to specify which file set in the image to restore. By default, all files belong to all sets, and by default, file set 1 is restored. By using the image explorer, you can exclude certain files from different sets, and then use the optional command-line parameter to specify which set will be restored.
Local syntax:
Img rl[partition number] path [s<set number>]
Proxy syntax:
Img rp <proxy IP address> <uncPath> [s<set number>]
Multicast
Note: This section describes the way multicast is currently implemented, which is not necessarily the final implementation.
This operation allows one workstation to act as the master and send its hard drive contents to all participating slave stations.
This operation uses the command-line parameter 'session' to avoid confusion with the 'm' for making new image archives.
The syntax is:
Img session <session name>
Each station that will participate in the multicast session should use the same command-line parameters.
Session name is any unique string to identify this multicast session from others that will be active concurrently. This string is used to hash a multicast address, so there is a small chance that 2 strings will yield the same multicast address.
Multicast addresses are class D IP addresses. In order to ease wire sniffing, trouble-shooting and LAN traffic analysis, the imaging engine will always use 231 as the first octet in its address.
When started, each station will wait for the user to determine which stations will act as the master. This station should be the computer whose hard drive you wish to duplicate on all the other stations.
The master is designated by the user pressing 'm' on the keyboard of the master station.
Once the master has been designated, the slave stations will attempt to register with the master and get a unique session identifier. This identifier is unique to that station for that session. If for some reason the station is rebooted before the session starts, it will always receive the same identifier.
The master displays a running count of registered slaves. When the desired number of stations have registered, the user starts the session by pressing 'g' on the master's keyboard. Any stations attempting to join the session once it has begun will be denied.
Once the session is over, the master displays a list of stations that did not successfully complete the image.
Please note that the multicast operations are dependent upon the multicast features configured in the users network equipment. Possible problems might be not routing multicast packets, stations outside the defined scope of multicast on the switches, etc.
OTHER STANDARD COMMANDS
At the bash prompt, type 'export'. The 'export' command will show you the Linux variables that are set. Use this command to verify the IP address of the Proxy Server PROXYADDR.
The syntax is:
export
At the bash prompt, type 'ifconfig'. The 'ifconfig' command will show you the ethernet statistics about your NIC including the MAC address and its IP address.
The syntax is:
ifconfig
At the bash prompt, type 'zdisk -detect'. The 'zdisk -detect' command determines if there is a ZENworks partition on the hard drive or not.
The syntax is:
zdisk - detect
POWER USER FEATURES
This section explains the extra features provided for power users to modify the behavior of the basic operations. They are implemented as extra parameters added after the parameters explained above.
HELP
None.
INFORMATION
None.
PARTITION DUMPS
None.
AUTOMATED
None.
PARTITION MANIPULATION
None.
CREATING IMAGE ARCHIVES
The default behavior of this operation is to make an archive of all partitions on the computer. However, this may no always be what is desired.
Additional parameters have been provided to allow you to specify partitions that you wish to be excluded from the archive. The syntax is:
Img ml /images/thisImage.zmg [x<partition number>]
Again, the partition number is derived from a partition dump. Any number of partitions may be excluded, using multiple parameters. For example,
Img ml /images/thisImage.zmg x2 x3
Will exclude both partitions 2 and 3. All other partitions will be included.
RESTORING IMAGE ARCHIVES
The default behavior of this operation is to delete all (non-protected) partition on the computer, create the partitions described in the archive, and insert the files into these partitions.
Again, this may not always be the best solution. For one thing, you may wish to have the same partitions, but you may want a particular partition to be larger than it was in the original computer. The standard features will shrink partitions to fit, but will not grow partitions on the fly.
Or you may wish to restore only a single partition from an archive.
Both of these objectives can only be accomplished by using the power user options, and usually by writing a script that calls the imaging engine multiple times for different operations.
It is important to understand that when you use the power user features of archive restoration, none of the existing partitions are destroyed. All files will be placed in existing partitions. Careless use of these features can greatly degrade performance.
The power user features of archive restoration allow you to change the mappings of partitions in the archive to physical partitions in the computer. The syntax follows.
Img rl /images/img1.zmg a<archive partition>:p<physical partition>
This syntax tells the engine to place the specified partition in the archive into the specified physical partition.
For example.
Img rl /images/img1.zmg a1:p2
Tells the imaging engine to place the first partition in the archive onto the second physical partition.
You must specify at least 1 partition mapping, or the imaging engine will use the standard features. You may specify as many mappings as are needed. You may map multiple archive partitions onto a single physical partition, but archive partitions can only be mapped to a single physical partition (a1:p1 a2:p1 is valid, but a1:p1 a1:p2 is not).
MULTICAST
None.
SAMPLE SCRIPTS
This section gives some sample scripts for possible scenarios.
SCRIPT 1 -- ENLARGING A PARTITION THROUGH IMAGING
Suppose that an image was taken of a user's computer when he had a single FAT32 partition on a 4GB hard drive. The user has upgraded his drive to 12GB and wishes to have the original image, but the partition expanded to fill the hard drive.
If the standard features are used, then the imaging engine will only create a 4GB partitions, since that was the original size. To create and image into a larger partition, we must use the power user options in a script.
Img pd1 #delete all existing partitions
Img pd2
Img pd3
Img pd4
Img pc1 FAT32 12000 #create a partition to receive the archived files
Img pa1 #set the new partition as the active partition
#The following command will place the first archive partition into the
# first physical partition. Without the partition mapping at the end of
# the line, the partition we just created would be deleted and a 4GB
# partition would be created in its place.
Img rp 10.1.1.1 //prv-imgserv/imgvol/images/win98.zmg a1:p1
SCRIPT 2 -- RESTORING JUST THE DOS PARTITION OF A NETWARE SERVER
This script supposes that for some reason you have lost the DOS partition on your NetWare server, but the NetWare volumes are intact. You want to restore just the DOS partition without losing the existing NetWare partition, it contents, or its DS membership.
Or perhaps you just want to refresh the DOS partition without going through the lengthy restoration of the NetWare partitions
Img pd1 #delete the current DOS partition
Img pc1 FAT16 #Must be MS-DOS readable, so use FAT16.
# Don't specify the size, it will be sized to fill the
# space before the NetWare partition.
Img rp 10.1.1.1 //prv-imgserv/imgvol/nw5.zmg a1:p1
(See ZFD 4.0.1 Troubleshooting Guide, Image Doesn't Fill the Entire Hard Disk)
Another option (using Image Explorer) to fill the hard disk if the image was created on a workstation with a smaller single partition than the target workstation:
Steps to make the partition take the whole drive.
a. Make image file with the one partition in it.
b. Open the image file with Image Explorer (IMGEXP.EXE)
c. View properties on the partition.
d. Set the original size to a KB value larger than any of the hard drives you have in your machines.
e. Save the image.
f. Restore the image.
IMG can stop properly if the Original Size is larger than the target partition. We can't continue past the Original Size if it is smaller than the target partition.
SCRIPT 3 -- PRESERVING USER FILES DURING IMAGING
In this scenario, you have a number of files on the users hard drive that you want to move to preserve from an impending imaging operation. You also wish to place these files on a different partition so that his system partition can be safely re-imaged.
Use the Zen image explorer to create an add-on image file containing the file you wish to move into the new partition. Simply drag the desired directories from the Windows explorer into the image explorer.
The following script assumes that the user's computer has an associated workstation object in the directory tree, and has been assigned an image.
Instead of just rebooting the computer, try using the following script:
Img auto #get the base image from the proxy
Img pc2 NTFS 2000 c8 #create a 2GB NTFS partition with a 4k cluster
#note that this partition is created in slot 2
#Now place the image of the user's files onto the new partition.
Img rp 10.1.1.1 //prv-imgserv/imgvol/images/userFiles.zmg a1:p2
SCRIPT 4 -- JUST FOR FUN
This is the same as the scenario for script 3, but modified beyond all reason just to show some possibilities.
Suppose that you now wanted to create multiple partitions of different type inside an extended partition, and restore the user's files to each partition. Here's the script:
Img auto #get the base image from the proxy
Img pc2 ext 3000 #create an extended partition of 3GB
Igm pc2 fat16 1000 #Note that these partitions are created inside the
# extended partition
img pc2 fat32 1000
img pc2 ntfs
#Now restore the user's files to each of the new partitions
Img rp 10.1.1.1 //prv-imgserv/imgvol/images/userFiles.zmg a1:p3
Img rp 10.1.1.1 //prv-imgserv/imgvol/images/userFiles.zmg a1:p4
Img rp 10.1.1.1 //prv-imgserv/imgvol/images/userFiles.zmg a1:p5
Troubleshooting Tips:
Troubleshooting Tips to use prior to making an image:
-After making the Imaging Boot Disks, modify the SETTINGS.TXT.
-Specify an IP address for the Imaging Proxy Server (ie PROXYADDR=137.65.87.100).
-Remove the # in front of MANUAL=YES to cause the Imaging Boot Disks to boot up in manual mode.
-Remove the # in front of PROMPT=YES to cause you to be prompted for each configuration setting during the imaging boot up process.
-Boot from the disks and follow the prompts until you get to the 'bash' prompt.
-When executing commands at the 'bash' prompt, pay close attention to the messages on the server console where the proxy server is running.
-To verify the proxy address type 'export' at the 'bash' prompt.
-To verify the IP address information type 'ifconfig' at the 'bash' prompt.
-To query the proxy server for any imaging tasks type 'img auto' at the 'bash' prompt. This should return with "Operation Successful."
-To display all information sent to the proxy server type 'img info h' at the 'bash' prompt. It querys the proxy server to see if there is any work to do and if there is no work to do, it reports back that it successfully did not do any work.
-To display information about the Image Safe Data that the Linux engine has received from NDS, type 'img info z' at the 'bash' prompt. If there is no workstation data, this means that the workstation object has not been imported into NDS or that the Image Safe Data Agent has not been run on the workstation. See "Triggering Unattended Imaging Operations" in the Getting Started Guide for further details.
Adding IMG command-line parameters to ZW 6.5 and 7 Administration Guide has been submitted to Novell Engineering.
document
| Document Title: | ZFD Image Engine Command-line parameters and Troubleshooting Tips. |
| Document ID: | 10053996 |
| Solution ID: | NOVL14641 |
| Creation Date: | 08Jun2000 |
| Modified Date: | 30Sep2005 |
| Novell Product Class: | Beta Management Products NetWare |
disclaimer
The Origin of this information may be internal or external to Novell. Novell makes all reasonable efforts to verify this information. However, the information provided in this document is for your information only. Novell makes no explicit or implied claims to the validity of this information.
Any trademarks referenced in this document are the property of their respective owners. Consult your product manuals for complete trademark information.