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="registry shares">yes</smbconfoption>
 111                 <smbconfoption name="include">registry</smbconfoption>
 112
 113                 <smbconfsection name="[share]"/>
 114                 <smbconfoption name="vfs objects">btrfs shadow_copy</smbconfoption>
 115                 <smbconfoption name="btrfs: manipulate snapshots">yes</smbconfoption>
 116         </programlisting>
 117 </refsect1>
 118
 119 <refsect1>
 120         <title>VERSION</title>
 121
 122         <para>
 123                 This man page is part of version &doc.version; of the Samba suite.
 124         </para>
 125 </refsect1>
 126
 127 <refsect1>
 128         <title>AUTHOR</title>
 129
 130         <para>The original Samba software and related utilities
 131         were created by Andrew Tridgell. Samba is now developed
 132         by the Samba Team as an Open Source project similar
 133         to the way the Linux kernel is developed.</para>
 134
 135 </refsect1>
 136
 137 </refentry>