60013f9be9a5a29abf293f27cb2f1011a2989884
[samba.git] / docs-xml / manpages / vfs_btrfs.8.xml
1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <!DOCTYPE refentry PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
3 <refentry id="vfs_btrfs.8">
4
5 <refmeta>
6         <refentrytitle>vfs_btrfs</refentrytitle>
7         <manvolnum>8</manvolnum>
8         <refmiscinfo class="source">Samba</refmiscinfo>
9         <refmiscinfo class="manual">System Administration tools</refmiscinfo>
10         <refmiscinfo class="version">&doc.version;</refmiscinfo>
11 </refmeta>
12
13
14 <refnamediv>
15         <refname>vfs_btrfs</refname>
16         <refpurpose>
17                 Utilize features provided by the Btrfs filesystem
18         </refpurpose>
19 </refnamediv>
20
21 <refsynopsisdiv>
22         <cmdsynopsis>
23                 <command>vfs objects = btrfs</command>
24         </cmdsynopsis>
25 </refsynopsisdiv>
26
27 <refsect1>
28         <title>DESCRIPTION</title>
29
30         <para>This VFS module is part of the
31         <citerefentry><refentrytitle>samba</refentrytitle>
32         <manvolnum>8</manvolnum></citerefentry> suite.</para>
33
34         <para>
35                 The <command>vfs_btrfs</command> VFS module exposes Btrfs
36                 specific features for use by Samba.
37         </para>
38
39         <para>
40                 Btrfs allows for multiple files to share the same on-disk data
41                 through the use cloned ranges. When an SMB client issues a
42                 request to copy duplicate data (via FSCTL_SRV_COPYCHUNK), this
43                 module maps the request to a Btrfs clone range IOCTL, instead
44                 of performing reads and writes required by a traditional copy.
45                 Doing so saves storage capacity and greatly reduces disk IO.
46         </para>
47
48         <para>
49                 This module also exposes Btrfs per-file compression support to
50                 SMB clients via the get/set compression fsctls.
51         </para>
52
53         <para>
54                 Btrfs snapshots can be manipulated by Samba's FSRVP server.
55                 Snapshot manipulation using this module is currently considered
56                 experimental, and is therefore disabled by default. The
57                 <command>vfs_snapper</command> module is instead recommended for
58                 this purpose.
59         </para>
60
61         <para>
62                 This module is stackable.
63         </para>
64 </refsect1>
65
66 <refsect1>
67         <title>OPTIONS</title>
68
69         <variablelist>
70                 <varlistentry>
71                 <term>btrfs: manipulate snapshots = [yes|no]</term>
72                 <listitem>
73                 <para>
74                 When set to <emphasis>yes</emphasis>, experimental support for
75                 the creation and deletion of snapshots via corresponding Btrfs
76                 IOCTLs will be enabled. The default is <emphasis>no</emphasis>,
77                 which means that such requests are passed through to any
78                 underlying VFS module.
79                 </para>
80                 </listitem>
81                 </varlistentry>
82         </variablelist>
83 </refsect1>
84
85 <refsect1>
86         <title>CONFIGURATION</title>
87
88         <para>
89                 <command>vfs_btrfs</command> requires that the underlying share
90                 path is a Btrfs subvolume.
91         </para>
92         <programlisting>
93                 <smbconfsection name="[share]"/>
94                 <smbconfoption name="vfs objects">btrfs</smbconfoption>
95                 <smbconfoption name="btrfs: manipulate snapshots">no</smbconfoption>
96         </programlisting>
97         <para>
98                 To use the experimental snapshot manipulation functionality
99                 provided by this module, it must be explicitly enabled, and
100                 Samba's FSRVP server must be running.
101         </para>
102         <para>
103                 The <command>vfs_shadow_copy</command> module can be used to
104                 expose snapshots created by <command>vfs_btrfs</command> to
105                 Windows Explorer as file / directory "previous versions".
106         </para>
107
108         <programlisting>
109                 <smbconfsection name="[global]"/>
110                 <smbconfoption name="rpc_daemon:fssd">fork</smbconfoption>
111                 <smbconfoption name="registry shares">yes</smbconfoption>
112                 <smbconfoption name="include">registry</smbconfoption>
113
114                 <smbconfsection name="[share]"/>
115                 <smbconfoption name="vfs objects">btrfs shadow_copy</smbconfoption>
116                 <smbconfoption name="btrfs: manipulate snapshots">yes</smbconfoption>
117         </programlisting>
118 </refsect1>
119
120 <refsect1>
121         <title>VERSION</title>
122
123         <para>
124                 This man page is part of version &doc.version; of the Samba suite.
125         </para>
126 </refsect1>
127
128 <refsect1>
129         <title>AUTHOR</title>
130
131         <para>The original Samba software and related utilities
132         were created by Andrew Tridgell. Samba is now developed
133         by the Samba Team as an Open Source project similar
134         to the way the Linux kernel is developed.</para>
135
136 </refsect1>
137
138 </refentry>