Below is a practical guide to Bareos, compiled as a working cheat sheet: based on the current official Bareos documentation (the main docs branch is now bareos-25) and on those questions that have already come up in past discussions: the roles of bareos-dir / bareos-sd / bareos-fd, meaning Devices / Pools / Volumes, work through bconsole, WebUI and typical causes of failures.
Bareos Directory
0. How Bareos works in a nutshell
Bareos consists of several key components. Bareos Director is a central management service: it knows Jobs, Schedules, Clients, Pools, Catalog and runs backup/restore. Bareos Storage Daemon (bareos-sd) writes data to media or file storage. Bareos File Daemon (bareos-fd) is placed on the client and sends the files to the director/storage. bconsole - text console for communicating with Director. Catalog is a database of metadata about jobs, files, clients, and volumes; The backup data itself is not in the Catalog.
In practice, this means this: dir decides what, when and where to backup; fd reads files on the client; sd stores the backup stream on disk, tape or another backend. When restore runs, Director finds the required Job/Volume in the Catalog, sd reads the data from the media, and fd returns it to the client.
1. Bareos folder and file structure
1.1. Main configuration directory
On Unix/Linux, the typical configuration path is /etc/bareos/. Each component has either a single .conf or a subdirectory scheme *.d. By default it looks like this:
/etc/bareos/
├── bareos-dir.conf
├── bareos-dir.d/
├── bareos-sd.conf
├── bareos-sd.d/
├── bareos-fd.conf
├── bareos-fd.d/
├── bconsole.conf
├── bconsole.d/
├── tray-monitor.conf
└── tray-monitor.d/This is exactly the scheme Bareos documents as standard for Unix. When launched, the component reads either COMPONENT.conf or COMPONENT.d/*/*.conf if a subdirectory scheme is used. You can also explicitly set the configuration path via -c PATH.
1.2. How to read the *.d structure
In a subdirectory scheme there is a simple rule: the resource path has the form:
COMPONENT.d/RESOURCETYPE/RESOURCENAME.confExamples from the documentation:
bareos-dir.d/director/bareos-dir.conf
bareos-dir.d/pool/Full.confThis is very useful for practice: if you are editing a Job, look for the file in bareos-dir.d/job/; if Pool - in bareos-dir.d/pool/; if the Storage Daemon device is in bareos-sd.d/device/.
1.3. What is where on Director
On Director you usually find the following directories:
/etc/bareos/bareos-dir.d/
├── catalog/ # Catalog resources, например MyCatalog.conf
├── client/ # Клиенты Bareos
├── console/ # Консоли и WebUI users
├── director/ # Глобальный Director resource
├── fileset/ # Что бэкапить
├── job/ # Конкретные Jobs
├── jobdefs/ # Шаблоны JobDefs
├── messages/ # Куда слать сообщения
├── pool/ # Пулы томов
├── profile/ # ACL/Profiles, в т.ч. для WebUI
├── schedule/ # Расписания
├── storage/ # Связь с Storage Daemon
└── ... # другие ресурсыThis structure follows directly from the RESOURCETYPE/RESOURCENAME.conf rule. Therefore, files like /etc/bareos/bareos-dir.d/catalog/MyCatalog.conf or /etc/bareos/bareos-dir.d/profile/webui-admin.conf are not “package magic”, but a normal Bareos resource model.
1.4. What lies where on the client
A client running File Daemon typically has:
/etc/bareos/bareos-fd.d/
├── client/myself.conf
├── director/bareos-dir.conf
├── director/bareos-mon.conf
└── messages/Standard.conf
client/myself.conf describes the local File Daemon itself, director/*.conf defines which Directors can connect to it, and messages/Standard.conf defines where messages go. This is exactly how it is shown in the official tutorial.
1.5. What’s where on Storage Daemon
On a storage server the following are usually important:
/etc/bareos/bareos-sd.d/
├── director/ # Which Directors have access to SD
├── device/ # Physical/logical storage devices
├── storage/ # Global SD configuration
├── messages/
└── autochanger/ # If tape libraries are used
Device is the key entity for the store. The documentation explicitly describes Device Resource as a resource that specifies the details of a device that the Storage Daemon can use; for file storage Archive Device is a directory, for tape it is a device like /dev/nst0.
1.6. Where are the backup files located?
In the default disk configuration, Bareos writes volumes to /var/lib/bareos/storage/; this is the path from tutorial/default FileStorage. For file storage, the file name is usually the same as the Volume name from the Catalog. This is a standard default, and not a required path: the real directory is set in Archive Device of your Device resource.
1.7. What’s changed in Bareos 25
As of Bareos 25, batch configuration templates are stored in /usr/lib/bareos/defaultconfigs/ and production configuration is deployed in /etc/bareos/. An important point for administration: when upgrading, Bareos no longer modifies existing configs automatically. This is good for the security of changes, but bad if the administrator expects that “the package itself will add the new required resource.”
1.8. WebUI files
For WebUI, key configs are located in /etc/bareos-webui/. The main ones:
/etc/bareos-webui/directors.ini
/etc/bareos-webui/configuration.inidirectors.ini describes which Director to connect to and on which port, as well as TLS parameters. The Apache config for WebUI usually puts the package in one of the standard paths like /etc/apache2/conf.d/bareos-webui.conf or a similar distro-specific option.
2. Bareos console commands
2.1. Service management
To start daemons, the documentation shows the following commands:
systemctl start bareos-dir bareos-sd bareos-fd
systemctl enable --now bareos-dir bareos-sd bareos-fdOn Debian/Ubuntu, systemd-unit names can be packaged:
systemctl start bareos-director bareos-storage bareos-filedaemon
systemctl enable --now bareos-director bareos-storage bareos-filedaemonThis is useful to remember: in Bareos commands, logs and unit names, sometimes the name of the binary appears, and sometimes the name of the package.
2.2. Checking the configuration before restarting
The most useful admin habit is to test the syntax before restart:
bareos-dir -t
bareos-sd -t
bareos-fd -tThe -t, --test-config option causes the daemon to read the config, print errors and exit immediately. This is the official way to syntax check new configs.
Other general daemon options that are useful are:
bareos-dir -c /etc/bareos
bareos-dir -xc
bareos-dir -v
bareos-dir -d 100-c sets an alternative config path, -xc prints the current configuration, -v makes the output more detailed, -d increases the debug-level. bareos-sd, bareos-fd and bconsole have the same family of options.
2.3. Running bconsole
The main console starts like this:
bconsoleCommonly used options:
bconsole -l # показать доступных directors
bconsole -D <director> # выбрать director
bconsole -c /etc/bareos # указать путь конфигурации
bconsole -d 100 # debug levelbconsole communicates specifically with Director; it reads the configuration from bconsole.conf, unless -c is specified.
2.4. Commands you need almost every day
Checking status
status dir
status client
status storage
status jobid=<ID>
statusstatus dir shows scheduled and current Jobs, status client - whether the File Daemon is responding, status storage - the status of the Storage Daemon, devices and drive reservation queue, status jobid=<ID> - the current status of a specific job. This is the basis for primary diagnosis.
View directory and media
show filesets
list jobs
list jobid=<ID>
list jobtotals
list files jobid=<ID>
list jobmedia
list pools
list volumesshow filesets helps you quickly understand which FileSets exist. list jobs / list files jobid=... are needed to analyze the history and contents of the backup. list pools and list volumes - for working with media and pools.
Starting and waiting for tasks
run
wait
wait jobid=<ID>
messages
autodisplay onrun starts the job, wait waits for completion, messages displays messages, and autodisplay on is convenient to enable during diagnostics so that messages are displayed immediately.
Restore
restore allNext, Bareos will guide you through the selection of JobId, FileSet, recovery client, directory and path Where. The tutorial shows that restore by default collects a tree of files and allows you to select files interactively.
Shutdown
quitNormal session termination is bconsole.
2.5. Commands for tapes and volumes
Partitioning a volume and adding it to the Pool
label
add pool=<POOL> storage=<STORAGE>
The practical difference is this: label works with physical media/volume and simultaneously creates an entry about it in Catalog; add adds Volume only to the Catalog and does not write a physical token to the media. In ordinary life, you almost always need label; add is a more special case.
Installation and updating of slots
mount
unmount
update slots
update slots scan
For autochanger, update slots synchronizes Catalog with library slots. If there is no barcode reader, update slots scan causes Bareos to read volume labels one by one and update Slot/InChanger.
Cancel a “stuck” job on SD
cancel storage=<StorageName> Jobid=<ID>
This form is useful when the Director no longer “sees” the job as active, but the Storage Daemon still thinks it is running and blocks the queue. This is one of the most practical commands for frozen backup/restore.
2.6. Commands for changing configuration on the fly
reload
configure add client name=client2-fd address=192.168.0.2 password=secret
configure add console name=admin password=secret profile=webui-admin tlsenable=false
configure add creates a full-fledged resource and saves it in bareos-dir.d/<resourcetype>/<name>.conf, that is, the change survives reload/restart. This is very convenient for adding a client and WebUI console. After manually editing files, do reload or restart.
2.7. Advanced utilities
When bconsole is no longer enough, the following tools are useful:
bls # посмотреть содержимое volume
bextract # вытащить файлы напрямую из volume
bscan # импортировать содержимое volume в catalog / восстановить каталог
btape # тесты ленточного устройства
bls can read both file volumes and tape volumes; bextract can help with emergency file retrieval; bscan is used to re-enroll the volume in the Catalog; btape is a test tool for tape. This is already the “emergency suitcase” of the Bareos administrator.
3. Bareos web interface
3.1. What WebUI can do
Bareos WebUI supports viewing detailed information on Jobs, Clients, Filesets, Pools, Volumes, Storages, Schedules, Logs and Director messages; allows you to start, cancel, restart backup jobs and do restore through the file tree; also knows how to manage tape autochanger, including label/import/export media and updating slot state. To restore, WebUI can work either with one backup job, or combine the history of backup jobs and client filesets into a single file tree. This is convenient if the client has a lot of Full/Incremental/Differential and needs to restore the “latest current version” of files.
3.2. How to understand interface sections
The names of the tabs may vary slightly by version, but the logic is usually like this:
- Jobs — history backup/restore/verify, launch, rerun, cancel.
- Clients — registered clients
bareos-fd. - Storages — connected Storage Daemon and associated devices/volumes.
- Pools — logical groups of volumes.
- Volumes — specific volumes to which backup jobs are written.
- Schedules / Filesets / Director messages / Logs - auxiliary administrative sections.
To explain it in very simple terms:
- Device - “where Storage Daemon physically writes”: directory on disk, tape drive, autochanger drive, object storage backend.
- Pool — “a set of volumes for a specific storage policy.”
- Volume — “specific backup media/file”, for example
Full-0001.
That is, the formula is:
Job → Pool → select the appropriate Volume → write through a specific Device/Storage.
For file storage this is especially clear: Device specifies the Archive Device directory, Pool defines the policy for selecting and reusing volumes, and Volume is a specific backup file in this directory.
3.3. Authorization in WebUI
WebUI does not have its own separate user base. It uses Console and Profile resources from Bareos Director itself. To log in, you need at least one Console (Dir) resource; Access rights are set via Profile (Dir), for example webui-admin.
In practice, this means: if the WebUI “logs in, but doesn’t show anything” or some sections are inaccessible, the problem is often not in PHP/Apache, but in the ACL of the Bareos profile. The documentation directly provides examples of CommandACL, Job ACL, Client ACL, Storage ACL and other restrictions for WebUI profiles.
3.4. What is important for installing and running WebUI
Bareos WebUI may not be on the same host as Director, but the major version of WebUI and Director must match. For modern installations, the WebUI package is designed for PHP-FPM; As of Bareos 22, WebUI requires php-fpm rather than Apache mod_php. After installing/upgrading, Apache needs to be restarted, and if there are problems with accessibility, you need to check php-fpm, fcgid, rewrite, SELinux/AppArmor and the directors.ini config.
3.5. Why is there sometimes no progress/graphs?
Statistics for displaying the status of running jobs in WebUI are taken from Catalog. If Statistics Collection is disabled, beautiful telemetry may not be available. The documentation specifically warns: collecting statistics increases the size of the database.
4. What helps solve problems in Bareos
4.1. Basic diagnostic algorithm
If Bareos isn’t working, it’s almost always helpful to go in this order:
- Check that
dir,sd,fdare alive. - Check the syntax of the configs.
- Check that names/passwords/ports match between components.
- Check storage/device/volume/pool.
- Check that restore was actually tested, and not just backup.
4.2. The first set of commands for any accident
bareos-dir -t
bareos-sd -t
bareos-fd -t
status dir
status client
status storage
messages
This combination usually already shows 80% of the problems: a syntax error, the client is not responding, storage does not see the device, job is stuck in the queue, volume is in the wrong state.
4.3. Authorization problems
One of the most common reasons is a Name / Password mismatch between Director and File Daemon or between Director and Storage Daemon. The official troubleshooting directly says: if you change the Director name or password, these changes must be mirrored in both SD and FD; both ends authenticate each other. For Storage Daemon, the Director name and password must match the Director config; for File Daemon, the Director password must match the Client resource on the Director side.
In practice, this means: when a client is “visible in the config, but the backup does not start,” first check not the DNS or the firewall, but rather the correspondence of resources and secrets in:
bareos-dir.d/client/*.conf
bareos-fd.d/director/*.conf
bareos-dir.d/storage/*.conf
bareos-sd.d/director/*.conf
bconsole.conf / bconsole.d/*
bconsole is also authenticated in Director through its Director resource.
4.4. Problems with Storage/Device/Volume
If the backup is waiting for the media, we think not about Job, but about the chain Storage → Device → Pool → Volume. A Pool is a set of volumes, Job uses the Pool, Director selects the first suitable appendable/recyclable Volume from the Pool, and the Media Type of the volume must match Storage/Device. If there is no suitable volume, the job will not run.
For disk file storage, it is important to remember: Archive Device must be an existing absolute directory, and Bareos creates volume files there with the name from Catalog. If the directory does not exist, the permissions are incorrect, or you are looking in the wrong Device, then the WebUI will show “everything seems to be there”, but there will be no entry.
4.5. Problems with tapes
The phrase “tape inserted” in normal use literally means the presence of physical media: either the operator manually inserted the cartridge into the tape drive, or the autochanger robot loaded it into the drive. The Console documentation explicitly notes that when working with multiple tapes, Bareos waits for the user to confirm the mount of the new media via Console.
If label fails, typical reasons according to the documentation are as follows: volume name is already in the Catalog; another media is already mounted in the device; the media is already labeled Bareos; or there is no volume in the drive at all. For autochanger, after changing magazine or cartridges, unmount is useful, then update slots, then mount.
4.6. Why Storage Daemon “doesn’t respond for a long time” after startup
Once the daemons are started, Storage Daemon tries to open all defined devices and check the mounted Volume. If it’s a tape drive, it can rewind a tape that’s already inserted, and this sometimes takes minutes. While the device check is not completed, the SD may not accept connections from the Console. This is normal behavior and not necessarily freezing.
4.7. Problems after update
There are two particularly important rules:
Bareos DirectorandBareos Storage Daemonmust be the same version.Bareos File Daemonmay differ by version.- For WebUI and Director major versions must match.
Plus, with Bareos 25, the package no longer “adds” your existing configs to the upgrade. Therefore, after updating, you need to separately check not only the versions, but also whether you are expecting a new resource in /etc/bareos/, which in fact remains only in the /usr/lib/bareos/defaultconfigs/ templates.
4.8. WebUI Issues
If WebUI does not open or does not log in, look first:
- major version Director/WebUI,
php-fpm,- Apache restart,
directors.ini,- SELinux/AppArmor,
- presence of
Consoleand a suitableProfile, - Profile ACL.
A very common scenario: WebUI opens, but the list of clients/jobs is empty or truncated. This is usually not a “broken WebUI”, but an overly limited Profile on the console through which the WebUI logs into Director.
4.9. Restore check is required
The official tutorial specifically emphasizes: it is not enough just to have a successful backup job; you need to test file recovery before an accident occurs. In Bareos restore is not a minor function, but an obligatory part of checking the functionality of the backup scheme.
5. A very short reminder for the administrator
Minimum things to remember
- Edit the config → bareos-*. -t → reload/restart.
- Backup → status dir/client/storage does not work.
- The client is not visible → I check Name/Password/Port/TLS.
- Waiting for the media → look at Storage/Device/Pool/Volume.
- WebUI is empty → I check Console/Profile/ACL.
- After the update → I check the versions of dir/sd and dir/webui.
- Backup without restore test = backup not yet verified.
This is the working minimum for administering Bareos.