summaryrefslogtreecommitdiff
path: root/docs-xml/manpages-3/vfs_aio_linux.8.xml
blob: dac94a57949c6da843123f7b0e0b0741b96c520c (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
<?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_aio_linux.8">

<refmeta>
	<refentrytitle>vfs_aio_linux</refentrytitle>
	<manvolnum>8</manvolnum>
	<refmiscinfo class="source">Samba</refmiscinfo>
	<refmiscinfo class="manual">System Administration tools</refmiscinfo>
	<refmiscinfo class="version">3.6</refmiscinfo>
</refmeta>


<refnamediv>
	<refname>vfs_aio_linux</refname>
	<refpurpose>implement async I/O in Samba vfs using Linux kernel aio calls</refpurpose>
</refnamediv>

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

<refsect1>
	<title>DESCRIPTION</title>

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

	<para>The <command>aio_linux</command> VFS module enables asynchronous
	I/O for Samba on Linux kernels that have the kernel AIO calls available
	without using the Posix AIO interface. Posix AIO can suffer from severe
	limitations.  For example, on some Linux versions the
	real-time signals that it uses are broken under heavy load.
	Other systems only allow AIO when special kernel modules are
	loaded or only allow a certain system-wide amount of async
	requests being scheduled. Systems based on glibc (most Linux
	systems) only allow a single outstanding request per file
	descriptor which essentially makes Posix AIO useless on systems
	using the glibc implementation.</para>

	<para>To work around all these limitations, the aio_linux module
	was written. It uses the Linux kernel AIO interface instead of the
	internal Posix AIO interface to allow read and write calls
	to be processed asynchronously. A queue size of 128 events
	is used by default. To change this limit set the "aio num events"
	parameter below.
	</para>

	<para>
	Note that the smb.conf parameters <command>aio read size</command>
	and <command>aio write size</command> must also be set appropriately
	for this module to be active.
	</para>

	<para>This module MUST be listed last in any module stack as
	the Samba VFS pread/pwrite interface is not thread-safe. This
	module makes direct pread and pwrite system calls and does
	NOT call the Samba VFS pread and pwrite interfaces.</para>

</refsect1>


<refsect1>
	<title>EXAMPLES</title>

	<para>Straight forward use:</para>

<programlisting>
        <smbconfsection name="[cooldata]"/>
	<smbconfoption name="path">/data/ice</smbconfoption>
	<smbconfoption name="aio read size">1024</smbconfoption>
	<smbconfoption name="aio write size">1024</smbconfoption>
	<smbconfoption name="vfs objects">aio_linux</smbconfoption>
</programlisting>

</refsect1>

<refsect1>
	<title>OPTIONS</title>

	<variablelist>

		<varlistentry>
		<term>aio_linux:aio num events = INTEGER</term>
		<listitem>
		<para>Set the maximum size of the event queue
		that is used to limit outstanding IO requests.
		</para>
		<para>By default this is set to 128.</para>
		</listitem>
		</varlistentry>

	</variablelist>
</refsect1>
<refsect1>
	<title>VERSION</title>

	<para>This man page is correct for version 3.6.6 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>