Generating a support bundle

This guide explains what a support bundle is and how to generate, both from the UI and the CLI.

What is a support bundle

A support bundle is a compressed file containing files from the root of your Jenkins home directory, $JENKINS_HOME, which can be used to assist a CloudBees Support Engineer in diagnosing your issue.

What a support bundle included

In summary, the contents of a support bundle contains:

The following are not included in a support bundle:

  • Credentials

  • Usernames (no, except jenkins user)

  • Job Details

  • Groovy Pipeline Code

An example filename of a support bundle is

The following is an example of the zip file contents:

├── (<-- Hostname)
├── cap
│   ├──
│   └──
├── docker
│   └── Dockerfile
├── load-stats
│   ├── label
│   │   └── master
│   │       ├── gnuplot
│   │       ├── hour.csv
│   │       ├── min.csv
│   │       └── sec10.csv
│   ├── no-label
│   │   ├── gnuplot
│   │   ├── hour.csv
│   │   ├── min.csv
│   │   └── sec10.csv
│   └── overall
│       ├── gnuplot
│       ├── hour.csv
│       ├── min.csv
│       └── sec10.csv
├── nodes
│   └── master
│       ├── checksums.md5
│       ├── dmesg.txt
│       ├── dmi.txt
│       ├── environment.txt
│       ├── file-descriptors.txt
│       ├── logs (<-- Hostname, IP Addresses)
│       │   ├── all_2019-09-23_19.29.56.log
│       │   ├── all_2019-09-23_19.33.20.log
│       │   ├── all_2019-09-23_19.50.20.log
│       │   ├── all_memory_buffer.log
│       │   └── jenkins.log
│       ├── metrics.json
│       ├── (<-- IP Address)
│       ├──
│       ├── pipeline-thread-dump.txt
│       ├── pipeline-timings.txt
│       ├── proc
│       │   ├── cpuinfo.txt
│       │   ├── meminfo.txt
│       │   ├── mounts.txt
│       │   ├── net
│       │   │   └── rpc
│       │   │       ├── nfs.txt
│       │   │       └── nfsd.txt
│       │   ├── self
│       │   │   ├── cmdline (<-- Hostname)
│       │   │   ├── environ (<-- Hostname, Username)
│       │   │   ├── limits.txt
│       │   │   ├── mountstats.txt
│       │   │   └── status.txt
│       │   ├── swaps.txt
│       │   └── system-uptime.txt
│       ├── sysctl.txt
│       ├──
│       ├── thread-dump.txt
│       └── userid.txt (<-- Username)
├── other-logs
│   ├── Argus\ Notifier\ Periodic\ Sender.log
│   ├── Argus\ Notifier\ Periodic\ Sender.log.1
│   ├── Download\ metadata.log
│   ├── Download\ metadata.log.1
│   ├── Download\ metadata.log.2
│   ├── SharedConfigurationSynchronizer.log
│   ├── SharedConfigurationSynchronizer.log.1
│   ├── SharedConfigurationSynchronizer.log.2
│   ├── Template\ Catalogs\ Update.log
│   ├── Template\ Catalogs\ Update.log.1
│   ├── com.cloudbees.jenkins.plugin.metrics.views.Alerter.log
│   ├── com.cloudbees.jenkins.plugin.metrics.views.Alerter.log.1
│   ├──
│   ├──
│   ├──$PeriodicWorkImpl.log
│   ├──$PeriodicWorkImpl.log.1
│   ├── copy_reference_file.log
│   └── health-checker.log
├── plugins
│   ├── active.txt
│   ├── disabled.txt
│   └── failed.txt

16 directories, 78 files

Generating a support bundle from the UI

To generate a bundle, go to the Support link in the web UI.

generate bundle
Figure 1. Generating a bundle

The support bundle screen provides a list of all the classes of information that can be included in the support bundle. Normally it is best to include all the selected information, however there may be some information which you do not want to share for reasons of confidentiality. In such cases you can de-select the information you do not want to include in the bundle.

Click the Generate Bundle to download the bundle to your machine. A bundle is a simple .zip file containing mostly plain text files. You can inspect the contents of this file to assure yourself that it does not contain information you do not want to share with CloudBees. You can even unpack and repack the bundle if there is some specific piece of information that you need to remove from the bundle.

