table of contents
- NAME
- SYNOPSIS
- DESCRIPTION
- Superblock commands
- Mount commands
- Repair commands
- Commands for managing a running filesystem
- Commands for managing devices within a running filesystem
- Commands for managing subvolumes and snapshots
- Commands for managing filesystem data
- Commands for encryption
- Commands for migration
- Commands for operating on files in a bcachefs filesystem
- Commands for debugging
- FUSE commands
- Miscellaneous commands
- EXIT STATUS
BCACHEFS(8) | System Manager's Manual (smm) | BCACHEFS(8) |
NAME¶
bcachefs
— manage
bcachefs filesystems/devices
SYNOPSIS¶
bcachefs |
command [options] [arguments] |
DESCRIPTION¶
The bcachefs
utility supports the
following subcommands, which are documented in detail below:
Superblock commands¶
format
- Format one or a list of devices with bcachefs data structures.
show-super
- Dump superblock information to stdout.
set-option
- Set a filesystem option
Mount commands¶
mount
- Mount a filesystem.
Repair commands¶
fsck
- Check an existing filesystem for errors.
Commands for managing a running filesystem¶
fs usage
- Show disk usage
Commands for managing devices within a running filesystem¶
device add
- Add a new device to an existing filesystem
device remove
- Remove a device from an existing filesystem
device online
- Re-add an existing member to a filesystem
device offline
- Take a device offline, without removing it
device evacuate
- Migrate data off of a specific device
device set-state
- Mark a device as failed
device resize
- Resize filesystem on a device
device resize-journal
- Resize journal on a device
Commands for managing subvolumes and snapshots¶
subvolume create
- Create a new subvolume
subvolume delete
- Delete an existing subvolume
subvolume snapshot
- Create a snapshot
Commands for managing filesystem data¶
data rereplicate
- Rereplicate degraded data
data job
- Kick off low level data jobs
Commands for encryption¶
unlock
- Unlock an encrypted filesystem prior to running/mounting
set-passphrase
- Change passphrase on an existing (unmounted) filesystem
remove-passphrase
- Remove passphrase on an existing (unmounted) filesystem
Commands for migration¶
migrate
- Migrate an existing filesystem to bcachefs, in place
migrate-superblock
- Add default superblock, after bcachefs migrate
Commands for operating on files in a bcachefs filesystem¶
setattr
- Set various per file attributes
Commands for debugging¶
dump
- Dump filesystem metadata to a qcow2 image
list
- List filesystem metadata in textual form
list_journal
- List contents of journal
FUSE commands¶
Miscellaneous commands¶
version
- Display the version of the invoked bcachefs tool
completions
- Generate shell completions
Superblock commands¶
bcachefs
format
[options] devices ...- Format one or a list of devices with bcachefs data structures. You need to
do this before you create a volume.
Device specific options must come before corresponding devices, e.g.
bcachefs format --label=ssd /dev/sda --label=hdd /dev/sdb
--block_size
=size- block size, in bytes (e.g. 4k)
--btree_node_size
=size- Btree node size, default 256k
--errors
=(continue
|ro
|panic
)- Action to take on filesystem error
--data_replicas
=number- Number of data replicas
--metadata_replicas
=number- Number of metadata replicas
--data_replicas_required
=number--metadata_replicas_required
=number--encoded_extent_max
=size- Maximum size of checksummed/compressed extents
--metadata_checksum
=(none
|crc32c
|crc64
|xxhash
)- Set metadata checksum type (default:
crc32c
). --data_checksum
=(none
|crc32c
|crc64
|xxhash
)- Set data checksum type (default:
crc32c
). --compression
=(none
|lz4
|gzip
|zstd
)- Set compression type (default:
none
). --background_compression
=(none
|lz4
|gzip
|zstd
)--str_hash
=(crc32c
|crc64
|siphash
)- Hash function for directory entries and xattrs
--metadata_target
=target- Device or label for metadata writes
--foreground_target
=target- Device or label for foreground writes
--background_target
=target- Device or label to move data to in the background
--promote_target
=target- Device or label to promote data to on read
--erasure_code
- Enable erasure coding (DO NOT USE YET)
--inodes_32bit
- Constrain inode numbers to 32 bits
- Shared new inode numbers by CPU id
--inodes_use_key_cache
- Use the btree key cache for the inodes btree
--gc_reserve_percent
=percentage- Percentage of disk space to reserve for copygc
--gc_reserve_bytes
=percentage- Amount of disk space to reserve for copygc
This takes precedence over
gc_reserve_percent
if set --root_reserve_percent
=percentage- Percentage of disk space to reserve for superuser
--wide_macs
- Store full 128bits of cryptographic MACS, instead of 80
--acl
- Enable POSIX acls
--usrquota
- Enable user quotas
--grpquota
- Enable group quotas
-prjquota
- Enable project quotas
--journal_transaction_names
- Log transaction function names in journal
--nocow
- Nocow mode: Writes will be done in place when possible.
Snapshots and reflink will still caused writes to be COW.
This flag implicitly disables data checksumming, compression and encryption.
--replicas
=number- Sets both data and metadata replicas
--encrypted
- Enable whole filesystem encryption (chacha20/poly1305); passphrase will be prompted for.
--no_passphrase
- Don't encrypt master encryption key
-L
,--fs_label
=label- Create the filesystem with the specified label
-U
,--uuid
=uuid- Create the filesystem with the specified uuid
--superblock_size
=size
Device specific options:
--discard
- Enable discard/TRIM support
--fs_size
=size- Create the filesystem using size bytes on the subsequent device.
--bucket
=size- Specifies the bucket size; must be greater than the btree node size
--durability
=n- Data written to this device will be considered to have already been replicated n times
-l
,--label
- Disk label
-f
,--force
- Force the filesystem to be created, even if the device already contains a filesystem.
-q
,--quiet
- Only print errors
-v
,--verbose
- Verbose filesystem initialization
bcachefs
show-super
[options] device- Dump superblock information to stdout.
bcachefs
set-option
[options] device-
--errors
=(continue
|ro
|panic
)- Action to take on filesystem error
--metadata_replicas
=number- Number of metadata replicas
--data_replicas
=number- Number of data replicas
--metadata_replicas_required
=number--data_replicas_required
=number--metadata_checksum
=(none
|crc32c
|crc64
|xxhash
)- Set metadata checksum type (default:
crc32c
). --data_checksum
=(none
|crc32c
|crc64
|xxhash
)- Set data checksum type (default:
crc32c
). --compression
=(none
|lz4
|gzip
|zstd
)- Set compression type (default:
none
). --background_compression
=(none
|lz4
|gzip
|zstd
)--str_hash
=(crc32c
|crc64
|siphash
)- Hash function for directory entries and xattrs
--metadata_target
=target- Device or label for metadata writes
--foreground_target
=target- Device or label for foreground writes
--background_target
=target- Device or label to move data to in the background
--promote_target
=target- Device or label to promote data to on read
--erasure_code
- Enable erasure coding (DO NOT USE YET)
--inodes_32bit
- Constrain inode numbers to 32 bits
- Shared new inode numbers by CPU id
--inodes_use_key_cache
- Use the btree key cache for the inodes btree
--gc_reserve_percent
=percentage- Percentage of disk space to reserve for copygc
--gc_reserve_bytes
=percentage- Amount of disk space to reserve for copygc
This takes precedence over
gc_reserve_percent
if set --root_reserve_percent
=percentage- Percentage of disk space to reserve for superuser
--wide_macs
- Store full 128bits of cryptographic MACS, instead of 80
--acl
- Enable POSIX acls
--usrquota
- Enable user quotas
--grpquota
- Enable group quotas
--prjquota
- Enable project quotas
--degraded
- Allow mounting in degraded mode
--very_degraded
- Allow mounting in when data will be missing
--discard
- Enable discard/TRIM support
--verbose
- Extra debugging information during mount/recovery
--journal_flush_delay
=ms- Delay in milliseconds before automatic journal commits
--journal_flush_disabled
- Disable journal flush on sync/fsync
If enabled, writes can be lost, but only since the last journal write (default 1 second)
--journal_reclaim_delay
=ms- Delay in milliseconds before automatic journal reclaim
--move_bytes_in_flight
=bytes- Maximum Amount of IO to keep in flight by the move path
--move_ios_in_flight
=number- Maximum number of IOs to keep in flight by the move path
--fsck
- Run fsck on mount
--fix_errors
=error- Fix errors during fsck without asking
--ratelimit_errors
- Ratelimit error messages during fsck
--nochanges
- Super read only mode - no writes at all will be issued, even if we have to replay the journal
--norecovery
- Don't replay the journal
--journal_transaction_names
- Log transaction function names in journal
--noexcl
- Don't open device in exclusive mode
--direct_io
- Use O_DIRECT (userspace only)
--sb
=offset- Sector offset of superblock
--reconstruct_alloc
- Reconstruct alloc btree
--version_upgrade
=(compatible
|incompatible
|none
)- Set superblock to latest version, allowing any new features to be used
--nocow
- Nocow mode: Writes will be done in place when possible.
Snapshots and reflink will still caused writes to be COW.
This flag implicitly disables data checksumming, compression and encryption.
--nocow_enabled
- Enable nocow mode: enables runtime locking in data move path needed if nocow will ever be in use
--no_data_io
- Skip submit_bio() for data reads and writes, for performance testing purposes
Mount commands¶
bcachefs
mount
[options] device mountpoint- Mount a filesystem. The device can be a device, a
colon-separated list of devices, or UUID=<UUID>. The
mountpoint is the path where the filesystem should
be mounted. If not set, then the filesystem won't actually be mounted but
all steps preceding mounting the filesystem (e.g. asking for passphrase)
will still be performed.
-o
options- Mount options provided as a comma-separated list. See user guide for
complete list.
degraded
- Allow mounting with data degraded
verbose
- Extra debugging info during mount/recovery
fsck
- Run fsck during mount
fix_errors
- Fix errors without asking during fsck
read_only
- Mount in read only mode
version_upgrade
-k
,--key-location
=(fail
|wait
|ask
)- Where the password would be loaded from. (default:
ask
). -c
,--colorize
=(true
|false
)- Force color on/off. Default: auto-detect TTY
-v
- Be verbose. Can be specified more than once.
Repair commands¶
bcachefs
fsck
[options] devices ...- Check an existing filesystem for errors.
Commands for managing a running filesystem¶
bcachefs
fs
usage
[options] [filesystem]- Show disk usage.
-h
,--human-readable
- Print human readable sizes.
Commands for managing devices within a running filesystem¶
bcachefs
device
add
[options] device- Add a device to an existing filesystem.
bcachefs
device
remove
[options] device- Remove a device from a filesystem
bcachefs
device
online
device- Re-add a device to a running filesystem
bcachefs
device
offline
device- Take a device offline, without removing it
-f
,--force
- Force, if data redundancy will be degraded
bcachefs
device
evacuate
device- Move data off of a given device
bcachefs
device
set-state
[options] new-state device-
- new-state=(rw | ro | failed | spare)
-f
,--force
- Force, if data redundancy will be degraded
--force-if-data-lost
- Force, if data will be lost
-o
,--offline
- Set state of an offline device
bcachefs
device
resize
device [size]- Resize filesystem on a device
bcachefs
device
resize-journal
device [size]- Resize journal on a device
Commands for managing subvolumes and snapshots¶
subvolume create
[options] path- Create a new subvolume
subvolume delete
[options] path- Delete an existing subvolume
subvolume snapshot
[options] source dest- Create a snapshot of source at
dest. If specified, source
must be a subvolume; if not specified the snapshot will be of the
subvolume containing dest.
-r
- Make snapshot read-only
Commands for managing filesystem data¶
bcachefs
data
rereplicate
filesystem- Walks existing data in a filesystem, writing additional copies of any degraded data.
bcachefs
data
job
job filesystem- Kick off a data job and report progress
job is one of (
scrub
|rereplicate
|migrate
|rewrite_old_nodes
)
Commands for encryption¶
bcachefs
unlock
device- Unlock an encrypted filesystem prior to running/mounting.
-c
- Check if a device is encrypted
-k
=(session
|user
|user_session
)- Keyring to add to (default:
user
)
bcachefs
set-passphrase
devices ...- Change passphrase on an existing (unmounted) filesystem.
bcachefs
remove-passphrase
devices ...- Remove passphrase on an existing (unmounted) filesystem.
Commands for migration¶
bcachefs
migrate
[options] device- Migrate an existing filesystem to bcachefs
-f
fs- Root of filesystem to migrate
--encrypted
- Enable whole filesystem encryption (chacha20/poly1305)
--no_passphrase
- Don't encrypt master encryption key
-F
- Force, even if metadata file already exists
bcachefs
migrate-superblock
[options] device- Create default superblock after migrating
Commands for operating on files in a bcachefs filesystem¶
bcachefs
setattr
[options] devices ...-
--data_replicas
=number- Number of data replicas
--data_checksum
=(none
|crc32c
|crc64
|xxhash
)- Set data checksum type (default:
crc32c
). --compression
=(none
|lz4
|gzip
|zstd
)- Set compression type (default:
none
). --background_compression
=(none
|lz4
|gzip
|zstd
)--metadata_target
=target- Device or label for metadata writes
--foreground_target
=target- Device or label for foreground writes
--background_target
=target- Device or label to move data to in the background
--promote_target
=target- Device or label to promote data to on read
--erasure_code
- Enable erasure coding (DO NOT USE YET)
--project
--nocow
- Nocow mode: Writes will be done in place when possible.
Commands for debugging¶
These commands work on offline, unmounted filesystems.
bcachefs
dump
[options] device- Dump filesystem metadata
-o
output- Required flag: Output qcow2 image(s)
-f
,--force
- Force; overwrite when needed
--nojournal
- Don't dump entire journal, just dirty entries
bcachefs
list
[options] devices ...- List filesystem metadata to stdout
-b
(extents
|inodes
|dirents
|xattrs
)- Btree to list from. (default:
extents)
-l
,--level
- Btree depth to descend to. (
0
== leaves; default:0)
-s
inode:
offset- Start position to list from
-e
inode:
offset- End position
-m
,--mode
(keys
|formats
|nodes
|nodes-ondisk
)- (default:
keys)
-f
- Check (fsck) the filesystem first
-c
,--colorize
=(true
|false
)- Force color on/off. Default: auto-detect TTY
-v
- Verbose mode
bcachefs
list_journal
[options] devices ...
FUSE commands¶
bcachefs
fusemount
- Mount a filesystem via FUSE
Miscellaneous commands¶
bcachefs
completions
shell- Generate shell completions
bcachefs
version
- Display the version of the invoked bcachefs tool
EXIT STATUS¶
The bcachefs
utility exits 0 on
success, and >0 if an error occurs.
November 17, 2023 | Linux 6.4.0-150600.23.17-default |