summaryrefslogtreecommitdiffstats
path: root/docs-xml/manpages/vfs_btrfs.8.xml
blob: c617a276e5bf63549208b09ba4f934f551df8251 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE refentry PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
<refentry id="vfs_btrfs.8">

<refmeta>
	<refentrytitle>vfs_btrfs</refentrytitle>
	<manvolnum>8</manvolnum>
	<refmiscinfo class="source">Samba</refmiscinfo>
	<refmiscinfo class="manual">System Administration tools</refmiscinfo>
	<refmiscinfo class="version">&doc.version;</refmiscinfo>
</refmeta>


<refnamediv>
	<refname>vfs_btrfs</refname>
	<refpurpose>
		Utilize features provided by the Btrfs filesystem
	</refpurpose>
</refnamediv>

<refsynopsisdiv>
	<cmdsynopsis>
		<command>vfs objects = btrfs</command>
	</cmdsynopsis>
</refsynopsisdiv>

<refsect1>
	<title>DESCRIPTION</title>

	<para>This VFS module is part of the
	<citerefentry><refentrytitle>samba</refentrytitle>
	<manvolnum>8</manvolnum></citerefentry> suite.</para>

	<para>
		The <command>vfs_btrfs</command> VFS module exposes Btrfs
		specific features for use by Samba.
	</para>

	<para>
		Btrfs allows for multiple files to share the same on-disk data
		through the use cloned ranges. When an SMB client issues a
		request to copy duplicate data (via FSCTL_SRV_COPYCHUNK), this
		module maps the request to a Btrfs clone range IOCTL, instead
		of performing reads and writes required by a traditional copy.
		Doing so saves storage capacity and greatly reduces disk IO.
	</para>

	<para>
		This module also exposes Btrfs per-file compression support to
		SMB clients via the get/set compression fsctls.
	</para>

	<para>
		Btrfs snapshots can be manipulated by Samba's FSRVP server.
		Snapshot manipulation using this module is currently considered
		experimental, and is therefore disabled by default. The
		<command>vfs_snapper</command> module is instead recommended for
		this purpose.
	</para>

	<para>
		This module is stackable.
	</para>
</refsect1>

<refsect1>
	<title>OPTIONS</title>

	<variablelist>
		<varlistentry>
		<term>btrfs: manipulate snapshots = [yes|no]</term>
		<listitem>
		<para>
		When set to <emphasis>yes</emphasis>, experimental support for
		the creation and deletion of snapshots via corresponding Btrfs
		IOCTLs will be enabled. The default is <emphasis>no</emphasis>,
		which means that such requests are passed through to any
		underlying VFS module.
		</para>
		</listitem>
		</varlistentry>
	</variablelist>
</refsect1>

<refsect1>
	<title>CONFIGURATION</title>

	<para>
		<command>vfs_btrfs</command> requires that the underlying share
		path is a Btrfs subvolume.
	</para>
	<programlisting>
		<smbconfsection name="[share]"/>
		<smbconfoption name="vfs objects">btrfs</smbconfoption>
		<smbconfoption name="btrfs: manipulate snapshots">no</smbconfoption>
	</programlisting>
	<para>
		To use the experimental snapshot manipulation functionality
		provided by this module, it must be explicitly enabled, and
		Samba's FSRVP server must be running.
	</para>
	<para>
		The <command>vfs_shadow_copy</command> module can be used to
		expose snapshots created by <command>vfs_btrfs</command> to
		Windows Explorer as file / directory "previous versions".
	</para>

	<programlisting>
		<smbconfsection name="[global]"/>
		<smbconfoption name="registry shares">yes</smbconfoption>
		<smbconfoption name="include">registry</smbconfoption>

		<smbconfsection name="[share]"/>
		<smbconfoption name="vfs objects">btrfs shadow_copy</smbconfoption>
		<smbconfoption name="btrfs: manipulate snapshots">yes</smbconfoption>
	</programlisting>
</refsect1>

<refsect1>
	<title>VERSION</title>

	<para>
		This man page is part of version &doc.version; of the Samba suite.
	</para>
</refsect1>

<refsect1>
	<title>AUTHOR</title>

	<para>The original Samba software and related utilities
	were created by Andrew Tridgell. Samba is now developed
	by the Samba Team as an Open Source project similar
	to the way the Linux kernel is developed.</para>

</refsect1>

</refentry>