334 lines
14 KiB
ReStructuredText
334 lines
14 KiB
ReStructuredText
Glossary
|
|
========
|
|
|
|
Terms in *italics* also appear in this glossary.
|
|
|
|
allocator
|
|
Usually *allocator* means the *block* allocator, i.e. the logic
|
|
inside filesystem which decides where to place newly allocated blocks
|
|
in order to maintain several constraints (like data locality, low
|
|
fragmentation).
|
|
|
|
In btrfs, allocator may also refer to *chunk* allocator, i.e. the
|
|
logic behind placing chunks on devices.
|
|
|
|
balance
|
|
An operation that can be done to a btrfs filesystem, for example
|
|
through :command:`btrfs fi balance /path`. A
|
|
balance passes all data in the filesystem through the *allocator*
|
|
again. It is primarily intended to rebalance the data in the filesystem
|
|
across the *devices* when a device is added or removed. A balance
|
|
will regenerate missing copies for the redundant *RAID* levels, if a
|
|
device has failed. As of Linux kernel 3.3, a balance operation can be
|
|
made selective about which parts of the filesystem are rewritten.
|
|
|
|
barrier
|
|
An instruction to the disk hardware to ensure that everything before
|
|
the barrier is physically written to permanent storage before anything
|
|
after it. Used in btrfs's *copy on write* approach to ensure
|
|
filesystem consistency.
|
|
|
|
block
|
|
A single physically and logically contiguous piece of storage on a
|
|
device, of size e.g. 4K.
|
|
|
|
block group
|
|
The unit of allocation of space in btrfs. A block group is laid out on
|
|
the disk by the btrfs *allocator*, and will consist of one or more
|
|
*chunks*, each stored on a different *device*. The number of chunks
|
|
used in a block group will depend on its *RAID* level.
|
|
|
|
B-tree
|
|
The fundamental storage data structure used in btrfs. Except for the
|
|
*superblocks*, all of btrfs *metadata* is stored in one of several
|
|
B-trees on disk. B-trees store key/item pairs. While the same code is
|
|
used to implement all of the B-trees, there are a few different
|
|
categories of B-tree. The name *btrfs*
|
|
refers to its use of B-trees.
|
|
|
|
btrfsck
|
|
Tool in *btrfs-progs* that checks a filesystem *offline* (i.e.
|
|
unmounted), and reports on any errors in the filesystem structures it
|
|
finds. By default the tool runs in read-only mode as fixing errors is
|
|
potentially dangerous. See also *scrub*.
|
|
|
|
btrfs-progs
|
|
User mode tools to manage btrfs-specific features. Maintained at
|
|
http://github.com/kdave/btrfs-progs.git . The main frontend to btrfs
|
|
features is the standalone tool *btrfs*, although
|
|
other tools such as *mkfs.btrfs* and *btrfstune* are also part of
|
|
btrfs-progs.
|
|
|
|
chunk
|
|
A part of a *block group*. Chunks are either 1 GiB in size (for data)
|
|
or 256 MiB (for *metadata*).
|
|
|
|
chunk tree
|
|
A layer that keeps information about mapping between physical and
|
|
logical block addresses. It's stored within the *system* group.
|
|
|
|
cleaner
|
|
Usually referred to in context of deleted subvolumes. It's a background
|
|
process that removes the actual data once a subvolume has been deleted.
|
|
Cleaning can involve lots of IO and CPU activity depending on the
|
|
fragmentation and amount of shared data with other subvolumes.
|
|
|
|
copy-on-write
|
|
Also known as *COW*. The method that btrfs uses for modifying data.
|
|
Instead of directly overwriting data in place, btrfs takes a copy of
|
|
the data, alters it, and then writes the modified data back to a
|
|
different (free) location on the disk. It then updates the *metadata*
|
|
to reflect the new location of the data. In order to update the
|
|
metadata, the affected metadata blocks are also treated in the same
|
|
way. In COW filesystems, files tend to fragment as they are modified.
|
|
Copy-on-write is also used in the implementation of *snapshots* and
|
|
*reflink copies*. A copy-on-write filesystem is, in theory,
|
|
*always* consistent, provided the underlying hardware supports
|
|
*barriers*.
|
|
|
|
COW
|
|
See *copy-on-write*.
|
|
|
|
default subvolume
|
|
The *subvolume* in a btrfs filesystem which is mounted when mounting
|
|
the filesystem without using the ``subvol=`` mount option.
|
|
|
|
device
|
|
A Linux block device, e.g. a whole disk, partition, LVM logical volume,
|
|
loopback device, or network block device. A btrfs filesystem can reside
|
|
on one or more devices.
|
|
|
|
df
|
|
A standard Unix tool for reporting the amount of space used and free in
|
|
a filesystem. The standard tool does not give accurate results, but the
|
|
*btrfs* command from *btrfs-progs* has
|
|
an implementation of *df* which shows space available in more detail. See
|
|
the
|
|
[[FAQ#Why_does_df_show_incorrect_free_space_for_my_RAID_volume.3F|FAQ]]
|
|
for a more detailed explanation of btrfs free space accounting.
|
|
|
|
DUP
|
|
A form of "*RAID*" which stores two copies of each piece of data on
|
|
the same *device*. This is similar to *RAID-1*, and protects
|
|
against *block*-level errors on the device, but does not provide any
|
|
guarantees if the entire device fails. By default, btrfs uses *DUP*
|
|
profile for metadata on filesystems with one rotational device,
|
|
*single* profile on filesystems with one non-rotational device, and
|
|
*RAID1* profile on filesystems with more than one device.
|
|
|
|
ENOSPC
|
|
Error code returned by the OS to a user program when the filesystem
|
|
cannot allocate enough data to fulfill the user requested. In most
|
|
filesystems, it indicates there is no free space available in the
|
|
filesystem. Due to the additional space requirements from btrfs's
|
|
*COW* behaviour, btrfs can sometimes return ENOSPC when there is
|
|
apparently (in terms of *df*) a large amount of space free. This is
|
|
effectively a bug in btrfs, and (if it is repeatable), using the mount
|
|
option ``enospc_debug`` may give a report
|
|
that will help the btrfs developers. See the
|
|
[[FAQ#if_your_device_is_large_.28.3E16GiB.29|FAQ entry]] on free space.
|
|
|
|
extent
|
|
Contiguous sequence of bytes on disk that holds file data.
|
|
|
|
A file stored on disk with 3 extents means that it consists of three
|
|
fragments of contiguous bytes. See *filefrag*. A file in one extent
|
|
would mean it is not fragmented.
|
|
|
|
Extent buffer
|
|
An abstraction to allow access to *B-tree* blocks larger than a page size.
|
|
|
|
fallocate
|
|
Command line tool in util-linux, and a syscall, that reserves space in
|
|
the filesystem for a file, without actually writing any file data to
|
|
the filesystem. First data write will turn the preallocated extents
|
|
into regular ones. See :manref:`fallocate(1)` and :manref:`fallocate(2)` manual pages
|
|
for more details.
|
|
|
|
filefrag
|
|
A tool to show the number of extents in a file, and hence the amount of
|
|
fragmentation in the file. It is usually part of the e2fsprogs package
|
|
on most Linux distributions. While initially developed for the ext2
|
|
filesystem, it works on Btrfs as well. It uses the *FIEMAP* ioctl.
|
|
|
|
free space cache
|
|
Btrfs doesn't track free space, it only tracks allocated space. Free
|
|
space is by definition any holes in the allocated space, but finding
|
|
these holes is actually fairly I/O intensive. The free space cache
|
|
stores a condensed representation of what is free. It is updated on
|
|
every *transaction* commit.
|
|
|
|
fsync
|
|
On Unix and Unix-like operating systems (of which Linux is the latter),
|
|
the :manref:`fsync(2)` system call causes all buffered file
|
|
descriptor related data changes to be flushed to the underlying block
|
|
device. When a file is modified on a modern operating system the
|
|
changes are generally not written to the disk immediately but rather
|
|
those changes are buffered in memory for reasons of performance,
|
|
calling :manref:`fsync(2)` causes any in-memory changes to be written
|
|
to disk.
|
|
|
|
generation
|
|
An internal counter which updates for each *transaction*. When a
|
|
*metadata* block is written (using *copy on write*), current
|
|
generation is stored in the block, so that blocks which are too new
|
|
(and hence possibly inconsistent) can be identified.
|
|
|
|
key
|
|
A fixed sized tuple used to identify and sort items in a *B-tree*.
|
|
The key is broken up into 3 parts: *objectid*, *type*, and
|
|
*offset*. The *type* field indicates how each of the other two
|
|
fields should be used, and what to expect to find in the item.
|
|
|
|
item
|
|
A variable sized structure stored in B-tree leaves. Items hold
|
|
different types of data depending on key type.
|
|
|
|
log tree
|
|
A b-tree that temporarily tracks ongoing metadata updates until a full
|
|
transaction commit is done. It's a performance optimization of
|
|
``fsync``. The log tracked in the tree are replayed if the filesystem
|
|
is not unmounted cleanly.
|
|
|
|
metadata
|
|
Data about data. In btrfs, this includes all of the internal data
|
|
structures of the filesystem, including directory structures,
|
|
filenames, file permissions, checksums, and the location of each file's
|
|
*extents*. All btrfs metadata is stored in *B-trees*.
|
|
|
|
mkfs.btrfs
|
|
The tool (from *btrfs-progs*) to create a btrfs filesystem.
|
|
|
|
offline
|
|
A filesystem which is not mounted is offline. Some tools (e.g.
|
|
*btrfsck*) will only work on offline filesystems. Compare *online*.
|
|
|
|
online
|
|
A filesystem which is mounted is online. Most btrfs tools will only
|
|
work on online filesystems. Compare *offline*.
|
|
|
|
orphan
|
|
A file that's still in use (opened by a running process) but all
|
|
directory entries of that file have been removed.
|
|
|
|
RAID
|
|
A class of different methods for writing some additional redundant data
|
|
across multiple *devices* so that if one device fails, the missing
|
|
data can be reconstructed from the remaining ones. See *RAID-0*,
|
|
*RAID-1*, *RAID-5*, *RAID-6*, *RAID-10*, *DUP* and
|
|
*single*. Traditional RAID methods operate across multiple devices of
|
|
equal size, whereas btrfs's RAID implementation works inside *block
|
|
groups*.
|
|
|
|
RAID-0
|
|
A form of *RAID* which provides no form of error recovery, but
|
|
stripes a single copy of data across multiple devices for performance
|
|
purposes. The stripe size is fixed to 64KB for now.
|
|
|
|
RAID-1
|
|
A form of *RAID* which stores two complete copies of each piece of
|
|
data. Each copy is stored on a different *device*. btrfs requires a
|
|
minimum of two devices to use RAID-1. This is the default for btrfs's
|
|
*metadata* on more than one device.
|
|
|
|
RAID-5
|
|
A form of *RAID* which stripes a single copy of data across multiple
|
|
*devices*, including one device's worth of additional parity data.
|
|
Can be used to recover from a single device failure.
|
|
|
|
RAID-6
|
|
A form of *RAID* which stripes a single copy of data across multiple
|
|
*devices*, including two device's worth of additional parity data. Can
|
|
be used to recover from the failure of two devices.
|
|
|
|
RAID-10
|
|
A form of *RAID* which stores two complete copies of each piece of
|
|
data, and also stripes each copy across multiple devices for
|
|
performance.
|
|
|
|
reflink
|
|
Parameter to :command:`cp`, allowing it to take advantage of the
|
|
capabilities of *COW*-capable filesystems. Allows for files to be
|
|
copied and modified, with only the modifications taking up additional
|
|
storage space. May be considered as *snapshots* on a single file rather
|
|
than a *subvolume*. Example: :command:`cp --reflink file1 file2`
|
|
|
|
relocation
|
|
The process of moving block groups within the filesystem while
|
|
maintaining full filesystem integrity and consistency. This
|
|
functionality is underlying *balance* and *device* removing features.
|
|
|
|
scrub
|
|
An *online* filesystem checking tool. Reads all the data and metadata
|
|
on the filesystem, and uses *checksums* and the duplicate copies from
|
|
*RAID* storage to identify and repair any corrupt data.
|
|
|
|
seed device
|
|
A readonly device can be used as a filesystem seed or template (e.g. a
|
|
CD-ROM containing an OS image). Read/write devices can be added to
|
|
store modifications (using *copy on write*), changes to the writable
|
|
devices are persistent across reboots. The original device remains
|
|
unchanged and can be removed at any time (after Btrfs has been
|
|
instructed to copy over all missing blocks). Multiple read/write file
|
|
systems can be built from the same seed.
|
|
|
|
single
|
|
A "*RAID*" level in btrfs, storing a single copy of each piece of data.
|
|
The default for data (as opposed to *metadata*) in btrfs. Single is
|
|
also default metadata profile for non-rotational (SSD, flash) devices.
|
|
|
|
snapshot
|
|
A *subvolume* which is a *copy on write* copy of another subvolume. The
|
|
two subvolumes share all of their common (unmodified) data, which means
|
|
that snapshots can be used to keep the historical state of a filesystem
|
|
very cheaply. After the snapshot is made, the original subvolume and
|
|
the snapshot are of equal status: the original does not "own" the
|
|
snapshot, and either one can be deleted without affecting the other
|
|
one.
|
|
|
|
subvolume
|
|
A tree of files and directories inside a btrfs that can be mounted as
|
|
if it were an independent filesystem. A subvolume is created by taking
|
|
a reference on the root of another subvolume. Each btrfs filesystem has
|
|
at least one subvolume, the *top-level subvolume*, which contains
|
|
everything else in the filesystem. Additional subvolumes can be created
|
|
and deleted with the *btrfs<* tool. All subvolumes share the same pool
|
|
of free space in the filesystem. See also *default subvolume*.
|
|
|
|
superblock
|
|
The *block* on the disk, at a fixed known location and of fixed size,
|
|
which contains pointers to the disk blocks containing all the other
|
|
filesystem *metadata* structures. btrfs stores multiple copies of the
|
|
superblock on each *device* in the filesystem at offsets 64 KiB, 64
|
|
MiB, 256 GiB, 1 TiB and PiB.
|
|
|
|
system array
|
|
Cryptic name of *superblock* metadata describing how to assemble a
|
|
filesystem from multiple device. Prior to mount, the command *btrfs dev
|
|
scan* has to be called, or all the devices have to be specified via
|
|
mount option *device=/dev/ice*.
|
|
|
|
top-level subvolume
|
|
The *subvolume* at the very top of the filesystem. This is the only
|
|
subvolume present in a newly-created btrfs filesystem, and internally has ID 5,
|
|
otherwise could be referenced as 0 (e.g. within the *set-default* subcommand of
|
|
*btrfs*).
|
|
|
|
transaction
|
|
A consistent set of changes. To avoid generating very large amounts of
|
|
disk activity, btrfs caches changes in RAM for up to 30 seconds
|
|
(sometimes more often if the filesystem is running short on space or
|
|
doing a lot of *fsync*s), and then writes (commits) these changes out
|
|
to disk in one go (using *copy on write* behaviour). This period of
|
|
caching is called a transaction. Only one transaction is active on the
|
|
filesystem at any one time.
|
|
|
|
transid
|
|
An alternative term for *generation*.
|
|
|
|
writeback
|
|
*Writeback* in the context of the Linux kernel can be defined as the
|
|
process of writing "dirty" memory from the page cache to the disk,
|
|
when certain conditions are met (timeout, number of dirty pages over a
|
|
ratio).
|