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