Toolbelt is an add-on BOSH release that provides a set of packages that are indispensible in troubleshooting and diagnosing issues on BOSH deployments.
Yes, yes, conventional wisdom holds that you ought not be SSHing into your BOSH VMs to do things, but when systems break down, on-box troubleshooting is often the fastest way to cut through to the heart of the issue.
But first, you need a Toolbelt.
To outfit your BOSH VMs with awesome tools, first upload Toolbelt to your BOSH director:
bosh target https://192.168.50.4:25555
bosh upload-release https://bosh.io/d/github.com/cloudfoundry-community/toolbelt-boshrelease
Then, add the desired toolbelt-* templates to your releases:
instance_groups:
- name: my-job
jobs:
- { release: toolbelt, name: toolbelt }
- { release: toolbelt, name: toolbelt-quick }
releases:
- name: toolbelt
version: latest
Or if you're looking to use toolbelt as a BOSH add-on via runtime-config:
addons:
- name: toolbelt
jobs:
- name: toolbelt
release: toolbelt
- name: toolbelt-quick
release: toolbelt
releases:
- name: toolbelt
url: https://bosh.io/d/github.com/cloudfoundry-community/toolbelt-boshrelease?v=4.1.0
version: 4.1.0
The toolbelt job sets up all users (present and future) on the
box to source in the appropriate $PATH, and $LD_LIBRARY_PATH
environment variables, as well as a colorized prompt that shows
you which deployment you are on, what job type, and which
instance.
The toolbelt-quick job pulls in a small subset of useful
packages, tuned for a good utility-to-compile-time ratio (hence
the 'quick').
The following toolbelt-* jobs exist:
toolbelt-boss- The Blacksmith CLI, bosstoolbelt-cf- The Cloud Foundry CLI, cf (ships cf7 7.7.12 and cf8 8.8.0;cfsymlinks to cf8)toolbelt-cfdot- This diego tool now ships with the diego bosh release cfdot. cfdot usage documentation.toolbelt-gaol- A CLI for Garden (DEPRECATED: unmaintained since 2018)toolbelt-jq- jq, it's sed for JSON.toolbelt-mysql-client- The MariaDB CLI.toolbelt-nats- A utility for interacting with a NATS messagebus.toolbelt-netsniff-ng- The excellent netsniff-ng suite of networking diagnostics tools. LONG COMPILE TIMEStoolbelt-nload- nload Displays the current network usagetoolbelt-nmap- Network exploration tool and security scanner, nmap.toolbelt-psql- The PostgreSQL CLI (ships psql16 16.13 and psql18 18.3;psqlsymlinks to psql16).toolbelt-redis- The Redis CLI.toolbelt-safe- safe is an alternate client for Vault.toolbelt-screen- screen Screen is a full-screen window manager that multiplexes a physical terminal between several processes.toolbelt-spruce- Spruce is a YAML templating tool.toolbelt-tcptrace- Colorized tcpdump packet captures.toolbelt-tree- Produce tree-based directory listings.toolbelt-tshark- Terminal-mode Wireshark, for analyzing network protocols at a higher level. LONG COMPILE TIMEStoolbelt-vault- The Vault CLI, from Hashicorp.
There are some special meta-packages that provide subsets of the above tools, as groups:
toolbelt-everything- Literally, everything.toolbelt-quick- Just the stuff that compiles quickly (i.e. not netsniff-ng or tshark).
Some packages build from source and take significant time on first deploy (measured on the Jammy stemcell compilation VM):
| Package | Compile Time |
|---|---|
| toolbelt-tshark | ~27 min |
| toolbelt-psql | ~10 min |
| toolbelt-mysql-client | ~5 min |
| toolbelt-nmap | ~5 min |
| toolbelt-netsniff-ng | long |
| toolbelt-quick | seconds |
Packages that install pre-built binaries (jq, safe, spruce, vault, boss, cf, redis, tree, etc.) take only seconds to install. BOSH caches compiled packages, so subsequent deploys reuse the cache unless the package spec changes.
You can create a small, working manifest file from this git repository:
git clone https://github.com/cloudfoundry-community/toolbelt-boshrelease
cd toolbelt-boshrelease
./templates/make_manifest warden
bosh -n deploy
Then, you can bosh ssh and see what it is like using Toolbelt!