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

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