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

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