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 --label=ssd /dev/sda --label=hdd /dev/sdb
 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 Ns = Ns ( Cm none | lz4 | gzip | zstd )
 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 q , Fl -quiet
 154 Only print errors
 155 .El
 156 .It Nm Ic show-super Oo Ar options Oc Ar device
 157 Dump superblock information to stdout.
 158 .Bl -tag -width Ds
 159 .It Fl f , Fl -fields Ns = Ns Ar fields
 160 List of sections to print
 161 .It Fl l , Fl -layout
 162 Print superblock layout
 163 .El
 164 .El
 165 .Sh Repair commands
 166 .Bl -tag -width Ds
 167 .It Nm Ic fsck Oo Ar options Oc Ar devices\ ...
 168 Check an existing filesystem for errors.
 169 .Bl -tag -width Ds
 170 .It Fl p
 171 Automatic repair (no questions)
 172 .It Fl n
 173 Don't repair, only check for errors
 174 .It Fl y
 175 Assume "yes" to all questions
 176 .It Fl f
 177 Force checking even if filesystem is marked clean
 178 .It Fl v
 179 Be verbose
 180 .El
 181 .El
 182 .Sh Startup/shutdown, assembly of multi device filesystems
 183 .Bl -tag -width Ds
 184 .It Nm Ic assemble Ar devices\ ...
 185 Assemble an existing multi device filesystem.
 186 .It Nm Ic incremental Ar device
 187 Incrementally assemble an existing multi device filesystem.
 188 .It Nm Ic run
 189 Start a partially assembled filesystem.
 190 .It Nm Ic stop Ar filesystem
 191 Stop a running filesystem.
 192 .El
 193 .Sh Commands for managing a running filesystem
 194 .Bl -tag -width Ds
 195 .It Nm Ic fs Ic usage Oo Ar options Oc Op Ar filesystem
 196 Show disk usage.
 197 .Bl -tag -width Ds
 198 .It Fl h
 199 Print human readable sizes.
 200 .El
 201 .El
 202 .Sh Commands for managing devices within a running filesystem
 203 .Bl -tag -width Ds
 204 .It Nm Ic device Ic add Oo Ar options Oc Ar device
 205 Add a device to an existing filesystem.
 206 .Bl -tag -width Ds
 207 .It Fl -fs_size Ns = Ns Ar size
 208 Size of filesystem on device
 209 .It Fl -bucket Ns = Ns Ar size
 210 Set bucket size
 211 .It Fl -discard
 212 Enable discards
 213 .It Fl f , Fl -force
 214 Use device even if it appears to already be formatted
 215 .El
 216 .It Nm Ic device Ic remove Oo Ar options Oc Ar device
 217 Remove a device from a filesystem
 218 .Bl -tag -width Ds
 219 .It Fl f , Fl -force
 220 Force removal, even if some data couldn't be migrated
 221 .It Fl -force-metadata
 222 Force removal, even if some metadata couldn't be migrated
 223 .El
 224 .It Nm Ic device Ic online Ar device
 225 Re-add a device to a running filesystem
 226 .It Nm Ic device Ic offline Ar device
 227 Take a device offline, without removing it
 228 .Bl -tag -width Ds
 229 .It Fl f , Fl -force
 230 Force, if data redundancy will be degraded
 231 .El
 232 .It Nm Ic device Ic evacuate Ar device
 233 Move data off of a given device
 234 .It Nm Ic device Ic set-state Oo Ar options Oc Ar new-state Ar device
 235 .Bl -tag -width Ds
 236 .It Ar  new-state Ns = Ns ( Ar rw | ro | failed | spare )
 237 .It Fl f , Fl -force
 238 Force, if data redundancy will be degraded
 239 .El
 240 .It Nm Ic device Ic resize Ar device Op Ar size
 241 Resize filesystem on a device
 242 .El
 243 .Sh Commands for managing filesystem data
 244 .Bl -tag -width Ds
 245 .It Nm Ic device Ic rereplicate Ar filesystem
 246 Walks existing data in a filesystem,
 247 writing additional copies of any degraded data.
 248 .El
 249 .Sh Commands for encryption
 250 .Bl -tag -width Ds
 251 .It Nm Ic unlock Ar device
 252 Unlock an encrypted filesystem prior to running/mounting.
 253 .It Nm Ic set-passphrase Ar devices\ ...
 254 Change passphrase on an existing (unmounted) filesystem.
 255 .It Nm Ic remove-passphrase Ar devices\ ...
 256 Remove passphrase on an existing (unmounted) filesystem.
 257 .El
 258 .Sh Commands for migration
 259 .Bl -tag -width Ds
 260 .It Nm Ic migrate Oo Ar options Oc Ar device
 261 Migrate an existing filesystem to bcachefs
 262 .Bl -tag -width Ds
 263 .It Fl f Ar fs
 264 Root of filesystem to migrate
 265 .It Fl -encrypted
 266 Enable whole filesystem encryption (chacha20/poly1305)
 267 .It Fl -no_passphrase
 268 Don't encrypt master encryption key
 269 .It Fl F
 270 Force, even if metadata file already exists
 271 .El
 272 .It Nm Ic migrate-superblock Oo Ar options Oc Ar device
 273 Create default superblock after migrating
 274 .Bl -tag -width Ds
 275 .It Fl d Ar device
 276 Device to create superblock for
 277 .It Fl o Ar offset
 278 Offset of existing superblock
 279 .El
 280 .El
 281 .Sh Commands for debugging
 282 These commands work on offline, unmounted filesystems.
 283 .Bl -tag -width Ds
 284 .It Nm Ic dump Oo Ar options Oc Ar device
 285 Dump filesystem metadata
 286 .Bl -tag -width Ds
 287 .It Fl o Ar output
 288 Required flag: Output qcow2 image(s)
 289 .It Fl f
 290 Force; overwrite when needed
 291 .El
 292 .It Nm Ic list Oo Ar options Oc Ar devices\ ...
 293 List filesystem metadata to stdout
 294 .Bl -tag -width Ds
 295 .It Fl b ( Cm extents | inodes | dirents | xattrs )
 296 Btree to list from
 297 .It Fl s Ar inode Ns Cm \&: Ns Ar offset
 298 Start position to list from
 299 .It Fl e Ar inode Ns Cm \&: Ns Ar offset
 300 End position
 301 .It Fl i Ar inode
 302 List keys for a given inode number
 303 .It Fl m ( Cm keys | formats )
 304 .It Fl f
 305 Force fsck
 306 .It Fl v
 307 Verbose mode
 308 List mode
 309 .El
 310 .El
 311 .Sh Miscellaneous commands
 312 .Bl -tag -width Ds
 313 .It Nm Ic version
 314 Display the version of the invoked bcachefs tool
 315 .El
 316 .Sh EXIT STATUS
 317 .Ex -std