Package Cleanup

The chef-automate package-cleanup command helps maintain your Chef Automate installation by identifying and removing unused Habitat packages. Over time, as Chef Automate is upgraded and services are updated, old package versions accumulate on the system, consuming valuable disk space. This command provides a safe, automated way to reclaim that space while protecting essential packages and active services.

Overview

The package cleanup process works through several stages to ensure system safety:

Discovery: Identifies all Habitat packages currently installed on the system
Protection: Builds a whitelist of essential packages, including:
- All currently running services
- Dependencies of running services
- Core Habitat components (hab, hab-sup, hab-launcher)
- The Chef Automate CLI itself
Analysis: Compares installed packages against the whitelist to identify candidates for removal
Cleanup: Removes unused packages using hab pkg uninstall

When to Use Package Cleanup

Consider running package cleanup in these scenarios:

After upgrading Chef Automate to a new version
When disk space is running low on your Chef Automate server
As part of regular system maintenance (monthly or quarterly)
Before creating system backups to reduce backup size
After testing new features that required additional packages

Prerequisites

Root or sudo access to the Chef Automate system
Chef Automate must be running
Sufficient disk I/O capacity for the cleanup operation
Recommended: Take a system backup before cleanup

Basic Usage

Preview Mode (Recommended First Step)

Always start with a dry-run to see what packages would be deleted:

sudo chef-automate package-cleanup --dry-run

This command will output:

Number of currently running services
Total number of packages installed
Number of packages in the whitelist (protected)
Number of unused packages that would be deleted
Estimated space to be reclaimed

CASE 1: Dry-Run - System with unused packages

🔍 Chef Automate Package Cleanup
  Analyzing installed Habitat packages...


  ✓ Found 45 running service(s)

  ✓ Total installed packages: 2847


  ✓ Whitelist contains 1247 protected package(s)

  ✓ Found 1600 unused package(s) to delete

DRY-RUN MODE

  Would delete 1600 package(s)
  Estimated space to be saved: ~80000 MB


✓ Dry-run completed - run without --dry-run to delete packages

Actual Cleanup

Once you’ve reviewed the dry-run output and are satisfied with the results, run the actual cleanup:

sudo chef-automate package-cleanup

The command will:

Display analysis of running services and installed packages
Delete unused packages
Report completion with statistics

CASE 2: Actual Cleanup - Successfully deleted packages

🔍 Chef Automate Package Cleanup
  Analyzing installed Habitat packages...


  ✓ Found 45 running service(s)

  ✓ Total installed packages: 2847


  ✓ Whitelist contains 1247 protected package(s)

  ✓ Found 1600 unused package(s) to delete


📦 Starting cleanup...




✓ Cleanup completed successfully!
  Removed 1600 package(s)
  Estimated space saved: ~80000 MB

CASE 3: Running cleanup when system is already clean

🔍 Chef Automate Package Cleanup
  Analyzing installed Habitat packages...


  ✓ Found 33 running service(s)

  ✓ Total installed packages: 148


  ✓ Whitelist contains 148 protected package(s)

  ✓ Found 0 unused package(s) to delete


📦 Starting cleanup...




✓ Cleanup completed successfully!
  Removed 0 package(s)

Verbose Mode

For detailed progress information, add the --verbose flag to any command.

Dry-Run with Verbose

sudo chef-automate package-cleanup --dry-run --verbose

Verbose mode provides:

Step-by-step execution progress
Complete list of running services and their package identifiers
All packages in the whitelist (protected packages)
Detailed statistical breakdown

CASE 4: Dry-Run with Verbose - System with unused packages

🔍 Chef Automate Package Cleanup
  Analyzing installed Habitat packages...

Step 1: Fetching running Habitat services (hab svc status)...
  ✓ Found 45 running service(s)

Running services:
  • chef/automate-gateway/4.10.20/20231101120000
  • chef/automate-load-balancer/4.10.20/20231101120000
  • chef/compliance-service/4.10.20/20231101120000
  ... (42 more services)

Step 2: Building whitelist (services + dependencies + essential)...
Step 3: Fetching all installed packages (hab pkg list --all)...
  ✓ Total installed packages: 2847


  ✓ Whitelist contains 1247 protected package(s)

Whitelisted packages:
  • chef/automate-gateway/4.10.20/20231101120000
  • core/glibc/2.27/20200612213729
  • core/hab/1.6.0/20200612213729
  ... (1244 more packages)

  ✓ Found 1600 unused package(s) to delete

DRY-RUN MODE

  Total installed packages:    2847
  Running services:            45
  Whitelist protected:         1247
  Unused candidates found:     1600
  → 1600 unused package(s) would be deleted
  Estimated space to be saved: ~80000 MB


✓ Dry-run completed - run without --dry-run to delete packages

CASE 5: Dry-Run with Verbose - System already clean

🔍 Chef Automate Package Cleanup
  Analyzing installed Habitat packages...

Step 1: Fetching running Habitat services (hab svc status)...
  ✓ Found 33 running service(s)

