git.sesse.net Git - bcachefs-tools-debian/blob - bcachefs.8

   1 .Dd September 17, 2023
   2 .Dt BCACHEFS 8 SMM
   3 .Os
   4 .Sh NAME
   5 .Nm bcachefs
   6 .Nd manage bcachefs filesystems/devices
   7 .Sh SYNOPSIS
   8 .Nm
   9 .Ar command
  10 .Op Ar options
  11 .Op Ar arguments
  12 .Sh DESCRIPTION
  13 The
  14 .Nm
  15 utility supports the following subcommands,
  16 which are documented in detail below:
  17 .Ss Superblock commands
  18 .Bl -tag -width 18n -compact
  19 .It Ic format
  20 Format one or a list of devices with bcachefs data structures.
  21 .It Ic show-super
  22 Dump superblock information to stdout.
  23 .It Ic set-option
  24 Set a filesystem option
  25 .El
  26 .Ss Mount commands
  27 .Bl -tag -width 18n -compact
  28 .It Ic mount
  29 Mount a filesystem.
  30 .El
  31 .Ss Repair commands
  32 .Bl -tag -width 18n -compact
  33 .It Ic fsck
  34 Check an existing filesystem for errors.
  35 .El
  36 .Ss Commands for managing a running filesystem
  37 .Bl -tag -width 18n -compact
  38 .It Ic fs usage
  39 Show disk usage
  40 .El
  41 .Ss Commands for managing devices within a running filesystem
  42 .Bl -tag -width 22n -compact
  43 .It Ic device add
  44 Add a new device to an existing filesystem
  45 .It Ic device remove
  46 Remove a device from an existing filesystem
  47 .It Ic device online
  48 Re-add an existing member to a filesystem
  49 .It Ic device offline
  50 Take a device offline, without removing it
  51 .It Ic device evacuate
  52 Migrate data off of a specific device
  53 .It Ic device set-state
  54 Mark a device as failed
  55 .It Ic device resize
  56 Resize filesystem on a device
  57 .It Ic device resize-journal
  58 Resize journal on a device
  59 .El
  60 .Ss Commands for managing subvolumes and snapshots
  61 .Bl -tag -width 18n -compact
  62 .It Ic subvolume create
  63 Create a new subvolume
  64 .It Ic subvolume delete
  65 Delete an existing subvolume
  66 .It Ic subvolume snapshot
  67 Create a snapshot
  68 .El
  69 .Ss Commands for managing filesystem data
  70 .Bl -tag -width 18n -compact
  71 .It Ic data rereplicate
  72 Rereplicate degraded data
  73 .It Ic data job
  74 Kick off low level data jobs
  75 .El
  76 .Ss Commands for encryption
  77 .Bl -tag -width 18n -compact
  78 .It Ic unlock
  79 Unlock an encrypted filesystem prior to running/mounting
  80 .It Ic set-passphrase
  81 Change passphrase on an existing (unmounted) filesystem
  82 .It Ic remove-passphrase
  83 Remove passphrase on an existing (unmounted) filesystem
  84 .El
  85 .Ss Commands for migration
  86 .Bl -tag -width 18n -compact
  87 .It Ic migrate
  88 Migrate an existing filesystem to bcachefs, in place
  89 .It Ic migrate-superblock
  90 Add default superblock, after bcachefs migrate
  91 .El
  92 .Ss Commands for operating on files in a bcachefs filesystem
  93 .Bl -tag -width 18n -compact
  94 .It Ic setattr
  95 Set various per file attributes
  96 .El
  97 .Ss Commands for debugging
  98 .Bl -tag -width 18n -compact
  99 .It Ic dump
 100 Dump filesystem metadata to a qcow2 image
 101 .It Ic list
 102 List filesystem metadata in textual form
 103 .It Ic list_journal
 104 List contents of journal
 105 .El
 106 .Ss FUSE commands
 107 .Bl -tag -width 18n -compact
 108 .It Ic fusemount Mount a filesystem via FUSE
 109 .El
 110 .Ss Miscellaneous commands
 111 .Bl -tag -width 18n -compact
 112 .It Ic version
 113 Display the version of the invoked bcachefs tool
 114 .It Ic completions
 115 Generate shell completions
 116 .El
 117 .Sh Superblock commands
 118 .Bl -tag -width Ds
 119 .It Nm Ic format Oo Ar options Oc Ar devices\ ...
 120 Format one or a list of devices with bcachefs data structures.
 121 You need to do this before you create a volume.
 122 .Pp
 123 Device specific options must come before corresponding devices, e.g.
 124 .Dl bcachefs format --label=ssd /dev/sda --label=hdd /dev/sdb
 125 .Bl -tag -width Ds
 126 .It Fl -block_size Ns = Ns Ar size
 127 block size, in bytes (e.g. 4k)
 128 .It Fl -btree_node_size Ns = Ns Ar size
 129 Btree node size, default 256k
 130 .It Fl -errors Ns = Ns ( Cm continue | ro | panic )
 131 Action to take on filesystem error
 132 .It Fl -data_replicas Ns = Ns Ar number
 133 Number of data replicas
 134 .It Fl -metadata_replicas Ns = Ns Ar number
 135 Number of metadata replicas
 136 .It Fl -data_replicas_required Ns = Ns Ar number
 137
 138 .It Fl -metadata_replicas_required Ns = Ns Ar number
 139
 140 .It Fl -encoded_extent_max Ns = Ns Ar size
 141 Maximum size of checksummed/compressed extents
 142 .It Fl -metadata_checksum Ns = Ns ( Cm none | crc32c | crc64 | xxhash )
 143 Set metadata checksum type (default:
 144 .Cm crc32c ) .
 145 .It Fl -data_checksum Ns = Ns ( Cm none | crc32c | crc64 | xxhash )
 146 Set data checksum type (default:
 147 .Cm crc32c ) .
 148 .It Fl -compression Ns = Ns ( Cm none | lz4 | gzip | zstd )
 149 Set compression type (default:
 150 .Cm none ) .
 151 .It Fl -background_compression Ns = Ns ( Cm none | lz4 | gzip | zstd )
 152
 153 .It Fl -str_hash Ns = Ns ( Cm crc32c | crc64 | siphash )
 154 Hash function for directory entries and xattrs
 155 .It Fl -metadata_target Ns = Ns Ar target
 156 Device or label for metadata writes
 157 .It Fl -foreground_target Ns = Ns Ar target
 158 Device or label for foreground writes
 159 .It Fl -background_target Ns = Ns Ar target
 160 Device or label to move data to in the background
 161 .It Fl -promote_target Ns = Ns Ar target
 162 Device or label to promote data to on read
 163 .It Fl -erasure_code
 164 Enable erasure coding (DO NOT USE YET)
 165 .It Fl -inodes_32bit
 166 Constrain inode numbers to 32 bits
 167 .It Fl -shared_inode_numbers
 168 Shared new inode numbers by CPU id
 169 .It Fl -inodes_use_key_cache
 170 Use the btree key cache for the inodes btree
 171 .It Fl -gc_reserve_percent Ns = Ns Ar percentage
 172 Percentage of disk space to reserve for copygc
 173 .It Fl -gc_reserve_bytes Ns = Ns Ar percentage
 174 Amount of disk space to reserve for copygc
 175 .sp
 176 This takes precedence over
 177 .Cm gc_reserve_percent
 178 if set
 179 .It Fl -root_reserve_percent Ns = Ns Ar percentage
 180 Percentage of disk space to reserve for superuser
 181 .It Fl -wide_macs
 182 Store full 128bits of cryptographic MACS, instead of 80
 183 .It Fl -acl
 184 Enable POSIX acls
 185 .It Fl -usrquota
 186 Enable user quotas
 187 .It Fl -grpquota
 188 Enable group quotas
 189 .It Fl prjquota
 190 Enable project quotas
 191 .It Fl -journal_transaction_names
 192 Log transaction function names in journal
 193 .It Fl -nocow
 194 Nocow mode: Writes will be done in place when possible.
 195 .sp
 196 Snapshots and reflink will still caused writes to be COW.
 197 .sp
 198 This flag implicitly disables data checksumming, compression and
 199 encryption.
 200 .It Fl -replicas Ns = Ns Ar number
 201 Sets both data and metadata replicas
 202 .It Fl -encrypted
 203 Enable whole filesystem encryption (chacha20/poly1305);
 204 passphrase will be prompted for.
 205 .It Fl -no_passphrase
 206 Don't encrypt master encryption key
 207 .It Fl L , Fl -fs_label Ns = Ns Ar label
 208 Create the filesystem with the specified
 209 .Ar label
 210 .It Fl U , -uuid Ns = Ns Ar uuid
 211 Create the filesystem with the specified
 212 .Ar uuid
 213 .It Fl -superblock_size Ns = Ns Ar size
 214
 215 .El
 216 .Pp
 217 Device specific options:
 218 .Bl -tag -width Ds
 219 .It Fl -discard
 220 Enable discard/TRIM support
 221 .It Fl -fs_size Ns = Ns Ar size
 222 Create the filesystem using
 223 .Ar size
 224 bytes on the subsequent device.
 225 .It Fl -bucket Ns = Ns Ar size
 226 Specifies the bucket size;
 227 must be greater than the btree node size
 228 .It Fl -durability Ns = Ns Ar n
 229 Data written to this device will be considered
 230 to have already been replicated
 231 .Ar n
 232 times
 233 .It Fl l , Fl -label
 234 Disk label
 235 .It Fl f , Fl -force
 236 Force the filesystem to be created,
 237 even if the device already contains a filesystem.
 238 .It Fl q , Fl -quiet
 239 Only print errors
 240 .It Fl v , Fl -verbose
 241 Verbose filesystem initialization
 242 .El
 243 .It Nm Ic show-super Oo Ar options Oc Ar device
 244 Dump superblock information to stdout.
 245 .Bl -tag -width Ds
 246 .It Fl f , Fl -fields Ns = Ns Ar fields
 247 List of sections to print
 248 .It Fl l , Fl -layout
 249 Print superblock layout
 250 .El
 251 .El
 252 .Sh Mount commands
 253 .Bl -tag -width Ds
 254 .It Nm Ic mount Oo Ar options Oc Ar device mountpoint
 255 Mount a filesystem. The
 256 .Ar device
 257 can be a device, a colon-separated list of devices, or UUID=<UUID>. The
 258 .Ar mountpoint
 259 is the path where the filesystem should be mounted. If not set, then the filesystem won't actually be mounted
 260 but all steps preceding mounting the filesystem (e.g. asking for passphrase) will still be performed.
 261 .Pp the options are as follows:
 262 .Bl -tag -width Ds
 263 .It Fl o Ar options
 264 Mount options provided as a comma-separated list. See user guide for complete list.
 265 .Bl -tag -width Ds -compact
 266 .It Cm degraded
 267 Allow mounting with data degraded
 268 .It Cm verbose
 269 Extra debugging info during mount/recovery
 270 .It Cm fsck
 271 Run fsck during mount
 272 .It Cm fix_errors
 273 Fix errors without asking during fsck
 274 .It Cm read_only
 275 Mount in read only mode
 276 .It Cm version_upgrade
 277 .El
 278 .It Fl k , Fl -key-location Ns = Ns ( Cm fail | wait | ask )
 279 Where the password would be loaded from. (default:
 280 .Cm ask ) .
 281 .Bl -tag -width Ds -compact
 282 .It Cm fail
 283 don't ask for password, fail if filesystem is encrypted.
 284 .It Cm wait
 285 wait for password to become available before mounting.
 286 .It Cm ask
 287 prompt the user for password.
 288 .El
 289 .It Fl c , Fl -colorize Ns = Ns ( Cm true | false )
 290 Force color on/off. Default: auto-detect TTY
 291 .It Fl v
 292 Be verbose. Can be specified more than once.
 293 .El
 294 .El
 295 .Sh Repair commands
 296 .Bl -tag -width Ds
 297 .It Nm Ic fsck Oo Ar options Oc Ar devices\ ...
 298 Check an existing filesystem for errors.
 299 .Bl -tag -width Ds
 300 .It Fl p
 301 Automatic repair (no questions)
 302 .It Fl n
 303 Don't repair, only check for errors
 304 .It Fl y
 305 Assume "yes" to all questions
 306 .It Fl f
 307 Force checking even if filesystem is marked clean
 308 .It Fl r , Fl -ratelimit_errors
 309 Don't display more than 10 errors of a given type
 310 .It Fl R , Fl -reconstruct_alloc
 311 Reconstruct the alloc btree
 312 .It Fl v
 313 Be verbose
 314 .El
 315 .El
 316 .Sh Commands for managing a running filesystem
 317 .Bl -tag -width Ds
 318 .It Nm Ic fs Ic usage Oo Ar options Oc Op Ar filesystem
 319 Show disk usage.
 320 .Bl -tag -width Ds
 321 .It Fl h , Fl -human-readable
 322 Print human readable sizes.
 323 .El
 324 .El
 325 .Sh Commands for managing devices within a running filesystem
 326 .Bl -tag -width Ds
 327 .It Nm Ic device Ic add Oo Ar options Oc Ar device
 328 Add a device to an existing filesystem.
 329 .Bl -tag -width Ds
 330 .It Fl -fs_size Ns = Ns Ar size
 331 Size of filesystem on device
 332 .It Fl -bucket Ns = Ns Ar size
 333 Set bucket size
 334 .It Fl -discard
 335 Enable discards
 336 .It Fl l , Fl -label Ns = Ns Ar label
 337 Disk label
 338 .It Fl f , Fl -force
 339 Use device even if it appears to already be formatted
 340 .El
 341 .It Nm Ic device Ic remove Oo Ar options Oc Ar device
 342 Remove a device from a filesystem
 343 .Bl -tag -width Ds
 344 .It Fl f , Fl -force
 345 Force removal, even if some data couldn't be migrated
 346 .It Fl F , Fl -force-metadata
 347 Force removal, even if some metadata couldn't be migrated
 348 .El
 349 .It Nm Ic device Ic online Ar device
 350 Re-add a device to a running filesystem
 351 .It Nm Ic device Ic offline Ar device
 352 Take a device offline, without removing it
 353 .Bl -tag -width Ds
 354 .It Fl f , Fl -force
 355 Force, if data redundancy will be degraded
 356 .El
 357 .It Nm Ic device Ic evacuate Ar device
 358 Move data off of a given device
 359 .It Nm Ic device Ic set-state Oo Ar options Oc Ar new-state Ar device
 360 .Bl -tag -width Ds
 361 .It Ar  new-state Ns = Ns ( Ar rw | ro | failed | spare )
 362 .It Fl f , Fl -force
 363 Force, if data redundancy will be degraded
 364 .It Fl -force-if-data-lost
 365 Force, if data will be lost
 366 .It Fl o , Fl -offline
 367 Set state of an offline device
 368 .El
 369 .It Nm Ic device Ic resize Ar device Op Ar size
 370 Resize filesystem on a device
 371 .It Nm Ic device Ic resize-journal Ar device Op Ar size
 372 Resize journal on a device
 373 .El
 374 .Sh Commands for managing subvolumes and snapshots
 375 .Bl -tag -width Ds
 376 .It Ic subvolume create Oo Ar options Oc Ar path
 377 Create a new subvolume
 378 .It Ic subvolume delete Oo Ar options Oc Ar path
 379 Delete an existing subvolume
 380 .It Ic subvolume delete Oo Ar options Oc Ar source dest
 381 Create a snapshot of
 382 .Ar source
 383 at
 384 .Ar dest .
 385 If specified,
 386 .Ar source
 387 must be a subvolume;
 388 if not specified the snapshot will be of the subvolume containing
 389 .Ar dest .
 390 .Bl -tag -width Ds
 391 .It Fl r
 392 Make snapshot read-only
 393 .El
 394 .El
 395 .Sh Commands for managing filesystem data
 396 .Bl -tag -width Ds
 397 .It Nm Ic data Ic rereplicate Ar filesystem
 398 Walks existing data in a filesystem,
 399 writing additional copies of any degraded data.
 400 .It Nm Ic data Ic job Ar job filesystem
 401 Kick off a data job and report progress
 402 .sp
 403 .Ar job
 404 is one of (
 405 .Cm scrub | rereplicate | migrate | rewrite_old_nodes
 406 )
 407 .Bl -tag -width Ds
 408 .It Fl b Ar btree
 409 Btree to operate on
 410 .It Fl s Ar inode Ns Cm \&: Ns Ar offset
 411 Start position
 412 .It Fl e Ar inode Ns Cm \&: Ns Ar offset
 413 End position
 414 .El
 415 .El
 416 .Sh Commands for encryption
 417 .Bl -tag -width Ds
 418 .It Nm Ic unlock Ar device
 419 Unlock an encrypted filesystem prior to running/mounting.
 420 .Bl -tag -width Ds
 421 .It Fl c
 422 Check if a device is encrypted
 423 .It Fl k Ns = Ns ( Cm session | user | user_session )
 424 Keyring to add to (default:
 425 .Cm user )
 426 .El
 427 .It Nm Ic set-passphrase Ar devices\ ...
 428 Change passphrase on an existing (unmounted) filesystem.
 429 .It Nm Ic remove-passphrase Ar devices\ ...
 430 Remove passphrase on an existing (unmounted) filesystem.
 431 .El
 432 .Sh Commands for migration
 433 .Bl -tag -width Ds
 434 .It Nm Ic migrate Oo Ar options Oc Ar device
 435 Migrate an existing filesystem to bcachefs
 436 .Bl -tag -width Ds
 437 .It Fl f Ar fs
 438 Root of filesystem to migrate
 439 .It Fl -encrypted
 440 Enable whole filesystem encryption (chacha20/poly1305)
 441 .It Fl -no_passphrase
 442 Don't encrypt master encryption key
 443 .It Fl F
 444 Force, even if metadata file already exists
 445 .El
 446 .It Nm Ic migrate-superblock Oo Ar options Oc Ar device
 447 Create default superblock after migrating
 448 .Bl -tag -width Ds
 449 .It Fl d Ar device
 450 Device to create superblock for
 451 .It Fl o Ar offset
 452 Offset of existing superblock
 453 .El
 454 .El
 455 .Sh Commands for operating on files in a bcachefs filesystem
 456 .Bl -tag -width Ds
 457 .It Nm Ic setattr Oo Ar options Oc Ar devices\ ...
 458 .Bl -tag -width Ds
 459 .It Fl -data_replicas Ns = Ns Ar number
 460 Number of data replicas
 461 .It Fl -data_checksum Ns = Ns ( Cm none | crc32c | crc64 | xxhash )
 462 Set data checksum type (default:
 463 .Cm crc32c ) .
 464 .It Fl -compression Ns = Ns ( Cm none | lz4 | gzip | zstd )
 465 Set compression type (default:
 466 .Cm none ) .
 467 .It Fl -background_compression Ns = Ns ( Cm none | lz4 | gzip | zstd )
 468
 469 .It Fl -metadata_target Ns = Ns Ar target
 470 Device or label for metadata writes
 471 .It Fl -foreground_target Ns = Ns Ar target
 472 Device or label for foreground writes
 473 .It Fl -background_target Ns = Ns Ar target
 474 Device or label to move data to in the background
 475 .It Fl -promote_target Ns = Ns Ar target
 476 Device or label to promote data to on read
 477 .It Fl -erasure_code
 478 Enable erasure coding (DO NOT USE YET)
 479 .It Fl -project
 480
 481 .It Fl -nocow
 482 Nocow mode: Writes will be done in place when possible.
 483 .El
 484 .El
 485 .Sh Commands for debugging
 486 These commands work on offline, unmounted filesystems.
 487 .Bl -tag -width Ds
 488 .It Nm Ic dump Oo Ar options Oc Ar device
 489 Dump filesystem metadata
 490 .Bl -tag -width Ds
 491 .It Fl o Ar output
 492 Required flag: Output qcow2 image(s)
 493 .It Fl f , Fl -force
 494 Force; overwrite when needed
 495 .It Fl -nojournal
 496 Don't dump entire journal, just dirty entries
 497 .El
 498 .It Nm Ic list Oo Ar options Oc Ar devices\ ...
 499 List filesystem metadata to stdout
 500 .Bl -tag -width Ds
 501 .It Fl b ( Cm extents | inodes | dirents | xattrs )
 502 Btree to list from. (default:
 503 .Cm extents)
 504 .It Fl l , Fl -level
 505 Btree depth to descend to. (
 506 .Cm 0
 507 == leaves; default:
 508 .Cm 0)
 509 .It Fl s Ar inode Ns Cm \&: Ns Ar offset
 510 Start position to list from
 511 .It Fl e Ar inode Ns Cm \&: Ns Ar offset
 512 End position
 513 .It Fl m , Fl -mode ( Cm keys | formats | nodes | nodes-ondisk )
 514 (default:
 515 .Cm keys)
 516 .It Fl f
 517 Check (fsck) the filesystem first
 518 .It Fl c , Fl -colorize Ns = Ns ( Cm true | false )
 519 Force color on/off. Default: auto-detect TTY
 520 .It Fl v
 521 Verbose mode
 522 .El
 523 .It Nm Ic list_journal Oo Ar options Oc Ar devices\ ...
 524 .Bl -tag -width Ds
 525 .It Fl a
 526 Read entire journal, not just dirty entries
 527 .It Fl n , Fl -nr-entries Ns = Ns Ar nr
 528 Number of journal entries to print, starting from the most recent
 529 .It Fl t , Fl -transaction-filter Ns = Ns Ar bbpos
 530 Filter transactions not updating
 531 .Ar bbpos
 532 .It Fl k , Fl -key-filter Ns = Ns Ar btree
 533 Filter keys not updating
 534 .Ar btree
 535 .It Fl v , Fl -verbose
 536 Verbose mode
 537 .El
 538 .El
 539 .Sh FUSE commands
 540 .Bl -tag -width Ds
 541 .It Nm Ic fusemount
 542 Mount a filesystem via FUSE
 543 .El
 544 .Sh Miscellaneous commands
 545 .Bl -tag -width Ds
 546 .It Nm Ic completions Ar shell
 547 Generate shell completions
 548 .It Nm Ic version
 549 Display the version of the invoked bcachefs tool
 550 .El
 551 .Sh EXIT STATUS
 552 .Ex -std