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

   1 .Dd March 7, 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 .El
  24 .Ss Mount commands
  25 .Bl -tag -width 18n -compact
  26 .It Ic mount
  27 Mount a filesystem.
  28 .El
  29 .Ss Repair commands
  30 .Bl -tag -width 18n -compact
  31 .It Ic fsck
  32 Check an existing filesystem for errors.
  33 .El
  34 .Ss Commands for managing a running filesystem
  35 .Bl -tag -width 18n -compact
  36 .It Ic fs usage
  37 Show disk usage
  38 .El
  39 .Ss Commands for managing devices within a running filesystem
  40 .Bl -tag -width 18n -compact
  41 .It Ic device add
  42 Add a new device to an existing filesystem
  43 .It Ic device remove
  44 Remove a device from an existing filesystem
  45 .It Ic device online
  46 Re-add an existing member to a filesystem
  47 .It Ic device offline
  48 Take a device offline, without removing it
  49 .It Ic device evacuate
  50 Migrate data off of a specific device
  51 .It Ic device set-state
  52 Mark a device as failed
  53 .It Ic device resize
  54 Resize filesystem on a device
  55 .El
  56 .Ss Commands for managing filesystem data
  57 .Bl -tag -width 18n -compact
  58 .It Ic data rereplicate
  59 Rereplicate degraded data
  60 .El
  61 .Ss Commands for encryption
  62 .Bl -tag -width 18n -compact
  63 .It Ic unlock
  64 Unlock an encrypted filesystem prior to running/mounting
  65 .It Ic set-passphrase
  66 Change passphrase on an existing (unmounted) filesystem
  67 .It Ic remove-passphrase
  68 Remove passphrase on an existing (unmounted) filesystem
  69 .El
  70 .Ss Commands for migration
  71 .Bl -tag -width 18n -compact
  72 .It Ic migrate
  73 Migrate an existing filesystem to bcachefs, in place
  74 .It Ic migrate-superblock
  75 Add default superblock, after bcachefs migrate
  76 .El
  77 .Ss Commands for debugging
  78 .Bl -tag -width 18n -compact
  79 .It Ic dump
  80 Dump filesystem metadata to a qcow2 image
  81 .It Ic list
  82 List filesystem metadata in textual form
  83 .El
  84 .Ss Miscellaneous commands
  85 .Bl -tag -width 18n -compact
  86 .It Ic version
  87 Display the version of the invoked bcachefs tool
  88 .El
  89 .Sh Superblock commands
  90 .Bl -tag -width Ds
  91 .It Nm Ic format Oo Ar options Oc Ar devices\ ...
  92 Format one or a list of devices with bcachefs data structures.
  93 You need to do this before you create a volume.
  94 .Pp
  95 Device specific options must come before corresponding devices, e.g.
  96 .Dl bcachefs format --label=ssd /dev/sda --label=hdd /dev/sdb
  97 .Bl -tag -width Ds
  98 .It Fl b , Fl -block Ns = Ns Ar size
  99 block size, in bytes (e.g. 4k)
 100 .It Fl -btree_node Ns = Ns Ar size
 101 Btree node size, default 256k
 102 .It Fl -metadata_checksum_type Ns = Ns ( Cm none | crc32c | crc64 )
 103 Set metadata checksum type (default:
 104 .Cm crc32c ) .
 105 .It Fl -data_checksum_type Ns = Ns ( Cm none | crc32c | crc64 )
 106 Set data checksum type (default:
 107 .Cm crc32c ) .
 108 .It Fl -compression Ns = Ns ( Cm none | lz4 | gzip | zstd )
 109 Set compression type (default:
 110 .Cm none ) .
 111 .It Fl -data_replicas Ns = Ns Ar number
 112 Number of data replicas
 113 .It Fl -metadata_replicas Ns = Ns Ar number
 114 Number of metadata replicas
 115 .It Fl -replicas Ns = Ns Ar number
 116 Sets both data and metadata replicas
 117 .It Fl -encrypted
 118 Enable whole filesystem encryption (chacha20/poly1305);
 119 passphrase will be prompted for.
 120 .It Fl -no_passphrase
 121 Don't encrypt master encryption key
 122 .It Fl -error_action Ns = Ns ( Cm continue | remount-ro | panic )
 123 Action to take on filesystem error (default:
 124 .Cm remount-ro )
 125 .It Fl L , Fl -label Ns = Ns Ar label
 126 Create the filesystem with the specified
 127 .Ar label
 128 .It Fl U , -uuid Ns = Ns Ar uuid
 129 Create the filesystem with the specified
 130 .Ar uuid
 131 .It Fl f , Fl -force
 132 Force the filesystem to be created,
 133 even if the device already contains a filesystem.
 134 .El
 135 .Pp
 136 Device specific options:
 137 .Bl -tag -width Ds
 138 .It Fl -fs_size Ns = Ns Ar size
 139 Create the filesystem using
 140 .Ar size
 141 bytes on the subsequent device.
 142 .It Fl -bucket Ns = Ns Ar size
 143 Specifies the bucket size;
 144 must be greater than the btree node size
 145 .It Fl -discard
 146 Enable discards on subsequent devices
 147 .It Fl q , Fl -quiet
 148 Only print errors
 149 .El
 150 .It Nm Ic show-super Oo Ar options Oc Ar device
 151 Dump superblock information to stdout.
 152 .Bl -tag -width Ds
 153 .It Fl f , Fl -fields Ns = Ns Ar fields
 154 List of sections to print
 155 .It Fl l , Fl -layout
 156 Print superblock layout
 157 .El
 158 .El
 159 .Sh Mount commands
 160 .Bl -tag -width Ds
 161 .It Nm Ic mount Oo Ar options Oc Ar device mountpoint
 162 Mount a filesystem. The
 163 .Ar device
 164 can be a device, a colon-separated list of devices, or UUID=<UUID>. The
 165 .Ar mountpoint
 166 is the path where the filesystem should be mounted. If not set, then the filesystem won't actually be mounted
 167 but all steps preceeding mounting the filesystem (e.g. asking for passphrase) will still be performed.
 168 .Pp the options are as follows:
 169 .Bl -tag -width Ds
 170 .It Fl o Ar options
 171 Mount options provided as a comma-separated list. See userguide for complete list.
 172 .Bl -tag -width Ds -compact
 173 .It Cm degraded
 174 Allow mounting with data degraded
 175 .It Cm verbose
 176 Extra debugging info during mount/recovery
 177 .It Cm fsck
 178 Run fsck during mount
 179 .It Cm fix_errors
 180 Fix errors without asking during fsck
 181 .It Cm read_only
 182 Mount in read only mode
 183 .It Cm version_upgrade
 184 .El
 185 .It Fl k , Fl -key-location Ns = Ns ( Cm fail | wait | ask )
 186 Where the password would be loaded from. (default:
 187 .Cm ask ) .
 188 .Bl -tag -width Ds -compact
 189 .It Cm fail
 190 don't ask for password, fail if filesystem is encrypted.
 191 .It Cm wait
 192 wait for password to become available before mounting.
 193 .It Cm ask
 194 prompt the user for password.
 195 .El
 196 .It Fl v
 197 Be verbose. Can be specified more than once.
 198 .El
 199 .El
 200 .Sh Repair commands
 201 .Bl -tag -width Ds
 202 .It Nm Ic fsck Oo Ar options Oc Ar devices\ ...
 203 Check an existing filesystem for errors.
 204 .Bl -tag -width Ds
 205 .It Fl p
 206 Automatic repair (no questions)
 207 .It Fl n
 208 Don't repair, only check for errors
 209 .It Fl y
 210 Assume "yes" to all questions
 211 .It Fl f
 212 Force checking even if filesystem is marked clean
 213 .It Fl v
 214 Be verbose
 215 .El
 216 .El
 217 .Sh Commands for managing a running filesystem
 218 .Bl -tag -width Ds
 219 .It Nm Ic fs Ic usage Oo Ar options Oc Op Ar filesystem
 220 Show disk usage.
 221 .Bl -tag -width Ds
 222 .It Fl h
 223 Print human readable sizes.
 224 .El
 225 .El
 226 .Sh Commands for managing devices within a running filesystem
 227 .Bl -tag -width Ds
 228 .It Nm Ic device Ic add Oo Ar options Oc Ar device
 229 Add a device to an existing filesystem.
 230 .Bl -tag -width Ds
 231 .It Fl -fs_size Ns = Ns Ar size
 232 Size of filesystem on device
 233 .It Fl -bucket Ns = Ns Ar size
 234 Set bucket size
 235 .It Fl -discard
 236 Enable discards
 237 .It Fl f , Fl -force
 238 Use device even if it appears to already be formatted
 239 .El
 240 .It Nm Ic device Ic remove Oo Ar options Oc Ar device
 241 Remove a device from a filesystem
 242 .Bl -tag -width Ds
 243 .It Fl f , Fl -force
 244 Force removal, even if some data couldn't be migrated
 245 .It Fl -force-metadata
 246 Force removal, even if some metadata couldn't be migrated
 247 .El
 248 .It Nm Ic device Ic online Ar device
 249 Re-add a device to a running filesystem
 250 .It Nm Ic device Ic offline Ar device
 251 Take a device offline, without removing it
 252 .Bl -tag -width Ds
 253 .It Fl f , Fl -force
 254 Force, if data redundancy will be degraded
 255 .El
 256 .It Nm Ic device Ic evacuate Ar device
 257 Move data off of a given device
 258 .It Nm Ic device Ic set-state Oo Ar options Oc Ar new-state Ar device
 259 .Bl -tag -width Ds
 260 .It Ar  new-state Ns = Ns ( Ar rw | ro | failed | spare )
 261 .It Fl f , Fl -force
 262 Force, if data redundancy will be degraded
 263 .El
 264 .It Nm Ic device Ic resize Ar device Op Ar size
 265 Resize filesystem on a device
 266 .El
 267 .Sh Commands for managing filesystem data
 268 .Bl -tag -width Ds
 269 .It Nm Ic device Ic rereplicate Ar filesystem
 270 Walks existing data in a filesystem,
 271 writing additional copies of any degraded data.
 272 .El
 273 .Sh Commands for encryption
 274 .Bl -tag -width Ds
 275 .It Nm Ic unlock Ar device
 276 Unlock an encrypted filesystem prior to running/mounting.
 277 .It Nm Ic set-passphrase Ar devices\ ...
 278 Change passphrase on an existing (unmounted) filesystem.
 279 .It Nm Ic remove-passphrase Ar devices\ ...
 280 Remove passphrase on an existing (unmounted) filesystem.
 281 .El
 282 .Sh Commands for migration
 283 .Bl -tag -width Ds
 284 .It Nm Ic migrate Oo Ar options Oc Ar device
 285 Migrate an existing filesystem to bcachefs
 286 .Bl -tag -width Ds
 287 .It Fl f Ar fs
 288 Root of filesystem to migrate
 289 .It Fl -encrypted
 290 Enable whole filesystem encryption (chacha20/poly1305)
 291 .It Fl -no_passphrase
 292 Don't encrypt master encryption key
 293 .It Fl F
 294 Force, even if metadata file already exists
 295 .El
 296 .It Nm Ic migrate-superblock Oo Ar options Oc Ar device
 297 Create default superblock after migrating
 298 .Bl -tag -width Ds
 299 .It Fl d Ar device
 300 Device to create superblock for
 301 .It Fl o Ar offset
 302 Offset of existing superblock
 303 .El
 304 .El
 305 .Sh Commands for debugging
 306 These commands work on offline, unmounted filesystems.
 307 .Bl -tag -width Ds
 308 .It Nm Ic dump Oo Ar options Oc Ar device
 309 Dump filesystem metadata
 310 .Bl -tag -width Ds
 311 .It Fl o Ar output
 312 Required flag: Output qcow2 image(s)
 313 .It Fl f
 314 Force; overwrite when needed
 315 .El
 316 .It Nm Ic list Oo Ar options Oc Ar devices\ ...
 317 List filesystem metadata to stdout
 318 .Bl -tag -width Ds
 319 .It Fl b ( Cm extents | inodes | dirents | xattrs )
 320 Btree to list from
 321 .It Fl s Ar inode Ns Cm \&: Ns Ar offset
 322 Start position to list from
 323 .It Fl e Ar inode Ns Cm \&: Ns Ar offset
 324 End position
 325 .It Fl i Ar inode
 326 List keys for a given inode number
 327 .It Fl m ( Cm keys | formats )
 328 .It Fl f
 329 Force fsck
 330 .It Fl v
 331 Verbose mode
 332 List mode
 333 .El
 334 .El
 335 .Sh Miscellaneous commands
 336 .Bl -tag -width Ds
 337 .It Nm Ic version
 338 Display the version of the invoked bcachefs tool
 339 .El
 340 .Sh EXIT STATUS
 341 .Ex -std