JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
Oracle Solaris 11 Express Distribution Constructor Guide     Oracle Solaris 11 Express 11/10
search filter icon
search icon

Document Information

1.  Introduction to the Distribution Constructor

2.  Design and Build Oracle Solaris Images

System Requirements

Customize Your Image by Editing the Manifests

Modifying Manifest Contents

Further Customize an Image Using Finalizer Scripts

Creating Custom Finalizer Scripts

Characteristics of Finalizer Scripts

Using the Manifest Reader

Specifying Key-Value Pairs

Building an Image

Building an Image in One Step

Building an Image in Stages

Building an Image in Stages by Using Checkpoint Options

Troubleshooting the Distribution Constructor

I Get Error Messages When I Download a Package

How to Debug Manifests With Validation Errors

Debugging Semantic Validation Errors

Checking Data

Additional Installation Information

3.  x86: Design and Build a Virtual Machine

A.  Custom Finalizer Scripts, Examples

Troubleshooting the Distribution Constructor

Review the following troubleshooting items.

I Get Error Messages When I Download a Package

Make sure the pkg(1) command on your system is working correctly, and your connection with the IPS server is stable. Sometimes, IPS times out when trying to download a big cluster of packages. To check outside of the distribution constructor environment, try to mimic what the constructor does in terms of installing packages. Assume the root role by executing the su - command. Then, try the following commands, confirming that the commands work correctly.

pkg image-create -F -a
pkg -R /tmp/test_img install SUNWcsd
pkg -R /tmp/test_ima install SUNWcs
pkg -R /tmp/test_img install slim_install

How to Debug Manifests With Validation Errors

If a manifest does not validate, as could be the case after the manifest has been changed, run the ManifestServ utility in a verbose mode to find the error.

The ManifestServ utility, /usr/bin/ManifestServ, with no arguments displays the following usage:

Usage: /bin/ManifestServ [-d] [-h|-?] [-s] [-t] [-v] [-f <validation_file_base> ] 
    [-o <out_manifest.xml file> ] <manifest.xml file> 
  -d: turn on socket debug output (valid when -s also specified) 
  -f <validation_file_base>: give basename for schema and defval files 
      Defaults to basename of manifest (name less .xml suffix) when not provided 
  -h or -?: print this message 
  -o <out_manifest.xml file>: write resulting XML after defaults and 
      validation processing 
  -t: save temporary file 
      Temp file is "/tmp/<manifest_basename>_temp_<pid> 
  -v: verbose defaults/validation output 
  -s: start socket server for use by ManifestRead 

The distribution constructor validates the manifest against an XML schema and a default manifest. ManifestServ enables you to perform a manual validation, using a verbose mode which shows where any problems are.

Example 2-3 Debugging Schema Validation Errors

The following example demonstrates a case where the manifest didn't validate against the schema. The boldface message below indicates this is a schema validation error.

# distro_const build my_distro.xml 
/usr/share/distro_const/DC-manifest.defval.xml validates 
/tmp/all_lang_slim_cd_x86_temp_7861.xml:350: element pair:
Relax-NG validity error : Element pair failed to validate attributes
/tmp/my_distro_temp_7861.xml fails to validate
validate_vs_schema: Validator terminated with status 3
validate_vs_schema: Validator terminated abnormally
Error validating manifest against schema


Run ManifestServ, /usr/bin/ManifestServ, specifying the -t option, in order to save the temporary file, and the -v option, in order to provide verbose output which will have the line number of the error.

# ManifestServ -f /usr/share/distro_const/DC-manifest -t -v manifest_file
ManifestServ -f /usr/share/distro_const/DC-manifest -t -v my_distro.xml 
/usr/share/distro_const/DC-manifest.defval.xml validates 
Checking defaults for name 
Checking defaults for distro_constr_params/distro_constr_flags/stop_on_error 
Checking defaults for distro_constr_params/pkg_repo_default_authority/main/url 
(omitted content)
/tmp/my_distro_temp_7870.xml:350: element pair: Relax-NG validity error
: Element pair failed to validate attributes 
/tmp/all_lang_slim_cd_x86_temp_7870.xml fails to validate 
validate_vs_schema: Validator terminated with status 3 
validate_vs_schema: Validator terminated abnormally 
Error validating manifest against schema /usr/share/distro_const/DC-manifest.rng 
Error running Manifest Server 
schema_validate: Schema validation failed for DC manifest /tmp/my_distro_temp_7870.xml 

The temporary file will be named near the end of the output. In the example above, the file is /tmp/my_distro_temp_7870.xml. Per the bold error messages, open that file and go to line 350 to find the issue. In this example, the line 350 looks like this:

    <pair value='/usr/share/distro_const/slim_cd/slimcd_iso.sort' key='iso_sort'/> 
    <pair VaLuE='myvalue' key='mykey'/>

The attribute, VaLuE, is incorrect. This contrived example should have value in all lowercase letters, as shown the line immediately above that one. The second to last message line states that the schema validation fails. The schema used for validation for the distribution constructor is /usr/share/distro_const/DC-manifest.xml. The schema shows that the only attributes for <pair> are <value> and <key>, not <VaLuE>.

Debugging Semantic Validation Errors

Semantic validation is also done. Semantic validation checks content for “meaning” and context errors as opposed to checking only the syntax. For example, finalizer scripts listed in a manifest can be validated to confirm that the scripts are executable files.

The following shows a case where the manifest failed semantic validation.

# distro_const build -l my_distro_sem.xml 
/usr/share/distro_const/DC-manifest.defval.xml validates 
/usr/share/distro_const/ either doesn't exist 
or is not an executable file 
validate_node: Content "/usr/share/distro_const/" 
at img_params/output_image/finalizer/script/name did not validate 
Error validating manifest tree content 

Semantic validation employs functions to do the validation, and those functions print error messages explaining why the manifest failed validation. In this contrived case, the file /usr/share/distro_const/ is missing, and the error message points directly to the problem. In this case, either needs to be restored, or, if appropriate, the reference to that file needs to be removed from the manifest.

You can still run ManifestServ with -v to get more details on semantic validation, but this command option will merely list the one failure among many successes, and may produce output which is harder to read than when -v is not specified.

Checking Data

Once validation and other preprocessing is completed, ManifestServ prompts for data to dump and check. This step is more useful for testing the data serving process rather than testing the data itself, since the data is plainly visible in the manifest itself.