Running services:
  • chef/automate-gateway/4.10.20/20231101120000
  • core/postgresql13/13.8/20220913145821
  ... (31 more services)

Step 2: Building whitelist (services + dependencies + essential)...
Step 3: Fetching all installed packages (hab pkg list --all)...
  ✓ Total installed packages: 148


  ✓ Whitelist contains 148 protected package(s)

Whitelisted packages:
  • chef/automate-gateway/4.10.20/20231101120000
  • core/glibc/2.27/20200612213729
  ... (146 more packages)

  ✓ Found 0 unused package(s) to delete

DRY-RUN MODE

  Total installed packages:    148
  Running services:            33
  Whitelist protected:         148
  Unused candidates found:     0


✓ Dry-run completed - run without --dry-run to delete packages

Actual Cleanup with Verbose

sudo chef-automate package-cleanup --verbose

Verbose mode during actual cleanup shows:

Step-by-step execution progress
List of running services with identifiers
Complete whitelist contents
Multi-pass statistics (pass number, packages to delete per pass)
Final summary with total passes and packages removed

CASE 6: Actual Cleanup with Verbose - Multi-pass deletion

🔍 Chef Automate Package Cleanup
  Analyzing installed Habitat packages...

Step 1: Fetching running Habitat services (hab svc status)...
  ✓ Found 45 running service(s)

Running services:
  • chef/automate-gateway/4.10.20/20231101120000
  • chef/automate-load-balancer/4.10.20/20231101120000
  ... (43 more services)

Step 2: Building whitelist (services + dependencies + essential)...
Step 3: Fetching all installed packages (hab pkg list --all)...
  ✓ Total installed packages: 2847


  ✓ Whitelist contains 1247 protected package(s)

Whitelisted packages:
  • chef/automate-gateway/4.10.20/20231101120000
  • core/glibc/2.27/20200612213729
  ... (1245 more packages)

  ✓ Found 1600 unused package(s) to delete


📦 Starting automated cleanup process...
  The cleanup will run in multiple passes until all unused packages are removed.


📦 Starting cleanup...

=== Cleanup Pass #1 ===
Rebuilding whitelist...
Current installed: 2847 packages
Whitelist size: 1247 packages
To delete in this pass: 1345 packages
  Attempting to delete 1345 candidate(s)...

Packages to delete in this pass:
  • chef/automate-gateway/4.9.0/20230101120000
  • chef/automate-load-balancer/4.9.0/20230101120000
  ... (1343 more packages)

[Per-package deletion progress...]

=== Cleanup Pass #2 ===
Rebuilding whitelist...
Current installed: 1502 packages
Whitelist size: 1247 packages
To delete in this pass: 255 packages
  Attempting to delete 255 candidate(s)...

Packages to delete in this pass:
  • core/old-dep/1.0.0/20200101000000
  ... (254 more packages)

[Per-package deletion progress...]

  ✓ Cleanup complete after 2 pass(es)!

✓ Cleanup completed successfully!
  Removed 1600 package(s)
  Estimated space saved: ~80000 MB

Understanding which packages are being removed in each pass
Auditing the cleanup process for compliance
Debugging whitelist protection logic

Command Options

Flag	Shorthand	Description	Default
`--dry-run`		Show which packages would be deleted without actually deleting them. Displays package count and estimated space savings.	`false`
`--verbose`	`-v`	Enable detailed progress output showing running services, whitelist contents, per-package deletion status, and multi-pass statistics.	`false`
`--debug`	`-d`	Enable debug output (shows chef-automate version and build info).	`false`
`--help`	`-h`	Display command help and usage information.	-

Using Verbose Mode

For detailed progress tracking and transparency:

sudo chef-automate package-cleanup --verbose

Verbose mode provides:

Step-by-step execution stages
Complete list of running services with package identifiers
All whitelisted/protected packages
Per-package deletion progress
Pass-by-pass cleanup statistics
Detailed final summary

Protected Packages

The following package categories are automatically protected from deletion:

1. Running Services

All packages currently running as Habitat services are protected. To see your running services:

sudo hab svc status

2. Essential Habitat Packages

Core Habitat components required for system operation:

