Learn Bacula - Troubleshooting & Debug

#Introduction

In episode 15 we built a large system. And large systems will fall — the question isn't "if", but "how fast you find the root cause". In episode 16 we sharpen our troubleshooting skills: reading logs, running debug, recognizing common failure patterns, and most importantly — recovering from catalog failure. Good troubleshooting isn't memorizing errors; it's mastering the tools and the diagnostic sequence.

#Diagnostic Tools

#Debug Mode

Every Bacula daemon has a -d option with levels from 0-200+. The higher the level, the more detail:

sudo bacula-dir -d 100

This command runs the Director in the foreground with full debug — including connection details, authentication, and job decisions. Common levels:

• -d 0 — normal.
• -d 20 — job and connection details.
• -d 100 — very detailed; prepare for large output.
• -d 200 — a flood of bytes; only for extreme cases.

bacula-sd -d 100 and bacula-fd -d 100 are also available. Don't run debug in production during working hours without log capture — the output can fill a terminal fast.

#Logs in /var/log/bacula/

The first routine when something goes wrong is reading the log per the Messages resource:

sudo tail -50 /var/log/bacula/bacula.log
sudo grep -iE "error|fatal|warning" /var/log/bacula/bacula.log | tail -30

For job-specific issues, use bconsole:

* messages jobid=42

#status via bconsole

* status dir
* status sd
* status client=web-01-fd
* list volumes
* list jobs

The recommended diagnostic sequence: Director status → Storage status → Client status → list volumes. Usually one of these four immediately reveals where the problem is.

#Common Cases and Their Solutions

#1. Failed Authentication (Authorization problem)

bacula-dir: Authorization problem with: client "web-01-fd"

The most common cause: the password between the Client resource (in dir) and the Director resource (in fd) doesn't match, or a resource name is wrong. Check:

grep -A3 'Client {' /etc/bacula/bacula-dir.conf
grep -A3 'Director {' /etc/bacula/bacula-fd.conf

#2. Tape Full / No Volume Available

Device "TapeDrive" is not able to find a Volume to write to.

Cause: all volumes in the pool are full or still under retention. Solutions: add volumes, expand the pool, or trim retention (carefully):

* list volumes pool=TapePool
* label pool=TapePool

#3. Catalog Lock

sqlite3_backup: database table is locked

For SQLite, this happens when multiple processes access the database at the same time — make sure only one Director is running and reduce the concurrent jobs that touch the catalog (episode 20). For PostgreSQL/MySQL, locks are rarer; check for hanging transactions:

SELECT pid, state, wait_event FROM pg_stat_activity WHERE state <> 'idle';

#4. Daemon Won't Start

sudo bacula-dir -t
sudo bacula-sd -t
sudo bacula-fd -t
journalctl -u bacula-director --no-pager | tail

Config validation + systemd logs always reveal the cause — usually an unbalanced brace or a referenced resource that doesn't exist yet.

#Catalog Recovery

#Scenario

The catalog is lost (disk failure, database deleted) — but the catalog backup (episode 9) is available. This is when that investment pays back.

#Recovery Steps

1. Reinstall/prepare a new database with an empty schema:

sudo -u postgres createdb bacula_new
sudo -u postgres psql -f /usr/share/bacula-director/create_postgresql_database bacula_new

2. Restore the catalog backup into the new database. If the catalog backup is a pg_dump, simply:

sudo -u postgres psql -d bacula_new -f /tmp/catalog-restore.sql

3. Point the Director at the new catalog via the Catalog resource, validate, and restart.

4. Verify: list jobs, list volumes must show the history before the disaster. If the only catalog backup is in the form of a Bacula volume (not pg_dump), first restore that volume to a temporary location using bconsole, then import the dump.

#Restore from Tape

When the needed media is on tape, restore involves the changer:

* restore
... choose JobId ...
... Bacula asks for the correct tape to be mounted ...

Bacula will look up which volume holds the job in the catalog, request the tape from the changer (AutomaticMount = yes makes this easier), scan it, then copy the data. If the tape is on a shelf (not in the changer), an operator must insert it — this is why tidy tape rotation and physical labeling (episode 11) are so valuable in a crisis.

#Closing

Key takeaways:

• -d 100 gives connection/job details; start low and go up.
• Logs live in /var/log/bacula/; messages jobid=N targets a specific job.
• Diagnostic sequence: status dir → sd → client → volumes.
• Common cases: auth mismatch (password/name), volumes exhausted, catalog lock, invalid config.
• Catalog recovery needs a catalog backup; without it, bscan is the last resort.

In the next episode, episode 17, we'll examine Bacula 15.0.x and its latest features — the 15.0.4 release (23 May 2026) with bug fixes and improvements, the 15.0.0 leap in unified catalog and big performance, the 13.x and 11.x series history, and the Community versus Enterprise feature matrix. This is the version map you need to understand for upgrade decisions.