When you are happy with the bundle, attach the bundle to your CloudBees support ticket.

Generating a support bundle from the CLI

If there is a problem accessing theweb UI, of course it is going to be difficult to diagnose those by going to that same UI and getting a bundle. As an alternative, you can use the Jenkins CLI to obtain a bundle from a shell. Before you encounter problems, make sure you have downloaded jenkins-cli.jar from the server (go to /cli/ to get a link). You may also need to make sure you have authenticated to the CLI, for example by uploading an SSH public key to your Jenkins user account.

Then try:

java -jar /path/to/jenkins-cli.jar -s http://server/ support > ./path/to/

This command generates the support bundle and saves it to the path you provided.

Alternatively, if you are using the deprecated and insecure legacy remoting-based CLI, the generated support bundle is saved to a file in your default temporary folder using the filename printed.

You can also request only specific components to include; to see the currently available list, ask for the command’s help:

java -jar /path/to/jenkins-cli.jar -s http://server/ help support

Generating a support bundle when Jenkins will not start

When the CloudBees Support Plugin is installed, it automatically stores a bundle every hour in $JENKINS_HOME/support. These bundles are purged using an exponential retention strategy so that they do not overflow disk space.

If your Jenkins instance is not starting correctly, this is usually due to some class-loading conflict among the set of plugins that you have installed in your instance. Normally such class-loading conflicts just results in one of your plugins failing to load, however in some extreme cases a plugin failing to load can cause a second plugin to render the UI of your Jenkins instance inaccessible.

In such cases, the latest support bundle (and some representative historical versions) can be very helpful for CloudBees in ensuring a rapid response and restoration of your Jenkins to an accessible state.

You can inspect the contents of these file(s) to assure yourself that they do not contain information you do not want to share with CloudBees. You can even unpack and repack bundle(s) if there is some specific piece of information that you need to remove from some bundle(s).

When you are happy with the bundle(s), attach the bundle(s) to your CloudBees support ticket.

Enabling anonymization

If support bundle anonymization is enabled through the global configuration settings, some metadata is replaced with automatically generated anonymized names: nodes, computers, labels, users, items (including jobs), views, hostnames, and IP addresses.

Controlling who can generate support bundles

By default, only Jenkins administrators can generate support bundles. The CloudBees Support Plugin defines an additional security permission within Jenkins (CloudBees Support/DownloadBundle). You can assign this permission to any users that you want to be able to generate support bundles, even the Anonymous user. The content of such bundles can be useful in diagnosing authentication issues that specific users are having.

CloudBees' general recommendation is only to allow trusted users to generate support bundles. Enabling the anonymous user to generate a bundle should be something that is time bounded and used specifically to obtain a bundle from a user who is having issues with authentication.
To reduce the possibility of the support plugin from leaking confidential information about your Jenkins installation, when a non-administrator generates a support bundle, certain specific components are not available for selection. For example, the Environment variables, System properties and Thread dumps components are disabled as these components tend to include information that is often not for general consumption.
generate restricted
Figure 2. Generating a bundle as a user who is not a Jenkins administrator
Copyright © 2010-2019 CloudBees, Inc.Online version published by CloudBees, Inc. under the Creative Commons Attribution-ShareAlike 4.0 license.CloudBees and CloudBees DevOptics are registered trademarks and CloudBees Core, CloudBees CodeShip, CloudBees Jenkins Enterprise, CloudBees Jenkins Platform, CloudBees Jenkins Operations Center and DEV@cloud are trademarks of CloudBees, Inc. Oracle and Java are registered trademarks of Oracle and/or its affiliates. Jenkins is a registered trademark of the non-profit Software in the Public Interest organization. Used with permission. See here for more info about the Jenkins project. The registered trademark Jenkins® is used pursuant to a sublicense from the Jenkins project and Software in the Public Interest, Inc. Read more at Apache, Apache Ant, Apache Maven, Ant and Maven are trademarks of The Apache Software Foundation. Used with permission. No endorsement by The Apache Software Foundation is implied by the use of these marks.Other names may be trademarks of their respective owners. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this content, and CloudBees was aware of a trademark claim, the designations have been printed in caps or initial caps. While every precaution has been taken in the preparation of this content, the publisher and authors assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein.