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.

   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

   Commands for managing filesystem data
     data rereplicate    Rereplicate degraded data

   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 debugging
     dump                Dump filesystem metadata to a qcow2 image
     list                List filesystem metadata in textual form

   Miscellaneous commands
     version             Display the version of the invoked bcachefs tool

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

             -b, --block=size
                     block size, in bytes (e.g. 4k)

             --btree_node=size
                     Btree node size, default 256k

             --metadata_checksum_type=(none | crc32c | crc64)
                     Set metadata checksum type (default: crc32c).

             --data_checksum_type=(none | crc32c | crc64)
                     Set data checksum type (default: crc32c).

             --compression=(none | lz4 | gzip | zstd)
                     Set compression type (default: none).

             --data_replicas=number
                     Number of data replicas

             --metadata_replicas=number
                     Number of metadata replicas

             --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

             --error_action=(continue | remount-ro | panic)
                     Action to take on filesystem error (default: remount-ro)

             -L, --label=label
                     Create the filesystem with the specified label

             -U, --uuid=uuid
                     Create the filesystem with the specified uuid

             -f, --force
                     Force the filesystem to be created, even if the device already contains a
                     filesystem.

             Device specific options:

             --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

             --discard
                     Enable discards on subsequent devices

             -q, --quiet
                     Only print errors

     bcachefs show-super [options] device
             Dump superblock information to stdout.

             -f, --fields=fields
                     List of sections to print

             -l, --layout
                     Print superblock layout

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 preceeding
             mounting the filesystem (e.g. asking for passphrase) will still be performed.

             -o options
                     Mount options provided as a comma-separated list. See userguide 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).
                     fail    don't ask for password, fail if filesystem is encrypted.
                     wait    wait for password to become available before mounting.
                     ask     prompt the user for password.

             -v      Be verbose. Can be specified more than once.

Repair commands

     bcachefs fsck [options] devices ...
             Check an existing filesystem for errors.

             -p      Automatic repair (no questions)

             -n      Don't repair, only check for errors

             -y      Assume "yes" to all questions

             -f      Force checking even if filesystem is marked clean

             -v      Be verbose

Commands for managing a running filesystem

     bcachefs fs usage [options] [filesystem]
             Show disk usage.

             -h      Print human readable sizes.

Commands for managing devices within a running filesystem

     bcachefs device add [options] device
             Add a device to an existing filesystem.

             --fs_size=size
                     Size of filesystem on device

             --bucket=size
                     Set bucket size

             --discard
                     Enable discards

             -f, --force
                     Use device even if it appears to already be formatted

     bcachefs device remove [options] device
             Remove a device from a filesystem

             -f, --force
                     Force removal, even if some data couldn't be migrated

             --force-metadata
                     Force removal, even if some metadata couldn't be migrated

     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

     bcachefs device resize device [size]
             Resize filesystem on a device

Commands for managing filesystem data

     bcachefs device rereplicate filesystem
             Walks existing data in a filesystem, writing additional copies of any degraded data.

Commands for encryption

     bcachefs unlock device
             Unlock an encrypted filesystem prior to running/mounting.

     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

             -d device
                     Device to create superblock for

             -o offset
                     Offset of existing superblock

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; overwrite when needed

     bcachefs list [options] devices ...
             List filesystem metadata to stdout

             -b (extents | inodes | dirents | xattrs)
                     Btree to list from

             -s inode:offset
                     Start position to list from

             -e inode:offset
                     End position

             -i inode
                     List keys for a given inode number

             -m (keys | formats)

             -f      Force fsck

             -v      Verbose mode List mode

Miscellaneous commands

     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.