bpftrace-statsnoop

title: bpftrace-statsnoop(8)

text:
# bpftrace-statsnoop(8)

## NAME
statsnoop.bt - Trace stat() syscalls. Uses bpftrace/eBPF.

## SYNOPSIS
statsnoop.bt

## DESCRIPTION
statsnoop traces the stat() syscall, showing which processes are attempting to stat which files. This can be useful for determining the location of config and log files, or for troubleshooting applications that are failing, specially on startup.

This traces the tracepoints for statfs(), statx(), newstat(), and newlstat(). These aren't the only the stat syscalls: if you are missing activity, you may need to add more variants.

Since this uses BPF, only the root user can use this tool.

## REQUIREMENTS
CONFIG_BPF and bcc.

## EXAMPLES
Trace all stat() syscalls:

\# statsnoop.bt

## FIELDS
PID Process ID

TID

Thread ID

COMM

Process name

FD

File descriptor (if success), or -1 (if failed)

ERR

Error number (see the system's errno.h)

PATH

Stat path

## OVERHEAD
This traces the stat tracepoints and prints output for each event. As the rate of this is generally expected to be low (< 1000/s), the overhead is also expected to be negligible. If you have an application that is calling a high rate of stat()s, then test and understand overhead before use.

## SOURCE
This is from bpftrace.

https://github.com/iovisor/bpftrace

Also look in the bpftrace distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

This is a bpftrace version of the bcc tool of the same name. The bcc tool may provide more options and customizations.

https://github.com/iovisor/bcc

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
opensnoop(8), execsnoop(8)


bpftrace-swapin

package: bpftrace

title: bpftrace-swapin(8)

text:
# bpftrace-swapin(8)

## NAME
swapin - Count swapins by process. Uses bpftrace/eBPF.

## SYNOPSIS
swapin

## DESCRIPTION
This tool counts swapins by process, to show which process is affected by swapping (if swap devices are in use). This can explain a significant source of application latency, if it has began swapping due to memory pressure on the system.

This works by tracing the swap_readpage() kernel function using dynamic instrumentation. This tool may need maintenance to keep working if that function changes in later kernels.

Since this uses BPF, only the root user can use this tool.

## REQUIREMENTS
CONFIG_BPF and bpftrace.

## EXAMPLES
Count swapins by process, showing per-second summaries.

\# swapin.bt

## FIELDS
1st

The process name.

2nd

The process ID.

3rd

The count of swapins during that interval.

## OVERHEAD
The rate of swapins should be low (bounded by swapin device IOPS), such that the overhead of this tool is expected to be negligible.

## SOURCE
This tool originated from the book "BPF Performance Tools", published by Addison Wesley (2019):

http://www.brendangregg.com/bpf-performance-tools-book.html

See the book for more documentation on this tool.

This version is in the bpftrace repository:

https://github.com/iovisor/bpftrace

Also look in the bpftrace distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
swapon(8)


bpftrace-syncsnoop

title: bpftrace-syncsnoop(8)

text:
# bpftrace-syncsnoop(8)

## NAME
syncsnoop.bt - Trace the sync() variety of syscalls. Uses bpftrace/eBPF.

## SYNOPSIS
syncsnoop.bt

## DESCRIPTION
syncsnoop traces calls to sync() syscalls (sync(), fsync(), msync(), etc), which flushes file system cache and buffers to storage devices. These calls can cause performance perturbations, and it can be useful to know if they are happening, when they happen, and how frequently.

This works by tracing the sync() variety of syscalls via tracepoints.

This program is also a basic example of eBPF/bcc.

Since this uses BPF, only the root user can use this tool.

## REQUIREMENTS
CONFIG_BPF and bpftrace.

## EXAMPLES
Trace calls to sync() syscalls:

\# syncsnoop.bt

## FIELDS
TIME

A timestamp on the output, in "HH:MM:SS" format.

PID

The process ID that was on-CPU during the event.

COMM

The process name that was on-CPU during the event.

EVENT

The tracepoint name for the sync event.

## OVERHEAD
This traces sync syscalls and prints output for each event. As the rate of this is generally expected to be low (<< 100/s), the overhead is also expected to be negligible.

## SOURCE
This is from bpftrace.

https://github.com/iovisor/bpftrace

Also look in the bpftrace distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

This is a bpftrace version of the bcc tool of the same name.

https://github.com/iovisor/bcc

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
iostat(1)


bpftrace-syscount

title: bpftrace-syscount(8)

summary: Count system calls. Uses bpftrace/eBPF.

text:
# bpftrace-syscount(8)

## NAME
syscount.bt - Count system calls. Uses bpftrace/eBPF.

## SYNOPSIS
syscount.bt

## DESCRIPTION
This counts system calls (syscalls), printing a summary of the top ten syscall IDs, and the top ten process names making syscalls. This can be helpful for characterizing the kernel and resource workload, and finding applications who are using syscalls inefficiently.

This works by using the tracepoint:raw_syscalls:sys_enter tracepoint.

Since this uses BPF, only the root user can use this tool.

## REQUIREMENTS
CONFIG_BPF and bpftrace.

## EXAMPLES
Count all VFS calls until Ctrl-C is hit:

\# syscount.bt

## OUTPUT
Top 10 syscalls IDs:

This shows the syscall ID number (in @syscall[]) followed by a count for this syscall during tracing. To see the syscall name for that ID, you can use "ausyscall --dump", or the bcc version of this tool that does translations.

Top 10 processes:

This shows the process name (in @process[]) followed by a count of syscalls during tracing.

## OVERHEAD
For most applications, the overhead should be manageable if they perform 1000's or even 10,000's of syscalls per second. For higher rates, the overhead may become considerable. For example, tracing a microbenchmark loop of 4 million calls to geteuid(), slows it down by 2.4x. However, this represents tracing a workload that has a syscall rate of over 4 million syscalls per second per CPU, which should not be typical (in one large cloud production environment, rates of between 10k and 50k are typical, where the application overhead is expected to be closer to 1%).

For comparison, strace(1) in its current ptrace-based implementation (which it has had for decades) runs the same geteuid() workload 102x slower (that's one hundred and two times slower).

## SOURCE
This is from bpftrace.

https://github.com/iovisor/bpftrace

Also look in the bpftrace distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

This is a bpftrace version of the bcc tool of the same name. The bcc version provides different command line options, and translates the syscall IDs to their syscall names.

https://github.com/iovisor/bcc

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
strace(1)


bpftrace-tcpaccept

title: bpftrace-tcpaccept(8)

text:
# bpftrace-tcpaccept(8)

## NAME
tcpaccept.bt - Trace TCP passive connections (accept()). Uses bpftrace/eBPF

## SYNOPSIS
tcpaccept.bt

## DESCRIPTION
This tool traces passive TCP connections (eg, via an accept() syscall; connect() are active connections). This can be useful for general troubleshooting to see what new connections the local server is accepting.

This uses dynamic tracing of the kernel inet_csk_accept() socket function (from tcp_prot.accept), and will need to be modified to match kernel changes.

This tool only traces successful TCP accept()s. Connection attempts to closed ports will not be shown (those can be traced via other functions).

Since this uses BPF, only the root user can use this tool.

## REQUIREMENTS
CONFIG_BPF and bpftrace.

## EXAMPLES
Trace all passive TCP connections (accept()s):

\# tcpaccept.bt

## FIELDS
TIME(s)

Time of the call, in HH:MM:SS format.

PID

Process ID

COMM

Process name

RADDR

Remote IP address.

RPORT

Remote port.

LADDR

Local IP address.

LPORT

Local port

BL

Current accept backlog vs maximum backlog

## OVERHEAD
This traces the kernel inet_csk_accept function and prints output for each event. The rate of this depends on your server application. If it is a web or proxy server accepting many tens of thousands of connections per second, then the overhead of this tool may be measurable (although, still a lot better than tracing every packet). If it is less than a thousand a second, then the overhead is expected to be negligible. Test and understand this overhead before use.

## SOURCE
This is from bpftrace

https://github.com/iovisor/bpftrace

Also look in the bpftrace distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

This is a bpftrace version of the bcc tool of the same name. The bcc tool may provide more options and customizations.

https://github.com/iovisor/bcc

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg, adapted for bpftrace by Dale Hamel

## SEE ALSO
tcpconnect(8), funccount(8), tcpdump(8)


bpftrace-tcpconnect

title: bpftrace-tcpconnect(8)

text:
# bpftrace-tcpconnect(8)

## NAME
tcpconnect.bt - Trace TCP active connections (connect()). Uses Linux bpftrace/eBPF

## SYNOPSIS
tcpconnect.bt

## DESCRIPTION
This tool traces active TCP connections (eg, via a connect() syscall; accept() are passive connections). This can be useful for general troubleshooting to see what connections are initiated by the local server.

All connection attempts are traced, even if they ultimately fail.

This works by tracing the kernel tcp_v4_connect() and tcp_v6_connect() functions using dynamic tracing, and will need updating to match any changes to these functions.

Since this uses BPF, only the root user can use this tool.

## REQUIREMENTS
CONFIG_BPF and bpftrace.

## EXAMPLES
Trace all active TCP connections:

\# tcpconnect.bt

## FIELDS
TIME(s)

Time of the call, in HH:MM:SS format.

PID

Process ID

COMM

Process name

SADDR

Source IP address.

SPORT

Source port.

DADDR

Destination IP address.

DPORT

Destination port

## OVERHEAD
This traces the kernel tcp_v[46]_connect functions and prints output for each event. As the rate of this is generally expected to be low (< 1000/s), the overhead is also expected to be negligible. If you have an application that is calling a high rate of connects()s, such as a proxy server, then test and understand this overhead before use.

## SOURCE
This is from bpftrace

https://github.com/iovisor/bpftrace

Also look in the bpftrace distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

This is a bpftrace version of the bcc tool of the same name. The bcc tool may provide more options and customizations.

https://github.com/iovisor/bcc

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg, adapted for bpftrace by Dale Hamel

## SEE ALSO
tcpaccept(8), funccount(8), tcpdump(8)


bpftrace-tcpdrop

title: bpftrace-tcpdrop(8)

text:
# bpftrace-tcpdrop(8)

## NAME
tcpdrop.bt - Trace kernel-based TCP packet drops with details. Uses Linux bpftrace/eBPF

## SYNOPSIS
tcpdrop.bt

## DESCRIPTION
This tool traces TCP packets or segments that were dropped by the kernel, and shows details from the IP and TCP headers, the socket state, and the kernel stack trace. This is useful for debugging cases of high kernel drops, which can cause timer-based retransmits and performance issues.

This tool works using dynamic tracing of the tcp_drop() kernel function, which requires a recent kernel version.

This tool is limited to ipv4, and cannot parse tcpflags as bpftrace currently cannot parse socket buffers in the way that bcc can.

Since this uses BPF, only the root user can use this tool.

## REQUIREMENTS
CONFIG_BPF and bpftrace.

## EXAMPLES
Trace all tcp drops:

\# tcpdrop.bt

## FIELDS
TIME

Time of the call, in HH:MM:SS format.

PID

Process ID that was on-CPU during the drop. This may be unrelated, as drops can occur on the receive interrupt and be unrelated to the PID that was interrupted.

COMM

Process name

SADDR

Source IP address.

SPORT

Source TCP port.

DADDR

Destination IP address.

DPORT

Destionation TCP port.

STATE

TCP session state ("ESTABLISHED", etc).

## OVERHEAD
This traces the kernel tcp_drop() function, which should be low frequency, and therefore the overhead of this tool should be negligible.

As always, test and understand this tools overhead for your types of workloads before production use.

## SOURCE
This is from bpftrace

https://github.com/iovisor/bpftrace

Also look in the bpftrace distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

This is a bpftrace version of the bcc tool of the same name. The bcc tool may provide more options and customizations.

https://github.com/iovisor/bcc

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg, adapted for bpftrace by Dale Hamel

## SEE ALSO
tcplife(8), tcpaccept(8), tcpconnect(8), tcptop(8)


bpftrace-tcplife

title: bpftrace-tcplife(8)

text:
# bpftrace-tcplife(8)

## NAME
tcplife - Trace TCP session lifespans with connection details. Uses bpftrace/eBPF.

## SYNOPSIS
tcplife

## DESCRIPTION
This tool shows the lifespan of TCP sessions that open and close while tracing, and shows the duration and throughput statistics. For efficiency, this tool only instruments TCP state changes, rather than all packets.

This tool works by using the sock:inet_sock_set_state tracepoint, which was added in Linux 4.16.

Since this uses BPF, only the root user can use this tool.

## REQUIREMENTS
CONFIG_BPF, bpftrace, and the sock:inet_sock_set_state tracepoint (Linux 4.16+).

## EXAMPLES
Show TCP sessions with details:

\# tcplife.bt

## FIELDS
PID

Process ID

COMM

Process name

LADDR

Local IP address.

DADDR

Remote IP address.

LPORT

Local port.

RPORT

Remote port.

TX_KB

Total transmitted Kbytes.

RX_KB

Total received Kbytes.

MS

Lifespan of the session, in milliseconds.

## OVERHEAD
This traces the kernel TCP set state function, which should be called much less often than send/receive tracing, and therefore have lower overhead. The overhead of the tool is relative to the rate of new TCP sessions: if this is high, over 10,000 per second, then there may be noticeable overhead just to print out 10k lines of formatted output per second.

You can find out the rate of new TCP sessions using "sar -n TCP 1", and adding the active/s and passive/s columns.

As always, test and understand this tools overhead for your types of workloads before production use.

## SOURCE
This tool originated from BCC:

https://github.com/iovisor/bcc

The BCC version has many command line options for customizing the output.

This bpftrace version originated from the book "BPF Performance Tools", published by Addison Wesley (2019):

http://www.brendangregg.com/bpf-performance-tools-book.html

See the book for more documentation on this tool.

This bpftrace version is in the bpftrace repository:

https://github.com/iovisor/bpftrace

Also look in the bpftrace distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
tcptop(8)


bpftrace-tcpretrans

title: bpftrace-tcpretrans(8)

text:
# bpftrace-tcpretrans(8)

## NAME
tcpretrans.bt - Trace or count TCP retransmits. Uses Linux bpftrace/eBPF

## SYNOPSIS
tcpretrans.bt

## DESCRIPTION
This traces TCP retransmits, showing address, port, and TCP state information, and sometimes the PID (although usually not, since retransmits are usually sent by the kernel on timeouts). To keep overhead very low, only the TCP retransmit functions are traced. This does not trace every packet (like tcpdump(8) or a packet sniffer). Optionally, it can count retransmits over a user signalled interval to spot potentially dropping network paths the flows are traversing.

This uses dynamic tracing of the kernel tcp_retransmit_skb() and tcp_send_loss_probe() functions, and will need to be updated to match kernel changes to these functions.

Since this uses BPF, only the root user can use this tool.

## REQUIREMENTS
CONFIG_BPF and bcc. CONFIG_BPF and bpftrace.

## EXAMPLES
Trace TCP retransmits:

\# tcpretrans.bt

## FIELDS
TIME

Time of the call, in HH:MM:SS format.

PID

Process ID that was on-CPU. This is less useful than it might sound, as it may usually be 0, for the kernel, for timer-based retransmits.

LADDR

Local IP address.

LPORT

Local port.

RADDR

Remote IP address.

RPORT

Remote port.

STATE

TCP session state.

## OVERHEAD
Should be negligible: TCP retransmit events should be low (<1000/s), and the low overhead this tool adds to each event should make the cost negligible.

## SOURCE
This is from bpftrace

https://github.com/iovisor/bpftrace

Also look in the bpftrace distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

This is a bpftrace version of the bcc tool of the same name. The bcc tool may provide more options and customizations.

https://github.com/iovisor/bcc

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg, adapted for bpftrace by Dale Hamel

## SEE ALSO
tcpconnect(8), tcpaccept(8)


bpftrace-tcpsynbl

title: bpftrace-tcpsynbl(8)

text:
# bpftrace-tcpsynbl(8)

## NAME
tcpsynbl - Show the TCP SYN backlog as a histogram. Uses bpftrace/eBPF.

## SYNOPSIS
tcpsynbl

## DESCRIPTION
This tool shows the TCP SYN backlog size during SYN arrival as a histogram. This lets you see how close your applications are to hitting the backlog limit and dropping SYNs (causing performance issues with SYN retransmits), and is a measure of workload saturation. The histogram shown is measured at the time of SYN received, and a separate histogram is shown for each backlog limit.

This works by tracing the tcp_v4_syn_recv_sock() and tcp_v6_syn_recv_sock() kernel functions using dynamic instrumentation. Since these functions may change in future kernels, this tool may need maintenance to keep working.

Since this uses BPF, only the root user can use this tool.

## REQUIREMENTS
CONFIG_BPF and bpftrace.

## EXAMPLES
Show the TCP SYN backlog as a histogram.

\# tcpsynbl.bt

## FIELDS
backlog

The backlog size when a SYN was received.

count

The number of times this backlog size was encountered.

distribution

An ASCII visualization of the count column.

## OVERHEAD
Inbound SYNs should be relatively low compared to packets and other events, so the overhead of this tool is expected to be negligible.

## SOURCE
This tool originated from the book "BPF Performance Tools", published by Addison Wesley (2019):

http://www.brendangregg.com/bpf-performance-tools-book.html

See the book for more documentation on this tool.

This version is in the bpftrace repository:

https://github.com/iovisor/bpftrace

Also look in the bpftrace distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
tcptop(8)


bpftrace-threadsnoop

title: bpftrace-threadsnoop(8)

text:
# bpftrace-threadsnoop(8)

## NAME
threadsnoop.bt - Trace thread creation via pthread_create(). Uses bpftrace/eBPF.

## SYNOPSIS
threadsnoop.bt

## DESCRIPTION
threadsnoop traces calls to pthread_create(), showing this path of thread creation. This can be used for workload characterization and discovery, and is a companion to execsnoop(8) which traces execve(2).

This works by tracing the pthread_create() from libpthread.so.0. The path to this library may need adjusting in the tool source to match your system.

Since this uses BPF, only the root user can use this tool.

## REQUIREMENTS
CONFIG_BPF and bpftrace.

## EXAMPLES
Trace calls pthread_create():

\# threadsnoop.bt

## FIELDS
TIME(ms)

Elapsed time since the tool began tracing (in milliseconds).

PID

The process ID.

COMM

The process (thread) name.

FUNC

The name of the start routine, if the symbol is available, else a hex address for the start routine address.

## OVERHEAD
Thread creation is expected to be low (<< 1000/s), so the overhead of this tool is expected to be negligible.

## SOURCE
This tool originated from the book "BPF Performance Tools", published by Addison Wesley (2019):

http://www.brendangregg.com/bpf-performance-tools-book.html

See the book for more documentation on this tool.

This version is in the bpftrace repository:

https://github.com/iovisor/bpftrace

Also look in the bpftrace distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
execsnoop(8)


bpftrace-vfscount

title: bpftrace-vfscount(8)

summary: Count VFS calls (vfs_*). Uses bpftrace/eBPF.

text:
# bpftrace-vfscount(8)

## NAME
vfscount.bt - Count VFS calls ("vfs_*"). Uses bpftrace/eBPF.

## SYNOPSIS
vfscount.bt

## DESCRIPTION
This counts VFS calls. This can be useful for general workload characterization of these operations.

This works by tracing all kernel functions beginning with "vfs_" using dynamic tracing. This may match more functions than you are interested in measuring: Edit the script to customize which functions to trace.

Since this uses BPF, only the root user can use this tool.

## REQUIREMENTS
CONFIG_BPF and bpftrace.

## EXAMPLES
Count all VFS calls until Ctrl-C is hit:

\# vfscount.bt

## FIELDS
1st

Kernel function name (in @[])

2nd

Number of calls while tracing

## OVERHEAD
This traces kernel vfs functions and maintains in-kernel counts, which are asynchronously copied to user-space. While the rate of VFS operations can be very high (>1M/sec), this is a relatively efficient way to trace these events, and so the overhead is expected to be small for normal workloads. Measure in a test environment, and if overheads are an issue, edit the script to reduce the types of vfs functions traced (currently all beginning with "vfs_").

## SOURCE
This is from bpftrace.

https://github.com/iovisor/bpftrace

Also look in the bpftrace distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

This is a bpftrace version of the bcc tool of the same name. The bcc tool may provide more options and customizations.

https://github.com/iovisor/bcc

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
vfsstat.bt(8)


bpftrace-vfsstat

title: bpftrace-vfsstat(8)

text:
# bpftrace-vfsstat(8)

## NAME
vfsstat.bt - Count key VFS calls. Uses bpftrace/eBPF.

## SYNOPSIS
vfsstat.bt

## DESCRIPTION
This traces some common VFS calls and prints per-second summaries. This can be useful for general workload characterization, and looking for patterns in operation usage over time.

This works by tracing some kernel vfs functions using dynamic tracing, and will need updating to match any changes to these functions. Edit the script to customize which functions are traced. Also see vfscount, which is more easily customized to trace multiple functions.

Since this uses BPF, only the root user can use this tool.

## REQUIREMENTS
CONFIG_BPF and bpftrace.

## EXAMPLES
Count some VFS calls, printing per-second summaries until Ctrl-C is hit:

\# vfsstat.bt

## FIELDS
HH:MM:SS

Each output summary is prefixed by the time of printing in "HH:MM:SS" format.

1st

Kernel function name (in @[])

2nd

Number of calls while tracing

## OVERHEAD
This traces various kernel vfs functions and maintains in-kernel counts, which are asynchronously copied to user-space. While the rate of VFS operations can be very high (>1M/sec), this is a relatively efficient way to trace these events, and so the overhead is expected to be small for normal workloads. Measure in a test environment.

## SOURCE
This is from bpftrace.

https://github.com/iovisor/bpftrace

Also look in the bpftrace distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

This is a bpftrace version of the bcc tool of the same name. The bcc tool may provide more options and customizations.

https://github.com/iovisor/bcc

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
vfscount.bt(8)


bpftrace-writeback

title: bpftrace-writeback(8)

text:
# bpftrace-writeback(8)

## NAME
writeback.bt - Trace file system writeback events with details. Uses bpftrace/eBPF.

## SYNOPSIS
writeback.bt

## DESCRIPTION
This traces when file system dirtied pages are flushed to disk by kernel writeback, and prints details including when the event occurred, and the duration of the event. This can be useful for correlating these times with other performance problems, and if there is a match, it would be a clue that the problem may be caused by writeback. How quickly the kernel does writeback can be tuned: see the kernel docs, eg, vm.dirty_writeback_centisecs.

This uses the tracepoint:writeback:writeback_start and tracepoint:writeback:writeback_written tracepoints.

Since this uses BPF, only the root user can use this tool.

## REQUIREMENTS
CONFIG_BPF and bpftrace.

## EXAMPLES
Trace all writeback events with timestamps and latency details:

\# writeback.bt

## FIELDS
TIME

Time that the writeback event completed, in %H:%M:%S format.

DEVICE

Device name in major:minor number format.

PAGES

Pages written during writeback.

REASON

Reason for the writeback event. This may be "background", "vmscan", "sync", "periodic", etc.

ms

Duration of the writeback event in milliseconds.

## OVERHEAD
Since writeback events are expected to be infrequent (<10/sec), the overhead of this tool is expected to be negligible (near 0%).

## SOURCE
This is from bpftrace.

https://github.com/iovisor/bpftrace

Also look in the bpftrace distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
biosnoop(8)


bpftrace-xfsdist

title: bpftrace-xfsdist(8)

text:
# bpftrace-xfsdist(8)

## NAME
xfsdist.bt - Summarize XFS operation latency. Uses bpftrace/eBPF.

## SYNOPSIS
xfsdist.bt

## DESCRIPTION
This tool summarizes time (latency) spent in common XFS file operations: reads, writes, opens, and syncs, and presents it as a power-of-2 histogram. It uses an in-kernel eBPF map to store the histogram for efficiency.

Since this works by tracing the xfs_file_operations interface functions, it will need updating to match any changes to these functions.

Since this uses BPF, only the root user can use this tool.

## REQUIREMENTS
CONFIG_BPF and bpftrace.

## EXAMPLES
Trace XFS operation time, and print a summary on Ctrl-C:

\# xfsdist.bt

## FIELDS
0th

The operation name (shown in "@[...]") is printed before each I/O histogram.

1st, 2nd

This is a range of latency, in microseconds (shown in "[...)" set notation).

3rd

A column showing the count of operations in this range.

4th

This is an ASCII histogram representing the count column.

## OVERHEAD
This adds low-overhead instrumentation to these XFS operations, including reads and writes from the file system cache. Such reads and writes can be very frequent (depending on the workload; eg, 1M/sec), at which point the overhead of this tool may become noticeable. Measure and quantify before use.

## SOURCE
This is from bpftrace.

https://github.com/iovisor/bpftrace

Also look in the bpftrace distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

This is a bpftrace version of the bcc tool of the same name. The bcc tool may provide more options and customizations.

https://github.com/iovisor/bcc

## OS
Linux

## STABILITY
Unstable - in development.

## AUTHOR
Brendan Gregg

## SEE ALSO
biolatency(8)


brctl

package: bridge-utils

title: brctl(8)

summary: ethernet bridge administration

text:
# brctl(8)

## NAME
brctl - ethernet bridge administration

## SYNOPSIS
brctl [command]

## DESCRIPTION
brctl is used to set up, maintain, and inspect the ethernet bridge configuration in the Linux kernel.

An ethernet bridge is a device commonly used to connect different networks of ethernets together, so that these ethernets will appear as one ethernet to the participants.

Each of the ethernets being connected corresponds to one physical interface in the bridge. These individual ethernets are bundled into one bigger ('logical') ethernet, this bigger ethernet corresponds to the bridge network interface.

## INSTANCES
The command brctl addbr <name> creates a new instance of the ethernet bridge. The network interface corresponding to the bridge will be called <name>.

The command brctl delbr <name> deletes the instance <name> of the ethernet bridge. The network interface corresponding to the bridge must be down before it can be deleted!

The command brctl show shows all current instances of the ethernet bridge.

## PORTS
Each bridge has a number of ports attached to it. Network traffic coming in on any of these ports will be forwarded to the other ports transparently, so that the bridge is invisible to the rest of the network (i.e. it will not show up in traceroute(8) ).

The command brctl addif <brname> <ifname> will make the interface <ifname> a port of the bridge <brname>. This means that all frames received on <ifname> will be processed as if destined for the bridge. Also, when sending frames on <brname>, <ifname> will be considered as a potential output interface.

The command brctl delif <brname> <ifname> will detach the interface <ifname> from the bridge <brname>.

The command brctl show <brname> will show some information on the bridge and its attached ports.

## AGEING
The bridge keeps track of ethernet addresses seen on each port. When it needs to forward a frame, and it happens to know on which port the destination ethernet address (specified in the frame) is located, it can 'cheat' by forwarding the frame to that port only, thus saving a lot of redundant copies and transmits.

However, the ethernet address location data is not static data. Machines can move to other ports, network cards can be replaced (which changes the machine's ethernet address), etc.

brctl showmacs <brname> shows a list of learned MAC addresses for this bridge.

brctl setageing <brname> <time> sets the ethernet (MAC) address ageing time, in seconds. After <time> seconds of not having seen a frame coming from a certain address, the bridge will time out (delete) that address from the Forwarding DataBase (fdb).

brctl setgcint <brname> <time> sets the garbage collection interval for the bridge <brname> to <time> seconds. This means that the bridge will check the forwarding database for timed out entries every <time> seconds.

## SPANNING TREE PROTOCOL
Multiple ethernet bridges can work together to create even larger networks of ethernets using the IEEE 802.1d spanning tree protocol. This protocol is used for finding the shortest path between two ethernets, and for eliminating loops from the topology. As this protocol is a standard, Linux bridges will interwork properly with other third party bridge products. Bridges communicate with each other by sending and receiving BPDUs (Bridge Protocol Data Units). These BPDUs can be recognised by an ethernet destination address of 01:80:c2:00:00:00.

The spanning tree protocol can also be turned off (for those situations where it just doesn't make sense, for example when this Linux box is the only bridge on the LAN, or when you know that there are no loops in the topology.)

brctl(8) can be used for configuring certain spanning tree protocol parameters. For an explanation of these parameters, see the IEEE 802.1d specification (or send me an email). The default values should be just fine. If you don't know what these parameters mean, you probably won't feel the desire to tweak them.

brctl stp <bridge> <state> controls this bridge instance's participation in the spanning tree protocol. If <state> is "on" or "yes" the STP will be turned on, otherwise it will be turned off. When turned off, the bridge will not send or receive BPDUs, and will thus not participate in the spanning tree protocol. If your bridge isn't the only bridge on the LAN, or if there are loops in the LAN's topology, DO NOT turn this option off. If you turn this option off, please know what you are doing.

brctl setbridgeprio <bridge> <priority> sets the bridge's priority to <priority>. The priority value is an unsigned 16-bit quantity (a number between 0 and 65535), and has no dimension. Lower priority values are 'better'. The bridge with the lowest priority will be elected 'root bridge'.

brctl setfd <bridge> <time> sets the bridge's 'bridge forward delay' to <time> seconds.

brctl sethello <bridge> <time> sets the bridge's 'bridge hello time' to <time> seconds.

brctl setmaxage <bridge> <time> sets the bridge's 'maximum message age' to <time> seconds.

brctl setpathcost <bridge> <port> <cost> sets the port cost of the port <port> to <cost>. This is a dimensionless metric.

brctl setportprio <bridge> <port> <priority> sets the port <port>'s priority to <priority>. The priority value is an unsigned 8-bit quantity (a number between 0 and 255), and has no dimension. This metric is used in the designated port and root port selection algorithms.

## NOTES
brctl(8) replaces the older brcfg tool.

## SEE ALSO
ipchains(8), iptables(8)

## AUTHOR
Lennert Buytenhek <buytenh@gnu.org>


compsize

package: btrfs-compsize

title: compsize(8)

text:
# compsize(8)

## NAME
compsize - calculate compression ratio of a set of files on btrfs

## SYNOPSIS
compsize file-or-dir [ file-or-dir ... ]

## DESCRIPTION
compsize takes a list of files on a btrfs filesystem (recursing directories) and measures used compression types and the effective compression ratio. Besides compression, compsize shows the effect of reflinks (cp --reflink, snapshots, deduplication), and certain types of btrfs waste.

The program gives a report similar to:

Processed 90319 files.

Type Perc Disk Usage Uncompressed Referenced

TOTAL 79% 1.4G 1.8G 1.9G

none 100% 1.0G 1.0G 1.0G

lzo 53% 446M 833M 843M

The fields above are:

Type

compression algorithm

Perc

disk usage/uncompressed (compression ratio)

Disk Usage

blocks on the disk; this is what storing these files actually costs you (save for RAID considerations)

Uncompressed

uncompressed extents; what you would need without compression - includes deduplication savings and pinned extent waste

Referenced

apparent file sizes (sans holes); this is what a traditional filesystem that supports holes and efficient tail packing, or tar -S, would need to store these files

Let's see this on an example: a file 128K big is stored as a single extent A which compressed to a single 4K page. It then receives a write of 32K at offset 32K, which also compressed to a single 4K page, stored as extent B.

The file now appears as:

+-------+-------+---------------+

extent A | used | waste | used |

+-------+-------+---------------+

extent B | used |

+-------+

The "waste" inside extent A can't be gotten rid until the whole extent is rewritten (for example by defrag). If compressed, the whole extent needs to be read every time that part of the file is being read, thus the "waste" is still required.

In this case, we have: Disk Usage: 8KB, Uncompressed: 160K, Referenced: 128K.

## OPTIONS
-b/--bytes

Show raw byte counts rather than human-friendly sizes.

-x/--one-file-system

Skip files and directories on different file systems.

## SIGNALS
USR1

Displays partial data for files processed so far.

## CAVEATS
Recently written files may show as not taking any space until they're actually allocated and compressed; this happens once they're synced or on natural writeout, typically on the order of 30 seconds.

The ioctls used by this program require root.

Inline extents are considered to be always unique, even if they share the same bytes on the disk.

This program doesn't currently support filesystems above 8TB on 32-bit machines but neither do other btrfs tools.


btrfs

package: btrfs-progs

title: btrfs(8)

summary: a toolbox to manage btrfs filesystems

text:
# btrfs(8)

## NAME
btrfs - a toolbox to manage btrfs filesystems

## SYNOPSIS
btrfs [global] <group> [<group>...] <command> [<args>]

## DESCRIPTION
The btrfs utility is a toolbox for managing btrfs filesystems. There are command groups to work with subvolumes, devices, for whole filesystem or other specific actions. See section COMMANDS.

There are also standalone tools for some tasks like btrfs-convert or btrfstune that were separate historically and/or haven't been merged to the main utility. See section STANDALONE TOOLS for more details.

For other topics (mount options, etc) please refer to the separate manual page btrfs(5).

## COMMAND SYNTAX
Any command name can be shortened so long as the shortened form is unambiguous, however, it is recommended to use full command names in scripts. All command groups have their manual page named btrfs-<group>.

For example: it is possible to run btrfs sub snaps instead of btrfs subvolume snapshot. But btrfs file s is not allowed, because file s may be interpreted both as filesystem show and as filesystem sync.

If the command name is ambiguous, the list of conflicting options is printed.

Sizes, both upon input and output, can be expressed in either SI or IEC-I units (see numfmt(1)) with the suffix B appended. All numbers will be formatted according to the rules of the C locale (ignoring the shell locale, see locale(7)).

For an overview of a given command use btrfs command --help or btrfs [command...] --help --full to print all available options.

There are global options that are passed between btrfs and the group name and affect behaviour not specific to the command, e.g. verbosity or the type of the output.

--format <format>

if supported by the command, print subcommand output in that format (text, json)

-v|--verbose

increase verbosity of the subcommandn"

-q|--quiet

print only errorsn"

--log <level>

set log level (default, info, verbose, debug, quiet)n"

The remaining options are relevant only for the main tool:

--help

print condensed help for all subcommands

--version

print version string

## COMMANDS
balance

Balance btrfs filesystem chunks across single or several devices. See btrfs-balance(8) for details.

check

Do off-line check on a btrfs filesystem. See btrfs-check(8) for details.

device

Manage devices managed by btrfs, including add/delete/scan and so on. See btrfs-device(8) for details.

filesystem

Manage a btrfs filesystem, including label setting/sync and so on. See btrfs-filesystem(8) for details.

inspect-internal

Debug tools for developers/hackers. See btrfs-inspect-internal(8) for details.

property

Get/set a property from/to a btrfs object. See btrfs-property(8) for details.

qgroup

Manage quota group(qgroup) for btrfs filesystem. See btrfs-qgroup(8) for details.

quota

Manage quota on btrfs filesystem like enabling/rescan and etc. See btrfs-quota(8) and btrfs-qgroup(8) for details.

receive

Receive subvolume data from stdin/file for restore and etc. See btrfs-receive(8) for details.

replace

Replace btrfs devices. See btrfs-replace(8) for details.

rescue

Try to rescue damaged btrfs filesystem. See btrfs-rescue(8) for details.

restore

Try to restore files from a damaged btrfs filesystem. See btrfs-restore(8) for details.

scrub

Scrub a btrfs filesystem. See btrfs-scrub(8) for details.

send

Send subvolume data to stdout/file for backup and etc. See btrfs-send(8) for details.

subvolume

Create/delete/list/manage btrfs subvolume. See btrfs-subvolume(8) for details.

## STANDALONE TOOLS
New functionality could be provided using a standalone tool. If the functionality proves to be useful, then the standalone tool is declared obsolete and its functionality is copied to the main tool. Obsolete tools are removed after a long (years) depreciation period.

Tools that are still in active use without an equivalent in btrfs:

btrfs-convert

in-place conversion from ext2/3/4 filesystems to btrfs

btrfstune

tweak some filesystem properties on a unmounted filesystem

btrfs-select-super

rescue tool to overwrite primary superblock from a spare copy

btrfs-find-root

rescue helper to find tree roots in a filesystem

For space-constrained environments, it's possible to build a single binary with functionality of several standalone tools. This is following the concept of busybox where the file name selects the functionality. This works for symlinks or hardlinks. The full list can be obtained by btrfs help --box.

## EXIT STATUS
btrfs returns a zero exit status if it succeeds. Non zero is returned in case of failure.

## AVAILABILITY
btrfs is part of btrfs-progs. Please refer to the documentation at https://btrfs.readthedocs.io.

## SEE ALSO
btrfs(5), btrfs-balance(8), btrfs-check(8), btrfs-convert(8), btrfs-device(8), btrfs-filesystem(8), btrfs-inspect-internal(8), btrfs-property(8), btrfs-qgroup(8), btrfs-quota(8), btrfs-receive(8), btrfs-replace(8), btrfs-rescue(8), btrfs-restore(8), btrfs-scrub(8), btrfs-send(8), btrfs-subvolume(8), btrfstune(8), mkfs.btrfs(8)


btrfs-balance

title: btrfs-balance(8)

text:
# btrfs-balance(8)

## NAME
btrfs-balance - balance block groups on a btrfs filesystem

## SYNOPSIS
btrfs balance <subcommand> <args>

## DESCRIPTION
The primary purpose of the balance feature is to spread block groups across all devices so they match constraints defined by the respective profiles. See mkfs.btrfs(8) section PROFILES for more details. The scope of the balancing process can be further tuned by use of filters that can select the block groups to process. Balance works only on a mounted filesystem. Extent sharing is preserved and reflinks are not broken. Files are not defragmented nor recompressed, file extents are preserved but the physical location on devices will change.

The balance operation is cancellable by the user. The on-disk state of the filesystem is always consistent so an unexpected interruption (e.g. system crash, reboot) does not corrupt the filesystem. The progress of the balance operation is temporarily stored as an internal state and will be resumed upon mount, unless the mount option skip_balance is specified.

WARNING:

Running balance without filters will take a lot of time as it basically move data/metadata from the whole filesystem and needs to update all block pointers.

The filters can be used to perform following actions:

- convert block group profiles (filter convert)

- make block group usage more compact (filter usage)

- perform actions only on a given device (filters devid, drange)

The filters can be applied to a combination of block group types (data, metadata, system). Note that changing only the system type needs the force option. Otherwise system gets automatically converted whenever metadata profile is converted.

When metadata redundancy is reduced (e.g. from RAID1 to single) the force option is also required and it is noted in system log.

NOTE:

The balance operation needs enough work space, i.e. space that is completely unused in the filesystem, otherwise this may lead to ENOSPC reports. See the section ENOSPC for more details.

## COMPATIBILITY
NOTE:

The balance subcommand also exists under the btrfs filesystem namespace. This still works for backward compatibility but is deprecated and should not be used any more.

NOTE:

A short syntax btrfs balance <path> works due to backward compatibility but is deprecated and should not be used any more. Use btrfs balance start command instead.

## PERFORMANCE IMPLICATIONS
Balancing operations are very IO intensive and can also be quite CPU intensive, impacting other ongoing filesystem operations. Typically large amounts of data are copied from one location to another, with corresponding metadata updates.

Depending upon the block group layout, it can also be seek heavy. Performance on rotational devices is noticeably worse compared to SSDs or fast arrays.

## SUBCOMMAND
cancel <path>

cancels a running or paused balance, the command will block and wait until the current block group being processed completes Since kernel 5.7 the response time of the cancellation is significantly improved, on older kernels it might take a long time until currently processed chunk is completely finished.

pause <path>

pause running balance operation, this will store the state of the balance progress and used filters to the filesystem

resume <path>

resume interrupted balance, the balance status must be stored on the filesystem from previous run, e.g. after it was paused or forcibly interrupted and mounted again with skip_balance

start [options] <path>

start the balance operation according to the specified filters, without any filters the data and metadata from the whole filesystem are moved. The process runs in the foreground. NOTE:

The balance command without filters will basically move everything in the filesystem to a new physical location on devices (i.e. it does not affect the logical properties of file extents like offsets within files and extent sharing). The run time is potentially very long, depending on the filesystem size. To prevent starting a full balance by accident, the user is warned and has a few seconds to cancel the operation before it starts. The warning and delay can be skipped with --full-balance option.

Please note that the filters must be written together with the -d, -m and -s options, because they're optional and bare -d and -m also work and mean no filters.

NOTE:

When the target profile for conversion filter is raid5 or raid6, there's a safety timeout of 10 seconds to warn users about the status of the feature

Options

-d[<filters>]

act on data block groups, see FILTERS section for details about filters

-m[<filters>]

act on metadata chunks, see FILTERS section for details about filters

-s[<filters>]

act on system chunks (requires -f), see FILTERS section for details about filters.

-f

force a reduction of metadata integrity, e.g. when going from raid1 to single, or skip safety timeout when the target conversion profile is raid5 or raid6

--background|--bg

run the balance operation asynchronously in the background, uses fork(2) to start the process that calls the kernel ioctl

--enqueue

wait if there's another exclusive operation running, otherwise continue

-v

(deprecated) alias for global '-v' option

status [-v] <path>

Show status of running or paused balance. Options

-v

(deprecated) alias for global -v option

## FILTERS
From kernel 3.3 onwards, btrfs balance can limit its action to a subset of the whole filesystem, and can be used to change the replication configuration (e.g. moving data from single to RAID1). This functionality is accessed through the -d, -m or -s options to btrfs balance start, which filter on data, metadata and system blocks respectively.

A filter has the following structure: type[=params][,type=...]

The available types are:

profiles=<profiles>

Balances only block groups with the given profiles. Parameters are a list of profile names separated by "|" (pipe).

usage=<percent>, usage=<range>

Balances only block groups with usage under the given percentage. The value of 0 is allowed and will clean up completely unused block groups, this should not require any new work space allocated. You may want to use usage=0 in case balance is returning ENOSPC and your filesystem is not too full. The argument may be a single value or a range. The single value N means at most N percent used, equivalent to ..N range syntax. Kernels prior to 4.4 accept only the single value format. The minimum range boundary is inclusive, maximum is exclusive.

devid=<id>

Balances only block groups which have at least one chunk on the given device. To list devices with ids use btrfs filesystem show.

drange=<range>

Balance only block groups which overlap with the given byte range on any device. Use in conjunction with devid to filter on a specific device. The parameter is a range specified as start..end.

vrange=<range>

Balance only block groups which overlap with the given byte range in the filesystem's internal virtual address space. This is the address space that most reports from btrfs in the kernel log use. The parameter is a range specified as start..end.

convert=<profile>

Convert each selected block group to the given profile name identified by parameters. NOTE:

Starting with kernel 4.5, the data chunks can be converted to/from the DUP profile on a single device.

NOTE:

Starting with kernel 4.6, all profiles can be converted to/from DUP on multi-device filesystems.

limit=<number>, limit=<range>

Process only given number of chunks, after all filters are applied. This can be used to specifically target a chunk in connection with other filters (drange, vrange) or just simply limit the amount of work done by a single balance run. The argument may be a single value or a range. The single value N means at most N chunks, equivalent to ..N range syntax. Kernels prior to 4.4 accept only the single value format. The range minimum and maximum are inclusive.

stripes=<range>

Balance only block groups which have the given number of stripes. The parameter is a range specified as start..end. Makes sense for block group profiles that utilize striping, i.e. RAID0/10/5/6. The range minimum and maximum are inclusive.

soft

Takes no parameters. Only has meaning when converting between profiles. When doing convert from one profile to another and soft mode is on, chunks that already have the target profile are left untouched. This is useful e.g. when half of the filesystem was converted earlier but got cancelled. The soft mode switch is (like every other filter) per-type. For example, this means that we can convert metadata chunks the "hard" way while converting data chunks selectively with soft switch.

Profile names, used in profiles and convert are one of: raid0, raid1, raid1c3, raid1c4, raid10, raid5, raid6, dup, single. The mixed data/metadata profiles can be converted in the same way, but it's conversion between mixed and non-mixed is not implemented. For the constraints of the profiles please refer to mkfs.btrfs(8), section PROFILES.

## ENOSPC
The way balance operates, it usually needs to temporarily create a new block group and move the old data there, before the old block group can be removed. For that it needs the work space, otherwise it fails for ENOSPC reasons. This is not the same ENOSPC as if the free space is exhausted. This refers to the space on the level of block groups, which are bigger parts of the filesystem that contain many file extents.

The free work space can be calculated from the output of the btrfs filesystem show command:

```
Label: 'BTRFS'  uuid: 8a9d72cd-ead3-469d-b371-9c7203276265

        Total devices 2 FS bytes used 77.03GiB

        devid    1 size 53.90GiB used 51.90GiB path /dev/sdc2

        devid    2 size 53.90GiB used 51.90GiB path /dev/sde1
```

size - used = free work space

53.90GiB - 51.90GiB = 2.00GiB

An example of a filter that does not require workspace is usage=0. This will scan through all unused block groups of a given type and will reclaim the space. After that it might be possible to run other filters.

CONVERSIONS ON MULTIPLE DEVICES

Conversion to profiles based on striping (RAID0, RAID5/6) require the work space on each device. An interrupted balance may leave partially filled block groups that consume the work space.

## EXAMPLES
A more comprehensive example when going from one to multiple devices, and back, can be found in section TYPICAL USECASES of btrfs-device(8).

### MAKING BLOCK GROUP LAYOUT MORE COMPACT
The layout of block groups is not normally visible; most tools report only summarized numbers of free or used space, but there are still some hints provided.

Let's use the following real life example and start with the output:

```
$ btrfs filesystem df /path
Data, single: total=75.81GiB, used=64.44GiB
System, RAID1: total=32.00MiB, used=20.00KiB
Metadata, RAID1: total=15.87GiB, used=8.84GiB
GlobalReserve, single: total=512.00MiB, used=0.00B
```

Roughly calculating for data, 75G - 64G = 11G, the used/total ratio is about 85%. How can we can interpret that:

- chunks are filled by 85% on average, i.e. the usage filter with anything smaller than 85 will likely not affect anything

- in a more realistic scenario, the space is distributed unevenly, we can assume there are completely used chunks and the remaining are partially filled

Compacting the layout could be used on both. In the former case it would spread data of a given chunk to the others and removing it. Here we can estimate that roughly 850 MiB of data have to be moved (85% of a 1 GiB chunk).

In the latter case, targeting the partially used chunks will have to move less data and thus will be faster. A typical filter command would look like:

```
# btrfs balance start -dusage=50 /path
Done, had to relocate 2 out of 97 chunks
$ btrfs filesystem df /path
Data, single: total=74.03GiB, used=64.43GiB
System, RAID1: total=32.00MiB, used=20.00KiB
Metadata, RAID1: total=15.87GiB, used=8.84GiB
GlobalReserve, single: total=512.00MiB, used=0.00B
```

As you can see, the total amount of data is decreased by just 1 GiB, which is an expected result. Let's see what will happen when we increase the estimated usage filter.

```
# btrfs balance start -dusage=85 /path
Done, had to relocate 13 out of 95 chunks
$ btrfs filesystem df /path
Data, single: total=68.03GiB, used=64.43GiB
System, RAID1: total=32.00MiB, used=20.00KiB
Metadata, RAID1: total=15.87GiB, used=8.85GiB
GlobalReserve, single: total=512.00MiB, used=0.00B
```

Now the used/total ratio is about 94% and we moved about 74G - 68G = 6G of data to the remaining block groups, i.e. the 6GiB are now free of filesystem structures, and can be reused for new data or metadata block groups.

We can do a similar exercise with the metadata block groups, but this should not typically be necessary, unless the used/total ratio is really off. Here the ratio is roughly 50% but the difference as an absolute number is "a few gigabytes", which can be considered normal for a workload with snapshots or reflinks updated frequently.

```
# btrfs balance start -musage=50 /path
Done, had to relocate 4 out of 89 chunks
$ btrfs filesystem df /path
Data, single: total=68.03GiB, used=64.43GiB
System, RAID1: total=32.00MiB, used=20.00KiB
Metadata, RAID1: total=14.87GiB, used=8.85GiB
GlobalReserve, single: total=512.00MiB, used=0.00B
```

Just 1 GiB decrease, which possibly means there are block groups with good utilization. Making the metadata layout more compact would in turn require updating more metadata structures, i.e. lots of IO. As running out of metadata space is a more severe problem, it's not necessary to keep the utilization ratio too high. For the purpose of this example, let's see the effects of further compaction:

```
# btrfs balance start -musage=70 /path
Done, had to relocate 13 out of 88 chunks
$ btrfs filesystem df .
Data, single: total=68.03GiB, used=64.43GiB
System, RAID1: total=32.00MiB, used=20.00KiB
Metadata, RAID1: total=11.97GiB, used=8.83GiB
GlobalReserve, single: total=512.00MiB, used=0.00B
```

### GETTING RID OF COMPLETELY UNUSED BLOCK GROUPS
Normally the balance operation needs a work space, to temporarily move the data before the old block groups gets removed. If there's no work space, it ends with no space left.

There's a special case when the block groups are completely unused, possibly left after removing lots of files or deleting snapshots. Removing empty block groups is automatic since 3.18. The same can be achieved manually with a notable exception that this operation does not require the work space. Thus it can be used to reclaim unused block groups to make it available.

```
# btrfs balance start -dusage=0 /path
```

This should lead to decrease in the total numbers in the btrfs filesystem df output.

## EXIT STATUS
Unless indicated otherwise below, all btrfs balance subcommands return a zero exit status if they succeed, and non zero in case of failure.

The pause, cancel, and resume subcommands exit with a status of 2 if they fail because a balance operation was not running.

The status subcommand exits with a status of 0 if a balance operation is not running, 1 if the command-line usage is incorrect or a balance operation is still running, and 2 on other errors.

## AVAILABILITY
btrfs is part of btrfs-progs. Please refer to the documentation at https://btrfs.readthedocs.io.

## SEE ALSO
mkfs.btrfs(8), btrfs-device(8)


btrfs-check

title: btrfs-check(8)

summary: check or repair a btrfs filesystem

text:
# btrfs-check(8)

## NAME
btrfs-check - check or repair a btrfs filesystem

## SYNOPSIS
btrfs check [options] <device>

## DESCRIPTION
The filesystem checker is used to verify structural integrity of a filesystem and attempt to repair it if requested. It is recommended to unmount the filesystem prior to running the check, but it is possible to start checking a mounted filesystem (see --force).

By default, btrfs check will not modify the device but you can reaffirm that by the option --readonly.

btrfsck is an alias of btrfs check command and is now deprecated.

WARNING:

Do not use --repair unless you are advised to do so by a developer or an experienced user, and then only after having accepted that no fsck successfully repair all types of filesystem corruption. E.g. some other software or hardware bugs can fatally damage a volume.

The structural integrity check verifies if internal filesystem objects or data structures satisfy the constraints, point to the right objects or are correctly connected together.

There are several cross checks that can detect wrong reference counts of shared extents, backreferences, missing extents of inodes, directory and inode connectivity etc.

The amount of memory required can be high, depending on the size of the filesystem, similarly the run time. Check the modes that can also affect that.

## SAFE OR ADVISORY OPTIONS
-b|--backup

use the first valid set of backup roots stored in the superblock This can be combined with --super if some of the superblocks are damaged.

--check-data-csum

verify checksums of data blocks This expects that the filesystem is otherwise OK, and is basically an offline scrub that does not repair data from spare copies.

--chunk-root <bytenr>

use the given offset bytenr for the chunk tree root

-E|--subvol-extents <subvolid>

show extent state for the given subvolume

-p|--progress

indicate progress at various checking phases

-Q|--qgroup-report

verify qgroup accounting and compare against filesystem accounting

-r|--tree-root <bytenr>

use the given offset 'bytenr' for the tree root

--readonly

(default) run in read-only mode, this option exists to calm potential panic when users are going to run the checker

-s|--super <N>

use Nth superblock copy, valid values are 0, 1 or 2 if the respective superblock offset is within the device size This can be used to use a different starting point if some of the primary superblock is damaged.

--clear-space-cache v1|v2

completely remove the free space cache of the given version See also the clear_cache mount option.

--clear-ino-cache

remove leftover items pertaining to the deprecated inode map feature

## DANGEROUS OPTIONS
--repair

enable the repair mode and attempt to fix problems where possible NOTE:

There's a warning and 10 second delay when this option is run without --force to give users a chance to think twice before running repair, the warnings in documentation have shown to be insufficient.

--init-csum-tree

create a new checksum tree and recalculate checksums in all files WARNING:

Do not blindly use this option to fix checksum mismatch problems.

--init-extent-tree

build the extent tree from scratch WARNING:

Do not use unless you know what you're doing.

--mode <MODE>

select mode of operation regarding memory and IO The MODE can be one of:

original

The metadata are read into memory and verified, thus the requirements are high on large filesystems and can even lead to out-of-memory conditions. The possible workaround is to export the block device over network to a machine with enough memory.

lowmem

This mode is supposed to address the high memory consumption at the cost of increased IO when it needs to re-read blocks. This may increase run time.

NOTE:

lowmem mode does not work with --repair yet, and is still considered experimental.

--force

allow work on a mounted filesystem and skip mount checks. Note that this should work fine on a quiescent or read-only mounted filesystem but may crash if the device is changed externally, e.g. by the kernel module. NOTE:

It is possible to run with --repair but on a mounted filesystem that will most likely lead to a corruption unless the filesystem is in a quiescent state which may not be possible to guarantee.

This option also skips the delay and warning in the repair mode (see --repair).

## EXIT STATUS
btrfs check returns a zero exit status if it succeeds. Non zero is returned in case of failure.

## AVAILABILITY
btrfs is part of btrfs-progs. Please refer to the documentation at https://btrfs.readthedocs.io.

## SEE ALSO
mkfs.btrfs(8), btrfs-scrub(8), btrfs-rescue(8)


btrfs-convert

title: btrfs-convert(8)

text:
# btrfs-convert(8)

## NAME
btrfs-convert - convert from ext2/3/4 or reiserfs filesystem to btrfs in-place

## SYNOPSIS
btrfs-convert [options] <device>

## DESCRIPTION
The btrfs-convert tool can be used to convert existing source filesystem image to a btrfs filesystem in-place. The original filesystem image is accessible in subvolume named like ext2_saved as file image.

Supported filesystems:

- ext2, ext3, ext4 -- original feature, always built in

- reiserfs -- since version 4.13, optionally built, requires libreiserfscore 3.6.27

- ntfs -- external tool https://github.com/maharmstone/ntfs2btrfs

The list of supported source filesystem by a given binary is listed at the end of help (option --help).

WARNING:

If you are going to perform rollback to the original filesystem, you should not execute btrfs balance command on the converted filesystem. This will change the extent layout and make btrfs-convert unable to rollback.

The conversion utilizes free space of the original filesystem. The exact estimate of the required space cannot be foretold. The final btrfs metadata might occupy several gigabytes on a hundreds-gigabyte filesystem.

If the ability to rollback is no longer important, the it is recommended to perform a few more steps to transition the btrfs filesystem to a more compact layout. This is because the conversion inherits the original data blocks' fragmentation, and also because the metadata blocks are bound to the original free space layout.

Due to different constraints, it is only possible to convert filesystems that have a supported data block size (i.e. the same that would be valid for mkfs.btrfs). This is typically the system page size (4KiB on x86_64 machines).

BEFORE YOU START

The source filesystem must be clean, e.g. no journal to replay or no repairs needed. The respective fsck utility must be run on the source filesystem prior to conversion. Please refer to the manual pages in case you encounter problems.

For ext2/3/4:

```
# e2fsck -fvy /dev/sdx
```

For reiserfs:

```
# reiserfsck -fy /dev/sdx
```

Skipping that step could lead to incorrect results on the target filesystem, but it may work.

REMOVE THE ORIGINAL FILESYSTEM METADATA

By removing the subvolume named like ext2_saved or reiserfs_saved, all metadata of the original filesystem will be removed:

```
# btrfs subvolume delete /mnt/ext2_saved
```

At this point it is not possible to do a rollback. The filesystem is usable but may be impacted by the fragmentation inherited from the original filesystem.

MAKE FILE DATA MORE CONTIGUOUS

An optional but recommended step is to run defragmentation on the entire filesystem. This will attempt to make file extents more contiguous.

```
# btrfs filesystem defrag -v -r -f -t 32M /mnt/btrfs
```

Verbose recursive defragmentation (-v, -r), flush data per-file (-f) with target extent size 32MiB (-t).

ATTEMPT TO MAKE BTRFS METADATA MORE COMPACT

Optional but recommended step.

The metadata block groups after conversion may be smaller than the default size (256MiB or 1GiB). Running a balance will attempt to merge the block groups. This depends on the free space layout (and fragmentation) and may fail due to lack of enough work space. This is a soft error leaving the filesystem usable but the block group layout may remain unchanged.

Note that balance operation takes a lot of time, please see also btrfs-balance(8).

```
# btrfs balance start -m /mnt/btrfs
```

## OPTIONS
--csum <type>, --checksum <type>

Specify the checksum algorithm. Default is crc32c. Valid values are crc32c, xxhash, sha256 or blake2. To mount such filesystem kernel must support the checksums as well.

-d|--no-datasum

disable data checksum calculations and set the NODATASUM file flag, this can speed up the conversion

-i|--no-xattr

ignore xattrs and ACLs of files

-n|--no-inline

disable inlining of small files to metadata blocks, this will decrease the metadata consumption and may help to convert a filesystem with low free space

-N|--nodesize <SIZE>

set filesystem nodesize, the tree block size in which btrfs stores its metadata. The default value is 16KiB (16384) or the page size, whichever is bigger. Must be a multiple of the sectorsize, but not larger than 65536. See mkfs.btrfs(8) for more details.

-r|--rollback

rollback to the original ext2/3/4 filesystem if possible

-l|--label <LABEL>

set filesystem label during conversion

-L|--copy-label

use label from the converted filesystem

-O|--features <feature1>[,<feature2>...]

A list of filesystem features enabled the at time of conversion. Not all features are supported by old kernels. To disable a feature, prefix it with ^. Description of the features is in section FILESYSTEM FEATURES of mkfs.btrfs(8). To see all available features that btrfs-convert supports run:

```
btrfs-convert -O list-all
```

-p|--progress

show progress of conversion (a heartbeat indicator and number of inodes processed), on by default

--no-progress

disable progress and show only the main phases of conversion

--uuid <SPEC>

set the FSID of the new filesystem based on 'SPEC':

- new - (default) generate UUID for the FSID of btrfs

- copy - copy UUID from the source filesystem

- UUID - a conforming UUID value, the 36 byte string representation

## EXIT STATUS
btrfs-convert will return 0 if no error happened. If any problems happened, 1 will be returned.

## SEE ALSO
mkfs.btrfs(8)


btrfs-device

title: btrfs-device(8)

summary: manage devices of btrfs filesystems

text:
# btrfs-device(8)

## NAME
btrfs-device - manage devices of btrfs filesystems

## SYNOPSIS
btrfs device <subcommand> <args>

## DESCRIPTION
The btrfs device command group is used to manage devices of the btrfs filesystems.

## SUBCOMMAND
add [-Kf] <device> [<device>...] <path>

Add device(s) to the filesystem identified by path. If applicable, a whole device discard (TRIM) operation is performed prior to adding the device. A device with existing filesystem detected by blkid(8) will prevent device addition and has to be forced. Alternatively the filesystem can be wiped from the device using e.g. the wipefs(8) tool.

The operation is instant and does not affect existing data. The operation merely adds the device to the filesystem structures and creates some block groups headers.

Options

-K|--nodiscard

do not perform discard (TRIM) by default

-f|--force

force overwrite of existing filesystem on the given disk(s)

--enqueue

wait if there's another exclusive operation running, otherwise continue

remove [options] <device>|<devid> [<device>|<devid>...] <path>

Remove device(s) from a filesystem identified by <path> Device removal must satisfy the profile constraints, otherwise the command fails. The filesystem must be converted to profile(s) that would allow the removal. This can typically happen when going down from 2 devices to 1 and using the RAID1 profile. See the section TYPICAL USECASES.

The operation can take long as it needs to move all data from the device.

It is possible to delete the device that was used to mount the filesystem. The device entry in the mount table will be replaced by another device name with the lowest device id.

If the filesystem is mounted in degraded mode (-o degraded), special term missing can be used for device. In that case, the first device that is described by the filesystem metadata, but not present at the mount time will be removed.

NOTE:

In most cases, there is only one missing device in degraded mode, otherwise mount fails. If there are two or more devices missing (e.g. possible in RAID6), you need specify missing as many times as the number of missing devices to remove all of them.

Options

--enqueue

wait if there's another exclusive operation running, otherwise continue

delete <device>|<devid> [<device>|<devid>...] <path>

Alias of remove kept for backward compatibility

replace <command> [options] <path>

Alias of whole command group btrfs replace for convenience. See btrfs-replace(8).

ready <device>

Wait until all devices of a multiple-device filesystem are scanned and registered within the kernel module. This is to provide a way for automatic filesystem mounting tools to wait before the mount can start. The device scan is only one of the preconditions and the mount can fail for other reasons. Normal users usually do not need this command and may safely ignore it.

scan [options] [<device> [<device>...]]

Scan devices for a btrfs filesystem and register them with the kernel module. This allows mounting multiple-device filesystem by specifying just one from the whole group. If no devices are passed, all block devices that blkid reports to contain btrfs are scanned.

The options --all-devices or -d can be used as a fallback in case blkid is not available. If used, behavior is the same as if no devices are passed.

The command can be run repeatedly. Devices that have been already registered remain as such. Reloading the kernel module will drop this information. There's an alternative way of mounting multiple-device filesystem without the need for prior scanning. See the mount option device.

Options

-d|--all-devices

Enumerate and register all devices, use as a fallback in case blkid is not available.

-u|--forget

Unregister a given device or all stale devices if no path is given, the device must be unmounted otherwise it's an error.

stats [options] <path>|<device>

Read and print the device IO error statistics for all devices of the given filesystem identified by path or for a single device>. The filesystem must be mounted. See section *DEVICE STATS for more information about the reported statistics and the meaning. Options

-z|--reset

Print the stats and reset the values to zero afterwards.

-c|--check

Check if the stats are all zeros and return 0 if it is so. Set bit 6 of the return code if any of the statistics is no-zero. The error values is 65 if reading stats from at least one device failed, otherwise it's 64.

-T

Print stats in a tabular form, devices as rows and stats as columns

usage [options] <path> [<path>...]::

Show detailed information about internal allocations on devices. The level of detail can differ if the command is run under a regular or the root user (due to use of restricted ioctls). The first example below is for normal user (warning included) and the next one with root on the same filesystem:

```
WARNING: cannot read detailed chunk info, per-device usage will not be shown, run as root
/dev/sdc1, ID: 1

   Device size:           931.51GiB

   Device slack:              0.00B

   Unallocated:           931.51GiB
/dev/sdc1, ID: 1

   Device size:           931.51GiB

   Device slack:              0.00B

   Data,single:           641.00GiB

   Data,RAID0/3:            1.00GiB

   Metadata,single:        19.00GiB

   System,single:          32.00MiB

   Unallocated:           271.48GiB
```

- Device size -- size of the device as seen by the filesystem (may be different than actual device size)

- Device slack -- portion of device not used by the filesystem but still available in the physical space provided by the device, e.g. after a device shrink

- Data,single, Metadata,single, System,single -- in general, list of block group type (Data, Metadata, System) and profile (single, RAID1, ...) allocated on the device

- Data,RAID0/3 -- in particular, striped profiles RAID0/RAID10/RAID5/RAID6 with the number of devices on which the stripes are allocated, multiple occurrences of the same profile can appear in case a new device has been added and all new available stripes have been used for writes

- Unallocated -- remaining space that the filesystem can still use for new block groups

Options

-b|--raw

raw numbers in bytes, without the B suffix

-h|--human-readable

print human friendly numbers, base 1024, this is the default

-H

print human friendly numbers, base 1000

--iec

select the 1024 base for the following options, according to the IEC standard

--si

select the 1000 base for the following options, according to the SI standard

-k|--kbytes

show sizes in KiB, or kB with --si

-m|--mbytes

show sizes in MiB, or MB with --si

-g|--gbytes

show sizes in GiB, or GB with --si

-t|--tbytes

show sizes in TiB, or TB with --si

If conflicting options are passed, the last one takes precedence.

## DEVICE STATS
The device stats keep persistent record of several error classes related to doing IO. The current values are printed at mount time and updated during filesystem lifetime or from a scrub run.

```
$ btrfs device stats /dev/sda3
[/dev/sda3].write_io_errs   0
[/dev/sda3].read_io_errs    0
[/dev/sda3].flush_io_errs   0
[/dev/sda3].corruption_errs 0
[/dev/sda3].generation_errs 0
```

write_io_errs

Failed writes to the block devices, means that the layers beneath the filesystem were not able to satisfy the write request.

read_io_errors

Read request analogy to write_io_errs.

flush_io_errs

Number of failed writes with the FLUSH flag set. The flushing is a method of forcing a particular order between write requests and is crucial for implementing crash consistency. In case of btrfs, all the metadata blocks must be permanently stored on the block device before the superblock is written.

corruption_errs

A block checksum mismatched or a corrupted metadata header was found.

generation_errs

The block generation does not match the expected value (e.g. stored in the parent node).

Since kernel 5.14 the device stats are also available in textual form in /sys/fs/btrfs/FSID/devinfo/DEVID/error_stats.

## EXIT STATUS
btrfs device returns a zero exit status if it succeeds. Non zero is returned in case of failure.

If the -c option is used, btrfs device stats will add 64 to the exit status if any of the error counters is non-zero.

## AVAILABILITY
btrfs is part of btrfs-progs. Please refer to the documentation at https://btrfs.readthedocs.io.

## SEE ALSO
btrfs-balance(8) btrfs-device(8), btrfs-replace(8), mkfs.btrfs(8),


btrfs-filesystem

title: btrfs-filesystem(8)

text:
# btrfs-filesystem(8)

## NAME
btrfs-filesystem - command group that primarily does work on the whole filesystems

## SYNOPSIS
btrfs filesystem <subcommand> <args>

## DESCRIPTION
btrfs filesystem is used to perform several whole filesystem level tasks, including all the regular filesystem operations like resizing, space stats, label setting/getting, and defragmentation. There are other whole filesystem tasks like scrub or balance that are grouped in separate commands.

## SUBCOMMAND
df [options] <path>

Show a terse summary information about allocation of block group types of a given mount point. The original purpose of this command was a debugging helper. The output needs to be further interpreted and is not suitable for quick overview. An example with description:

- device size: 1.9TiB, one device, no RAID

- filesystem size: 1.9TiB

- created with: mkfs.btrfs -d single -m single

```
$ btrfs filesystem df /path
Data, single: total=1.15TiB, used=1.13TiB
System, single: total=32.00MiB, used=144.00KiB
Metadata, single: total=12.00GiB, used=6.45GiB
GlobalReserve, single: total=512.00MiB, used=0.00B
```

- Data, System and Metadata are separate block group types. GlobalReserve is an artificial and internal emergency space, see below.

- single -- the allocation profile, defined at mkfs time

- total -- sum of space reserved for all allocation profiles of the given type, i.e. all Data/single. Note that it's not total size of filesystem.

- used -- sum of used space of the above, i.e. file extents, metadata blocks

GlobalReserve is an artificial and internal emergency space. It is used e.g. when the filesystem is full. Its total size is dynamic based on the filesystem size, usually not larger than 512MiB, used may fluctuate.

The GlobalReserve is a portion of Metadata. In case the filesystem metadata is exhausted, GlobalReserve/total + Metadata/used = Metadata/total. Otherwise there appears to be some unused space of Metadata.

Options

-b|--raw

raw numbers in bytes, without the B suffix

-h|--human-readable

print human friendly numbers, base 1024, this is the default

-H

print human friendly numbers, base 1000

--iec

select the 1024 base for the following options, according to the IEC standard

--si

select the 1000 base for the following options, according to the SI standard

-k|--kbytes

show sizes in KiB, or kB with --si

-m|--mbytes

show sizes in MiB, or MB with --si

-g|--gbytes

show sizes in GiB, or GB with --si

-t|--tbytes

show sizes in TiB, or TB with --si

If conflicting options are passed, the last one takes precedence.

defragment [options] <file>|<dir> [<file>|<dir>...]

Defragment file data on a mounted filesystem. Requires kernel 2.6.33 and newer. If -r is passed, files in dir will be defragmented recursively (not descending to subvolumes, mount points and directory symlinks). The start position and the number of bytes to defragment can be specified by start and length using -s and -l options below. Extents bigger than value given by -t will be skipped, otherwise this value is used as a target extent size, but is only advisory and may not be reached if the free space is too fragmented. Use 0 to take the kernel default, which is 256KiB but may change in the future. You can also turn on compression in defragment operations.

WARNING:

Defragmenting with Linux kernel versions < 3.9 or ≥ 3.14-rc2 as well as with Linux stable kernel versions ≥ 3.10.31, ≥ 3.12.12 or ≥ 3.13.4 will break up the reflinks of COW data (for example files copied with cp --reflink, snapshots or de-duplicated data). This may cause considerable increase of space usage depending on the broken up reflinks.

NOTE:

Directory arguments without -r do not defragment files recursively but will defragment certain internal trees (extent tree and the subvolume tree). This has been confusing and could be removed in the future.

For start, len, size it is possible to append units designator: K, M, G, T, P, or E, which represent KiB, MiB, GiB, TiB, PiB, or EiB, respectively (case does not matter).

Options

-c[<algo>]

compress file contents while defragmenting. Optional argument selects the compression algorithm, zlib (default), lzo or zstd. Currently it's not possible to select no compression. See also section EXAMPLES.

-r

defragment files recursively in given directories, does not descend to subvolumes or mount points

-f

flush data for each file before going to the next file. This will limit the amount of dirty data to current file, otherwise the amount accumulates from several files and will increase system load. This can also lead to ENOSPC if there's too much dirty data to write and it's not possible to make the reservations for the new data (i.e. how the COW design works).

-s <start>[kKmMgGtTpPeE]

defragmentation will start from the given offset, default is beginning of a file

-l <len>[kKmMgGtTpPeE]

defragment only up to len bytes, default is the file size

-t <size>[kKmMgGtTpPeE]

target extent size, do not touch extents bigger than size, default: 32MiB The value is only advisory and the final size of the extents may differ, depending on the state of the free space and fragmentation or other internal logic. Reasonable values are from tens to hundreds of megabytes.

-v

(deprecated) alias for global -v option

du [options] <path> [<path>..]

Calculate disk usage of the target files using FIEMAP. For individual files, it will report a count of total bytes, and exclusive (not shared) bytes. We also calculate a 'set shared' value which is described below. Each argument to btrfs filesystem du will have a set shared value calculated for it. We define each set as those files found by a recursive search of an argument (recursion descends to subvolumes but not mount points). The set shared value then is a sum of all shared space referenced by the set.

set shared takes into account overlapping shared extents, hence it isn't as simple as adding up shared extents.

Options

-s|--summarize

display only a total for each argument

--raw

raw numbers in bytes, without the B suffix.

--human-readable

print human friendly numbers, base 1024, this is the default

--iec

select the 1024 base for the following options, according to the IEC standard.

--si

select the 1000 base for the following options, according to the SI standard.

--kbytes

show sizes in KiB, or kB with --si.

--mbytes

show sizes in MiB, or MB with --si.

--gbytes

show sizes in GiB, or GB with --si.

--tbytes

show sizes in TiB, or TB with --si.

label [<device>|<mountpoint>] [<newlabel>]

Show or update the label of a filesystem. This works on a mounted filesystem or a filesystem image. The newlabel argument is optional. Current label is printed if the argument is omitted.

NOTE:

The maximum allowable length shall be less than 256 chars and must not contain a newline. The trailing newline is stripped automatically.

mkswapfile [-s size] file

Create a new file that's suitable and formatted as a swapfile. Default size is 2GiB, fixed page size 4KiB, minimum size is 40KiB. A swapfile must be created in a specific way: NOCOW and preallocated. Subvolume containing a swapfile cannot be snapshotted and blocks of an activated swapfile cannot be balanced.

Swapfile creation can be achieved by standalone commands too. Activation needs to be done by command swapon(8). See also command btrfs inspect-internal map-swapfile and the Swapfile feature description.

NOTE:

The command is a simplified version of 'mkswap', if you want to set label, page size, or other parameters please use 'mkswap' proper.

Options

-s|--size SIZE

Create swapfile of a given size SIZE (accepting k/m/g/e/p suffix).

-U|--uuid UUID

specify UUID to use, or a special value: clear (all zeros), random, time (time-based random)

resize [options] [<devid>:][+/-]<size>[kKmMgGtTpPeE]|[<devid>:]max <path>

Resize a mounted filesystem identified by path. A particular device can be resized by specifying a devid. WARNING:

If path is a file containing a BTRFS image then resize does not work as expected and does not resize the image. This would resize the underlying filesystem instead.

The devid can be found in the output of btrfs filesystem show and defaults to 1 if not specified. The size parameter specifies the new size of the filesystem. If the prefix + or - is present the size is increased or decreased by the quantity size. If no units are specified, bytes are assumed for size. Optionally, the size parameter may be suffixed by one of the following unit designators: K, M, G, T, P, or E, which represent KiB, MiB, GiB, TiB, PiB, or EiB, respectively (case does not matter).

If max is passed, the filesystem will occupy all available space on the device respecting devid (remember, devid 1 by default).

The resize command does not manipulate the size of underlying partition. If you wish to enlarge/reduce a filesystem, you must make sure you can expand the partition before enlarging the filesystem and shrink the partition after reducing the size of the filesystem. This can done using fdisk(8) or parted(8) to delete the existing partition and recreate it with the new desired size. When recreating the partition make sure to use the same starting partition offset as before.

Growing is usually instant as it only updates the size. However, shrinking could take a long time if there are data in the device area that's beyond the new end. Relocation of the data takes time.

See also section EXAMPLES.

Options

--enqueue

wait if there's another exclusive operation running, otherwise continue

show [options] [<path>|<uuid>|<device>|<label>]

Show the btrfs filesystem with some additional info about devices and space allocation. If no option none of path/uuid/device/label is passed, information about all the BTRFS filesystems is shown, both mounted and unmounted.

Options

-m|--mounted

probe kernel for mounted BTRFS filesystems

-d|--all-devices

scan all devices under /dev, otherwise the devices list is extracted from the /proc/partitions file. This is a fallback option if there's no device node manager (like udev) available in the system.

--raw

raw numbers in bytes, without the B suffix

--human-readable

print human friendly numbers, base 1024, this is the default

--iec

select the 1024 base for the following options, according to the IEC standard

--si

select the 1000 base for the following options, according to the SI standard

--kbytes

show sizes in KiB, or kB with --si

--mbytes

show sizes in MiB, or MB with --si

--gbytes

show sizes in GiB, or GB with --si

--tbytes

show sizes in TiB, or TB with --si

sync <path>

Force a sync of the filesystem at path, similar to the sync(1) command. In addition, it starts cleaning of deleted subvolumes. To wait for the subvolume deletion to complete use the btrfs subvolume sync command.

usage [options] <path> [<path>...]

Show detailed information about internal filesystem usage. This is supposed to replace the btrfs filesystem df command in the long run. The level of detail can differ if the command is run under a regular or the root user (due to use of restricted ioctl). For both there's a summary section with information about space usage:

```
$ btrfs filesystem usage /path
WARNING: cannot read detailed chunk info, RAID5/6 numbers will be incorrect, run as root
Overall:

    Device size:                   1.82TiB

    Device allocated:              1.17TiB

    Device unallocated:          669.99GiB

    Device missing:                  0.00B

    Device slack:                  1.00GiB

    Used:                          1.14TiB

    Free (estimated):            692.57GiB      (min: 692.57GiB)

    Free (statfs, df)            692.57GiB

    Data ratio:                       1.00

    Metadata ratio:                   1.00

    Global reserve:              512.00MiB      (used: 0.00B)

    Multiple profiles:                  no
```

- Device size -- sum of raw device capacity available to the filesystem, note that this may not be the same as the total device size (the difference is accounted as slack)

- Device allocated -- sum of total space allocated for data/metadata/system profiles, this also accounts space reserved but not yet used for extents

- Device unallocated -- the remaining unallocated space for future allocations (difference of the above two numbers)

- Device missing -- sum of capacity of all missing devices

- Device slack -- sum of slack space on all devices (difference between entire device size and the space occupied by filesystem)

- Used -- sum of the used space of data/metadata/system profiles, not including the reserved space

- Free (estimated) -- approximate size of the remaining free space usable for data, including currently allocated space and estimating the usage of the unallocated space based on the block group profiles, the min is the lower bound of the estimate in case multiple profiles are present

- Free (statfs, df) -- the amount of space available for data as reported by the statfs syscall, also returned as Avail in the output of df. The value is calculated in a different way and may not match the estimate in some cases (e.g. multiple profiles).

- Data ratio -- ratio of total space for data including redundancy or parity to the effectively usable data space, e.g. single is 1.0, RAID1 is 2.0 and for RAID5/6 it depends on the number of devices

- Metadata ratio -- ditto, for metadata

- Global reserve -- portion of metadata currently used for global block reserve, used for emergency purposes (like deletion on a full filesystem)

- Multiple profiles -- what block group types (data, metadata) have more than one profile (single, raid1, ...), see btrfs(5) section FILESYSTEMS WITH MULTIPLE BLOCK GROUP PROFILES.

And on a zoned filesystem there are two more lines in the Device section:

```
Device zone unusable:          5.13GiB
Device zone size:            256.00MiB
```

- Device zone unusable -- sum of of space that's been used in the past but now is not due to COW and not referenced anymore, the chunks have to be reclaimed and zones reset to make it usable again

- Device zone size -- the reported zone size of the host-managed device, same for all devices

The root user will also see stats broken down by block group types:

```
Data,single: Size:1.15TiB, Used:1.13TiB (98.26%)

   /dev/sdb        1.15TiB
Metadata,single: Size:12.00GiB, Used:6.45GiB (53.75%)

   /dev/sdb       12.00GiB
System,single: Size:32.00MiB, Used:144.00KiB (0.44%)

   /dev/sdb       32.00MiB
Unallocated:

   /dev/sdb      669.99GiB
```

Data is block group type, single is block group profile, Size is total size occupied by this type, Used is the actually used space, the percent is ratio of Used/Size. The Unallocated is remaining space.

Options

-b|--raw

raw numbers in bytes, without the B suffix

-h|--human-readable

print human friendly numbers, base 1024, this is the default

-H

print human friendly numbers, base 1000

--iec

select the 1024 base for the following options, according to the IEC standard

--si

select the 1000 base for the following options, according to the SI standard

-k|--kbytes

show sizes in KiB, or kB with --si

-m|--mbytes

show sizes in MiB, or MB with --si

-g|--gbytes

show sizes in GiB, or GB with --si

-t|--tbytes

show sizes in TiB, or TB with --si

-T

show data in tabular format

If conflicting options are passed, the last one takes precedence.

## EXAMPLES
$ btrfs filesystem defrag -v -r dir/

Recursively defragment files under dir/, print files as they are processed. The file names will be printed in batches, similarly the amount of data triggered by defragmentation will be proportional to last N printed files. The system dirty memory throttling will slow down the defragmentation but there can still be a lot of IO load and the system may stall for a moment.

$ btrfs filesystem defrag -v -r -f dir/

Recursively defragment files under dir/, be verbose and wait until all blocks are flushed before processing next file. You can note slower progress of the output and lower IO load (proportional to currently defragmented file).

$ btrfs filesystem defrag -v -r -f -clzo dir/

Recursively defragment files under dir/, be verbose, wait until all blocks are flushed and force file compression.

$ btrfs filesystem defrag -v -r -t 64M dir/

Recursively defragment files under dir/, be verbose and try to merge extents to be about 64MiB. As stated above, the success rate depends on actual free space fragmentation and the final result is not guaranteed to meet the target even if run repeatedly.

$ btrfs filesystem resize -1G /path

$ btrfs filesystem resize 1:-1G /path

Shrink size of the filesystem's device id 1 by 1GiB. The first syntax expects a device with id 1 to exist, otherwise fails. The second is equivalent and more explicit. For a single-device filesystem it's typically not necessary to specify the devid though.

$ btrfs filesystem resize max /path

$ btrfs filesystem resize 1:max /path

Let's assume that devid 1 exists and the filesystem does not occupy the whole block device, e.g. it has been enlarged and we want to grow the filesystem. By simply using max as size we will achieve that.

NOTE:

There are two ways to minimize the filesystem on a given device. The btrfs inspect-internal min-dev-size command, or iteratively shrink in steps.

## EXIT STATUS
btrfs filesystem returns a zero exit status if it succeeds. Non zero is returned in case of failure.

## AVAILABILITY
btrfs is part of btrfs-progs. Please refer to the documentation at https://btrfs.readthedocs.io.

## SEE ALSO
btrfs-subvolume(8), mkfs.btrfs(8)


btrfs-find-root

title: btrfs-find-root(8)

summary: filter to find btrfs root

text:
# btrfs-find-root(8)

## NAME
btrfs-find-root - filter to find btrfs root

## SYNOPSIS
btrfs-find-root [options] <device>

## DESCRIPTION
btrfs-find-root is used to find the satisfied root, you can filter by root tree's objectid, generation, level.

## OPTIONS
-a

Search through all metadata extents, even the root has been already found.

-g <generation>

Filter root tree by it's original transaction id, tree root's generation in default.

-o <objectid>

Filter root tree by it's objectid,tree root's objectid in default.

-l <level>

Filter root tree by b-tree's level, level 0 in default.

## EXIT STATUS
btrfs-find-root will return 0 if no error happened. If any problems happened, 1 will be returned.

## SEE ALSO
mkfs.btrfs(8)


btrfs-image

title: btrfs-image(8)

text:
# btrfs-image(8)

## NAME
btrfs-image - create/restore an image of the filesystem

## SYNOPSIS
btrfs-image [options] <source> <target>

## DESCRIPTION
btrfs-image is used to create an image of a btrfs filesystem. All data will be zeroed, but metadata and the like is preserved. Mainly used for debugging purposes.

In the dump mode, source is the btrfs device/file and target is the output file (use - for stdout).

In the restore mode (option -r), source is the dumped image and target is the btrfs device/file.

## OPTIONS
-r

Restore metadump image. By default, this fixes super's chunk tree, by using 1 stripe pointing to primary device, so that file system can be restored by running tree log reply if possible. To restore without changing number of stripes in chunk tree check -o option.

-c <value>

Compression level (0 ~ 9).

-t <value>

Number of threads (1 ~ 32) to be used to process the image dump or restore.

-o

Use the old restore method, this does not fixup the chunk tree so the restored file system will not be able to be mounted.

-s

Sanitize the file names when generating the image. One -s means just generate random garbage, which means that the directory indexes won't match up since the hashes won't match with the garbage filenames. Using -s will calculate a collision for the filename so that the hashes match, and if it can't calculate a collision then it will just generate garbage. The collision calculator is very time and CPU intensive so only use it if you are having problems with your file system tree and need to have it mostly working.

-w

Walk all the trees manually and copy any blocks that are referenced. Use this option if your extent tree is corrupted to make sure that all of the metadata is captured.

-m

Restore for multiple devices, more than 1 device should be provided.

## EXIT STATUS
btrfs-image will return 0 if no error happened. If any problems happened, 1 will be returned.

## SEE ALSO
mkfs.btrfs(8)