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
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
|
<!-- $Id: mod_dso.html,v 1.2 2004/10/29 22:33:42 castaglia Exp $ -->
<!-- $Source: /cvsroot/proftp/proftpd/doc/modules/mod_dso.html,v $ -->
<html>
<head>
<title>ProFTPD module mod_dso</title>
</head>
<body bgcolor=white>
<hr>
<center>
<h2><b>ProFTPD module <code>mod_dso</code></b></h2>
</center>
<hr><br>
<p>
<b>What are DSO modules?</b><br>
"On modern Unix derivatives there exists a nifty mechanism usually called
dynamic linking/loading of <i>Dynamic Shared Objects</i> (DSO) which provides
a way to build a piece of program code in a special format for loading it at
run-time into the address space of an executable program.
<p>
This loading can usually be done in two ways: Automatically by a system program
called <code>ld.so</code> when an executable program is started, or manually
from within the executing program via a programmatic system interface to the
Unix loader through the system calls <code>dlopen()/dlsym()</code>.
<p>
In the first way the DSO's are usually called <i>shared libraries</i> or
<i>DSO libraries</i> and named <code>libfoo.so</code> or
<code>libfoo.so.1.2</code>. They reside in a system directory (usually
<code>/usr/lib/</code>) and the link to the executable program is established
at build-time by specifying <code>-lfoo</code> to the linker command. This
hard-codes library references into the executable program file so that at
start-time the Unix loader is able to locate <code>libfoo.so</code> in
<code>/usr/lib/</code>, in paths hard-coded via linker-options like
<code>-R</code> or in paths configured via the environment variable
<code>LD_LIBRARY_PATH</code>. It then resolves any (yet unresolved) symbols in
the executable program which are available in the DSO.
<p>
Symbols in the executable program are usually not referenced by the DSO
(because it's a reusable library of general code) and hence no further
resolving has to be done. The executable program has no need to do anything on
its own to use the symbols from the DSO because the complete resolving is done
by the Unix loader. (In fact, the code to invoke <code>ld.so</code> is part of
the run-time startup code which is linked into every executable program which
has been bound non-static.) The advantage of dynamic loading of common library
code is obvious: the library code needs to be stored only once, in a system
library like libc.so, saving disk space for every program.
<p>
In the second way the DSO's are usually called <i>shared objects</i> or
<i>DSO files</i> and can be named with an arbitrary extension (although the
canonical name is <code>foo.so</code>). These files usually stay inside a
program-specific directory and there is no automatically established link to
the executable program where they are used. Instead the executable program
manually loads the DSO at run-time into its address space via
<code>dlopen()</code>. At this time no resolving of symbols from the DSO for
the executable program is done. Instead the Unix loader automatically resolves
any (yet unresolved) symbols in the DSO from the set of symbols exported by the
executable program and its already loaded DSO libraries (especially all symbols
from the ubiquitous <code>libc.so</code>). This way the DSO gets knowledge of
the executable program's symbol set as if it had been statically linked with
it in the first place."
<p>
<i>(Taken from <a href="http://httpd.apache.org/docs/dso.html">http://httpd.apache.org/docs/dso.html</a>)</i>
<p>
The <code>mod_dso</code> module is ProFTPD's module for handling the dynamic
loading of modules. This module is contained in the <code>mod_dso.c</code>
file for ProFTPD 1.3.<i>x</i>, and is not compiled by default. Installation
instructions are discussed <a href="#Installation">here</a>.
<p>
The most current version of <code>mod_dso</code> can be found in the
ProFTPD source distribution:
<pre>
<a href="http://www.proftpd.org/">http://www.proftpd.org/</a>
</pre>
<h2>Directives</h2>
<ul>
<li><a href="#LoadFile">LoadFile</a>
<li><a href="#LoadModule">LoadModule</a>
<li><a href="#ModuleControlsACLs">ModuleControlsACLs</a>
<li><a href="#ModuleOrder">ModuleOrder</a>
<li><a href="#ModulePath">ModulePath</a>
</ul>
<p>
<h2>Control Actions</h2>
<ul>
<li><a href="#insmod">insmod</a>
<li><a href="#lsmod">lsmod</a>
<li><a href="#rmmod">rmmod</a>
</ul>
<p>
<hr>
<h2><a name="LoadFile">LoadFile</a></h2>
<strong>Syntax:</strong> LoadFile <em>path</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> "server config"<br>
<strong>Module:</strong> mod_dso<br>
<strong>Compatibility:</strong> 1.3rc1
<p>
The <code>LoadFile</code> directive is used to load any shared object
(<code>.so</code> file extension), such as shared libraries. On some
platforms, it may be necessary to load all of the libraries needed by
a DSO module, using <code>LoadFile</code>, prior to loading the module itself.
<p>
The <em>path</em> parameter must be the absolute path to the shared object
to load.
<p>
Example:
<pre>
# Load the zlib library
LoadFile /usr/lib/libz.so
</pre>
<p>
<hr>
<h2><a name="LoadModule">LoadModule</a></h2>
<strong>Syntax:</strong> LoadModule <em>name</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> "server config"<br>
<strong>Module:</strong> mod_dso<br>
<strong>Compatibility:</strong> 1.3rc1
<p>
The <code>LoadModule</code> directive is used to dynamically load a module
from the configuration file.
<p>
Example:
<pre>
LoadModule mod_test.c
</pre>
<p>
<hr>
<h2><a name="ModuleControlsACLs">ModuleControlsACLs</a></h2>
<strong>Syntax:</strong> ModuleControlsACLs <em>>actions|all allow|deny user|group list</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> "server config"<br>
<strong>Module:</strong> mod_dso<br>
<strong>Compatibility:</strong> 1.3rc1
<p>
The <code>ModuleControlsACLs</code> directive configures access lists of
<em>users</em> or <em>groups</em> who are allowed (or denied) the ability to
use the <em>actions</em> implemented by <code>mod_dso</code>. The default
behavior is to deny everyone unless an ACL allowing access has been explicitly
configured.
<p>
If "allow" is used, then <em>list</em>, a comma-delimited list
of <em>users</em> or <em>groups</em>, can use the given <em>actions</em>; all
others are denied. If "deny" is used, then the <em>list</em> of
<em>users</em> or <em>groups</em> cannot use <em>actions</em> all others are
allowed. Multiple <code>ModuleControlsACLs</code> directives may be used to
configure ACLs for different control actions, and for both users and groups.
<p>
The <em>actions</em> provided by <code>mod_dso</code> are "insmod"
"lsmod", and "rmmod".
<p>
Example:
<pre>
# Allow only user root to load and unload modules, but allow everyone
# to see which modules have been loaded
ModuleControlsACLs insmod,rmmod allow user root
ModuleControlsACLs lsmod allow user *
</pre>
<p>
<hr>
<h2><a name="ModuleOrder">ModuleOrder</a></h2>
<strong>Syntax:</strong> ModuleOrder <em>...</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> "server config"<br>
<strong>Module:</strong> mod_dso<br>
<strong>Compatibility:</strong> 1.3rc1
<p>
The <code>ModuleOrder</code> directive can be used to explicitly set the
module order. <b>Note</b>: do not use this directive unless you know what
you are doing. It is <i>very</i> easy to configure a non-working server with
this directive.
<p>
If you <i>are</i> going to use <code>ModuleOrder</code>, make sure it is
the very first directive in your <code>proftpd.conf</code> file.
<p>
Example:
<pre>
# Make this one the very first things, if you're going to use it.
ModuleOrder \
mod_core.c \
mod_cap.c \
mod_auth_unix.c \
mod_auth_pam.c \
mod_ls.c \
mod_log.c \
mod_site.c \
mod_xfer.c \
mod_auth.c \
mod_ifsession.c \
mod_auth_file.c
</pre>
<p>
<hr>
<h2><a name="ModulePath">ModulePath</a></h2>
<strong>Syntax:</strong> ModulePath <em>path</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> "server config"<br>
<strong>Module:</strong> mod_dso<br>
<strong>Compatibility:</strong> 1.3rc1
<p>
The <code>ModulePath</code> directive is used to configure an alternative
directory from which <code>mod_dso</code> will load DSO modules. By
default, <code>mod_dso</code> uses <em>$prefix</em>/<code>libexec/</code>,
where <em>$prefix</em> is where you installed <code>proftpd</code>,
<i>e.g.</i> <code>/usr/local/</code>.
<p>
The <em>path</em> parameter must be an absolute path.
<p>
Example:
<pre>
ModulePath /etc/proftpd/libexec
</pre>
<p>
<hr>
<h1>Control Actions</h1>
<p>
<hr>
<h2><a name="insmod"><code>insmod</code></a></h2>
<strong>Syntax:</strong> ftpdctl insmod <em>module</em><br>
<strong>Purpose:</strong> Load a DSO module
<p>
The <code>insmod</code> control action can be used to load a DSO module
into the running <code>proftpd</code> daemon.
<p>
A module cannot be loaded multiple times.
<p>
Example:
<pre>
ftpdctl rmmod mod_test.c
ftpdctl: 'mod_test.c' loaded
</pre>
<p>
<hr>
<h2><a name="lsmod"><code>lsmod</code></a></h2>
<strong>Syntax:</strong> ftpdctl lsmod<br>
<strong>Purpose:</strong> Display list of all loaded modules
<p>
The <code>lsmod</code> control action is used to display a list of all
loaded modules.
<p>
Example:
<pre>
ftpdctl lsmod
ftpdctl: Loaded Modules:
ftpdctl: mod_core.c
ftpdctl: mod_xfer.c
ftpdctl: mod_auth_unix.c
ftpdctl: mod_auth_file.c
ftpdctl: mod_auth.c
ftpdctl: mod_ls.c
ftpdctl: mod_log.c
ftpdctl: mod_site.c
ftpdctl: mod_dso.c
ftpdctl: mod_ctrls.c
ftpdctl: mod_auth_pam.c
ftpdctl: mod_cap.c
</pre>
<p>
<hr>
<h2><a name="rmmod"><code>rmmod</code></a></h2>
<strong>Syntax:</strong> ftpdctl rmmod <em>module</em><br>
<strong>Purpose:</strong> Unload a DSO module
<p>
The <code>rmmod</code> control action can be used to unload a DSO module
from the running <code>proftpd</code> daemon. Note that it is also
possible to "unload" one of the staticly-linked modules; this
does not remove that module from the process' memory space, but does remove
that module from the core engine, such that <code>proftpd</code> will
act as if the module is not present.
<p>
Example:
<pre>
ftpdctl rmmod mod_test.c
ftpdctl: 'mod_test.c' unloaded
</pre>
<p>
<hr>
<h2><a name="Usage">Usage</a></h2>
Note that <code>mod_dso</code>'s control actions are only available if
your <code>proftpd</code> has been compiled with Controls support.
<p>
<hr>
<h2><a name="Installation">Installation</a></h2>
The <code>mod_dso</code> module is distributed with ProFTPD. To enable use
of DSO modules, use the <code>--enable-dso</code> configure option:
<pre>
./configure --enable-dso
make
make install
</pre>
This option causes <code>mod_dso</code> to be compiled into
<code>proftpd</code>.
<p>
<hr><br>
Author: <i>$Author: castaglia $</i><br>
Last Updated: <i>$Date: 2004/10/29 22:33:42 $</i><br>
<br><hr>
<font size=2><b><i>
© Copyright 2004 TJ Saunders<br>
All Rights Reserved<br>
</i></b></font>
<hr><br>
</body>
</html>
|
