Skip Navigation Links | |
Exit Print View | |
Oracle Solaris 11 Express Distribution Constructor Guide Oracle Solaris 11 Express 11/10 |
1. Introduction to the Distribution Constructor
2. Design and Build Oracle Solaris Images
Customize Your Image by Editing the Manifests
Further Customize an Image Using Finalizer Scripts
Creating Custom Finalizer Scripts
Characteristics of Finalizer Scripts
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
Additional Installation Information
Review the following troubleshooting items.
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
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>.
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.
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.