Back to Zing Documentation Home

About the core-bundler Script

The core-bundler script is a self-contained bash script introduced in ZVM 19.06.0.0. It works well in a container environment.

When the Zing VM crashes, a core file is dumped on a disk (if core dump is configured and enabled). See Core Bundling with Zing for more information.

The core-bundler script is used to create an encrypted bundle containing the core file along with object files used by the crashed application and log files produced by ZVM.

It collects and bundles the core file along with the dynamic libraries to an encrypted gzipped tarball (.tgz.gpg) archive.

core-bundler requires gpg, gtar/tar, pigz/gzip, gawk/awk.

The core-bundler script does not require installation and is located in the <zvm installation directory>/etc/core-bundler directory once Zing is installed on your system.

Using core-bundler

The core-bundler syntax and options are listed below.

Usage: core-bundler -h|--help

core-bundler <command> <args>

Command Description
create Creates an encrypted archive with files needed to successfully debug the core dump.
extract

Extracts an encrypted core bundle to the current directory.

help

Provides information about a specific command usage.

Creating an Encrypted Bundle

To create a bundle, use the core-bundler create command:

core-bundler create [--hsfile <hsfile>] [--docker-container <cid> | --docker-image <iid> [-v <vlist> ...]] [<force-options> ...] <core>

Option Description
<core> Specifies the path to the core file to create a bundle for.
<hsfile>

Specifies the path to the hs_err log file left by the same VM process.

Default: hs_err fileis in the same directory as the corefile.

<cid>

Docker container ID of the container that dumped the core or of a similar container (if the original one is not available).

<iid>

Docker image ID of the image that can be used to create a container similar to the one that dumped the core.

<vlist>

Docker volumes mount list (in the format of -v <src>:<dst>). Multiple -v options allowed.

<force-options>

core-bundler is interactive by default but you can force some/all actions by providing the following options:

  • --no-host-check forces bundling on the current host even if it differs from the host where coredump was produced
  • --no-preview does not open an EDITOR to preview the list of files to bundle
  • --no-space-check does not perform a free disk space check
  • --overwrite overwrites the bundle if a file with the same name already exists

For example:

$ /opt/zing/zing-jdk8/etc/core-bundler create core.57075 core-bundler version 0.3 Extracting hostname from the core file. Could take a while ... Done The bundle file will contain core file, log files, executable, dynamic libraries and some system information. For security reasons the bundle will be encrypted. Do you want to review (and/or modify) list of files to be included before proceeding? ([Y]es / [N]o / [C]ancel) [default 'n']: n Creating an encrypted bundle: /tmp/corelibs.57075_testhost.tgz.gpg ... Encrypted bundle file has been created and is ready to be shared with Azul! File: /tmp/corelibs.57075_testhost.tgz.gpg ** PLEASE DO NOT UPLOAD THE PASSWORD FILE TO AZUL ** Azul already has a private key which can decrypt the core bundle. The password is only for your use, in case YOU need to extract files from the bundle. To extract the file use core-bundler extract corelibs.57075_testhost.tgz.gpg.

Extracting an Encrypted Bundle

The password file that is created next to the bundle file can be used to decode/extract files from the bundle.

To extract an archive, use the core-bundler extract command:

core-bundler extract [--list-only] <encrypted-bundle>

Option Description
<encrypted-bundle> Specifies the path to the encrypted bundle (corelibs.xxxx.tgz.gpg).
--list-only

Does not extract files. Lists the archive content only.

.

For example:

$ /opt/zing/zing-jdk8/etc/core-bundler create /tmp/corelibs.57075_testhost.tgz.gpg core-bundler version 0.3 Extracting data from /tmp/corelibs.57075_testhost.tgz.gpg ... Done

The above command extracts the content of the bundle to the current directory.

Dealing with Core Files from Docker Container Environment

Core files dumped by the Zing VM while running in a container need to be co-bundled with the same dynamic libraries that were used by the Zing VM during the crashed run. So the core-bundler script needs a way to access files from the container.

If the Docker container is either still alive or was started without the --rm option, one can use the --docker-container <cid> option to pass the ID of the container to the script.

In this case, the script will auto-detect all the mappings that are used by the container and prepare a bundle:

For example:

$ /opt/zing/zing-jdk8/etc/core-bundler create core.15 --docker-container 123abc456def core-bundler version 0.3 The bundle file will contain core file, log files, executable, dynamic libraries and some system information. For security reasons the bundle will be encrypted. Do you want to review (and/or modify) list of files to be included before proceeding? ([Y]es / [N]o / [C]ancel) [default 'n']: n Creating an encrypted bundle: /tmp/corelibs.15_123abc456def.tgz.gpg ... Encrypted bundle file has been created and is ready to be shared with Azul! File: /tmp/corelibs.15_123abc456def.tgz.gpg PLEASE DO NOT UPLOAD THE PASSWORD FILE TO AZUL Azul already has a private key which can decrypt the core bundle. The password is only for your use, in case YOU need to extract files from the bundle. To extract the file use core-bundler extract corelibs.15_123abc456def.tgz.gpg.

If the container is not available, you can use the --docker-image option to specify an image ID that could be used to re-create the environment used during the crashed run. It is important to provide an image that has the same set of dynamic libraries installed.

Ideally, it should be the same image that the container was created from.

Note, that in this case the script has no information about Docker Volumes mappings. So you have to provide them with -v <vlist> option(s):

For example:

$ core-bundler create core.15 --docker-image fed654cba321 -v /tmp:/cores -v /home/user/data:/data --no-preview core-bundler version 0.3 Creating an encrypted bundle: /tmp/corelibs.15_45e64c65dd4b.tgz.gpg ... Encrypted bundle file has been created and is ready to be shared with Azul! File: /tmp/corelibs.15_45e64c65dd4b.tgz.gpg PLEASE DO NOT UPLOAD THE PASSWORD FILE TO AZUL * Azul already has a private key which can decrypt the core bundle. The password is only for your use, in case YOU need to extract files from the bundle. To extract the file use core-bundler extract corelibs.15_45e64c65dd4b.tgz.gpg.

 


© Azul Systems, Inc. 2020 All rights reserved.

Privacy Policy | Legal | Terms of Use