path: root/bcachefs.8

.Dd March 7, 2023
.Dt BCACHEFS 8 SMM
.Os
.Sh NAME
.Nm bcachefs
.Nd manage bcachefs filesystems/devices
.Sh SYNOPSIS
.Nm
.Ar command
.Op Ar options
.Op Ar arguments
.Sh DESCRIPTION
The
.Nm
utility supports the following subcommands,
which are documented in detail below:
.Ss Superblock commands
.Bl -tag -width 18n -compact
.It Ic format
Format one or a list of devices with bcachefs data structures.
.It Ic show-super
Dump superblock information to stdout.
.El
.Ss Mount commands
.Bl -tag -width 18n -compact
.It Ic mount
Mount a filesystem.
.El
.Ss Repair commands
.Bl -tag -width 18n -compact
.It Ic fsck
Check an existing filesystem for errors.
.El
.Ss Commands for managing a running filesystem
.Bl -tag -width 18n -compact
.It Ic fs usage
Show disk usage
.El
.Ss Commands for managing devices within a running filesystem
.Bl -tag -width 18n -compact
.It Ic device add
Add a new device to an existing filesystem
.It Ic device remove
Remove a device from an existing filesystem
.It Ic device online
Re-add an existing member to a filesystem
.It Ic device offline
Take a device offline, without removing it
.It Ic device evacuate
Migrate data off of a specific device
.It Ic device set-state
Mark a device as failed
.It Ic device resize
Resize filesystem on a device
.El
.Ss Commands for managing filesystem data
.Bl -tag -width 18n -compact
.It Ic data rereplicate
Rereplicate degraded data
.El
.Ss Commands for encryption
.Bl -tag -width 18n -compact
.It Ic unlock
Unlock an encrypted filesystem prior to running/mounting
.It Ic set-passphrase
Change passphrase on an existing (unmounted) filesystem
.It Ic remove-passphrase
Remove passphrase on an existing (unmounted) filesystem
.El
.Ss Commands for migration
.Bl -tag -width 18n -compact
.It Ic migrate
Migrate an existing filesystem to bcachefs, in place
.It Ic migrate-superblock
Add default superblock, after bcachefs migrate
.El
.Ss Commands for debugging
.Bl -tag -width 18n -compact
.It Ic dump
Dump filesystem metadata to a qcow2 image
.It Ic list
List filesystem metadata in textual form
.El
.Ss Miscellaneous commands
.Bl -tag -width 18n -compact
.It Ic version
Display the version of the invoked bcachefs tool
.El
.Sh Superblock commands
.Bl -tag -width Ds
.It Nm Ic format Oo Ar options Oc Ar devices\ ...
Format one or a list of devices with bcachefs data structures.
You need to do this before you create a volume.
.Pp
Device specific options must come before corresponding devices, e.g.
.Dl bcachefs format --label=ssd /dev/sda --label=hdd /dev/sdb
.Bl -tag -width Ds
.It Fl b , Fl -block Ns = Ns Ar size
block size, in bytes (e.g. 4k)
.It Fl -btree_node Ns = Ns Ar size
Btree node size, default 256k
.It Fl -metadata_checksum_type Ns = Ns ( Cm none | crc32c | crc64 )
Set metadata checksum type (default:
.Cm crc32c ) .
.It Fl -data_checksum_type Ns = Ns ( Cm none | crc32c | crc64 )
Set data checksum type (default:
.Cm crc32c ) .
.It Fl -compression Ns = Ns ( Cm none | lz4 | gzip | zstd )
Set compression type (default:
.Cm none ) .
.It Fl -data_replicas Ns = Ns Ar number
Number of data replicas
.It Fl -metadata_replicas Ns = Ns Ar number
Number of metadata replicas
.It Fl -replicas Ns = Ns Ar number
Sets both data and metadata replicas
.It Fl -encrypted
Enable whole filesystem encryption (chacha20/poly1305);
passphrase will be prompted for.
.It Fl -no_passphrase
Don't encrypt master encryption key
.It Fl -error_action Ns = Ns ( Cm continue | remount-ro | panic )
Action to take on filesystem error (default:
.Cm remount-ro )
.It Fl L , Fl -label Ns = Ns Ar label
Create the filesystem with the specified
.Ar label
.It Fl U , -uuid Ns = Ns Ar uuid
Create the filesystem with the specified
.Ar uuid
.It Fl f , Fl -force
Force the filesystem to be created,
even if the device already contains a filesystem.
.El
.Pp
Device specific options:
.Bl -tag -width Ds
.It Fl -fs_size Ns = Ns Ar size
Create the filesystem using
.Ar size
bytes on the subsequent device.
.It Fl -bucket Ns = Ns Ar size
Specifies the bucket size;
must be greater than the btree node size
.It Fl -discard
Enable discards on subsequent devices
.It Fl q , Fl -quiet
Only print errors
.El
.It Nm Ic show-super Oo Ar options Oc Ar device
Dump superblock information to stdout.
.Bl -tag -width Ds
.It Fl f , Fl -fields Ns = Ns Ar fields
List of sections to print
.It Fl l , Fl -layout
Print superblock layout
.El
.El
.Sh Mount commands
.Bl -tag -width Ds
.It Nm Ic mount Oo Ar options Oc Ar device mountpoint
Mount a filesystem. The
.Ar device
can be a device, a colon-separated list of devices, or UUID=<UUID>. The
.Ar 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.
.Pp the options are as follows:
.Bl -tag -width Ds
.It Fl o Ar options
Mount options provided as a comma-separated list. See userguide for complete list.
.Bl -tag -width Ds -compact
.It Cm degraded
Allow mounting with data degraded
.It Cm verbose
Extra debugging info during mount/recovery
.It Cm fsck
Run fsck during mount
.It Cm fix_errors
Fix errors without asking during fsck
.It Cm read_only
Mount in read only mode
.It Cm version_upgrade
.El
.It Fl k , Fl -key-location Ns = Ns ( Cm fail | wait | ask )
Where the password would be loaded from. (default:
.Cm ask ) .
.Bl -tag -width Ds -compact
.It Cm fail
don't ask for password, fail if filesystem is encrypted.
.It Cm wait
wait for password to become available before mounting.
.It Cm ask
prompt the user for password.
.El
.It Fl v
Be verbose. Can be specified more than once.
.El
.El
.Sh Repair commands
.Bl -tag -width Ds
.It Nm Ic fsck Oo Ar options Oc Ar devices\ ...
Check an existing filesystem for errors.
.Bl -tag -width Ds
.It Fl p
Automatic repair (no questions)
.It Fl n
Don't repair, only check for errors
.It Fl y
Assume "yes" to all questions
.It Fl f
Force checking even if filesystem is marked clean
.It Fl v
Be verbose
.El
.El
.Sh Commands for managing a running filesystem
.Bl -tag -width Ds
.It Nm Ic fs Ic usage Oo Ar options Oc Op Ar filesystem
Show disk usage.
.Bl -tag -width Ds
.It Fl h
Print human readable sizes.
.El
.El
.Sh Commands for managing devices within a running filesystem
.Bl -tag -width Ds
.It Nm Ic device Ic add Oo Ar options Oc Ar device
Add a device to an existing filesystem.
.Bl -tag -width Ds
.It Fl -fs_size Ns = Ns Ar size
Size of filesystem on device
.It Fl -bucket Ns = Ns Ar size
Set bucket size
.It Fl -discard
Enable discards
.It Fl f , Fl -force
Use device even if it appears to already be formatted
.El
.It Nm Ic device Ic remove Oo Ar options Oc Ar device
Remove a device from a filesystem
.Bl -tag -width Ds
.It Fl f , Fl -force
Force removal, even if some data couldn't be migrated
.It Fl -force-metadata
Force removal, even if some metadata couldn't be migrated
.El
.It Nm Ic device Ic online Ar device
Re-add a device to a running filesystem
.It Nm Ic device Ic offline Ar device
Take a device offline, without removing it
.Bl -tag -width Ds
.It Fl f , Fl -force
Force, if data redundancy will be degraded
.El
.It Nm Ic device Ic evacuate Ar device
Move data off of a given device
.It Nm Ic device Ic set-state Oo Ar options Oc Ar new-state Ar device
.Bl -tag -width Ds
.It Ar  new-state Ns = Ns ( Ar rw | ro | failed | spare )
.It Fl f , Fl -force
Force, if data redundancy will be degraded
.El
.It Nm Ic device Ic resize Ar device Op Ar size
Resize filesystem on a device
.El
.Sh Commands for managing filesystem data
.Bl -tag -width Ds
.It Nm Ic device Ic rereplicate Ar filesystem
Walks existing data in a filesystem,
writing additional copies of any degraded data.
.El
.Sh Commands for encryption
.Bl -tag -width Ds
.It Nm Ic unlock Ar device
Unlock an encrypted filesystem prior to running/mounting.
.It Nm Ic set-passphrase Ar devices\ ...
Change passphrase on an existing (unmounted) filesystem.
.It Nm Ic remove-passphrase Ar devices\ ...
Remove passphrase on an existing (unmounted) filesystem.
.El
.Sh Commands for migration
.Bl -tag -width Ds
.It Nm Ic migrate Oo Ar options Oc Ar device
Migrate an existing filesystem to bcachefs
.Bl -tag -width Ds
.It Fl f Ar fs
Root of filesystem to migrate
.It Fl -encrypted
Enable whole filesystem encryption (chacha20/poly1305)
.It Fl -no_passphrase
Don't encrypt master encryption key
.It Fl F
Force, even if metadata file already exists
.El
.It Nm Ic migrate-superblock Oo Ar options Oc Ar device
Create default superblock after migrating
.Bl -tag -width Ds
.It Fl d Ar device
Device to create superblock for
.It Fl o Ar offset
Offset of existing superblock
.El
.El
.Sh Commands for debugging
These commands work on offline, unmounted filesystems.
.Bl -tag -width Ds
.It Nm Ic dump Oo Ar options Oc Ar device
Dump filesystem metadata
.Bl -tag -width Ds
.It Fl o Ar output
Required flag: Output qcow2 image(s)
.It Fl f
Force; overwrite when needed
.El
.It Nm Ic list Oo Ar options Oc Ar devices\ ...
List filesystem metadata to stdout
.Bl -tag -width Ds
.It Fl b ( Cm extents | inodes | dirents | xattrs )
Btree to list from
.It Fl s Ar inode Ns Cm \&: Ns Ar offset
Start position to list from
.It Fl e Ar inode Ns Cm \&: Ns Ar offset
End position
.It Fl i Ar inode
List keys for a given inode number
.It Fl m ( Cm keys | formats )
.It Fl f
Force fsck
.It Fl v
Verbose mode
List mode
.El
.El
.Sh Miscellaneous commands
.Bl -tag -width Ds
.It Nm Ic version
Display the version of the invoked bcachefs tool
.El
.Sh EXIT STATUS
.Ex -std