← Back to branch summary

~ubuntu-branches/ubuntu/feisty/apache2/feisty

« back to all changes in this revision

Viewing changes to docs/man/apxs.8

  • Committer: Bazaar Package Importer
  • Author(s): Andreas Barth
  • Date: 2006-12-09 21:05:45 UTC
  • mfrom: (0.6.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20061209210545-h70s0xaqc2v8vqr2
Tags: 2.2.3-3.2
http://bugs.debian.org/396265
* Non-maintainer upload.
* 043_ajp_connection_reuse: Patch from upstream Bugzilla, fixing a critical
  issue with regard to connection reuse in mod_proxy_ajp.
  Closes: #396265

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/man/apxs.8
 
1
.\" XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 
2
.\" DO NOT EDIT! Generated from XML source.
 
3
.\" XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 
4
.de Sh \" Subsection
 
5
.br
 
6
.if t .Sp
 
7
.ne 5
 
8
.PP
 
9
\fB\\$1\fR
 
10
.PP
 
11
..
 
12
.de Sp \" Vertical space (when we can't use .PP)
 
13
.if t .sp .5v
 
14
.if n .sp
 
15
..
 
16
.de Ip \" List item
 
17
.br
 
18
.ie \\n(.$>=3 .ne \\$3
 
19
.el .ne 3
 
20
.IP "\\$1" \\$2
 
21
..
 
22
.TH "APXS" 8 "2004-10-01" "Apache HTTP Server" "apxs"
 
23
 
 
24
.SH NAME
 
25
apxs \- APache eXtenSion tool
 
26
 
 
27
.SH "SYNOPSIS"
 
28
 
 
29
.PP
 
30
\fBapxs\fR -\fBg\fR [ -\fBS\fR \fIname\fR=\fIvalue\fR ] -\fBn\fR \fImodname\fR
 
31
 
 
32
.PP
 
33
\fBapxs\fR -\fBq\fR [ -\fBS\fR \fIname\fR=\fIvalue\fR ] \fIquery\fR \&.\&.\&.
 
34
 
 
35
.PP
 
36
\fBapxs\fR -\fBc\fR [ -\fBS\fR \fIname\fR=\fIvalue\fR ] [ -\fBo\fR \fIdsofile\fR ] [ -\fBI\fR \fIincdir\fR ] [ -\fBD\fR \fIname\fR=\fIvalue\fR ] [ -\fBL\fR \fIlibdir\fR ] [ -\fBl\fR \fIlibname\fR ] [ -\fBWc,\fR\fIcompiler-flags\fR ] [ -\fBWl,\fR\fIlinker-flags\fR ] \fIfiles\fR \&.\&.\&.
 
37
 
 
38
.PP
 
39
\fBapxs\fR -\fBi\fR [ -\fBS\fR \fIname\fR=\fIvalue\fR ] [ -\fBn\fR \fImodname\fR ] [ -\fBa\fR ] [ -\fBA\fR ] \fIdso-file\fR \&.\&.\&.
 
40
 
 
41
.PP
 
42
\fBapxs\fR -\fBe\fR [ -\fBS\fR \fIname\fR=\fIvalue\fR ] [ -\fBn\fR \fImodname\fR ] [ -\fBa\fR ] [ -\fBA\fR ] \fIdso-file\fR \&.\&.\&.
 
43
 
 
44
 
 
45
.SH "SUMMARY"
 
46
 
 
47
.PP
 
48
apxs is a tool for building and installing extension modules for the Apache HyperText Transfer Protocol (HTTP) server\&. This is achieved by building a dynamic shared object (DSO) from one or more source or object \fIfiles\fR which then can be loaded into the Apache server under runtime via the LoadModule directive from mod_so\&.
 
49
 
 
50
.PP
 
51
So to use this extension mechanism your platform has to support the DSO feature and your Apache httpd binary has to be built with the mod_so module\&. The apxs tool automatically complains if this is not the case\&. You can check this yourself by manually running the command
 
52
 
 
53
.nf
 
54
 
 
55
      $ httpd -l
 
56
    
 
57
.fi
 
58
 
 
59
.PP
 
60
The module mod_so should be part of the displayed list\&. If these requirements are fulfilled you can easily extend your Apache server's functionality by installing your own modules with the DSO mechanism by the help of this apxs tool:
 
61
 
 
62
.nf
 
63
 
 
64
      $ apxs -i -a -c mod_foo\&.c
 
65
      gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo\&.c
 
66
      ld -Bshareable -o mod_foo\&.so mod_foo\&.o
 
67
      cp mod_foo\&.so /path/to/apache/modules/mod_foo\&.so
 
68
      chmod 755 /path/to/apache/modules/mod_foo\&.so
 
69
      [activating module `foo' in /path/to/apache/etc/httpd\&.conf]
 
70
      $ apachectl restart
 
71
      /path/to/apache/sbin/apachectl restart: httpd not running, trying to start
 
72
      [Tue Mar 31 11:27:55 1998] [debug] mod_so\&.c(303): loaded module foo_module
 
73
      /path/to/apache/sbin/apachectl restart: httpd started
 
74
      $ _
 
75
    
 
76
.fi
 
77
 
 
78
.PP
 
79
The arguments \fIfiles\fR can be any C source file (\&.c), a object file (\&.o) or even a library archive (\&.a)\&. The apxs tool automatically recognizes these extensions and automatically used the C source files for compilation while just using the object and archive files for the linking phase\&. But when using such pre-compiled objects make sure they are compiled for position independent code (PIC) to be able to use them for a dynamically loaded shared object\&. For instance with GCC you always just have to use -fpic\&. For other C compilers consult its manual page or at watch for the flags apxs uses to compile the object files\&.
 
80
 
 
81
.PP
 
82
For more details about DSO support in Apache read the documentation of mod_so or perhaps even read the src/modules/standard/mod_so\&.c source file\&.
 
83
 
 
84
 
 
85
.SH "OPTIONS"
 
86
 
 
87
.SS "Common Options"
 
88
 
 
89
 
 
90
.TP
 
91
-n \fImodname\fR
 
92
This explicitly sets the module name for the -i (install) and -g (template generation) option\&. Use this to explicitly specify the module name\&. For option -g this is required, for option -i the apxs tool tries to determine the name from the source or (as a fallback) at least by guessing it from the filename\&.  
 
93
  
 
94
.SS "Query Options"
 
95
 
 
96
 
 
97
.TP
 
98
-q
 
99
Performs a query for apxs's knowledge about certain settings\&. The \fIquery\fR parameters can be one or more of the following strings: CC, CFLAGS, CFLAGS_SHLIB, INCLUDEDIR, LD_SHLIB, LDFLAGS_SHLIB, LIBEXECDIR, LIBS_SHLIB, SBINDIR, SYSCONFDIR, TARGET\&. .PP Use this for manually determining settings\&. For instance use INC=-I`apxs -q INCLUDEDIR` .PP inside your own Makefiles if you need manual access to Apache's C header files\&.  
 
100
  
 
101
.SS "Configuration Options"
 
102
 
 
103
 
 
104
.TP
 
105
-S \fIname\fR=\fIvalue\fR
 
106
This option changes the apxs settings described above\&.  
 
107
  
 
108
.SS "Template Generation Options"
 
109
 
 
110
 
 
111
.TP
 
112
-g
 
113
This generates a subdirectory \fIname\fR (see option -n) and there two files: A sample module source file named mod_\fIname\fR\&.c which can be used as a template for creating your own modules or as a quick start for playing with the apxs mechanism\&. And a corresponding Makefile for even easier build and installing of this module\&.  
 
114
  
 
115
.SS "DSO Compilation Options"
 
116
 
 
117
 
 
118
.TP
 
119
-c
 
120
This indicates the compilation operation\&. It first compiles the C source files (\&.c) of \fIfiles\fR into corresponding object files (\&.o) and then builds a dynamically shared object in \fIdsofile\fR by linking these object files plus the remaining object files (\&.o and \&.a) of \fIfiles\fR\&. If no -o option is specified the output file is guessed from the first filename in \fIfiles\fR and thus usually defaults to mod_\fIname\fR\&.so\&.  
 
121
.TP
 
122
-o \fIdsofile\fR
 
123
Explicitly specifies the filename of the created dynamically shared object\&. If not specified and the name cannot be guessed from the \fIfiles\fR list, the fallback name mod_unknown\&.so is used\&.  
 
124
.TP
 
125
-D \fIname\fR=\fIvalue\fR
 
126
This option is directly passed through to the compilation command(s)\&. Use this to add your own defines to the build process\&.  
 
127
.TP
 
128
-I \fIincdir\fR
 
129
This option is directly passed through to the compilation command(s)\&. Use this to add your own include directories to search to the build process\&.  
 
130
.TP
 
131
-L \fIlibdir\fR
 
132
This option is directly passed through to the linker command\&. Use this to add your own library directories to search to the build process\&.  
 
133
.TP
 
134
-l \fIlibname\fR
 
135
This option is directly passed through to the linker command\&. Use this to add your own libraries to search to the build process\&.  
 
136
.TP
 
137
-Wc,\fIcompiler-flags\fR
 
138
This option passes \fIcompiler-flags\fR as additional flags to the libtool --mode=compile command\&. Use this to add local compiler-specific options\&.  
 
139
.TP
 
140
-Wl,\fIlinker-flags\fR
 
141
This option passes \fIlinker-flags\fR as additional flags to the libtool --mode=link command\&. Use this to add local linker-specific options\&.  
 
142
  
 
143
.SS "DSO Installation and Configuration Options"
 
144
  
 
145
 
 
146
.TP
 
147
-i
 
148
This indicates the installation operation and installs one or more dynamically shared objects into the server's \fImodules\fR directory\&.  
 
149
.TP
 
150
-a
 
151
This activates the module by automatically adding a corresponding LoadModule line to Apache's httpd\&.conf configuration file, or by enabling it if it already exists\&.  
 
152
.TP
 
153
-A
 
154
Same as option -a but the created LoadModule directive is prefixed with a hash sign (#), \fIi\&.e\&.\fR, the module is just prepared for later activation but initially disabled\&.  
 
155
.TP
 
156
-e
 
157
This indicates the editing operation, which can be used with the -a and -A options similarly to the -i operation to edit Apache's httpd\&.conf configuration file without attempting to install the module\&.  
 
158
  
 
159
.SH "EXAMPLES"
 
160
 
 
161
.PP
 
162
Assume you have an Apache module named mod_foo\&.c available which should extend Apache's server functionality\&. To accomplish this you first have to compile the C source into a shared object suitable for loading into the Apache server under runtime via the following command:
 
163
 
 
164
.nf
 
165
 
 
166
      $ apxs -c mod_foo\&.c
 
167
      /path/to/libtool --mode=compile gcc \&.\&.\&. -c mod_foo\&.c
 
168
      /path/to/libtool --mode=link gcc \&.\&.\&. -o mod_foo\&.la mod_foo\&.slo
 
169
      $ _
 
170
    
 
171
.fi
 
172
 
 
173
.PP
 
174
Then you have to update the Apache configuration by making sure a LoadModule directive is present to load this shared object\&. To simplify this step apxs provides an automatic way to install the shared object in its "modules" directory and updating the httpd\&.conf file accordingly\&. This can be achieved by running:
 
175
 
 
176
.nf
 
177
 
 
178
      $ apxs -i -a mod_foo\&.la
 
179
      /path/to/instdso\&.sh mod_foo\&.la /path/to/apache/modules
 
180
      /path/to/libtool --mode=install cp mod_foo\&.la /path/to/apache/modules
 
181
      \&.\&.\&.
 
182
      chmod 755 /path/to/apache/modules/mod_foo\&.so
 
183
      [activating module `foo' in /path/to/apache/conf/httpd\&.conf]
 
184
      $ _
 
185
    
 
186
.fi
 
187
 
 
188
.PP
 
189
This way a line named
 
190
 
 
191
.nf
 
192
 
 
193
      LoadModule foo_module modules/mod_foo\&.so
 
194
    
 
195
.fi
 
196
 
 
197
.PP
 
198
is added to the configuration file if still not present\&. If you want to have this disabled per default use the -A option, \fIi\&.e\&.\fR
 
199
 
 
200
.nf
 
201
 
 
202
      $ apxs -i -A mod_foo\&.c
 
203
    
 
204
.fi
 
205
 
 
206
.PP
 
207
For a quick test of the apxs mechanism you can create a sample Apache module template plus a corresponding Makefile via:
 
208
 
 
209
.nf
 
210
 
 
211
      $ apxs -g -n foo
 
212
      Creating [DIR]  foo
 
213
      Creating [FILE] foo/Makefile
 
214
      Creating [FILE] foo/modules\&.mk
 
215
      Creating [FILE] foo/mod_foo\&.c
 
216
      Creating [FILE] foo/\&.deps
 
217
      $ _
 
218
    
 
219
.fi
 
220
 
 
221
.PP
 
222
Then you can immediately compile this sample module into a shared object and load it into the Apache server:
 
223
 
 
224
.nf
 
225
 
 
226
      $ cd foo
 
227
      $ make all reload
 
228
      apxs -c mod_foo\&.c
 
229
      /path/to/libtool --mode=compile gcc \&.\&.\&. -c mod_foo\&.c
 
230
      /path/to/libtool --mode=link gcc \&.\&.\&. -o mod_foo\&.la mod_foo\&.slo
 
231
      apxs -i -a -n "foo" mod_foo\&.la
 
232
      /path/to/instdso\&.sh mod_foo\&.la /path/to/apache/modules
 
233
      /path/to/libtool --mode=install cp mod_foo\&.la /path/to/apache/modules
 
234
      \&.\&.\&.
 
235
      chmod 755 /path/to/apache/modules/mod_foo\&.so
 
236
      [activating module `foo' in /path/to/apache/conf/httpd\&.conf]
 
237
      apachectl restart
 
238
      /path/to/apache/sbin/apachectl restart: httpd not running, trying to start
 
239
      [Tue Mar 31 11:27:55 1998] [debug] mod_so\&.c(303): loaded module foo_module
 
240
      /path/to/apache/sbin/apachectl restart: httpd started
 
241
      $ _
 
242
    
 
243
.fi
 
244