Btrfs (Español)

From ArchWiki

Tango-preferences-desktop-locale-modified.pngLa traducción de este artículo o sección no refleja el texto original.Tango-preferences-desktop-locale-modified.png

Motivos: No updates to finish the traduction were made after 2021-06-04 (Discusión en Talk:Btrfs (Español)#)

Artículos relacionados

De Btrfs Wiki:

btrfs es un moderno Sistema de archivos para Linux copy on write (CoW) enfocado en implementar características avanzadas al mismo tiempo que se centra en la tolerancia a los errores, reparación y fácil administración.
Advertencia: Btrfs tiene algunas características inestables. Véase el Estado de la Wiki de Btrfs, Es Btrfs estable? y Guía de inicio para información más detallada. Vea la sección de #Solución de problemas[broken link: invalid section].

Requisitos

Para utilidades userspace (de espacio de usuario) instale el paquete btrfs-progs, el cual se requiere para operaciones básicas.

Si necesita arrancar desde un sistema de archivos Btrfs (p.ej., su kernel e initramfs están en una partición Btrfs), revise si su gestor de arranque soporta Btrfs.

Creación del sistema de archivos

A continuación se muestra como crear un Sistema de Archivos Btrfs. Para convertir una partición ext3/4 a Btrfs, vea #Conversión Ext3/4 a Btrfs[broken link: invalid section]. Para una instalación sin particiones, vea #Disco Btrfs sin particiones[broken link: invalid section].

Vea mkfs.btrfs(8) para más información.

Sistema de archivos en un único dispositivo

Para crear un sistema de archivos en la partición /dev/partition: 

# mkfs.btrfs -L mylabel /dev/partition

El nodesize para los metadatos por defecto es 16 KB, mientras que el sectorsize predeterminado para los datos es igual al tamaño de página y se auto-detecta. Para usar un nodesize para metadatos más grande (debe ser múltiplo del sectorsize, se permite hasta 64KB), especifique un valor para el nodesize a través del interruptor -n como se muestra en este ejemplo usando bloques de 32KB: 

# mkfs.btrfs -L mylabel -n 32k /dev/partition
Nota: De acuerdo a mkfs.btrfs(8) § OPTIONS, "[un] nodesize más pequeño incrementa la fragmentación pero conduce a árboles-b, lo cual conduce a su vez a menor contención de bloqueos. Nodesizes más grandes brindan mejor empaquetado y menos fragmentación al costo de operaciones de memoria más grandes mientras se actualizan los bloques de metadatos".

Sistema de archivos en múltiples dispositivos

Advertencia: Los modos RAID 5 y RAID 6 de Btrfs son fatalmente desastrosos, y no deberían ser usados "en absoluto, salvo se pruebe con datos desechables" Lista de problemas y parciales soluciones. Vea La página de Btrfs en RAID 5 y RAID 6 para actualizaciones de estado (Se ve que no está actualizado).

Múltiples dispositivos pueden ser usados para crear un RAID. Niveles de Raid soportados incluyen RAID 0, RAID 1, RAID 10, RAID 5 y RAID 6. A partir del kernel 5.5 RAID1c3 y RAID1c4 para 3- y 4- copias del nivel RAID 1. Los niveles RAID pueden ser configurados por separado para los datos y metadatos usando las opciones -d y -m respectivamente. Por defecto los datos tienen una copia (single) y los metadatos están reflejados (raid1). Esto es similar a crear configuración de JBOD , donde los discos se ven como un sistema de archivos, pero los ficheros no están duplicados. Vea Usando Btrfs con múltiples dispositivos para mayor información acerca de como crear un volumen Btrfs RAID. 

# mkfs.btrfs -d single -m raid1 /dev/part1 /dev/part2 ...

Debe incluir, ya sea el hook udev o el btrfs en /etc/mkinitcpio.conf para utilizar múltiples dispositivos Btrfs. Vea el artículo Mkinitcpio (Español)#Hooks más comunes para más información.

Nota:
  • Es posible añadir dispositivos en un sistema de archivos múltiple entonces. Vea este artículo de la wiki de Btrfs Para más información.
  • Los dispositivos pueden estar en diferentes tamaños. De todas formas, si una unidad en la configuración RAID es más grande que los otros, este espacio extra no se usará.
  • Algunos gestores de arranque como Syslinux no tienen soporte para sistemas de archivos con múltiples dispositivos.
  • Btrfs no lee automáticamente del dispositivo más rápido, así que mezclar distintos tipos de discos resulta en un rendimiento inconsistente. Mire esta respuesta de Stack Overflow para más detalles.

Vea #RAID para conseguir consejos en el mantenimiento específico a sistemas de archivos Btrfs de múltiples dispositivos.

Configurar el sistema de archivos

Copy-on-Write (CoW)

Por defecto, Btrfs usa copy-on-write para todos los ficheros en todo momento. Vea la sección Guía Sysadmin de Btrfs para detalles de implementación, como también sus ventajas y desventajas.

Deshabilitar CoW

Para deshabilitar copy-on-write para ficheros recién creados en un subvolumen montado, use la opción de montaje nodatacow. Esto solamente afectará a ficheros recién creados. Copy-on-write todavía ocurrirá con archivos existentes. La opción nodatacow además desactiva la compresión. Véase btrfs(5) Para más detalles.

Nota: De btrfs(5) § MOUNT OPTIONS: "dentro de un único sistema de archivos, no es posible montar algunos sub-volumenes con nodatacow y otros con datacow. La opción de montaje del primer sub-volumen montado aplica para cualquier otro sub-volumen."

Para deshabilitar el copy-on-write para ficheros/directorios únicos: 

$ chattr +C /dir/file

Esto deshabilitará copy-on-write para aquellas operaciones en cuales solo haya una referencia al archivo. Si hay más de una referencia (por ejemplo, a través de cp --reflink=always o debido a una instantánea del sistma de archivos), copy-on-write sigue ocurriendo.

Nota: Del manual de chattr: "Para btrfs, la 'C' flag debe ser establecida en archivos nuevos o vacíos. Si está configurando un archivo el cual ya tenga bloques de datos, es indefinido cuando los bloques asignados al archivo serán completamente estables. Si la 'C' flag está establecida en un directorio, no tendrá efecto en el directorio, pero archivos nuevos creados en este tendrán el atributo No_COW."
Sugerencia: De acuerdo a la nota de arriba, puede usar el siguiente truco para deshabilitar copy-on-write en archivos existentes en un directorio: 
$ mv /path/to/dir /path/to/dir_old
$ mkdir /path/to/dir
$ chattr +C /path/to/dir
$ cp -a /path/to/dir_old/* /path/to/dir
$ rm -rf /path/to/dir_old

Make sure that the data are not used during this process. Also note that mv or cp --reflink as described below will not work.

Crear copias ligeras

Por defecto, cuando se copian archivos en un sistema de archivos Btrfs con cp, copias reales son creadas. Para crear una copia ligera que haga referencia a los originales, utilice la opción reflink: 

$ cp --reflink source dest

Vea la página del manual cp(1) para más detalles en --reflink flag.

Compresión

Btrfs soporta compresión automática y transparente. Esto reduce el tamaño de los archivos como también aumenta significativamente la duración de medios basados en flash, reduciendo la amplificación de escritura. [1][2][3] También se puede mejorar el rendimiento, en algunos casos (p. ej. thread único con I/O de un archivo pesado), mientras que obviamente dañando el rendimiento en otros casos (p.ej. multi-threaded y/o tareas intensivas I/O de la CPU con un archivo grande). Un mejor rendimiento es generalmente logrado con algoritmos más rapidos de compresión como zstd y lzo, y algunos benchmarks proporcionan comparaciones detalladas. La opción de montaje compress=alg habilita considerar automáticamente todos los archivos para compresión, donde alg ya sea zlib, lzo, zstd, o no (para no compresión). Usando esta opción, btrfs revisará si comprimiendo la primera porción de datos lo logra encoger. Si lo hace, la escritura entera del archivo será comprimida. Si no, Nada de eso se va a comprimir. Con esta opción, si la primera porción de la escritura no se encoge, la compresión no sera aplicada a la escritura incluso si el resto de la información encoje tremendamente. [4] Esto está hecho para prevenir que el disco espere para empezar a escribir hasta que todos los datos que se van a escribir estén en btrfs por completo y se compriman. La opción de montaje compress-force=alg puede ser usada en su lugar, lo que hace que btrfs omita comprobar si la compresión encogió la primera porción, y habilita de forma automática probar la compresión archivo por archivo. En el peor caso, esto puede causar (levemente) más consumo de la CPU sin propósito. En todo caso, pruebas empíricas en múltiples sistemas de uso mixto han mostrado una significativa mejora de al rededor del 10% de compresión de disco usando compress-force=zstd sobre solo compress=zstd, el cual también tenía una compresión de disco del 10%.

Sólo archivos creados o modificados después de la opción de montaje estarán comprimidos.

Para aplicar compresión a archivos existentes, use el comando btrfs filesystem defragment -calg, cuando alg ya sea zlib, lzo o zstd. Por ejemplo, para volver a comprimir todo el sistema de archivos con zstd, ejecute el siguiente comando: 

# btrfs filesystem defragment -r -v -czstd /

Para habilitar compresión cuando instala Arch en una partición Btrfs vacía, use la opción compress al montar el sistema de archivos: mount -o compress=zstd /dev/sdxY /mnt/. Durante la configuración, añada compress=zstd a las opciones de montaje del sistema de archivos de root en fstab(Español).

Sugerencia: La compresión además puede ser habilitada por archivo, sin usar la opción de montajecompress; para hacerlo aplique chattr +c al archivo. Cuando sea aplicada a los directorios, causará que los nuevos archivos sean automáticamente comprimidos.
Advertencia:
  • Sistemas que usan viejos kernels o btrfs-progs sin el soporte de zstd pueden ser incapaces de leer o reparar su sistema de archivos si usa esa opción.
  • GRUB introdujo el soporte de zstd en la versión 2.04. Actualice el gestor de arranque de su MBR/ESP ejecutando grub-install con las opciones apropiadas para su configuración BIOS/UEFI, ya que eso no lo hace automáticamente. Véase FS#63235.

Ver tipos y proporciones de compresión

compsize toma una lista de archivos (o el sistema de archivos btrfs entero) y mide los tipos de compresión usados y proporciones de compresión efectiva. El tamaño sin comprimir puede no coincidir con el número dado por otros programas como du, porque cada extensión se cuenta una vez, incluso si se refresca varias veces, e incluso si parte de ella ya no se usa en ningún lado pero no se ha recogido basura. La opción -x la mantiene en un solo sistema de archivos, lo cual es útil en situaciones como compsize -x / para to evitar que intente buscar en subdirectorios que no sean btrfs y falle toda la ejecución.

Sub-volumenes

"Un sub-volumen de btrfs no es un dispositivo de bloque (ni debe ser tratado como uno) en lugar de eso, un sub-volumen btrfs puede considerarse como un archivo de namespace POSIX. Estos namespace pueden ser accesibles vía el sub-volumen de nivel superior del sistema de archivos, o puede ser montado por derecho propio" [5]

Cada sistema de archivos Btrfs tiene un nivel superior de sub-volumen con ID 5. Puede ser montada como / (por defecto), u otro sub-volumen puede ser montado en vez de eso. Los sub-volumenes pueden moverse en el sistema de archivos y se identifican más por su ID que por su ruta.

Revise los siguientes links para más detalles:

Crear un sub-volumen

Para crear un sub-volumen: 

# btrfs subvolume create /path/to/subvolume

Listar sub-volumenes

Para ver una lista de los sub-volumenes actuales y sus ID bajo la path (ruta): 

# btrfs subvolume list -p path

Eliminar un sub-volumen

Para eliminar un sub-volumen: 

# btrfs subvolume delete /path/to/subvolume

Desde Linux 4.18, también se puede eliminar un subvolumen como un directorio regular (rm -r, rmdir).

Montar sub-volumenes

Sub-volumenes pueden ser montados como particiones del sistema de archivos usando las flags subvol=/path/to/subvolume o subvolid=objectid. Por ejemplo, puede tener un sub-volumen llamado subvol_root y montarlo como /. SSe pueden imitar las particiones tradicionales del sistema de archivos creando varios subvolumenes en el nivel superior del sistema de archivos y luego montándolos en los puntos de montaje apropiados. Se pueden imitar las particiones tradicionales del sistema de archivos creando varios subvolumenes en el nivel superior del sistema de archivos y luego montándolos en los puntos de montaje apropiados. En otras palabras uno puede restaurar fácilmente un sistema de archivos (o parte de él) a un estado anterior usando #Snapshots.

Sugerencia: El cambio de diseño de sub-volumen se hace simple al no utilizar el sub-volumen del nivel superior (ID=5) como / (lo cual ocurre por defecto). En vez de eso, considere crear un sub-volumen para sus datos reales y montarlos como /.
Nota: De btrfs(5) § MOUNT OPTIONS: "La mayor parte de opciones de montaje se aplican al sistema de archivos entero, y sólo las opciones para el primer sub-volumen que se va a montar harán. Esto se debe a la implementación y puede cambiar en el futuro." Vea Btrfs Wiki Preguntas Frecuentes para cuales opciones pueden ser usadas por sub-volumen.

Véase Snapper#Suggested filesystem layout, Btrfs SysadminGuide#Managing Snapshots, y Btrfs SysadminGuide#Layout para ejemplos de diseños de sistemas de archivo que usan sub-volumenes.

Véase btrfs(5) para una lista completa de opciónes específicas de montado para btrfs.

Montar sub-volumen en raíz

Para usar un sub-volumen como punto de montaje raíz, especifique el sub-volumen vía parámetros del kernel usando rootflags=subvol=/path/to/subvolume. Edite el punto de montaje raíz en /etc/fstab y especifique el punto de montaje subvol=. Alternativamente el subvolumen puede ser pesecificado con su id, rootflags=subvolid=objectid como parámetro del kernel y subvolid=objectid como opción de montaje en /etc/fstab.

Cambiar el sub-volumen por defecto

El sub-volumen por defecto se monta si no se provee la opción de montado subvol=. Para cambiar el sub-volumen por defecto, haga: 

# btrfs subvolume set-default subvolume-id /

cuando subvolume-id sea encontrado listando.

Nota: Después de cambiar el sub-volumen predeterminado en un sistema con GRUB, debe ejecutar grub-install otra vez para avisarle al gestor de arranque sobre los cambios. Véase este hilo del foro.

Cambiando el sub-volumen por defecto con btrfs subvolume set-default hará que el nivel superior del sistema de archivos sea inaccesible, excepto usando las opciones de montado subvol=/ o subvolid=5 [6].

Quota

Advertencia: Qgroup aún es inestable y combinar Quota con (demasiadas) snapshots o sub-volumenes puede causar problemas de rendimiento, por ejemplo eliminando snapshots. Además hay varios problemas más.

El soporte de Quota en Btrfs se implementa al nivel de sub-volumen por el uso de quota groups (grupos) o qgroup: Cada sub-volumen es asignado a quota groups en forma de 0/subvolume_id por defecto. No obstante, es posible crear un quota group usando cualquier número si lo desea.

Para usar qgroups necesita habilitar quota primero, usando 

# btrfs quota enable path

A partir de este punto en adelante los sub-volumenes recién creados serán controlados por esos grupos. Con el fin de, retrospectivamente habilitarlos them para sub-volumenes existentes, habilite quota normalmente, luego cree un qgroup (quota group) para cada uno de esos sub-volumenes usando subvolume_id y reescaneelos: 

# btrfs subvolume list path | cut -d' ' -f2 | xargs -I{} -n1 btrfs qgroup create 0/{} path
# btrfs quota rescan path

Quota groups en Btrfs forma una jerarquía de árbol, por lo cual qgroups está adjunto a los sub-volumenes. El tamaño límite se establece por qgroup y se aplican cuando cualquier límite del árbol que contenga un determinado sub-volumen es alcanzado.

Límites en quota groups pueden aplicarse al uso total de los datos, ya sea, uso no compartido, datos comprimidos o ambos. Eliminar y copiar archivos puede afectar los límites de ambos debido a que el límite no compartido de otro qgroup puede cambiar si los archivos del volumen original se eliminan y solo queda una copia. Por ejemplo, una nueva snapshot comparte casi todos los bloques con el sub-volumen original, nuevas escrituras a cualquiera de los sub-volumenes hacia el límite exlusivo, eliminaciones de datos comunes en un volumen aumentan hacia el límite exclusivo en el otro.

Para aplicar un límite a un grupo, use el comando btrfs qgroup limit. Dependiendo de su uso utilice un límite total, límite sin comprimir (-e) o límite comprimido (-c). Para ver utilización y límites de una ruta dada dentro del sistema de archivos 

# btrfs qgroup show -reF path

Intervalo de commit

La resolución de cuáles datos son escritos en el sistema de archivos es dictada por el mismo Btrfs y por los ajustes system-wide. Btrfs por defecto tiene 30 segundos de intervalo de punto de control en el cual nuevos datos son cometidos al sistema de archivos. Esto puede ser cambiado añadiendo la opción de montado commit en /etc/fstab para la partición btrfs. 

LABEL=arch64 / btrfs defaults,compress=zstd,commit=120 0 0

Ajustes en el sistema también afectan el intervalo de commits. Incluyen los archivos debajo de /proc/sys/vm/* y están fuera del foco de este artículo Wiki. La documentación del kernel sobre estos reside en Documentation/sysctl/vm.txt.

SSD TRIM

Un sistema de archivos Btrfs es capaz de liberar bloques no utilizados de una unidad SSD que admita el comando TRIM. A partir de la versión del kernel 5.6 hay soporte de descarte asíncrono, habilitado con la opción de montado discard=async. Las extensiones libreadas no se descartan de inmediato, sino que se agrupan y recortan después por un subproceso de trabajo independiente, lo que mejora la latencia del commit.

Más información sobre utilizar y habilitar TRIM disponible en Solid State Drives#TRIM.

Uso

Archivo swap

Btrfs soporta archivo swap a partir del kernel de Linux 5.0.[7] La manera apropiada de iniciar un archivo swap es primero crear un sub-volumen no-comprimido, no-snapshoteado subvolume para albergar el archivo, cd al directorio, luego crear un archivo vacío, establecer el atributo No_COW en su chattr, y deshabilitar la compresión: 

# cd /path/to/swapfile
# truncate -s 0 ./swapfile
# chattr +C ./swapfile
# btrfs property set ./swapfile compression none

Continúe con los siguientes pasos en Swap#Swap file creation. Configure la hibernación del archivo swap como está descrito en Power management (Español)/Suspend and hibernate(Español)#Hibernar en un archivo swap.

Nota: A partir del kernel Linux 5.0, Btrfs tiene soporte para swap nativo con algunas limitaciones:

Ver espacio usado/libre

Herramientas de espacio de usuario de linux como df reportarán de forma incorrecta espacio libre en una partición Btrfs. Se recomienda usar btrfs filesystem usage para consultar particiones Btrfs. Por ejemplo, para un desglose completo de asignación de dispositivos y estadísticas de utilización: 

# btrfs filesystem usage /
Nota: La orden btrfs filesystem usage actualmente no funciona correctamente con los niveles RAID5/RAID6

Alternativamente, btrfs filesystem df permite un vistazo rápido del uso del espacio asignado sin el requisito de ejecutarse como root: 

$ btrfs filesystem df /

Consulte [8] para más información.

Defragmentation

Btrfs supports online defragmentation through the mount option autodefrag, see btrfs(5) § MOUNT OPTIONS. To manually defragment your root, use: 

# btrfs filesystem defragment -r /

Using the above command without the -r switch will result in only the metadata held by the subvolume containing the directory being defragmented. This allows for single file defragmentation by simply specifying the path.

Defragmenting a file which has a COW copy (either a snapshot copy or one made with cp --reflink or bcp) plus using the -c switch with a compression algorithm may result in two unrelated files effectively increasing the disk usage.

RAID

Btrfs offers native "RAID" for #Multi-device file system[broken link: invalid section]s. Notable features which set btrfs RAID apart from mdadm are self-healing redundant arrays and online balancing. See the Btrfs wiki page for more information. The Btrfs sysadmin page also has a section with some more technical background.

Advertencia: Parity RAID (RAID 5/6) code has multiple serious data-loss bugs in it. See the Btrfs Wiki's RAID5/6 page and a bug report on linux-btrfs mailing list for more detailed information. In June 2020, somebody posted a comprehensive list of current issues and a helpful recovery guide.

Scrub

Tango-view-fullscreen.pngThis article or section needs expansion.Tango-view-fullscreen.png

The Btrfs Wiki Glossary says that Btrfs scrub is "[a]n online filesystem checking tool. Reads all the data and metadata on the filesystem, and uses checksums and the duplicate copies from RAID storage to identify and repair any corrupt data."

Nota: A running scrub process will prevent the system from suspending, see this thread for details.

Start manually

To start a (background) scrub on the filesystem which contains /: 

# btrfs scrub start /

To check the status of a running scrub: 

# btrfs scrub status /

Start with a service or timer

The btrfs-progs package brings the [email protected] unit for monthly scrubbing the specified mountpoint. Enable the timer with an escaped path, e.g. [email protected] for / and [email protected] for /home. You can use systemd-escape -p /path/to/mountpoint to escape the path, see systemd-escape(1) for details.

You can also run the scrub by starting [email protected] (with the same encoded path). The advantage of this over btrfs scrub (as the root user) is that the results of the scrub will be logged in the systemd journal.

On large NVMe drives with insufficient cooling (e.g. in a laptop), scrubbing can read the drive fast enough and long enough to get it very hot. If you are running scrubs with systemd, you can easily limit the rate of scrubbing with the IOReadBandwidthMax option described in systemd.resource-control(5) by using a drop-in file.

Balance

"A balance passes all data in the filesystem through the allocator again. It is primarily intended to rebalance the data in the filesystem across the devices when a device is added or removed. A balance will regenerate missing copies for the redundant RAID levels, if a device has failed." [9] See Upstream FAQ page.

On a single-device filesystem a balance may be also useful for (temporarily) reducing the amount of allocated but unused (meta)data chunks. Sometimes this is needed for fixing "filesystem full" issues. 

# btrfs balance start --bg /
# btrfs balance status /

Snapshots

"A snapshot is simply a subvolume that shares its data (and metadata) with some other subvolume, using btrfs's COW capabilities." See Btrfs Wiki SysadminGuide#Snapshots for details.

To create a snapshot: 

# btrfs subvolume snapshot source [dest/]name

To create a readonly snapshot add the -r flag. To create writable version of a readonly snapshot, simply create a snapshot of it.

Nota: Snapshots are not recursive. Every nested subvolume will be an empty directory inside the snapshot.

Send/receive

A subvolume can be sent to stdout or a file using the send command. This is usually most useful when piped to a Btrfs receive command. For example, to send a snapshot named /root_backup (perhaps of a snapshot you made of / earlier) to /backup you would do the following: 

# btrfs send /root_backup | btrfs receive /backup

The snapshot that is sent must be readonly. The above command is useful for copying a subvolume to an external device (e.g. a USB disk mounted at /backup above).

You can also send only the difference between two snapshots. For example, if you have already sent a copy of root_backup above and have made a new readonly snapshot on your system named root_backup_new, then to send only the incremental difference to /backup do: 

# btrfs send -p /root_backup /root_backup_new | btrfs receive /backup

Now a new subvolume named root_backup_new will be present in /backup.

See Btrfs Wiki's Incremental Backup page on how to use this for incremental backups and for tools that automate the process.

Deduplication

Using copy-on-write, Btrfs is able to copy files or whole subvolumes without actually copying the data. However whenever a file is altered a new proper copy is created. Deduplication takes this a step further, by actively identifying blocks of data which share common sequences and combining them into an extent with the same copy-on-write semantics.

Tools dedicated to deduplicate a Btrfs formatted partition include duperemove, bedupAUR and btrfs-dedup. One may also want to merely deduplicate data on a file based level instead using e.g. rmlint, jdupesAUR or dduper-gitAUR. For an overview of available features of those programs and additional information have a look at the upstream Wiki entry.

Furthermore Btrfs developers are working on inband (also known as synchronous or inline) deduplication, meaning deduplication done when writing new data to the filesystem. Currently it is still an experiment which is developed out-of-tree. Users willing to test the new feature should read the appropriate kernel wiki page.

Known issues

A few limitations should be known before trying.

Encryption

Btrfs has no built-in encryption support, but this may come in the future. Users can encrypt the partition before running mkfs.btrfs. See dm-crypt/Encrypting an entire system#Btrfs subvolumes with swap.

Existing Btrfs file systems can use something like EncFS or TrueCrypt, though perhaps without some of Btrfs' features.

btrfs check issues

The tool btrfs check has known issues and should not be run without further reading, see section #btrfs check.

Tips and tricks

Partitionless Btrfs disk

Advertencia:
  • Most users do not want this type of setup and instead should install Btrfs on a regular partition. Furthermore, GRUB strongly discourages installation to a partitionless disk.
  • Since grub 2.04, GRUB's core.img is too big to fit in Btrfs VBR. See FS#63656.

Btrfs can occupy an entire data storage device, replacing the MBR or GPT partitioning schemes, using subvolumes to simulate partitions. However, using a partitionless setup is not required to simply create a Btrfs filesystem[broken link: invalid section] on an existing partition that was created using another method. There are some limitations to partitionless single disk setups:

  • Cannot place other file systems on another partition on the same disk.
  • If using a Linux kernel version before 5.0, you cannot use swap area as Btrfs did not support swap files pre-5.0 and there is no place to create swap partition
  • Cannot use UEFI to boot.

To overwrite the existing partition table with Btrfs, run the following command: 

# mkfs.btrfs /dev/sdX

For example, use /dev/sda rather than /dev/sda1. The latter would format an existing partition instead of replacing the entire partitioning scheme. Because the root partition is Btrfs, make sure btrfs is compiled into the kernel, or put btrfs into mkinitcpio.conf#MODULES and regenerate the initramfs.

Install the boot loader like you would for a data storage device with a Master Boot Record. See Syslinux#Manual install or GRUB/Tips and tricks#Install to partition or partitionless disk. If your kernel does not boot due to Failed to mount /sysroot., please add GRUB_PRELOAD_MODULES="btrfs" in /etc/default/grub and generate the grub configuration (GRUB#Generate the main configuration file).

Ext3/4 to Btrfs conversion

Advertencia: There are many reports on the btrfs mailing list about incomplete/corrupt/broken conversions. Make sure you have working backups of any data you cannot afford to lose. See Conversion from Ext3 on the btrfs wiki for more information.
Advertencia: There is a bug in btrfs-progs 5.6.1 and before, that will yield a btrfs filesystem with wrong size for the last block group, thus preventing to mount the newly converted btrfs. This bug is fixed in btrfs-progs 5.7 in this commit. Please use btrfs-convert from btrfs-progs 5.7-1 and above.

Boot from an install CD, then convert by doing: 

# btrfs-convert /dev/partition

Mount the partion and test the conversion by checking the files. Be sure to change the /etc/fstab to reflect the change (type to btrfs and fs_passno [the last field] to 0 as Btrfs does not do a file system check on boot). Also note that the UUID of the partition will have changed, so update fstab accordingly when using UUIDs. chroot into the system and rebuild your bootloaders menu list (see Install from existing Linux). If converting a root filesystem, while still chrooted run mkinitcpio -p linux to regenerate the initramfs or the system will not successfully boot.

Nota: If there is anything wrong, either unable to mount or write files to the newly converted btrfs, there is always the option to rollback as long as the backup subvolume /ext2_saved is still there. Use btrfs-convert -r /dev/partition command to rollback, this will discard any modifications to the newly converted btrfs filesystem.

After confirming that there are no problems, complete the conversion by deleting the backup ext2_saved sub-volume. Note that you cannot revert back to ext3/4 without it. 

# btrfs subvolume delete /ext2_saved

Finally balance the file system to reclaim the space.

Remember that some applications which were installed prior have to be adapted to Btrfs.

Checksum hardware acceleration

Tango-inaccurate.pngThe factual accuracy of this article or section is disputed.Tango-inaccurate.png

Reason: According to [10], the CRC algorithm printed by the following command simply matches "whatever crypto library is currently loaded at the time", and "can change arbitrarily while the file system is loaded". So this method should not be relied upon in order to determine which CRC algorithm Btrfs is currently using. (Discuss in Talk:Btrfs (Español))

CRC32 is a new instruction in Intel SSE4.2. To verify if Btrfs checksum is hardware accelerated: 

# dmesg | grep crc32c
Btrfs loaded, crc32c=crc32c-intel

If you see crc32c=crc32c-generic, it is probably because your root partition is Btrfs, and you will have to compile crc32c-intel into the kernel to make it work. Putting crc32c-intel into mkinitcpio.conf does not work.

Corruption recovery

Advertencia: The tool btrfs check has known issues, see section #btrfs check

btrfs-check cannot be used on a mounted file system. To be able to use btrfs-check without booting from a live USB, add it to the initial ramdisk: 

/etc/mkinitcpio.conf
BINARIES=("/usr/bin/btrfs")

Regenerate the initramfs.

Then if there is a problem booting, the utility is available for repair.

Nota: If the fsck process has to invalidate the space cache (and/or other caches?) then it is normal for a subsequent boot to hang up for a while (it may give console messages about btrfs-transaction being hung). The system should recover from this after a while.

See the Btrfs Wiki page for more information.

Booting into snapshots

In order to boot into a snapshot, the same procedure applies as for mounting a subvolume as your root parition, as given in section mounting a subvolume as your root partition[broken link: invalid section], because snapshots can be mounted like subvolumes.

  • If using GRUB you can automatically populate your boot menu with btrfs snapshots when regenerating the configuration file with the help of grub-btrfs or grub-btrfs-gitAUR.
  • If using rEFInd you can automatically populate your boot menu with btrfs snapshots with the help of refind-btrfsAUR, after enabling refind-btrfs.service.

Use Btrfs subvolumes with systemd-nspawn

See the Systemd-nspawn#Use Btrfs subvolume as container root and Systemd-nspawn#Use temporary Btrfs snapshot of container articles.

Reducing access time metadata updates

Because of the copy-on-write nature of Btrfs simply accessing files can trigger the metadata copy and writing. Reducing the frequency of access time updates may eliminate this unexpected disk usage and increase performance. See fstab#atime options for the available options.

Troubleshooting

See the Btrfs Problem FAQ for general troubleshooting.

GRUB

Partition offset

The offset problem may happen when you try to embed core.img into a partitioned disk. It means that it is OK to embed GRUB's core.img into a Btrfs pool on a partitionless disk (e.g. /dev/sdX) directly.

GRUB can boot Btrfs partitions, however the module may be larger than other file systems. And the core.img file made by grub-install may not fit in the first 63 sectors (31.5KiB) of the drive between the MBR and the first partition. Up-to-date partitioning tools such as fdisk and gdisk avoid this issue by offsetting the first partition by roughly 1MiB or 2MiB.

Missing root

Tango-inaccurate.pngThe factual accuracy of this article or section is disputed.Tango-inaccurate.png

Reason: Suggests editing a non-configuration file manually. (Discuss in Talk:Btrfs#Should not suggest to edit files in /usr/share)

Users experiencing the following: error no such device: root when booting from a RAID style setup then edit /usr/share/grub/grub-mkconfig_lib and remove both quotes from the line echo " search --no-floppy --fs-uuid --set=root ${hints} ${fs_uuid}". Regenerate the config for grub and the system should boot without an error.

Mounting timed out

Sometimes, especially with large RAID1 arrays, mounting might time out during boot with a journal message such as: 

Jan 25 18:05:12 host systemd[1]: storage.mount: Mounting timed out. Terminating.
Jan 25 18:05:46 host systemd[1]: storage.mount: Mount process exited, code=killed, status=15/TERM
Jan 25 18:05:46 host systemd[1]: storage.mount: Failed with result 'timeout'.
Jan 25 18:05:46 host systemd[1]: Failed to mount /storage.
Jan 25 18:05:46 host systemd[1]: Startup finished in 32.943s (firmware) + 3.097s (loader) + 7.247s (kernel)>
Jan 25 18:05:46 host kernel: BTRFS error (device sda): open_ctree failed

This can easily be worked around by providing a longer timeout via the systemd-specific mount option x-systemd.mount-timeout in fstab. For example: 

/dev/sda                /storage    btrfs       rw,relatime,x-systemd.mount-timeout=5min  0 0

BTRFS: open_ctree failed

As of November 2014 there seems to be a bug in systemd or mkinitcpio causing the following error on systems with multi-device Btrfs filesystem using the btrfs hook in mkinitcpio.conf: 

BTRFS: open_ctree failed
mount: wrong fs type, bad option, bad superblock on /dev/sdb2, missing codepage or helper program, or other error

In some cases useful info is found in syslog - try dmesg|tail or so.

You are now being dropped into an emergency shell.

A workaround is to remove btrfs from the HOOKS array in /etc/mkinitcpio.conf and instead add btrfs to the MODULES array. Then regenerate the initramfs and reboot.

You will get the same error if you try to mount a raid array without one of the devices. In that case you must add the degraded mount option to /etc/fstab. If your root resides on the array, you must also add rootflags=degraded to your kernel parameters.

As of August 2016, a potential workaround for this bug is to mount the array by a single drive only in /etc/fstab, and allow btrfs to discover and append the other drives automatically. Group-based identifiers such as UUID and LABEL appear to contribute to the failure. For example, a two-device RAID1 array consisting of 'disk1' and disk2' will have a UUID allocated to it, but instead of using the UUID, use only /dev/mapper/disk1 in /etc/fstab. For a more detailed explanation, see the following blog post.

Another possible workaround is to remove the udev hook in mkinitcpio.conf and replace it with the systemd hook. In this case, btrfs should not be in the HOOKS or MODULES arrays.

See the original forums thread and FS#42884 for further information and discussion.

btrfs check

Advertencia: Since Btrfs is under heavy development, especially the btrfs check command, it is highly recommended to create a backup and consult the Btrfsck documentation before executing btrfs check with the --repair switch.

The btrfs check command can be used to check or repair an unmounted Btrfs filesystem. However, this repair tool is still immature and not able to repair certain filesystem errors even those that do not render the filesystem unmountable.

See also