Back to Zing Documentation Home

About the zing-core-bundler Script

ZVM Core Bundling

If automatic core bundling is not enabled, you can manually bundle the core files with the shared libraries that were in use by the ZVM instance running the Java application when it failed.

If you are running a system based on Red Hat Enterprise Linux 5.2 or CentOS Linux 5.2, the automatic core bundler is not on, so core files need to be bundled manually. For this purpose the script zing-core-bundler is provided. This script, as part of the ZST installation, is located in the /usr/sbin subdirectory of the ZST installation.

The zing-core-bundler bundles the required files needed to debug a Zing Virtual Machine core. It assembles, collects, and bundles the core file along with the shared objects, data, and executable files in-use to an encrypted gzipped tarball (.tgz.gpg) archive.

To manually bundle the core file with shared libraries:

  1. On RHEL, SLES, and Ubuntu systems, ensure the development tools package group is installed.

    $ yum groupinstall 'Development Tools'

    Note:

    Selected development tools are required to bundle RHEL 5 core files. If they are not installed, the shared libraries, which were used at the time of the crash and are essential to processing the core file, are not included.

  2. Locate the core file.

    Core files are bundled and stored in the current working directory of the process that crashed.

    Note:

    Typically, you create a core bundle on the system where the core file was created, for example hostA. If you run the zing-core-bundler command with a copy of the core file on a different system, for example hostB, then include the -bundle-on-current-host option.

  3. On Ubuntu systems, ensure that the strings command is available. If it is not, install the package, binutils.

    # apt-get install binutils

  4. If you use the jsvc tool to start your application, to generate Zing core files:

    # kill -SIGABRT <PID>

  5. Ensure /usr/sbin is in your Zing executable path. For example:

    To your appropriate profile file, add:

    export PATH=/usr/sbin:$PATH

  6. Run the zing-core-bundler command. At the ZVM host command line,where ZST is installed:

    To create a bundle with only related shared libraries that does not include the .jar files.

    /usr/sbin/zing-core-bundler -core core<pid>

    For example:

    $ /usr/sbin/zing-core-bundler -core core.1234 -getall -hsfile hs_err_pid1234.log

    A compressed and encrypted tar file ending in .tgz.gpg is returned.

    In this example, the package contains the core file, the .jar files, and because the -getall option is specified, it also contains the related shared libraries which were used in the ZVM instance running the Java application.

    • The -getall option ensures the bundle contains all application related data including the .jar files.

    • The -hsfile option creates an additional file that provides additional information useful for support to identify issues.

    Notes:

    • Encryption error

      If there is a file with the same name as the core bundle, the core bundle will not be encrypted and the following message is displayed in the core bundling response.

      INFO: Encrypting core bundle libs.1234.tgz ... gpg: libs.1234.tgz: encryption failed: File exists ERROR: Encryption failed. WARNING: Core bundle is not encrypted INFO: Core bundle at libs.1234.tgz

    • Bundler host error

      Typically, you create the bundle on the same system where the core file was created. If you are not creating the bundle on the originating core file system, and you did not specify the required option, the following message is displayed in the core bundling response.

      ERROR: The bundler must run on host <hostname> ERROR: Use the argument '-bundle-on-current-host' to bundle on this host

    To create the bundle on a different system:

    1. Copy the core file from the originating core file system (hostA) to hostB.

    2. On hostB, include the -bundle-on-current-host option when you run the zing-core-bundler command.

The zing-core-bundler syntax and options are listed below.

zing-core-bundler [-core COREFILE][-getexe] [-getall] [-exepath executable file path] [-hsfile hs_err_pid<pid>.log file] [-decrypt file] [-passwordfile password file path] [-bundle-on-current-host

Option Description
-core Specify the core file to be bundled.
-bundle-on-current-host Create bundle on current host. This allows bundling a core file that was generated on another host.
-exepath Specify the path of the binary that was used to invoke Zing Virtual Machine.
-decrypt Specify file to decrypt
-getall Include all possible files associated with the crash. This includes shared objects, data, and executable files.
-getexe Include non-java executable with the bundle. This is bundled if it is available on the host at the time of bundling.
-hsfile Explicitly specify the path of the hs_err file.
-passwordfile Specify decryption password file.
-help Print options help.
-output-dir | -o Bundle will be produced at the location specified.
  1. Locate the bundled libs.<corepid>.tgz.gpg file.

The libs.<corepid>.tgz.gpg file is created in the current directory.

For example, If you execute the command from /home/test. The bundled libs.<corepid>.tgz.gpg file is created in /home/test.

Ensure you have write permissions in the executing directory. In this example, /home/test.

  1. Send the generated bundle to Azul for failure analysis.

Decrypting Core Files

Core bundles created through zing-core-pattern, whether they are automatically or manually created and bundled, are encrypted. Files contained in the core bundle are not encrypted individually. The core bundle filename format is: libs.<corepid>.tgz.gpg, where <corepid> is a unique ID specific to the process that encountered an error and crashed.

Note:

Core files are not encrypted if zing-core-pattern is disabled.

To decrypt the Zing core bundle:

  1. Locate the core bundle file.
  2. Run the command:

$ /usr/sbin/zing-core-bundler –decrypt libs.<corepid>.tgz.gpg

For example:

$ /usr/sbin/zing-core-bundler -decrypt libs.12830.tgz.gpg INFO: Decrypting file libs.12830.tgz.gpg gpg: CAST5 encrypted session key gpg: encrypted with 1 passphrase gpg: encrypted with RSA key, ID 2934892D SUCCESS: Decrypted file libs.12830.tgz

Core Bundling with Docker Containers

You can select one of the following options to collect core dumps from the Docker container:

Option 1

Install zing-core-pattern to dump and bundle cores while using docker:

# system-config-zing-core-pattern enable

Bundles will be kept under /var/crash/<docker_container_id> on the host.

Option 2

Use zing-core-bundler script to bundle the core dumped by a docker container process:

# zing-core-bundler -c <core> --dockercontainerid <docker_container_id>

Note: The container should be running while using the above script.

© Azul Systems, Inc. 2020 All rights reserved.

Privacy Policy | Legal | Terms of Use