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 opensolaris.org=http://pkg.opensolaris.org
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:

ManifestServ  
Usage: /bin/ManifestServ [-d] [-h|-?] [-s] [-t] [-v] [-f <validation_file_base> ] 
    [-o <out_manifest.xml file> ] <manifest.xml file> 
where: 
  -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
/usr/share/distro_const/DC-manifest.rng

# 

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:

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

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/grub_setup.py either doesn't exist 
or is not an executable file 
validate_node: Content "/usr/share/distro_const/grub_setup.py" 
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/grub_setup.py is missing, and the error message points directly to the problem. In this case, either grub_setup.py 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.