*/hab/*/* - Habitat binary
*/hab-sup/*/* - Habitat Supervisor
*/hab-launcher/*/* - Habitat Launcher

3. Chef Automate CLI

The CLI tool itself is protected using wildcard pattern:

*/automate-cli/*/* - All versions of the CLI from any origin

4. Service Dependencies

All packages that are dependencies of running services, including transitive dependencies.

Understanding the Whitelist

The whitelist is built dynamically each time you run the command:

Query Running Services: Uses hab svc status to find all active services
Resolve Dependencies: For each running service, queries its dependency tree using hab pkg dependencies --transitive
Add Essentials: Includes core Habitat packages and the CLI using wildcard patterns
Build Protection Set: Creates a comprehensive list of packages that must not be deleted

Multi-Pass Cleanup Process

The package cleanup uses an iterative multi-pass approach to handle complex dependency chains safely:

Why Multi-Pass?

When packages are deleted, their dependencies may become unused. A single-pass cleanup might miss these newly orphaned packages. The multi-pass approach ensures complete cleanup:

Pass 1: Removes the first batch of unused packages
Whitelist Rebuild: Recalculates running services and dependencies
Pass 2: Identifies newly unused packages (former dependencies of deleted packages)
Iteration: Continues until no more unused packages are found

Algorithm

WHILE unused packages exist:
  1. Get current running services (hab svc status)
  2. Build whitelist: services + dependencies + essential packages
  3. Get all installed packages (hab pkg list --all)
  4. Identify packages NOT in whitelist
  5. IF no unused packages found THEN exit (cleanup complete)
  6. Delete batch of unused packages
  7. Track successes and failures
  8. Increment pass counter
END WHILE

Example Multi-Pass Scenario

Initial State: 2847 packages installed

Pass 1:

Running services: 45
Whitelist: 1247 protected packages
To delete: 1345 packages
After deletion: 1502 packages remain

Pass 2:

Whitelist rebuilds with current state
Some dependencies of deleted packages are now unused
To delete: 255 newly identified unused packages
After deletion: 1247 packages remain (only protected packages)

Completion: No more unused packages found after 2 passes

Best Practices

1. Always Use Dry-Run First

# Preview before cleanup
sudo chef-automate package-cleanup --dry-run

# Review output carefully, then proceed
sudo chef-automate package-cleanup

2. Schedule Regular Cleanups

Add to your maintenance schedule:

# Monthly cleanup (in cron)
0 2 1 * * /bin/chef-automate package-cleanup

3. Monitor Disk Space

Check disk space before and after:

# Before
df -h /hab/pkgs

# Run cleanup
sudo chef-automate package-cleanup

# After
df -h /hab/pkgs

4. Combine with Service Management

Stop unnecessary services before cleanup to maximize space reclamation:

# Stop old services no longer needed
sudo hab svc unload chef/old-service

# Then run cleanup
sudo chef-automate package-cleanup

5. Backup Before Major Cleanups

Always maintain a backup:

# Create backup before cleanup
sudo chef-automate backup create

# Then proceed with cleanup
sudo chef-automate package-cleanup

Troubleshooting

Package Deletion Failures

If some packages fail to delete:

Check if Package is in Use:
```
sudo hab svc status
```
Verify Package Exists:
```
sudo hab pkg list <origin>/<name>
```
Check File Locks:
```
sudo lsof | grep hab/pkgs
```

Review Verbose Output:

sudo chef-automate package-cleanup --verbose

Permission Errors

If you encounter permission errors:

# Ensure you're running as root
sudo -i
chef-automate package-cleanup

Habitat Service Errors

If hab svc status fails:

# Check Habitat supervisor status
sudo systemctl status hab-sup

# Restart if needed
sudo systemctl restart hab-sup

Disk Space Not Reclaimed

If disk space doesn’t free up as expected:

Verify Deletions:

# Count packages before
sudo hab pkg list --all | wc -l

# Run cleanup
sudo chef-automate package-cleanup

# Count packages after
sudo hab pkg list --all | wc -l

Check for Other Space Issues:

# Find large directories
sudo du -sh /hab/* | sort -h

Consider Log Files:

# Check log directory size
sudo du -sh /hab/svc/*/logs

Safety Mechanisms

The package cleanup command includes multiple safety mechanisms:

Whitelist Protection: Essential packages are never deleted
Dependency Awareness: Habitat respects package dependencies during uninstall
Dry-Run Mode: Preview changes before applying them
Individual Package Handling: Failed deletions don’t stop the entire process
Detailed Logging: All actions are logged for audit purposes

Performance Considerations

Cleanup time scales with the number of packages to delete
Typical cleanup takes 2-5 minutes for 50-100 packages
Large cleanups (500+ packages) may take 15-30 minutes
Disk I/O is the primary performance factor
No impact on running services during cleanup

Disk Space Reclamation

Typical space savings vary by installation and upgrade history:

Small Installation (few upgrades): 500 MB - 1 GB
Medium Installation (multiple upgrades): 1 GB - 3 GB
Large Installation (many upgrades, long-running): 3 GB - 10+ GB

Packages are stored in /hab/pkgs, with each package consuming:

Small packages (binaries): 10-50 MB
Medium packages (services): 50-200 MB
Large packages (runtimes): 200 MB - 1 GB

chef-automate service-versions - Check versions of running services
chef-automate status - View system status
chef-automate upgrade run - Upgrade Chef Automate
hab pkg list --all - List all installed Habitat packages
hab svc status - Check Habitat service status
hab pkg uninstall - Manually uninstall specific packages

Additional Resources

Support

If you encounter issues with package cleanup:

Review the troubleshooting section above
Check the Chef Automate documentation
Contact Chef Support
Visit the Chef Community Forum