mirror of
https://github.com/koverstreet/bcachefs-tools.git
synced 2025-01-22 00:04:31 +03:00
342 lines
9.3 KiB
Groff
342 lines
9.3 KiB
Groff
.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
|