Definitions
- Block
-
A block represents the primitive unit of information that the Storage daemon
reads and writes to a physical device. Normally, for a tape device, it will
be the same as a tape block. The Storage daemon always reads and writes
blocks. A block consists of block header information followed by records.
Clients of the Storage daemon (the File daemon) normally never see blocks.
However, some of the Storage tools (bls, bscan, bextract, ...) may be use
block header information. In older Bacula tape versions, a block could
contain records (see record definition below) from multiple jobs. However,
all blocks currently written by Bacula are block level BB02, and a given
block contains records for only a single job. Different jobs simply have
their own private blocks that are intermingled with the other blocks from
other jobs on the Volume (previously the records were intermingled within
the blocks). Having only records from a single job in any give block
permitted moving the VolumeSessionId and VolumeSessionTime (see below) from
each record heading to the Block header. This has two advantages: 1. a block
can be quickly rejected based on the contents of the header without reading
all the records. 2. because there is on the average more than one record per
block, less data is written to the Volume for each job.
- Record
-
A record consists of a Record Header, which is managed by the Storage daemon
and Record Data, which is the data received from the Client. A record is the
primitive unit of information sent to and from the Storage daemon by the
Client (File daemon) programs. The details are described below.
- JobId
-
A number assigned by the Director daemon for a particular job. This number
will be unique for that particular Director (Catalog). The daemons use this
number to keep track of individual jobs. Within the Storage daemon, the JobId
may not be unique if several Directors are accessing the Storage daemon
simultaneously.
- Session
-
A Session is a concept used in the Storage daemon corresponds one to one to a
Job with the exception that each session is uniquely identified within the
Storage daemon by a unique SessionId/SessionTime pair (see below).
- VolSessionId
-
A unique number assigned by the Storage daemon to a particular session (Job)
it is having with a File daemon. This number by itself is not unique to the
given Volume, but with the VolSessionTime, it is unique.
- VolSessionTime
-
A unique number assigned by the Storage daemon to a particular Storage daemon
execution. It is actually the Unix time_t value of when the Storage daemon
began execution cast to a 32 bit unsigned integer. The combination of the
VolSessionId and the VolSessionTime for a given Storage daemon is
guaranteed to be unique for each Job (or session).
- FileIndex
-
A sequential number beginning at one assigned by the File daemon to the files
within a job that are sent to the Storage daemon for backup. The Storage
daemon ensures that this number is greater than zero and sequential. Note,
the Storage daemon uses negative FileIndexes to flag Session Start and End
Labels as well as End of Volume Labels. Thus, the combination of
VolSessionId, VolSessionTime, and FileIndex uniquely identifies the records
for a single file written to a Volume.
- Stream
-
While writing the information for any particular file to the Volume, there
can be any number of distinct pieces of information about that file, e.g. the
attributes, the file data, ... The Stream indicates what piece of data it
is, and it is an arbitrary number assigned by the File daemon to the parts
(Unix attributes, Win32 attributes, data, compressed data, ...) of a file
that are sent to the Storage daemon. The Storage daemon has no knowledge of
the details of a Stream; it simply represents a numbered stream of bytes. The
data for a given stream may be passed to the Storage daemon in single record,
or in multiple records.
- Block Header
-
A block header consists of a block identification (``BB02''), a block length
in bytes (typically 64,512) a checksum, and sequential block number. Each
block starts with a Block Header and is followed by Records. Current block
headers also contain the VolSessionId and VolSessionTime for the records
written to that block.
- Record Header
-
A record header contains the Volume Session Id, the Volume Session Time, the
FileIndex, the Stream, and the size of the data record which follows. The
Record Header is always immediately followed by a Data Record if the size
given in the Header is greater than zero. Note, for Block headers of level
BB02 (version 1.27 and later), the Record header as written to tape does not
contain the Volume Session Id and the Volume Session Time as these two
fields are stored in the BB02 Block header. The in-memory record header does
have those fields for convenience.
- Data Record
-
A data record consists of a binary stream of bytes and is always preceded by
a Record Header. The details of the meaning of the binary stream of bytes are
unknown to the Storage daemon, but the Client programs (File daemon) defines
and thus knows the details of each record type.
- Volume Label
-
A label placed by the Storage daemon at the beginning of each storage volume.
It contains general information about the volume. It is written in Record
format. The Storage daemon manages Volume Labels, and if the client wants, he
may also read them.
- Begin Session Label
-
The Begin Session Label is a special record placed by the Storage daemon on
the storage medium as the first record of an append session job with a File
daemon. This record is useful for finding the beginning of a particular
session (Job), since no records with the same VolSessionId and VolSessionTime
will precede this record. This record is not normally visible outside of the
Storage daemon. The Begin Session Label is similar to the Volume Label except
that it contains additional information pertaining to the Session.
- End Session Label
-
The End Session Label is a special record placed by the Storage daemon on the
storage medium as the last record of an append session job with a File
daemon. The End Session Record is distinguished by a FileIndex with a value
of minus two (-2). This record is useful for detecting the end of a
particular session since no records with the same VolSessionId and
VolSessionTime will follow this record. This record is not normally visible
outside of the Storage daemon. The End Session Label is similar to the Volume
Label except that it contains additional information pertaining to the
Session.
Kern Sibbald
2010-08-30