diff options
186 files changed, 41501 insertions, 0 deletions
diff --git a/BuildBin.dsp b/BuildBin.dsp new file mode 100644 index 0000000000..628c7b6d67 --- /dev/null +++ b/BuildBin.dsp @@ -0,0 +1,97 @@ +# Microsoft Developer Studio Project File - Name="BuildBin" - Package Owner=<4> +# Microsoft Developer Studio Generated Build File, Format Version 6.00 +# ** DO NOT EDIT ** + +# TARGTYPE "Win32 (x86) External Target" 0x0106 + +CFG=BuildBin - Win32 Debug +!MESSAGE This is not a valid makefile. To build this project using NMAKE, +!MESSAGE use the Export Makefile command and run +!MESSAGE +!MESSAGE NMAKE /f "BuildBin.mak". +!MESSAGE +!MESSAGE You can specify a configuration when running NMAKE +!MESSAGE by defining the macro CFG on the command line. For example: +!MESSAGE +!MESSAGE NMAKE /f "BuildBin.mak" CFG="BuildBin - Win32 Debug" +!MESSAGE +!MESSAGE Possible choices for configuration are: +!MESSAGE +!MESSAGE "BuildBin - Win32 Release" (based on "Win32 (x86) External Target") +!MESSAGE "BuildBin - Win32 Debug" (based on "Win32 (x86) External Target") +!MESSAGE + +# Begin Project +# PROP AllowPerConfigDependencies 0 +# PROP Scc_ProjName "" +# PROP Scc_LocalPath "" + +!IF "$(CFG)" == "BuildBin - Win32 Release" + +# PROP BASE Use_Debug_Libraries 0 +# PROP BASE Output_Dir "" +# PROP BASE Intermediate_Dir "" +# PROP BASE Cmd_Line "NMAKE /f makefile.win" +# PROP BASE Rebuild_Opt "/a" +# PROP BASE Target_File "\Apache2.0\bin\Apache.exe" +# PROP BASE Bsc_Name ".\Browse\BuildBin.bsc" +# PROP BASE Target_Dir "" +# PROP Use_Debug_Libraries 0 +# PROP Output_Dir "" +# PROP Intermediate_Dir "" +# PROP Cmd_Line "NMAKE /f makefile.win INSTDIR="\Apache2" _dummy" +# PROP Rebuild_Opt "" +# PROP Target_File "\Apache2\bin\Apache.exe" +# PROP Bsc_Name ".\Browse\Apache.bsc" +# PROP Target_Dir "" + +!ELSEIF "$(CFG)" == "BuildBin - Win32 Debug" + +# PROP BASE Use_Debug_Libraries 1 +# PROP BASE Output_Dir "" +# PROP BASE Intermediate_Dir "" +# PROP BASE Cmd_Line "NMAKE /f makefile.win" +# PROP BASE Rebuild_Opt "/a" +# PROP BASE Target_File "\Apache2.0\bin\Apache.exe" +# PROP BASE Bsc_Name ".\Browse\BuildBin.bsc" +# PROP BASE Target_Dir "" +# PROP Use_Debug_Libraries 1 +# PROP Output_Dir "" +# PROP Intermediate_Dir "" +# PROP Cmd_Line "NMAKE /f makefile.win INSTDIR="\Apache2" _dummy" +# PROP Rebuild_Opt "" +# PROP Target_File "\Apache2\bin\Apache.exe" +# PROP Bsc_Name ".\Browse\Apache.bsc" +# PROP Target_Dir "" + +!ENDIF + +# Begin Target + +# Name "BuildBin - Win32 Release" +# Name "BuildBin - Win32 Debug" + +!IF "$(CFG)" == "BuildBin - Win32 Release" + +!ELSEIF "$(CFG)" == "BuildBin - Win32 Debug" + +!ENDIF + +# Begin Source File + +SOURCE=.\os\win32\BaseAddr.ref +# End Source File +# Begin Source File + +SOURCE=.\CHANGES +# End Source File +# Begin Source File + +SOURCE=.\Makefile.win +# End Source File +# Begin Source File + +SOURCE=.\STATUS +# End Source File +# End Target +# End Project diff --git a/NWGNUmakefile b/NWGNUmakefile new file mode 100644 index 0000000000..39af31185e --- /dev/null +++ b/NWGNUmakefile @@ -0,0 +1,400 @@ +# +# Declare the sub-directories to be built here +# + +SUBDIRS = \ + srclib\apr \ + build \ + support \ + modules \ + $(EOLIST) + +# +# Get the 'head' of the build environment. This includes default targets and +# paths to tools +# + +include $(AP_WORK)\build\NWGNUhead.inc + +# +# build this level's files + +# +# Make sure all needed macro's are defined +# + +# +# These directories will be at the beginning of the include list, followed by +# INCDIRS +# +XINCDIRS += \ + $(AP_WORK)/srclib/apr/include \ + $(AP_WORK)/srclib/include/arch/NetWare \ + $(AP_WORK)/srclib/apr-util/include \ + $(AP_WORK)/include \ + $(AP_WORK)/modules/filters/ \ + $(AP_WORK)/modules/generators/ \ + $(AP_WORK)/modules/http/ \ + $(AP_WORK)/modules/loggers/ \ + $(AP_WORK)/modules/mappers/ \ + $(AP_WORK)/modules/proxy/ \ + $(AP_WORK)/os/NetWare \ + $(AP_WORK)/server/mpm/NetWare \ + $(AP_WORK)/srclib/pcre \ + $(NWOS) \ + $(EOLIST) + +# +# These flags will come after CFLAGS +# +XCFLAGS += \ + $(EOLIST) + +# +# These defines will come after DEFINES +# +XDEFINES += \ + $(EOLIST) + +# +# These flags will be added to the link.opt file +# +XLFLAGS += \ + $(EOLIST) + +# +# These values will be appended to the correct variables based on the value of +# RELEASE +# +ifeq "$(RELEASE)" "debug" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "noopt" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "release" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +# +# These are used by the link target if an NLM is being generated +# This is used by the link 'name' directive to name the nlm. If left blank +# TARGET_nlm (see below) will be used. +# +NLM_NAME = Apache2 + +# +# This is used by the link '-desc ' directive. +# If left blank, NLM_NAME will be used. +# +NLM_DESCRIPTION = Apache Web Server + +# +# This is used by the '-threadname' directive. If left blank, +# NLM_NAME Thread will be used. +# +NLM_THREAD_NAME = Apache +# +# If this is specified, it will override VERSION value in +# $(AP_WORK)\build\NWGNUenvironment.inc +# +NLM_VERSION = + +# +# If this is specified, it will override the default of 64K +# +NLM_STACK_SIZE = 65536 + + +# +# If this is specified it will be used by the link '-entry' directive +# +NLM_ENTRY_SYM = _LibCPrelude + +# +# If this is specified it will be used by the link '-exit' directive +# +NLM_EXIT_SYM = _LibCPostlude + +# +# If this is specified it will be used by the link '-check' directive +# +NLM_CHECK_SYM = _LibCCheckUnload + +# +# If these are specified it will be used by the link '-flags' directive +# +NLM_FLAGS = PSEUDOPREEMPTION + +# +# If this is specified it will be linked in with the XDCData option in the def +# file instead of the default of $(NWOS)/apache.xdc. XDCData can be disabled +# by setting APACHE_UNIPROC in the environment +# +XDCDATA = + +# +# If there is an NLM target, put it here +# +TARGET_nlm = \ + $(OBJDIR)/Apache2.nlm \ + $(EOLIST) + +# +# If there is an LIB target, put it here +# +TARGET_lib = \ + $(EOLIST) + +# +# These are the OBJ files needed to create the NLM target above. +# Paths must all use the '/' character +# +FILES_nlm_objs = \ + $(OBJDIR)/buildmark.o \ + $(OBJDIR)/config.o \ + $(OBJDIR)/connection.o \ + $(OBJDIR)/core.o \ + $(OBJDIR)/error_bucket.o \ + $(OBJDIR)/http_core.o \ + $(OBJDIR)/http_protocol.o \ + $(OBJDIR)/http_request.o \ + $(OBJDIR)/listen.o \ + $(OBJDIR)/log.o \ + $(OBJDIR)/main.o \ + $(OBJDIR)/mod_access.o \ + $(OBJDIR)/mod_actions.o \ + $(OBJDIR)/mod_alias.o \ + $(OBJDIR)/mod_asis.o \ + $(OBJDIR)/mod_auth.o \ + $(OBJDIR)/mod_autoindex.o \ + $(OBJDIR)/mod_dir.o \ + $(OBJDIR)/mod_env.o \ + $(OBJDIR)/mod_imap.o \ + $(OBJDIR)/mod_include.o \ + $(OBJDIR)/mod_log_config.o \ + $(OBJDIR)/mod_mime.o \ + $(OBJDIR)/mod_negotiation.o \ + $(OBJDIR)/mod_nw_ssl.o \ + $(OBJDIR)/mod_setenvif.o \ + $(OBJDIR)/mod_so.o \ + $(OBJDIR)/mod_userdir.o \ + $(OBJDIR)/modules.o \ + $(OBJDIR)/mpm_common.o \ + $(OBJDIR)/mpm_netware.o \ + $(OBJDIR)/pcre.o \ + $(OBJDIR)/pcreposix.o \ + $(OBJDIR)/protocol.o \ + $(OBJDIR)/request.o \ + $(OBJDIR)/rfc1413.o \ + $(OBJDIR)/scoreboard.o \ + $(OBJDIR)/util.o \ + $(OBJDIR)/util_cfgtree.o \ + $(OBJDIR)/util_charset.o \ + $(OBJDIR)/util_filter.o \ + $(OBJDIR)/util_md5.o \ + $(OBJDIR)/util_nw.o \ + $(OBJDIR)/util_script.o \ + $(OBJDIR)/util_time.o \ + $(OBJDIR)/util_xml.o \ + $(OBJDIR)/vhost.o \ + $(EOLIST) + +# +# These are the LIB files needed to create the NLM target above. +# These will be added as a library command in the link.opt file. +# +FILES_nlm_libs = \ + libcpre.o \ + $(EOLIST) + +# +# These are the modules that the above NLM target depends on to load. +# These will be added as a module command in the link.opt file. +# +FILES_nlm_modules = \ + aprlib \ + Libc \ + $(EOLIST) + +# +# If the nlm has a msg file, put it's path here +# +FILE_nlm_msg = + +# +# If the nlm has a hlp file put it's path here +# +FILE_nlm_hlp = + +# +# If this is specified, it will override $(NWOS)\copyright.txt. +# +FILE_nlm_copyright = + +# +# Any additional imports go here +# +FILES_nlm_Ximports = \ + @netware.imp \ + @$(APR)/aprlib.imp \ + @libc.imp \ + @ws2nlm.imp \ + GetCurrentAddressSpace \ + $(EOLIST) + +# +# Any symbols exported to here +# +FILES_nlm_exports = \ + @$(NWOS)/httpd.imp \ + $(EOLIST) + +# +# These are the OBJ files needed to create the LIB target above. +# Paths must all use the '/' character +# +FILES_lib_objs = \ + $(EOLIST) + +# +# implement targets and dependancies (leave this section alone) +# + +libs :: $(OBJDIR) $(TARGET_lib) + +nlms :: libs $(TARGET_nlm) + +# +# Updated this target to create necessary directories and copy files to the +# correct place. (See $(AP_WORK)\build\NWGNUhead.inc for examples) +# +install :: nlms FORCE + copy $(OBJDIR)\Apache2.nlm $(INSTALL)\Apache2\*.* + -copy ABOUT_APACHE $(INSTALL)\Apache2\*.* + -copy README $(INSTALL)\Apache2\*.* + -copy STATUS $(INSTALL)\Apache2\*.* + -copy LICENSE $(INSTALL)\Apache2\*.* + -copy docs\cgi-examples\*. $(INSTALL)\Apache2\cgi-examples\*.* + -copy docs\conf\httpd-std.conf $(INSTALL)\Apache2\conf\httpd.conf + -copy docs\conf\magic $(INSTALL)\Apache2\conf\magic + -copy docs\conf\mime.types $(INSTALL)\Apache2\conf\mime.types + -copy docs\error\*.* $(INSTALL)\Apache2\error\*.* + -copy docs\error\include\*.* $(INSTALL)\Apache2\error\include\*.* + -copy docs\docroot\*.* $(INSTALL)\Apache2\htdocs\*.* + -copy docs\icons\*.* $(INSTALL)\Apache2\icons\*.* + -copy docs\icons\small\*.* $(INSTALL)\Apache2\icons\small\*.* + -copy docs\man\*.* $(INSTALL)\Apache2\man\*.* + -copy docs\manual\*.* $(INSTALL)\Apache2\manual\*.* + -copy docs\manual\developer\*.* $(INSTALL)\Apache2\manual\developer + -copy docs\manual\faq\*.* $(INSTALL)\Apache2\manual\faq + -copy docs\manual\howto\*.* $(INSTALL)\Apache2\manual\howto + -copy docs\manual\images\*.* $(INSTALL)\Apache2\manual\images + -copy docs\manual\misc\*.* $(INSTALL)\Apache2\manual\misc + -copy docs\manual\mod\*.* $(INSTALL)\Apache2\manual\mod + -copy docs\manual\platform\*.* $(INSTALL)\Apache2\manual\platform + -copy docs\manual\programs\*.* $(INSTALL)\Apache2\manual\programs + -copy docs\manual\search\*.* $(INSTALL)\Apache2\manual\search + -copy docs\manual\vhosts\*.* $(INSTALL)\Apache2\manual\vhosts + +installdev :: FORCE + -copy $(subst /,\,$(AP_WORK))\include\*.h $(INSTALL)\Apache2\include\*.* + -copy $(subst /,\,$(AP_WORK))\os\netware\*.h $(INSTALL)\Apache2\include\*.* + -copy $(subst /,\,$(NWOS))\include\*.h $(INSTALL)\Apache2\include\*.* + -copy $(subst /,\,$(NWOS))\*.imp $(INSTALL)\Apache2\lib\*.* + -copy $(subst /,\,$(APR))\include\*.h $(INSTALL)\Apache2\include\*.* + -copy $(subst /,\,$(APR))\arch\netware\include\*.h $(INSTALL)\Apache2\include\*.* + -copy $(subst /,\,$(APRUTIL))\include\*.h $(INSTALL)\Apache2\include\*.* + -copy $(subst /,\,$(APR))\*.imp $(INSTALL)\Apache2\lib\*.* + +# +# Any specialized rules here +# + +$(OBJDIR)/%.o: server/%.c $(OBJDIR)\cc.opt + @echo compiling $< + $(CC) $< -o=$(OBJDIR)\$(@F) @$(OBJDIR)\cc.opt + +$(OBJDIR)/%.o: modules/arch/netware/%.c $(OBJDIR)\cc.opt + @echo compiling $< + $(CC) $< -o=$(OBJDIR)\$(@F) @$(OBJDIR)\cc.opt + +$(OBJDIR)/%.o: modules/http/%.c $(OBJDIR)\cc.opt + @echo compiling $< + $(CC) $< -o=$(OBJDIR)\$(@F) @$(OBJDIR)\cc.opt + +$(OBJDIR)/%.o: modules/aaa/%.c $(OBJDIR)\cc.opt + @echo compiling $< + $(CC) $< -o=$(OBJDIR)\$(@F) @$(OBJDIR)\cc.opt + +$(OBJDIR)/%.o: modules/mappers/%.c $(OBJDIR)\cc.opt + @echo compiling $< + $(CC) $< -o=$(OBJDIR)\$(@F) @$(OBJDIR)\cc.opt + +$(OBJDIR)/%.o: modules/generators/%.c $(OBJDIR)\cc.opt + @echo compiling $< + $(CC) $< -o=$(OBJDIR)\$(@F) @$(OBJDIR)\cc.opt + +$(OBJDIR)/%.o: modules/metadata/%.c $(OBJDIR)\cc.opt + @echo compiling $< + $(CC) $< -o=$(OBJDIR)\$(@F) @$(OBJDIR)\cc.opt + +$(OBJDIR)/%.o: modules/filters/%.c $(OBJDIR)\cc.opt + @echo compiling $< + $(CC) $< -o=$(OBJDIR)\$(@F) @$(OBJDIR)\cc.opt + +$(OBJDIR)/%.o: modules/loggers/%.c $(OBJDIR)\cc.opt + @echo compiling $< + $(CC) $< -o=$(OBJDIR)\$(@F) @$(OBJDIR)\cc.opt + +$(OBJDIR)/%.o: os/netware/%.c $(OBJDIR)\cc.opt + @echo compiling $< + $(CC) $< -o=$(OBJDIR)\$(@F) @$(OBJDIR)\cc.opt + +$(OBJDIR)/%.o: server/mpm/netware/%.c $(OBJDIR)\cc.opt + @echo compiling $< + $(CC) $< -o=$(OBJDIR)\$(@F) @$(OBJDIR)\cc.opt + +$(OBJDIR)/%.o: srclib/pcre/%.c $(OBJDIR)\cc.opt + @echo compiling $< + $(CC) $< -o=$(OBJDIR)\$(@F) @$(OBJDIR)\cc.opt + +# +# Include the 'tail' makefile that has targets that depend on variables defined +# in this makefile +# + +include $(AP_WORK)\build\NWGNUtail.inc + diff --git a/ROADMAP b/ROADMAP new file mode 100644 index 0000000000..cd45d6d5b5 --- /dev/null +++ b/ROADMAP @@ -0,0 +1,39 @@ +APACHE 2.1+ ROADMAP: + +Last modified at [$Date: 2001/11/27 05:19:39 $] + +DEFERRRED FOR APACHE 2.1 + + * Source code should follow style guidelines. + OK, we all agree pretty code is good. Probably best to clean this + up by hand immediately upon branching a 2.1 tree. + Justin's voulenteered to hand-edit the entire source tree ;) + + * revamp the input filter syntax to provide for ordering of + filters created with the Set{Input|Output}Filter and the + Add{Input|Output}Filter directives. A 'relative to filterx' + syntax is definately preferable, but not realistic for 2.0. + + * Platforms that do not support fork (primarily Win32 and AS/400) + Architect start-up code that avoids initializing all the modules + in the parent process on platforms that do not support fork. + Better yet - not only inform the startup of which phase it's in, + but allow the parent 'process' to initialize shared memory, etc, + and create a module-by-module stream to pass to the child, so the + parent can actually arbitrate the important stuff. + + * Replace stat [deferred open] with open/fstat in directory_walk. + Justin, Ian, OtherBill all interested in this. Implies setting up + the apr_file_t member in request_rec, and having all modules use + that file, and allow the cleanup to close it [if it isn't a shared, + cached file handle.] + + * Refactor auth into auth protocols and auth database stores. + Many interested hackers, too destabilizing for 2.0 inclusion. + +DEFERRRED FOR APACHE 3.0 + + * The Async Apache Server implemented in terms of APR. + [Bill Stoddard's pet project.] + + diff --git a/apachenw.mcp.zip b/apachenw.mcp.zip Binary files differnew file mode 100644 index 0000000000..645099f073 --- /dev/null +++ b/apachenw.mcp.zip diff --git a/build/NWGNUenvironment.inc b/build/NWGNUenvironment.inc new file mode 100644 index 0000000000..76149ad0c8 --- /dev/null +++ b/build/NWGNUenvironment.inc @@ -0,0 +1,286 @@ +# +# Setup needed Tools and Libraries +# + +ifeq "$(wildcard $(AP_WORK)\NWGNUcustom.ini)" "$(AP_WORK)\NWGNUcustom.ini" +include $(AP_WORK)\NWGNUcustom.ini +CUSTOM_INI = $(AP_WORK)\NWGNUcustom.ini +endif + +ifndef VERBOSE +.SILENT: +endif + +# +# Treat like an include +# +ifndef EnvironmentDefined + +# +# simple macros for parsing makefiles +# +EOLIST:= +EMPTY := +COMMA := , +SPACE := $(EMPTY) $(EMPTY) + +# +# Base environment +# + +# Try and handle case issues +ifndef NOVELLLIBC +ifdef NovellLibC +NOVELLLIBC = $(NovellLibC) +endif +endif + +ifndef NOVELLLIBC +NOVELLLIBC = C:/novell/ndk/libc +endif + +# This is a placeholder +# ifndef LDAPSDK +# LDAPSDK = C:/novell/ndk/cldapsdk +# endif + +ifndef METROWERKS +METROWERKS = C:\Program Files\Metrowerks\CodeWarrior +endif + +# If LM_LICENSE_FILE isn't defined, define a variable that can be used to +# restart make with it defined +ifndef LM_LICENSE_FILE +NO_LICENSE_FILE = NO_LICENSE_FILE +endif + +# +# Set the Release type that you want to build, possible values are: +# +# debug - full debug switches are set +# noopt - normal switches are set (default) +# optimized - optimization switches are set + +ifdef reltype +RELEASE=$(reltype) +endif + +ifdef RELTYPE +RELEASE=$(RELTYPE) +endif + +ifdef debug +RELEASE=debug +endif + +ifdef DEBUG +RELEASE=debug +endif + +ifdef optimized +RELEASE=optimized +endif + +ifdef OPTIMIZED +RELEASE=optimized +endif + +ifndef RELEASE +RELEASE = optimized +endif + +ifeq "$(RELEASE)" "debug" +OBJDIR = Debug +endif + +ifeq "$(RELEASE)" "noopt" +OBJDIR = Noopt +endif + +ifeq "$(RELEASE)" "optimized" +OBJDIR = Release +endif + +# +# Setup compiler information +# + +# MetroWerks NLM tools +CC = mwccnlm +CPP = mwccnlm +LINK = mwldnlm +LIB = mwldnlm -type library -w nocmdline + +NOVI = $(NOVELLLIBC)\imports + +INCDIRS = $(NOVELLLIBC)\include;$(NOVELLLIBC)\include\nks;$(NOVELLLIBC)\include\winsock; + +DEFINES = -DNETWARE + +# +# MetroWerks static Libraries + +CLIB3S = $(METROWERKS)\Novell Support\Metrowerks Support\Libraries\Runtime\mwcrtl.lib +MATH3S = +PLIB3S = $(METROWERKS)\Novell Support\Metrowerks Support\Libraries\MSL C++\MWCPP.lib + +# Base compile flags +# and prefix or precompiled header added here. + +# The default flags are as follows: +# +# -c compile only, no link +# -nosyspath treat #include <...> like #include "..." +# -Cpp_exceptions off disable C++ exceptions +# -RTTI off disable C++ run-time typing information +# -align 4 align on 4 byte bounderies +# -w nocmdline disable command-line driver/parser warnings +# -proc PII generate code base on Pentium II instruction set +# -inst mmx use MMX extensions + +CFLAGS = -c -nosyspath -Cpp_exceptions off -RTTI off -align 4 -w nocmdline -proc PII -inst mmx + +# -g generate debugging information +# -O1 level 1 optimizations + +ifeq "$(RELEASE)" "debug" +CFLAGS += -g -O1 +endif + +# -O4,p level 4 optimizations, optimize for speed +ifeq "$(RELEASE)" "optimized" +CFLAGS += -O4,p +endif + +# -prefix pre_nw.h #include pre_nw.h for all files + +CFLAGS += -prefix pre_nw.h + + +PATH:=$(PATH);$(METROWERKS)\bin;$(METROWERKS)\Other Metrowerks Tools\Command Line Tools + +# +# Declare major project deliverables output directories here +# + +ifdef DEST +INSTALL = $(DEST) +ifeq (\, $(findstring \,$(INSTALL))) +INSTDIRS = $(DEST) +endif +endif + +ifdef dest +INSTALL = $(dest) +ifeq (\, $(findstring \,$(INSTALL))) +INSTDIRS = $(dest) +endif +endif + +ifndef INSTALL +INSTALL = $(AP_WORK)\..\Dist +INSTDIRS = $(AP_WORK)\..\Dist +endif + +INSTDEVDIRS := \ + $(INSTDIRS) \ + $(INSTALL)\Apache2\include \ + $(INSTALL)\Apache2\lib \ + +INSTDIRS += \ + $(INSTALL)\Apache2 \ + $(INSTALL)\Apache2\cgi-examples \ + $(INSTALL)\Apache2\conf \ + $(INSTALL)\Apache2\error \ + $(INSTALL)\Apache2\error\include \ + $(INSTALL)\Apache2\htdocs \ + $(INSTALL)\Apache2\icons \ + $(INSTALL)\Apache2\icons\small \ + $(INSTALL)\Apache2\logs \ + $(INSTALL)\Apache2\man \ + $(INSTALL)\Apache2\manual \ + $(INSTALL)\Apache2\manual\developer \ + $(INSTALL)\Apache2\manual\faq \ + $(INSTALL)\Apache2\manual\howto \ + $(INSTALL)\Apache2\manual\images \ + $(INSTALL)\Apache2\manual\misc \ + $(INSTALL)\Apache2\manual\mod \ + $(INSTALL)\Apache2\manual\platform \ + $(INSTALL)\Apache2\manual\programs \ + $(INSTALL)\Apache2\manual\search \ + $(INSTALL)\Apache2\manual\ssl \ + $(INSTALL)\Apache2\manual\vhosts \ + $(INSTALL)\Apache2\modules \ + +# +# Declare Command and tool macros here +# + +# Os2LibPath is an extra check to see if we are on NT +ifdef Os2LibPath +OS = Windows_NT +endif + +ifeq "$(OS)" "Windows_NT" +CMD=cmd /C +CHK=cmd /C if exist +CHKNOT=cmd /C if not exist +DEL = del /F +DELTREE = cmd /C rd /s/q +WINNT=1 +else +CMD=command /C +CHK=command /C if exist +CHKNOT=command /C if not exist +DEL = del +DELTREE = deltree /y +endif + + +# +# Setup base C compiler flags +# + +# +# Common directories +# + +STDMOD = $(AP_WORK)/modules +NWOS = $(AP_WORK)/os/netware +SERVER = $(AP_WORK)/server +SRC = $(AP_WORK) +APR = $(AP_WORK)/srclib/apr +APRUTIL = $(AP_WORK)/srclib/apr-util +SUPMOD = $(AP_WORK)/support +PCRE = $(AP_WORK)/srclib/pcre +APRTEST = $(AP_WORK)/srclib/apr/test +HTTPD = $(AP_WORK)/modules/http +XML = $(AP_WORK)/srclib/apr-util/xml + +# +# Internal Libraries +# + +APRLIB = $(APR)/$(OBJDIR)/aprlib.lib +APRUTLIB = $(APRUTIL)/$(OBJDIR)/aprutil.lib +STMODLIB = $(STDMOD)/$(OBJDIR)/stdmod.lib +PCRELIB = $(PCRE/$(OBJDIR)/pcre.lib +NWOSLIB = $(NWOS)/$(OBJDIR)/netware.lib +SERVLIB = $(SERVER)/$(OBJDIR)/server.lib +HTTPDLIB = $(HTTPD)/$(OBJDIR)/httpd.lib +XMLLIB = $(XML)/$(OBJDIR)/xmllib.lib + +# +# Additional general defines +# +VERSION = 2,0,0 + +EnvironmentDefined = 1 +endif # ifndef EnvironmentDefined + +# This is always set so that it will show up in lower directories + +ifdef Path +Path = $(PATH) +endif + diff --git a/build/NWGNUhead.inc b/build/NWGNUhead.inc new file mode 100644 index 0000000000..71855ab3cd --- /dev/null +++ b/build/NWGNUhead.inc @@ -0,0 +1,103 @@ +# +# Obtain the global build environment +# + +include $(AP_WORK)\build\NWGNUenvironment.inc + +# +# Define base targets and rules +# + +TARGETS = libs nlms install clobber_libs clobber_nlms clean installdev + +.PHONY : $(TARGETS) default all help $(NO_LICENSE_FILE) + +# Here is where we will use the NO_LICENSE_FILE variable to see if we need to +# restart the make with it defined + +ifdef NO_LICENSE_FILE + +default: NO_LICENSE_FILE + +all: NO_LICENSE_FILE + +install :: NO_LICENSE_FILE + +installdev :: NO_LICENSE_FILE + +NO_LICENSE_FILE : + $(MAKE) $(MAKECMDGOALS) -f NWGNUmakefile RELEASE=$(RELEASE) DEST="$(INSTALL)" LM_LICENSE_FILE="$(METROWERKS)\license.dat" + +else # LM_LICENSE_FILE must be defined so use the real targets + +default: $(SUBDIRS) libs nlms + +all: $(SUBDIRS) libs nlms install + +$(TARGETS) :: $(SUBDIRS) + +install :: nlms $(INSTDIRS) + +installdev :: $(INSTDEVDIRS) + +$(INSTDIRS) :: + $(CHKNOT) $@\NUL mkdir $@ + +$(INSTDEVDIRS) :: + $(CHKNOT) $@\NUL mkdir $@ + +endif #NO_LICENSE_FILE check + +help : + @echo targets for RELEASE=$(RELEASE): + @echo (default) . . . . libs nlms + @echo all . . . . . . . does everything (libs nlms install) + @echo libs. . . . . . . builds all libs + @echo nlms. . . . . . . builds all nlms + @echo install . . . . . builds libs and nlms and copies install files to + @echo "$(INSTALL)" + @echo clean . . . . . . deletes $(OBJDIR) dirs, *.err, and *.map + @echo clobber_all . . . deletes all possible output from the make + @echo clobber_install . deletes all files in $(INSTALL) + @$(CMD) echo. + @echo Multiple targets can be used on a single nmake command line - + @echo (i.e. $(MAKE) clean all) + @$(CMD) echo. + @echo You can also specify RELEASE=debug, RELEASE=noopt, or RELEASE=optimized + @echo The default is RELEASE=optimized + +clobber_all :: clean clobber_install + +clobber_install :: + -$(DELTREE) $(INSTALL) 2>NUL + +# +# build recursive targets +# + +$(SUBDIRS) : FORCE +ifneq "$(MAKECMDGOALS)" "clean" + $(CMD) echo. + @echo Building $(CURDIR)/$@ +endif + $(MAKE) -C $@ $(MAKECMDGOALS) -f NWGNUmakefile RELEASE=$(RELEASE) DEST="$(INSTALL)" LM_LICENSE_FILE="$(LM_LICENSE_FILE)" + $(CMD) echo. + +FORCE: + +# +# Standard targets +# + +clean :: $(SUBDIRS) + @echo Cleaning up $(CURDIR) + -$(DELTREE) $(OBJDIR) 2> NUL + $(CHK) *.err $(DEL) *.err + $(CHK) *.map $(DEL) *.map + $(CHK) *.d $(DEL) *.d + $(CHK) *.tmp $(DEL) *.tmp + -$(DELTREE) $(OBJDIR) 2> NUL + +$(OBJDIR) :: + $(CHKNOT) $(OBJDIR)\nul mkdir $(OBJDIR) + diff --git a/build/NWGNUmakefile b/build/NWGNUmakefile new file mode 100644 index 0000000000..deeef84fa2 --- /dev/null +++ b/build/NWGNUmakefile @@ -0,0 +1,80 @@ +# +# Declare the sub-directories to be built here +# + +SUBDIRS = \ + $(EOLIST) + +# +# Get the 'head' of the build environment. This includes default targets and +# paths to tools +# + +include $(AP_WORK)\build\NWGNUhead.inc + +# +# build this level's files + +FILES_prebuild_headers = \ + $(APR)/include/apr.h \ + $(APRUTIL)/include/apu.h \ + $(APRUTIL)/include/apr_ldap.h \ + $(PCRE)/config.h \ + $(PCRE)/pcre.h \ + $(EOLIST) + +nlms :: $(NWOS)/httpd.imp + +$(NWOS)/httpd.imp : make_nw_export.awk nw_export.i + @echo Generating $(subst /,\,$@) + awk -f make_nw_export.awk nw_export.i | sort >$(NWOS)/httpd.imp + +nw_export.i : nw_export.inc $(FILES_prebuild_headers) cc.opt + @echo Generating $(subst /,\,$@) + $(CC) $< @cc.opt + +cc.opt : NWGNUmakefile $(AP_WORK)\build\NWGNUenvironment.inc $(AP_WORK)\build\NWGNUtail.inc $(AP_WORK)\build\NWGNUhead.inc + $(CHK) $@ $(DEL) $@ + @echo -P >> $@ + @echo -EP >> $@ + @echo -nosyspath >> $@ + @echo -w nocmdline >> $@ + @echo -DNETWARE >> $@ + @echo -DCORE_PRIVATE >> $@ + @echo -I..\include >> $@ + @echo -I..\modules\http >> $@ + @echo -I..\os\netware >> $@ + @echo -I..\server\mpm\netware >> $@ + @echo -I..\srclib\apr\include >> $@ + @echo -I..\srclib\apr-util\include >> $@ + @echo -ir $(NOVELLLIBC) >> $@ + +$(APR)/include/%.h: $(subst /,\,$(APR))\include\%.hnw + @echo Creating $(subst /,\,$@) + copy $< $(subst /,\,$(APR))\include\$(@F) + +$(APRUTIL)/include/%.h: $(subst /,\,$(APRUTIL))\include\%.hnw + @echo Creating $(subst /,\,$@) + copy $< $(subst /,\,$(APRUTIL))\include\$(@F) + +$(PCRE)/%.h: $(subst /,\,$(PCRE))\%.hw + @echo Creating $(subst /,\,$@) + copy $< $(subst /,\,$(PCRE))\$(@F) + +# +# You can use this target if all that is needed is to copy files to the +# installation area +# +install :: nlms FORCE + + +clean :: + $(CHK) nw_export.i $(DEL) nw_export.i + $(CHK) cc.opt $(DEL) cc.opt + $(CHK) $(subst /,\,$(APR))\include\apr.h $(DEL) $(subst /,\,$(APR))\include\apr.h + $(CHK) $(subst /,\,$(APRUTIL))\include\apu.h $(DEL) $(subst /,\,$(APRUTIL))\include\apu.h + $(CHK) $(subst /,\,$(APRUTIL))\include\apr_ldap.h $(DEL) $(subst /,\,$(APRUTIL))\include\apr_ldap.h + $(CHK) $(subst /,\,$(PCRE))\config.h $(DEL) $(subst /,\,$(PCRE))\config.h + $(CHK) $(subst /,\,$(PCRE))\pcre.h $(DEL) $(subst /,\,$(PCRE))\pcre.h + $(CHK) $(subst /,\,$(NWOS))\httpd.imp $(DEL) $(subst /,\,$(NWOS))\httpd.imp + diff --git a/build/NWGNUtail.inc b/build/NWGNUtail.inc new file mode 100644 index 0000000000..015f197cbc --- /dev/null +++ b/build/NWGNUtail.inc @@ -0,0 +1,287 @@ +# +# This contains final targets and should be included at the end of any +# NWGNUmakefile file +# + +# +# If we are going to create an nlm, make sure we have assigned variables to +# use during the link. +# +echo NLM_NAME=$(NLM_NAME) +ifndef NLM_NAME +NLM_NAME = $(TARGET_nlm) +endif + +ifndef NLM_DESCRIPTION +NLM_DESCRIPTION = $(NLM_NAME) +endif + +ifndef NLM_THREAD_NAME +NLM_THREAD_NAME = $(NLM_NAME) Thread +endif + +# +# Create dependency lists based on the files available +# + +CCOPT_DEPENDS = \ + $(AP_WORK)\build\NWGNUhead.inc \ + $(AP_WORK)\build\NWGNUenvironment.inc \ + $(AP_WORK)\build\NWGNUtail.inc \ + NWGNUmakefile \ + $(CUSTOM_INI) \ + $(EOLIST) + +CPPOPT_DEPENDS = \ + $(AP_WORK)\build\NWGNUhead.inc \ + $(AP_WORK)\build\NWGNUenvironment.inc \ + $(AP_WORK)\build\NWGNUtail.inc \ + NWGNUmakefile \ + $(CUSTOM_INI) \ + $(EOLIST) + +$(NLM_NAME)_LINKOPT_DEPENDS = \ + $(TARGET_lib) \ + $(AP_WORK)\build\NWGNUenvironment.inc \ + NWGNUmakefile \ + $(AP_WORK)\build\NWGNUtail.inc \ + $(CUSTOM_INI) \ + $(EOLIST) + +ifeq "$(words $(strip $(TARGET_lib)))" "1" +LIB_NAME = $(basename $(notdir $(TARGET_lib))) +$(LIB_NAME)_LIBLST_DEPENDS = \ + $(FILES_lib_objs) \ + $(AP_WORK)\build\NWGNUenvironment.inc \ + NWGNUmakefile \ + $(AP_WORK)\build\NWGNUtail.inc \ + $(CUSTOM_INI) \ + $(EOLIST) +endif + +ifeq "$(wildcard NWGNU$(LIB_NAME))" "NWGNU$(LIB_NAME)" +$(LIB_NAME)_LIBLST_DEPENDS += NWGNU$(LIB_NAME) +endif + +ifeq "$(wildcard NWGNU$(NLM_NAME))" "NWGNU$(NLM_NAME)" +$(NLM_NAME)_LINKOPT_DEPENDS += NWGNU$(NLM_NAME) +CCOPT_DEPENDS += NWGNU$(NLM_NAME) +CPPOPT_DEPENDS += NWGNU$(NLM_NAME) +endif + +# +# Generic compiler rules +# + +$(OBJDIR)/%.o: %.c $(OBJDIR)\cc.opt + @echo Compiling $< + $(CC) $< -o=$(OBJDIR)\$(@F) @$(OBJDIR)\cc.opt + +$(OBJDIR)\cc.opt: $(CCOPT_DEPENDS) + $(CHK) $@ $(DEL) $@ + @echo Generating $@ +ifneq "$(strip $(CFLAGS))" "" + @echo $(CFLAGS) >> $@ +endif +ifneq "$(strip $(XCFLAGS))" "" + @echo $(XCFLAGS) >> $@ +endif +ifneq "$(strip $(XINCDIRS))" "" + @echo $(foreach xincdir,$(strip $(subst ;,$(SPACE),$(XINCDIRS))),-I$(xincdir)) >> $@ +endif +ifneq "$(strip $(INCDIRS))" "" + @echo $(foreach incdir,$(strip $(subst ;,$(SPACE),$(INCDIRS))),-I$(incdir)) >> $@ +endif +ifneq "$(strip $(DEFINES))" "" + @echo $(DEFINES) >> $@ +endif +ifneq "$(strip $(XDEFINES))" "" + @echo $(XDEFINES) >> $@ +endif + +$(OBJDIR)/%.o: %.cpp $(OBJDIR)\cpp.opt + @echo Compiling $< + $(CPP) $< -o=$(OBJDIR)\$(@F) @$(OBJDIR)\cpp.opt + +$(OBJDIR)\cpp.opt: $(CPPOPT_DEPENDS) + $(CHK) $@ $(DEL) $@ + @echo Generating $@ +ifneq "$(strip $(CFLAGS))" "" + @echo $(CFLAGS) >> $@ +endif +ifneq "$(strip $(XCFLAGS))" "" + @echo $(XCFLAGS) >> $@ +endif +ifneq "$(strip $(XINCDIRS))" "" + @echo $(foreach xincdir,$(strip $(subst ;,$(SPACE),$(XINCDIRS))),-I$(xincdir)) >> $@ +endif +ifneq "$(strip $(INCDIRS))" "" + @echo $(foreach incdir,$(strip $(subst ;,$(SPACE),$(INCDIRS))),-I$(incdir)) >> $@ +endif +ifneq "$(strip $(DEFINES))" "" + @echo $(DEFINES) >> $@ +endif +ifneq "$(strip $(XDEFINES))" "" + @echo $(XDEFINES) >> $@ +endif + +# +# Rules to build libraries +# + +# If we only have one target library then build it + +ifeq "$(words $(strip $(TARGET_lib)))" "1" + +$(TARGET_lib) : $(OBJDIR)\$(LIB_NAME)_lib.lst + @echo Generating $@ + $(CHK) $(OBJDIR)\$(@F) $(DEL) $(OBJDIR)\$(@F) + $(LIB) -o $(OBJDIR)\$(@F) @$? + +$(OBJDIR)\$(LIB_NAME)_lib.lst: $($(LIB_NAME)_LIBLST_DEPENDS) + $(CHK) $@ $(DEL) $@ + @echo Generating $@ +ifneq "$(strip $(FILES_lib_objs))" "" + @echo $(foreach objfile,$(FILES_lib_objs),$(subst /,\,$(objfile)) ) >> $@ +endif + +else # We must have more than one target library so load the individual makefiles + +$(OBJDIR)/%.lib: NWGNU% $(AP_WORK)\build\NWGNUhead.inc $(AP_WORK)\build\NWGNUtail.inc $(AP_WORK)\build\NWGNUenvironment.inc FORCE + @echo Calling $< + $(MAKE) -f $< $(MAKECMDGOALS) RELEASE=$(RELEASE) + +endif + +# +# Rules to build nlms. +# + +vpath libcpre.o $(NOVELLLIBC)\imports + +# If we only have one target NLM then build it +ifeq "$(words $(strip $(TARGET_nlm)))" "1" + +$(TARGET_nlm) : $(FILES_nlm_objs) $(FILES_nlm_libs) $(OBJDIR)\$(NLM_NAME)_link.opt + @echo Linking $@ + $(LINK) @$(OBJDIR)\$(NLM_NAME)_link.opt + +# This will force the link option file to be rebuilt if we change the +# corresponding makefile + +$(OBJDIR)\$(NLM_NAME)_link.opt : $($(NLM_NAME)_LINKOPT_DEPENDS) + $(CHK) $(OBJDIR)\$(@F) $(DEL) $(OBJDIR)\$(@F) + $(CHK) $(OBJDIR)\$(NLM_NAME)_link.def $(DEL) $(OBJDIR)\$(NLM_NAME)_link.def + @echo Generating $@ + @echo -warnings off >> $@ + @echo -zerobss >> $@ + @echo -desc "$(NLM_DESCRIPTION)" >> $@ + @echo -o $(TARGET_nlm) >> $@ +ifneq "$(FILE_nlm_copyright)" "" + @-type $(FILE_nlm_copyright) >> $@ +endif +ifeq "$(RELEASE)" "debug" + @echo -g >> $@ + @echo -sym internal >> $@ + @echo -sym codeview4 >> $@ + @echo -osym $(OBJDIR)\$(NLM_NAME).sym >> $@ +else + @echo -sym internal >> $@ +endif + @echo -screenname "Apache for NetWare" >> $@ +ifneq "$(NLM_VERSION)" "" + @echo -nlmversion=$(NLM_VERSION) >> $@ +else + @echo -nlmversion=$(VERSION) >> $@ +endif + @echo -l $(NWOS) >> $@ + @echo -l $(AP)/$(OBJDIR) >> $@ + @echo -l $(APR)/$(OBJDIR) >> $@ + @echo -l $(APRUTIL)/$(OBJDIR) >> $@ + @echo -l $(PCRE)/$(OBJDIR) >> $@ + @echo -l $(HTTPD)/$(OBJDIR) >> $@ + @echo -l $(SERVER)/$(OBJDIR) >> $@ + @echo -l $(STDMOD)/$(OBJDIR) >> $@ + @echo -l $(NWOS)/$(OBJDIR) >> $@ + @echo -l "$(METROWERKS)/Novell Support/Metrowerks Support/Libraries/Runtime" >> $@ + @echo -l "$(METROWERKS)/Novell Support/Metrowerks Support/Libraries/MSL C++" >> $@ + @echo -l $(NOVELLLIBC)/imports >> $@ +ifneq "$(LDAPSDK)" "" + @echo -l $(LDAPSDK)/lib/nlm >> $@ +endif + @echo -l $(XML)/$(OBJDIR) >> $@ + @echo -nodefaults >> $@ + @echo -map $(OBJDIR)\$(NLM_NAME).map>> $@ + @echo -threadname "$(NLM_THREAD_NAME)" >> $@ +ifneq "$(NLM_STACK_SIZE)" "" + @echo -stacksize $(subst K,000,$(subst k,K,$(strip $(NLM_STACK_SIZE)))) >> $@ +else + @echo -stacksize 64000 >> $@ +endif +ifneq "$(NLM_ENTRY_SYM)" "" + @echo -entry $(NLM_ENTRY_SYM) >> $@ +endif +ifneq "$(NLM_EXIT_SYM)" "" + @echo -exit $(NLM_EXIT_SYM) >> $@ +endif +ifneq "$(NLM_CHECK_SYM)" "" + @echo -check $(NLM_CHECK_SYM) >> $@ +endif +ifneq "$(NLM_FLAGS)" "" + @echo -flags $(NLM_FLAGS) >> $@ +endif +ifneq "$(strip $(FILES_nlm_objs))" "" + @echo $(foreach objfile,$(strip $(FILES_nlm_objs)),$(subst /,\,$(objfile))) >> $@ +endif +ifneq "$(FILES_nlm_libs)" "" + @echo $(foreach libfile, $(notdir $(strip $(FILES_nlm_libs))),-l$(subst /,\,$(libfile))) >> $@ +endif + @echo -commandfile $(OBJDIR)\$(NLM_NAME)_link.def >> $@ +ifneq "$(FILE_nlm_msg)" "" + @echo Messages $(FILE_nlm_msg) >> $(OBJDIR)\$(NLM_NAME)_link.def +endif +ifneq "$(FILE_nlm_hlp)" "" + @echo Help $(FILE_nlm_hlp) >> $(OBJDIR)\$(NLM_NAME)_link.def +endif +ifneq "$(FILES_nlm_modules)" "" + @echo module $(foreach module,$(subst $(SPACE),$(COMMA),$(strip $(FILES_nlm_modules))),$(subst /,\,$(module))) >> $(OBJDIR)\$(NLM_NAME)_link.def +endif +ifneq "$(FILES_nlm_Ximports)" "" + @echo Import $(foreach import,$(subst $(SPACE),$(COMMA),$(strip $(FILES_nlm_Ximports))),$(subst /,\,$(import))) >> $(OBJDIR)\$(NLM_NAME)_link.def +endif +ifneq "$(FILES_nlm_exports)" "" + @echo Export $(foreach export,$(subst $(SPACE),$(COMMA),$(strip $(FILES_nlm_exports))),$(subst /,\,$(export))) >> $(OBJDIR)\$(NLM_NAME)_link.def +endif +ifneq "$(strip $(XLFLAGS))" "" + @echo $(XLFLAGS) >> $(OBJDIR)\$(NLM_NAME)_link.def +endif + +# if APACHE_UNIPROC is defined, don't include XDCData +ifndef APACHE_UNIPROC +ifneq "$(string $(XDCDATA))" "" + @echo XDCData $(XDCDATA) >> $(OBJDIR)\$(NLM_NAME)_link.def +else + @echo XDCData $(NWOS)\apache.xdc >> $(OBJDIR)\$(NLM_NAME)_link.def +endif +endif + +else # more than one target so look for individual makefiles. + +# Only include these if NO_LICENSE_FILE isn't set to prevent excessive +# recursion + +ifndef NO_LICENSE_FILE + +$(OBJDIR)/%.nlm: NWGNU% $(AP_WORK)\build\NWGNUhead.inc $(AP_WORK)\build\NWGNUtail.inc $(AP_WORK)\build\NWGNUenvironment.inc $(CUSTOM_INI) FORCE + @echo Calling $< + $(MAKE) -f $< $(MAKECMDGOALS) RELEASE=$(RELEASE) + $(CMD) echo. + +else + +$(TARGET_nlm): + +endif # NO_LICENSE_FILE + +endif + diff --git a/build/install-bindist.sh.in b/build/install-bindist.sh.in new file mode 100755 index 0000000000..0c8a23ed71 --- /dev/null +++ b/build/install-bindist.sh.in @@ -0,0 +1,130 @@ +#!/bin/sh +# +# Usage: install-bindist.sh [ServerRoot] +# This script installs the Apache binary distribution and +# was automatically created by binbuild.sh. + +lmkdir() +{ + path="" + dirs=`echo $1 | sed -e 's%/% %g'` + mode=$2 + + set -- ${dirs} + + for d in ${dirs} + do + path="${path}/$d" + if test ! -d "${path}" ; then + mkdir ${path} + if test $? -ne 0 ; then + echo "Failed to create directory: ${path}" + exit 1 + fi + chmod ${mode} ${path} + fi + done +} + +lcopy() +{ + from=$1 + to=$2 + dmode=$3 + fmode=$4 + + test -d ${to} || lmkdir ${to} ${dmode} + (cd ${from} && tar -cf - *) | (cd ${to} && tar -xf -) + + if test "X${fmode}" != X ; then + find ${to} -type f -print | xargs chmod ${fmode} + fi + if test "X${dmode}" != X ; then + find ${to} -type d -print | xargs chmod ${dmode} + fi +} + +## +## determine path to (optional) Perl interpreter +## +PERL=no-perl5-on-this-system +perls='perl5 perl' +path=`echo $PATH | sed -e 's/:/ /g'` + +for dir in ${path} ; do + for pperl in ${perls} ; do + if test -f "${dir}/${pperl}" ; then + if `${dir}/${pperl} -v | grep 'version 5\.' >/dev/null 2>&1` ; then + PERL="${dir}/${pperl}" + break + fi + fi + done +done + +if [ .$1 = . ] +then + SR=@default_dir@ +else + SR=$1 +fi +echo "Installing binary distribution for platform i686-pc-linux" +echo "into directory $SR ..." +lmkdir $SR 755 +lmkdir $SR/proxy 750 +lmkdir $SR/logs 750 +lcopy bindist/man $SR/man 755 644 +if [ -d bindist/modules ] +then + lcopy bindist/modules $SR/modules 750 750 +fi +lcopy bindist/include $SR/include 755 644 +lcopy bindist/icons $SR/icons 755 644 +lcopy bindist/cgi-bin $SR/cgi-bin 750 750 +lcopy bindist/bin $SR/bin 750 750 +if [ -d $SR/conf ] +then + echo "[Preserving existing configuration files.]" + cp bindist/conf/*-std.conf $SR/conf/ +else + lcopy bindist/conf $SR/conf 750 640 + sed -e "s%@default_dir@%$SR%" $SR/conf/httpd-std.conf > $SR/conf/httpd.conf +fi +if [ -d $SR/htdocs ] +then + echo "[Preserving existing htdocs directory.]" +else + lcopy bindist/htdocs $SR/htdocs 755 644 +fi +if [ -d $SR/error ] +then + echo "[Preserving existing error documents directory.]" +else + lcopy bindist/error $SR/error 755 644 +fi + +sed -e "s;^#!/.*;#!$PERL;" -e "s;\@prefix\@;$SR;" -e "s;\@sbindir\@;$SR/bin;" \ + -e "s;\@libexecdir\@;$SR/libexec;" -e "s;\@includedir\@;$SR/include;" \ + -e "s;\@sysconfdir\@;$SR/conf;" bindist/bin/apxs > $SR/bin/apxs +sed -e "s;^#!/.*;#!$PERL;" bindist/bin/dbmmanage > $SR/bin/dbmmanage +sed -e "s%@default_dir@%$SR%" \ + -e "s%^HTTPD=.*$%HTTPD=\"$SR/bin/httpd -d $SR\"%" bindist/bin/apachectl > $SR/bin/apachectl + +echo "Ready." +echo " +--------------------------------------------------------+" +echo " | You now have successfully installed the Apache @ver@ |" +echo " | HTTP server. To verify that Apache actually works |" +echo " | correctly you should first check the (initially |" +echo " | created or preserved) configuration files: |" +echo " | |" +echo " | $SR/conf/httpd.conf" +echo " | |" +echo " | You should then be able to immediately fire up |" +echo " | Apache the first time by running: |" +echo " | |" +echo " | $SR/bin/apachectl start " +echo " | |" +echo " | Thanks for using Apache. The Apache Group |" +echo " | http://www.apache.org/ |" +echo " +--------------------------------------------------------+" +echo " " diff --git a/build/instdso.sh b/build/instdso.sh new file mode 100755 index 0000000000..c7b5d61564 --- /dev/null +++ b/build/instdso.sh @@ -0,0 +1,54 @@ +#!/bin/sh +# +# instdso.sh - install Apache DSO modules +# +# usually this just passes through to libtool but on a few +# platforms libtool doesn't install DSOs exactly like we'd +# want so more effort is required + +if test "$#" != "3"; then + echo "wrong number of arguments to instdso.sh" + echo "Usage: instdso.sh SH_LIBTOOL-value dso-name path-to-modules" + exit 1 +fi + +SH_LIBTOOL=`echo $1 | sed -e 's/^SH_LIBTOOL=//'` +DSOARCHIVE=$2 +TARGETDIR=$3 +DSOBASE=`echo $DSOARCHIVE | sed -e 's/\.la$//'` +TARGET_NAME="$DSOBASE.so" + +# special logic for systems where libtool doesn't install +# the DSO exactly like we'd want + +SYS=`uname -s` +case $SYS in + AIX) + # on AIX, shared libraries remain in storage even when + # all processes using them have exited; standard practice + # prior to installing a shared library is to rm -f first + CMD="rm -f $TARGETDIR/$TARGET_NAME" + echo $CMD + $CMD || exit $? + CMD="cp .libs/lib$DSOBASE.so.0 $TARGETDIR/$TARGET_NAME" + echo $CMD + $CMD || exit $? + ;; + HP-UX) + CMD="cp .libs/$DSOBASE.sl $TARGETDIR/$TARGET_NAME" + echo $CMD + $CMD || exit $? + ;; + OSF1) + CMD="cp .libs/lib$DSOBASE.so $TARGETDIR/$TARGET_NAME" + echo $CMD + $CMD || exit $? + ;; + *) + CMD="$SH_LIBTOOL --mode=install cp $DSOARCHIVE $TARGETDIR" + echo $CMD + $CMD || exit $? + ;; +esac + +exit 0 diff --git a/build/make_nw_export.awk b/build/make_nw_export.awk new file mode 100644 index 0000000000..317e4bc7c3 --- /dev/null +++ b/build/make_nw_export.awk @@ -0,0 +1,113 @@ +# Based on apr's make_export.awk, which is +# based on Ryan Bloom's make_export.pl + +# List of functions that we don't support, yet?? +/apr_##name##_set_inherit/{next} +/apr_##name##_unset_inherit/{next} +/apr_compare_groups/{next} +/apr_compare_users/{next} +/apr_find_pool/{next} +/apr_generate_random_bytes/{next} +/apr_lock_create_np/{next} +/apr_md5_set_xlate/{next} +/apr_mmap_create/{next} +/apr_mmap_delete/{next} +/apr_mmap_offset/{next} +/apr_os_thread_get/{next} +/apr_os_thread_put/{next} +/apr_pool_free_blocks_num_bytes/{next} +/apr_pool_join/{next} +/apr_pool_num_bytes/{next} +/apr_proc_mutex_child_init/{next} +/apr_proc_mutex_create/{next} +/apr_proc_mutex_create_np/{next} +/apr_proc_mutex_destroy/{next} +/apr_proc_mutex_lock/{next} +/apr_proc_mutex_trylock/{next} +/apr_proc_mutex_unlock/{next} +/apr_proc_other_child_check/{next} +/apr_proc_other_child_read/{next} +/apr_proc_other_child_register/{next} +/apr_proc_other_child_unregister/{next} +/apr_sendfile/{next} +/apr_shm_avail/{next} +/apr_shm_calloc/{next} +/apr_shm_destroy/{next} +/apr_shm_free/{next} +/apr_shm_init/{next} +/apr_shm_malloc/{next} +/apr_shm_name_get/{next} +/apr_shm_name_set/{next} +/apr_shm_open/{next} +/apr_signal/{next} +/apr_signal_thread/{next} +/apr_socket_from_file/{next} +/apr_thread_once/{next} +/apr_thread_once_init/{next} +/apr_xlate_close/{next} +/apr_xlate_conv_buffer/{next} +/apr_xlate_conv_byte/{next} +/apr_xlate_conv_char/{next} +/apr_xlate_get_sb/{next} +/apr_xlate_open/{next} +/apr_brigade_consume/{next} +/apr_bucket_mmap_create/{next} +/apr_bucket_mmap_make/{next} +/apr_bucket_type_mmap/{next} +/apr_md4_set_xlate/{next} +#/XML_ParserFree/{next} +#/XML_ParserCreate/{next} +#/XML_SetUserData/{next} +#/XML_SetElementHandler/{next} +#/XML_SetCharacterDataHandler/{next} +#/XML_Parse/{next} +#/XML_GetErrorCode/{next} +#/XML_ErrorString/{next} + + +function add_symbol (sym_name) { + if (count) { + found++ + } +# for (i = 0; i < count; i++) { +# line = line "\t" +# } + line = line sym_name ",\n" + + if (count == 0) { + printf(" %s", line) + line = "" + } +} + +/^[ \t]*AP[RU]?_DECLARE[^(]*[(][^)]*[)]([^ ]* )*[^(]+[(]/ { + sub("[ \t]*AP[RU]?_DECLARE[^(]*[(][^)]*[)][ \t]*", "") + sub("[(].*", "") + sub("([^ ]* (^([ \t]*[(])))+", "") + + add_symbol($0) + next +} + +/^[ \t]*AP_DECLARE_HOOK[^(]*[(][^)]*[)]/ { + split($0, args, ",") + symbol = args[2] + sub("^[ \t]+", "", symbol) + sub("[ \t]+$", "", symbol) + + add_symbol("ap_hook_" symbol) + add_symbol("ap_hook_get_" symbol) + add_symbol("ap_run_" symbol) + next +} + +/^[ \t]*AP[RU]?_DECLARE_DATA .*;$/ { + varname = $NF; + gsub( /[*;]/, "", varname); + gsub( /\[.*\]/, "", varname); + add_symbol(varname); +} + +#END { +# printf(" %s", line) +#} diff --git a/build/mkconfNW.awk b/build/mkconfNW.awk new file mode 100644 index 0000000000..3ec7a51bb1 --- /dev/null +++ b/build/mkconfNW.awk @@ -0,0 +1,59 @@ + + +BEGIN { + + A["ServerRoot"] = "SYS:\APACHE2" + A["Port"] = "80" + +} + +/@@LoadModule@@/ { + print "#LoadModule auth_anon_module modules/authanon.nlm" + print "#LoadModule auth_dbm_module modules/authdbm.nlm" + print "#LoadModule auth_digest_module modules/digest.nlm" + print "#LoadModule cern_meta_module modules/cernmeta.nlm" + print "#LoadModule dav_module modules/mod_dav.nlm" + print "#LoadModule dav_fs_module modules/moddavfs.nlm" + print "#LoadModule expires_module modules/expires.nlm" + print "#LoadModule file_cache_module modules/filecach.nlm" + print "#LoadModule headers_module modules/headers.nlm" + print "#LoadModule info_module modules/info.nlm" + print "#LoadModule mime_magic_module modules/mimemagi.nlm" + print "#LoadModule proxy_module modules/proxy.nlm" + print "#LoadModule proxy_connect_module modules/proxy_connect.nlm" + print "#LoadModule proxy_http_module modules/proxy_http.nlm" + print "#LoadModule proxy_ftp_module modules/proxy_ftp.nlm" + print "#LoadModule rewrite_module modules/rewrite.nlm" + print "#LoadModule speling_module modules/speling.nlm" + print "#LoadModule status_module modules/status.nlm" + print "#LoadModule unique_id_module modules/uniqueid.nlm" + print "#LoadModule usertrack_module modules/usertrk.nlm" + print "#LoadModule vhost_alias_module modules/vhost.nlm" + print "" + next +} + +match ($0,/@@.*@@/) { + s=substr($0,RSTART+2,RLENGTH-4) +# substr($0,RSTART,RLENGTH) = A[s] + sub(/@@.*@@/,A[s],$0) +# print +} + + +{ + print +} + + +END { + print + print "#" + print "# SecureListen: Allows you to securely bind Apache to specific IP addresses " + print "# and/or ports." + print "#" + print "# Change this to SecureListen on specific IP addresses as shown below to " + print "# prevent Apache from glomming onto all bound IP addresses (0.0.0.0)" + print "#" + print "#SecureListen 443 \"SSL CertificateIP\"" +} diff --git a/build/nw_export.inc b/build/nw_export.inc new file mode 100644 index 0000000000..27185ead30 --- /dev/null +++ b/build/nw_export.inc @@ -0,0 +1,47 @@ +/* Must include ap_config.h first so that we can redefine + the standard prototypes macros after it messes with + them. */ +#include "ap_config.h" + +/* Define all of the standard prototype macros as themselves + so that httpd.h will not mess with them. This allows + them to pass untouched so that the AWK script can pick + them out of the preprocessed result file. */ +#define AP_DECLARE AP_DECLARE +#define AP_CORE_DECLARE AP_CORE_DECLARE +#define AP_DECLARE_NONSTD AP_DECLARE_NONSTD +#define AP_CORE_DECLARE_NONSTD AP_CORE_DECLARE_NONSTD +#define AP_DECLARE_HOOK AP_DECLARE_HOOK +#define AP_DECLARE_DATA AP_DECLARE_DATA + +#include "httpd.h" + +/* Preprocess all of the standard HTTPD headers. */ +#include "ap_compat.h" +#include "ap_listen.h" +#include "ap_mmn.h" +#include "ap_mpm.h" +#include "ap_release.h" +#include "http_config.h" +#include "http_connection.h" +#include "http_core.h" +#include "http_log.h" +#include "http_main.h" +#include "http_protocol.h" +#include "http_request.h" +#include "http_vhost.h" +#include "mpm_common.h" +#include "pcreposix.h" +#include "rfc1413.h" +#include "scoreboard.h" +#include "util_cfgtree.h" +#include "util_charset.h" +#include "util_ebcdic.h" +#include "util_filter.h" +/*#include "util_ldap.h"*/ +#include "util_md5.h" +#include "util_script.h" +#include "util_time.h" +#include "util_xml.h" + +#include "mod_core.h" diff --git a/build/prebuildNW.bat b/build/prebuildNW.bat new file mode 100755 index 0000000000..d82be4e6d1 --- /dev/null +++ b/build/prebuildNW.bat @@ -0,0 +1,24 @@ +@echo off +rem # As part of the pre-build process, the utilities GenChars.NLM +rem # (Gen Test Chars) and DFTables.NLM (dftables) must be built, +rem # copied to a NetWare server and run using the following commands: +rem # +rem # genchars >test_char.h +rem # dftables >chartables.c +rem # +rem # The files "sys:\test_chars.h" and "sys:\chartables.c" must be +rem # copied to "httpd\os\netware" on the build machine. + +@echo Fixing up the APR headers +copy ..\srclib\apr\include\apr.hnw ..\srclib\apr\include\apr.h + +@echo Fixing up the APR-Util headers +copy ..\srclib\apr-util\include\apu.h.in ..\srclib\apr-util\include\apu.h + +@echo Fixing up the pcre headers +copy ..\srclib\pcre\config.hw ..\srclib\pcre\config.h +copy ..\srclib\pcre\pcre.hw ..\srclib\pcre\pcre.h + +@echo Generating the import lists... +awk95 -f make_nw_export.awk ..\srclib\apr\include\*.h |sort > ..\os\netware\aprlib.imp +awk95 -f make_nw_export.awk ..\srclib\apr-util\include\*.h |sort > ..\os\netware\aprutil.imp
\ No newline at end of file diff --git a/docs/error/README b/docs/error/README new file mode 100644 index 0000000000..6856b7c7ee --- /dev/null +++ b/docs/error/README @@ -0,0 +1,27 @@ + + Multi Language Custom Error Documents + ------------------------------------- + + The 'error' directory in the document root directory contains HTTP error + messages in multiple languages. If the preferred language of client is + available it is selected automatically via the MultiViews feature. + You may configure the design and markup of the documents by modifying + the HTML files in the directory '/error/includes', especially the + file 'config.html'. + + + Supported Languages: + + +------------------+------------------------------------------+ + | Language | Contributed by | + +------------------+------------------------------------------+ + | English (en) | Lars Eilebrecht | + | German (de) | Lars Eilebrecht | + | Spanish (es) | Karla Quintero | + | French (fr) | Cecile de Crecy | + +------------------+------------------------------------------+ + (Please see http://httpd.apache.org/docs-project/ if you would + like to contribute the pages in an additional language.) + + + Copyright (c) 2001 The Apache Software Foundation. All rights reserved. diff --git a/docs/manual/developer/filters.html b/docs/manual/developer/filters.html new file mode 100644 index 0000000000..b8ac610025 --- /dev/null +++ b/docs/manual/developer/filters.html @@ -0,0 +1,168 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <title>Request Processing in Apache 2.0</title> + </head> + <!-- Background white, links blue (unvisited), navy (visited), red (active) --> + + <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" + vlink="#000080" alink="#FF0000"> + <!--#include virtual="header.html" --> + + <h1>How filters work in Apache 2.0</h1> + + <p>Warning - this is a cut 'n paste job from an email: + <022501c1c529$f63a9550$7f00000a@KOJ></p> + +<pre> +There are three basic filter types (each of these is actually broken +down into two categories, but that comes later). + +CONNECTION: Filters of this type are valid for the lifetime of this + connection. + +PROTOCOL: Filters of this type are valid for the lifetime of this + request from the point of view of the client, this means + that the request is valid from the time that the request + is sent until the time that the response is received. + +RESOURCE: Filters of this type are valid for the time that this + content is used to satisfy a request. For simple + requests, this is identical to PROTOCOL, but internal redirects + and sub-requests can change the content without ending + the request. + +It is important to make the distinction between a protocol and a +resource filter. A resource filter is tied to a specific resource, it +may also be tied to header information, but the main binding is to a +resource. If you are writing a filter and you want to know if it is +resource or protocol, the correct question to ask is: "Can this filter +be removed if the request is redirected to a different resource?" If +the answer is yes, then it is a resource filter. If it is no, then it +is most likely a protocol or connection filter. I won't go into +connection filters, because they seem to be well understood. + +With this definition, a few examples might help: +Byterange: We have coded it to be inserted for all +requests, and it is removed if not used. Because this filter is active +at the beginning of all requests, it can not be removed if it is +redirected, so this is a protocol filter. + +http_header: This filter actually writes the headers to the +network. This is obviously a required filter (except in the asis case +which is special and will be dealt with below) and so it is a protocol +filter. + +Deflate: The administrator configures this filter based on +which file has been requested. If we do an internal redirect from an +autoindex page to an index.html page, the deflate filter may be added or +removed based on config, so this is a resource filter. + +The further breakdown of each category into two more filter types is +strictly for ordering. We could remove it, and only allow for one +filter type, but the order would tend to be wrong, and we would need to +hack things to make it work. Currently, the RESOURCE filters only have +one filter type, but that should change. + +How are filters inserted? +This is actually rather simple in theory, but the code is +complex. First of all, it is important that everybody realize that +there are three filter lists for each request, but they are all +concatenated together. So, the first list is r->output_filters, then +r->proto_output_filters, and finally r->connection->output_filters. +These correspond to the RESOURCE, PROTOCOL, and CONNECTION filters +respectively. The problem previously, was that we used a singly linked +list to create the filter stack, and we started from the "correct" +location. This means that if I had a RESOURCE filter on the stack, and +I added a CONNECTION filter, the CONNECTION filter would be ignored. +This should make sense, because we would insert the connection filter at +the top of the c->output_filters list, but the end of r->output_filters +pointed to the filter that used to be at the front of c->output_filters. +This is obviously wrong. The new insertion code uses a doubly linked +list. This has the advantage that we never lose a filter that has been +inserted. Unfortunately, it comes with a separate set of headaches. + +The problem is that we have two different cases were we use subrequests. +The first is to insert more data into a response. The second is to +replace the existing response with an internal redirect. These are two +different cases and need to be treated as such. + +In the first case, we are creating the subrequest from within a handler +or filter. This means that the next filter should be passed to +make_sub_request function, and the last resource filter in the +sub-request will point to the next filter in the main request. This +makes sense, because the sub-request's data needs to flow through the +same set of filters as the main request. A graphical representation +might help: + +Default_handler --> includes_filter --> byterange --> content_length -> +etc + +If the includes filter creates a sub request, then we don't want the +data from that sub-request to go through the includes filter, because it +might not be SSI data. So, the subrequest adds the following: + +Default_handler --> includes_filter -/-> byterange --> content_length -> etc + / +Default_handler --> sub_request_core + +What happens if the subrequest is SSI data? Well, that's easy, the +includes_filter is a resource filter, so it will be added to the sub +request in between the Default_handler and the sub_request_core filter. + +The second case for sub-requests is when one sub-request is going to +become the real request. This happens whenever a sub-request is created +outside of a handler or filter, and NULL is passed as the next filter to +the make_sub_request function. + +In this case, the resource filters no longer make sense for the new +request, because the resource has changed. So, instead of starting from +scratch, we simply point the front of the resource filters for the +sub-request to the front of the protocol filters for the old request. +This means that we won't lose any of the protocol filters, neither will +we try to send this data through a filter that shouldn't see it. + +The problem is that we are using a doubly-linked list for our filter +stacks now. But, you should notice that it is possible for two lists to +intersect in this model. So, you do you handle the previous pointer? +This is a very difficult question to answer, because there is no "right" +answer, either method is equally valid. I looked at why we use the +previous pointer. The only reason for it is to allow for easier +addition of new servers. With that being said, the solution I chose was +to make the previous pointer always stay on the original request. + +This causes some more complex logic, but it works for all cases. My +concern in having it move to the sub-request, is that for the more +common case (where a sub-request is used to add data to a response), the +main filter chain would be wrong. That didn't seem like a good idea to +me. + +asis: +The final topic. :-) Mod_Asis is a bit of a hack, but the +handler needs to remove all filters except for connection filters, and +send the data. If you are using mod_asis, all other bets are off. + +The absolutely last point is that the reason this code was so hard to +get right, was because we had hacked so much to force it to work. I +wrote most of the hacks originally, so I am very much to blame. +However, now that the code is right, I have started to remove some +hacks. Most people should have seen that the reset_filters and +add_required_filters functions are gone. Those inserted protocol level +filters for error conditions, in fact, both functions did the same +thing, one after the other, it was really strange. Because we don't +lose protocol filters for error cases any more, those hacks went away. +The HTTP_HEADER, Content-length, and Byterange filters are all added in +the insert_filters phase, because if they were added earlier, we had +some interesting interactions. Now, those could all be moved to be +inserted with the HTTP_IN, CORE, and CORE_IN filters. That would make +the code easier to follow. +</pre> + + <!--#include virtual="footer.html" --> + </body> +</html> + diff --git a/docs/manual/mod/allmodules.xml b/docs/manual/mod/allmodules.xml new file mode 100644 index 0000000000..ddf557d601 --- /dev/null +++ b/docs/manual/mod/allmodules.xml @@ -0,0 +1,46 @@ +<modulelist> +<modulefile>core.xml</modulefile> +<modulefile>mod_access.xml</modulefile> +<modulefile>mod_actions.xml</modulefile> +<modulefile>mod_alias.xml</modulefile> +<modulefile>mod_asis.xml</modulefile> +<modulefile>mod_auth.xml</modulefile> +<modulefile>mod_auth_anon.xml</modulefile> +<modulefile>mod_auth_dbm.xml</modulefile> +<modulefile>mod_auth_digest.xml</modulefile> +<modulefile>mod_autoindex.xml</modulefile> +<modulefile>mod_cern_meta.xml</modulefile> +<modulefile>mod_cgi.xml</modulefile> +<modulefile>mod_cgid.xml</modulefile> +<modulefile>mod_charset_lite.xml</modulefile> +<modulefile>mod_dav.xml</modulefile> +<modulefile>mod_deflate.xml</modulefile> +<modulefile>mod_dir.xml</modulefile> +<modulefile>mod_env.xml</modulefile> +<modulefile>mod_example.xml</modulefile> +<modulefile>mod_ext_filter.xml</modulefile> +<modulefile>mod_file_cache.xml</modulefile> +<modulefile>mod_headers.xml</modulefile> +<modulefile>mod_imap.xml</modulefile> +<modulefile>mod_include.xml</modulefile> +<modulefile>mod_info.xml</modulefile> +<modulefile>mod_isapi.xml</modulefile> +<modulefile>mod_log_config.xml</modulefile> +<modulefile>mod_mime.xml</modulefile> +<modulefile>mod_mime_magic.xml</modulefile> +<modulefile>mod_negotiation.xml</modulefile> +<modulefile>mod_proxy.xml</modulefile> +<modulefile>mod_rewrite.xml</modulefile> +<modulefile>mod_setenvif.xml</modulefile> +<modulefile>mod_so.xml</modulefile> +<modulefile>mod_speling.xml</modulefile> +<modulefile>mod_status.xml</modulefile> +<modulefile>mod_suexec.xml</modulefile> +<modulefile>mod_unique_id.xml</modulefile> +<modulefile>mod_userdir.xml</modulefile> +<modulefile>mod_usertrack.xml</modulefile> +<modulefile>mod_vhost_alias.xml</modulefile> +<modulefile>mpm_common.xml</modulefile> +<modulefile>mpm_winnt.xml</modulefile> +<modulefile>prefork.xml</modulefile> +</modulelist>
\ No newline at end of file diff --git a/docs/manual/mod/core.xml b/docs/manual/mod/core.xml new file mode 100644 index 0000000000..2eb6527b2d --- /dev/null +++ b/docs/manual/mod/core.xml @@ -0,0 +1,2480 @@ +<?xml version="1.0"?> +<!DOCTYPE xml:manual [ <!ENTITY nbsp " "> ]> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>core</name> +<status>Core</status> +<description>Core Apache HTTP Server features that are always +available</description> + +<directivesynopsis> +<name>AcceptPathInfo</name> +<description>Controls whether requests can contain trailing pathname information</description> +<syntax>AcceptPathInfo On|Off|Default</syntax> +<default>AcceptPathInfo Default</default> +<contextlist><context>server config</context> +<context>virtual host</context><context>directory</context> +<context>.htaccess</context></contextlist> +<compatibility>Available in Apache 2.0.30 and later</compatibility> + +<usage> + + <p>This directive controls whether requests that contain trailing + pathname information that follows an actual filename (or + non-existent file in an existing directory) will be accepted or + rejected. The trailing pathname information can be made + available to scripts in the PATH_INFO environment variable.</p> + + <p>For example, assume the location <code>/test/</code> points to + a directory that contains only the single file + <code>here.html</code>. Then requests for + <code>/test/here.html/more</code> and + <code>/test/nothere.html/more</code> both collect + <code>/more</code> as PATH_INFO.</p> + + <p>The three possible arguments for the + <directive>AcceptPathInfo</directive> directive are:</p> + <dl> + <dt><code>off</code></dt><dd>A request will only be accepted if it + maps to a literal path that exists. Therefore a request with + trailing pathname information after the true filename such as + <code>/test/here.html/more</code> in the above example will return + a 404 NOT FOUND error.</dd> + + <dt><code>on</code></dt><dd>A request will be accepted if a + leading path component maps to a file that exists. The above + example <code>/test/here.html/more</code> will be accepted if + <code>/test/here.html</code> maps to a valid file.</dd> + + <dt><code>default</code></dt><dd>The treatment of requests with + trailing pathname information is determined by the <a + href="../handler.html">handler</a> responsible for the request. + The core handler for normal files defaults to rejecting PATH_INFO. + Handlers that serve scripts, such as <a + href="mod_cgi.html">cgi-script</a> and <a + href="mod_isapi.html">isapi-isa</a>, generally accept PATH_INFO by + default.</dd> + </dl> + + <p>The primary purpose of the <code>AcceptPathInfo</code> + directive is to allow you to override the handler's choice of + accepting or rejecting PATH_INFO. This override is required, for + example, when you use a <a href="../filter.html">filter</a>, such + as <a href="mod_include.html">INCLUDES</a>, to generate content + based on PATH_INFO. The core handler would usually reject the + request, so you can use the following configuration to enable + such a script:</p> +<example> +<Files "mypaths.shtml"><br /> + Options +Includes<br /> + SetOutputFilter INCLUDES<br /> + AcceptPathInfo on<br /> +</Files> +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>AccessFileName</name> +<description>Sets the name of the .htaccess file</description> +<syntax>AccessFileName <em>filename</em> [<em>filename</em>] ...</syntax> +<default>AccessFileName .htaccess</default> +<contextlist><context>server config</context><context>virtual host</context> +</contextlist> + +<usage> + <p>When returning a document to the client the server looks for + the first existing access control file from this list of names + in every directory of the path to the document, if access + control files are enabled for that directory. For example:</p> + +<example> +AccessFileName .acl +</example> + + <p>before returning the document + <code>/usr/local/web/index.html</code>, the server will read + <code>/.acl</code>, <code>/usr/.acl</code>, + <code>/usr/local/.acl</code> and <code>/usr/local/web/.acl</code> + for directives, unless they have been disabled with</p> + +<example> +<Directory /><br /> + AllowOverride None<br /> +</Directory> +</example> +</usage> +<seealso><directive module="core">AllowOverride</directive></seealso> +<seealso><a href="../configuring.html">Configuration Files</a></seealso> +</directivesynopsis> + +<directivesynopsis> +<name>AddDefaultCharset</name> +<description>Specifies the default character set to be added for a +response without an explicit character set</description> +<syntax>AddDefaultCharset On|Off|<em>charset</em></syntax> +<contextlist><context>server config</context> +<context>virtual host</context><context>directory</context> +<context>.htaccess</context></contextlist> +<default>AddDefaultCharset Off</default> + +<usage> + + <p>This directive specifies the name of the character set that + will be added to any response that does not have any parameter on + the content type in the HTTP headers. This will override any + character set specified in the body of the document via a + <code>META</code> tag. A setting of <code>AddDefaultCharset + Off</code> disables this + functionality. <code>AddDefaultCharset On</code> enables + Apache's internal default charset of <code>iso-8859-1</code> as + required by the directive. You can also specify an alternate + <em>charset</em> to be used. For example:</p> + +<example> + AddDefaultCharset utf-8 +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>AddModule</name> +<syntax>AddModule <em>module</em> [<em>module</em>] ...</syntax> +<contextlist><context>server config</context></contextlist> + +<usage> + <p>The server can have modules compiled in which are not + actively in use. This directive can be used to enable the use + of those modules. The server comes with a pre-loaded list of + active modules; this list can be cleared with the <directive + module="core">ClearModuleList</directive> directive.</p> + + <p>For example:</p> +<example> +AddDefaultCharset utf-8 +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>AllowOverride</name> +<description>Sets the types of directives that are allowed in +.htaccess files</description> +<syntax>AllowOverride All|None|<em>directive-type</em> [<em>directive-type</em>] ...</syntax> +<default>AllowOverride All</default> +<contextlist><context>directory</context></contextlist> + +<usage> + <p>When the server finds an .htaccess file (as specified by <directive + module="core">AccessFileName</directive>) it needs to know + which directives declared in that file can override earlier + access information.</p> + + <p>When this directive is set to <code>None</code>, then + .htaccess files are completely ignored. In this case, the + server will not even attempt to read .htaccess files in the + filesystem.</p> + + <p>When this directive is set to <code>All</code>, then any + directive which has the .htaccess <a + href="directive-dict.html#Context">Context</a> is allowed in + .htaccess files.</p> + + <p>The <em>directive-type</em> can be one of the following + groupings of directives.</p> + + <dl> + <dt>AuthConfig</dt> + + <dd> + + Allow use of the authorization directives (<directive + module="mod_auth_dbm">AuthDBMGroupFile</directive>, + <directive module="mod_auth_dbm">AuthDBMUserFile</directive>, + <directive module="mod_auth">AuthGroupFile</directive>, + <directive module="core">AuthName</directive>, + <directive module="core">AuthType</directive>, <directive + module="mod_auth">AuthUserFile</directive>, <directive + module="core">Require</directive>, <em>etc.</em>).</dd> + + <dt>FileInfo</dt> + + <dd> + Allow use of the directives controlling document types (<directive + module="core">DefaultType</directive>, <directive + module="core">ErrorDocument</directive>, <directive + module="core">ForceType</directive>, <directive + module="mod_negotiation">LanguagePriority</directive>, + <directive module="core">SetHandler</directive>, <directive + module="core">SetInputFilter</directive>, <directive + module="core">SetOutputFilter</directive>, and + <module>mod_mime</module> Add* and Remove* + directives, <em>etc.</em>).</dd> + + <dt>Indexes</dt> + + <dd> + Allow use of the directives controlling directory indexing + (<directive + module="mod_autoindex">AddDescription</directive>, + <directive module="mod_autoindex">AddIcon</directive>, <directive + module="mod_autoindex">AddIconByEncoding</directive>, + <directive module="mod_autoindex">AddIconByType</directive>, + <directive module="mod_autoindex">DefaultIcon</directive>, <directive + module="mod_dir">DirectoryIndex</directive>, <directive + module="mod_autoindex">FancyIndexing</directive>, <directive + module="mod_autoindex">HeaderName</directive>, <directive + module="mod_autoindex">IndexIgnore</directive>, <directive + module="mod_autoindex">IndexOptions</directive>, <directive + module="mod_autoindex">ReadmeName</directive>, + <em>etc.</em>).</dd> + + <dt>Limit</dt> + + <dd> + Allow use of the directives controlling host access (<directive + module="mod_access">Allow</directive>, <directive + module="mod_access">Deny</directive> and <directive + module="mod_access">Order</directive>).</dd> + + <dt>Options</dt> + + <dd> + Allow use of the directives controlling specific directory + features (<directive module="core">Options</directive> and + <directive module="mod_include">XBitHack</directive>).</dd> + </dl> + + <p>Example:</p> + + <example>AllowOverride AuthConfig Indexes</example> +</usage> + +<seealso><directive module="core">AccessFileName</directive></seealso> +<seealso><a href="../configuring.html">Configuration Files</a></seealso> +</directivesynopsis> + +<directivesynopsis> +<name>AuthName</name> +<description>Sets the authorization realm for use in HTTP +authentication</description> +<syntax>AuthName <em>auth-domain</em></syntax> +<contextlist><context>directory</context><context>.htaccess</context> +</contextlist> +<override>AuthConfig</override> + +<usage> + <p>This directive sets the name of the authorization realm for a + directory. This realm is given to the client so that the user + knows which username and password to send. + <directive>AuthName</directive> takes a single argument; if the + realm name contains spaces, it must be enclosed in quotation + marks. It must be accompanied by <directive + module="core">AuthType</directive> and <directive + module="core">Require</directive> directives, and directives such + as <directive module="mod_auth">AuthUserFile</directive> and + <directive module="mod_auth">AuthGroupFile</directive> to + work.</p> + + <p>For example:</p> + + <example>AuthName "Top Secret"</example> + + <p>The string provided for the <code>AuthRealm</code> is what will + appear in the password dialog provided by most browsers.</p> +</usage> +<seealso><a + href="../howto/auth.html">Authentication, Authorization, and + Access Control</a></seealso> +</directivesynopsis> + +<directivesynopsis> +<name>AuthType</name> +<description>Selects the type of user authentication</description> +<syntax>AuthType Basic|Digest</syntax> +<contextlist><context>directory</context><context>.htaccess</context> +<override>AuthConfig</override></contextlist> + +<usage> + <p>This directive selects the type of user authentication for a + directory. Only <code>Basic</code> and <code>Digest</code> are + currently implemented. + + It must be accompanied by <directive + module="core">AuthName</directive> and <directive + module="core">Require</directive> directives, and directives such + as <directive module="mod_auth">AuthUserFile</directive> and + <directive module="mod_auth">AuthGroupFile</directive> to + work.</p> +</usage> +<seealso><a href="../howto/auth.html">Authentication, Authorization, +and Access Control</a></seealso> +</directivesynopsis> + +<directivesynopsis> +<name>ContentDigest</name> +<description>Enables the generation of Content-MD5 HTTP Response +headers</description> +<syntax>ContentDigest on|off</syntax> +<default>ContentDigest off</default> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context> +</contextlist> +<override>Options</override> +<status>Experimental</status> +<compatibility>Available in Apache 1.1 and later</compatibility> + +<usage> + <p>This directive enables the generation of + <code>Content-MD5</code> headers as defined in RFC1864 + respectively RFC2068.</p> + + <p>MD5 is an algorithm for computing a "message digest" + (sometimes called "fingerprint") of arbitrary-length data, with + a high degree of confidence that any alterations in the data + will be reflected in alterations in the message digest.</p> + + <p>The <code>Content-MD5</code> header provides an end-to-end + message integrity check (MIC) of the entity-body. A proxy or + client may check this header for detecting accidental + modification of the entity-body in transit. Example header:</p> +<example> + Content-MD5: AuLb7Dp1rqtRtxz2m9kRpA== +</example> + + <p>Note that this can cause performance problems on your server + since the message digest is computed on every request (the + values are not cached).</p> + + <p><code>Content-MD5</code> is only sent for documents served + by the core, and not by any module. For example, SSI documents, + output from CGI scripts, and byte range responses do not have + this header.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>DefaultType</name> +<description>Sets the MIME content-type that will be sent if the +server cannot determine a type in any other way</description> +<syntax>DefaultType <em>MIME-type</em></syntax> +<default>DefaultType text/html</default> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context> +</contextlist> +<override>FileInfo</override> + +<usage> + <p>There will be times when the server is asked to provide a + document whose type cannot be determined by its MIME types + mappings.</p> + + <p>The server must inform the client of the content-type of the + document, so in the event of an unknown type it uses the + <code>DefaultType</code>. For example:</p> + +<example> + <code>DefaultType image/gif</code> +</example> + would be appropriate for a directory which contained many gif + images with filenames missing the .gif extension. + + <p>Note that unlike <directive + module="core">ForceType</directive>, this directive is only + provides the default mime-type. All other mime-type definitions, + including filename extensions, that might identify the media type + will override this default.</p> +</usage> +</directivesynopsis> + +<directivesynopsis type="section"> +<name>Directory</name> +<description>Enclose a group of directives that apply only to the +named file-system directory and sub-directories</description> +<syntax><Directory <em>directory-path</em>> +... </Directory></syntax> +<contextlist><context>server config</context><context>virtual host</context> +</contextlist> + +<usage> + <p><directive type="section">Directory</directive> and + <code></Directory></code> are used to enclose a group of + directives which will apply only to the named directory and + sub-directories of that directory. Any directive which is allowed + in a directory context may be used. <em>Directory-path</em> is + either the full path to a directory, or a wild-card string. In a + wild-card string, `?' matches any single character, and `*' + matches any sequences of characters. You may + also use `[]' character ranges like in the shell. Also as of + Apache 1.3 none of the wildcards match a `/' character, which more + closely mimics the behavior of Unix shells. Example:</p> +<example> + <Directory /usr/local/httpd/htdocs><br /> + Options Indexes FollowSymLinks<br /> + </Directory><br /> +</example> + + <p>Extended regular + expressions can also be used, with the addition of the + <code>~</code> character. For example:</p> +<example> + <Directory ~ "^/www/.*/[0-9]{3}"> +</example> + would match directories in /www/ that consisted of three + numbers. + + <p>If multiple (non-regular expression) directory sections + match the directory (or its parents) containing a document, + then the directives are applied in the order of shortest match + first, interspersed with the directives from the <a + href="#accessfilename">.htaccess</a> files. For example, + with</p> + +<example> + <Directory /><br /> + AllowOverride None<br /> + </Directory><br /> + <br /> + <Directory /home/*><br /> + AllowOverride FileInfo<br /> + </Directory> +</example> + <p>for access to the document <code>/home/web/dir/doc.html</code> + the steps are:</p> + + <ul> + <li>Apply directive <code>AllowOverride None</code> + (disabling <code>.htaccess</code> files).</li> + + <li>Apply directive <code>AllowOverride FileInfo</code> (for + directory <code>/home/web</code>).</li> + + <li>Apply any FileInfo directives in + <code>/home/web/.htaccess</code></li> + </ul> + + <p>Regular expressions are not considered until after all of the + normal sections have been applied. Then all of the regular + expressions are tested in the order they appeared in the + configuration file. For example, with</p> + +<example><Directory ~ abc$><br /> + ... directives here ...<br /> + </Directory><br /> +</example> + + <p>The regular expression section won't be considered until after + all normal <Directory>s and <code>.htaccess</code> files + have been applied. Then the regular expression will match on + <code>/home/abc/public_html/abc</code> and be applied.</p> + + <p><strong>Note that the default Apache access for + <Directory /> is <samp>Allow from All</samp>. This means + that Apache will serve any file mapped from an URL. It is + recommended that you change this with a block such + as</strong></p> + +<example> + <Directory /><br /> + Order Deny,Allow<br /> + Deny from All<br /> + </Directory> +</example> + + <p><strong>and then override this for directories you + <em>want</em> accessible. See the <a + href="../misc/security_tips.html">Security Tips</a> page for more + details.</strong></p> + + <p>The directory sections typically occur in + the access.conf file, but they may appear in any configuration + file. <directive type="section">Directory</directive> directives + cannot nest, and cannot appear in a <directive module="core" + type="section">Limit</directive> or <directive module="core" + type="section">LimitExcept</directive> section.</p> +</usage> +<seealso><a href="../sections.html">How + Directory, Location and Files sections work</a> for an + explanation of how these different sections are combined when a + request is received</seealso> +</directivesynopsis> + +<directivesynopsis type="section"> +<name>DirectoryMatch</name> +<description>Enclose a group of directives that apply only to +file-system directories that match a regular expression and their +subdirectories</description> +<syntax><Directory <em>regex</em>> +... </Directory></syntax> +<contextlist><context>server config</context><context>virtual host</context> +</contextlist> + +<usage> + <p><directive type="section">DirectoryMatch</directive> and + <code></DirectoryMatch></code> are used to enclose a group + of directives which will apply only to the named directory and + sub-directories of that directory, the same as <directive + module="core" type="section">Directory</directive>. However, it + takes as an argument a regular expression. For example:</p> +<example> + <DirectoryMatch "^/www/.*/[0-9]{3}"> +</example> + + <p>would match directories in <code>/www/</code> that consisted of three + numbers.</p> +</usage> +<seealso><directive type="section" module="core">Directory</directive> for +a description of how regular expressions are mixed in with normal +<code><Directory></code>s</seealso> +<seealso><a +href="../sections.html">How Directory, Location and Files sections +work</a> for an explanation of how these different sections are +combined when a request is received</seealso> +</directivesynopsis> + +<directivesynopsis> +<name>DocumentRoot</name> +<description>Sets the directory that forms the main document tree visible +from the web</description> +<syntax>DocumentRoot <em>directory-path</em></syntax> +<default>DocumentRoot /usr/local/apache/htdocs</default> +<contextlist><context>server config</context><context>virtual host</context> +</contextlist> + +<usage> + <p>This directive sets the directory from which httpd will + serve files. Unless matched by a directive like Alias, the + server appends the path from the requested URL to the document + root to make the path to the document. Example:</p> +<example> + DocumentRoot /usr/web +</example> + <p>then an access to + <code>http://www.my.host.com/index.html</code> refers to + <code>/usr/web/index.html</code>.</p> + + <p>The <directive>DocumentRoot</directive> should be specified without + a trailing slash.</p> +</usage> +<seealso><a href="../urlmapping.html">Mapping URLs to Filesystem +Location</a></seealso> +</directivesynopsis> + +<directivesynopsis> +<name>ErrorDocument</name> +<description>Specifies what the server will return to the client +in case of an error</description> +<syntax>ErrorDocument <em>error-code document</em></syntax> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context> +</contextlist> +<override>FileInfo</override> +<compatibility>Quoting syntax for text messages is different in Apache +2.0</compatibility> + +<usage> + <p>In the event of a problem or error, Apache can be configured + to do one of four things,</p> + + <ol> + <li>output a simple hardcoded error message</li> + + <li>output a customized message</li> + + <li>redirect to a local <em>URL-path</em> to handle the + problem/error</li> + + <li>redirect to an external <em>URL</em> to handle the + problem/error</li> + </ol> + + <p>The first option is the default, while options 2-4 are + configured using the <directive>ErrorDocument</directive> + directive, which is followed by the HTTP response code and a URL + or a message. Apache will sometimes offer additional information + regarding the problem/error.</p> + + <p>URLs can begin with a slash (/) for local URLs, or be a full + URL which the client can resolve. Alternatively, a message can + be provided to be displayed by the browser. Examples:</p> + +<example> + ErrorDocument 500 + http://foo.example.com/cgi-bin/tester<br /> + ErrorDocument 404 /cgi-bin/bad_urls.pl<br /> + ErrorDocument 401 /subscription_info.html<br /> + ErrorDocument 403 "Sorry can't allow you access + today" +</example> + + <p>Note that when you specify an <directive>ErrorDocument</directive> + that points to a remote URL (ie. anything with a method such as + "http" in front of it), Apache will send a redirect to the + client to tell it where to find the document, even if the + document ends up being on the same server. This has several + implications, the most important being that the client will not + receive the original error status code, but instead will + receive a redirect status code. This in turn can confuse web + robots and other clients which try to determine if a URL is + valid using the status code. In addition, if you use a remote + URL in an <code>ErrorDocument 401</code>, the client will not + know to prompt the user for a password since it will not + receive the 401 status code. Therefore, <strong>if you use an + "ErrorDocument 401" directive then it must refer to a local + document.</strong></p> + + <p>Prior to version 2.0, messages were indicated by prefixing + them with a single unmatched double quote character.</p> +</usage> + +<seealso><a href="../custom-error.html">documentation of + customizable responses</a></seealso> +</directivesynopsis> + +<directivesynopsis> +<name>ErrorLog</name> +<description>Sets the name of the file to which the server +will log errors</description> +<syntax> ErrorLog <em>file-path</em>|syslog[:<em>facility</em>]</syntax> +<default>ErrorLog logs/error_log (Unix) +ErrorLog logs/error.log (Windows and OS/2)</default> +<contextlist><context>server config</context><context>virtual host</context> +</contextlist> + +<usage> + <p>The <directive>ErrorLog</directive> directive sets the name of + the file to which the server will log any errors it encounters. If + the <em>file-path</em> does not begin with a slash (/) then it is + assumed to be relative to the <directive + module="core">ServerRoot</directive>. If the <em>file-path</em> + begins with a pipe (|) then it is assumed to be a command to spawn + to handle the error log.</p> + + <p>Using <code>syslog</code> instead of a filename enables logging + via syslogd(8) if the system supports it. The default is to use + syslog facility <code>local7</code>, but you can override this by + using the <code>syslog:</code><em>facility</em> syntax where + <em>facility</em> can be one of the names usually documented in + syslog(1).</p> + + <p>SECURITY: See the <a + href="../misc/security_tips.html#serverroot">security tips</a> + document for details on why your security could be compromised + if the directory where logfiles are stored is writable by + anyone other than the user that starts the server.</p> +</usage> +<seealso><directive module="core">LogLevel</directive></seealso> +<seealso><a href="../logs.html">Apache Log Files</a></seealso> +</directivesynopsis> + +<directivesynopsis> +<name>FileETag</name> +<description>Configures the file attributes used to create the ETag +HTTP response header</description> +<syntax>FileETag <em>component</em> ...</syntax> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context> +</contextlist> +<override>FileInfo</override> + +<usage> + <p> + The <directive>FileETag</directive> directive configures the file + attributes that are used to create the ETag (entity tag) response + header field when the document is based on a file. (The ETag + value is used in cache management to save network bandwidth.) In + Apache 1.3.22 and earlier, the ETag value was <em>always</em> formed + from the file's inode, size, and last-modified time (mtime). The + FileETag directive allows you to choose which of these -- if any + -- should be used. The recognized keywords are: + </p> + <dl compact="compact"> + <dt><b>INode</b></dt> + <dd>The file's i-node number will be included in the calculation</dd> + <dt><b>MTime</b></dt> + <dd>The date and time the file was last modified will be included</dd> + <dt><b>Size</b></dt> + <dd>The number of bytes in the file will be included</dd> + <dt><b>All</b></dt> + <dd>All available fields will be used (equivalent to + '<code>FileETag INode MTime Size</code>')</dd> + <dt><b>None</b></dt> + <dd>If a document is file-based, no ETag field will be included in the + response</dd> + </dl> + <p> + The INode, MTime, and Size keywords may be prefixed with either '+' + or '-', which allow changes to be made to the default setting + inherited from a broader scope. Any keyword appearing without + such a prefix immediately and completely cancels the inherited + setting. + </p> + <p> + If a directory's configuration includes + '<code>FileETag INode MTime Size</code>', and a + subdirectory's includes '<code>FileETag -INode</code>', + the setting for that subdirectory (which will be inherited by + any sub-subdirectories that don't override it) will be equivalent to + '<code>FileETag MTime Size</code>'. + </p> +</usage> +</directivesynopsis> + +<directivesynopsis type="section"> +<name>Files</name> +<description>Contains that directives that apply to matched +filenames</description> +<syntax><Files <em>filename</em>> ... </Files></syntax> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context> +</contextlist> + +<usage> + <p>The <directive type="section">Files</directive> directive + provides for access control by filename. It is comparable to the + <directive module="core" type="directive">Directory</directive> + directive and <directive module="core" + type="directive">Location</directive> directives. It should be + matched with a <code></Files></code> directive. The + directives given within this section will be applied to any object + with a basename (last component of filename) matching the + specified filename. <directive type="section">Files</directive> + sections are processed in the order they appear in the + configuration file, after the <directive module="core" + type="section">Directory</directive> sections and + <code>.htaccess</code> files are read, but before <directive + type="section" module="core">Location</directive> sections. Note + that <directive type="section">Files</directive> can be nested + inside <directive type="section" + module="core">Directory</directive> sections to restrict the + portion of the filesystem they apply to.</p> + + <p>The <em>filename</em> argument should include a filename, or + a wild-card string, where `?' matches any single character, and + `*' matches any sequences of characters. Extended regular + expressions can also be used, with the addition of the + <code>~</code> character. For example:</p> +<example> + <Files ~ "\.(gif|jpe?g|png)$"> +</example> + <p>would match most common Internet graphics formats. In Apache 1.3 + and later, <directive module="core" + type="section">FilesMatch</directive> is preferred, however.</p> + + <p>Note that unlike <directive type="section" + module="core">Directory</directive> and <directive type="section" + module="core">Location</directive> sections, <directive + type="section">Files</directive> sections can be used inside + .htaccess files. This allows users to control access to their own + files, at a file-by-file level.</p> + +</usage> +<seealso><a href="../sections.html">How + Directory, Location and Files sections work</a> for an + explanation of how these different sections are combined when a + request is received</seealso> +</directivesynopsis> + +<directivesynopsis type="section"> +<name>FilesMatch</name> +<description>Contains that directives that apply to regular-expression matched +filenames</description> +<syntax><FilesMatch <em>regex</em>> ... </FilesMatch></syntax> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context> +</contextlist> + +<usage> + <p>The <directive type="section">FilesMatch</directive> directive + provides for access control by filename, just as the <directive + module="core" type="section">Files</directive> directive + does. However, it accepts a regular expression. For example:</p> +<example> + <FilesMatch "\.(gif|jpe?g|png)$"> +</example> + + <p>would match most common Internet graphics formats.</p> +</usage> + +<seealso><a href="../sections.html">How + Directory, Location and Files sections work</a> for an + explanation of how these different sections are combined when a + request is received</seealso> +</directivesynopsis> + +<directivesynopsis> +<name>ForceType</name> +<description>Forces all matching files to be served with the specified +MIME content-type</description> +<syntax>ForceType <em>mime-type</em></syntax> +<contextlist><context>directory</context><context>.htaccess</context> +</contextlist> +<compatibility>Moved to the core in Apache 2.0</compatibility> + +<usage> + <p>When placed into an <code>.htaccess</code> file or a + <directive type="section" module="core">Directory</directive>, or + <directive type="section" module="core">Location</directive> or + <directive type="section" module="core">Files</directive> + section, this directive forces all matching files to be served + with the content type identification given by + <em>mime-type</em>. For example, if you had a directory full of + GIF files, but did not want to label them all with ".gif", you + might want to use:</p> +<example> + ForceType image/gif +</example> + + <p>Note that unlike <directive module="core">DefaultType</directive>, + this directive overrides all mime-type associations, including + filename extensions, that might identify the media type.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>HostnameLookups</name> +<description>Enables DNS lookups on client IP addresses</description> +<syntax>HostnameLookups on|off|double</syntax> +<default>HostnameLookups off</default> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context></contextlist> + +<usage> + <p>This directive enables DNS lookups so that host names can be + logged (and passed to CGIs/SSIs in <code>REMOTE_HOST</code>). + The value <code>double</code> refers to doing double-reverse + DNS. That is, after a reverse lookup is performed, a forward + lookup is then performed on that result. At least one of the ip + addresses in the forward lookup must match the original + address. (In "tcpwrappers" terminology this is called + <code>PARANOID</code>.)</p> + + <p>Regardless of the setting, when <module>mod_access</module> is + used for controlling access by hostname, a double reverse lookup + will be performed. This is necessary for security. Note that the + result of this double-reverse isn't generally available unless you + set <code>HostnameLookups double</code>. For example, if only + <code>HostnameLookups on</code> and a request is made to an object + that is protected by hostname restrictions, regardless of whether + the double-reverse fails or not, CGIs will still be passed the + single-reverse result in <code>REMOTE_HOST</code>.</p> + + <p>The default is off in order to save the network + traffic for those sites that don't truly need the reverse + lookups done. It is also better for the end users because they + don't have to suffer the extra latency that a lookup entails. + Heavily loaded sites should leave this directive + <code>off</code>, since DNS lookups can take considerable + amounts of time. The utility <a + href="../programs/logresolve.html">logresolve</a>, provided in + the <em>/support</em> directory, can be used to look up host + names from logged IP addresses offline.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>IdentityCheck</name> +<description>Enables logging of the RFC1413 identity of the remote +user</description> +<syntax>IdentityCheck on|off</syntax> +<default>IdentityCheck off</default> + +<usage> + <p>This directive enables RFC1413-compliant logging of the + remote user name for each connection, where the client machine + runs identd or something similar. This information is logged in + the access log.</p> + + <p>The information should not be trusted in any way except for + rudimentary usage tracking.</p> + + <p>Note that this can cause serious latency problems accessing + your server since every request requires one of these lookups + to be performed. When firewalls are involved each lookup might + possibly fail and add 30 seconds of latency to each hit. So in + general this is not very useful on public servers accessible + from the Internet.</p> +</usage> +</directivesynopsis> + +<directivesynopsis type="section"> +<name>IfDefine</name> +<description>Encloses directives that will be processed only +if a test is true at startup</description> +<syntax><IfDefine [!]<em>parameter-name</em>> <em>...</em> + </IfDefine></syntax> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context> +</contextlist> + +<usage> + <p>The <code><IfDefine + <em>test</em>>...</IfDefine></code> section is used to + mark directives that are conditional. The directives within an + <directive type="section">IfDefine</directive> section are only + processed if the <em>test</em> is true. If <em>test</em> is false, + everything between the start and end markers is ignored.</p> + + <p>The <em>test</em> in the <directive + type="section">IfDefine</directive> section directive can be one + of two forms:</p> + + <ul> + <li><em>parameter-name</em></li> + + <li><code>!</code><em>parameter-name</em></li> + </ul> + + <p>In the former case, the directives between the start and end + markers are only processed if the parameter named + <em>parameter-name</em> is defined. The second format reverses + the test, and only processes the directives if + <em>parameter-name</em> is <strong>not</strong> defined.</p> + + <p>The <em>parameter-name</em> argument is a define as given on + the <code>httpd</code> command line via + <code>-D</code><em>parameter-</em>, at the time the server was + started.</p> + + <p><directive type="section">IfDefine</directive> sections are + nest-able, which can be used to implement simple + multiple-parameter tests. Example:</p> +<example><pre> + $ httpd -DReverseProxy ... + + # httpd.conf + <IfDefine ReverseProxy> + LoadModule rewrite_module modules/mod_rewrite.so + LoadModule proxy_module modules/libproxy.so + </IfDefine> +</pre></example> + +</usage> +</directivesynopsis> + +<directivesynopsis type="section"> +<name>IfModule</name> +<description>Encloses directives that are processed conditional on the +presence of absence of a specific module</description> +<syntax><IfModule [!]<em>module-name</em>> <em>...</em> + </IfModule></syntax> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context> +</contextlist> + +<usage> + <p>The <code><IfModule + <em>test</em>>...</IfModule></code> section is used to + mark directives that are conditional. The directives within an + <directive type="section">IfModule</directive> section are only + processed if the <em>test</em> is true. If <em>test</em> is false, + everything between the start and end markers is ignored.</p> + + <p>The <em>test</em> in the <directive + type="section">IfModule</directive> section directive can be one + of two forms:</p> + + <ul> + <li><em>module name</em></li> + + <li>!<em>module name</em></li> + </ul> + + <p>In the former case, the directives between the start and end + markers are only processed if the module named <em>module + name</em> is included in Apache -- either compiled in or + dynamically loaded using <directive module="mod_so" + >LoadModule</directive>. The second format + reverses the test, and only processes the directives if <em>module + name</em> is <strong>not</strong> included.</p> + + <p>The <em>module name</em> argument is the file name of the + module, at the time it was compiled. + For example, <code>mod_rewrite.c</code>.</p> + + <p><directive type="section">IfModule</directive> sections are + nest-able, which can be used to implement simple multiple-module + tests.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>Include</name> +<description>Includes other configuration files from within +the server configuration files</description> +<syntax>Include <em>file-path</em>|<em>directory-path</em></syntax> +<contextlist><context>server config</context></contextlist> + +<usage> + <p>This directive allows inclusion of other configuration files + from within the server configuration files.</p> + + <p>If <directive>Include</directive> points to a directory, rather than a + file, Apache will read all files in that directory, and any + subdirectory, and parse those as configuration files.</p> + + <p>The file path specified may be a fully qualified path (i.e. + starting with a slash), or may be relative to the + <directive module="core">ServerRoot</directive> directory.</p> + + <p>Examples:</p> + +<example> + Include /usr/local/apache/conf/ssl.conf<br /> + Include /usr/local/apache/conf/vhosts/ +</example> + + <p>Or, providing paths relative to your <code>ServerRoot</code> + directory:</p> + +<example> + Include conf/ssl.conf<br /> + Include conf/vhosts/ +</example> + + <p>Make sure that an included directory does not contain any stray + files, such as editor temporary files, for example, as Apache will + attempt to read them in and use the contents as configuration + directives, which may cause the server to fail on start up. + Running <code>apachectl configtest</code> will give you a list of + the files that are being processed during the configuration + check:</p> + +<example><pre> + root@host# apachectl configtest + Processing config directory: /usr/local/apache/conf/vhosts + Processing config file: /usr/local/apache/conf/vhosts/vhost1 + Processing config file: /usr/local/apache/conf/vhosts/vhost2 + Syntax OK +</pre></example> + + <p>This will help in verifying that you are getting only the files + that you intended as part of your configuration.</p> +</usage> + +<seealso><a href="../programs/apachectl.html">apachectl</a></seealso> +</directivesynopsis> + +<directivesynopsis> +<name>KeepAlive</name> +<description>Turns on or off HTTP persistent connections.</description> +<syntax>KeepAlive on|off</syntax> +<default>KeepAlive On</default> +<contextlist><context>server config</context></contextlist> + +<usage> + <p>The Keep-Alive extension to HTTP/1.0 and the persistent + connection feature of HTTP/1.1 provide long-lived HTTP sessions + which allow multiple requests to be sent over the same TCP + connection. In some cases this has been shown to result in an + almost 50% speedup in latency times for HTML documents with + many images. To enable Keep-Alive connections in Apache 1.2 and + later, set <code>KeepAlive On</code>.</p> + + <p>For HTTP/1.0 clients, Keep-Alive connections will only be + used if they are specifically requested by a client. In + addition, a Keep-Alive connection with an HTTP/1.0 client can + only be used when the length of the content is known in + advance. This implies that dynamic content such as CGI output, + SSI pages, and server-generated directory listings will + generally not use Keep-Alive connections to HTTP/1.0 clients. + For HTTP/1.1 clients, persistent connections are the default + unless otherwise specified. If the client requests it, chunked + encoding will be used in order to send content of unknown + length over persistent connections.</p> +</usage> + +<seealso><directive module="core">MaxKeepAliveRequests</directive></seealso> +</directivesynopsis> + +<directivesynopsis> +<name>KeepAliveTimeout</name> +<description>Sets the amount of time the server will wait for subsequent +requests on a persistent connection</description> +<syntax>KeepAliveTimeout <em>seconds</em></syntax> +<default>KeepAliveTimeout 15</default> +<contextlist><context>server config</context></contextlist> + +<usage> + <p>The number of seconds Apache will wait for a subsequent + request before closing the connection. Once a request has been + received, the timeout value specified by the + <directive module="core">Timeout</directive> directive applies.</p> + + <p>Setting <directive>KeepAliveTimeout</directive> to a high value + may cause performance problems in heavily loaded servers. The + higher the timeout, the more server processes will be kept + occupied waiting on connections with idle clients.</p> +</usage> +</directivesynopsis> + +<directivesynopsis type="section"> +<name>Limit</name> +<description>Restrict access controls to only certain HTTP +methods</description> +<syntax><Limit <em>method</em> [<em>method</em>] ... > ... + </Limit></syntax> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context> +</contextlist> + +<usage> + <p>Access controls are normally effective for + <strong>all</strong> access methods, and this is the usual + desired behavior. <strong>In the general case, access control + directives should not be placed within a + <directive type="section">limit</directive> section.</strong></p> + + <p>The purpose of the <directive type="section">Limit</directive> + directive is to restrict the effect of the access controls to the + nominated HTTP methods. For all other methods, the access + restrictions that are enclosed in the <code><Limit></code> + bracket <strong>will have no effect</strong>. The following + example applies the access control only to the methods POST, PUT, + and DELETE, leaving all other methods unprotected:</p> + +<example> + <code><Limit POST PUT DELETE><br /> + Require valid-user<br /> + </Limit></code> +</example> + <p>The method names listed can be one or more of: GET, POST, PUT, + DELETE, CONNECT, OPTIONS, TRACE, PATCH, PROPFIND, PROPPATCH, + MKCOL, COPY, MOVE, LOCK, and UNLOCK. <strong>The method name is + case-sensitive.</strong> If GET is used it will also restrict + HEAD requests.</p> +</usage> +</directivesynopsis> + +<directivesynopsis type="section"> +<name>LimitExcept</name> +<description>Restrict access controls to all HTTP methods +except the named ones</description> +<syntax><LimitExcept <em>method</em> [<em>method</em>] ... > ... + </LimitExcept></syntax> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context> +</contextlist> + +<usage> + <p><directive type="section">LimitExcept</directive> and + <code></LimitExcept></code> are used to enclose a group of + access control directives which will then apply to any HTTP access + method <strong>not</strong> listed in the arguments; i.e., it is + the opposite of a <directive type="section" + module="core">Limit</directive> section and can be used to control + both standard and nonstandard/unrecognized methods. See the + documentation for <directive module="core" + type="section">Limit</directive> for more details.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>LimitRequestBody</name> +<description>Restricts the total size of the HTTP request body sent +from the client</description> +<syntax>LimitRequestBody <em>bytes</em></syntax> +<default>LimitRequestBody 0</default> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context> +</contextlist> + +<usage> + <p>This directive specifies the number of <em>bytes</em> from 0 + (meaning unlimited) to 2147483647 (2GB) that are allowed in a + request body. The default value is defined by the compile-time + constant <code>DEFAULT_LIMIT_REQUEST_BODY</code> (0 as + distributed).</p> + + <p>The <directive>LimitRequestBody</directive> directive allows + the user to set a limit on the allowed size of an HTTP request + message body within the context in which the directive is given + (server, per-directory, per-file or per-location). If the client + request exceeds that limit, the server will return an error + response instead of servicing the request. The size of a normal + request message body will vary greatly depending on the nature of + the resource and the methods allowed on that resource. CGI scripts + typically use the message body for passing form information to the + server. Implementations of the PUT method will require a value at + least as large as any representation that the server wishes to + accept for that resource.</p> + + <p>This directive gives the server administrator greater + control over abnormal client request behavior, which may be + useful for avoiding some forms of denial-of-service + attacks.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>LimitRequestFields</name> +<description>Limits the number of HTTP request header fields that +will be accepted from the client</description> +<syntax>LimitRequestFields <em>number</em></syntax> +<default>LimitRequestFields 100</default> +<contextlist><context>server config</context></contextlist> + +<usage> + <p><em>Number</em> is an integer from 0 (meaning unlimited) to + 32767. The default value is defined by the compile-time + constant <code>DEFAULT_LIMIT_REQUEST_FIELDS</code> (100 as + distributed).</p> + + <p>The <directive>LimitRequestFields</directive> directive allows + the server administrator to modify the limit on the number of + request header fields allowed in an HTTP request. A server needs + this value to be larger than the number of fields that a normal + client request might include. The number of request header fields + used by a client rarely exceeds 20, but this may vary among + different client implementations, often depending upon the extent + to which a user has configured their browser to support detailed + content negotiation. Optional HTTP extensions are often expressed + using request header fields.</p> + + <p>This directive gives the server administrator greater + control over abnormal client request behavior, which may be + useful for avoiding some forms of denial-of-service attacks. + The value should be increased if normal clients see an error + response from the server that indicates too many fields were + sent in the request.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>LimitRequestFieldSize</name> +<description>Limits the size of the HTTP request header allowed from the +client</description> +<syntax>LimitRequestFieldsize <em>bytes</em></syntax> +<default>LimitRequestFieldsize 8190</default> +<contextlist><context>server config</context></contextlist> + +<usage> + <p>This directive specifies the number of <em>bytes</em> from 0 + to the value of the compile-time constant + <code>DEFAULT_LIMIT_REQUEST_FIELDSIZE</code> (8190 as + distributed) that will be allowed in an HTTP request + header.</p> + + <p>The <directive>LimitRequestFieldsize</directive> directive + allows the server administrator to reduce the limit on the allowed + size of an HTTP request header field below the normal input buffer + size compiled with the server. A server needs this value to be + large enough to hold any one header field from a normal client + request. The size of a normal request header field will vary + greatly among different client implementations, often depending + upon the extent to which a user has configured their browser to + support detailed content negotiation.</p> + + <p>This directive gives the server administrator greater + control over abnormal client request behavior, which may be + useful for avoiding some forms of denial-of-service attacks. + Under normal conditions, the value should not be changed from + the default.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>LimitRequestLine</name> +<description>Limit the size of the HTTP request line that will be accepted +from the client</description> +<syntax>LimitRequestLine <em>bytes</em></syntax> +<default>LimitRequestLine 8190</default> +<contextlist><context>server config</context></contextlist> + +<usage> + <p>This directive sets the number of <em>bytes</em> from 0 to + the value of the compile-time constant + <code>DEFAULT_LIMIT_REQUEST_LINE</code> (8190 as distributed) + that will be allowed on the HTTP request-line.</p> + + <p>The <directive>LimitRequestLine</directive> directive allows + the server administrator to reduce the limit on the allowed size + of a client's HTTP request-line below the normal input buffer size + compiled with the server. Since the request-line consists of the + HTTP method, URI, and protocol version, the + <directive>LimitRequestLine</directive> directive places a + restriction on the length of a request-URI allowed for a request + on the server. A server needs this value to be large enough to + hold any of its resource names, including any information that + might be passed in the query part of a GET request.</p> + + <p>This directive gives the server administrator greater + control over abnormal client request behavior, which may be + useful for avoiding some forms of denial-of-service attacks. + Under normal conditions, the value should not be changed from + the default.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>LimitXMLRequestBody</name> +<description>Limits the size of an XML-based request body</description> +<syntax>LimitXMLRequestBody <em>number</em></syntax> +<default>LimitXMLRequestBody 1000000</default> +<contextlist><context>server config</context></contextlist> + +<usage> + <p>Limit (in bytes) on maximum size of an XML-based request + body. A value of <code>0</code> will disable any checking.</p> +</usage> +</directivesynopsis> + +<directivesynopsis type="section"> +<name>Location</name> +<description>Applies the enclosed directives only to matching +URLs</description> +<syntax><Location + <em>URL-path</em>|<em>URL</em>> ... </Location></syntax> +<contextlist><context>server config</context><context>virtual host</context> +</contextlist> + +<usage> + <p>The <directive type="section">Location</directive> directive + provides for access control by URL. It is similar to the + <directive type="section" module="core">Directory</directive> + directive, and starts a subsection which is terminated with a + <code></Location></code> directive. <directive + type="section">Location</directive> sections are processed in the + order they appear in the configuration file, after the <directive + type="section" module="core">Directory</directive> sections and + <code>.htaccess</code> files are read, and after the <directive + type="section" module="core">Files</directive> sections.</p> + + <p>Note that URLs do not have to line up with the filesystem at + all, it should be emphasized that <Location> operates + completely outside the filesystem.</p> + + <p>For all origin (non-proxy) requests, the URL to be matched + is of the form <code>/path/</code>, and you should not include + any <code>http://servername</code> prefix. For proxy requests, + the URL to be matched is of the form + <code>scheme://servername/path</code>, and you must include the + prefix.</p> + + <p>The URL may use wildcards In a wild-card string, `?' matches + any single character, and `*' matches any sequences of + characters.</p> + + <p>Extended regular + expressions can also be used, with the addition of the + <code>~</code> character. For example:</p> +<example> + <Location ~ "/(extra|special)/data"> +</example> + + <p>would match URLs that contained the substring "/extra/data" or + "/special/data". In Apache 1.3 and above, a new directive + <directive type="section" module="core">LocationMatch</directive> + exists which behaves identical to the regex version of + <directive type="section">Location</directive>.</p> + + <p>The <directive type="section">Location</directive> + functionality is especially useful when combined with the + <directive module="core">SetHandler</directive> + directive. For example, to enable status requests, but allow them + only from browsers at foo.com, you might use:</p> +<example> + <Location /status><br /> + SetHandler server-status<br /> + Order Deny,Allow<br /> + Deny from all<br /> + Allow from .foo.com<br /> + </Location> +</example> + +<note><title>Note about / (slash)</title> <p>The slash character has +special meaning depending on where in a URL it appears. People may be +used to its behavior in the filesystem where multiple adjacent slashes +are frequently collapsed to a single slash (<em>i.e.</em>, +<code>/home///foo</code> is the same as <code>/home/foo</code>). In +URL-space this is not necessarily true. The <directive type="section" +module="core">LocationMatch</directive> directive and the regex +version of <directive type="section">Location</directive> require you +to explicitly specify multiple slashes if that is your intention. For +example, <code><LocationMatch ^/abc></code> would match the +request URL <code>/abc</code> but not the request URL +<code>//abc</code>. The (non-regex) <directive +type="section">Location</directive> directive behaves similarly when +used for proxy requests. But when (non-regex) <directive +type="section">Location</directive> is used for non-proxy requests it +will implicitly match multiple slashes with a single slash. For +example, if you specify <code><Location /abc/def></code> and the +request is to <code>/abc//def</code> then it will match.</p> +</note> +</usage> +<seealso><a href="../sections.html">How + Directory, Location and Files sections work</a> for an + explanation of how these different sections are combined when a + request is received</seealso> +</directivesynopsis> + +<directivesynopsis type="section"> +<name>LocationMatch</name> +<description>Applies the enclosed directives only to regular-expression +matching URLs</description> +<syntax><LocationMatch + <em>regex</em>> ... </Location></syntax> +<contextlist><context>server config</context><context>virtual host</context> +</contextlist> + +<usage> + <p>The <directive type="section">LocationMatch</directive> directive + provides for access control by URL, in an identical manner to + <directive module="core" + type="section">Location</directive>. However, it takes a regular + expression as an argument instead of a simple string. For + example:</p> +<example> + <LocationMatch "/(extra|special)/data"> +</example> + + <p>would match URLs that contained the substring "/extra/data" + or "/special/data".</p> +</usage> + +<seealso><a href="../sections.html">How + Directory, Location and Files sections work</a> for an + explanation of how these different sections are combined when a + request is received</seealso> +</directivesynopsis> + +<directivesynopsis> +<name>LogLevel</name> +<description>Controls the verbosity of the ErrorLog</description> +<syntax>LogLevel <em>level</em></syntax> +<default>LogLevel warn</default> +<contextlist><context>server config</context><context>virtual host</context> +</contextlist> + +<usage> + <p><directive>LogLevel</directive> adjusts the verbosity of the + messages recorded in the error logs (see <directive + module="core">ErrorLog</directive> directive). The following + <em>level</em>s are available, in order of decreasing + significance:</p> + + <table> + <tr> + <th align="LEFT"><strong>Level</strong> </th> + + <th align="LEFT"><strong>Description</strong> </th> + </tr> + + <tr> + <th> + </th> + + <th align="LEFT"><strong>Example</strong> </th> + </tr> + + <tr> + <td><code>emerg</code> </td> + + <td>Emergencies - system is unusable.</td> + </tr> + + <tr> + <td> + </td> + + <td>"Child cannot open lock file. Exiting"</td> + </tr> + + <tr> + <td><code>alert</code> </td> + + <td>Action must be taken immediately.</td> + </tr> + + <tr> + <td> + </td> + + <td>"getpwuid: couldn't determine user name from uid"</td> + </tr> + + <tr> + <td><code>crit</code> </td> + + <td>Critical Conditions.</td> + </tr> + + <tr> + <td> + </td> + + <td>"socket: Failed to get a socket, exiting child"</td> + </tr> + + <tr> + <td><code>error</code> </td> + + <td>Error conditions.</td> + </tr> + + <tr> + <td> + </td> + + <td>"Premature end of script headers"</td> + </tr> + + <tr> + <td><code>warn</code> </td> + + <td>Warning conditions.</td> + </tr> + + <tr> + <td> + </td> + + <td>"child process 1234 did not exit, sending another + SIGHUP"</td> + </tr> + + <tr> + <td><code>notice</code> </td> + + <td>Normal but significant condition.</td> + </tr> + + <tr> + <td> + </td> + + <td>"httpd: caught SIGBUS, attempting to dump core in + ..."</td> + </tr> + + <tr> + <td><code>info</code> </td> + + <td>Informational.</td> + </tr> + + <tr> + <td> + </td> + + <td>"Server seems busy, (you may need to increase + StartServers, or Min/MaxSpareServers)..."</td> + </tr> + + <tr> + <td><code>debug</code> </td> + + <td>Debug-level messages</td> + </tr> + + <tr> + <td> + </td> + + <td>"Opening config file ..."</td> + </tr> + </table> + + <p>When a particular level is specified, messages from all + other levels of higher significance will be reported as well. + <em>E.g.</em>, when <code>LogLevel info</code> is specified, + then messages with log levels of <code>notice</code> and + <code>warn</code> will also be posted.</p> + + <p>Using a level of at least <code>crit</code> is + recommended.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>MaxKeepAliveRequests</name> +<description>Sets the number of requests allowed on a persistent +connection</description> +<syntax>MaxKeepAliveRequests <em>number</em></syntax> +<default>MaxKeepAliveRequests 100</default> +<contextlist><context>server config</context></contextlist> + +<usage> + <p>The <directive>MaxKeepAliveRequests</directive> directive + limits the number of requests allowed per connection when + <directive module="core" >KeepAlive</directive> is on. If it is + set to "<code>0</code>", unlimited requests will be allowed. We + recommend that this setting be kept to a high value for maximum + server performance.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>NameVirtualHost</name> +<description>Configures an IP address for name-virtual +hosting</description> +<syntax>NameVirtualHost <em>addr</em>[:<em>port</em>]</syntax> +<contextlist><context>server config</context></contextlist> + +<usage> + <p>The <directive>NameVirtualHost</directive> directive is a + required directive if you want to configure <a + href="../vhosts/">name-based virtual hosts</a>.</p> + + <p>Although <em>addr</em> can be hostname it is recommended + that you always use an IP address, <em>e.g.</em></p> + +<example>NameVirtualHost 111.22.33.44</example> + + <p>With the <directive>NameVirtualHost</directive> directive you + specify the IP address on which the server will receive requests + for the name-based virtual hosts. This will usually be the address + to which your name-based virtual host names resolve. In cases + where a firewall or other proxy receives the requests and forwards + them on a different IP address to the server, you must specify the + IP address of the physical interface on the machine which will be + servicing the requests. If you have multiple name-based hosts on + multiple addresses, repeat the directive for each address.</p> + + <p>Note: the "main server" and any _default_ servers will + <strong>never</strong> be served for a request to a + <directive>NameVirtualHost</directive> IP Address (unless for some + reason you specify <directive>NameVirtualHost</directive> but then + don't define any VirtualHosts for that address).</p> + + <p>Optionally you can specify a port number on which the + name-based virtual hosts should be used, <em>e.g.</em></p> + +<example>NameVirtualHost 111.22.33.44:8080</example> + + <p>IPv6 addresses must be enclosed in square brackets, as shown + in the following example:</p> + +<example>NameVirtualHost [fe80::a00:20ff:fea7:ccea]:8080</example> + +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>Options</name> +<description>Configures what features are available in a particular +directory</description> +<syntax>Options + [+|-]<em>option</em> [[+|-]<em>option</em>] ...</syntax> +<default>Options All</default> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context> +</contextlist> +<override>Options</override> + +<usage> + <p>The <directive>Options</directive> directive controls which + server features are available in a particular directory.</p> + + <p><em>option</em> can be set to <code>None</code>, in which + case none of the extra features are enabled, or one or more of + the following:</p> + + <dl> + <dt>All</dt> + + <dd>All options except for MultiViews. This is the default + setting.</dd> + + <dt>ExecCGI</dt> + + <dd> + Execution of CGI scripts is permitted.</dd> + + <dt>FollowSymLinks</dt> + + <dd> + + The server will follow symbolic links in this directory.<br /> + <strong>Note</strong>: even though the server follows the + symlink it does <em>not</em> change the pathname used to match + against <directive type="section" + module="core">Directory</directive> sections.<br /> + <strong>Note</strong>: this option gets ignored if set inside a + <directive type="section" module="core">Location</directive> + section.</dd> + + <dt>Includes</dt> + + <dd> + Server-side includes are permitted.</dd> + + <dt>IncludesNOEXEC</dt> + + <dd> + + Server-side includes are permitted, but the #exec command and + #exec CGI are disabled. It is still possible to #include + virtual CGI scripts from ScriptAliase'd directories.</dd> + + <dt>Indexes</dt> + + <dd> + If a URL which maps to a directory is requested, and the + there is no DirectoryIndex (<em>e.g.</em>, index.html) in + that directory, then the server will return a formatted + listing of the directory.</dd> + + <dt>MultiViews</dt> + + <dd> + <a href="../content-negotiation.html">Content negotiated</a> + MultiViews are allowed.</dd> + + <dt>SymLinksIfOwnerMatch</dt> + + <dd> + + The server will only follow symbolic links for which the target + file or directory is owned by the same user id as the link.<br + /> <strong>Note</strong>: this option gets ignored if set inside + a <directive module="core" type="section">Location</directive> + section.</dd> + </dl> + <p>Normally, if multiple <directive>Options</directive> could apply to a + directory, then the most specific one is taken complete; the + options are not merged. However if <em>all</em> the options on + the <directive>Options</directive> directive are preceded by a + or - + symbol, the options are merged. Any options preceded by a + are + added to the options currently in force, and any options + preceded by a - are removed from the options currently in + force. </p> + + <p>For example, without any + and - symbols:</p> + + +<example><Directory /web/docs><br /> + Options Indexes FollowSymLinks<br /> + </Directory><br /> + <Directory /web/docs/spec><br /> + Options Includes<br /> + </Directory> +</example> + <p>then only <code>Includes</code> will be set for the + /web/docs/spec directory. However if the second + <directive>Options</directive> directive uses the + and - symbols:</p> + +<example> + <Directory /web/docs><br /> + Options Indexes FollowSymLinks<br /> + </Directory><br /> + <Directory /web/docs/spec><br /> + Options +Includes -Indexes<br /> + </Directory> +</example> + <p>then the options <code>FollowSymLinks</code> and + <code>Includes</code> are set for the /web/docs/spec directory.</p> + + + <p><strong>Note:</strong> Using <code>-IncludesNOEXEC</code> or + <code>-Includes</code> disables server-side includes completely + regardless of the previous setting.</p> + + <p>The default in the absence of any other settings is + <code>All</code>.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>Require</name> +<description>Selects which authenticated users can access +a resource</description> +<syntax>Require <em>entity-name</em> [<em>entity-name</em>] ...</syntax> +<contextlist><context>directory</context><context>.htaccess</context> +</contextlist> +<override>AuthConfig</override> + +<usage> + <p>This directive selects which authenticated users can access + a directory. The allowed syntaxes are:</p> + + <ul> + <li> + Require user <em>userid</em> [<em>userid</em>] ... + + <p>Only the named users can access the directory.</p> + </li> + + <li> + Require group <em>group-name</em> [<em>group-name</em>] ... + + + <p>Only users in the named groups can access the + directory.</p> + </li> + + <li> + Require valid-user + + <p>All valid users can access the directory.</p> + </li> + </ul> + + <p><directive>Require</directive> must be accompanied by + <directive module="core">AuthName</directive> and <directive + module="core">AuthType</directive> directives, and directives such + as <directive module="mod_auth">AuthUserFile</directive> + and <directive module="mod_auth">AuthGroupFile</directive> (to + define users and groups) in order to work correctly. Example:</p> + +<example> + AuthType Basic<br /> + AuthName "Restricted Directory"<br /> + AuthUserFile /web/users<br /> + AuthGroupFile /web/groups<br /> + Require group admin<br /> +</example> + + <p>Access controls which are applied in this way are effective for + <strong>all</strong> methods. <strong>This is what is normally + desired.</strong> If you wish to apply access controls only to + specific methods, while leaving other methods unprotected, then + place the <directive>Require</directive> statement into a + <directive module="core" type="section">Limit</directive> + section.</p> +</usage> +<seealso><directive module="core">Satisfy</directive></seealso> +<seealso><module>mod_access</module></seealso> +</directivesynopsis> + +<directivesynopsis> +<name>RLimitCPU</name> +<description>Limits the CPU consumption of processes launched +by Apache children</description> +<syntax>RLimitCPU <em>number</em>|max [<em>number</em>|max]</syntax> +<default>Unset; uses operating system defaults</default> +<contextlist>><context>server config</context><context>virtual host</context> +</contextlist> +<compatibility>Moved in version 2.0 to + the <a href="../mpm.html">MPMs</a></compatibility> + +<usage> + <p>Takes 1 or 2 parameters. The first parameter sets the soft + resource limit for all processes and the second parameter sets + the maximum resource limit. Either parameter can be a number, + or <em>max</em> to indicate to the server that the limit should + be set to the maximum allowed by the operating system + configuration. Raising the maximum resource limit requires that + the server is running as root, or in the initial startup + phase.</p> + + <p>This applies to processes forked off from Apache children + servicing requests, not the Apache children themselves. This + includes CGI scripts and SSI exec commands, but not any + processes forked off from the Apache parent such as piped + logs.</p> + + <p>CPU resource limits are expressed in seconds per + process.</p> +</usage> +<seealso><directive module="core">RLimitMEM</directive></seealso> +<seealso><directive module="core">RLimitNPROC</directive></seealso> +</directivesynopsis> + +<directivesynopsis> +<name>RLimitMEM</name> +<description>Limits the memory consumption of processes launched +by Apache children</description> +<syntax>RLimitMEM <em>number</em>|max [<em>number</em>|max]</syntax> +<default>Unset; uses operating system defaults</default> +<contextlist><context>server config</context><context>virtual host</context> +</contextlist> +<compatibility>Moved in version 2.0 to the <a +href="../mpm.html">MPMs</a>.</compatibility> + +<usage> + <p>Takes 1 or 2 parameters. The first parameter sets the soft + resource limit for all processes and the second parameter sets + the maximum resource limit. Either parameter can be a number, + or <em>max</em> to indicate to the server that the limit should + be set to the maximum allowed by the operating system + configuration. Raising the maximum resource limit requires that + the server is running as root, or in the initial startup + phase.</p> + + <p>This applies to processes forked off from Apache children + servicing requests, not the Apache children themselves. This + includes CGI scripts and SSI exec commands, but not any + processes forked off from the Apache parent such as piped + logs.</p> + + <p>Memory resource limits are expressed in bytes per + process.</p> +</usage> +<seealso><directive module="core">RLimitCPU</directive></seealso> +<seealso><directive module="core">RLimitNPROC</directive></seealso> +</directivesynopsis> + +<directivesynopsis> +<name>RLimitNPROC</name> +<description>Limits the number of processes that can be launched by +processes launched by Apache children</description> +<syntax>RLimitNPROC <em>number</em>|max [<em>number</em>|max]</syntax> +<default>Unset; uses operating system defaults</default> +<contextlist><context>server config</context><context>virtual host</context> +</contextlist> +<compatibility>Moved in version 2.0 to the <a +href="../mpm.html">MPMs</a>.</compatibility> + +<usage> + <p>Takes 1 or 2 parameters. The first parameter sets the soft + resource limit for all processes and the second parameter sets + the maximum resource limit. Either parameter can be a number, + or <code>max</code> to indicate to the server that the limit + should be set to the maximum allowed by the operating system + configuration. Raising the maximum resource limit requires that + the server is running as root, or in the initial startup + phase.</p> + + <p>This applies to processes forked off from Apache children + servicing requests, not the Apache children themselves. This + includes CGI scripts and SSI exec commands, but not any + processes forked off from the Apache parent such as piped + logs.</p> + + <p>Process limits control the number of processes per user.</p> + + <p>Note: If CGI processes are <strong>not</strong> running + under userids other than the web server userid, this directive + will limit the number of processes that the server itself can + create. Evidence of this situation will be indicated by + <strong><em>cannot fork</em></strong> messages in the + error_log.</p> +</usage> +<seealso><directive module="core">RLimitMEM</directive></seealso> +<seealso><directive module="core">RLimitCPU</directive></seealso> +</directivesynopsis> + +<directivesynopsis> +<name>Satisfy</name> +<description>Configures how host-level access control and user authentication +interact</description> +<syntax>Satisfy any|all</syntax> +<default>Satisfy all</default> +<contextlist><context>directory</context><context>.htaccess</context> +</contextlist> + +<usage> + <p>Access policy if both <directive + module="core">Allow</directive> and <directive + module="core">Require</directive> used. The parameter can be + either <em>'all'</em> or <em>'any'</em>. This directive is only + useful if access to a particular area is being restricted by both + username/password <em>and</em> client host address. In this case + the default behavior ("all") is to require that the client passes + the address access restriction <em>and</em> enters a valid + username and password. With the "any" option the client will be + granted access if they either pass the host restriction or enter a + valid username and password. This can be used to password restrict + an area, but to let clients from particular addresses in without + prompting for a password.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>ScriptInterpreterSource</name> +<description>Controls how the interpreter for CGI scripts is +located</description> +<syntax>ScriptInterpreterSource registry|script</syntax> +<default>ScriptInterpreterSource script</default> +<contextlist><context>directory</context><context>.htaccess</context> +</contextlist> +<compatibility>Win32 only</compatibility> + +<usage> + <p>This directive is used to control how Apache finds the + interpreter used to run CGI scripts. The default technique is to + use the interpreter pointed to by the #! line in the + script. Setting <code>ScriptInterpreterSource registry</code> will + cause the Windows Registry to be searched using the script file + extension (e.g., .pl) as a search key.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>ServerAdmin</name> +<description>Sets the email address that the server includes in error +messages sent to the client</description> +<syntax>ServerAdmin <em>email-address</em></syntax> +<contextlist><context>server config</context><context>virtual host</context> +</contextlist> + +<usage> + <p>The <directive>ServerAdmin</directive> sets the e-mail address + that the server includes in any error messages it returns to the + client.</p> + + <p>It may be worth setting up a dedicated address for this, + <em>e.g.</em></p> +<example>ServerAdmin www-admin@foo.bar.com</example> + <p>as users do not always mention that they are talking about the + server!</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>ServerAlias</name> +<description>Sets alternate names for a host used when matching requests +to name-virtual hosts</description> +<syntax>ServerAlias <em>hostname</em> [<em>hostname</em>] ...</syntax> +<contextlist><context>virtual host</context></contextlist> + +<usage> + <p>The <directive>ServerAlias</directive> directive sets the + alternate names for a host, for use with <a + href="../vhosts/name-based.html">name-based virtual hosts</a>.</p> + +<example> + <VirtualHost *><br /> + ServerName server.domain.com<br /> + ServerAlias server server2.domain.com server2<br /> + ...<br /> + </VirtualHost> +</example> +</usage> +<seealso><a href="../vhosts/">Apache Virtual Host documentation</a></seealso> +</directivesynopsis> + +<directivesynopsis> +<name>ServerName</name> +<description>Sets the hostname and port that the server uses to identify +itself</description> +<syntax>ServerName <em>fully-qualified-domain-name[:port]</em></syntax> +<contextlist><context>server config</context><context>virtual host</context> +</contextlist> +<compatibility>In version 2.0, this + directive supersedes the functionality of the <directive>Port</directive> + directive from version 1.3.</compatibility> + +<usage> + <p>The <directive>ServerName</directive> directive sets the hostname and + port that the server uses to identify itself. This is used when + creating redirection URLs. For example, if the name of the + machine hosting the webserver is <code>simple.example.com</code>, + but the machine also has the DNS alias <code>www.example.com</code> + and you wish the webserver to be so identified, the following + directive should be used:</p> + +<example>ServerName www.example.com:80</example> + + <p>If no <directive>ServerName</directive> is specified, then the + server attempts to deduce the hostname by performing a reverse + lookup on the IP address. If no port is specified in the + servername, then the server will use the port from the incoming + request. For optimal reliability and predictability, you should + specify an explicit hostname and port using the + <directive>ServerName</directive> directive.</p> + + <p>If you are using <a + href="../vhosts/name-based.html">name-based virtual hosts</a>, + the <directive>ServerName</directive> inside a + <directive type="section" module="core">VirtualHost</directive> + section specifies what hostname must appear in the request's + <code>Host:</code> header to match this virtual host.</p> + + <p>See the description of the + <directive module="core">UseCanonicalName</directive> directive for + settings which determine whether self-referential URL's (e.g., by the + <module>mod_dir</module> module) will refer to the + specified port, or to the port number given in the client's request. + </p> +</usage> + +<seealso><a href="../dns-caveats.html">DNS Issues</a></seealso> +<seealso><a href="../vhosts/">Apache virtual host + documentation</a></seealso> +<seealso><directive module="core">UseCanonicalName</directive></seealso> +<seealso><directive module="core">NameVirtualHost</directive></seealso> +<seealso><directive module="core">ServerAlias</directive></seealso> +</directivesynopsis> + +<directivesynopsis> +<name>ServerPath</name> +<description>Sets the legacy URL pathname for a name-virtual host that +is accessed by an incompatible browser</description> +<syntax>ServerPath <em>directory-path</em></syntax> +<contextlist><context>virtual host</context></contextlist> + +<usage> + <p>The <directive>ServerPath</directive> directive sets the legacy + URL pathname for a host, for use with <a + href="../vhosts/">name-based virtual hosts</a>.</p> +</usage> +<seealso><a href="../vhosts/">Apache Virtual Host documentation</a></seealso> +</directivesynopsis> + +<directivesynopsis> +<name>ServerRoot</name> +<description>Sets the base directory for the server installation</description> +<syntax>ServerRoot <em>directory-path</em></syntax> +<default>ServerRoot /usr/local/apache</default> +<contextlist><context>server config</context></contextlist> + +<usage> + <p>The <directive>ServerRoot</directive> directive sets the + directory in which the server lives. Typically it will contain the + subdirectories <code>conf/</code> and <code>logs/</code>. Relative + paths for other configuration files are taken as relative to this + directory.</p> +</usage> +<seealso><a href="../invoking.html">the <code>-d</code> + option to <code>httpd</code></a></seealso> +<seealso><a href="../misc/security_tips.html#serverroot">the + security tips</a> for information on how to properly set + permissions on the ServerRoot</seealso> +</directivesynopsis> + +<directivesynopsis> +<name>ServerSignature</name> +<description>Configures the footer on server-generated documents</description> +<syntax>ServerSignature On|Off|EMail</syntax> +<default>ServerSignature Off</default> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context> +</contextlist> + +<usage> + <p>The <directive>ServerSignature</directive> directive allows the + configuration of a trailing footer line under server-generated + documents (error messages, mod_proxy ftp directory listings, + mod_info output, ...). The reason why you would want to enable + such a footer line is that in a chain of proxies, the user often + has no possibility to tell which of the chained servers actually + produced a returned error message.<br /> The <samp>Off</samp> + setting, which is the default, suppresses the error line (and is + therefore compatible with the behavior of Apache-1.2 and + below). The <samp>On</samp> setting simply adds a line with the + server version number and <directive + module="core">ServerName</directive> of the serving virtual host, + and the <samp>EMail</samp> setting additionally creates a + "mailto:" reference to the <directive + module="core">ServerAdmin</directive> of the referenced + document.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>ServerTokens</name> +<description>Configures the Server HTTP response header</description> +<syntax>ServerTokens Minimal|ProductOnly|OS|Full</syntax> +<default>ServerTokens Full</default> +<contextlist><context>server config</context></contextlist> + +<usage> + <p>This directive controls whether <samp>Server</samp> response + header field which is sent back to clients includes a + description of the generic OS-type of the server as well as + information about compiled-in modules.</p> + + <dl> + <dt><code>ServerTokens Prod[uctOnly]</code></dt> + + <dd>Server sends (<em>e.g.</em>): <samp>Server: + Apache</samp></dd> + + <dt><code>ServerTokens Min[imal]</code></dt> + + <dd>Server sends (<em>e.g.</em>): <samp>Server: + Apache/1.3.0</samp></dd> + + <dt><code>ServerTokens OS</code></dt> + + <dd>Server sends (<em>e.g.</em>): <samp>Server: Apache/1.3.0 + (Unix)</samp></dd> + + <dt><code>ServerTokens Full</code> (or not specified)</dt> + + <dd>Server sends (<em>e.g.</em>): <samp>Server: Apache/1.3.0 + (Unix) PHP/3.0 MyMod/1.2</samp></dd> + </dl> + + <p>This setting applies to the entire server, and cannot be + enabled or disabled on a virtualhost-by-virtualhost basis.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>SetHandler</name> +<description>Forces all matching files to be processed by a +handler</description> +<syntax>SetHandler <em>handler-name</em></syntax> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context> +</contextlist> +<compatibility>Moved into the core in Apache 2.0</compatibility> + +<usage> + <p>When placed into an <code>.htaccess</code> file or a + <directive type="section" module="core">Directory</directive> or + <directive type="section" module="core">Location</directive> + section, this directive forces all matching files to be parsed + through the <a href="../handler.html">handler</a> given by + <em>handler-name</em>. For example, if you had a directory you + wanted to be parsed entirely as imagemap rule files, regardless + of extension, you might put the following into an + <code>.htaccess</code> file in that directory:</p> +<example> + SetHandler imap-file +</example> + + <p>Another example: if you wanted to have the server display a + status report whenever a URL of + <code>http://servername/status</code> was called, you might put + the following into httpd.conf:</p> +<example> + <Location /status><br /> + SetHandler server-status<br /> + </Location> +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>SetInputFilter</name> +<description>Sets the filters that will process client requests and POST +input</description> +<syntax>SetInputFilter <em>filter</em>[<em>;filter</em>...]</syntax> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context> +</contextlist> + +<usage> + <p>The <directive>SetInputFilter</directive> directive sets the + filter or filters which will process client requests and POST + input when they are received by the server. This is in addition to + any filters defined elsewhere, including the + <directive module="mod_mime">AddInputFilter</directive> + directive.</p> + + <p>If more than one filter is specified, they must be separated + by semicolons in the order in which they should process the + content.</p> +</usage> +<seealso><a href="../filter.html">Filters</a> documentation</seealso> +</directivesynopsis> + +<directivesynopsis> +<name>SetOutputFilter</name> +<description>Sets the filters that will process responses from the +server</description> +<syntax>SetOutputFilter <em>filter</em> [<em>filter</em>] ...</syntax> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context> +</contextlist> + +<usage> + <p>The <directive>SetOutputFilter</directive> directive sets the filters + which will process responses from the server before they are + sent to the client. This is in addition to any filters defined + elsewhere, including the + <directive module="mod_mime">AddOutputFilter</directive> + directive.</p> + + <p>For example, the following configuration will process all files + in the <code>/www/data/</code> directory for server-side + includes.</p> +<example> +<Directory /www/data/><br /> + SetOutputFilter INCLUDES<br /> +</Directory> +</example> + + <p>If more than one filter is specified, they must be separated + by semicolons in the order in which they should process the + content.</p> +</usage> +<seealso><a href="../filter.html">Filters</a> documentation</seealso> +</directivesynopsis> + +<directivesynopsis> +<name>TimeOut</name> +<description>Defines the amount of time the server will wait for +certain events before failing a request</description> +<syntax>TimeOut <em>number</em></syntax> +<default>TimeOut 300</default> +<contextlist><context>server config</context></contextlist> + +<usage> + <p>The <directive>TimeOut</directive> directive currently defines + the amount of time Apache will wait for three things:</p> + + <ol> + <li>The total amount of time it takes to receive a GET + request.</li> + + <li>The amount of time between receipt of TCP packets on a + POST or PUT request.</li> + + <li>The amount of time between ACKs on transmissions of TCP + packets in responses.</li> + </ol> + + <p>We plan on making these separately configurable at some point + down the road. The timer used to default to 1200 before 1.2, + but has been lowered to 300 which is still far more than + necessary in most situations. It is not set any lower by + default because there may still be odd places in the code where + the timer is not reset when a packet is sent. </p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>UseCanonicalName</name> +<description>Configures how the server determines its own name and +port</description> +<syntax>UseCanonicalName on|off|dns</syntax> +<default>UseCanonicalName on</default> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context></contextlist> +<override>Options</override> + +<usage> + <p>In many situations Apache has to construct a + <em>self-referential</em> URL. That is, a URL which refers back to + the same server. With <code>UseCanonicalName on</code> Apache will + use the hostname and port specified in the <directive + module="core">ServerName</directive> directive to construct a canonical + name for the server. This name is used in all self-referential + URLs, and for the values of <code>SERVER_NAME</code> and + <code>SERVER_PORT</code> in CGIs.</p> + + <p>With <code>UseCanonicalName off</code> Apache will form + self-referential URLs using the hostname and port supplied by + the client if any are supplied (otherwise it will use the + canonical name). These values are the same that are used to + implement <a href="../vhosts/name-based.html">name based + virtual hosts</a>, and are available with the same clients. The + CGI variables <code>SERVER_NAME</code> and + <code>SERVER_PORT</code> will be constructed from the client + supplied values as well.</p> + + <p>An example where this may be useful is on an intranet server + where you have users connecting to the machine using short + names such as <code>www</code>. You'll notice that if the users + type a shortname, and a URL which is a directory, such as + <code>http://www/splat</code>, <em>without the trailing + slash</em> then Apache will redirect them to + <code>http://www.domain.com/splat/</code>. If you have + authentication enabled, this will cause the user to have to + reauthenticate twice (once for <code>www</code> and once again + for <code>www.domain.com</code>). But if + <directive>UseCanonicalName</directive> is set off, then Apache will + redirect to <code>http://www/splat/</code>.</p> + + <p>There is a third option, <code>UseCanonicalName DNS</code>, + which is intended for use with mass IP-based virtual hosting to + support ancient clients that do not provide a + <code>Host:</code> header. With this option Apache does a + reverse DNS lookup on the server IP address that the client + connected to in order to work out self-referential URLs.</p> + + <p><strong>Warning:</strong> if CGIs make assumptions about the + values of <code>SERVER_NAME</code> they may be broken by this + option. The client is essentially free to give whatever value + they want as a hostname. But if the CGI is only using + <code>SERVER_NAME</code> to construct self-referential URLs + then it should be just fine.</p> +</usage> +<seealso><directive module="core">ServerName</directive></seealso> +<seealso><directive module="mpm_common">Listen</directive></seealso> +</directivesynopsis> + +<directivesynopsis type="section"> +<name>VirtualHost</name> +<description>Contains directives that apply only to a specific +hostname or IP address</description> +<syntax><VirtualHost + <em>addr</em>[:<em>port</em>] [<em>addr</em>[:<em>port</em>]] + ...> ... </VirtualHost></syntax> +<contextlist><context>server config</context></contextlist> + +<usage> + <p><directive type="section">VirtualHost</directive> and + <code></VirtualHost></code> are used to enclose a group of + directives which will apply only to a particular virtual host. Any + directive which is allowed in a virtual host context may be + used. When the server receives a request for a document on a + particular virtual host, it uses the configuration directives + enclosed in the <directive type="section">VirtualHost</directive> + section. <em>Addr</em> can be</p> + + <ul> + <li>The IP address of the virtual host</li> + + <li>A fully qualified domain name for the IP address of the + virtual host.</li> + </ul> + Example: + +<example><VirtualHost 10.1.2.3><br /> + ServerAdmin webmaster@host.foo.com<br /> + DocumentRoot /www/docs/host.foo.com<br /> + ServerName host.foo.com<br /> + ErrorLog logs/host.foo.com-error_log<br /> + TransferLog logs/host.foo.com-access_log<br /> + </VirtualHost> +</example> + + + <p>IPv6 addresses must be specified in square brackets because + the optional port number could not be determined otherwise. An + IPv6 example is shown below:</p> + +<example> +<VirtualHost [fe80::a00:20ff:fea7:ccea]><br /> + ServerAdmin webmaster@host.foo.com<br /> + DocumentRoot /www/docs/host.foo.com<br /> + ServerName host.foo.com<br /> + ErrorLog logs/host.foo.com-error_log<br /> + TransferLog logs/host.foo.com-access_log<br /> + </VirtualHost> +</example> + + <p>Each Virtual Host must correspond to a different IP address, + different port number or a different host name for the server, + in the former case the server machine must be configured to + accept IP packets for multiple addresses. (If the machine does + not have multiple network interfaces, then this can be + accomplished with the <code>ifconfig alias</code> command (if + your OS supports it), or with kernel patches like <a + href="../misc/vif-info.html">VIF</a> (for SunOS(TM) 4.1.x)).</p> + + <p>The special name <code>_default_</code> can be specified in + which case this virtual host will match any IP address that is + not explicitly listed in another virtual host. In the absence + of any _default_ virtual host the "main" server config, + consisting of all those definitions outside any VirtualHost + section, is used when no match occurs.</p> + + <p>You can specify a <code>:port</code> to change the port that is + matched. If unspecified then it defaults to the same port as the + most recent <directive module="mpm_common">Listen</directive> + statement of the main server. You may also specify <code>:*</code> + to match all ports on that address. (This is recommended when used + with <code>_default_</code>.)</p> + + <p><strong>SECURITY</strong>: See the <a + href="../misc/security_tips.html">security tips</a> document + for details on why your security could be compromised if the + directory where logfiles are stored is writable by anyone other + than the user that starts the server.</p> + + <p><strong>NOTE</strong>: The use of <directive + type="section">VirtualHost</directive> does <strong>not</strong> + affect what addresses Apache listens on. You may need to ensure + that Apache is listening on the correct addresses using <directive + module="mpm_common">Listen</directive>.</p> +</usage> +<seealso><a href="../vhosts/">Apache Virtual Host documentation</a></seealso> +<seealso><a href="../dns-caveats.html">Warnings about DNS and + Apache</a></seealso> +<seealso><a href="../bind.html">Setting + which addresses and ports Apache uses</a></seealso> +<seealso><a href="../sections.html">How + Directory, Location and Files sections work</a> for an + explanation of how these different sections are combined when a + request is received</seealso> +</directivesynopsis> + +</modulesynopsis>
\ No newline at end of file diff --git a/docs/manual/mod/directives.xml b/docs/manual/mod/directives.xml new file mode 100644 index 0000000000..6ef8220c07 --- /dev/null +++ b/docs/manual/mod/directives.xml @@ -0,0 +1,17 @@ +<?xml version="1.0"?> +<!DOCTYPE directiveindex [ + <!ENTITY allmodules SYSTEM "allmodules.xml"> +]> + +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<directiveindex> +<title>Directive Index</title> +<summary> + <p>Each Apache directive available in the standard Apache + distribution is listed here. They are described using a + consistent format, and there is <a href="directive-dict.html" + rel="Glossary">a dictionary</a> of the terms used in their + descriptions available.</p> +</summary> +&allmodules; +</directiveindex>
\ No newline at end of file diff --git a/docs/manual/mod/index.xml b/docs/manual/mod/index.xml new file mode 100644 index 0000000000..a509c2eb0d --- /dev/null +++ b/docs/manual/mod/index.xml @@ -0,0 +1,18 @@ +<?xml version="1.0"?> +<!DOCTYPE directiveindex [ + <!ENTITY allmodules SYSTEM "allmodules.xml"> +]> + +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<moduleindex> +<title>Module Index</title> +<summary> + + <p>Below is a list of all of the modules that come as part of + the Apache distribution. See also the complete + alphabetical list of <a href="directives.html">all Apache + directives</a>.</p> + +</summary> +&allmodules; +</moduleindex>
\ No newline at end of file diff --git a/docs/manual/mod/mod_actions.xml b/docs/manual/mod/mod_actions.xml new file mode 100644 index 0000000000..e702dbe134 --- /dev/null +++ b/docs/manual/mod/mod_actions.xml @@ -0,0 +1,115 @@ +<?xml version="1.0"?> +<!DOCTYPE xml:manual [ <!ENTITY nbsp " "> ]> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>mod_actions</name> + +<description>This module provides for executing CGI scripts based on +media type or request method.</description> + +<status>Base</status> +<sourcefile>mod_actions.c</sourcefile> +<identifier>actions_module</identifier> + +<summary> + <p>This module has two directives. The <directive + module="mod_actions">Action</directive> directive lets you run CGI + scripts whenever a file of a certain type is requested. The + <directive module="mod_actions">Script</directive> directive lets + you run CGI scripts whenever a particular method is used in a + request. This makes it much easier to execute scripts that process + files.</p> +</summary> + +<directivesynopsis> + +<name>Action</name> + +<description>Activates a CGI script for a particular handler or +content-type</description> + +<syntax>Action <em>action-type cgi-script</em></syntax> +<contextlist> +<context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context> +</contextlist> +<override>FileInfo</override> + +<usage> + <p>This directive adds an action, which will activate + <em>cgi-script</em> when <em>action-type</em> is triggered by + the request. The <em>action-type</em> can be either a <a + href="../handler.html">handler</a> or a MIME content type. It + sends the URL and file path of the requested document using the + standard CGI PATH_INFO and PATH_TRANSLATED environment + variables.</p> + +<example> +<title>Examples</title> + + # Requests for files of a particular type:<br /> + Action image/gif /cgi-bin/images.cgi<br /> +<br /> + # Files of a particular file extension<br /> + AddHandler my-file-type .xyz<br /> + Action my-file-type /cgi-bin/program.cgi<br /> +</example> + + <p>In the first example, requests for files with a MIME content + type of <code>image/gif</code> will instead be handled by the + specified cgi script <code>/cgi-bin/images.cgi</code>.</p> + + <p>In the second example, requests for files with a file extension of + <code>.xyz</code> are handled instead by the specified cgi script + <code>/cgi-bin/program.cgi</code>.</p> +</usage> + +<seealso><directive module="mod_mime">AddHandler</directive></seealso> + +</directivesynopsis> + +<directivesynopsis> + +<name>Script</name> + +<description>Activates a CGI script for a particular request +method.</description> +<syntax> Script <em>method cgi-script</em></syntax> +<contextlist> +<context>server config</context><context>virtual host</context> +<context>directory</context></contextlist> +<usage> + <p>This directive adds an action, which will activate + <em>cgi-script</em> when a file is requested using the method of + <em>method</em>. It sends the URL and file path of the requested + document using the standard CGI PATH_INFO and PATH_TRANSLATED + environment variables.</p> + +<note> + Any arbitrary method name may be used. <strong>Method names are + case-sensitive</strong>, so <code>Script PUT</code> and + <code>Script put</code> have two entirely different + effects. +</note> + + <p>Note that the Script command defines default actions only. + If a CGI script is called, or some other resource that is + capable of handling the requested method internally, it will do + so. Also note that Script with a method of <code>GET</code> + will only be called if there are query arguments present + (<em>e.g.</em>, foo.html?hi). Otherwise, the request will + proceed normally.</p> + +<example> +<title>Examples</title> + # For <ISINDEX>-style searching<br /> + Script GET /cgi-bin/search<br /> + # A CGI PUT handler<br /> + Script PUT /~bob/put.cgi<br /> +</example> +</usage> + +</directivesynopsis> + +</modulesynopsis>
\ No newline at end of file diff --git a/docs/manual/mod/mod_alias.xml b/docs/manual/mod/mod_alias.xml new file mode 100644 index 0000000000..84db11dc1c --- /dev/null +++ b/docs/manual/mod/mod_alias.xml @@ -0,0 +1,279 @@ +<?xml version="1.0"?> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>mod_alias</name> +<description>Provides for mapping different parts of the host + filesystem in the document tree and for URL redirection</description> +<status>Base</status> +<sourcefile>mod_alias.c</sourcefile> +<identifier>alias_module</identifier> + +<summary> + <p>The directives contained in this module allow for manipulation + and control of URLs as requests arrive at the server. The + <directive module="mod_alias">Alias</directive> and <directive + module="mod_alias">ScriptAlias</directive> directives are used to + map between URLs and filesystem paths. This allows for content + which is not directly under the <directive + module="core">DocumentRoot</directive> served as part of the web + document tree. The <directive + module="mod_alias">ScriptAlias</directive> directive has the + additional effect of marking the target directory as containing + only CGI scripts.</p> + + <p>The <directive module="mod_alias">Redirect</directive> + directives are used to instruct clients to make a new request with + a different URL. They are often used when a resource has moved to + a new location.</p> + + <p>A more powerful and flexible set of directives for + manipulating URLs is contained in the <module>mod_rewrite</module> + module.</p> +</summary> + +<directivesynopsis> +<name>Alias</name> +<description>Maps URLs to filesystem locations</description> +<syntax> Alias <em>URL-path + file-path</em>|<em>directory-path</em></syntax> +<contextlist><context>server config</context><context>virtual host</context> +</contextlist> + +<usage> + + <p>The <directive>Alias</directive> directive allows documents to + be stored in the local filesystem other than under the + <directive module="core">DocumentRoot</directive>. URLs with a + (%-decoded) path beginning with <em>url-path</em> will be mapped + to local files beginning with <em>directory-filename</em>.</p> + + <p>Example:</p> + +<example>Alias /image /ftp/pub/image</example> + + <p>A request for http://myserver/image/foo.gif would cause the + server to return the file /ftp/pub/image/foo.gif.</p> + + <p>Note that if you include a trailing / on the + <em>url-path</em> then the server will require a trailing / in + order to expand the alias. That is, if you use <code>Alias + /icons/ /usr/local/apache/icons/</code> then the url + <code>/icons</code> will not be aliased.</p> + + <p>Note that you may need to specify additional <directive + module="core"><Directory></directive> sections which cover + the <em>destination</em> of aliases. Aliasing occurs before + <directive module="core"><Directory></directive> sections + are checked, so only the destination of aliases are affected. + (Note however <directive module="core"><Location></directive> + sections are run through once before aliases are performed, so + they will apply.)</p> + +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>AliasMatch</name> +<description>Maps URLs to filesystem locations using regular +expressions</description> +<syntax>AliasMatch <em>regex + file-path</em>|<em>directory-path</em></syntax> +<contextlist><context>server config</context><context>virtual host</context> +</contextlist> + +<usage> + <p>This directive is equivalent to <directive + module="mod_alias">Alias</directive>, but makes use of standard + regular expressions, instead of simple prefix matching. The + supplied regular expression is matched against the URL-path, and + if it matches, the server will substitute any parenthesized + matches into the given string and use it as a filename. For + example, to activate the <code>/icons</code> directory, one might + use:</p> +<example> + AliasMatch ^/icons(.*) /usr/local/apache/icons$1 +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>Redirect</name> +<description>Sends an external redirect asking the client to fetch +a different URL</description> +<syntax>Redirect [<em>status</em>] <em>URL-path URL</em></syntax> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context></contextlist> +<override>FileInfo</override> + +<usage> + <p>The Redirect directive maps an old URL into a new one. The + new URL is returned to the client which attempts to fetch it + again with the new address. <em>URL-path</em> a (%-decoded) + path; any requests for documents beginning with this path will + be returned a redirect error to a new (%-encoded) URL beginning + with <em>URL</em>.</p> + + <p>Example:</p> + +<example>Redirect /service http://foo2.bar.com/service</example> + + <p>If the client requests http://myserver/service/foo.txt, it + will be told to access http://foo2.bar.com/service/foo.txt + instead.</p> + +<note><title>Note</title> <p>Redirect directives take precedence over +Alias and ScriptAlias directives, irrespective of their ordering in +the configuration file. Also, <em>URL-path</em> must be an absolute +path, not a relative path, even when used with .htaccess files or +inside of <directive module="core"><Directory></directive> +sections.</p></note> + + <p>If no <em>status</em> argument is given, the redirect will + be "temporary" (HTTP status 302). This indicates to the client + that the resource has moved temporarily. The <em>status</em> + argument can be used to return other HTTP status codes:</p> + + <dl> + <dt>permanent</dt> + + <dd>Returns a permanent redirect status (301) indicating that + the resource has moved permanently.</dd> + + <dt>temp</dt> + + <dd>Returns a temporary redirect status (302). This is the + default.</dd> + + <dt>seeother</dt> + + <dd>Returns a "See Other" status (303) indicating that the + resource has been replaced.</dd> + + <dt>gone</dt> + + <dd>Returns a "Gone" status (410) indicating that the + resource has been permanently removed. When this status is + used the <em>url</em> argument should be omitted.</dd> + </dl> + + <p>Other status codes can be returned by giving the numeric + status code as the value of <em>status</em>. If the status is + between 300 and 399, the <em>url</em> argument must be present, + otherwise it must be omitted. Note that the status must be + known to the Apache code (see the function + <code>send_error_response</code> in http_protocol.c).</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>RedirectMatch</name> +<description>Sends an external redirect asking the client to fetch +a different URL based on a regular expression match of the +current URL</description> +<syntax>RedirectMatch [<em>status</em>] <em>regex URL</em></syntax> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context></contextlist> +<override>FileInfo</override> + +<usage> + <p>This directive is equivalent to <directive + module="mod_alias">Redirect</directive>, but makes use of standard + regular expressions, instead of simple prefix matching. The + supplied regular expression is matched against the URL-path, and + if it matches, the server will substitute any parenthesized + matches into the given string and use it as a filename. For + example, to redirect all GIF files to like-named JPEG files on + another server, one might use:</p> +<example> + RedirectMatch (.*)\.gif$ http://www.anotherserver.com$1.jpg +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>RedirectTemp</name> +<description>Sends an external temporary redirect asking the client to fetch +a different URL</description> +<syntax>RedirectTemp <em>URL-path URL</em></syntax> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context></contextlist> +<override>FileInfo</override> + +<usage> + <p>This directive makes the client know that the Redirect is + only temporary (status 302). Exactly equivalent to + <code>Redirect temp</code>.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>RedirectPermanent</name> +<description>Sends an external permanent redirect asking the client to fetch +a different URL</description> +<syntax>RedirectPermanent <em>URL-path URL</em></syntax> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context></contextlist> +<override>FileInfo</override> + +<usage> + <p>This directive makes the client know that the Redirect is + permanent (status 301). Exactly equivalent to <code>Redirect + permanent</code>.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>ScriptAlias</name> +<description>Maps a URL to a filesystem location and designates the +target as a CGI script</description> +<syntax>ScriptAlias +<em>URL-path file-path</em>|<em>directory-path</em></syntax> +<contextlist><context>server config</context><context>virtual host</context> +</contextlist> + +<usage> + <p>The <directive>ScriptAlias</directive> directive has the same + behavior as the <directive module="mod_alias">Alias</directive> + directive, except that in addition it marks the target directory + as containing CGI scripts that will be processed by <module + >mod_cgi</module>'s cgi-script handler. URLs with a + (%-decoded) path beginning with <em>URL-path</em> will be mapped + to scripts beginning with the second argument which is a full + pathname in the local filesystem.</p> + + <p>Example:</p> + +<example>ScriptAlias /cgi-bin/ /web/cgi-bin/</example> + + <p>A request for <code>http://myserver/cgi-bin/foo</code> would cause the + server to run the script <code>/web/cgi-bin/foo</code>.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>ScriptAliasMatch</name> +<description>Maps a URL to a filesystem location using a regular expression +and designates the target as a CGI script</description> +<syntax>ScriptAliasMatch +<em>regex file-path</em>|<em>directory-path</em></syntax> +<contextlist><context>server config</context><context>virtual host</context> +</contextlist> + +<usage> + <p>This directive is equivalent to <directive module="mod_alias" + >ScriptAlias</directive>, but makes use of standard + regular expressions, instead of simple prefix matching. The + supplied regular expression is matched against the URL-path, + and if it matches, the server will substitute any parenthesized + matches into the given string and use it as a filename. For + example, to activate the standard <code>/cgi-bin</code>, one + might use:</p> +<example> + ScriptAliasMatch ^/cgi-bin(.*) /usr/local/apache/cgi-bin$1 +</example> +</usage> +</directivesynopsis> + +</modulesynopsis> + diff --git a/docs/manual/mod/mod_asis.xml b/docs/manual/mod/mod_asis.xml new file mode 100644 index 0000000000..171e2b6681 --- /dev/null +++ b/docs/manual/mod/mod_asis.xml @@ -0,0 +1,69 @@ +<?xml version="1.0"?> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>mod_asis</name> +<description>Sends files that contain their own +HTTP headers</description> +<status>Base</status> +<sourcefile>mod_asis.c</sourcefile> +<identifier>asis_module</identifier> + +<summary> + <p>This module provides the handler <code>send-as-is</code> + which causes Apache to send the document without adding most of + the usual HTTP headers.</p> + + <p>This can be used to send any kind of data from the server, + including redirects and other special HTTP responses, without + requiring a cgi-script or an nph script.</p> + + <p>For historical reasons, this module will also process any + file with the mime type <code>httpd/send-as-is</code>.</p> +</summary> + +<section><title>Usage</title> + + <p>In the server configuration file, associate files with the + <code>send-as-is</code> handler <em>e.g.</em></p> + +<example>AddHandler send-as-is asis</example> + + <p>The contents of any file with a <code>.asis</code> extension + will then be sent by Apache to the client with almost no + changes. Clients will need HTTP headers to be attached, so do + not forget them. A Status: header is also required; the data + should be the 3-digit HTTP response code, followed by a textual + message.</p> + + <p>Here's an example of a file whose contents are sent <em>as + is</em> so as to tell the client that a file has + redirected.</p> + + +<example>Status: 301 Now where did I leave that URL<br /> + Location: http://xyz.abc.com/foo/bar.html<br /> + Content-type: text/html<br /> + <br /> + <HTML><br /> + <HEAD><br /> + <TITLE>Lame excuses'R'us</TITLE><br /> + </HEAD><br /> + <BODY><br /> + <H1>Fred's exceptionally wonderful page has moved + to<br /> + <A + HREF="http://xyz.abc.com/foo/bar.html">Joe's</A> + site.<br /> + </H1><br /> + </BODY><br /> + </HTML> +</example> + + <p>Notes: the server always adds a Date: and Server: header to + the data returned to the client, so these should not be + included in the file. The server does <em>not</em> add a + Last-Modified header; it probably should. </p> +</section> + +</modulesynopsis> diff --git a/docs/manual/mod/mod_auth_digest.xml b/docs/manual/mod/mod_auth_digest.xml new file mode 100644 index 0000000000..3d3c544278 --- /dev/null +++ b/docs/manual/mod/mod_auth_digest.xml @@ -0,0 +1,270 @@ +<?xml version="1.0"?> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> +<name>mod_auth_digest</name> +<description>User authentication using MD5 + Digest Authentication.</description> +<status>Experimental</status> +<sourcefile>mod_auth_digest.c</sourcefile> +<identifier>auth_digest_module</identifier> + +<summary> + <p>This module implements HTTP Digest Authentication. However, it + has not been extensively tested and is therefore marked + experimental.</p> +</summary> + +<seealso><directive module="core">AuthName</directive></seealso> +<seealso><directive module="core">AuthType</directive></seealso> +<seealso><directive module="core">Require</directive></seealso> +<seealso><directive module="core">Satisfy</directive></seealso> + +<section><title>Using Digest Authentication</title> + + <p>Using MD5 Digest authentication is very simple. Simply set + up authentication normally, using "AuthType Digest" and + "AuthDigestFile" instead of the normal "AuthType Basic" and + "AuthUserFile"; also, replace any "AuthGroupFile" with + "AuthDigestGroupFile". Then add a "AuthDigestDomain" directive + containing at least the root URI(s) for this protection space. + Example:</p> +<example> + <Location /private/><br /> + AuthType Digest<br /> + AuthName "private area"<br /> + AuthDigestDomain /private/ http://mirror.my.dom/private2/<br /> + AuthDigestFile /web/auth/.digest_pw<br /> + Require valid-user<br /> + </Location> +</example> + +<note><title>Note</title> + <p>MD5 authentication provides a more + secure password system than Basic authentication, but only + works with supporting browsers. As of this writing (October 2001), + the only major browsers which support digest authentication are + <a href="http://www.opera.com/">Opera 4.0</a>, + <a href="http://www.microsoft.com/windows/ie/">MS Internet + Explorer 5.0</a> and <a href="http://www.w3.org/Amaya/">Amaya</a>. + Therefore, we do not yet recommend using this feature on a large + Internet site. However, for personal and intra-net use, where + browser users can be controlled, it is ideal.</p> +</note> +</section> + +<directivesynopsis> +<name>AuthDigestFile</name> +<description>Location of the text file containing the list +of users and encoded passwords for digest authentication</description> +<syntax>AuthDigestFile <em>file-path</em></syntax> +<contextlist><context>directory</context><context>.htaccess</context> +</contextlist> +<override>AuthConfig</override> + +<usage> + <p>The <directive>AuthDigestFile</directive> directive sets the + name of a textual file containing the list of users and encoded + passwords for digest authentication. <em>File-path</em> is the + absolute path to the user file.</p> + + <p>The digest file uses a special format. Files in this format + can be created using the <a + href="../programs/htdigest.html">htdigest</a> utility found in + the support/ subdirectory of the Apache distribution.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>AuthDigestGroupFile</name> +<description>Name of the text file containing the list of groups +for digest authentication</description> +<syntax>AuthDigestGroupFile <em>file-path</em></syntax> +<contextlist><context>directory</context><context>.htaccess</context> +</contextlist> +<override>AuthConfig</override> + +<usage> + <p>The <directive>AuthDigestGroupFile</directive> directive sets + the name of a textual file containing the list of groups and their + members (user names). <em>File-path</em> is the absolute path to + the group file.</p> + + <p>Each line of the group file contains a groupname followed by + a colon, followed by the member usernames separated by spaces. + Example:</p> + +<example>mygroup: bob joe anne</example> + + <p>Note that searching large text files is <em>very</em> + inefficient.</p> + + <p>Security: make sure that the AuthGroupFile is stored outside + the document tree of the web-server; do <em>not</em> put it in + the directory that it protects. Otherwise, clients will be able + to download the AuthGroupFile.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>AuthDigestQop</name> +<description>Determines the quality-of-protection to use in digest +authentication</description> +<syntax>AuthDigestQop none|auth|auth-int [auth|auth-int]</syntax> +<default>AuthDigestQop auth</default> +<contextlist><context>directory</context><context>.htaccess</context> +</contextlist> +<override>AuthConfig</override> + +<usage> + <p>The <directive>AuthDigestQop</directive> directive determines + the quality-of-protection to use. <em>auth</em> will only do + authentication (username/password); <em>auth-int</em> is + authentication plus integrity checking (an MD5 hash of the entity + is also computed and checked); <em>none</em> will cause the module + to use the old RFC-2069 digest algorithm (which does not include + integrity checking). Both <em>auth</em> and <em>auth-int</em> may + be specified, in which the case the browser will choose which of + these to use. <em>none</em> should only be used if the browser for + some reason does not like the challenge it receives otherwise.</p> + + <p><strong><em>auth-int</em> is not implemented + yet</strong>.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>AuthDigestNonceLifetime</name> +<description>How long the server nonce is valid</description> +<syntax>AuthDigestNonceLifetime <em>seconds</em></syntax> +<default>AuthDigestNonceLifetime 300</default> +<contextlist><context>directory</context><context>.htaccess</context> +</contextlist> +<override>AuthConfig</override> + +<usage> + <p>The <directive>AuthDigestNonceLifetime</directive> directive + controls how long the server nonce is valid. When the client + contacts the server using an expired nonce the server will send + back a 401 with <code>stale=true</code>. If <em>seconds</em> is + greater than 0 then it specifies the amount of time for which the + nonce is valid; this should probably never be set to less than 10 + seconds. If <em>seconds</em> is less than 0 then the nonce never + expires. <!-- Not implemented yet If <EM>seconds</EM> is 0 then + the nonce may be used exactly once by the client. Note that while + one-time-nonces provide higher security against replay attacks, + they also have significant performance implications, as the + browser cannot pipeline or multiple connections for the + requests. Because browsers cannot easily detect that + one-time-nonces are being used, this may lead to browsers trying + to pipeline requests and receiving 401 responses for all but the + first request, requiring the browser to resend the requests. Note + also that the protection against reply attacks only makes sense + for dynamically generated content and things like POST requests; + for static content the attacker may already have the complete + response, so one-time-nonces do not make sense here. --> + </p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>AuthDigestNonceFormat</name> +<description>Determines how the nonce is generated</description> +<syntax>???</syntax> +<default>???</default> +<contextlist><context>directory</context><context>.htaccess</context> +</contextlist> +<override>AuthConfig</override> + +<usage> + <p><strong>Not implemented yet.</strong> <!-- + <P>The AuthDigestNonceFormat directive determines how the nonce is + generated. + --> + </p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>AuthDigestNcCheck</name> +<description>Enables or disables checking of the nonce-count sent by the +server</description> +<syntax>AuthDigestNcCheck On|Off</syntax> +<default>AuthDigestNcCheck Off</default> +<contextlist><context>server config</context></contextlist> + +<usage> + <p><strong>Not implemented yet.</strong> <!-- + <P>The AuthDigestNcCheck directive enables or disables the checking of the + nonce-count sent by the server. + + <P>While recommended from a security standpoint, turning this directive + On has one important performance implication. To check the nonce-count + *all* requests (which have an Authorization header, irrespective of + whether they require digest authentication) must be serialized through + a critical section. If the server is handling a large number of + requests which contain the Authorization header then this may noticeably + impact performance. + --> + </p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>AuthDigestAlgorithm</name> +<description>Selects the algorithm used to calculate the challenge and +response hases in digest authentication</description> +<syntax>AuthDigestAlgorithm MD5|MD5-sess</syntax> +<default>AuthDigestAlgorithm MD5</default> +<contextlist><context>directory</context><context>.htaccess</context> +</contextlist> +<override>AuthConfig</override> + +<usage> + <p>The <directive>AuthDigestAlgorithm</directive> directive + selects the algorithm used to calculate the challenge and response + hashes.</p> + + <p><strong><em>MD5-sess</em> is not correctly implemented + yet</strong>. <!-- + <P>To use <EM>MD5-sess</EM> you must first code up the + <VAR>get_userpw_hash()</VAR> function in <VAR>mod_auth_digest.c</VAR> . + --> + </p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>AuthDigestDomain</name> +<description>URIs that are in the same protection space for digest +authentication</description> +<syntax>AuthDigestDomain <em>URI</em> [<em>URI</em>] ...</syntax> +<contextlist><context>directory</context><context>.htaccess</context> +</contextlist> +<override>AuthConfig</override> + +<usage> + <p>The <directive>AuthDigestDomain</directive> directive allows + you to specify one or more URIs which are in the same protection + space (i.e. use the same realm and username/password info). The + specified URIs are prefixes, i.e. the client will assume that all + URIs "below" these are also protected by the same + username/password. The URIs may be either absolute URIs + (i.e. inluding a scheme, host, port, etc) or relative URIs.</p> + + <p>This directive <em>should</em> always be specified and + contain at least the (set of) root URI(s) for this space. + Omitting to do so will cause the client to send the + Authorization header for <em>every request</em> sent to this + server. Apart from increasing the size of the request, it may + also have a detrimental effect on performance if + "AuthDigestNcCheck" is on.</p> + + <p>The URIs specified can also point to different servers, in + which case clients (which understand this) will then share + username/password info across multiple servers without + prompting the user each time. </p> +</usage> +</directivesynopsis> + +</modulesynopsis> + diff --git a/docs/manual/mod/mod_autoindex.xml b/docs/manual/mod/mod_autoindex.xml new file mode 100644 index 0000000000..73aeb7dcc6 --- /dev/null +++ b/docs/manual/mod/mod_autoindex.xml @@ -0,0 +1,842 @@ +<?xml version="1.0"?> +<!DOCTYPE xml:manual [ <!ENTITY nbsp " "> ]> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> +<name>mod_autoindex</name> + +<description>Generates directory indexes, + automatically, similar to the Unix <em>ls</em> command or the + Win32 <em>dir</em> shell command</description> +<status>Base</status> +<sourcefile>mod_autoindex.c</sourcefile> +<identifier>autoindex_module</identifier> + +<summary> + <p>The index of a directory can come from one of two + sources:</p> + + <ul> + <li>A file written by the user, typically called + <code>index.html</code>. The <directive + module="mod_dir">DirectoryIndex</directive> directive sets the + name of this file. This is controlled by + <module>mod_dir</module>.</li> + + <li>Otherwise, a listing generated by the server. The other + directives control the format of this listing. The <directive + module="mod_autoindex">AddIcon</directive>, <directive + module="mod_autoindex">AddIconByEncoding</directive> and + <directive module="mod_autoindex">AddIconByType</directive> are + used to set a list of icons to display for various file types; + for each file listed, the first icon listed that matches the + file is displayed. These are controlled by + <module>mod_autoindex</module>.</li> + </ul> + <p>The two functions are separated so that you can completely + remove (or replace) automatic index generation should you want + to.</p> + + <p>Automatic index generation is enabled with using + <code>Options +Indexes</code>. See the + <directive module="core">Options</directive> directive for + more details.</p> + + <p>If the <directive module="autoindex">FancyIndexing</directive> + option is given with the <directive module="autoindex" + >IndexOptions</directive> directive, + the column headers are links that control the order of the + display. If you select a header link, the listing will be + regenerated, sorted by the values in that column. Selecting the + same header repeatedly toggles between ascending and descending + order. These column header links are suppressed with + <directive module="autoindex">IndexOptions</directive> directive's + <samp>SuppressColumnSorting</samp> option.</p> + + <p>Note that when the display is sorted by "Size", it's the + <em>actual</em> size of the files that's used, not the + displayed value - so a 1010-byte file will always be displayed + before a 1011-byte file (if in ascending order) even though + they both are shown as "1K".</p> +</summary> + +<section><title>Autoindex Request Query Arguments</title> + + <p>Apache 2.0.23 reorganized the Query Arguments for Column + Sorting, and introduced an entire group of new query options. + To effectively eliminate all client control over the output, + the <code><a href="#indexoptions:ignoreclient">IndexOptions + IgnoreClient</a></code> option was introduced.</p> + + <p>The column sorting headers themselves are self-referencing + hyperlinks that add the sort query options shown below. Any + option below may be added to any request for the directory + resource.</p> + + <ul> + <li><samp>C=N</samp> sorts the directory by file name</li> + + <li><samp>C=M</samp> sorts the directory by last-modified + date, then file name</li> + + <li><samp>C=S</samp> sorts the directory by size, then file + name</li> + + <li><samp>C=D</samp> sorts the directory by description, then + file name<br /> + </li> + + <li><samp>O=A</samp> sorts the listing in Ascending + Order</li> + + <li><samp>O=D</samp> sorts the listing in Descending + Order<br /> + </li> + + <li><samp>F=0</samp> formats the listing as a simple list + (not FancyIndexed)</li> + + <li><samp>F=1</samp> formats the listing as a FancyIndexed + list</li> + + <li><samp>F=2</samp> formats the listing as an HTMLTable + FancyIndexed list<br /> + </li> + + <li><samp>V=0</samp> disables version sorting</li> + + <li><samp>V=1</samp> enables version sorting<br /> + </li> + + <li><samp>P=<em>pattern</em></samp> lists only files matching + the given <em>pattern</em></li> + </ul> + + <p>Note that the 'P'attern query argument is tested + <em>after</em> the usual IndexIgnore directives are processed, + and all file names are still subjected to the same criteria as + any other autoindex listing. The Query Arguments parser in + mod_autoindex will stop abruptly when an unrecognized option is + encountered. The Query Arguments must be well formed, according + to the table above.</p> + + <p>The simple example below, which can be clipped and saved in + a header.html file, illustrates these query options. Note that + the unknown "X" argument, for the submit button, is listed last + to assure the arguments are all parsed before mod_autoindex + encounters the X=Go input.</p> + +<example> +<FORM METHOD="GET"><br /> + Show me a <SELECT NAME="F"><br /> + <OPTION VALUE="0"> Plain list <br /> + <OPTION VALUE="1" SELECTED> Fancy list<br /> + <OPTION VALUE="2"> Table list<br /> + </SELECT><br /> + Sorted by <SELECT NAME="C"><br /> + <OPTION VALUE="N" SELECTED> Name<br /> + <OPTION VALUE="M"> Date Modified<br /> + <OPTION VALUE="S"> Size<br /> + <OPTION VALUE="D"> Description<br /> + </SELECT><br /> + <SELECT NAME="O"><br /> + <OPTION VALUE="A" SELECTED> Ascending<br /> + <OPTION VALUE="D"> Descending<br /> + </SELECT><br /> + <SELECT NAME="V"><br /> + <OPTION VALUE="0" SELECTED> in Normal order<br /> + <OPTION VALUE="1"> in Version order<br /> + </SELECT><br /> + Matching <INPUT TYPE="text" NAME="P" VALUE="*"><br /> + <INPUT TYPE="submit" NAME="X" VALUE="Go"><br /> +</FORM> +</example> + +</section> + +<directivesynopsis> +<name>AddAlt</name> +<description>Alternate text to display for a file, instead of an +icon selected by filename</description> +<syntax>AddAlt <em>string file</em> [<em>file</em>] ...</syntax> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context> +</contextlist> +<override>Indexes</override> + +<usage> + <p><directive>AddAlt</directive> provides the alternate text to + display for a file, instead of an icon, for <code><a + href="#indexoptions:fancyindexing">FancyIndexing</a></code>. + <em>File</em> is a file extension, partial filename, wild-card + expression or full filename for files to describe. + <em>String</em> is enclosed in double quotes (<code>"</code>). + This alternate text is displayed if the client is image-incapable, + has image loading disabled, or fails to retrieve the icon.</p> + + <p>Examples:</p> +<example> + AddAlt "PDF" *.pdf<br /> + AddAlt "Compressed" *.gz *.zip *.Z +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>AddAltByEncoding</name> +<description>Alternate text to display for a file instead of an icon +selected by MIME-encoding</description> +<syntax>AddAltByEncoding <em>string MIME-encoding</em> +[<em>MIME-encoding</em>] ...</syntax> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context> +</contextlist> +<override>Indexes</override> + +<usage> + <p><directive>AddAltByEncoding</directive> provides the alternate + text to display for a file, instead of an icon, for <code><a + href="#indexoptions:fancyindexing">FancyIndexing</a></code>. + <em>MIME-encoding</em> is a valid content-encoding, such as + <code>x-compress</code>. <em>String</em> is enclosed in double + quotes (<code>"</code>). This alternate text is displayed if the + client is image-incapable, has image loading disabled, or fails to + retrieve the icon.</p> + + <p>Example:</p> +<example> + AddAltByEncoding "gzip" x-gzip +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>AddAltByType</name> +<description>Alternate text to display for a file, instead of an +icon selected by MIME content-type</description> +<syntax>AddAltByType <em>string + MIME-type</em> [<em>MIME-type</em>] ...</syntax> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context> +</contextlist> +<override>Indexes</override> + +<usage> + <p><directive>AddAltByType</directive> sets the alternate text to + display for a file, instead of an icon, for <code><a + href="#indexoptions:fancyindexing">FancyIndexing</a></code>. + <em>MIME-type</em> is a valid content-type, such as + <code>text/html</code>. <em>String</em> is enclosed in double + quotes (<code>"</code>). This alternate text is displayed if the + client is image-incapable, has image loading disabled, or fails to + retrieve the icon.</p> + + <p>Example:</p> +<example> + AddAltByType "TXT" text/plain +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>AddDescription</name> +<syntax>AddDescription + <em>string file</em> [<em>file</em>] ...</syntax> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context> +</contextlist> +<override>Indexes</override> + +<usage> + <p>This sets the description to display for a file, for + <code><a + href="#indexoptions:fancyindexing">FancyIndexing</a></code>. + <em>File</em> is a file extension, partial filename, wild-card + expression or full filename for files to describe. + <em>String</em> is enclosed in double quotes (<code>"</code>). + Example:</p> + +<example>AddDescription "The planet Mars" + /web/pics/mars.gif</example> + + <p>The typical, default description field is 23 bytes wide. 6 + more bytes are added by the + <code>IndexOptions SuppressIcon</code> option, 7 bytes are + added by the <code>IndexOptions SuppressSize</code> + option, and 19 bytes are added by the + <code>IndexOptions SuppressLastModified</code> option. + Therefore, the widest default the description column is ever + assigned is 55 bytes.</p> + + <p>See the <a + href="#indexoptions:descriptionwidth">DescriptionWidth</a> + <directive module="mod_autoindex">IndexOptions</directive> keyword + for details on overriding the size of this column, or allowing + descriptions of unlimited length.</p> + +<note><title>Caution</title> <p>Descriptive text defined with + <directive>AddDescription</directive> may contain HTML markup, such as + tags and character entities. If the width of the description + column should happen to truncate a tagged element (such as + cutting off the end of a bolded phrase), the results may + affect the rest of the directory listing.</p> +</note> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>AddIcon</name> +<description>Icon to display for a file selected by name</description> +<syntax>AddIcon <em>icon + name</em> [<em>name</em>] ...</syntax> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context> +</contextlist> +<override>Indexes</override> + +<usage> + <p>This sets the icon to display next to a file ending in + <em>name</em> for <code><a + href="#indexoptions:fancyindexing">FancyIndexing</a></code>. + <em>Icon</em> is either a (%-escaped) relative URL to the icon, + or of the format (<em>alttext</em>,<em>url</em>) where + <em>alttext</em> is the text tag given for an icon for + non-graphical browsers.</p> + + <p><em>Name</em> is either ^^DIRECTORY^^ for directories, + ^^BLANKICON^^ for blank lines (to format the list correctly), a + file extension, a wildcard expression, a partial filename or a + complete filename. Examples:</p> + +<example> + AddIcon (IMG,/icons/image.xbm) .gif .jpg .xbm<br /> + AddIcon /icons/dir.xbm ^^DIRECTORY^^<br /> + AddIcon /icons/backup.xbm *~ +</example> + + <p><directive module="mod_autoindex">AddIconByType</directive> + should be used in preference to <directive>AddIcon</directive>, + when possible.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>AddIconByEncoding</name> +<description>Icon to display next to files selected by MIME +content-encoding</description> +<syntax>AddIconByEncoding + <em>icon MIME-encoding</em> [<em>MIME-encoding</em>] ...</syntax> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context> +</contextlist> +<override>Indexes</override> + +<usage> + <p>This sets the icon to display next to files with <code><a + href="#indexoptions:fancyindexing">FancyIndexing</a></code>. + <em>Icon</em> is either a (%-escaped) relative URL to the icon, + or of the format (<em>alttext</em>,<em>url</em>) where + <em>alttext</em> is the text tag given for an icon for + non-graphical browsers.</p> + + <p><em>Mime-encoding</em> is a wildcard expression matching + required the content-encoding. Examples:</p> + +<example>AddIconByEncoding /icons/compress.xbm x-compress</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>AddIconByType</name> +<description>Icon to display next to files selected by MIME +content-type</description> +<syntax>AddIconByType + <em>icon MIME-type</em> [<em>MIME-type</em>] ...</syntax> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context> +</contextlist> +<override>Indexes</override> + +<usage> + <p>This sets the icon to display next to files of type + <em>MIME-type</em> for <code><a + href="#indexoptions:fancyindexing">FancyIndexing</a></code>. + <em>Icon</em> is either a (%-escaped) relative URL to the icon, + or of the format (<em>alttext</em>,<em>url</em>) where + <em>alttext</em> is the text tag given for an icon for + non-graphical browsers.</p> + + <p><em>Mime-type</em> is a wildcard expression matching + required the mime types. Examples:</p> + +<example>AddIconByType (IMG,/icons/image.xbm) image/*</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>DefaultIcon</name> +<description>Icon to display for files when no specific icon is +configured</description> +<syntax>DefaultIcon <em>url-path</em></syntax> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context> +</contextlist> +<override>Indexes</override> + +<usage> + <p>The <directive>DefaultIcon</directive> directive sets the icon + to display for files when no specific icon is known, for <code><a + href="#indexoptions:fancyindexing">FancyIndexing</a></code>. + <em>Url</em> is a (%-escaped) relative URL to the icon. + Examples:</p> +<example>DefaultIcon /icon/unknown.xbm</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>HeaderName</name> +<description>Name of the file that will be inserted at the top +of the index listing</description> +<syntax>HeaderName <em>filename</em></syntax> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context> +</contextlist> +<override>Indexes</override> + +<usage> + <p>The <directive>HeaderName</directive> directive sets the name + of the file that will be inserted at the top of the index + listing. <em>Filename</em> is the name of the file to include.</p> + +<note> + <p>Both HeaderName and <directive + module="mod_autoindex">ReadmeName</directive> now treat + <em>Filename</em> as a URI path relative to the one used to + access the directory being indexed. <em>Filename</em> must + resolve to a document with a major content type of + "<code>text/*</code>" (<em>e.g.</em>, <code>text/html</code>, + <code>text/plain</code>, <em>etc.</em>). This means that + <em>filename</em> may refer to a CGI script if the script's + actual file type (as opposed to its output) is marked as + <code>text/html</code> such as with a directive like:</p> +<example> + AddType text/html .cgi +</example> + <p><a href="../content-negotiation.html">Content negotiation</a> + will be performed if the <code>MultiViews</code> <directive + module="core">Option</directive> is enabled. If + <em>filename</em> resolves to a static <code>text/html</code> + document (not a CGI script) and the <code>Includes</code> + <directive module="core">option</directive> is enabled, the file + will be processed for server-side includes (see the + <module>mod_include</module> documentation).</p> +</note> + + <p>If the file specified by <directive>HeaderName</directive> contains + the beginnings of an HTML document (<HTML>, <HEAD>, + etc) then you will probably want to set <a + href="#indexoptions:suppresshtmlpreamble"><code>IndexOptions + +SuppressHTMLPreamble</code></a>, so that these tags are not + repeated.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>IndexIgnore</name> +<description>Adds to the list of files to hide when listing +a directory</description> +<syntax>IndexIgnore <em>file</em> [<em>file</em>] ...</syntax> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context> +</contextlist> +<override>Indexes</override> + +<usage> + <p>The <directive>IndexIgnore</directive> directive adds to the + list of files to hide when listing a directory. <em>File</em> is a + file extension, partial filename, wildcard expression or full + filename for files to ignore. Multiple IndexIgnore directives add + to the list, rather than the replacing the list of ignored + files. By default, the list contains + `<code>.</code>'. Example:</p> + +<example>IndexIgnore README .htaccess *~</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>IndexOptions</name> +<description>Various configuration settings for directory +indexing</description> +<syntax>IndexOptions [+|-]<em>option</em> [[+|-]<em>option</em>] ...</syntax> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context> +</contextlist> +<override>Indexes</override> + +<usage> + <p>The <directive>IndexOptions</directive> directive specifies the + behavior of the directory indexing. <em>Option</em> can be one + of</p> + + <dl> + <dt><a id="indexoptions:descriptionwidth" + name="indexoptions:descriptionwidth">DescriptionWidth=[<em>n</em> + | *] (<em>Apache 1.3.10 or 2.0.23 and later</em>)</a></dt> + + <dd>The <code>DescriptionWidth</code> keyword allows you to + specify the width of the description column in + characters.</dd> + + <dd><code>-DescriptionWidth</code> (or unset) allows + mod_autoindex to calculate the best width.</dd> + + <dd><code>DescriptionWidth=n</code> fixes the column width to + n bytes wide.</dd> + + <dd><code>DescriptionWidth=*</code> grows the column to the + width necessary to accommodate the longest description + string.</dd> + + <dd><b>See the section on <directive + module="mod_autoindex">AddDescription</directive> for dangers + inherent in truncating descriptions.</b></dd> + + <dt><a id="indexoptions:fancyindexing" + name="indexoptions:fancyindexing">FancyIndexing</a></dt> + + <dd> + This turns on fancy indexing of directories.</dd> + + <dt><a id="indexoptions:foldersfirst" + name="indexoptions:foldersfirst">FoldersFirst (<i>Apache + 1.3.10 or 2.0.23 and later</i>)</a></dt> + + <dd>If this option is enabled, subdirectory listings will + <i>always</i> appear first, followed by normal files in the + directory. The listing is basically broken into two + components, the files and the subdirectories, and each is + sorted separately and then displayed subdirectories-first. + For instance, if the sort order is descending by name, and + <code>FoldersFirst</code> is enabled, subdirectory + <code>Zed</code> will be listed before subdirectory + <code>Beta</code>, which will be listed before normal files + <code>Gamma</code> and <code>Alpha</code>. <b>This option + only has an effect if <a + href="#indexoptions:fancyindexing"><code>FancyIndexing</code></a> + is also enabled.</b></dd> + + <dt><a id="indexoptions:htmltable" + name="indexoptions:htmltable">HTMLTable</a> <i>(Experimental, + Apache 2.0.23 and later)</i></dt> + + <dd> + This experimental option with FancyIndexing constructs a + simple table for the fancy directory listing. Note this will + confuse older browsers. It is particularly necessary if file + names or description text will alternate between + left-to-right and right-to-left reading order, as can happen + on WinNT or other utf-8 enabled platforms.</dd> + + <dt><a id="indexoptions:iconsarelinks" + name="indexoptions:iconsarelinks">IconsAreLinks</a></dt> + + <dd> + This makes the icons part of the anchor for the filename, for + fancy indexing.</dd> + + <dt><a id="indexoptions:iconheight" + name="indexoptions:iconheight">IconHeight[=pixels] + (<em>Apache 1.3 and later</em>)</a></dt> + + <dd> + Presence of this option, when used with IconWidth, will cause + the server to include <code>HEIGHT</code> and + <code>WIDTH</code> attributes in the <code>IMG</code> tag for + the file icon. This allows browser to precalculate the page + layout without having to wait until all the images have been + loaded. If no value is given for the option, it defaults to + the standard height of the icons supplied with the Apache + software.</dd> + + <dt><a id="indexoptions:iconwidth" + name="indexoptions:iconwidth">IconWidth[=pixels] (<em>Apache + 1.3 and later</em>)</a></dt> + + <dd> + Presence of this option, when used with IconHeight, will + cause the server to include <code>HEIGHT</code> and + <code>WIDTH</code> attributes in the <code>IMG</code> tag for + the file icon. This allows browser to precalculate the page + layout without having to wait until all the images have been + loaded. If no value is given for the option, it defaults to + the standard width of the icons supplied with the Apache + software.</dd> + + <dt><a id="indexoptions:ignoreclient" + name="indexoptions:ignoreclient">IgnoreClient</a></dt> + + <dd> + This option causes mod_autoindex to ignore all query + variables from the client, including sort order (implies + <code><a + href="#indexoptions:suppresscolumnsorting">SuppressColumnSorting</a></code>.)</dd> + + <dt><a id="indexoptions:namewidth" + name="indexoptions:namewidth">NameWidth=[<em>n</em> | *] + (<em>Apache 1.3.2 and later</em>)</a></dt> + + <dd>The NameWidth keyword allows you to specify the width of + the filename column in bytes.</dd> + + <dd><code>-NameWidth</code> (or unset) allows mod_autoindex + to calculate the best width.</dd> + + <dd><code>NameWidth=n</code> fixes the column width to n + bytes wide.</dd> + + <dd><code>NameWidth=*</code> grows the column to the + necessary width.</dd> + + <dt><a id="indexoptions:scanhtmltitles" + name="indexoptions:scanhtmltitles">ScanHTMLTitles</a></dt> + + <dd> + This enables the extraction of the title from HTML documents + for fancy indexing. If the file does not have a description + given by <a href="#adddescription">AddDescription</a> then + httpd will read the document for the value of the TITLE tag. + This is CPU and disk intensive.</dd> + + <dt><a id="indexoptions:suppresscolumnsorting" + name="indexoptions:suppresscolumnsorting">SuppressColumnSorting</a> + (<em>Apache 1.3 and later</em>)</dt> + + <dd> + If specified, Apache will not make the column headings in a + FancyIndexed directory listing into links for sorting. The + default behavior is for them to be links; selecting the + column heading will sort the directory listing by the values + in that column. <strong>Prior to Apache 2.0.23, this also + disabled parsing the Query Arguments for the sort + string.</strong> That behavior is now controlled by <a + href="#indexoptions:ignoreclient">IndexOptions + IgnoreClient</a> in Apache 2.0.23.</dd> + + <dt><a id="indexoptions:suppressdescription" + name="indexoptions:suppressdescription">SuppressDescription</a></dt> + + <dd> + This will suppress the file description in fancy indexing + listings. By default, no file descriptions are defined, and + so the use of this option will regain 23 characters of screen + space to use for something else. See <a + href="#adddescription"><code>AddDescription</code></a> for + information about setting the file description. See also the + <a + href="#indexoptions:descriptionwidth"><code>DescriptionWidth</code></a> + index option to limit the size of the description + column.</dd> + + <dt><a id="indexoptions:suppresshtmlpreamble" + name="indexoptions:suppresshtmlpreamble">SuppressHTMLPreamble</a> + (<em>Apache 1.3 and later</em>)</dt> + + <dd> + If the directory actually contains a file specified by the + <directive module="mod_autoindex">HeaderName</directive> + directive, the module usually includes the contents of the file + after a standard HTML preamble (<HTML>, <HEAD>, + <em>et cetera</em>). The SuppressHTMLPreamble option disables + this behaviour, causing the module to start the display with the + header file contents. The header file must contain appropriate + HTML instructions in this case. If there is no header file, the + preamble is generated as usual.</dd> + + <dt><a id="indexoptions:suppressicon" + name="indexoptions:suppressicon">SuppressIcon</a> (<em>Apache + 2.0.23 and later</em>)</dt> + + <dd> + This will suppress the icon in fancy indexing listings. + Combining both <em>SuppressIcon</em> and + <em>SuppressRules</em> yields proper HTML 3.2 output, which + by the final specification prohibits IMG and HR tags from the + PRE block (used to format FancyIndexed listings.)</dd> + + <dt><a id="indexoptions:suppresslastmodified" + name="indexoptions:suppresslastmodified">SuppressLastModified</a></dt> + + <dd> + This will suppress the display of the last modification date, + in fancy indexing listings.</dd> + + <dt><a id="indexoptions:suppressrules" + name="indexoptions:suppressrules">SuppressRules</a> + (<em>Apache 2.0.23 and later</em>)</dt> + + <dd> + This will suppress the horizontal rule lines (HR tags) in + directory listings. Combining both <em>SuppressIcon</em> and + <em>SuppressRules</em> yeilds proper HTML 3.2 output, which + by the final specification prohibits IMG and HR tags from the + PRE block (used to format FancyIndexed listings.)</dd> + + <dt><a id="indexoptions:suppresssize" + name="indexoptions:suppresssize">SuppressSize</a></dt> + + <dd> + This will suppress the file size in fancy indexing + listings.</dd> + + <dt><a id="indexoptions:trackmodified" + name="indexoptions:trackmodified">TrackModified (<em>Apache + 1.3.15 or 2.0.23 and later</em>)</a></dt> + + <dd> + This returns the Last-Modified and ETag values for the listed + directory in the HTTP header. It is only valid if the + operating system and file system return appropriate stat() + results. Some Unix systems do so, as do OS2's JFS and Win32's + NTFS volumes. OS2 and Win32 FAT volumes, for example, do not. + Once this feature is enabled, the client or proxy can track + changes to the list of files when they perform a HEAD + request. Note some operating systems correctly track new and + removed files, but do not track changes for sizes or dates of + the files within the directory. <strong>Changes to the size + or date stamp of an existing file will not update the + Last-Modified header on all Unix platforms.</strong> If this + is a concern, leave this option disabled.</dd> + + <dt><a id="indexoptions:versionsort" + name="indexoptions:versionsort">VersionSort (<em>Apache 2.0a3 + and later</em>)</a></dt> + + <dd> + The VersionSort keyword causes files containing version + numbers to sort in a natural way. Strings are sorted as + usual, except that substrings of digits in the name and + description are compared according to their numeric value. + For example: + +<example> +foo-1.7<br /> +foo-1.7.2<br /> +foo-1.7.12<br /> +foo-1.8.2<br /> +foo-1.8.2a<br /> +foo-1.12<br /> +</example> + If the number starts with a zero, then it is considered to + be a fraction: + +<example> +foo-1.001<br /> +foo-1.002<br /> +foo-1.030<br /> +foo-1.04 +</example> + </dd> + + <dd> + <h3>Incremental IndexOptions</h3> + </dd> + + <dd> + Apache 1.3.3 introduced some significant changes in the + handling of <directive>IndexOptions</directive> directives. In + particular,<br /> + <br /> + + + <ul> + <li>Multiple <directive>IndexOptions</directive> directives for a + single directory are now merged together. The result of + the example above will now be the equivalent of + <code>IndexOptions FancyIndexing ScanHTMLTitles</code>.</li> + + <li>The addition of the incremental syntax + (<em>i.e.</em>, prefixing keywords with '+' or '-').</li> + </ul> + <br /> + Whenever a '+' or '-' prefixed keyword is encountered, it + is applied to the current <directive>IndexOptions</directive> + settings (which may have been inherited from an upper-level + directory). However, whenever an unprefixed keyword is + processed, it clears all inherited options and any + incremental settings encountered so far. Consider the + following example: + +<example>IndexOptions +ScanHTMLTitles -IconsAreLinks + FancyIndexing<br /> + IndexOptions +SuppressSize<br /> +</example> + The net effect is equivalent to + <code>IndexOptions FancyIndexing +SuppressSize</code>, + because the unprefixed <code>FancyIndexing</code> discarded + the incremental keywords before it, but allowed them to + start accumulating again afterward.<br /> + <br /> + To unconditionally set the <directive>IndexOptions</directive> for a + particular directory, clearing the inherited settings, + specify keywords without any '+' or '-' prefixes. + </dd> + </dl> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>IndexOrderDefault</name> +<description>Sets the default ordering of the directory index</description> +<syntax>IndexOrderDefault +Ascending|Descending Name|Date|Size|Description</syntax> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context> +</contextlist> +<override>Indexes</override> + +<usage> + <p>The <directive>IndexOrderDefault</directive> directive is used + in combination with the <a + href="#indexoptions:fancyindexing"><code>FancyIndexing</code></a> + index option. By default, fancyindexed directory listings are + displayed in ascending order by filename; the + <directive>IndexOrderDefault</directive> allows you to change this initial + display order.</p> + + <p><directive>IndexOrderDefault</directive> takes two + arguments. The first must be either <code>Ascending</code> or + <code>Descending</code>, indicating the direction of the sort. + The second argument must be one of the keywords <code>Name</code>, + <code>Date</code>, <code>Size</code>, or <code>Description</code>, + and identifies the primary key. The secondary key is + <em>always</em> the ascending filename.</p> + + <p>You can force a directory listing to only be displayed in a + particular order by combining this directive with the <a + href="#indexoptions:suppresscolumnsorting"><code>SuppressColumnSorting</code></a> + index option; this will prevent the client from requesting the + directory listing in a different order.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>ReadmeName</name> +<syntax>ReadmeName <em>filename</em></syntax> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context> +</contextlist> +<override>Indexes</override> + +<usage> + <p>The <directive>ReadmeName</directive> directive sets the name + of the file that will be appended to the end of the index + listing. <em>Filename</em> is the name of the file to include, and + is taken to be relative to the location being indexed.</p> + + <p>See also <directive + module="mod_autoindex">HeaderName</directive>, where this behavior + is described in greater detail.</p> +</usage> +</directivesynopsis> + +</modulesynopsis>
\ No newline at end of file diff --git a/docs/manual/mod/mod_cern_meta.xml b/docs/manual/mod/mod_cern_meta.xml new file mode 100644 index 0000000000..de97c827f4 --- /dev/null +++ b/docs/manual/mod/mod_cern_meta.xml @@ -0,0 +1,76 @@ +<?xml version="1.0"?> +<!DOCTYPE xml:manual [ <!ENTITY nbsp " "> ]> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>mod_cern_meta</name> +<description>CERN httpd metafile semantics</description> +<status>Extension</status> +<sourcefile>mod_cern_meta.c</sourcefile> +<identifier>cern_meta_module</identifier> + +<summary> + <!-- XXX: Should mention other possibilities in Apache: mod_header --> + <p>Emulate the CERN HTTPD Meta file semantics. Meta files are HTTP + headers that can be output in addition to the normal range of + headers for each file accessed. They appear rather like the + Apache .asis files, and are able to provide a crude way of + influencing the Expires: header, as well as providing other + curiosities. There are many ways to manage meta information, + this one was chosen because there is already a large number of + CERN users who can exploit this module.</p> + + <p>More information on the <a + href="http://www.w3.org/pub/WWW/Daemon/User/Config/General.html#MetaDir"> + CERN metafile semantics</a> is available.</p> +</summary> + +<directivesynopsis> +<name>MetaFiles</name> +<description>Activates CERN meta-file processing</description> +<syntax>MetaFiles on|off</syntax> +<default>MetaFiles off</default> +<contextlist><context>directory</context></contextlist> + +<usage> + <p>Turns on/off Meta file processing on a per-directory basis.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>MetaDir</name> +<description>Name of the directory to find CERN-style meta information +files</description> +<syntax>MetaDir <em>directory</em></syntax> +<default>MetaDir .web</default> +<contextlist><context>directory</context></contextlist> + +<usage> + <p>Specifies the name of the directory in which Apache can find + meta information files. The directory is usually a 'hidden' + subdirectory of the directory that contains the file being + accessed. Set to "<code>.</code>" to look in the same directory + as the file.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>MetaSuffix</name> +<description>File name suffix for the file containg CERN-style +meta information</description> +<syntax>MetaSuffix <em>suffix</em></syntax> +<default>MetaSuffix .meta</default> +<contextlist><context>directory</context></contextlist> + +<usage> + <p>Specifies the file name suffix for the file containing the + meta information. For example, the default values for the two + directives will cause a request to + <code>DOCUMENT_ROOT/somedir/index.html</code> to look in + <code>DOCUMENT_ROOT/somedir/.web/index.html.meta</code> and + will use its contents to generate additional MIME header + information.</p> +</usage> +</directivesynopsis> + +</modulesynopsis> diff --git a/docs/manual/mod/mod_cgi.xml b/docs/manual/mod/mod_cgi.xml new file mode 100644 index 0000000000..4c3ea9c1ef --- /dev/null +++ b/docs/manual/mod/mod_cgi.xml @@ -0,0 +1,202 @@ +<?xml version="1.0"?> +<!DOCTYPE xml:manual [ <!ENTITY nbsp " "> ]> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>mod_cgi</name> +<description>Execution of CGI scripts</description> +<status>Base</status> +<sourcefile>mod_cgi.c</sourcefile> +<identifier>cgi_module</identifier> + +<summary> + <!-- XXX: Should have references to CGI definition/RFC --> + <!-- XXX: Should mention Options ExecCGI --> + <!-- XXX: Should mention AcceptPathInfo --> + + <p>Any file that has the mime type + <code>application/x-httpd-cgi</code> or handler + <code>cgi-script</code> (Apache 1.1 or later) will be treated + as a CGI script, and run by the server, with its output being + returned to the client. Files acquire this type either by + having a name containing an extension defined by the + <directive module="mod_mime">AddType</directive> directive, or by being + in a <directive module="mod_alias">ScriptAlias</directive> + directory.</p> + + <p>When the server invokes a CGI script, it will add a variable + called <code>DOCUMENT_ROOT</code> to the environment. This + variable will contain the value of the + <directive module="core.html">DocumentRoot</directive> configuration + variable.</p> + + <p>For an introduction to using CGI scripts with Apache, see + our tutorial on <a href="../howto/cgi.html">Dynamic Content + With CGI</a>.</p> + + <p>When using a multi-threaded MPM under unix, the module + <module>mod_cgid</module> should be used in place of + this module. At the user level, the two modules are essentially + identical.</p> +</summary> + +<seealso><directive module="core">Options</directive></seealso> +<seealso><directive module="mod_alias">ScriptAlias</directive></seealso> +<seealso><directive module="mod_mime">AddHandler</directive></seealso> + +<section><title>CGI Environment variables</title> + <p>The server will set the CGI environment variables as described + in the <a href="http://hoohoo.ncsa.uiuc.edu/cgi/">CGI + specification</a>, with the following provisions:</p> + + <dl> + <dt>PATH_INFO</dt> + + <dd>This will not be available if the <directive module="core" + >AcceptPathInfo</directive> directive is explicitly set to + <code>off</code>. The default behavior, if AcceptPathInfo is + not given, is that mod_cgi will accept path info (trailing + /more/path/info following the script filename in the URI), while + the core server will return a 404 NOT FOUND error for requests + with additional path info. Omitting the AcceptPathInfo + directive has the same effect as setting it <code>on</code> for + mod_cgi requests.</dd> + + <dt>REMOTE_HOST</dt> + + <dd>This will only be set if <directive module="core" + >HostnameLookups</directive> is set to <code>on</code> (it + is off by default), and if a reverse DNS lookup of the accessing + host's address indeed finds a host name.</dd> + + <dt>REMOTE_IDENT</dt> + + <dd>This will only be set if <directive module="core" + >IdentityCheck</directive> is set to + <code>on</code> and the accessing host supports the ident + protocol. Note that the contents of this variable cannot be + relied upon because it can easily be faked, and if there is a + proxy between the client and the server, it is usually + totally useless.</dd> + + <dt>REMOTE_USER</dt> + + <dd>This will only be set if the CGI script is subject to + authentication.</dd> + </dl> +</section> + +<section id="cgi_debug"><title>CGI Debugging</title> + <p>Debugging CGI scripts has traditionally been difficult, mainly + because it has not been possible to study the output (standard + output and error) for scripts which are failing to run + properly. These directives, included in Apache 1.2 and later, + provide more detailed logging of errors when they occur. </p> + +<section><title>CGI Logfile Format</title> + <p>When configured, the CGI error log logs any CGI which does not + execute properly. Each CGI script which fails to operate causes + several lines of information to be logged. The first two lines + are always of the format:</p> +<example> + %% [<em>time</em>] <em>request-line</em><br /> + %% <em>HTTP-status</em> <em>CGI-script-filename</em> +</example> + <p>If the error is that CGI script cannot be run, the log file + will contain an extra two lines:</p> +<example> + %%error<br /> + <em>error-message</em> +</example> + <p>Alternatively, if the error is the result of the script + returning incorrect header information (often due to a bug in + the script), the following information is logged: </p> +<example> + %request<br /> + <em>All HTTP request headers received</em><br /> + <em>POST or PUT entity (if any)</em><br /> + %response<br /> + <em>All headers output by the CGI script</em><br /> + %stdout<br /> + <em>CGI standard output</em><br /> + %stderr<br /> + <em>CGI standard error</em><br /> +</example> + <p>(The %stdout and %stderr parts may be missing if the script did + not output anything on standard output or standard error). </p> +</section> +</section> + +<directivesynopsis> +<name>ScriptLog</name> +<description>Location of the CGI script error logfile</description> +<syntax>ScriptLog <em>file-path</em></syntax> +<contextlist><context>server config</context></contextlist> +<modulelist><module>mod_cgi</module><module>mod_cgid</module> +</modulelist> + +<usage> + <p>The <directive>ScriptLog</directive> directive sets the CGI + script error logfile. If no ScriptLog is given, no error log is + created. If given, any CGI errors are logged into the filename + given as argument. If this is a relative file or path it is taken + relative to the server root.</p> + + <p>This log will be opened as the user the child processes run + as, ie. the user specified in the main <directive module="mpm_common" + >User</directive> directive. This means that + either the directory the script log is in needs to be writable + by that user or the file needs to be manually created and set + to be writable by that user. If you place the script log in + your main logs directory, do <strong>NOT</strong> change the + directory permissions to make it writable by the user the child + processes run as.</p> + + <p>Note that script logging is meant to be a debugging feature + when writing CGI scripts, and is not meant to be activated + continuously on running servers. It is not optimized for speed + or efficiency, and may have security problems if used in a + manner other than that for which it was designed.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>ScriptLogLength</name> +<description>Size limit of the CGI script logfile</description> +<syntax>ScriptLogLength <em>bytes</em></syntax> +<default>ScriptLogLength 10385760</default> +<contextlist><context>server config</context></contextlist> +<modulelist><module>mod_cgi</module><module>mod_cgid</module> +</modulelist> + +<usage> + <p><directive>ScriptLogLength</directive> can be used to limit the + size of the CGI script logfile. Since the logfile logs a lot of + information per CGI error (all request headers, all script output) + it can grow to be a big file. To prevent problems due to unbounded + growth, this directive can be used to set an maximum file-size for + the CGI logfile. If the file exceeds this size, no more + information will be written to it.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>ScriptLogBuffer</name> +<description>Maximum amount of PUT or POST requests that will be recorded +in the scriptlog</description> +<syntax>ScriptLogBuffer <em>bytes</em></syntax> +<default>ScriptLogBuffer 1024</default> +<contextlist><context>server config</context></contextlist> +<modulelist><module>mod_cgi</module><module>mod_cgid</module> +</modulelist> + +<usage> + <p>The size of any PUT or POST entity body that is logged to + the file is limited, to prevent the log file growing too big + too quickly if large bodies are being received. By default, up + to 1024 bytes are logged, but this can be changed with this + directive.</p> +</usage> +</directivesynopsis> + +</modulesynopsis>
\ No newline at end of file diff --git a/docs/manual/mod/mod_cgid.xml b/docs/manual/mod/mod_cgid.xml new file mode 100644 index 0000000000..bebea4f7c3 --- /dev/null +++ b/docs/manual/mod/mod_cgid.xml @@ -0,0 +1,68 @@ +<?xml version="1.0"?> +<!DOCTYPE xml:manual [ <!ENTITY nbsp " "> ]> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>mod_cgid</name> +<description>Execution of CGI scripts using an + external CGI daemon</description> +<status>Base</status> +<sourcefile>mod_cgid.c</sourcefile> +<identifier>cgid_module</identifier> +<compatibility>Unix threaded MPMs only</compatibility> + +<summary> + <p>Except for the optimizations and the additional <directive + module="mod_cgid">ScriptSock</directive> directive noted below, + mod_cgid behaves similarly to mod_cgi. <strong>See the + <module>mod_cgi</module> Summary for additional details about + Apache and CGI.</strong></p> + + <p>On certain unix operating systems, forking a process from a + multi-threaded server is a very expensive operation because the + new process will replicate all the threads of the parent + process. In order to avoid incurring this expense on each CGI + invocation, mod_cgid creates an external daemon that is + responsible for forking child processes to run CGI scripts. The + main server communicates with this daemon using a unix domain + socket.</p> + + <p>This module is used by default whenever a multi-threaded MPM + is selected during the compilation process. At the user level, + this module is identical in configuration and operation to + <module>mod_cgi</module>. The only exception is the + additional directive <code>ScriptSock</code> which gives the + name of the socket to use for communication with the cgi + daemon.</p> +</summary> + +<directivesynopsis location="mod_cgi"> +<name>ScriptLog</name> +</directivesynopsis> + +<directivesynopsis location="mod_cgi"> +<name>ScriptLogLength</name> +</directivesynopsis> + +<directivesynopsis location="mod_cgi"> +<name>ScriptLogBuffer</name> +</directivesynopsis> + +<directivesynopsis> +<name>ScriptSock</name> +<syntax>ScriptSock <em>file-path</em></syntax> +<default>ScriptSock logs/cgisock</default> +<contextlist><context>server config</context></contextlist> + +<usage> + <p>This directive sets the name of the socket to use for + communication with the CGI daemon. The socket will be opened + using the permissions of the user who starts Apache (usually + root). To maintain the security of communications with CGI + scripts, it is important that no other user has permission to + write in the directory where the socket is located.</p> +</usage> +</directivesynopsis> + +</modulesynopsis> + diff --git a/docs/manual/mod/mod_charset_lite.xml b/docs/manual/mod/mod_charset_lite.xml new file mode 100644 index 0000000000..dff19f649b --- /dev/null +++ b/docs/manual/mod/mod_charset_lite.xml @@ -0,0 +1,170 @@ +<?xml version="1.0"?> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>mod_charset_lite</name> +<description>specify character set translation or recoding</description> +<status>Experimental</status> +<sourcefile>mod_charset_lite.c</sourcefile> +<identifier>charset_lite_module</identifier> + +<summary> + <p>This is an <strong>experimental</strong> module and should + be used with care. Experiment with your + <code>mod_charset_lite</code> configuration to ensure that it + performs the desired function.</p> + + <p><module>mod_charset_lite</module> allows the administrator to + specify the source character set of objects as well as the + character set they should be translated into before sending to the + client. <module>mod_charset_lite</module> does not translate the + data itself but instead tells Apache what translation to + perform. <module>mod_charset_lite</module> is applicable to EBCDIC + and ASCII host environments. In an EBCDIC environment, Apache + normally translates text content from the code page of the Apache + process locale to ISO-8859-1. <module>mod_charset_lite</module> + can be used to specify that a different translation is to be + performed. In an ASCII environment, Apache normally performs no + translation, so <module>mod_charset_lite</module> is needed in + order for any translation to take place.</p> + + <p>This module provides a small subset of configuration + mechanisms implemented by Russian Apache and its associated + <code>mod_charset</code>.</p> +</summary> + +<section><title>Common Problems</title> + +<section><title>Invalid character set names</title> + + <p>The character set name parameters of <directive + module="mod_charset_lite">CharsetSourceEnc</directive> and + <directive module="mod_charset_lite">CharsetDefault</directive> + must be acceptable to the translation mechanism used by APR on the + system where <module>mod_charset_lite</module> is deployed. These + character set names are not standardized and are usually not the + same as the corresponding values used in http headers. Currently, + APR can only use iconv(3), so you can easily test your character + set names using the iconv(1) program, as follows:</p> +<example> + iconv -f charsetsourceenc-value -t charsetdefault-value +</example> +</section> + +<section><title>Mismatch between character set of content and translation + rules</title> + + <p>If the translation rules don't make sense for the content, + translation can fail in various ways, including:</p> + + <ul> + <li>The translation mechanism may return a bad return code, + and the connection will be aborted.</li> + + <li>The translation mechanism may silently place special + characters (e.g., question marks) in the output buffer when + it cannot translate the input buffer.</li> + </ul> +</section> +</section> + +<directivesynopsis> +<name>CharsetSourceEnc</name> +<syntax>CharsetSourceEnc <em>charset</em></syntax> +<contextlist><context>server config</context> +<context>virtual host</context><context>directory</context> +<context>.htaccess</context> +</contextlist> +<override>FileInfo</override> + +<usage> + <p>The <directive>CharsetSourceEnc</directive> directive specifies the + source charset of files in the associated container.</p> + + <p>The value of the <em>charset</em> argument must be accepted + as a valid character set name by the character set support in + APR. Generally, this means that it must be supported by + iconv.</p> + Example: +<example> + <Directory "/export/home/trawick/apacheinst/htdocs/convert"><br /> + CharsetSourceEnc UTF-16BE<br /> + CharsetDefault ISO8859-1<br /> + </Directory> +</example> + <p>The character set names in this example work with the iconv + translation support in Solaris 8.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>CharsetDefault</name> +<syntax>CharsetDefault <em>charset</em></syntax> +<contextlist><context>server config</context> +<context>virtual host</context><context>directory</context> +<context>.htaccess</context> +</contextlist> +<override>FileInfo</override> + +<usage> + <p>The <directive>CharsetDefault</directive> directive specifies the + charset that content in the associated container should be + translated to.</p> + + <p>The value of the <em>charset</em> argument must be accepted + as a valid character set name by the character set support in + APR. Generally, this means that it must be supported by + iconv.</p> + Example: +<example> + <Directory "/export/home/trawick/apacheinst/htdocs/convert"><br /> + CharsetSourceEnc UTF-16BE<br /> + CharsetDefault ISO8859-1<br /> + </Directory> +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>CharsetOptions</name> +<syntax>CharsetOptions <em>option</em> [<em>option</em>] ...</syntax> +<default>CharsetOptions <em>DebugLevel=0</em> +<em>NoImplicitAdd</em></default> +<contextlist><context>server config</context> +<context>virtual host</context><context>directory</context> +<context>.htaccess</context> +</contextlist> +<override>FileInfo</override> + +<usage> + <p>The <directive>CharsetOptions</directive> directive configures certain + behaviors of <module>mod_charset_lite</module>. <em>Option</em> can + be one of</p> + + <dl> + <dt>DebugLevel=<em>n</em></dt> + + <dd>The <code>DebugLevel</code> keyword allows you to specify + the level of debug messages generated by + <module>mod_charset_lite</module>. By default, no messages are + generated. This is equivalent to <code>DebugLevel=0</code>. + With higher numbers, more debug messages are generated, and + server performance will be degraded. The actual meanings of + the numeric values are described with the definitions of the + DBGLVL_ constants near the beginning of + <code>mod_charset_lite.c</code>.</dd> + + <dt>ImplicitAdd | NoImplicitAdd</dt> + + <dd>The <code>ImplicitAdd</code> keyword specifies that + <module>mod_charset_lite</module> should implicitly insert its + filter when the configuration specifies that the character + set of content should be translated. If the filter chain is + explicitly configured using the AddOutputFilter directive, + <code>NoImplicitAdd</code> should be specified so that + <module>mod_charset_lite</module> doesn't add its filter.</dd> + </dl> +</usage> +</directivesynopsis> + +</modulesynopsis>
\ No newline at end of file diff --git a/docs/manual/mod/mod_dav.xml b/docs/manual/mod/mod_dav.xml new file mode 100644 index 0000000000..c7b8f3f5b5 --- /dev/null +++ b/docs/manual/mod/mod_dav.xml @@ -0,0 +1,136 @@ +<?xml version="1.0"?> +<!DOCTYPE xml:manual [ <!ENTITY nbsp " "> ]> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>mod_dav</name> +<description>Distributed Authoring and Versioning +(<a href="http://www.webdav.org/">WebDAV</a>) functionality.</description> +<status>Extension</status> +<sourcefile>mod_dav.c</sourcefile> +<identifier>dav_module</identifier> + +<summary> + <p>This module provides class 1 and class 2 <a + href="http://www.webdav.org">WebDAV</a> ('Web-based Distributed + Authoring and Versioning') functionality for Apache. This + extension to the HTTP protocol allows creating, moving, + copying, and deleting resources and collections on a remote web + server.</p> + + <p>To enable mod_dav, add the following to a container in your + <code>httpd.conf</code> file:</p> + +<example>Dav On</example> + + <p>Also, specify a valid filename for the DAV lock database by + adding the following to the global section in your + <code>httpd.conf</code> file:</p> + +<example>DavLockDB /tmp/DavLock + <em>(Any web-server writable filename, without an + extension)</em> +</example> +</summary> + +<directivesynopsis> +<name>Dav</name> +<description>Enable WebDAV HTTP methods</description> +<syntax>Dav on|off</syntax> +<default>Dav off</default> +<contextlist><context>directory</context></contextlist> + +<usage> + <p>Use the <directive>Dav</directive> directive to enable the + WebDAV HTTP methods for the given container. You may wish to add a + <directive module="core" type="section">Limit</directive> clause + inside the <directive module="core" + type="section">location</directive> directive to limit access to + DAV-enabled locations.</p> + +<example><title>Example</title> + DavLockDB /tmp/DavLock<br /> + <br /> + <Location /foo><br /> + Dav On<br /> + <br /> + AuthType Basic<br /> + AuthName DAV<br /> + AuthUserFile user.passwd<br /> + <br /> + <LimitExcept GET HEAD OPTIONS><br /> + require user admin<br /> + </LimitExcept><br /> + </Location><br /> +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<description>Location of the DAV lock database</description> +<name>DavLockDB</name> +<syntax>DavLockDB <em>file-path</em></syntax> +<contextlist><context>server config</context><context>virtual host</context> +</contextlist> + +<usage> + <p>Use the <directive>DavLockDB</directive> directive to specify + the full path to the lock database, excluding an extension. The + default (file system) implementation of mod_dav uses a SDBM + database to track user locks. The utility + <code>modules/dav/util/lockview</code> can be used from the server + to display all locks in a lock database.</p> + +<example><title>Example</title> +DavLockDB /tmp/DavLock +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>DavMinTimeout</name> +<description>Minimum amount of time the server holds a lock on +a DAV resource</description> +<syntax>DavMinTimeout <em>seconds</em></syntax> +<default>DavMinTimeout 0</default> +<contextlist><context>directory</context></contextlist> + +<usage> + <p>When a client requests a DAV resource lock, it can also + specify a time when the lock will be automatically removed by + the server. This value is only a request, and the server can + ignore it or inform the client of an arbitrary value.</p> + + <p>Use the <directive>DavMinTimeout</directive> directive to specify, in + seconds, the minimum lock timeout to return to a client. + Microsoft Web Folders defaults to a timeout of 120 seconds; the + <directive>DavMinTimeout</directive> can override this to a higher value + (like 600 seconds) to reduce the chance of the client losing + the lock due to network latency.</p> + +<example><title>Example</title> + <Location /MSWord><br /> + DavMinTimeout 600<br /> + </Location><br /> +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>DavDepthInfinity</name> +<description>Allow PROPFIND, Depth: Infinity requests</description> +<syntax>DavDepthInfinity on|off</syntax> +<default>DavDepthInfinity off</default> +<contextlist><context>directory</context></contextlist> + +<usage> + <p>Use the <directive>DavDepthInfinity</directive> directive to + allow the processing of PROPFIND requests containing the header + 'Depth: Infinity'. Because this type of request could constitute a + denial-of-service attack, by default it is not allowed.</p> +</usage> +</directivesynopsis> + +</modulesynopsis> + + diff --git a/docs/manual/mod/mod_deflate.html b/docs/manual/mod/mod_deflate.html new file mode 100755 index 0000000000..48c190fc2d --- /dev/null +++ b/docs/manual/mod/mod_deflate.html @@ -0,0 +1,129 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <title>Apache module mod_deflate</title> + </head> + <!-- Background white, links blue (unvisited), navy (visited), red (active) --> + + <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" + vlink="#000080" alink="#FF0000"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Module mod_deflate</h1> + + <p>This module provides the ability to set environment + variables based upon attributes of the request.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Experimental<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> + mod_deflate.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + deflate_module<br /> + <a href="module-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Available in + Apache 2.0 and later.</p> + + <h2>Summary</h2> + + <p>The experimental <samp>mod_deflate</samp> module allows + output from your server to be compressed before being sent + to the client over the network.</p> + + <h2>Directives</h2> + + <ul> + <li><a href="#DeflateFilterNote">DeflateFilterNote</a></li> + + <li><a href="#DeflateWindowSize">DeflateWindowSize</a></li> + + <li><a href="#DeflateMemLevel">DeflateMemLevel</a></li> + </ul> + <hr /> + <!-- the HR is part of the directive description --> + + <h2><a id="DeflateFilterNote" name="DeflateFilterNote">DeflateFilterNote + directive</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> DeflateFilterNote <em>notename + </em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <i>none</i><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> none<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Experimental<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_deflate<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Apache 2.0 and + above</p> + + <p>The DeflateFilterNote directive specifies that a note about + compression ratios should be attached to the request. The name + of the note is the value specified for the directive.</p> + + <hr /> + <!-- the HR is part of the directive description --> + + <h2><a id="DeflateWindowSize" + name="DeflateWindowSize">DeflateWindowSize directive</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> DeflateWindowSize + <em>value</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <em>none</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> none<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Experimental<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_deflate<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Apache 2.0 and + above</p> + + <p>The <samp>DeflateWindowSize</samp> directive specifies the + zlib compression window size.</p> + + <hr /> + <!-- the HR is part of the directive description --> + + <h2><a id="DeflateMemLevel" name="DeflateMemLevel">DeflateMemLevel + directive</a></h2> + + <p><a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> DeflateMemLevel + <em>value</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <em>none</em><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Override" + rel="Help"><strong>Override:</strong></a> none<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> Experimental<br /> + <a href="directive-dict.html#Module" + rel="Help"><strong>Module:</strong></a> mod_deflate<br /> + <a href="directive-dict.html#Compatibility" + rel="Help"><strong>Compatibility:</strong></a> Apache 2.0 and + above</p> + + <p>The DeflateMemLevel directive specifies the amount of + memory available to zlib for compression.</p> + <!--#include virtual="footer.html" --> + </body> +</html> + diff --git a/docs/manual/mod/mod_deflate.xml b/docs/manual/mod/mod_deflate.xml new file mode 100644 index 0000000000..44b5efda36 --- /dev/null +++ b/docs/manual/mod/mod_deflate.xml @@ -0,0 +1,88 @@ +<?xml version="1.0"?> +<!DOCTYPE xml:manual [ <!ENTITY nbsp " "> ]> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>mod_deflate</name> +<description>Compress content before + it is delivered to the client</description> +<status>experimental</status> +<sourcefile>mod_deflate.c</sourcefile> +<identifier>deflate_module</identifier> + +<summary> + <p>The experimental <module>mod_deflate</module> module provides + the <code>DEFLATE</code> output filter that allows output from + your server to be compressed before being sent to the client over + the network.</p> +</summary> +<seealso><directive module="mod_mime">AddOutputFilter</directive></seealso> +<seealso><directive module="core">SetOutputFilter</directive></seealso> + +<section><title>Enabling Compression</title> + + <p>Compression is implemented by the <code>DEFLATE</code> + <a href="../filter.html">filter</a>. The following directive + will enable compression for documents in the container where it + is placed:</p> + <p><strong>Most popular browsers can not handle compression of all content + so you may want to enable the 'gzip-only-text/html' note (see below) + </strong></p> + +<example>SetEnv gzip-only-text/html 1<br /> +SetOutputFilter DEFLATE +</example> + + <p>Here is an example of enabling compression for the Apache + documentation:</p> + +<example> +<Directory "/your-server-root/manual"><br /> + SetEnv gzip-only-text/html 1<br /> + SetOutputFilter DEFLATE<br /> +</Directory> +</example> +</section> + +<directivesynopsis> +<name>DeflateFilterNote</name> +<description>Places the compression ratio in a note for logging</description> +<syntax>DeflateFilterNote <em>notename</em></syntax> +<contextlist><context>server config</context></contextlist> + +<usage> + <p>The <directive>DeflateFilterNote</directive> directive + specifies that a note about compression ratios should be attached + to the request. The name of the note is the value specified for + the directive.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>DeflateWindowSize</name> +<description>Zlib compression window size</description> +<syntax>DeflateWindowSize <em>value</em></syntax> +<contextlist><context>server config</context></contextlist> + +<usage> + <!-- XXX: Ummm... What unit??? --> + <p>The <directive>DeflateWindowSize</directive> directive specifies the + zlib compression window size.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>DeflateMemLevel</name> +<description>Amount of memory available to zlib for compression</description> +<syntax>DeflateMemLevel <em>value</em></syntax> +<contextlist><context>server config</context></contextlist> + +<usage> + <!-- XXX: Ummm... What unit??? --> + <p>The <directive>DeflateMemLevel</directive> directive specifies + the amount of memory available to zlib for compression.</p> +</usage> +</directivesynopsis> + +</modulesynopsis> + diff --git a/docs/manual/mod/mod_dir.xml b/docs/manual/mod/mod_dir.xml new file mode 100644 index 0000000000..850aa63872 --- /dev/null +++ b/docs/manual/mod/mod_dir.xml @@ -0,0 +1,81 @@ +<?xml version="1.0"?> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>mod_dir</name> +<description>Provides for "trailing slash" redirects and + serving directory index files.</description> +<status>Base</status> +<sourcefile>mod_dir.c</sourcefile> +<identifier>dir_module</identifier> + +<summary> + <p>The index of a directory can come from one of two sources:</p> + + <ul> + <li>A file written by the user, typically called + <code>index.html</code>. The <directive module="mod_dir" + >DirectoryIndex</directive> directive sets the + name of this file. This is controlled by + <module>mod_dir</module>.</li> + + <li>Otherwise, a listing generated by the server. This is + provided by <module>mod_autoindex</module>.</li> + </ul> + <p>The two functions are separated so that you can completely + remove (or replace) automatic index generation should you want + to.</p> + + <p>A "trailing slash" redirect is issued when the server + receives a request for a URL + <code>http://servername/foo/dirname</code> where + <code>dirname</code> is a directory. Directories require a + trailing slash, so <module>mod_dir</module> issues a redirect to + <code>http://servername/foo/dirname/</code>.</p> +</summary> + +<directivesynopsis> +<description>List of resources to look for when the client requests +a directory</description> +<name>DirectoryIndex</name> +<syntax>DirectoryIndex + <em>local-url</em> [<em>local-url</em>] ...</syntax> +<default>DirectoryIndex index.html</default> +<contextlist><context>server config</context> +<context>virtual host</context> +<context>directory</context> +<context>.htaccess</context> +</contextlist> +<override>Indexes</override> + +<usage> + <p>The <directive>DirectoryIndex</directive> directive sets the + list of resources to look for, when the client requests an index + of the directory by specifying a / at the end of the a directory + name. <em>Local-url</em> is the (%-encoded) URL of a document on + the server relative to the requested directory; it is usually the + name of a file in the directory. Several URLs may be given, in + which case the server will return the first one that it finds. If + none of the resources exist and the <code>Indexes</code> option is + set, the server will generate its own listing of the + directory.</p> + +<example><title>Example</title> +DirectoryIndex index.html +</example> + + <p>then a request for <code>http://myserver/docs/</code> would + return <code>http://myserver/docs/index.html</code> if it + exists, or would list the directory if it did not.</p> + + <p>Note that the documents do not need to be relative to the + directory;</p> + +<example>DirectoryIndex index.html index.txt /cgi-bin/index.pl</example> + <p>would cause the CGI script <code>/cgi-bin/index.pl</code> to be + executed if neither <code>index.html</code> or + <code>index.txt</code> existed in a directory.</p> +</usage> +</directivesynopsis> + +</modulesynopsis>
\ No newline at end of file diff --git a/docs/manual/mod/mod_env.xml b/docs/manual/mod/mod_env.xml new file mode 100644 index 0000000000..a502fb5745 --- /dev/null +++ b/docs/manual/mod/mod_env.xml @@ -0,0 +1,80 @@ +<?xml version="1.0"?> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>mod_env</name> + <description>Modifies the environment which is + passed to CGI scripts and SSI pages</description> + <status>Base</status> + <sourcefile>mod_env.c</sourcefile> + <identifier>env_module</identifier> + <summary> + <p>This module allows for control of the environment that will + be provided to CGI scripts and SSI pages. Environment variables + may be passed from the shell which invoked the httpd process. + Alternatively, environment variables may be set or unset within + the configuration process.</p> + </summary> + <seealso><a href="../env.html">Environment Variables</a></seealso> + + <directivesynopsis> + <name>PassEnv</name> + <description>Passes environment variables from the shell</description> + <syntax>PassEnv + <em>env-variable</em> [<em>env-variable</em>] ...</syntax> + <contextlist> + <context>server config</context><context>virtual host</context> + <context>directory</context><context>.htaccess</context> + </contextlist> + <override>FileInfo</override> + +<usage> + <p>Specifies one or more environment variables to pass to CGI + scripts and SSI pages from the environment of the shell which + invoked the httpd process. Example:</p> +<example> + PassEnv LD_LIBRARY_PATH +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>SetEnv</name> +<description>Sets environment variables</description> +<syntax>SetEnv <em>env-variable value</em></syntax> +<contextlist> +<context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context> +</contextlist> +<override>FileInfo</override> + +<usage> + <p>Sets an environment variable, which is then passed on to CGI + scripts and SSI pages. Example:</p> +<example> + SetEnv SPECIAL_PATH /foo/bin +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>UnsetEnv</name> +<description>Removes variables from the environment</description> +<syntax>UnsetEnv <em>env-variable</em> [<em>env-variable</em>] ...</syntax> +<contextlist> +<context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context> +</contextlist> +<override>FileInfo</override> + +<usage> + <p>Removes one or more environment variables from those passed + on to CGI scripts and SSI pages. Example:</p> +<example> + UnsetEnv LD_LIBRARY_PATH +</example> +</usage> +</directivesynopsis> + +</modulesynopsis> + diff --git a/docs/manual/mod/mod_example.xml b/docs/manual/mod/mod_example.xml new file mode 100644 index 0000000000..97bd72f71a --- /dev/null +++ b/docs/manual/mod/mod_example.xml @@ -0,0 +1,120 @@ +<?xml version="1.0"?> +<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd"> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>mod_example</name> +<description>Illustrates the Apache module API</description> +<status>Experimental</status> +<sourcefile>mod_example.c</sourcefile> +<identifier>example_module</identifier> + +<summary> +<note type="warning"> + This document has not been updated + to take into account changes made in the 2.0 version of the + Apache HTTP Server. Some of the information may still be + relevant, but please use it with care. +</note> + + <p>The files in the <code>src/modules/example directory</code> + under the Apache distribution directory tree are provided as an + example to those that wish to write modules that use the Apache + API.</p> + + <p>The main file is <code>mod_example.c</code>, which + illustrates all the different callback mechanisms and call + syntaxes. By no means does an add-on module need to include + routines for all of the callbacks - quite the contrary!</p> + + <p>The example module is an actual working module. If you link + it into your server, enable the "example-handler" handler for a + location, and then browse to that location, you will see a + display of some of the tracing the example module did as the + various callbacks were made.</p> +</summary> + +<section><title>Compiling the example module</title> + + <p>To include the example module in your server, follow the + steps below:</p> + + <ol> + <li> + Uncomment the "AddModule modules/example/mod_example" line + near the bottom of the <code>src/Configuration</code> file. + If there isn't one, add it; it should look like this: +<example> + AddModule modules/example/mod_example.o +</example> + </li> + + <li>Run the <code>src/Configure</code> script + ("<code>cd src; ./Configure</code>"). This will + build the Makefile for the server itself, and update the + <code>src/modules/Makefile</code> for any additional modules + you have requested from beneath that subdirectory.</li> + + <li>Make the server (run "<code>make</code>" in the + <code>src</code> directory).</li> + </ol> + + <p>To add another module of your own:</p> + + <ol type="A"> + <li><code>mkdir src/modules/<em>mymodule</em></code></li> + + <li><code>cp src/modules/example/* + src/modules/<em>mymodule</em></code></li> + + <li>Modify the files in the new directory.</li> + + <li>Follow steps [1] through [3] above, with appropriate + changes.</li> + </ol> +</section> + +<section><title>Using the <code>mod_example</code> Module</title> + + <p>To activate the example module, include a block similar to + the following in your <code>srm.conf</code> file:</p> +<example> + <Location /example-info><br /> + SetHandler example-handler<br /> + </Location> +</example> + + <p>As an alternative, you can put the following into a <a + href="core.html#accessfilename"><code>.htaccess</code></a> file + and then request the file "test.example" from that location:</p> +<example> + AddHandler example-handler .example +</example> + + <p>After reloading/restarting your server, you should be able + to browse to this location and see the brief display mentioned + earlier.</p> +</section> + +<directivesynopsis> +<name>Example</name> +<description>Demonstration directive to illustrate the Apache module +API</description> +<syntax>Example</syntax> +<contextlist><context>server config</context> +<context>virtual host</context><context>directory</context> +<context>.htaccess</context></contextlist> + +<usage> + <p>The <directive>Example</directive> directive just sets a demonstration + flag which the example module's content handler displays. It + takes no arguments. If you browse to an URL to which the + example content-handler applies, you will get a display of the + routines within the module and how and in what order they were + called to service the document request. The effect of this + directive one can observe under the point "<code>Example + directive declared here: YES/NO</code>".</p> +</usage> +</directivesynopsis> + +</modulesynopsis> diff --git a/docs/manual/mod/mod_expires.xml b/docs/manual/mod/mod_expires.xml new file mode 100644 index 0000000000..90ddbe3a7e --- /dev/null +++ b/docs/manual/mod/mod_expires.xml @@ -0,0 +1,208 @@ +<?xml version="1.0"?> +<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd"> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>mod_expires</name> +<description>Generation of + <code>Expires</code> HTTP headers according to user-specified + criteria</description> +<status>Extension</status> +<sourcefile>mod_expires.c</sourcefile> +<identifier>expires_module</identifier> + +<summary> + <p>This module controls the setting of the <code>Expires</code> + HTTP header in server responses. The expiration date can set to + be relative to either the time the source file was last + modified, or to the time of the client access.</p> + + <p>The <code>Expires</code> HTTP header is an instruction to + the client about the document's validity and persistence. If + cached, the document may be fetched from the cache rather than + from the source until this time has passed. After that, the + cache copy is considered "expired" and invalid, and a new copy + must be obtained from the source.</p> +</summary> + +<section id="AltSyn"><title>Alternate Interval + Syntax</title> + + <p>The <directive module="mod_expires">ExpiresDefault</directive> and + <directive module="mod_expires">ExpiresByType</directive> directives + can also be defined in a more readable syntax of the form:</p> + +<example> + ExpiresDefault "<base> [plus] {<num> + <type>}*"<br /> + ExpiresByType type/encoding "<base> [plus] + {<num> <type>}*" +</example> + + <p>where <base> is one of:</p> + + <ul> + <li><code>access</code></li> + + <li><code>now</code> (equivalent to + '<code>access</code>')</li> + + <li><code>modification</code></li> + </ul> + + <p>The '<code>plus</code>' keyword is optional. <num> + should be an integer value [acceptable to <code>atoi()</code>], + and <type> is one of:</p> + + <ul> + <li><code>years</code></li> + + <li><code>months</code></li> + + <li><code>weeks</code></li> + + <li><code>days</code></li> + + <li><code>hours</code></li> + + <li><code>minutes</code></li> + + <li><code>seconds</code></li> + </ul> + + <p>For example, any of the following directives can be used to + make documents expire 1 month after being accessed, by + default:</p> + +<example> + ExpiresDefault "access plus 1 month"<br /> + ExpiresDefault "access plus 4 weeks"<br /> + ExpiresDefault "access plus 30 days" +</example> + + <p>The expiry time can be fine-tuned by adding several + '<num> <type>' clauses:</p> + +<example> +ExpiresByType text/html "access plus 1 month 15 + days 2 hours"<br /> + ExpiresByType image/gif "modification plus 5 hours 3 + minutes" +</example> + + <p>Note that if you use a modification date based setting, the + Expires header will <strong>not</strong> be added to content + that does not come from a file on disk. This is due to the fact + that there is no modification time for such content.</p> +</section> + +<directivesynopsis> +<name>ExpiresActive</name> +<description>Enables generation of <code>Expires</code> headers</description> +<syntax>ExpiresActive On|Off</syntax> +<contextlist><context>server config</context> +<context>virtual host</context><context>directory</context> +<context>.htaccess</context></contextlist> +<override>Indexes</override> + +<usage> + <p>This directive enables or disables the generation of the + <code>Expires</code> header for the document realm in question. + (That is, if found in an <code>.htaccess</code> file, for + instance, it applies only to documents generated from that + directory.) If set to <em><code>Off</code></em>, no + <code>Expires</code> header will be generated for any document + in the realm (unless overridden at a lower level, such as an + <code>.htaccess</code> file overriding a server config file). + If set to <em><code>On</code></em>, the header will be added to + served documents according to the criteria defined by the + <directive module="mod_expires">ExpiresByType</directive> and + <directive module="mod_expires">ExpiresDefault</directive> directives + (<em>q.v.</em>).</p> + + <p>Note that this directive does not guarantee that an + <code>Expires</code> header will be generated. If the criteria + aren't met, no header will be sent, and the effect will be as + though this directive wasn't even specified.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>ExpiresByType</name> +<description>Value of the <code>Expires</code> header configured +by MIME type</description> +<syntax>ExpiresByType + <em>MIME-type <code>seconds</em></syntax> +<contextlist><context>server config</context> +<context>virtual host</context><context>directory</context> +<context>.htaccess</context></contextlist> +<override>Indexes</override> + +<usage> + <p>This directive defines the value of the <code>Expires</code> + header generated for documents of the specified type + (<em>e.g.</em>, <code>text/html</code>). The second argument + sets the number of seconds that will be added to a base time to + construct the expiration date.</p> + + <p>The base time is either the last modification time of the + file, or the time of the client's access to the document. Which + should be used is specified by the + <code><em><code></em></code> field; <strong>M</strong> + means that the file's last modification time should be used as + the base time, and <strong>A</strong> means the client's access + time should be used.</p> + + <p>The difference in effect is subtle. If <em>M</em> is used, + all current copies of the document in all caches will expire at + the same time, which can be good for something like a weekly + notice that's always found at the same URL. If <em>A</em> is + used, the date of expiration is different for each client; this + can be good for image files that don't change very often, + particularly for a set of related documents that all refer to + the same images (<em>i.e.</em>, the images will be accessed + repeatedly within a relatively short timespan).</p> + + <p><strong>Example:</strong></p> +<example> +# enable expirations<br /> +ExpiresActive On<br /> +# expire GIF images after a month in the client's cache<br /> +ExpiresByType image/gif A2592000<br /> +# HTML documents are good for a week from the time they were changed<br /> +ExpiresByType text/html M604800 +</example> + + <p>Note that this directive only has effect if + <code>ExpiresActive On</code> has been specified. It overrides, + for the specified MIME type <em>only</em>, any expiration date + set by the <directive module="mod_expires">ExpiresDefault</directive> + directive.</p> + + <p>You can also specify the expiration time calculation using + an <a href="#AltSyn">alternate syntax</a>, described earlier in + this document.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>ExpiresDefault</name> +<description>Default algorithm for calculating expiration time</description> +<syntax>ExpiresDefault <em><code>seconds</em></syntax> +<contextlist><context>server config</context> +<context>virtual host</context><context>directory</context> +<context>.htaccess</context></contextlist> +<override>Indexes</override> + +<usage> + <p>This directive sets the default algorithm for calculating the + expiration time for all documents in the affected realm. It can be + overridden on a type-by-type basis by the <directive + module="mod_expires">ExpiresByType</directive> directive. See the + description of that directive for details about the syntax of the + argument, and the <a href="#AltSyn">alternate syntax</a> + description as well.</p> +</usage> +</directivesynopsis> +</modulesynopsis> + diff --git a/docs/manual/mod/mod_ext_filter.xml b/docs/manual/mod/mod_ext_filter.xml new file mode 100644 index 0000000000..20dd458af0 --- /dev/null +++ b/docs/manual/mod/mod_ext_filter.xml @@ -0,0 +1,232 @@ +<?xml version="1.0"?> +<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd"> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>mod_ext_filter</name> +<description>Pass the response body + through an external program before delivery to the + client</description> +<status>Experimental</status> +<sourcefile>mod_ext_filter.c</sourcefile> +<identifier>ext_filter_module</identifier> + +<summary> + <p>This is an <strong>experimental</strong> module and should + be used with care. Test your <module>mod_ext_filter</module> + configuration carefully to ensure that it performs the desired + function. You may wish to review <a href="../filter.html"> + this information</a> for background on the Apache filtering + model.</p> + + <p><module>mod_ext_filter</module> presents a simple and familiar + programming model for filters. With this module, a program + which reads from stdin and writes to stdout (i.e., a Unix-style + filter command) can be a filter for Apache. This filtering + mechanism is much slower than using a filter which is specially + written for the Apache API and runs inside of the Apache server + process, but it does have the following benefits:</p> + + <ul> + <li>the programming model is much simpler</li> + + <li>any programming/scripting language can be used, provided + that it allows the program to read from standard input and + write to standard output</li> + + <li>existing programs can be used unmodified as Apache + filters</li> + </ul> + + <p>Even when the performance characteristics are not suitable + for production use, <code>mod_ext_filter</code> can be used as + a prototype environment for filters.</p> +</summary> + +<section><title>Examples</title> + +<section><title>Generating HTML from some other type of response</title> +<example> +<pre> + # mod_ext_filter directive to define a filter to HTML-ize text/c files + # using the external program /usr/bin/enscript, with the type of the + # result set to text/html + ExtFilterDefine c-to-html mode=output intype=text/c outtype=text/html \ + cmd="/usr/bin/enscript --color -W html -Ec -o - -" + + <Directory "/export/home/trawick/apacheinst/htdocs/c"> + + # core directive to cause the new filter to be run on output + SetOutputFilter c-to-html + + # mod_mime directive to set the type of .c files to text/c + AddType text/c .c + + # mod_ext_filter directive to set the debug level just high + # enough to see a log message per request showing the configuration + # in force + ExtFilterOptions DebugLevel=1 + + </Directory> +</pre> +</example> +</section> + +<section><title>Implementing a content encoding filter</title> +<example> +<pre> + # mod_ext_filter directive to define the external filter + ExtFilterDefine gzip mode=output cmd=/bin/gzip + + <Location /gzipped> + + # core directive to cause the gzip filter to be run on output + SetOutputFilter gzip + + # mod_header directive to add "Content-Encoding: gzip" header field + Header set Content-Encoding gzip + + </Location> +</pre> +</example> + + <p>Note: this gzip example is just for the purposes of illustration. + Please refer to <module>mod_deflate</module> for a practical + implementation.</p> +</section> + +<section><title>Slowing down the server</title> +<example> +<pre> + # mod_ext_filter directive to define a filter which runs everything + # through cat; cat doesn't modify anything; it just introduces extra + # pathlength and consumes more resources + ExtFilterDefine slowdown mode=output cmd=/bin/cat preservescontentlength + + <Location /> + + # core directive to cause the slowdown filter to be run several times on + # output + SetOutputFilter slowdown slowdown slowdown + + </Location> +</pre> +</example> +</section> + +</section> <!-- Examples --> + +<directivesynopsis> +<name>ExtFilterDefine</name> +<syntax>ExtFilterDefine <em>filtername</em> <em>parameters</em></syntax> +<contextlist><context>server config</context></contextlist> + +<usage> + <p>The <directive>ExtFilterDefine</directive> directive defines the + characteristics of an external filter, including the program to + run and its arguments.</p> + + <p><em>filtername</em> specifies the name of the filter being + defined. This name can then be used in SetOutputFilter + directives. It must be unique among all registered filters. + <em>At the present time, no error is reported by the + register-filter API, so a problem with duplicate names isn't + reported to the user.</em></p> + + <p>Subsequent parameters can appear in any order and define the + external command to run and certain other characteristics. The + only required parameter is <em>cmd=</em>. These parameters + are:</p> + + <dl> + <dt>cmd=<em>cmdline</em></dt> + + <dd>The <code>cmd=</code> keyword allows you to specify the + external command to run. If there are arguments after the + program name, the command line should be surrounded in + quotation marks.</dd> + + <dt>mode=<em>mode</em></dt> + + <dd><em>mode</em> should be <em>output</em> for now (the + default). In the future, <em>mode=input</em> will be used to + specify a filter for request bodies.</dd> + + <dt>intype=<em>imt</em></dt> + + <dd>This parameter specifies the internet media type (i.e., + MIME type) of documents which should be filtered. By default, + all documents are filtered. If <code>intype=</code> is + specified, the filter will be disabled for documents of other + types.</dd> + + <dt>outtype=<em>imt</em></dt> + + <dd>This parameter specifies the internet media type (i.e., + MIME type) of filtered documents. It is useful when the + filter changes the internet media type as part of the + filtering operation. By default, the internet media type is + unchanged.</dd> + + <dt>PreservesContentLength</dt> + + <dd>The <code>PreservesContentLength</code> keyword specifies + that the filter preserves the content length. This is not the + default, as most filters change the content length. In the + event that the filter doesn't modify the length, this keyword + should be specified.</dd> + </dl> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>ExtFilterOptions</name> +<syntax>ExtFilterOptions + <em>option</em> [<em>option</em>] ...</syntax> +<default>ExtFilterOptions DebugLevel=0 NoLogStderr</default> +<contextlist><context>directory</context></contextlist> + +<usage> + <p>The <directive>ExtFilterOptions</directive> directive specifies + special processing options for <code>mod_ext_filter</code>. + <em>Option</em> can be one of</p> + + <dl> + <dt>DebugLevel=<em>n</em></dt> + + <dd> + The <code>DebugLevel</code> keyword allows you to specify + the level of debug messages generated by + <code>mod_ext_filter</code>. By default, no debug messages + are generated. This is equivalent to + <code>DebugLevel=0</code>. With higher numbers, more debug + messages are generated, and server performance will be + degraded. The actual meanings of the numeric values are + described with the definitions of the DBGLVL_ constants + near the beginning of <code>mod_ext_filter.c</code>. + + <p>Note: The core directive LogLevel should be used to + cause debug messages to be stored in the Apache error + log.</p> + </dd> + + <dt>LogStderr | NoLogStderr</dt> + + <dd>The <code>LogStderr</code> keyword specifies that + messages written to standard error by the external filter + program will be saved in the Apache error log. + <code>NoLogStderr</code> disables this feature.</dd> + </dl> + + <p>Example:</p> +<example> + ExtFilterOptions LogStderr DebugLevel=0 +</example> + + <p>Messages written to the filter's standard error will be stored + in the Apache error log. No debug messages will be generated by + <module>mod_ext_filter</module>. </p> +</usage> +</directivesynopsis> + +</modulesynopsis>
\ No newline at end of file diff --git a/docs/manual/mod/mod_file_cache.xml b/docs/manual/mod/mod_file_cache.xml new file mode 100644 index 0000000000..3e6f4a4ef6 --- /dev/null +++ b/docs/manual/mod/mod_file_cache.xml @@ -0,0 +1,178 @@ +<?xml version="1.0"?> +<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd"> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>mod_file_cache</name> +<description>Caches a static list of files in memory</description> +<status>Experimental</status> +<sourcefile>mod_file_cache.c</sourcefile> +<identifier>file_cache_module</identifier> + +<summary> + +<note type="warning"> +This module should be used with care. You can easily + create a broken site using mod_file_cache, so read this + document carefully. +</note> + + <p><em>Caching</em> frequently requested files that change very + infrequently is a technique for reducing server load. + mod_file_cache provides two techniques for caching frequently + requested <em>static</em> files. Through configuration + directives, you can direct mod_file_cache to either open then + mmap()a file, or to pre-open a file and save the file's open + <em>file handle</em>. Both techniques reduce server load when + processing requests for these files by doing part of the work + (specifically, the file I/O) for serving the file when the + server is started rather than during each request.</p> + + <p>Notice: You cannot use this for speeding up CGI programs or + other files which are served by special content handlers. It + can only be used for regular files which are usually served by + the Apache core content handler.</p> + + <p>This module is an extension of and borrows heavily from the + mod_mmap_static module in Apache 1.3.</p> +</summary> + +<section><title>Using mod_file_cache</title> + + <p><module>mod_file_cache</module> caches a list of statically + configured files via <directive + module="mod_file_cache">MMapFile</directive> or <directive + module="mod_file_cache">CacheFile</directive> directives in the + main server configuration.</p> + + <p>Not all platforms support both directives. For example, Apache + on Windows does not currently support the <directive + module="mod_file_cache">MMapStatic</directive> directive, while + other platforms, like AIX, support both. You will receive an error + message in the server error log if you attempt to use an + unsupported directive. If given an unsupported directive, the + server will start but the file will not be cached. On platforms + that support both directives, you should experiment with both to + see which works best for you.</p> + +<section><title>MmapFile Directive</title> + + <p>The <directive module="mod_file_cache">MmapFile</directive> + directive of <module>mod_file_cache</module> maps a list of + statically configured files into memory through the system call + <code>mmap()</code>. This system call is available on most modern + Unix derivates, but not on all. There are sometimes + system-specific limits on the size and number of files that can be + mmap()d, experimentation is probably the easiest way to find + out.</p> + + <p>This mmap()ing is done once at server start or restart, + only. So whenever one of the mapped files changes on the + filesystem you <em>have</em> to restart the server (see the <a + href="../stopping.html">Stopping and Restarting</a> + documentation). To reiterate that point: if the files are + modified <em>in place</em> without restarting the server you + may end up serving requests that are completely bogus. You + should update files by unlinking the old copy and putting a new + copy in place. Most tools such as <code>rdist</code> and + <code>mv</code> do this. The reason why this modules doesn't + take care of changes to the files is that this check would need + an extra <code>stat()</code> every time which is a waste and + against the intent of I/O reduction.</p> +</section> + +<section><title>CacheFile Directive</title> + + <p>The <directive module="mod_file_cache">CacheFile</directive> + directive of <module>mod_file_cache</module> opens an active + <em>handle</em> or <em>file descriptor</em> to the file (or files) + listed in the configuration directive and places these open file + handles in the cache. When the file is requested, the server + retrieves the handle from the cache and passes it to the + sendfile() (or TransmitFile() on Windows), socket API.</p> + + <p>Insert more details about sendfile API...</p> + + <p>This file handle caching is done once at server start or + restart, only. So whenever one of the cached files changes on + the filesystem you <em>have</em> to restart the server (see the + <a href="../stopping.html">Stopping and Restarting</a> + documentation). To reiterate that point: if the files are + modified <em>in place</em> without restarting the server you + may end up serving requests that are completely bogus. You + should update files by unlinking the old copy and putting a new + copy in place. Most tools such as <code>rdist</code> and + <code>mv</code> do this.</p> +</section> + +<note><title>Note</title> Don't bother asking for a for a + directive which recursively caches all the files in a + directory. Try this instead... See the + <directive module="core">Include</directive> directive, and consider + this command: +<example> + find /www/htdocs -type f -print \ <br /> + | sed -e 's/.*/mmapfile &/' > /www/conf/mmap.conf +</example> +</note> + +</section> + +<directivesynopsis> +<name>MMapFile</name> +<syntax>MMapFile <em>file-path</em> [<em>file-path</em>] ...</syntax> +<contextlist><context>server config</context></contextlist> + +<usage> + <p>The <directive>MMapFile</directive> directive maps one or more files + (given as whitespace separated arguments) into memory at server + startup time. They are automatically unmapped on a server + shutdown. When the files have changed on the filesystem at + least a HUP or USR1 signal should be send to the server to + re-mmap them.</p> + + <p>Be careful with the <em>file-path</em> arguments: They have + to literally match the filesystem path Apache's URL-to-filename + translation handlers create. We cannot compare inodes or other + stuff to match paths through symbolic links <em>etc.</em> + because that again would cost extra <code>stat()</code> system + calls which is not acceptable. This module may or may not work + with filenames rewritten by <module>mod_alias</module> or + <module>mod_rewrite</module>.</p> + +<example><title>Example</title> + MMapFile /usr/local/apache/htdocs/index.html +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>CacheFile</name> +<syntax>CacheFile + <em>file-path</em> [<em>file-path</em>] ...</syntax> +<contextlist><context>server config</context></contextlist> + +<usage> + <p>The <directive>CacheFile</directive> directive opens handles to + one or more files (given as whitespace separated arguments) and + places these handles into the cache at server startup + time. Handles to cached files are automatically closed on a server + shutdown. When the files have changed on the filesystem, the + server should be restarted to to re-cache them.</p> + + <p>Be careful with the <em>file-path</em> arguments: They have + to literally match the filesystem path Apache's URL-to-filename + translation handlers create. We cannot compare inodes or other + stuff to match paths through symbolic links <em>etc.</em> + because that again would cost extra <code>stat()</code> system + calls which is not acceptable. This module may or may not work + with filenames rewritten by <module>mod_alias</module> or + <module>mod_rewrite</module>.</p> + +<example><title>Example</title> + CacheFile /usr/local/apache/htdocs/index.html +</example> +</usage> + +</directivesynopsis> +</modulesynopsis>
\ No newline at end of file diff --git a/docs/manual/mod/mod_headers.xml b/docs/manual/mod/mod_headers.xml new file mode 100644 index 0000000000..b71885c2b9 --- /dev/null +++ b/docs/manual/mod/mod_headers.xml @@ -0,0 +1,261 @@ +<?xml version="1.0"?> +<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd"> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>mod_headers</name> +<description>Customization of HTTP request + and response headers</description> +<status>Extension</status> +<sourcefile>mod_headers.c</sourcefile> +<identifier>headers_module</identifier> +<compatibility>RequestHeader is available only in Apache 2.0</compatibility> + +<summary> + <p>This module provides directives to control and modify HTTP + request and response headers. Headers can be merged, replaced + or removed.</p> +</summary> + +<section><title>Order of Processing</title> + + <p>The directives provided by mod_header can occur almost + anywhere within the server configuration. They are valid in the + main server config and virtual host sections, inside + <Directory>, <Location> and <Files> sections, + and within .htaccess files.</p> + + <p>The directives are processed in the following order:</p> + + <ol> + <li>main server</li> + + <li>virtual host</li> + + <li><Directory> sections and .htaccess</li> + + <li><Location></li> + + <li><Files></li> + </ol> + + <p>Order is important. These two headers have a different + effect if reversed:</p> + +<example> +RequestHeader append MirrorID "mirror 12"<br /> + RequestHeader unset MirrorID +</example> + + <p>This way round, the MirrorID header is not set. If reversed, + the MirrorID header is set to "mirror 12".</p> +</section> + +<section><title>Example</title> + + <ol> + <li>Copy all request headers that begin with "TS" to the + response headers: + +<example> + Header echo ^TS* +</example></li> + + <li>Add a header, MyHeader, to the response including a + timestamp for when the request was received and how long it + took to begin serving the request. This header can be used by + the client to intuit load on the server or in isolating + bottlenecks between the client and the server. + +<example> + Header add MyHeader "%D %t" +</example> + results in this header being added to the response: +<example> + MyHeader: D=3775428 t=991424704447256 +</example> + </li> + + <li>Say hello to Joe + +<example> + Header add MyHeader "Hello Joe. It took %D microseconds for Apache to serve this request." +</example> + results in this header being added to the response: +<example> + MyHeader: Hello Joe. It took D=3775428 microseconds for Apache to serve this request. +</example> + </li> + + <li>Conditionally send MyHeader on the response if and only + if header "MyRequestHeader" is present on the request. This + is useful for constructing headers in response to some client + stimulus. Note that this example requires the services of the + mod_setenvif module. + +<example> + SetEnvIf MyRequestHeader value HAVE_MyRequestHeader<br /> + Header add MyHeader "%D %t mytext" env=HAVE_MyRequestHeader +</example> + If the header "MyRequestHeader: value" is present on the + HTTP request, the response will contain the following + header: +<example> + MyHeader: D=3775428 t=991424704447256 mytext +</example> + </li> + </ol> +</section> + +<directivesynopsis> +<name>RequestHeader</name> +<description>Configure HTTP request headers</description> +<syntax>RequestHeader set|append|add|unset <em>header</em> +[<em>value</em>]</syntax> +<contextlist><context>server config</context> +<context>virtual host</context> +<context>directory</context> +<context>.htaccess</context></contextlist> +<override>FileInfo</override> + +<usage> + <p>This directive can replace, merge or remove HTTP request + headers. The header is modified just before the content handler + is run, allowing incoming headers to be modified. The action it + performs is determined by the first argument. This can be one + of the following values:</p> + + <ul> + <li><strong>set</strong><br /> + The request header is set, replacing any previous header + with this name</li> + + <li><strong>append</strong><br /> + The request header is appended to any existing header of the + same name. When a new value is merged onto an existing header + it is separated from the existing header with a comma. This + is the HTTP standard way of giving a header multiple + values.</li> + + <li><strong>add</strong><br /> + The request header is added to the existing set of headers, + even if this header already exists. This can result in two + (or more) headers having the same name. This can lead to + unforeseen consequences, and in general "append" should be + used instead.</li> + + <li><strong>unset</strong><br /> + The request header of this name is removed, if it exists. If + there are multiple headers of the same name, all will be + removed.</li> + </ul> + + <p>This argument is followed by a header name, which can + include the final colon, but it is not required. Case is + ignored. For <code>add</code>, <code>append</code> and + <code>set</code> a value is given as the third argument. If + this value contains spaces, it should be surrounded by double + quotes. For unset, no value should be given.</p> + + <p>The <directive>RequestHeader</directive> directive is processed + just before the request is run by its handler in the fixup phase. + This should allow headers generated by the browser, or by Apache + input filters to be overridden or modified.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>Header</name> +<description>Configure HTTP response headers</description> +<syntax>Header set|append|add|unset|echo <em>header</em> +[<em>value</em>]</syntax> +<contextlist><context>server config</context> +<context>virtual host</context> +<context>directory</context> +<context>.htaccess</context></contextlist> +<override>FileInfo</override> + +<usage> + <p>This directive can replace, merge or remove HTTP response + headers. The header is modified just after the content handler + and output filters are run, allowing outgoing headers to be + modified. The action it performs is determined by the first + argument. This can be one of the following values:</p> + + <ul> + <li><strong>set</strong><br /> + The response header is set, replacing any previous header + with this name. The <em>value</em> may be a format + string.</li> + + <li><strong>append</strong><br /> + The response header is appended to any existing header of + the same name. When a new value is merged onto an existing + header it is separated from the existing header with a comma. + This is the HTTP standard way of giving a header multiple + values.</li> + + <li><strong>add</strong><br /> + The response header is added to the existing set of headers, + even if this header already exists. This can result in two + (or more) headers having the same name. This can lead to + unforeseen consequences, and in general "append" should be + used instead.</li> + + <li><strong>unset</strong><br /> + The response header of this name is removed, if it exists. + If there are multiple headers of the same name, all will be + removed.</li> + + <li><strong>echo</strong><br /> + Request headers with this name are echoed back in the + response headers. <em>header</em> may be a regular + expression.</li> + </ul> + + <p>This argument is followed by a <em>header</em> name, which + can include the final colon, but it is not required. Case is + ignored for set, append, add and unset. The <em>header</em> + name for echo is case sensitive and may be a regular + expression.</p> + + <p>For <code>add</code>, <code>append</code> and + <code>set</code> a <em>value</em> is specified as the third + argument. If <em>value</em> contains spaces, it should be + surrounded by doublequotes. <em>value</em> may be a character + string, a string containing format specifiers or a combination + of both. The following format specifiers are supported in + <em>value</em>:</p> +<table> +<tr><td>%t: </td> <td>The time the request was received in Universal +Coordinated Time since the epoch (Jan. 1, 1970) measured in +microseconds. The value is preceded by "t=".</td></tr> + +<tr><td>%D: </td> <td>The time from when the request was received to +the time the headers are sent on the wire. This is a measure of the +duration of the request. The value is preceded by "D=".</td></tr> + +<tr><td>%{FOOBAR}e:</td> <td>The contents of the <a href="../env.html">environment +variable</a> FOOBAR.</td></tr> +</table> + + <p>When the <directive>Header</directive> directive is used with the + <code>add</code>, <code>append</code>, or <code>set</code> + argument, a fourth argument may be used to specify conditions + under which the action will be taken. If the <a + href="../env.html">environment variable</a> specified in the + <code>env=...</code> argument exists (or if the environment + variable does not exist and <code>env=!...</code> is specified) + then the action specified by the <directive>Header</directive> directive + will take effect. Otherwise, the directive will have no effect + on the request.</p> + + <p>The Header directives are processed just before the response + is sent to the network. These means that it is possible to set + and/or override most headers, except for those headers added by + the header filter.</p> +</usage> +</directivesynopsis> + +</modulesynopsis> + diff --git a/docs/manual/mod/mod_imap.xml b/docs/manual/mod/mod_imap.xml new file mode 100644 index 0000000000..489a2053b1 --- /dev/null +++ b/docs/manual/mod/mod_imap.xml @@ -0,0 +1,334 @@ +<?xml version="1.0"?> +<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd"> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>mod_imap</name> +<description>Server-side imagemap processing</description> +<status>Base</status> +<sourcefile>mod_imap.c</sourcefile> +<identifier>imap_module</identifier> + +<summary> + <p>This module processes <code>.map</code> files, thereby + replacing the functionality of the <code>imagemap</code> CGI + program. Any directory or document type configured to use the + handler <code>imap-file</code> (using either + <directive module="mod_mime">AddHandler</directive> or + <directive module="core">SetHandler</directive>) + will be processed by this module.</p> + + <p>The following directive will activate files ending with + <code>.map</code> as imagemap files:</p> + +<example>AddHandler imap-file map</example> + + <p>Note that the following is still supported:</p> + +<example>AddType application/x-httpd-imap map</example> + + <p>However, we are trying to phase out "magic MIME types" so we + are deprecating this method.</p> +</summary> + +<section><title>New Features</title> + + <p>The imagemap module adds some new features that were not + possible with previously distributed imagemap programs.</p> + + <ul> + <li>URL references relative to the Referer: information.</li> + + <li>Default <BASE> assignment through a new map + directive <code>base</code>.</li> + + <li>No need for <code>imagemap.conf</code> file.</li> + + <li>Point references.</li> + + <li>Configurable generation of imagemap menus.</li> + </ul> +</section> + +<section><title>Imagemap File</title> + + <p>The lines in the imagemap files can have one of several + formats:</p> + +<example> + directive value [x,y ...]<br /> + directive value "Menu text" [x,y ...]<br /> + directive value x,y ... "Menu text" +</example> + <p>The directive is one of <code>base</code>, + <code>default</code>, <code>poly</code>, <code>circle</code>, + <code>rect</code>, or <code>point</code>. The value is an + absolute or relative URL, or one of the special values listed + below. The coordinates are <code>x,y</code> pairs separated by + whitespace. The quoted text is used as the text of the link if + a imagemap menu is generated. Lines beginning with '#' are + comments.</p> + +<section><title>Imagemap File Directives</title> + <p>There are six directives allowed in the imagemap file. The + directives can come in any order, but are processed in the + order they are found in the imagemap file.</p> + + <dl> + <dt><code>base</code> Directive</dt> + + <dd>Has the effect of <code><BASE HREF="value"></code>. + The non-absolute URLs of the map-file are taken relative to + this value. The <code>base</code> directive overrides + ImapBase as set in a .htaccess file or in the server + configuration files. In the absence of an ImapBase + configuration directive, <code>base</code> defaults to + <code>http://server_name/</code>.<br /> + <code>base_uri</code> is synonymous with <code>base</code>. + Note that a trailing slash on the URL is significant.</dd> + + <dt><code>default</code> Directive</dt> + + <dd>The action taken if the coordinates given do not fit any + of the <code>poly</code>, <code>circle</code> or + <code>rect</code> directives, and there are no + <code>point</code> directives. Defaults to + <code>nocontent</code> in the absence of an ImapDefault + configuration setting, causing a status code of <code>204 No + Content</code> to be returned. The client should keep the + same page displayed.</dd> + + <dt><code>poly</code> Directive</dt> + + <dd>Takes three to one-hundred points, and is obeyed if the + user selected coordinates fall within the polygon defined by + these points.</dd> + + <dt><code>circle</code></dt> + + <dd>Takes the center coordinates of a circle and a point on + the circle. Is obeyed if the user selected point is with the + circle.</dd> + + <dt><code>rect</code> Directive</dt> + + <dd>Takes the coordinates of two opposing corners of a + rectangle. Obeyed if the point selected is within this + rectangle.</dd> + + <dt><code>point</code> Directive</dt> + + <dd>Takes a single point. The point directive closest to the + user selected point is obeyed if no other directives are + satisfied. Note that <code>default</code> will not be + followed if a <code>point</code> directive is present and + valid coordinates are given.</dd> + </dl> +</section> + +<section><title>Values</title> + + <p>The values for each of the directives can any of the following:</p> + + + <dl> + <dt>a URL</dt> + + <dd>The URL can be relative or absolute URL. Relative URLs + can contain '..' syntax and will be resolved relative to the + <code>base</code> value.<br /> + <code>base</code> itself will not resolved according to the + current value. A statement <code>base mailto:</code> will + work properly, though.</dd> + + <dt><code>map</code></dt> + + <dd>Equivalent to the URL of the imagemap file itself. No + coordinates are sent with this, so a menu will be generated + unless ImapMenu is set to 'none'.</dd> + + <dt><code>menu</code></dt> + + <dd>Synonymous with <code>map</code>.</dd> + + <dt><code>referer</code></dt> + + <dd>Equivalent to the URL of the referring document. Defaults + to <code>http://servername/</code> if no Referer: header was + present.</dd> + + <dt><code>nocontent</code></dt> + + <dd>Sends a status code of <code>204 No Content</code>, + telling the client to keep the same page displayed. Valid for + all but <code>base</code>.</dd> + + <dt><code>error</code></dt> + + <dd>Fails with a <code>500 Server Error</code>. Valid for all + but <code>base</code>, but sort of silly for anything but + <code>default</code>.</dd> + </dl> +</section> + +<section><title>Coordinates</title> + + <dl> + <dt><code>0,0 200,200</code></dt> + + <dd>A coordinate consists of an <code>x</code> and a <code>y</code> + value separated by a comma. The coordinates are separated + from each other by whitespace. To accommodate the way Lynx + handles imagemaps, should a user select the coordinate + <code>0,0</code>, it is as if no coordinate had been + selected.</dd> + </dl> + +</section> + +<section><title>Quoted Text</title> + + <dl> + <dt><code>"Menu Text"</code></dt> + + <dd>After the value or after the coordinates, the line + optionally may contain text within double quotes. This string + is used as the text for the link if a menu is + generated:<br /> + <code><a HREF="http://foo.com/">Menu + text</a></code><br /> + If no quoted text is present, the name of the link will be + used as the text:<br /> + <code><a + HREF="http://foo.com/">http://foo.com</a></code><br /> + It is impossible to escape double quotes within this + text.</dd> + </dl> +</section> +</section> + +<section><title>Example Mapfile</title> + +<example> + #Comments are printed in a 'formatted' or + 'semiformatted' menu.<br /> + #And can contain html tags. <hr><br /> + base referer<br /> + poly map "Could I have a menu, please?" 0,0 0,10 10,10 + 10,0<br /> + rect .. 0,0 77,27 "the directory of the referer"<br /> + circle http://www.inetnebr.com/lincoln/feedback/ 195,0 + 305,27<br /> + rect another_file "in same directory as referer" 306,0 + 419,27<br /> + point http://www.zyzzyva.com/ 100,100<br /> + point http://www.tripod.com/ 200,200<br /> + rect mailto:nate@tripod.com 100,150 200,0 "Bugs?"<br /> +</example> + +</section> + +<section><title>Referencing your mapfile</title> + +<example> + <A HREF="/maps/imagemap1.map"><br /> + <IMG ISMAP SRC="/images/imagemap1.gif"><br /> + </A> +</example> +</section> + +<directivesynopsis> +<name>ImapMenu</name> +<description>Action if no coordinates are given when calling +an imagemap</description> +<syntax>ImapMenu + none|formatted|semiformatted|unformatted</syntax> +<contextlist><context>server config</context> +<context>virtual host</context> +<context>directory</context> +<context>.htaccess</context></contextlist> +<override>Indexes</override> + +<usage> + <p>The <directive>ImapMenu</directive> directive determines the + action taken if an imagemap file is called without valid + coordinates.</p> + + <dl> + <dt><code>none</code></dt> + + <dd>If ImapMenu is <code>none</code>, no menu is generated, + and the <code>default</code> action is performed.</dd> + + <dt><code>formatted</code></dt> + + <dd>A <code>formatted</code> menu is the simplest menu. + Comments in the imagemap file are ignored. A level one header + is printed, then an hrule, then the links each on a separate + line. The menu has a consistent, plain look close to that of + a directory listing.</dd> + + <dt><code>semiformatted</code></dt> + + <dd>In the <code>semiformatted</code> menu, comments are + printed where they occur in the imagemap file. Blank lines + are turned into HTML breaks. No header or hrule is printed, + but otherwise the menu is the same as a + <code>formatted</code> menu.</dd> + + <dt><code>unformatted</code></dt> + + <dd>Comments are printed, blank lines are ignored. Nothing is + printed that does not appear in the imagemap file. All breaks + and headers must be included as comments in the imagemap + file. This gives you the most flexibility over the appearance + of your menus, but requires you to treat your map files as + HTML instead of plaintext.</dd> + </dl> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>ImapDefault</name> +<description>Default action when an imagemap is called with coordinates +that are not explicitly mapped</description> +<syntax>ImapDefault error|nocontent|map|referer|<em>URL</em></syntax> +<default>ImapDefault nocontent</default> +<contextlist><context>server config</context> +<context>virtual host</context> +<context>directory</context> +<context>.htaccess</context></contextlist> +<override>Indexes</override> + +<usage> + <p>The <directive>ImapDefault</directive> directive sets the default + <code>default</code> used in the imagemap files. Its value is + overridden by a <code>default</code> directive within the + imagemap file. If not present, the <code>default</code> action + is <code>nocontent</code>, which means that a <code>204 No + Content</code> is sent to the client. In this case, the client + should continue to display the original page.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>ImapBase</name> +<description>Default <code>base</code> for imagemap files</description> +<syntax>ImapBase map|referer|<em>URL</em></syntax> +<default>ImapBase http://servername/</default> +<contextlist><context>server config</context> +<context>virtual host</context> +<context>directory</context> +<context>.htaccess</context></contextlist> +<override>Indexes</override> + +<usage> + <p>The <directive>ImapBase</directive> directive sets the default + <code>base</code> used in the imagemap files. Its value is + overridden by a <code>base</code> directive within the imagemap + file. If not present, the <code>base</code> defaults to + <code>http://servername/</code>.</p> +</usage> +</directivesynopsis> + +</modulesynopsis>
\ No newline at end of file diff --git a/docs/manual/mod/mod_include.xml b/docs/manual/mod/mod_include.xml new file mode 100644 index 0000000000..c124daa1bf --- /dev/null +++ b/docs/manual/mod/mod_include.xml @@ -0,0 +1,695 @@ +<?xml version="1.0"?> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>mod_include</name> +<status>Base</status> +<identifier>include_module</identifier> +<source>mod_include.c</source> +<compatibility></compatibility> +<description>This module provides for server-parsed html +documents.</description> + +<summary> + + <p>This module provides a filter which will process files + before they are sent to the client. The processing is + controlled by specially formated SGML comments, referred to as + <em>elements</em>. These elements allow conditional text, the + inclusion other files or programs, as well as the setting and + printing of environment variables.</p> + + <seealso><strong>See also</strong>: + <directive module="core">Options</directive>, + <directive module="core">SetOutputFilter</directive> + and <directive module="core">AcceptPathInfo</directive>.</seealso> + +</summary> + +<section id="enabling"> + <title>Enabling Server-Side Includes</title> + + <p>Server Side Includes are implemented by the + <code>INCLUDES</code> <a href="../filter.html">filter</a>. If + documents containing server-side include directives are given + the extension .shtml, the following directives will make Apache + parse them and assign the resulting document the mime type of + <code>text/html</code>:</p> + + <example> + AddType text/html .shtml<br /> + AddOutputFilter INCLUDES .shtml + </example> + + <p>The following directive must be given for the directories + containing the shtml files (typically in a + <code><Directory></code> section, but this directive is + also valid .htaccess files if <code>AllowOverride + Options</code> is set):</p> + + <example> + Options +Includes + </example> + + <p>For backwards compatibility, the <code>server-parsed</code> + <a href="../handler.html">handler</a> also activates the + INCLUDES filter. As well, Apache will activate the INCLUDES + filter for any document with mime type + <code>text/x-server-parsed-html</code> or + <code>text/x-server-parsed-html3</code> (and the resulting + output will have the mime type <code>text/html</code>).</p> + + <p>For more information, see our <a + href="../howto/ssi.html">Tutorial on Server Side + Includes</a>.</p> +</section> + +<section id="basic"> + <title>Basic Elements</title> + <p>The document is parsed as an HTML document, with special + commands embedded as SGML comments. A command has the syntax: </p> + + <example> + <code><!--#</code><em>element attribute=value + attribute=value ...</em> <code>--></code> + </example> + + <p>The value will often be enclosed in double quotes; many + commands only allow a single attribute-value pair. Note that + the comment terminator (<samp>--></samp>) should be preceded + by whitespace to ensure that it isn't considered part of an SSI + token. </p> + + <p>The allowed elements are:</p> + + <dl> + <dt><strong>config</strong></dt> + + <dd> + This command controls various aspects of the parsing. The + valid attributes are: + + <dl> + <dt><strong>errmsg</strong></dt> + + <dd>The value is a message that is sent back to the + client if an error occurs whilst parsing the + document.</dd> + + <dt><strong>sizefmt</strong></dt> + + <dd>The value sets the format to be used which displaying + the size of a file. Valid values are <code>bytes</code> + for a count in bytes, or <code>abbrev</code> for a count + in Kb or Mb as appropriate.</dd> + + <dt><strong>timefmt</strong></dt> + + <dd>The value is a string to be used by the + <code>strftime(3)</code> library routine when printing + dates.</dd> + </dl> + </dd> + + <dt><strong><a id="echo" name="echo">echo</a></strong></dt> + + <dd> + This command prints one of the <a href="#includevars">include + variables</a>, defined + below. If the variable is unset, it is printed as + <code>(none)</code>. Any dates printed are subject to the + currently configured <code>timefmt</code>. Attributes: + + <dl> + <dt><strong>var</strong></dt> + + <dd>The value is the name of the variable to print.</dd> + + <dt><strong>encoding</strong></dt> + + <dd>Specifies how Apache should encode special characters + contained in the variable before outputting them. If set + to "none", no encoding will be done. If set to "url", + then URL encoding (also known as %-encoding; this is + appropriate for use within URLs in links, etc.) will be + performed. At the start of an <code>echo</code> element, + the default is set to "entity", resulting in entity + encoding (which is appropriate in the context of a + block-level HTML element, eg. a paragraph of text). This + can be changed by adding an <code>encoding</code> + attribute, which will remain in effect until the next + <code>encoding</code> attribute is encountered or the + element ends, whichever comes first. Note that the + <code>encoding</code> attribute must <em>precede</em> the + corresponding <code>var</code> attribute to be effective, + and that only special characters as defined in the + ISO-8859-1 character encoding will be encoded. This + encoding process may not have the desired result if a + different character encoding is in use. Apache 1.3.12 and + above; previous versions do no encoding.</dd> + </dl> + </dd> + + <dt><strong>exec</strong></dt> + + <dd> + The exec command executes a given shell command or CGI + script. The IncludesNOEXEC <a + href="core.html#options">Option</a> disables this command + completely. The valid attributes are: + + <dl> + <dt><strong>cgi</strong></dt> + + <dd> + The value specifies a (%-encoded) URL relative path to + the CGI script. If the path does not begin with a (/), + then it is taken to be relative to the current + document. The document referenced by this path is + invoked as a CGI script, even if the server would not + normally recognize it as such. However, the directory + containing the script must be enabled for CGI scripts + (with <a + href="mod_alias.html#scriptalias">ScriptAlias</a> or + the ExecCGI <a href="core.html#options">Option</a>). + + <p>The CGI script is given the PATH_INFO and query + string (QUERY_STRING) of the original request from the + client; these cannot be specified in the URL path. The + include variables will be available to the script in + addition to the standard <a href="mod_cgi.html">CGI</a> + environment.</p> + + <p>For example:</p> + + <code><!--#exec cgi="/cgi-bin/example.cgi" --></code> + + <p>If the script returns a Location: header instead of + output, then this will be translated into an HTML + anchor.</p> + + <p>The <code><a href="#includevirtual">include + virtual</a></code> element should be + used in preference to <code>exec cgi</code>. In particular, + if you need to pass additional arguments to a CGI program, + using the query string, this cannot be done with <code>exec + cgi</code>, but can be done with <code>include + virtual</code>, as shown here:</p> + + <code><!--#include virtual="/cgi-bin/example.cgi?argument=value" --></code> + </dd> + + <dt><strong>cmd</strong></dt> + + <dd> + <p>The server will execute the given string using + <code>/bin/sh</code>. The <a + href="#includevars">include variables</a> are available + to the command, in addition to the usual set of CGI + variables.</p> + + <p>The use of <code><a href="#includevirtual">#include + virtual</a></code> is almost always + prefered to using either <code>#exec cgi</code> or <code>#exec + cmd</code>. The former (<code>#include virtual</code>) used the + standard Apache sub-request mechanism to include files or + scripts. It is much better tested and maintained.</p> + + <p>In addition, on some platforms, like Win32, and on unix + when using suexec, you cannot pass arguments to a command in + an <code>exec</code> directive, or otherwise include spaces in + the command. Thus, while the following will work under a + non-suexec configuration on unix, it will not produce the + desired result under Win32, or when running suexec:</p> + + <code><!--#exec cmd="perl /path/to/perlscript arg1 arg2" --></code> + + </dd> + </dl> + </dd> + + <dt><strong>fsize</strong></dt> + + <dd> + This command prints the size of the specified file, subject + to the <code>sizefmt</code> format specification. + Attributes: + + <dl> + <dt><strong>file</strong></dt> + + <dd>The value is a path relative to the directory + containing the current document being parsed.</dd> + + <dt><strong>virtual</strong></dt> + + <dd>The value is a (%-encoded) URL-path relative to the + current document being parsed. If it does not begin with + a slash (/) then it is taken to be relative to the + current document.</dd> + </dl> + </dd> + + <dt><strong>flastmod</strong></dt> + + <dd>This command prints the last modification date of the + specified file, subject to the <code>timefmt</code> format + specification. The attributes are the same as for the + <code>fsize</code> command.</dd> + + <dt><strong>include</strong></dt> + + <dd> + This command inserts the text of another document or file + into the parsed file. Any included file is subject to the + usual access control. If the directory containing the + parsed file has the <a href="core.html#options">Option</a> + IncludesNOEXEC set, and the including the document would + cause a program to be executed, then it will not be + included; this prevents the execution of CGI scripts. + Otherwise CGI scripts are invoked as normal using the + complete URL given in the command, including any query + string. + + <p>An attribute defines the location of the document; the + inclusion is done for each attribute given to the include + command. The valid attributes are:</p> + + <dl> + <dt><strong>file</strong></dt> + + <dd>The value is a path relative to the directory + containing the current document being parsed. It cannot + contain <code>../</code>, nor can it be an absolute path. + Therefore, you cannot include files that are outside of the + document root, or above the current document in the directory + structure. + The <code>virtual</code> attribute should always be used + in preference to this one.</dd> + + <dt><strong><a name="includevirtual">virtual</a></strong></dt> + + <dd> + <p>The value is a (%-encoded) URL relative to the + current document being parsed. The URL cannot contain a + scheme or hostname, only a path and an optional query + string. If it does not begin with a slash (/) then it is + taken to be relative to the current document.</p> + + <p>A URL is constructed from the attribute, and the output the + server would return if the URL were accessed by the client + is included in the parsed output. Thus included files can + be nested.</p> + + <p>If the specified URL is a CGI program, the program will + be executed and its output inserted in place of the directive + in the parsed file. You may include a query string in a CGI + url:</p> + + <code><!--#include virtual="/cgi-bin/example.cgi?argument=value" --></code> + + <p><code>include virtual</code> should be used in preference + to <code>exec cgi</code> to include the output of CGI + programs into an HTML document.</p> + </dd> + </dl> + </dd> + + <dt><strong>printenv</strong></dt> + + <dd> + <p>This prints out a listing of all existing variables and + their values. Starting with Apache 1.3.12, special characters + are entity encoded (see the <a + href="#echo"><code>echo</code></a> element for details) + before being output. There are no attributes.</p> + + <p>For example:</p> + + <p><code><!--#printenv --></code></p> + + <p>The <strong>printenv</strong> element is available only in + Apache 1.2 and above.</p> + </dd> + <dt><strong>set</strong></dt> + + <dd> + This sets the value of a variable. Attributes: + + <dl> + <dt><strong>var</strong></dt> + + <dd>The name of the variable to set.</dd> + + <dt><strong>value</strong></dt> + + <dd>The value to give a variable.</dd> + </dl> + <p> + For example: <code><!--#set var="category" value="help" + --></code></p> + + <p>The <strong>set</strong> element is available only in + Apache 1.2 and above.</p> + </dd> + </dl> +</section> + +<section id="includevars"> + <title>Include Variables</title> + + In addition to the variables in the standard CGI environment, + these are available for the <code>echo</code> command, for + <code>if</code> and <code>elif</code>, and to any program + invoked by the document. + + <dl> + <dt>DATE_GMT</dt> + + <dd>The current date in Greenwich Mean Time.</dd> + + <dt>DATE_LOCAL</dt> + + <dd>The current date in the local time zone.</dd> + + <dt>DOCUMENT_NAME</dt> + + <dd>The filename (excluding directories) of the document + requested by the user.</dd> + + <dt>DOCUMENT_URI</dt> + + <dd>The (%-decoded) URL path of the document requested by the + user. Note that in the case of nested include files, this is + <em>not</em> then URL for the current document.</dd> + + <dt>LAST_MODIFIED</dt> + + <dd>The last modification date of the document requested by + the user.</dd> + </dl> +</section> + +<section> + <title>Variable Substitution</title> + + <p>Variable substitution is done within quoted strings in most + cases where they may reasonably occur as an argument to an SSI + directive. This includes the <samp>config</samp>, + <samp>exec</samp>, <samp>flastmod</samp>, <samp>fsize</samp>, + <samp>include</samp>, and <samp>set</samp> directives, as well + as the arguments to conditional operators. You can insert a + literal dollar sign into the string using backslash + quoting:</p> +<pre> + <!--#if expr="$a = \$test" --> +</pre> + + <p>If a variable reference needs to be substituted in the + middle of a character sequence that might otherwise be + considered a valid identifier in its own right, it can be + disambiguated by enclosing the reference in braces, + <em>a la</em> shell substitution:</p> +<pre> + <!--#set var="Zed" value="${REMOTE_HOST}_${REQUEST_METHOD}" --> +</pre> + + <p>This will result in the <samp>Zed</samp> variable being set + to "<samp>X_Y</samp>" if <samp>REMOTE_HOST</samp> is + "<samp>X</samp>" and <samp>REQUEST_METHOD</samp> is + "<samp>Y</samp>".</p> + + <p>EXAMPLE: the below example will print "in foo" if the + DOCUMENT_URI is /foo/file.html, "in bar" if it is + /bar/file.html and "in neither" otherwise:</p> +<pre> + <!--#if expr="\"$DOCUMENT_URI\" = \"/foo/file.html\"" --> + in foo + <!--#elif expr="\"$DOCUMENT_URI\" = \"/bar/file.html\"" --> + in bar + <!--#else --> + in neither + <!--#endif --> +</pre> +</section> + +<section> + <title id="flowctrl">Flow Control Elements</title> + + These are available in Apache 1.2 and above. The basic flow + control elements are: +<pre> + <!--#if expr="<em>test_condition</em>" --> + <!--#elif expr="<em>test_condition</em>" --> + <!--#else --> + <!--#endif --> +</pre> + + <p>The <strong><code>if</code></strong> element works like an + if statement in a programming language. The test condition is + evaluated and if the result is true, then the text until the + next <strong><code>elif</code></strong>, + <strong><code>else</code></strong>. or + <strong><code>endif</code></strong> element is included in the + output stream.</p> + + <p>The <strong><code>elif</code></strong> or + <strong><code>else</code></strong> statements are be used the + put text into the output stream if the original test_condition + was false. These elements are optional.</p> + + <p>The <strong><code>endif</code></strong> element ends the + <strong><code>if</code></strong> element and is required.</p> + + <p><em>test_condition</em> is one of the following:</p> + + <dl> + <dt><em>string</em></dt> + + <dd>true if <em>string</em> is not empty</dd> + + <dt><em>string1</em> = <em>string2</em><br /> + <em>string1</em> != <em>string2</em><br /> + <em>string1</em> < <em>string2</em><br /> + <em>string1</em> <= <em>string2</em><br /> + <em>string1</em> > <em>string2</em><br /> + <em>string1</em> >= <em>string2</em></dt> + + <dd>Compare string1 with string 2. If string2 has the form + <em>/string/</em> then it is compared as a regular + expression. Regular expressions have the same syntax as those + found in the Unix <samp>egrep</samp> command.</dd> + + <dt>( <em>test_condition</em> )</dt> + + <dd>true if <em>test_condition</em> is true</dd> + + <dt>! <em>test_condition</em></dt> + + <dd>true if <em>test_condition</em> is false</dd> + + <dt><em>test_condition1</em> && + <em>test_condition2</em></dt> + + <dd>true if both <em>test_condition1</em> and + <em>test_condition2</em> are true</dd> + + <dt><em>test_condition1</em> || <em>test_condition2</em></dt> + + <dd>true if either <em>test_condition1</em> or + <em>test_condition2</em> is true</dd> + </dl> + + <p>"<em>=</em>" and "<em>!=</em>" bind more tightly than + "<em>&&</em>" and "<em>||</em>". "<em>!</em>" binds + most tightly. Thus, the following are equivalent:</p> +<pre> + <!--#if expr="$a = test1 && $b = test2" --> + <!--#if expr="($a = test1) && ($b = test2)" --> +</pre> + + <p>Anything that's not recognized as a variable or an operator + is treated as a string. Strings can also be quoted: + <em>'string'</em>. Unquoted strings can't contain whitespace + (blanks and tabs) because it is used to separate tokens such as + variables. If multiple strings are found in a row, they are + concatenated using blanks. So,</p> +<pre> + <em>string1 string2</em> results in <em>string1 string2</em> + <em>'string1 string2'</em> results in <em>string1 string2</em> +</pre> + +</section> + +<section> + <title>Using Server Side Includes for ErrorDocuments</title> + + There is <a href="../misc/custom_errordocs.html">a document</a> + which describes how to use the features of mod_include to offer + internationalized customized server error documents. + + <h2>PATH_INFO with Server Side Includes</h2> + + <p>Files processed for server-side includes no longer accept + requests with PATH_INFO (trailing pathname information) by + default. You can use the <a + href="core.html#AcceptPathInfo">AcceptPathInfo</a> directive to + configure the server to accept requests with PATH_INFO.</p> + +</section> + + +<directivesynopsis> +<name>SSIEndTag</name> +<description>Changes the string that mod_include looks for to end an +include command.</description> +<syntax>SSIEndTag <em>tag</em></syntax> +<default>SSIEndTag "-->"</default> +<contextlist><context>server config</context> +<context>virtual host</context></contextlist> +<override>FileInfo</override> +<compatibility>Apache 1.2 and Available in version 2.0.30 and later. +</compatibility> + +<usage> + <p>This directive changes the string that mod_include looks for + to mark the end of a include command.</p> + + <seealso>See also: <directive>SSIStartTag</directive>.</seealso> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>SSIErrorMsg</name> +<description>Changes the error message displayed when there is an error</description> +<syntax>SSIErrorMsg <em>message</em></syntax> +<default>SSIErrorMsg +"[an error occurred while processing this directive]"</default> +<contextlist> +<context>server config</context> +<context>virtual host</context> +<context>directory</context> +<context>.htaccess</context> +</contextlist> +<override></override> +<compatibility>Available in version 2.0.30 and later.</compatibility> + +<usage> + <p>The SSIErrorMsg directive changes the error message displayed + when mod_include encounters an error. For production servers you + may consider changing the default error message to + <code>"<-- Error -->"</code> so that the message + is not presented to the user. + </p> + <p>This directive has the same effect as the <code><--#config + errmsg=<em>message</em> --></code> element.</p> + +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>SSIStartTag</name> +<description></description> +<syntax>Changes the string that mod_include looks for to start an +include element</syntax> +<default>SSIStartTag "<--!"</default> +<contextlist> +<context>server config</context> +<context>virtual host</context> +</contextlist> +<override></override> +<compatibility>Available in version 2.0.30 and later.</compatibility> + +<usage> + + <p>This directive changes the string that mod_include looks for + to mark an include element to process.</p> + + <p>You may want to use this option if have 2 servers parsing the + output of a file each processing different commands (possibly at + different times).</p> + + <seealso>See also: <directive>SSIEndTag</directive></seealso> + +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>SSITimeFormat</name> +<description>Configures the format in which date strings are +displayed</description> +<syntax>SSITimeFormat <em>formatstring</em></syntax> +<default>SSITimeFormat "%A, %d-%b-%Y %H:%M:%S %Z"</default> +<contextlist> +<context>server config</context> +<context>virtual host</context> +<context>directory</context> +<context>.htaccess</context> +</contextlist> +<override></override> +<compatibility>Available in version 2.0.30 and later.</compatibility> + +<usage> +<p>This directive changes the format in which date strings are displayed + when echoing DATE environment variables. The <em>formatstring</em> + is as in strftime(3) from the C standard library.</p> + + <p>This directive has the same effect as the <code><--#config + timefmt=<em>formatstring</em> --></code> element.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>XBitHack</name> +<syntax>XBitHack on|off|full</syntax> +<default>XBitHack off</default> +<contextlist> +<context>server config</context> +<context>virtual host</context> +<context>directory</context> +<context>.htaccess</context> +</contextlist> +<override>Options</override> +<compatibility></compatibility> +<description>Parse SSI directives in files with the execute +bit set</description> + +<usage> + <p>The XBitHack directives controls the parsing of ordinary + html documents. This directive only affects files associated + with the MIME type <code>text/html</code>. XBitHack can take on + the following values:</p> + + <dl> + <dt>off</dt> + + <dd>No special treatment of executable files.</dd> + + <dt>on</dt> + + <dd>Any text/html file that has the user-execute bit set will + be treated as a server-parsed html document.</dd> + + <dt>full</dt> + + <dd> + As for <code>on</code> but also test the group-execute bit. + If it is set, then set the Last-modified date of the + returned file to be the last modified time of the file. If + it is not set, then no last-modified date is sent. Setting + this bit allows clients and proxies to cache the result of + the request. + + <p><strong>Note:</strong> you would not want to use the full + option, unless you assure the group-execute bit is unset for + every SSI script which might <code>#include</code> a CGI + or otherwise produces different output on each hit (or could + potentially change on subsequent requests).</p> + </dd> + </dl> + + </usage> +</directivesynopsis> + +</modulesynopsis> + diff --git a/docs/manual/mod/mod_info.xml b/docs/manual/mod/mod_info.xml new file mode 100644 index 0000000000..c086a891f0 --- /dev/null +++ b/docs/manual/mod/mod_info.xml @@ -0,0 +1,79 @@ +<?xml version="1.0"?> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>mod_info</name> +<status>Extension</status> +<description>This module provides a comprehensive overview of the server +configuration including all installed modules and directives in the +configuration files.</description> +<identifier>info_module</identifier> +<sourcefile>mod_info.c</sourcefile> +<compatibility>Available in Apache 1.1 and later</compatibility> + + +<summary> + + <h2>Using mod_info</h2> + + <p>To configure it, add the following to your + <code>httpd.conf</code> file.</p> + +<example> +<Location /server-info><br /> +SetHandler server-info<br /> +</Location><br /> +</example> + + You may wish to add a + <directive module="core"><Limit></directive> + clause inside the + <directive module="core"><location></directive> + directive to limit access to your server configuration + information. + + <p>Once configured, the server information is obtained by + accessing <code>http://your.host.dom/server-info</code></p> + + <note> + Note that the configuration files are read by the + module at run-time, and therefore the display may + <em>not</em> reflect the running server's active + configuration if the files have been changed since the server + was last reloaded. Also, the configuration files must be + readable by the user as which the server is running (see the + <directive module="mpm_common">User</directive> directive), or + else the directive settings will not be listed. + + <p>It should also be noted that if + <module>mod_info</module> is compiled into the server, its + handler capability is available in <em>all</em> configuration + files, including <em>per</em>-directory files (<em>e.g.</em>, + <code>.htaccess</code>). This may have security-related + ramifications for your site.</p> + </note> +</summary> + +<directivesynopsis> +<name>AddModuleInfo</name> +<description>Allows additional information to be added to the module +information displayed by the server-info handler</description> +<syntax>AddModuleInfo <em>module-name string</em></syntax> +<default><em>none</em></default> +<contextlist><context>server config</context> <context>virtual +host</context></contextlist> +<compatibility>Apache 1.3 and above</compatibility> + +<usage> + <p>This allows the content of <em>string</em> to be shown as + HTML interpreted, <strong>Additional Information</strong> for + the module <em>module-name</em>. Example:</p> + +<example> +AddModuleInfo mod_auth.c 'See <A HREF="http://www.apache.org/docs/mod/mod_auth.html">http://www.apache.org/docs/mod/mod_auth.html</A>' +</example> +</usage> + +</directivesynopsis> +</modulesynopsis> + diff --git a/docs/manual/mod/mod_isapi.xml b/docs/manual/mod/mod_isapi.xml new file mode 100644 index 0000000000..c64cbd0b18 --- /dev/null +++ b/docs/manual/mod/mod_isapi.xml @@ -0,0 +1,271 @@ +<?xml version="1.0"?> +<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd"> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>mod_isapi</name> +<description>ISAPI Extensions within Apache for Windows</description> +<status>Base</status> +<sourcefile>mod_isapi.c</sourcefile> +<identifier>isapi_module</identifier> +<compatibility>Win32 only</compatibility> + +<summary> + <p>This module implements the Internet Server extension API. It + allows Internet Server extensions (<em>e.g.</em> ISAPI .dll + modules) to be served by Apache for Windows, subject to the + noted restrictions.</p> + + <p>ISAPI extension modules (.dll files) are written by third + parties. The Apache Group does not author these modules, so we + provide no support for them. Please contact the ISAPI's author + directly if you are experiencing problems running their ISAPI + extention. <strong>Please <em>do not</em> post such problems to + Apache's lists or bug reporting pages.</strong></p> +</summary> + +<section><title>Usage</title> <p>In the server configuration file, use +the <directive module="mod_mime">AddHandler</directive> directive to +associate ISAPI files with the <code>isapi-isa</code> handler, and map +it to the with their file extensions. To enable any .dll file to be +processed as an ISAPI extention, edit the httpd.conf file and add the +following line:</p> +<example> + AddHandler isapi-isa .dll +</example> + + <p>There is no capability within the Apache server to leave a + requested module loaded. However, you may preload and keep a + specific module loaded by using the following syntax in your + httpd.conf:</p> +<example> + ISAPICacheFile c:/WebWork/Scripts/ISAPI/mytest.dll +</example> + + <p>Whether or not you have preloaded an ISAPI extension, all + ISAPI extensions are governed by the same permissions and + restrictions as CGI scripts. That is, <code>Options + ExecCGI</code> must be set for the directory that contains the + ISAPI .dll file.</p> + + <p>Review the <a href="#notes">Additional Notes</a> and the <a + href="#journal">Programmer's Journal</a> for additional details + and clarification of the specific ISAPI support offered by + mod_isapi.</p> +</section> + +<section id="notes"><title>Additional Notes</title> + + <p>Apache's ISAPI implementation conforms to all of the ISAPI + 2.0 specification, except for some "Microsoft-specific" + extensions dealing with asynchronous I/O. Apache's I/O model + does not allow asynchronous reading and writing in a manner + that the ISAPI could access. If an ISA tries to access + unsupported features, including async I/O, a message is placed + in the error log to help with debugging. Since these messages + can become a flood, the directive <code>ISAPILogNotSupported + Off</code> exists to quiet this noise.</p> + + <p>Some servers, like Microsoft IIS, load the ISAPI extension + into the server and keep it loaded until memory usage is too + high, or unless configuration options are specified. Apache + currently loads and unloads the ISAPI extension each time it is + requested, unless the ISAPICacheFile directive is specified. + This is inefficient, but Apache's memory model makes this the + most effective method. Many ISAPI modules are subtly + incompatible with the Apache server, and unloading these + modules helps to ensure the stability of the server.</p> + + <p>Also, remember that while Apache supports ISAPI Extensions, + it <strong>does not support ISAPI Filters.</strong> Support for + filters may be added at a later date, but no support is planned + at this time.</p> +</section> + +<section id="journal"><title>Programmer's Journal</title> + + <p>If you are programming Apache 2.0 <module>mod_isapi</module> + modules, you must limit your calls to ServerSupportFunction to the + following directives:</p> + + <dl> + <dt>HSE_REQ_SEND_URL_REDIRECT_RESP</dt> + + <dd>Redirect the user to another location.<br /> + This must be a fully qualified URL (e.g. + http://server/location).</dd> + + <dt>HSE_REQ_SEND_URL</dt> + + <dd>Redirect the user to another location.<br /> + This cannot be a fully qualified URL, you are not allowed to + pass the protocol or a server name (e.g. simply + /location).<br /> + This redirection is handled by the server, not the + browser.<br /> + <strong>Warning:</strong> in their recent documentation, + Microsoft appears to have abandoned the distinction between + the two HSE_REQ_SEND_URL functions. Apache continues to treat + them as two distinct functions with different requirements + and behaviors.</dd> + + <dt>HSE_REQ_SEND_RESPONSE_HEADER</dt> + + <dd>Apache accepts a response body following the header if it + follows the blank line (two consecutive newlines) in the + headers string argument. This body cannot contain NULLs, + since the headers argument is NULL terminated.</dd> + + <dt>HSE_REQ_DONE_WITH_SESSION</dt> + + <dd>Apache considers this a no-op, since the session will be + finished when the ISAPI returns from processing.</dd> + + <dt>HSE_REQ_MAP_URL_TO_PATH</dt> + + <dd>Apache will translate a virtual name to a physical + name.</dd> + + <dt>HSE_APPEND_LOG_PARAMETER</dt> + + <dd> + This logged message may be captured in any of the following + logs: + + <ul> + <li>in the \"%{isapi-parameter}n\" component in a + CustomLog directive</li> + + <li>in the %q log component with the + ISAPIAppendLogToQuery On directive</li> + + <li>in the error log with the ISAPIAppendLogToErrors On + directive</li> + </ul> + The first option, the %{isapi-parameter}n component, is + always available and prefered. + </dd> + + <dt>HSE_REQ_IS_KEEP_CONN</dt> + + <dd>Will return the negotiated Keep-Alive status.</dd> + + <dt>HSE_REQ_SEND_RESPONSE_HEADER_EX</dt> + + <dd>Will behave as documented, although the fKeepConn flag is + ignored.</dd> + + <dt>HSE_REQ_IS_CONNECTED</dt> + + <dd>Will report false if the request has been aborted.</dd> + </dl> + + <p>Apache returns FALSE to any unsupported call to + ServerSupportFunction, and sets the GetLastError value to + ERROR_INVALID_PARAMETER.</p> + + <p>ReadClient retrieves the request body exceeding the initial + buffer (defined by ISAPIReadAheadBuffer). Based on the + ISAPIReadAheadBuffer setting (number of bytes to buffer prior + to calling the ISAPI handler) shorter requests are sent + complete to the extension when it is invoked. If the request is + longer, the ISAPI extension must use ReadClient to retrieve the + remaining request body.</p> + + <p>WriteClient is supported, but only with the HSE_IO_SYNC flag + or no option flag (value of 0). Any other WriteClient request + will be rejected with a return value of FALSE, and a + GetLastError value of ERROR_INVALID_PARAMETER.</p> + + <p>GetServerVariable is supported, although extended server + variables do not exist (as defined by other servers.) All the + usual Apache CGI environment variables are available from + GetServerVariable, as well as the ALL_HTTP and ALL_RAW + values.</p> + + <p>Apache 2.0 <module>mod_isapi</module> supports additional + features introduced in later versions of the ISAPI specification, + as well as limited emulation of async I/O and the TransmitFile + semantics. Apache also supports preloading ISAPI .dlls for + performance, neither of which were not available under Apache 1.3 + mod_isapi.</p> +</section> + +<directivesynopsis> +<name>ISAPIFileChache</name> +<description>ISAPI .dll files to be loaded at startup</description> +<syntax>ISAPIFileCache <em>file-path</em> [<em>file-path</em>] ...</syntax> +<contextlist><context>server config</context></contextlist> + +<usage> + <p>Specifies a space-separated list of file names to be loaded + when the Apache server is launched, and remain loaded until the + server is shut down. This directive may be repeated for every + ISAPI .dll file desired. The full path name of each file should + be specified.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>ISAPIReadAheadBuffer</name> +<description>Size of the Read Ahead Buffer sent to ISAPI +extensions</description> +<syntax>ISAPIReadAheadBuffer <em>size</em></syntax> +<default>ISAPIReadAheadBuffer 49152</default> +<contextlist><context>server config</context></contextlist> + +<usage> + <p>Defines the maximum size of the Read Ahead Buffer sent to + ISAPI extensions when they are initially invoked. All remaining + data must be retrieved using the ReadClient callback; some + ISAPI extensions may not support the ReadClient function. Refer + questions to the ISAPI extension's author.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>ISAPILogNotSupported</name> +<description>Log unsupported feature requests from ISAPI +extensions</description> +<syntax>ISAPILogNotSupported on|off</syntax> +<default>ISAPILogNotSupported on</default> +<contextlist><context>server config</context></contextlist> + +<usage> + <p>Logs all requests for unsupported features from ISAPI + extensions in the server error log. While this should be turned + off once all desired ISAPI modules are functioning, it defaults + to on to help administrators track down problems.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>ISAPIAppendLogToErrors</name> +<description>Record HSE_APPEND_LOG_PARAMETER requests from ISAPI +extensions to the error log</description> +<syntax>ISAPIAppendLogToErrors on|off</syntax> +<default>ISAPIAppendLogToErrors off</default> +<contextlist><context>server config</context></contextlist> + +<usage> + <p>Record HSE_APPEND_LOG_PARAMETER requests from ISAPI + extensions to the server error log.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>ISAPIAppendLogToQuery</name> +<description>Record HSE_APPEND_LOG_PARAMETER requests from ISAPI +extensions to the query field</description> +<syntax>ISAPIAppendLogToQuery on|off</syntax> +<default>ISAPIAppendLogToQuery off</default> +<contextlist><context>server config</context></contextlist> + +<usage> + <p>Record HSE_APPEND_LOG_PARAMETER requests from ISAPI + extensions to the query field (appended to the CustomLog %q + component).</p> +</usage> +</directivesynopsis> + +</modulesynopsis>
\ No newline at end of file diff --git a/docs/manual/mod/mod_log_config.xml b/docs/manual/mod/mod_log_config.xml new file mode 100644 index 0000000000..b3c3809a1a --- /dev/null +++ b/docs/manual/mod/mod_log_config.xml @@ -0,0 +1,389 @@ +<?xml version="1.0"?> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>mod_log_config</name> +<status>Base</status> +<identifier>log_config_module</identifier> +<compatibility></compatibility> + +<description>This module provides for logging of the requests +made to the server, using the Common Log Format or a +user-specified format.</description> + +<summary> + + <p>This module provides for flexible logging of client + requests. Logs are written in a customizable format, and may be + written directly to a file, or to an external program. + Conditional logging is provided so that individual requests may + be included or excluded from the logs based on characteristics + of the request.</p> + + <p>Three directives are provided by this module: + <code>TransferLog</code> to create a log file, + <code>LogFormat</code> to set a custom format, and + <code>CustomLog</code> to define a log file and format in one + step. The <code>TransferLog</code> and <code>CustomLog</code> + directives can be used multiple times in each server to cause + each request to be logged to multiple files.</p> + +<seealso><strong>See also</strong>: +<a href="../logs.html">Apache Log Files</a>.</seealso> + +<section> +<title>Custom Log Formats</title> + + <p>The format argument to the <code>LogFormat</code> and + <code>CustomLog</code> directives is a string. This string is + logged to the log file for each request. It can contain literal + characters copied into the log files and the c-type control + characters "\n" and "\t" to represent new-lines and tabs. + Literal quotes and back-slashes should be escaped with + back-slashes.</p> + + <p>The characteristics of the request itself are logged by + placing "%" directives in the format string, which are replaced + in the log file by the values as follows:</p> + +<table> + +<tr><td>%...a:</td> +<td>Remote IP-address</td></tr> + +<tr><td>%...A:</td> +<td>Local IP-address</td></tr> + +<tr><td>%...B:</td> +<td>Bytes sent, excluding HTTP headers.</td></tr> + +<tr><td>%...b:</td> +<td>Bytes sent, excluding HTTP headers. In CLF format +i.e. a '-' rather than a 0 when no bytes are sent.</td></tr> + +<tr><td>%...{Foobar}C:</td> +<td>The contents of cookie "Foobar" in the request sent to the server.</td></tr> + +<tr><td>%...D:</td> +<td>The time taken to serve the request, in microseconds.</td></tr> + +<tr><td>%...{FOOBAR}e:</td> +<td>The contents of the environment variable FOOBAR</td></tr> + +<tr><td>%...f:</td> +<td>Filename</td></tr> + +<tr><td>%...h:</td> +<td>Remote host</td></tr> + +<tr><td>%...H</td> +<td>The request protocol</td></tr> + +<tr><td>%...{Foobar}i:</td> +<td>The contents of Foobar: header line(s) in the request +sent to the server.</td></tr> + +<tr><td>%...l:</td> +<td>Remote logname (from identd, if supplied)</td></tr> + +<tr><td>%...m:</td> +<td>The request method</td></tr> + +<tr><td>%...{Foobar}n:</td> +<td>The contents of note "Foobar" from another module.</td></tr> + +<tr><td>%...{Foobar}o:</td> +<td>The contents of Foobar: header line(s) in the reply.</td></tr> + +<tr><td>%...p:</td> +<td>The canonical Port of the server serving the request</td></tr> + +<tr><td>%...P:</td> +<td>The process ID of the child that serviced the request.</td></tr> + +<tr><td>%...q:</td> +<td>The query string (prepended with a ? if a query string exists, +otherwise an empty string)</td></tr> + +<tr><td>%...r:</td> +<td>First line of request</td></tr> + +<tr><td>%...s:</td> +<td>Status. For requests that got internally redirected, this is +the status of the *original* request --- %...>s for the last.</td></tr> + +<tr><td>%...t:</td> +<td>Time, in common log format time format (standard english format)</td></tr> + +<tr><td>%...{format}t:</td> +<td>The time, in the form given by format, which should +be in strftime(3) format. (potentially localized)</td></tr> + +<tr><td>%...T:</td> +<td>The time taken to serve the request, in seconds.</td></tr> + +<tr><td>%...u:</td> +<td>Remote user (from auth; may be bogus if return status (%s) is 401)</td></tr> + +<tr><td>%...U:</td> +<td>The URL path requested, not including any query string.</td></tr> + +<tr><td>%...v:</td> +<td>The canonical ServerName of the server serving the request.</td></tr> + +<tr><td>%...V:</td> +<td>The server name according to the UseCanonicalName setting.</td></tr> + +<tr><td>%...X:</td> +<td>Connection status when response is completed. +<example> +'X' = connection aborted before the response completed.<br /> +'+' = connection may be kept alive after the response is sent.<br /> +'-' = connection will be closed after the response is sent. +</example> +(This directive was %...c in late versions of Apache 1.3, but +this conflicted with the historical ssl %...{var}c syntax.)</td></tr> + +</table> + + <p>The "..." can be nothing at all (<em>e.g.</em>, <code>"%h %u + %r %s %b"</code>), or it can indicate conditions for inclusion + of the item (which will cause it to be replaced with "-" if the + condition is not met). The forms of condition are a list of + HTTP status codes, which may or may not be preceded by "!". + Thus, "%400,501{User-agent}i" logs User-agent: on 400 errors + and 501 errors (Bad Request, Not Implemented) only; + "%!200,304,302{Referer}i" logs Referer: on all requests which + did <strong>not</strong> return some sort of normal status.</p> + + <p>Note that there is no escaping performed on the strings from + %...r, %...i and %...o. This is mainly to comply with the + requirements of the Common Log Format. This implies that + clients can insert control characters into the log, so care + should be taken when dealing with raw log files.</p> + + <p>Some commonly used log format strings are:</p> + + <dl> + <dt>Common Log Format (CLF)</dt> + + <dd><code>"%h %l %u %t \"%r\" %>s %b"</code></dd> + + <dt>Common Log Format with Virtual Host</dt> + + <dd><code>"%v %h %l %u %t \"%r\" %>s %b"</code></dd> + + <dt>NCSA extended/combined log format</dt> + + <dd><code>"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" + \"%{User-agent}i\""</code></dd> + + <dt>Referer log format</dt> + + <dd><code>"%{Referer}i -> %U"</code></dd> + + <dt>Agent (Browser) log format</dt> + + <dd><code>"%{User-agent}i"</code></dd> + </dl> + + <p>Note that the canonical <a + href="core.html#servername">ServerName</a> and <a + href="mpm_common.html#listen">Listen</a> of the server serving the + request are used for <code>%v</code> and <code>%p</code> + respectively. This happens regardless of the <a + href="core.html#usecanonicalname">UseCanonicalName</a> setting + because otherwise log analysis programs would have to duplicate + the entire vhost matching algorithm in order to decide what + host really served the request.</p> + </section> + + <section> + + <title>Security Considerations</title> + + <p>See the <a + href="../misc/security_tips.html#serverroot">security tips</a> + document for details on why your security could be compromised + if the directory where logfiles are stored is writable by + anyone other than the user that starts the server.</p> + + </section> + +</summary> + +<directivesynopsis> +<name>CookieLog</name> +<description>Sets filename for the logging of cookies</description> +<syntax>CookieLog <em>filename</em></syntax> +<default><i>none</i></default> +<contextlist><context>server config</context><context>virtual +host</context></contextlist> +<compatibility>Only available in Apache 1.2 and above</compatibility> + +<usage> + + <p>The <directive>CookieLog</directive> directive sets the + filename for logging of cookies. The filename is relative to the + <directive module="core">serverroot</directive>. This directive is + included only for compatibility with <module>mod_cookies</module>, + and is deprecated.</p> +</usage> + +</directivesynopsis> + +<directivesynopsis> +<name>CustomLog</name> +<description>Sets filename and format of log file</description> +<syntax>CustomLog + <em>file</em>|<em>pipe</em> <em>format</em>|<em>nickname</em> + [env=[!]<em>environment-variable</em>]</syntax> +<default><i>none</i></default> +<contextlist><context>server config</context><context>virtual +host</context></contextlist> +<compatibility>Nickname only available in Apache 1.3 or later. +Conditional logging available in 1.3.5 or later.</compatibility> + + +<usage> + <p>The <directive>CustomLog</directive> directive is used to + log requests to the server. A log format is specified, and the + logging can optionally be made conditional on request + characteristics using environment variables.</p> + + <p>The first argument, which specifies the location to which + the logs will be written, can take on one of the following two + types of values:</p> + + <dl> + <dt><em>file</em></dt> + + <dd>A filename, relative to the <a + href="core.html#serverroot">ServerRoot</a>.</dd> + + <dt><em>pipe</em></dt> + + <dd>The pipe character "<code>|</code>", followed by the path + to a program to receive the log information on its standard + input. <strong>Security:</strong> if a program is used, then + it will be run under the user who started httpd. This will be + root if the server was started by root; be sure that the + program is secure.</dd> + </dl> + + <p>The second argument specifies what will be written to the + log file. It can specify either a <em>nickname</em> defined by + a previous <a href="#logformat">LogFormat</a> directive, or it + can be an explicit <em>format</em> string as described in the + <a href="#formats">log formats</a> section.</p> + + <p>For example, the following two sets of directives have + exactly the same effect:</p> + +<example> + # CustomLog with format nickname<br /> + LogFormat "%h %l %u %t \"%r\" %>s %b" common<br /> + CustomLog logs/access_log common<br /> +<br /> + # CustomLog with explicit format string<br /> + CustomLog logs/access_log "%h %l %u %t \"%r\" %>s %b"<br /> +</example> + + <p>The third argument is optional and allows the decision on + whether or not to log a particular request to be based on the + presence or absence of a particular variable in the server + environment. If the specified <a href="../env.html">environment + variable</a> is set for the request (or is not set, in the case + of a '<code>env=!<em>name</em></code>' clause), then the + request will be logged.</p> + + <p>Environment variables can be set on a <em>per</em>-request + basis using the <module>mod_setenvif</module> + and/or <module>mod_rewrite</module> modules. For + example, if you don't want to record requests for all GIF + images on your server in a separate logfile but not your main + log, you can use:</p> + +<example> + SetEnvIf Request_URI \.gif$ gif-image<br /> + CustomLog gif-requests.log common env=gif-image<br /> + CustomLog nongif-requests.log common env=!gif-image +</example> +</usage> + +</directivesynopsis> + +<directivesynopsis> +<name>LogFormat</name> +<description>Describes a format for use in a log file</description> +<syntax>LogFormat + <em>format</em>|<em>nickname</em> [<em>nickname</em>]</syntax> +<default><i>none</i></default> +<contextlist><context>server config</context><context>virtual +host</context></contextlist> +<compatibility>Nickname only available in Apache 1.3 or later. +</compatibility> + +<usage> + <p>This directive specifies the format of the access log + file.</p> + + <p>The <directive>LogFormat</directive> directive can take one of two + forms. In the first form, where only one argument is specified, + this directive sets the log format which will be used by logs + specified in subsequent <directive>TransferLog</directive> + directives. The single argument can specify an explicit + <em>format</em> as discussed in <a href="#formats">custom log + formats</a> section above. Alternatively, it can use a + <em>nickname</em> to refer to a log format defined in a + previous <directive>LogFormat</directive> directive as described + below.</p> + + <p>The second form of the <directive>LogFormat</directive> + directive associates an explicit <em>format</em> with a + <em>nickname</em>. This <em>nickname</em> can then be used in + subsequent <directive>LogFormat</directive> or + <directive>CustomLog</directive> directives rather than + repeating the entire format string. A + <directive>LogFormat</directive> + directive which defines a nickname <strong>does nothing + else</strong> -- that is, it <em>only</em> defines the + nickname, it doesn't actually apply the format and make it the + default. Therefore, it will not affect subsequent + <directive>TransferLog</directive> directives.</p> + +</usage> +</directivesynopsis> + +<directivesynopsis> + +<name>TransferLog</name> +<description>Specifly location of a log file</description> +<syntax>TransferLog <em>file</em>|<em>pipe</em></syntax> +<default><i>none</i></default> +<contextlist><context>server config</context><context>virtual +host</context></contextlist> +<compatibility></compatibility> + +<usage> + + <p>This directive has exactly the same arguments and effect as + the <directive>CustomLog</directive> directive, with the + exception that it does not allow the log format to be specified + explicitly or for conditional logging of requests. Instead, the + log format is determined by the most recently specified + specified <directive>LogFormat</directive> directive (which + does not define a nickname). Common Log Format is used if no + other format has been specified.</p> + + <p>Example:</p> +<example> + LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""<br /> + TransferLog logs/access_log +</example> + +</usage> + +</directivesynopsis> + +</modulesynopsis> diff --git a/docs/manual/mod/mod_mime.xml b/docs/manual/mod/mod_mime.xml new file mode 100644 index 0000000000..77bf64b267 --- /dev/null +++ b/docs/manual/mod/mod_mime.xml @@ -0,0 +1,922 @@ +<?xml version="1.0"?> +<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd"> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>mod_mime</name> +<description>This module associates the request filename's extensions + (e.g. .html) with the file's behavior (handlers and filters) + and content (mime-type, language, character set and + encoding.) +</description> +<sourcefile>mod_mime.c</sourcefile> +<identifier>mime_module</identifier> +<status>Base</status> + +<summary> + <p>This module is used to associate various bits of "meta + information" with files by their filename extensions. This + information relates the filename of the document to it's + mime-type, language, character set and encoding. This + information is sent to the browser, and participates in content + negotiation, so the user's preferences are respected when + choosing one of several possible files to serve. See + <module>mod_negotiation</module> for more information + about content negotiation. </p> + + <p>The directives <directive>AddCharset</directive>, + <directive>AddEncoding</directive>, + <directive>AddLanguage</directive> and + <directive>AddType</directive> all used to map file extensions + onto the meta-information for that file. Respectively they set + the character set, content-encoding, content-language, and + MIME-type (content-type) of documents.</p> + + <p>In addition, mod_mime may define the "handler" for a + document, which controls which module or script will serve the + document. With the introduction of "filters" in Apache 2.0, + mod_mime can also define the filters that the the content + should be processed through (e.g. the Includes output filter + for server side scripting) and what filters the client request + and POST content should be processed through (the input + filters.)</p> + + <p>The directives <directive>AddHandler</directive>, + <directive>AddOutputFilter</directive>, and + <directive>AddInputFilter</directive> control the modules + or scripts that serve the document. The + <directive>MultiviewsMatch</directive> directive allows + <directive>mod_negotiation</directive> to consider these + file extensions to included when testing Multiviews matches.</p> + + <p>The directive <directive>TypesConfig</directive> is used + to specify a file which also maps extensions onto MIME types. + Most administrators use the provided mime.types file which + associates common filename extensions with IANA registered + content types. The current list is maintained at + <code>http://www.isi.edu/in-notes/iana/assignments/media-types/media-types</code> + although it may be mirrored elsewhere). This simplifies the + httpd.conf file by providing the majority of media-type + definitions, and they may be overridden by + <directive>AddType</directive> directives as needed.</p> + + <note>Please do not send requests to the Apache httpd Project + to add any new entries in the distributed mime.types file + unless (1) they are already registered with IANA, and (2) they + use widely accepted, non-conflicting filename extensions across + platforms. category/x-subtype requests will be automatically + rejected, as will any new two-letter extensions as they will + likely conflict later with the already crowded language and + character set namespace.</note> + + <p>The core directives <directive + module="core">ForceType</directive> and + <directive>SetHandler</directive> are used to + associate all the files in a given container (<em>e.g.</em>, + <location>, <directory>, or <Files>) with a + particular MIME-type or handler. These settings override any + filename extension mappings defined in mod_mime.</p> + + <p>Note that changing the type or encoding of a file does not + change the value of the <code>Last-Modified</code> header. + Thus, previously cached copies may still be used by a client or + proxy, with the previous headers. If you change the + meta-information (language, content type, character set or + encoding) you may need to 'touch' affected files (updating + their last modified date) to ensure that all visitors are + receive the corrected content headers.</p> +</summary> + + <seealso>See also: <directive + module="mod_mime_magic">MimeMagicFile</directive></seealso> + +<section> +<title id="multipleext">Files with Multiple Extensions</title> + + <p>Files can have more than one extension, and the order of the + extensions is <em>normally</em> irrelevant. For example, if the + file <code>welcome.html.fr</code> maps onto content type + text/html and language French then the file <code>welcome.fr.html</code> + will map onto exactly the same information. If more than one + extension is given which maps onto the same + type of meta-information, then the one to the right will be + used. For example, if ".gif" maps to the MIME-type image/gif + and ".html" maps to the MIME-type text/html, then the file + <code>welcome.gif.html</code> will be associated with the + MIME-type "text/html".</p> + + <p>Care should be taken when a file with multiple extensions + gets associated with both a MIME-type and a handler. This will + usually result in the request being by the module associated + with the handler. For example, if the <code>.imap</code> + extension is mapped to the handler "imap-file" (from mod_imap) + and the <code>.html</code> extension is mapped to the MIME-type + "text/html", then the file <code>world.imap.html</code> will be + associated with both the "imap-file" handler and "text/html" + MIME-type. When it is processed, the "imap-file" handler will + be used, and so it will be treated as a mod_imap imagemap + file.</p> +</section> + +<section><title id="contentencoding">Content encoding</title> + + <p>A file of a particular MIME type can additionally be encoded a + particular way to simplify transmission over the Internet. + While this usually will refer to compression, such as + <samp>gzip</samp>, it can also refer to encryption, such a + <samp>pgp</samp> or to an encoding such as UUencoding, which is + designed for transmitting a binary file in an ASCII (text) + format.</p> + + <p>The MIME RFC puts it this way:</p> + + <note> + The Content-Encoding entity-header field is used as a + modifier to the media-type. When present, its value indicates + what additional content coding has been applied to the + resource, and thus what decoding mechanism must be applied in + order to obtain the media-type referenced by the Content-Type + header field. The Content-Encoding is primarily used to allow + a document to be compressed without losing the identity of + its underlying media type. + </note> + + <p>By using more than one file extension (see <a + href="#multipleext">section above about multiple file + extensions</a>), you can indicate that a file is of a + particular <em>type</em>, and also has a particular + <em>encoding</em>. </p> + + <p>For example, you may have a file which is a Microsoft Word + document, which is pkzipped to reduce its size. If the + <samp>.doc</samp> extension is associated with the Microsoft + Word file type, and the <samp>.zip</samp> extension is + associated with the pkzip file encoding, then the file + <samp>Resume.doc.zip</samp>would be known to be a pkzip'ed Word + document.</p> + + <p>Apache send a <samp>Content-encoding</samp> header with the + resource, in order to tell the client browser about the + encoding method.</p> + + <example>Content-encoding: pkzip</example> + +</section> + +<section> + +<title>Character sets and languages</title> + + <p>In addition to file type and the file encoding, + another important piece of information is what language a + particular document is in, and in what character set the file + should be displayed. For example, the document might be written + in the Vietnamese alphabet, or in Cyrillic, and should be + displayed as such. This information, also, is transmitted in + HTTP headers.</p> + + <p>The character set, language encoding and mime type are all + used in the process of content negotiation (See + <module>mod_negotiation</module>) to determine + which document to give to the client, when there are + alternative documents in more than one character set, language, + encoding or mime type. All filename extensions associations + created with <module>AddCharset</module>, <module>AddEncoding</module>, + <module>AddLanguage</module> and <module>AddType</module> directives + (and extensions listed in the <module>MimeMagicFile</module>) + participate in this select process. Filename extensions that + are only associated using the <module>AddHandler</module>, + <module>AddInputFilter</module> or <module>AddOutputFilter</module> + directives may be included or excluded from matching by using + the <directive>MultiviewsMatch</directive> directive.</p> + +<section> +<title>Charset</title> + + <p>To convey this further information, Apache optionally sends + a <samp>Content-Language</samp> header, to specify the language + that the document is in, and can append additional information + onto the <samp>Content-Type</samp> header to indicate the + particular character set that should be used to correctly + render the information.</p> + +<example> +Content-Language: en, fr<br /> +Content-Type: text/plain; charset=ISO-8859-2 +</example> + + <p>The language specification is the two-letter abbreviation + for the language. The <samp>charset</samp> is the name of the + particular character set which should be used.</p> +</section> +</section> + + +<directivesynopsis> +<name>AddCharset</name> +<syntax>AddCharset <em>charset extension</em> +[<em>extension</em>] ...</syntax> +<default>None</default> +<contextlist> +<context>server config</context> +<context>virtual host</context> +<context>directory</context> +<context>.htaccess</context> +</contextlist> +<override>FileInfo</override> +<compatibility>AddCharset is only available in Apache +1.3.10 and later</compatibility> +<description>Maps the given filename extensions + to the specified content charset</description> + +<usage> + + <p>The AddCharset directive maps the given filename extensions + to the specified content charset. <i>charset</i> is the MIME + charset parameter of filenames containing <i>extension</i>. + This mapping is added to any already in force, overriding any + mappings that already exist for the same <i>extension</i>.</p> + + <p>Example:</p> +<example> + AddLanguage ja .ja<br /> + AddCharset EUC-JP .euc<br /> + AddCharset ISO-2022-JP .jis<br /> + AddCharset SHIFT_JIS .sjis +</example> + + <p>Then the document <code>xxxx.ja.jis</code> will be treated + as being a Japanese document whose charset is ISO-2022-JP (as + will the document <code>xxxx.jis.ja</code>). The AddCharset + directive is useful for both to inform the client about the + character encoding of the document so that the document can be + interpreted and displayed appropriately, and for <a + href="../content-negotiation.html">content negotiation</a>, + where the server returns one from several documents based on + the client's charset preference.</p> + + <p>The <em>extension</em> argument is case-insensitive, and can + be specified with or without a leading dot.</p> + + <seealso><strong>See also</strong>: + <module>mod_negotiation</module></seealso> + +</usage> + +</directivesynopsis> + +<directivesynopsis> +<name>AddEncoding</name> +<syntax>AddEncoding + <em>MIME-enc extension</em> [<em>extension</em>] ...</syntax> +<default>None</default> +<contextlist> +<context>server config</context> +<context>virtual host</context> +<context>directory</context> +<context>.htaccess</context> +<override>FileInfo</override> +</contextlist> +<description>Maps the given filename extensions + to the specified encoding type</description> + +<usage> + + <p>The AddEncoding directive maps the given filename extensions + to the specified encoding type. <em>MIME-enc</em> is the MIME + encoding to use for documents containing the + <em>extension</em>. This mapping is added to any already in + force, overriding any mappings that already exist for the same + <em>extension</em>. Example:</p> + + <example> + AddEncoding x-gzip .gz<br /> + AddEncoding x-compress .Z + </example> + + <p>This will cause filenames containing the .gz extension to be + marked as encoded using the x-gzip encoding, and filenames + containing the .Z extension to be marked as encoded with + x-compress. </p> + + <p>Old clients expect <code>x-gzip</code> and + <code>x-compress</code>, however the standard dictates that + they're equivalent to <code>gzip</code> and + <code>compress</code> respectively. Apache does content + encoding comparisons by ignoring any leading <code>x-</code>. + When responding with an encoding Apache will use whatever form + (<em>i.e.</em>, <code>x-foo</code> or <code>foo</code>) the + client requested. If the client didn't specifically request a + particular form Apache will use the form given by the + <code>AddEncoding</code> directive. To make this long story + short, you should always use <code>x-gzip</code> and + <code>x-compress</code> for these two specific encodings. More + recent encodings, such as <code>deflate</code> should be + specified without the <code>x-</code>.</p> + + <p>The <em>extension</em> argument is case-insensitive, and can + be specified with or without a leading dot.</p> + + <seealso><strong>See also</strong>: <a href="#multipleext">Files with + multiple extensions</a></seealso> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>AddHandler</name> +<syntax>AddHandler + <em>handler-name extension</em> [<em>extension</em>] ...</syntax> +<default>None</default> +<contextlist> +<context>server config</context> +<context>virtual host</context> +<context>directory</context> +<context>.htaccess</context> +</contextlist> +<override>FileInfo</override> +<compatibility></compatibility> +<description>AddHandler maps the filename extensions <em>extension</em> +to the <a href="../handler.html">handler</a> <em>handler-name</em>. +</description> + +<usage> +<p>This mapping is added to any already in + force, overriding any mappings that already exist for the same + <em>extension</em>. For example, to activate CGI scripts with + the file extension "<code>.cgi</code>", you might use:</p> + +<example> + AddHandler cgi-script .cgi +</example> + + <p>Once that has been put into your srm.conf or httpd.conf + file, any file containing the "<code>.cgi</code>" extension + will be treated as a CGI program.</p> + + <p>The <em>extension</em> argument is case-insensitive, and can + be specified with or without a leading dot.</p> + + <seealso><strong>See also</strong>: <a href="#multipleext">Files with + multiple extensions</a></seealso> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>AddInputFilter</name> +<syntax>AddInputFilter + <em>filter</em>[<em>;filter</em>...] extension + [<em>extension</em> ...]</syntax> +<default>None</default> +<contextlist> +<context>server config</context> +<context>virtual host</context> +<context>directory</context> +<context>.htaccess</context> +</contextlist> +<compatibility>AddInputFilter + is only available in Apache 2.0.26 and later.</compatibility> +<description>Maps the filename extensions + <em>extension</em> to the filter or filters which will process + client requests and POST input when they are received by the + server.</description> + +<usage> + + <p>AddInputFilter maps the filename extensions + <em>extension</em> to the filter or filters which will process + client requests and POST input when they are received by the + server. This is in addition to any filters defined elsewhere, + including the <a + href="core.html#setinputfilter">SetInputFilter</a> directive. + This mapping is merged over any already in force, overriding + any mappings that already exist for the same + <em>extension</em>.</p> + + <p>If more than one filter is specified, they must be separated + by semicolons in the order in which they should process the + content. Both the filter and <em>extension</em> arguments are + case-insensitive, and the extension may be specified with or + without a leading dot.</p> + + <seealso>See also the <a href="../filter.html">Filters</a> + documentation.</seealso> +</usage> + +</directivesynopsis> + + +<directivesynopsis> +<name>AddLanguage</name> +<syntax>AddLanguage + <em>MIME-lang extension</em> [<em>extension</em>] ...</syntax> +<default>None</default> +<contextlist> +<context>server config</context> +<context>virtual host</context> +<context>directory</context> +<context>.htaccess</context> +</contextlist> +<override>FileInfo</override> +<description>maps the given filename extension +to the specified content language.</description> + +<usage> + + <p>The AddLanguage directive maps the given filename extension + to the specified content language. <em>MIME-lang</em> is the + MIME language of filenames containing <em>extension</em>. This + mapping is added to any already in force, overriding any + mappings that already exist for the same + <em>extension</em>.</p> + + <p>Example:</p> + + <example> + AddEncoding x-compress .Z<br /> + AddLanguage en .en<br /> + AddLanguage fr .fr + </example> + + <p>Then the document <code>xxxx.en.Z</code> will be treated as + being a compressed English document (as will the document + <code>xxxx.Z.en</code>). Although the content language is + reported to the client, the browser is unlikely to use this + information. The AddLanguage directive is more useful for <a + href="../content-negotiation.html">content negotiation</a>, + where the server returns one from several documents based on + the client's language preference.</p> + + <p>If multiple language assignments are made for the same + extension, the last one encountered is the one that is used. + That is, for the case of:</p> + +<example> + AddLanguage en .en<br /> + AddLanguage en-uk .en<br /> + AddLanguage en-us .en +</example> + + <p>documents with the extension "<code>.en</code>" would be + treated as being "<code>en-us</code>".</p> + + <p>The <em>extension</em> argument is case-insensitive, and can + be specified with or without a leading dot.</p> + + <seealso><strong>See also</strong>: <a href="#multipleext">Files with + multiple extensions</a>, <module>mod_negotiation</module></seealso> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>AddOutputFilter</name> +<syntax>AddOutputFilter + <em>filter</em>[<em>;filter</em>...] extension + [<em>extension</em> ...]</syntax> +<default>None</default> +<contextlist> +<context>server config</context> +<context>virtual host</context> +<context>directory</context> +<context>.htaccess</context> +</contextlist> +<override></override> +<compatibility>AddOutputFilter + is only available in Apache 2.0.26 and later.</compatibility> +<description>maps the filename +extensions <em>extension</em> to the filters which will process +responses from the server before they are sent to the +client.</description> + +<usage> + + <p>The <directive>AddOutputFilter</directive> directive maps the filename + extensions <em>extension</em> to the filters which will process + responses from the server before they are sent to the client. + This is in addition to any filters defined elsewhere, including + the <directive module="core">SetOutputFilter</directive> + directive. This mapping is merged over any already in force, + overriding any mappings that already exist for the same + <em>extension</em>.</p> + + <p>For example, the following configuration will process all + .shtml files for server-side includes.</p> + + + <example> + AddOutputFilter INCLUDES shtml + </example> + + <p>If more than one filter is specified, they must be separated + by semicolons in the order in which they should process the + content. Both the filter and <em>extension</em> arguments are + case-insensitive, and the extension may be specified with or + without a leading dot.</p> + + <seealso>See also the <a href="../filter.html">Filters</a> + documentation.</seealso> + +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>AddType</name> +<syntax>AddType <em>MIME-type + extension</em> [<em>extension</em>] ...</syntax> +<default>None</default> +<contextlist> +<context>server config</context> +<context>virtual host</context> +<context>directory</context> +<context>.htaccess</context> +</contextlist> +<override>FileInfo</override> +<description>maps the given filename extensions +onto the specified content type.</description> + +<usage> + + <p>The AddType directive maps the given filename extensions + onto the specified content type. <em>MIME-type</em> is the MIME + type to use for filenames containing <em>extension</em>. This + mapping is added to any already in force, overriding any + mappings that already exist for the same <em>extension</em>. + This directive can be used to add mappings not listed in the + MIME types file (see the <directive>TypesConfig</directive> + directive).</p> + + <p>Example:</p> + + <example> + AddType image/gif .gif + </example> + + <note>It is recommended that new MIME types be added using the + AddType directive rather than changing the + <directive>TypesConfig</directive> file. </note> + + <note>Note that, unlike the NCSA httpd, this directive cannot be + used to set the type of particular files.</note> + + <p>The <em>extension</em> argument is case-insensitive, and can + be specified with or without a leading dot.</p> + + <seealso><strong>See also</strong>: <a href="#multipleext">Files with + multiple extensions</a></seealso> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>MultiviewsMatch</name> +<syntax>MultiviewsMatch + <em>[NegotiatedOnly] [Handlers] [Filters] [Any]</em></syntax> +<default>None</default> +<contextlist> +<context>server config</context> +<context>virtual host</context> +<context>directory</context> +<context>.htaccess</context> +</contextlist> +<override>FileInfo</override> +<compatibility>only available + in Apache 2.0.26 and later.</compatibility> + +<usage> + + <p>MultiviewsMatch permits three different behaviors for + <a href="mod_negotiation.html">mod_negotiation</a>'s Multiviews + feature. Multiviews allows a request for a file, e.g. index.html, + to match any negotiated extensions following the base request, + e.g. index.html.en, index.html,fr, or index.html.gz.</p> + + <p>The NegotiatedOnly option provides that every extension following + the base name must correlate to a recognized mod_mime extension for + content negotation, e.g. Charset, Content-Type, Language, or + Encoding. This is the strictest implementation with the fewest + unexpected side effects, and is the default behavior.</p> + + <p>To include extensions associated with Handlers and/or Filters, + set the MultiviewsMatch directive to either Handlers, Filters, or + both option keywords. If all other factors are equal, the smallest + file will be served, e.g. in deciding between index.html.cgi of 500 + characters and index.html.pl of 1000 bytes, the .cgi file would win + in this example. Users of .asis files might prefer to use the + Handler option, if .asis files are associated with the asis-handler.</p> + + <p>You may finally allow Any extensions to match, even if mod_mime + doesn't recognize the extension. This was the behavior in Apache 1.3, + and can cause unpredicatable results, such as serving .old or .bak + files the webmaster never expected to be served.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>DefaultLanguage</name> +<syntax>DefaultLanguage + <em>MIME-lang</em></syntax> +<default>None</default> +<contextlist> +<context>server config</context> +<context>virtual host</context> +<context>directory</context> +<context>.htaccess</context> +</contextlist> +<override>FileInfo</override> +<compatibility>DefaultLanguage + is only available in Apache 1.3.4 and later.</compatibility> +<description>Sets all files in the given scope to the +specified language</description> + +<usage> + + <p>The DefaultLanguage directive tells Apache that all files in + the directive's scope (<em>e.g.</em>, all files covered by the + current <code><Directory></code> container) that don't + have an explicit language extension (such as <samp>.fr</samp> + or <samp>.de</samp> as configured by <samp>AddLanguage</samp>) + should be considered to be in the specified <em>MIME-lang</em> + language. This allows entire directories to be marked as + containing Dutch content, for instance, without having to + rename each file. Note that unlike using extensions to specify + languages, <samp>DefaultLanguage</samp> can only specify a + single language.</p> + + <p>If no <samp>DefaultLanguage</samp> directive is in force, + and a file does not have any language extensions as configured + by <samp>AddLanguage</samp>, then that file will be considered + to have no language attribute.</p> + + <seealso><strong>See also</strong>: <a href="#multipleext">Files with + multiple extensions</a>, <module>mod_negotiation</module></seealso> +</usage> +</directivesynopsis> + + +<directivesynopsis> +<name>RemoveCharset</name> +<syntax>RemoveCharset + <em>extension</em> [<em>extension</em>] ...</syntax> +<default>None</default> +<contextlist> +<context>directory</context> +<context>.htaccess</context> +</contextlist> +<compatibility>RemoveCharset is + only available in Apache 2.0.24 and later.</compatibility> + +<usage> + <p>The <samp>RemoveCharset</samp> directive removes any + character set associations for files with the given extensions. + This allows <code>.htaccess</code> files in subdirectories to + undo any associations inherited from parent directories or the + server config files.</p> + + <p>The <em>extension</em> argument is case-insensitive, and can + be specified with or without a leading dot.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>RemoveEncoding</name> +<syntax>RemoveEncoding + <em>extension</em> [<em>extension</em>] ...</syntax> +<default>None</default> +<contextlist> +<context>directory</context> +<context>.htaccess</context> +</contextlist> +<compatibility>RemoveEncoding + is only available in Apache 1.3.13 and later.</compatibility> + +<usage> + + <p>The <samp>RemoveEncoding</samp> directive removes any + encoding associations for files with the given extensions. This + allows <code>.htaccess</code> files in subdirectories to undo + any associations inherited from parent directories or the + server config files. An example of its use might be:</p> + + +<example> + <dl> + <dt><code>/foo/.htaccess:</code></dt> + <dd><code>AddEncoding x-gzip .gz</code><br /> + <code>AddType text/plain .asc</code><br /> + <code><Files *.gz.asc></code><br /> + <code> RemoveEncoding + .gz</code><br /> + <code></Files></code></dd> + </dl> +</example> + + <p>This will cause <code>foo.gz</code> to be marked as being + encoded with the gzip method, but <code>foo.gz.asc</code> as an + unencoded plaintext file.</p> + + <p><b>Note:</b>RemoveEncoding directives are processed + <i>after</i> any AddEncoding directives, so it is possible they + may undo the effects of the latter if both occur within the + same directory configuration.</p> + + <p>The <em>extension</em> argument is case-insensitive, and can + be specified with or without a leading dot.</p> +</usage> +</directivesynopsis> + + +<directivesynopsis> +<name>RemoveHandler</name> +<syntax>RemoveHandler + <em>extension</em> [<em>extension</em>] ...</syntax> +<default>None</default> +<contextlist> +<context>directory</context> +<context>.htaccess</context> +</contextlist> +<compatibility>RemoveHandler is + only available in Apache 1.3.4 and later.</compatibility> + +<usage> + + <p>The <samp>RemoveHandler</samp> directive removes any handler + associations for files with the given extensions. This allows + <code>.htaccess</code> files in subdirectories to undo any + associations inherited from parent directories or the server + config files. An example of its use might be:</p> + +<example> + <dl> + <dt><code>/foo/.htaccess:</code></dt> + + <dd><code>AddHandler server-parsed .html</code></dd> + + <dt><code>/foo/bar/.htaccess:</code></dt> + + <dd><code>RemoveHandler .html</code></dd> + </dl> +</example> + + <p>This has the effect of returning <samp>.html</samp> files in + the <samp>/foo/bar</samp> directory to being treated as normal + files, rather than as candidates for parsing (see the <a + href="mod_include.html"><samp>mod_include</samp></a> + module).</p> + + <p>The <em>extension</em> argument is case-insensitive, and can + be specified with or without a leading dot.</p> +</usage> +</directivesynopsis> + + +<directivesynopsis> +<name>RemoveInputFilter</name> +<syntax>RemoveInputFilter + <em>extension</em> [<em>extension</em>] ...</syntax> +<default>None</default> +<contextlist> +<context>directory</context> +<context>.htaccess</context> +</contextlist> +<compatibility>RemoveInputFilter is only available in Apache +2.0.26 and later.</compatibility> + +<usage> + + <p>The <samp>RemoveInputFilter</samp> directive removes any + input filter associations for files with the given extensions. + This allows <code>.htaccess</code> files in subdirectories to + undo any associations inherited from parent directories or the + server config files.</p> + + <p>The <em>extension</em> argument is case-insensitive, and can + be specified with or without a leading dot.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>RemoveLanguage</name> +<syntax>RemoveLanguage + <em>extension</em> [<em>extension</em>] ...</syntax> +<default>None</default> +<contextlist> +<context>directory</context> +<context>.htaccess</context> +</contextlist> +<compatibility>RemoveLanguage + is only available in Apache 2.0.24 and later.</compatibility> + + +<usage> + + <p>The <samp>RemoveLanguage</samp> directive removes any + language associations for files with the given extensions. This + allows <code>.htaccess</code> files in subdirectories to undo + any associations inherited from parent directories or the + server config files.</p> + + <p>The <em>extension</em> argument is case-insensitive, and can + be specified with or without a leading dot.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>RemoveOutputFilter</name> +<syntax>RemoveOutputFilter + <em>extension</em> [<em>extension</em>] ...</syntax> +<default></default> +<contextlist> +<context>directory</context> +<context>.htaccess</context> +</contextlist> +<override></override> +<compatibility>RemoveOutputFilter is only available in Apache +2.0.26 and later.</compatibility> + +<usage> + + <p>The <samp>RemoveOutputFilter</samp> directive removes any + output filter associations for files with the given extensions. + This allows <code>.htaccess</code> files in subdirectories to + undo any associations inherited from parent directories or the + server config files.</p> + + <p>The <em>extension</em> argument is case-insensitive, and can + be specified with or without a leading dot.</p> +</usage> +</directivesynopsis> + + +<directivesynopsis> +<name>RemoveType</name> +<syntax>RemoveType + <em>extension</em> [<em>extension</em>] ...</syntax> +<default></default> +<contextlist> +<context>directory</context> +<context>.htaccess</context> +</contextlist> +<override></override> +<compatibility>RemoveType is + only available in Apache 1.3.13 and later.</compatibility> + +<usage> + <p>The <directive>RemoveType</directive> directive removes any MIME type + associations for files with the given extensions. This allows + <code>.htaccess</code> files in subdirectories to undo any + associations inherited from parent directories or the server + config files. An example of its use might be:</p> + +<example> + <dl> + <dt><code>/foo/.htaccess:</code></dt> + + <dd><code>RemoveType .cgi</code></dd> + </dl> +</example> + + <p>This will remove any special handling of <code>.cgi</code> + files in the <code>/foo/</code> directory and any beneath it, + causing the files to be treated as being of the <a + href="core.html#defaulttype">default type</a>.</p> + + <note><b>Note:</b><module>RemoveType</module> directives are processed + <i>after</i> any <module>AddType</module> directives, so it is + possible they may undo the effects of the latter if both occur + within the same directory configuration.</note> + + <p>The <em>extension</em> argument is case-insensitive, and can + be specified with or without a leading dot.</p> +</usage> +</directivesynopsis> + + + +<directivesynopsis> +<name>TypesConfig</name> +<syntax>TypesConfig <em>file-path</em></syntax> +<default>TypesConfig conf/mime.types</default> +<contextlist> +<context>server config</context> +</contextlist> + +<usage> + + <p>The TypesConfig directive sets the location of the MIME + types configuration file. <em>Filename</em> is relative to the + <a href="core.html#serverroot">ServerRoot</a>. This file sets + the default list of mappings from filename extensions to + content types; changing this file is not recommended. Use the + <a href="#addtype">AddType</a> directive instead. The file + contains lines in the format of the arguments to an AddType + command:</p> + + <example> + MIME-type extension extension ... + </example> + + <p> + The extensions are lower-cased. Blank lines, and lines + beginning with a hash character (`#') are ignored. </p> +</usage> +</directivesynopsis> +</modulesynopsis> + diff --git a/docs/manual/mod/mod_mime_magic.xml b/docs/manual/mod/mod_mime_magic.xml new file mode 100644 index 0000000000..18f22158d1 --- /dev/null +++ b/docs/manual/mod/mod_mime_magic.xml @@ -0,0 +1,304 @@ +<?xml version="1.0"?> +<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd"> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>mod_mime_magic</name> +<description>Determines the MIME type of a file + by looking at a few bytes of its contents</description> +<status>Extension</status> +<sourcefile>mod_mime_magic.c</sourcefile> +<identifier>mime_magic_module</identifier> + +<summary> + <p>This module determines the MIME type of files in the same + way the Unix file(1) command works: it looks at the first few + bytes of the file. It is intended as a "second line of defense" + for cases that <module>mod_mime</module> can't + resolve. To assure that mod_mime gets first try at determining + a file's MIME type, be sure to list mod_mime_magic + <strong>before</strong> mod_mime in the configuration.</p> + + <p>This module is derived from a free version of the + <code>file(1)</code> command for Unix, which uses "magic + numbers" and other hints from a file's contents to figure out + what the contents are. This module is active only if the magic + file is specified by the <directive module="mod_mime_magic" + >MimeMagicFile</directive> directive.</p> +</summary> + +<section><title>Format of the Magic File</title> + + <p>The contents of the file are plain ASCII text in 4-5 + columns. Blank lines are allowed but ignored. Commented lines + use a hash mark "#". The remaining lines are parsed for the + following columns:</p> + + <table border="1"> + <tr valign="top"> + <th>Column</th> + + <th>Description</th> + </tr> + + <tr valign="top"> + <td>1</td> + + <td>byte number to begin checking from<br /> + ">" indicates a dependency upon the previous non-">" + line</td> + </tr> + + <tr valign="top"> + <td>2</td> + + <td> + type of data to match + + <table border="1"> + <tr> + <td>byte</td> + + <td>single character</td> + </tr> + + <tr> + <td>short</td> + + <td>machine-order 16-bit integer</td> + </tr> + + <tr> + <td>long</td> + + <td>machine-order 32-bit integer</td> + </tr> + + <tr> + <td>string</td> + + <td>arbitrary-length string</td> + </tr> + + <tr> + <td>date</td> + + <td>long integer date (seconds since Unix + epoch/1970)</td> + </tr> + + <tr> + <td>beshort</td> + + <td>big-endian 16-bit integer</td> + </tr> + + <tr> + <td>belong</td> + + <td>big-endian 32-bit integer</td> + </tr> + + <tr> + <td>bedate</td> + + <td>big-endian 32-bit integer date</td> + </tr> + + <tr> + <td>leshort</td> + + <td>little-endian 16-bit integer</td> + </tr> + + <tr> + <td>lelong</td> + + <td>little-endian 32-bit integer</td> + </tr> + + <tr> + <td>ledate</td> + + <td>little-endian 32-bit integer date</td> + </tr> + </table> + </td> + </tr> + + <tr valign="top"> + <td>3</td> + + <td>contents of data to match</td> + </tr> + + <tr valign="top"> + <td>4</td> + + <td>MIME type if matched</td> + </tr> + + <tr valign="top"> + <td>5</td> + + <td>MIME encoding if matched (optional)</td> + </tr> + </table> + + <p>For example, the following magic file lines would recognize + some audio formats.</p> +<example> +<pre> +# Sun/NeXT audio data +0 string .snd +>12 belong 1 audio/basic +>12 belong 2 audio/basic +>12 belong 3 audio/basic +>12 belong 4 audio/basic +>12 belong 5 audio/basic +>12 belong 6 audio/basic +>12 belong 7 audio/basic +>12 belong 23 audio/x-adpcm +</pre> +</example> + <p>Or these would recognize the difference between "*.doc" files + containing Microsoft Word or FrameMaker documents. (These are + incompatible file formats which use the same file suffix.)</p> +<example> +<pre> +# Frame +0 string \<MakerFile application/x-frame +0 string \<MIFFile application/x-frame +0 string \<MakerDictionary application/x-frame +0 string \<MakerScreenFon application/x-frame +0 string \<MML application/x-frame +0 string \<Book application/x-frame +0 string \<Maker application/x-frame + +# MS-Word +0 string \376\067\0\043 application/msword +0 string \320\317\021\340\241\261 application/msword +0 string \333\245-\0\0\0 application/msword +</pre> +</example> + <p>An optional MIME encoding can be included as a fifth column. + For example, this can recognize gzipped files and set the + encoding for them.</p> +<example> +<pre> +# gzip (GNU zip, not to be confused with [Info-ZIP/PKWARE] zip archiver) +0 string \037\213 application/octet-stream x-gzip +</pre> +</example> +</section> + +<section><title>Performance Issues</title> + <p>This module is not for every system. If your system is barely + keeping up with its load or if you're performing a web server + benchmark, you may not want to enable this because the + processing is not free.</p> + + <p>However, an effort was made to improve the performance of + the original file(1) code to make it fit in a busy web server. + It was designed for a server where there are thousands of users + who publish their own documents. This is probably very common + on intranets. Many times, it's helpful if the server can make + more intelligent decisions about a file's contents than the + file name allows ...even if just to reduce the "why doesn't my + page work" calls when users improperly name their own files. + You have to decide if the extra work suits your + environment.</p> + + <p>When compiling an Apache server, this module should be at or + near the top of the list of modules in the Configuration file. + The modules are listed in increasing priority so that will mean + this one is used only as a last resort, just like it was + designed to.</p> + +</section> + +<section id="notes"><title>Notes</title> + + <p>The following notes apply to the mod_mime_magic module and are + included here for compliance with contributors' copyright + restrictions that require their acknowledgment. </p> +<pre> +/* + * mod_mime_magic: MIME type lookup via file magic numbers + * Copyright (c) 1996-1997 Cisco Systems, Inc. + * + * This software was submitted by Cisco Systems to the Apache Group in July + * 1997. Future revisions and derivatives of this source code must + * acknowledge Cisco Systems as the original contributor of this module. + * All other licensing and usage conditions are those of the Apache Group. + * + * Some of this code is derived from the free version of the file command + * originally posted to comp.sources.unix. Copyright info for that program + * is included below as required. + * --------------------------------------------------------------------------- + * - Copyright (c) Ian F. Darwin, 1987. Written by Ian F. Darwin. + * + * This software is not subject to any license of the American Telephone and + * Telegraph Company or of the Regents of the University of California. + * + * Permission is granted to anyone to use this software for any purpose on any + * computer system, and to alter it and redistribute it freely, subject to + * the following restrictions: + * + * 1. The author is not responsible for the consequences of use of this + * software, no matter how awful, even if they arise from flaws in it. + * + * 2. The origin of this software must not be misrepresented, either by + * explicit claim or by omission. Since few users ever read sources, credits + * must appear in the documentation. + * + * 3. Altered versions must be plainly marked as such, and must not be + * misrepresented as being the original software. Since few users ever read + * sources, credits must appear in the documentation. + * + * 4. This notice may not be removed or altered. + * ------------------------------------------------------------------------- + * + * For compliance with Mr Darwin's terms: this has been very significantly + * modified from the free "file" command. + * - all-in-one file for compilation convenience when moving from one + * version of Apache to the next. + * - Memory allocation is done through the Apache API's pool structure. + * - All functions have had necessary Apache API request or server + * structures passed to them where necessary to call other Apache API + * routines. (<em>i.e.</em>, usually for logging, files, or memory allocation in + * itself or a called function.) + * - struct magic has been converted from an array to a single-ended linked + * list because it only grows one record at a time, it's only accessed + * sequentially, and the Apache API has no equivalent of realloc(). + * - Functions have been changed to get their parameters from the server + * configuration instead of globals. (It should be reentrant now but has + * not been tested in a threaded environment.) + * - Places where it used to print results to stdout now saves them in a + * list where they're used to set the MIME type in the Apache request + * record. + * - Command-line flags have been removed since they will never be used here. + * + */ +</pre> +</section> + +<directivesynopsis> +<name>MimeMagicFile</name> +<description>Enable MIME-type determination based on file contents +using the specified magic file</description> +<syntax>MimeMagicFile <em>file-path</em></syntax> +<contextlist><context>server config</context> +<context>virtual host</context></contextlist> + +<usage> + <p>The <directive>MimeMagicFile</directive> directive can be used to + enable this module, the default file is distributed at + <code>conf/magic</code>. Non-rooted paths are relative to the + ServerRoot. Virtual hosts will use the same file as the main + server unless a more specific setting is used, in which case + the more specific setting overrides the main server's file.</p> +</usage> +</directivesynopsis> +</modulesynopsis> + diff --git a/docs/manual/mod/mod_negotiation.xml b/docs/manual/mod/mod_negotiation.xml new file mode 100644 index 0000000000..12904441a8 --- /dev/null +++ b/docs/manual/mod/mod_negotiation.xml @@ -0,0 +1,243 @@ +<?xml version="1.0"?> +<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd"> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>mod_negotiation</name> +<description>Provides for <a + href="../content-negotiation.html">content negotiation</a></description> +<status>Base</status> +<sourcefile>mod_negotiation.c</sourcefile> +<identifier>negotiation_module</identifier> + +<summary> + <p>Content negotiation, or more accurately content selection, is + the selection of the document that best matches the clients + capabilities, from one of several available documents. There + are two implementations of this.</p> + + <ul> + <li>A type map (a file with the handler + <code>type-map</code>) which explicitly lists the files + containing the variants.</li> + + <li>A MultiViews search (enabled by the MultiViews <directive + module="core.html">Options</directive>, where the server does an + implicit filename pattern match, and choose from amongst the + results.</li> + </ul> +</summary> + +<seealso><directive module="mod_mime">DefaultLangauge</directive></seealso> +<seealso><directive module="mod_mime">AddEncoding</directive></seealso> +<seealso><directive module="mod_mime">AddLanguage</directive></seealso> +<seealso><directive module="mod_mime">AddType</directive></seealso> + +<section><title>Type maps</title> + <p>A type map has the same format as RFC822 mail headers. It + contains document descriptions separated by blank lines, with + lines beginning with a hash character ('#') treated as + comments. A document description consists of several header + records; records may be continued on multiple lines if the + continuation lines start with spaces. The leading space will be + deleted and the lines concatenated. A header record consists of + a keyword name, which always ends in a colon, followed by a + value. Whitespace is allowed between the header name and value, + and between the tokens of value. The headers allowed are: </p> + + <dl> + <dt>Content-Encoding:</dt> + + <dd>The encoding of the file. Apache only recognizes + encodings that are defined by an <directive + module="mod_mime">AddEncoding</directive> directive. + This normally includes the encodings <code>x-compress</code> + for compress'd files, and <code>x-gzip</code> for gzip'd + files. The <code>x-</code> prefix is ignored for encoding + comparisons.</dd> + + <dt>Content-Language:</dt> + + <dd>The language of the variant, as an Internet standard + language tag (RFC 1766). An example is <code>en</code>, + meaning English.</dd> + + <dt>Content-Length:</dt> + + <dd>The length of the file, in bytes. If this header is not + present, then the actual length of the file is used.</dd> + + <dt>Content-Type:</dt> + + <dd> + The MIME media type of the document, with optional + parameters. Parameters are separated from the media type + and from one another by a semi-colon, with a syntax of + <code>name=value</code>. Common parameters include: + + <dl> + <dt>level</dt> + + <dd>an integer specifying the version of the media type. + For <code>text/html</code> this defaults to 2, otherwise + 0.</dd> + + <dt>qs</dt> + + <dd>a floating-point number with a value in the range 0.0 + to 1.0, indicating the relative 'quality' of this variant + compared to the other available variants, independent of + the client's capabilities. For example, a jpeg file is + usually of higher source quality than an ascii file if it + is attempting to represent a photograph. However, if the + resource being represented is ascii art, then an ascii + file would have a higher source quality than a jpeg file. + All qs values are therefore specific to a given + resource.</dd> + </dl> + Example: + + <blockquote> + <code>Content-Type: image/jpeg; qs=0.8</code> + </blockquote> + </dd> + + <dt>URI:</dt> + + <dd>The path to the file containing this variant, relative to + the map file.</dd> + </dl> +</section> + +<section><title>MultiViews</title> + + <p>A MultiViews search is enabled by the MultiViews <directive + module="core">Options</directive>. If the server receives a + request for <code>/some/dir/foo</code> and + <code>/some/dir/foo</code> does <em>not</em> exist, then the + server reads the directory looking for all files named + <code>foo.*</code>, and effectively fakes up a type map which + names all those files, assigning them the same media types and + content-encodings it would have if the client had asked for one + of them by name. It then chooses the best match to the client's + requirements, and returns that document.</p> +</section> + +<directivesynopsis> +<name>CacheNegotiatedDocs</name> +<description>Allows content-negotiated documents to be +cached by proxy servers</description> +<syntax>CacheNegotiatedDocs on|off</syntax> +<default>CacheNegotiatedDocs off</default> +<contextlist><context>server config</context></contextlist> +<compatibility>The syntax changed in version 2.0.</compatibility> + +<usage> + <p>If set, this directive allows content-negotiated documents + to be cached by proxy servers. This could mean that clients + behind those proxys could retrieve versions of the documents + that are not the best match for their abilities, but it will + make caching more efficient.</p> + + <p>This directive only applies to requests which come from + HTTP/1.0 browsers. HTTP/1.1 provides much better control over + the caching of negotiated documents, and this directive has no + effect in responses to HTTP/1.1 requests.</p> + + <p>Prior to version 2.0, + <directive>CacheNegotiatedDocs</directive> did not take an + argument; it was turned on by the presence of the directive by + itself.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>ForceLangaugePriority</name> +<description>Action to take if a single acceptable document is not +found</description> +<syntax>ForceLanguagePriority None|Prefer|Fallback [Prefer|Fallback]</syntax> +<default>ForceLangaugePriority None</default> +<contextlist><context>server config</context> +<context>virtual host</context> +<context>directory</context> +<context>.htaccess</context> +</contextlist> +<override>FileInfo</override> +<compatibility>Available in version 2.0.30 and later</compatibility> + +<usage> + <p>The <directive>ForceLanguagePriority</directive> directive uses + the given <directive + module="mod_negotiation">LanguagePriority</directive> to satisfy + negotation where the server could otherwise not return a single + matching document.</p> + + <p><code>ForceLanguagePriority Prefer</code> uses + <code>LanguagePriority</code> to serve a one valid result, rather + than returning an HTTP result 300 (MULTIPLE CHOICES) when there + are several equally valid choices. If the directives below were + given, and the user's Accept-Language header assigned en and de + each as quality .500 (equally acceptable) then then first matching + variant, en, will be served.</p> + +<example> + LanguagePriority en fr de<br /> + ForceLanguagePriority Prefer +</example> + + <p><code>ForceLanguagePriority Fallback</code> uses + <code>LanguagePriority</code> to serve a valid result, rather than + returning an HTTP result 406 (NOT ACCEPTABLE). If the directives + below were given, and the user's Accept-Language only permitted an + es langauge response, but such a variant isn't found, then the + first variant from the LanguagePriority list below will be + served.</p> + +<example> + LanguagePriority en fr de<br /> + ForceLanguagePriority Fallback +</example> + + <p>Both options, Prefer and Fallback, may be specified, so either the + first matching variant from LanguagePriority will be served if more + that one variant is acceptable, or first available document will be + served if none of the variants matched the client's acceptable list of + languages.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>LanguagePriority</name> +<description>The precendence of language variants for cases where +the client does not express a preference</description> +<syntax>LanguagePriority <em>MIME-lang</em> [<em>MIME-lang</em>] ...</syntax> +<contextlist><context>server config</context> +<context>virtual host</context> +<context>directory</context> +<context>.htaccess</context> +</contextlist> +<override>FileInfo</override> + +<usage> + <p>The <directive>LanguagePriority</directive> sets the precedence + of language variants for the case where the client does not + express a preference, when handling a MultiViews request. The list + of <em>MIME-lang</em> are in order of decreasing preference. + Example:</p> + +<example>LanguagePriority en fr de</example> + + <p>For a request for <code>foo.html</code>, where + <code>foo.html.fr</code> and <code>foo.html.de</code> both + existed, but the browser did not express a language preference, + then <code>foo.html.fr</code> would be returned.</p> + + <p>Note that this directive only has an effect if a 'best' + language cannot be determined by any other means or the <directive + module="mod_negotiation">ForceLanguagePriority</directive> directive + is not <code>None</code>. Correctly implemented HTTP/1.1 requests + will mean this directive has no effect.</p> +</usage> +</directivesynopsis> + +</modulesynopsis>
\ No newline at end of file diff --git a/docs/manual/mod/mod_proxy.xml b/docs/manual/mod/mod_proxy.xml new file mode 100644 index 0000000000..d4d7551f2e --- /dev/null +++ b/docs/manual/mod/mod_proxy.xml @@ -0,0 +1,722 @@ +<?xml version="1.0"?> +<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd"> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>mod_proxy</name> +<description>HTTP/1.1 proxy/gateway server</description> +<status>Extension</status> +<sourcefile>mod_proxy.c</sourcefile> +<identifier>proxy_module</identifier> + +<summary> +<note type="warning"><title>Warning</title> +This document has been updated to take into account changes +made in the 2.0 version of the Apache HTTP Server. Some of the +information may still be inaccurate, please use it +with care. +</note> + +<p>This module implements a proxy/gateway for Apache. It implements +proxying capability for +<code>FTP</code>, +<code>CONNECT</code> (for SSL), +<code>HTTP/0.9</code>, +<code>HTTP/1.0</code>, and +<code>HTTP/1.1</code>. +The module can be configured to connect to other proxy modules for these +and other protocols.</p> + +<p>This module was experimental in Apache 1.1.x. Improvements and bugfixes +were made in Apache v1.2.x and Apache v1.3.x, then the module underwent a major +overhaul for Apache v2.0. The protocol support was upgraded to HTTP/1.1, +and filter support was enabled.</p> + +<p>Please note that the <strong>caching</strong> function present in +mod_proxy up to Apache v1.3.x has been <strong>removed</strong> from +mod_proxy and will be incorporated into a new module, mod_cache.</p> +</summary> + +<section id="configs"><title>Common configuration topics</title> + +<ul> +<li><a href="#forwardreverse">Forward and Reverse Proxies</a></li> +<li><a href="#access">Controlling access to your proxy</a></li> +<li><a href="#shortname">Using Netscape hostname shortcuts</a></li> +<li><a href="#mimetypes">Why doesn't file type <em>xxx</em> download via FTP?</a></li> +<li><a href="#type">How can I force an FTP ASCII download of File <em>xxx</em>?</a></li> +<li><a href="#percent2fhack">How can I access FTP files outside of my home directory?</a></li> +<li><a href="#ftppass">How can I hide the FTP cleartext password in my browser's URL line?</a></li> +<li><a href="#startup">Why does Apache start more slowly when using the + proxy module?</a></li> +<!--<li><a href="#socks">Can I use the Apache proxy module with my SOCKS proxy?</a>--> +<li><a href="#intranet">What other functions are useful for an intranet proxy server?</a></li> +</ul> + +<section id="forwardreverse"><title>Forward and Reverse Proxies</title> + +<p>Apache can be configured in both a <em>forward</em> and <em>reverse</em> +proxy configuration.</p> + +<p>A <em>forward proxy</em> is an intermediate system that enables a browser to connect to a +remote network to which it normally does not have access. A forward proxy +can also be used to cache data, reducing load on the networks between the +forward proxy and the remote webserver.</p> + +<p>Apache's mod_proxy can be figured to behave like a forward proxy +using the <directive module="mod_proxy">ProxyRemote</directive> +directive. In addition, caching of data can be achieved by configuring +Apache <module>mod_cache</module>. Other dedicated forward proxy +packages include <a href="http://www.squid.org">Squid</a>.</p> + +<p>A <em>reverse proxy</em> is a webserver system that is capable of serving webpages +sourced from other webservers - in addition to webpages on disk or generated +dynamically by CGI - making these pages look like they originated at the +reverse proxy.</p> + +<p>When configured with the mod_cache module the reverse +proxy can act as a cache for slower backend webservers. The reverse proxy +can also enable advanced URL strategies and management techniques, allowing +webpages served using different webserver systems or architectures to +coexist inside the same URL space. Reverse proxy systems are also ideal for +implementing centralised logging websites with many or diverse website +backends. Complex multi-tier webserver systems can be constructed using an +Apache mod_proxy frontend and any number of backend webservers.</p> + +<p>The reverse proxy is configured using the +<directive module="mod_proxy">ProxyPass</directive> and <directive +module="mod_proxy">ProxyPassReverse</directive> directives. Caching can be +enabled using mod_cache as with the forward proxy.</p> + +</section> + +<section id="access"><title>Controlling access to your proxy</title> + +<p>You can control who can access your proxy via the normal <directive module="core" type="section">Directory</directive> +control block using the following example:</p> + +<example> +<Directory proxy:*><br /> +Order Deny,Allow<br /> +Deny from all<br /> +Allow from 192.168.0<br /> +</Directory> +</example> + +<p>A <directive module="core" type="section">Files</directive> block +will also work, and is the only method known to work for all possible +URLs in Apache versions earlier than 1.2b10.</p> + +<p>When configuring a reverse proxy, access control takes on the +attributes of the normal server <directive module="core" +type="section">directory</directive> configuration.</p> + + +<!--<h2><a name="shortname">Using Netscape hostname shortcuts</a></h2> + +There is an optional patch to the proxy module to allow Netscape-like +hostname shortcuts to be used. It's available from the +<a href="http://www.apache.org/dist/contrib/patches/1.2/netscapehost.patch" +><code>contrib/patches/1.2</code></a> directory on the Apache Web +site.<p>--> + +</section> + +<section id="mimetypes"><title>Why doesn't file type <em>xxx</em> +download via FTP?</title> + +<p>You probably don't have that particular file type defined as +<em>application/octet-stream</em> in your proxy's mime.types configuration +file. A useful line can be</p> + +<example> +application/octet-stream bin dms lha lzh exe class tgz taz +</example> +</section> + +<section id="type"><title>How can I force an FTP ASCII download of +File <em>xxx</em>?</title> + +<p>In the rare situation where you must download a specific file using the FTP +<strong>ASCII</strong> transfer method (while the default transfer is in +<strong>binary</strong> mode), you can override mod_proxy's default by +suffixing the request with <code>;type=a</code> to force an ASCII transfer. +(FTP Directory listings are always executed in ASCII mode, however.)</p> +</section> + +<section id="percent2fhck"><title>How can I access FTP files outside +of my home directory?</title> + +<p> +An FTP URI is interpreted relative to the home directory of the user +who is logging in. Alas, to reach higher directory levels you cannot +use /../, as the dots are interpreted by the browser and not actually +sent to the FTP server. To address this problem, the so called "Squid +%2f hack" was implemented in the Apache FTP proxy; it is is a solution +which is also used by other popular proxy servers like the <a +href="http://www.squid-cache.org/">Squid Proxy Cache</a>. By +prepending /%2f to the path of your request, you can make such a proxy +change the FTP starting directory to / (instead of the home +directory). </p> + +<p><strong>Example:</strong> To retrieve the file +<code>/etc/motd</code>, you would use the URL</p> +<example>ftp://<em>user@host</em>/%2f/etc/motd</example> +</section> + +<section id="ftppass"><title>How can I hide the FTP cleartext password +in my browser's URL line?</title> + +<p> +To log in to an FTP server by username and password, Apache +uses different strategies. +In absense of a user name and password in the URL altogether, +Apache sends an anomymous login to the FTP server, i.e.,</p> +<example> +user: anonymous<br /> +password: apache_proxy@ +</example> +<p>This works for all popular FTP servers which are configured for +anonymous access.</p> + +<p>For a personal login with a specific username, you can embed +the user name into the URL, like in: +<code>ftp://<em>username@host</em>/myfile</code>. If the FTP server +asks for a password when given this username (which it should), +then Apache will reply with a [401 Authorization required] response, +which causes the Browser to pop up the username/password dialog. +Upon entering the password, the connection attempt is retried, +and if successful, the requested resource is presented. +The advantage of this procedure is that your browser does not +display the password in cleartext (which it would if you had used +<code>ftp://<em>username:password@host</em>/myfile</code> in +the first place).</p> + +<note><title>Note</title> +The password which is transmitted in such a way +is not encrypted on its way. It travels between your browser and +the Apache proxy server in a base64-encoded cleartext string, and +between the Apache proxy and the FTP server as plaintext. You should +therefore think twice before accessing your FTP server via HTTP +(or before accessing your personal files via FTP at all!) When +using unsecure channels, an eavesdropper might intercept your +password on its way. +</note> +</section> + +<section id="startup"><title>Why does Apache start more slowly when +using the proxy module?</title> + +<p>If you're using the <directive module="mod_proxy">ProxyBlock</directive> +directive, hostnames' IP addresses are looked up and cached during +startup for later match test. This may take a few seconds (or more) +depending on the speed with which the hostname lookups occur.</p> +</section> + +<!--<h2><a name="socks">Can I use the Apache proxy module with my SOCKS proxy?</a></h2> + +Yes. Just build Apache with the rule <code>SOCKS4=yes</code> in your +<em>Configuration</em> file, and follow the instructions there. SOCKS5 +capability can be added in a similar way (there's no <code>SOCKS5</code> +rule yet), so use the <code>EXTRA_LDFLAGS</code> definition, or build Apache +normally and run it with the <em>runsocks</em> wrapper provided with SOCKS5, +if your OS supports dynamically linked libraries.<p> + +Some users have reported problems when using SOCKS version 4.2 on Solaris. +The problem was solved by upgrading to SOCKS 4.3.<p> + +Remember that you'll also have to grant access to your Apache proxy machine by +permitting connections on the appropriate ports in your SOCKS daemon's +configuration.<p> +--> + +<section id="intranet"><title>What other functions are useful for an +intranet proxy server?</title> + +<p>An Apache proxy server situated in an intranet needs to forward +external requests through the company's firewall. However, when it has +to access resources within the intranet, it can bypass the firewall +when accessing hosts. The <directive +module="mod_proxy">NoProxy</directive> directive is useful for +specifying which hosts belong to the intranet and should be accessed +directly.</p> + +<p>Users within an intranet tend to omit the local domain name from their +WWW requests, thus requesting "http://somehost/" instead of +"http://somehost.my.dom.ain/". Some commercial proxy servers let them get +away with this and simply serve the request, implying a configured +local domain. When the <directive module="mod_proxy">ProxyDomain</directive> directive +is used and the server is <a href="#proxyrequests">configured for +proxy service</a>, Apache can return a redirect response and send the client +to the correct, fully qualified, server address. This is the preferred method +since the user's bookmark files will then contain fully qualified hosts.</p> +</section> + +</section> + +<directivesynopsis> +<name>ProxyPreserveHost</name> +<syntax>ProxyPreserveHost on|off</syntax> +<default>ProxyPreserveHost Off</default> +<contextlist><context>server config</context> +<context>virtual host</context> +</contextlist> +<compatibility>Available in +Apache 2.0.31 and later.</compatibility> + +<usage> +<p>When enabled, this option will pass the Host: line from the +incoming request to the proxied host, instead of the hostname +specified in the proxypass line. +</p> +<p>This option should normally be turned 'off'.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>ProxyRequests</name> +<syntax>ProxyRequests on|off</syntax> +<default>ProxyRequests Off</default> +<contextlist><context>server config</context> +<context>virtual host</context> +</contextlist> + +<usage> +<p>This allows or prevents Apache from functioning as a forward proxy +server. (Setting ProxyRequests to 'off' does not disable use of the +<directive module="mod_proxy">ProxyPass</directive> directive.)</p> + +<p>In a typical reverse proxy configuration, this option should be set to +'off'.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>ProxyRemote</name> +<syntax>ProxyRemote <em>match remote-server</em></syntax> +<contextlist><context>server config</context> +<context>virtual host</context> +</contextlist> + +<usage> +<p>This defines remote proxies to this proxy. <em>match</em> is either the +name of a URL-scheme that the remote server supports, or a partial URL +for which the remote server should be used, or '*' to indicate the +server should be contacted for all requests. <em>remote-server</em> is a +partial URL for the remote server. Syntax:</p> + +<pre> + remote-server = protocol://hostname[:port] +</pre> + +<p><em>protocol</em> is the protocol that should be used to communicate +with the remote server; only "http" is supported by this module.</p> + +<p> +Example:</p> +<example> + ProxyRemote http://goodguys.com/ http://mirrorguys.com:8000<br /> + ProxyRemote * http://cleversite.com<br /> + ProxyRemote ftp http://ftpproxy.mydomain.com:8080 +</example> + +<p>In the last example, the proxy will forward FTP requests, encapsulated +as yet another HTTP proxy request, to another proxy which can handle +them.</p> + +<p>This option also supports reverse proxy configuration - a backend +webserver can be embedded within a virtualhost URL space even if that +server is hidden by another forward proxy.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>ProxyPass</name> +<syntax>ProxyPass [<em>path</em>] !|<em>url</em></syntax> +<contextlist><context>server config</context> +<context>virtual host</context> +</contextlist> + +<usage> +<!-- XXX: Need to document that the path is not used when placed in +a location section --> +<p>This directive allows remote servers to be mapped into the space of +the local server; the local server does not act as a proxy in the +conventional sense, but appears to be a mirror of the remote +server. <em>path</em> is the name of a local virtual path; +<em>url</em> is a partial URL for the remote server.</p> + +<p>Suppose the local server has address <code>http://wibble.org/</code>; +then</p> +<example> + ProxyPass /mirror/foo/ http://foo.com/ +</example> +<p>will cause a local request for the +<<code>http://wibble.org/mirror/foo/bar</code>> to be +internally converted into a proxy request to +<<code>http://foo.com/bar</code>>.</p> +<p> +The ! directive is useful in situations where you don't want to reverse-proxy +a subdirectory. eg.</p> +<example> + ProxyPass /mirror/foo/i !<br /> + ProxyPass /mirror/foo http://foo.com +</example> +<p>will proxy all requests to /mirror/foo to foo.com EXCEPT requests made to /mirror/foo/i</p> + +<note>NB: order is important. you need to put the exclusions BEFORE the general proxypass directive</note> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>ProxyPassReverse</name> +<syntax>ProxyPassReverse [<em>path</em>] <em>url</em></syntax> +<contextlist><context>server config</context> +<context>virtual host</context> +</contextlist> + +<usage> +<!-- XXX: Need to document that the path is not used when placed in +a location section --> +<p>This directive lets Apache adjust the URL in the <code>Location</code>, +<code>Content-Location</code> and <code>URI</code> headers on +HTTP redirect responses. This is essential when Apache is used as +a reverse proxy to avoid by-passing the reverse proxy because of HTTP +redirects on the backend servers which stay behind the reverse proxy.</p> + +<p><em>path</em> is the name of a local virtual path.<br /> +<em>url</em> is a partial URL for the remote server - the same way they are +used for the <directive module="mod_proxy">ProxyPass</directive> directive.</p> + +<p> +Example:<br /> +Suppose the local server has address <code>http://wibble.org/</code>; then</p> +<example> + ProxyPass /mirror/foo/ http://foo.com/<br /> + ProxyPassReverse /mirror/foo/ http://foo.com/ +</example> +<p>will not only cause a local request for the +<<code>http://wibble.org/mirror/foo/bar</code>> to be internally +converted into a proxy request to <<code>http://foo.com/bar</code>> (the +functionality <code>ProxyPass</code> provides here). It also takes care of +redirects the server foo.com sends: when <code>http://foo.com/bar</code> is +redirected by him to <code>http://foo.com/quux</code> Apache adjusts this to +<code>http://wibble.org/mirror/foo/quux</code> before forwarding the HTTP +redirect response to the client. </p> +<p> +Note that this <directive>ProxyPassReverse</directive> directive can +also be used in conjunction with the proxy pass-through feature +("<code>RewriteRule ... [P]</code>") from +<module>mod_rewrite</module> because its doesn't depend on a +corresponding <directive module="mod_proxy">ProxyPass</directive> +directive.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>AllowCONNECT</name> +<syntax>AllowCONNECT <em>port</em> [<em>port</em>] ...</syntax> +<default>AllowCONNECT 443 563</default> +<contextlist><context>server config</context> +<context>virtual host</context> +</contextlist> + +<usage> +<p>The <directive>AllowCONNECT</directive> directive specifies a list +of port numbers to which the proxy <code>CONNECT</code> method may +connect. Today's browsers use this method when a <em>https</em> +connection is requested and proxy tunneling over <em>http</em> is in +effect.<br /> By default, only the default https port (443) and the +default snews port (563) are enabled. Use the +<directive>AllowCONNECT</directive> directive to overrride this default and +allow connections to the listed ports only.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>ProxyBlock</name> +<syntax>ProxyBlock *|<em>word|host|domain</em> +[<em>word|host|domain</em>] ...</syntax> +<contextlist><context>server config</context> +<context>virtual host</context> +</contextlist> + +<usage> +<p>The <directive>ProxyBlock</directive> directive specifies a list of +words, hosts and/or domains, separated by spaces. HTTP, HTTPS, and +FTP document requests to sites whose names contain matched words, +hosts or domains are <em>blocked</em> by the proxy server. The proxy +module will also attempt to determine IP addresses of list items which +may be hostnames during startup, and cache them for match test as +well. Example:</p> + +<example> + ProxyBlock joes-garage.com some-host.co.uk rocky.wotsamattau.edu +</example> + +<p>'rocky.wotsamattau.edu' would also be matched if referenced by IP +address.</p> + +<p>Note that 'wotsamattau' would also be sufficient to match +'wotsamattau.edu'.</p> + +<p>Note also that</p> + +<example> +ProxyBlock * +</example> + +<p>blocks connections to all sites.</p> + +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>ProxyReceiveBufferSize</name> +<syntax>ProxyReceiveBufferSize <em>bytes</em></syntax> +<contextlist><context>server config</context> +<context>virtual host</context> +</contextlist> + +<usage> +<p>The <directive>ProxyReceiveBufferSize</directive> directive +specifies an explicit network buffer size for outgoing HTTP and FTP +connections, for increased throughput. It has to be greater than 512 +or set to 0 to indicate that the system's default buffer size should +be used.</p> +<example><title>Example</title> + ProxyReceiveBufferSize 2048 +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>ProxyMaxForwards</name> +<syntax>ProxyMaxForwards <em>number</em></syntax> +<default>ProxyMaxForwards 10</default> +<contextlist><context>server config</context> +<context>virtual host</context> +</contextlist> +<compatibility>Available in Apache 2.0 and later</compatibility> + +<usage> +<p>The <directive>ProxyMaxForwards</directive> directive specifies the +maximum number of proxies through which a request may pass. This is +set to prevent infinite proxy loops, or a DoS attack.</p> + +<example><title>Example</title> + ProxyMaxForwards 10 +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>NoProxy</name> +<syntax>NoProxy + <em>Domain</em>| + <em>SubNet</em>| + <em>IpAddr</em>| + <em>Hostname</em> +[<em>Domain</em>| + <em>SubNet</em>| + <em>IpAddr</em>| + <em>Hostname</em>] ...</syntax> +<contextlist><context>server config</context> +<context>virtual host</context> +</contextlist> + +<usage> +<p>This directive is only useful for Apache proxy servers within +intranets. The <directive>NoProxy</directive> directive specifies a +list of subnets, IP addresses, hosts and/or domains, separated by +spaces. A request to a host which matches one or more of these is +always served directly, without forwarding to the configured +<directive module="mod_proxy">ProxyRemote</directive> proxy server(s).</p> + +<example><title>Example</title> + ProxyRemote * http://firewall.mycompany.com:81<br /> + NoProxy .mycompany.com 192.168.112.0/21 +</example> + +<p>The arguments to the NoProxy directive are one of the following type list:</p> + <dl> + <!-- ===================== Domain ======================= --> + <dt><a name="domain"> + <em>Domain</em></a></dt> + <dd>A <em>Domain</em> is a partially qualified DNS domain name, preceded + by a period. + It represents a list of hosts which logically belong to the same DNS + domain or zone (<em>i.e.</em>, the suffixes of the hostnames are all ending in + <em>Domain</em>).<br /> + Examples: <code>.com</code> <code>.apache.org.</code><br /> + To distinguish <em>Domain</em>s from <a href="#hostname"><em>Hostname</em></a>s (both + syntactically and semantically; a DNS domain can have a DNS A record, + too!), <em>Domain</em>s are always written + with a leading period.<br /> + Note: Domain name comparisons are done without regard to the case, + and <em>Domain</em>s are always assumed to be anchored in the root + of the DNS tree, therefore two domains <code>.MyDomain.com</code> and + <code>.mydomain.com.</code> (note the trailing period) are + considered equal. Since a domain comparison does not involve a DNS + lookup, it is much more efficient than subnet comparison.</dd> + + <!-- ===================== SubNet ======================= --> + <dt><a name="subnet"> + <em>SubNet</em></a></dt> + <dd>A <em>SubNet</em> is a partially qualified internet address in + numeric (dotted quad) form, optionally followed by a slash and the + netmask, specified as the number of significant bits in the + <em>SubNet</em>. It is used to represent a subnet of hosts which can + be reached over a common network interface. In the absence of the + explicit net mask it is assumed that omitted (or zero valued) + trailing digits specify the mask. (In this case, the netmask can + only be multiples of 8 bits wide.)<br /> + Examples: + <dl> + <dt><code>192.168</code> or <code>192.168.0.0</code></dt> + <dd>the subnet 192.168.0.0 with an implied netmask of 16 valid bits + (sometimes used in the netmask form <code>255.255.0.0</code>)</dd> + <dt><code>192.168.112.0/21</code></dt> + <dd>the subnet <code>192.168.112.0/21</code> with a netmask of 21 + valid bits (also used in the form 255.255.248.0)</dd> + </dl> + As a degenerate case, a <em>SubNet</em> with 32 valid bits is the + equivalent to an <em>IPAddr</em>, while a <em>SubNet</em> with zero + valid bits (<em>e.g.</em>, 0.0.0.0/0) is the same as the constant + <em>_Default_</em>, matching any IP address. </dd> + + <!-- ===================== IPAddr ======================= --> + <dt><a name="ipaddr"> + <em>IPAddr</em></a></dt> + <dd>A <em>IPAddr</em> represents a fully qualified internet address in + numeric (dotted quad) form. Usually, this address represents a + host, but there need not necessarily be a DNS domain name + connected with the address.<br /> + Example: 192.168.123.7<br /> + Note: An <em>IPAddr</em> does not need to be resolved by the DNS + system, so it can result in more effective apache performance.</dd> + + <!-- ===================== Hostname ======================= --> + <dt><a name="hostname"> + <em>Hostname</em></a></dt> + <dd>A <em>Hostname</em> is a fully qualified DNS domain name which can + be resolved to one or more <a + href="#ipaddr"><em>IPAddrs</em></a> via the DNS domain name service. + It represents a logical host (in contrast to + <a href="#domain"><em>Domain</em></a>s, see + above) and must be resolvable to at least one <a + href="#ipaddr"><em>IPAddr</em></a> (or often to a list of hosts + with different <a href="#ipaddr"><em>IPAddr</em></a>'s).<br /> + Examples: <code>prep.ai.mit.edu</code> + <code>www.apache.org.</code><br /> + Note: In many situations, it is more effective to specify an + <a href="#ipaddr"><em>IPAddr</em></a> in place of a + <em>Hostname</em> since a DNS lookup + can be avoided. Name resolution in Apache can take a remarkable deal + of time when the connection to the name server uses a slow PPP + link.<br /> + Note: <em>Hostname</em> comparisons are done without regard to the case, + and <em>Hostname</em>s are always assumed to be anchored in the root + of the DNS tree, therefore two hosts <code>WWW.MyDomain.com</code> + and <code>www.mydomain.com.</code> (note the trailing period) are + considered equal.</dd> +</dl> +</usage> +<seealso><a href="../dns-caveats.html">DNS Issues</a></seealso> +</directivesynopsis> + +<directivesynopsis> +<name>ProxyTimeout</name> +<syntax>ProxyTimeout <em>seconds</em></syntax> +<default>ProxyTimeout 300</default> +<contextlist><context>server config</context> +<context>virtual host</context> +</contextlist> +<compatibility>Available in +Apache 2.0.31 and later</compatibility> + +<usage> +<p>This directive allows a user to specifiy a timeout on proxy requests. +This is usefull when you have a slow/buggy appserver which hangs, +and you would rather just return a timeout and fail gracefully instead +of waiting however long it takes the server to return +</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>ProxyDomain</name> +<syntax>ProxyDomain <em>Domain</em></syntax> +<contextlist><context>server config</context> +<context>virtual host</context> +</contextlist> + +<usage> +<p>This directive is only useful for Apache proxy servers within +intranets. The <directive>ProxyDomain</directive> directive specifies +the default domain which the apache proxy server will belong to. If a +request to a host without a domain name is encountered, a redirection +response to the same host with the configured <em>Domain</em> appended +will be generated.</p> + +<example><title>Example</title> + ProxyRemote * http://firewall.mycompany.com:81<br /> + NoProxy .mycompany.com 192.168.112.0/21<br /> + ProxyDomain .mycompany.com +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>ProxyVia</name> +<syntax>ProxyVia on|off|full|block</syntax> +<default>ProxyVia off</default> +<contextlist><context>server config</context> +<context>virtual host</context> +</contextlist> + +<usage> +<p>This directive controls the use of the <code>Via:</code> HTTP +header by the proxy. Its intended use is to control the flow of of +proxy requests along a chain of proxy servers. See RFC2068 (HTTP/1.1) +for an explanation of <code>Via:</code> header lines.</p> + +<ul> <li>If set +to <em>off</em>, which is the default, no special processing is +performed. If a request or reply contains a <code>Via:</code> header, +it is passed through unchanged.</li> + +<li>If set to <em>on</em>, each +request and reply will get a <code>Via:</code> header line added for +the current host.</li> + +<li>If set to <em>full</em>, each generated <code>Via:</code> header +line will additionally have the Apache server version shown as a +<code>Via:</code> comment field.</li> + +<li>If set to <em>block</em>, every +proxy request will have all its <code>Via:</code> header lines +removed. No new <code>Via:</code> header will be generated.</li> +</ul> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>ProxyErrorOverride</name> +<syntax>ProxyErrorOverride On|Off</syntax> +<default>ProxyErrorOverride Off</default> +<contextlist><context>server config</context> +<context>virtual host</context> +</contextlist> +<compatibility>Available in version 2.0 and later</compatibility> + +<usage> +<p>This directive is useful for reverse-proxy setups, where you want to +have a common look and feel on the error pages seen by the end user. +This also allows for included files (via mod_include's SSI) to get +the error code and act accordingly (default behavior would display +the error page of the proxied server, turning this on shows the SSI +Error message).</p> +</usage> +</directivesynopsis> +</modulesynopsis> diff --git a/docs/manual/mod/mod_rewrite.xml b/docs/manual/mod/mod_rewrite.xml new file mode 100644 index 0000000000..ff31e179bc --- /dev/null +++ b/docs/manual/mod/mod_rewrite.xml @@ -0,0 +1,1798 @@ +<?xml version="1.0"?> +<!DOCTYPE xml:manual [ <!ENTITY nbsp " "> ]> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>mod_rewrite</name> + +<description>Provides a rule-based rewriting engine to rewrite requested +URLs on the fly</description> + +<status>Extension</status> +<sourcefile>mod_rewrite.c</sourcefile> +<identifier>rewrite_module</identifier> +<compatibility>Available in Apache 1.3 and later</compatibility> + +<summary> + <blockquote> + <em>``The great thing about mod_rewrite is it gives you + all the configurability and flexibility of Sendmail. + The downside to mod_rewrite is that it gives you all + the configurability and flexibility of Sendmail.''</em> + + + <div align="RIGHT"> + -- Brian Behlendorf<br /> + Apache Group + </div> + </blockquote> + + <blockquote> + <em>`` Despite the tons of examples and docs, + mod_rewrite is voodoo. Damned cool voodoo, but still + voodoo. ''</em> + + <div align="RIGHT"> + -- Brian Moore<br /> + bem@news.cmc.net + </div> + </blockquote> + + + <p>Welcome to mod_rewrite, the Swiss Army Knife of URL + manipulation!</p> + + <p>This module uses a rule-based rewriting engine (based on a + regular-expression parser) to rewrite requested URLs on the + fly. It supports an unlimited number of rules and an + unlimited number of attached rule conditions for each rule to + provide a really flexible and powerful URL manipulation + mechanism. The URL manipulations can depend on various tests, + for instance server variables, environment variables, HTTP + headers, time stamps and even external database lookups in + various formats can be used to achieve a really granular URL + matching.</p> + + <p>This module operates on the full URLs (including the + path-info part) both in per-server context + (<code>httpd.conf</code>) and per-directory context + (<code>.htaccess</code>) and can even generate query-string + parts on result. The rewritten result can lead to internal + sub-processing, external request redirection or even to an + internal proxy throughput.</p> + + <p>But all this functionality and flexibility has its + drawback: complexity. So don't expect to understand this + entire module in just one day.</p> + + <p>This module was invented and originally written in April + 1996 and gifted exclusively to the The Apache Group in July 1997 + by</p> + + <blockquote> + <a href="http://www.engelschall.com/"><code>Ralf S. + Engelschall</code></a><br /> + <a + href="mailto:rse@engelschall.com"><code>rse@engelschall.com</code></a><br /> + <a + href="http://www.engelschall.com/"><code>www.engelschall.com</code></a> + </blockquote> +</summary> + +<section id="Internal"><title>Interal Processing</title> + + <p>The internal processing of this module is very complex but + needs to be explained once even to the average user to avoid + common mistakes and to let you exploit its full + functionality.</p> + +<section id="InternalAPI"><title>API Phases</title> + + <p>First you have to understand that when Apache processes a + HTTP request it does this in phases. A hook for each of these + phases is provided by the Apache API. Mod_rewrite uses two of + these hooks: the URL-to-filename translation hook which is + used after the HTTP request has been read but before any + authorization starts and the Fixup hook which is triggered + after the authorization phases and after the per-directory + config files (<code>.htaccess</code>) have been read, but + before the content handler is activated.</p> + + <p>So, after a request comes in and Apache has determined the + corresponding server (or virtual server) the rewriting engine + starts processing of all mod_rewrite directives from the + per-server configuration in the URL-to-filename phase. A few + steps later when the final data directories are found, the + per-directory configuration directives of mod_rewrite are + triggered in the Fixup phase. In both situations mod_rewrite + rewrites URLs either to new URLs or to filenames, although + there is no obvious distinction between them. This is a usage + of the API which was not intended to be this way when the API + was designed, but as of Apache 1.x this is the only way + mod_rewrite can operate. To make this point more clear + remember the following two points:</p> + + <ol> + <li>Although mod_rewrite rewrites URLs to URLs, URLs to + filenames and even filenames to filenames, the API + currently provides only a URL-to-filename hook. In Apache + 2.0 the two missing hooks will be added to make the + processing more clear. But this point has no drawbacks for + the user, it is just a fact which should be remembered: + Apache does more in the URL-to-filename hook than the API + intends for it.</li> + + <li> + Unbelievably mod_rewrite provides URL manipulations in + per-directory context, <em>i.e.</em>, within + <code>.htaccess</code> files, although these are reached + a very long time after the URLs have been translated to + filenames. It has to be this way because + <code>.htaccess</code> files live in the filesystem, so + processing has already reached this stage. In other + words: According to the API phases at this time it is too + late for any URL manipulations. To overcome this chicken + and egg problem mod_rewrite uses a trick: When you + manipulate a URL/filename in per-directory context + mod_rewrite first rewrites the filename back to its + corresponding URL (which is usually impossible, but see + the <code>RewriteBase</code> directive below for the + trick to achieve this) and then initiates a new internal + sub-request with the new URL. This restarts processing of + the API phases. + + <p>Again mod_rewrite tries hard to make this complicated + step totally transparent to the user, but you should + remember here: While URL manipulations in per-server + context are really fast and efficient, per-directory + rewrites are slow and inefficient due to this chicken and + egg problem. But on the other hand this is the only way + mod_rewrite can provide (locally restricted) URL + manipulations to the average user.</p> + </li> + </ol> + + <p>Don't forget these two points!</p> +</section> + +<section id="InternalRuleset"><title>Ruleset Processing</title> + + <p>Now when mod_rewrite is triggered in these two API phases, it + reads the configured rulesets from its configuration + structure (which itself was either created on startup for + per-server context or during the directory walk of the Apache + kernel for per-directory context). Then the URL rewriting + engine is started with the contained ruleset (one or more + rules together with their conditions). The operation of the + URL rewriting engine itself is exactly the same for both + configuration contexts. Only the final result processing is + different. </p> + + <p>The order of rules in the ruleset is important because the + rewriting engine processes them in a special (and not very + obvious) order. The rule is this: The rewriting engine loops + through the ruleset rule by rule (<directive + module="mod_rewrite">RewriteRule</directive> directives) and + when a particular rule matches it optionally loops through + existing corresponding conditions (<code>RewriteCond</code> + directives). For historical reasons the conditions are given + first, and so the control flow is a little bit long-winded. See + Figure 1 for more details.</p> + + <div align="CENTER"> + <table cellspacing="0" cellpadding="2" border="0"> + <tr> + <td bgcolor="#CCCCCC"><img + src="../images/mod_rewrite_fig1.gif" width="428" + height="385" + alt="[Needs graphics capability to display]" /></td> + </tr> + + <tr> + <td align="CENTER"><strong>Figure 1:</strong> The + control flow through the rewriting ruleset</td> + </tr> + </table> + </div> + + <p>As you can see, first the URL is matched against the + <em>Pattern</em> of each rule. When it fails mod_rewrite + immediately stops processing this rule and continues with the + next rule. If the <em>Pattern</em> matches, mod_rewrite looks + for corresponding rule conditions. If none are present, it + just substitutes the URL with a new value which is + constructed from the string <em>Substitution</em> and goes on + with its rule-looping. But if conditions exist, it starts an + inner loop for processing them in the order that they are + listed. For conditions the logic is different: we don't match + a pattern against the current URL. Instead we first create a + string <em>TestString</em> by expanding variables, + back-references, map lookups, <em>etc.</em> and then we try + to match <em>CondPattern</em> against it. If the pattern + doesn't match, the complete set of conditions and the + corresponding rule fails. If the pattern matches, then the + next condition is processed until no more conditions are + available. If all conditions match, processing is continued + with the substitution of the URL with + <em>Substitution</em>.</p> + +</section> + +<section id="quoting"><title>Quoting Special Characters</title> + + <p>As of Apache 1.3.20, special characters in + <i>TestString</i> and <i>Substitution</i> strings can be + escaped (that is, treated as normal characters without their + usual special meaning) by prefixing them with a slosh ('\') + character. In other words, you can include an actual + dollar-sign character in a <i>Substitution</i> string by + using '<code>\$</code>'; this keeps mod_rewrite from trying + to treat it as a backreference.</p> +</section> + +<section id="InternalBackRefs"><title>Regex Back-Reference Availability</title> + + <p>One important thing here has to be remembered: Whenever you + use parentheses in <em>Pattern</em> or in one of the + <em>CondPattern</em>, back-references are internally created + which can be used with the strings <code>$N</code> and + <code>%N</code> (see below). These are available for creating + the strings <em>Substitution</em> and <em>TestString</em>. + Figure 2 shows to which locations the back-references are + transfered for expansion.</p> + + <div align="CENTER"> + <table cellspacing="0" cellpadding="2" border="0"> + <tr> + <td bgcolor="#CCCCCC"><img + src="../images/mod_rewrite_fig2.gif" width="381" + height="179" + alt="[Needs graphics capability to display]" /></td> + </tr> + + <tr> + <td align="CENTER"><strong>Figure 2:</strong> The + back-reference flow through a rule</td> + </tr> + </table> + </div> + + <p>We know this was a crash course on mod_rewrite's internal + processing. But you will benefit from this knowledge when + reading the following documentation of the available + directives.</p> + +</section> +</section> + +<section id="EnvVar"><title>Environment Variables</title> + + <p>This module keeps track of two additional (non-standard) + CGI/SSI environment variables named <code>SCRIPT_URL</code> + and <code>SCRIPT_URI</code>. These contain the + <em>logical</em> Web-view to the current resource, while the + standard CGI/SSI variables <code>SCRIPT_NAME</code> and + <code>SCRIPT_FILENAME</code> contain the <em>physical</em> + System-view. </p> + + <p>Notice: These variables hold the URI/URL <em>as they were + initially requested</em>, <em>i.e.</em>, <em>before</em> any + rewriting. This is important because the rewriting process is + primarily used to rewrite logical URLs to physical + pathnames.</p> + + <p><strong>Example:</strong></p> + +<example> +<pre> +SCRIPT_NAME=/sw/lib/w3s/tree/global/u/rse/.www/index.html +SCRIPT_FILENAME=/u/rse/.www/index.html +SCRIPT_URL=/u/rse/ +SCRIPT_URI=http://en1.engelschall.com/u/rse/ +</pre> +</example> + +</section> + +<section id="Solutions"><title>Practical Solutions</title> + + <p>We also have an <a href="../misc/rewriteguide.html">URL + Rewriting Guide</a> available, which provides a collection of + practical solutions for URL-based problems. There you can + find real-life rulesets and additional information about + mod_rewrite.</p> +</section> + + +<directivesynopsis> + +<name>RewriteEngine</name> + +<summary>Enables or disables runtime rewriting engine</summary> + +<syntax>RewriteEngine on|off</syntax> +<default>RewriteEngine off</default> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context></contextlist> +<override>FileInfo</override> + +<usage> + + <p>The <directive>RewriteEngine</directive> directive enables or + disables the runtime rewriting engine. If it is set to + <code>off</code> this module does no runtime processing at + all. It does not even update the <code>SCRIPT_URx</code> + environment variables.</p> + + <p>Use this directive to disable the module instead of + commenting out all the <directive + module="mod_rewrite">RewriteRule</directive> directives!</p> + + <p>Note that, by default, rewrite configurations are not + inherited. This means that you need to have a + <code>RewriteEngine on</code> directive for each virtual host + in which you wish to use it.</p> +</usage> + +</directivesynopsis> + +<directivesynopsis> +<name>RewriteOptions</name> +<description>Sets some special options for the rewrite engine</description> +<syntax>RewriteOptions <em>Options</em></syntax> +<default>None</default> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context></contextlist> + +<usage> + + <p>The <directive>RewriteOptions</directive> directive sets some + special options for the current per-server or per-directory + configuration. The <em>Option</em> strings can be one of the + following:</p> + + <ul> + <li>'<strong><code>inherit</code></strong>'<br /> + This forces the current configuration to inherit the + configuration of the parent. In per-virtual-server context + this means that the maps, conditions and rules of the main + server are inherited. In per-directory context this means + that conditions and rules of the parent directory's + <code>.htaccess</code> configuration are inherited.</li> + </ul> +</usage> + +</directivesynopsis> + +<directivesynopsis> +<name>RewriteLog</name> +<description>Sets the name of the file used for logging rewrite engine +processing</description> +<syntax>RewriteLog <em>file-path</em></syntax> +<contextlist><context>server config</context><context>virtual host</context> +</contextlist> + +<usage> + <p>The <directive>RewriteLog</directive> directive sets the name + of the file to which the server logs any rewriting actions it + performs. If the name does not begin with a slash + ('<code>/</code>') then it is assumed to be relative to the + <em>Server Root</em>. The directive should occur only once per + server config.</p> + +<note> To disable the logging of + rewriting actions it is not recommended to set + <em>Filename</em> to <code>/dev/null</code>, because + although the rewriting engine does not then output to a + logfile it still creates the logfile output internally. + <strong>This will slow down the server with no advantage + to the administrator!</strong> To disable logging either + remove or comment out the <directive>RewriteLog</directive> + directive or use <code>RewriteLogLevel 0</code>! +</note> + +<note><title>Security</title> + +See the <a href="../misc/security_tips.html">Apache Security Tips</a> +document for details on why your security could be compromised if the +directory where logfiles are stored is writable by anyone other than +the user that starts the server. +</note> + +<example><title>Example</title> +RewriteLog "/usr/local/var/apache/logs/rewrite.log" +</example> + +</usage> + +</directivesynopsis> + +<directivesynopsis> +<name>RewriteLogLevel</name> +<description>Sets the verbosity of the log file used by the rewrite +engine</description> +<syntax>RewriteLogLevel <em>Level</em></syntax> +<default>RerwiteLogLevel 0</default> +<contextlist><context>server config</context><context>virtual host</context> +</contextlist> + +<usage> + <p>The <directive>RewriteLogLevel</directive> directive sets the + verbosity level of the rewriting logfile. The default level 0 + means no logging, while 9 or more means that practically all + actions are logged.</p> + + <p>To disable the logging of rewriting actions simply set + <em>Level</em> to 0. This disables all rewrite action + logs.</p> + +<note> Using a high value for + <em>Level</em> will slow down your Apache server + dramatically! Use the rewriting logfile at a + <em>Level</em> greater than 2 only for debugging! +</note> + +<example><title>Example</title> +RewriteLogLevel 3 +</example> + +</usage> + +</directivesynopsis> + +<directivesynopsis> +<name>RewriteLock</name> +<description>Sets the name of the lock file used for <directive +module="mod_rewrite">RewriteMap</directive> +synchronization</description> +<syntax>RewriteLock <em>file-path</em></syntax> +<default>None</default> +<contextlist><context>server config</context></contextlist> + +<usage> + <p>This directive sets the filename for a synchronization + lockfile which mod_rewrite needs to communicate with <directive + module="mod_rewrite">RewriteMap</directive> + <em>programs</em>. Set this lockfile to a local path (not on a + NFS-mounted device) when you want to use a rewriting + map-program. It is not required for other types of rewriting + maps.</p> +</usage> + +</directivesynopsis> + +<directivesynopsis> +<name>RewriteMap</name> +<description>Defines a mapping function for key-lookup</description> +<syntax>RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em> +</syntax> +<default>None</default> +<contextlist><context>server config</context><context>virtual host</context> +</contextlist> + +<usage> + <p>The <directive>RewriteMap</directive> directive defines a + <em>Rewriting Map</em> which can be used inside rule + substitution strings by the mapping-functions to + insert/substitute fields through a key lookup. The source of + this lookup can be of various types.</p> + + <p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> is + the name of the map and will be used to specify a + mapping-function for the substitution strings of a rewriting + rule via one of the following constructs:</p> + + <blockquote> + <strong><code>${</code> <em>MapName</em> <code>:</code> + <em>LookupKey</em> <code>}</code><br /> + <code>${</code> <em>MapName</em> <code>:</code> + <em>LookupKey</em> <code>|</code> <em>DefaultValue</em> + <code>}</code></strong> + </blockquote> + + <p>When such a construct occurs the map <em>MapName</em> is + consulted and the key <em>LookupKey</em> is looked-up. If the + key is found, the map-function construct is substituted by + <em>SubstValue</em>. If the key is not found then it is + substituted by <em>DefaultValue</em> or by the empty string + if no <em>DefaultValue</em> was specified.</p> + + <p>The following combinations for <em>MapType</em> and + <em>MapSource</em> can be used:</p> + + <ul> + <li> + <strong>Standard Plain Text</strong><br /> + MapType: <code>txt</code>, MapSource: Unix filesystem + path to valid regular file + + <p>This is the standard rewriting map feature where the + <em>MapSource</em> is a plain ASCII file containing + either blank lines, comment lines (starting with a '#' + character) or pairs like the following - one per + line.</p> + + <blockquote> + <strong><em>MatchingKey</em> + <em>SubstValue</em></strong> + </blockquote> + +<example><title>Example</title> +<pre> +## +## map.txt -- rewriting map +## + +Ralf.S.Engelschall rse # Bastard Operator From Hell +Mr.Joe.Average joe # Mr. Average +</pre> +</example> + +<example> +RewriteMap real-to-user txt:/path/to/file/map.txt +</example> + </li> + + <li> + <strong>Randomized Plain Text</strong><br /> + MapType: <code>rnd</code>, MapSource: Unix filesystem + path to valid regular file + + <p>This is identical to the Standard Plain Text variant + above but with a special post-processing feature: After + looking up a value it is parsed according to contained + ``<code>|</code>'' characters which have the meaning of + ``or''. In other words they indicate a set of + alternatives from which the actual returned value is + chosen randomly. Although this sounds crazy and useless, + it was actually designed for load balancing in a reverse + proxy situation where the looked up values are server + names. Example:</p> + +<example> +<pre> +## +## map.txt -- rewriting map +## + +static www1|www2|www3|www4 +dynamic www5|www6 +</pre> +</example> + +<example> +RewriteMap servers rnd:/path/to/file/map.txt +</example> + </li> + + <li> + <strong>Hash File</strong><br /> + MapType: <code>dbm</code>, MapSource: Unix filesystem + path to valid regular file + + <p>Here the source is a binary NDBM format file + containing the same contents as a <em>Plain Text</em> + format file, but in a special representation which is + optimized for really fast lookups. You can create such a + file with any NDBM tool or with the following Perl + script:</p> + +<example> +<pre> +#!/path/to/bin/perl +## +## txt2dbm -- convert txt map to dbm format +## + +use NDBM_File; +use Fcntl; + +($txtmap, $dbmmap) = @ARGV; + +open(TXT, "<$txtmap") or die "Couldn't open $txtmap!\n"; +tie (%DB, 'NDBM_File', $dbmmap,O_RDWR|O_TRUNC|O_CREAT, 0644) or die "Couldn't create $dbmmap!\n"; + +while (<TXT>) { + next if (/^\s*#/ or /^\s*$/); + $DB{$1} = $2 if (/^\s*(\S+)\s+(\S+)/); +} + +untie %DB; +close(TXT); +</pre> +</example> + +<example> +$ txt2dbm map.txt map.db +</example> + </li> + + <li> + <strong>Internal Function</strong><br /> + MapType: <code>int</code>, MapSource: Internal Apache + function + + <p>Here the source is an internal Apache function. + Currently you cannot create your own, but the following + functions already exists:</p> + + <ul> + <li><strong>toupper</strong>:<br /> + Converts the looked up key to all upper case.</li> + + <li><strong>tolower</strong>:<br /> + Converts the looked up key to all lower case.</li> + + <li><strong>escape</strong>:<br /> + Translates special characters in the looked up key to + hex-encodings.</li> + + <li><strong>unescape</strong>:<br /> + Translates hex-encodings in the looked up key back to + special characters.</li> + </ul> + </li> + + <li> + <strong>External Rewriting Program</strong><br /> + MapType: <code>prg</code>, MapSource: Unix filesystem + path to valid regular file + + <p>Here the source is a program, not a map file. To + create it you can use the language of your choice, but + the result has to be a executable (<em>i.e.</em>, either + object-code or a script with the magic cookie trick + '<code>#!/path/to/interpreter</code>' as the first + line).</p> + + <p>This program is started once at startup of the Apache + servers and then communicates with the rewriting engine + over its <code>stdin</code> and <code>stdout</code> + file-handles. For each map-function lookup it will + receive the key to lookup as a newline-terminated string + on <code>stdin</code>. It then has to give back the + looked-up value as a newline-terminated string on + <code>stdout</code> or the four-character string + ``<code>NULL</code>'' if it fails (<em>i.e.</em>, there + is no corresponding value for the given key). A trivial + program which will implement a 1:1 map (<em>i.e.</em>, + key == value) could be:</p> + +<example> +<pre> +#!/usr/bin/perl +$| = 1; +while (<STDIN>) { + # ...put here any transformations or lookups... + print $_; +} +</pre> +</example> + + <p>But be very careful:</p> + + <ol> + <li>``<em>Keep it simple, stupid</em>'' (KISS), because + if this program hangs it will hang the Apache server + when the rule occurs.</li> + + <li>Avoid one common mistake: never do buffered I/O on + <code>stdout</code>! This will cause a deadloop! Hence + the ``<code>$|=1</code>'' in the above example...</li> + + <li>Use the <directive + module="mod_rewrite">RewriteLock</directive> directive to + define a lockfile mod_rewrite can use to synchronize the + communication to the program. By default no such + synchronization takes place.</li> + </ol> + </li> + </ul> + The <directive>RewriteMap</directive> directive can occur more than + once. For each mapping-function use one + <directive>RewriteMap</directive> directive to declare its rewriting + mapfile. While you cannot <strong>declare</strong> a map in + per-directory context it is of course possible to + <strong>use</strong> this map in per-directory context. + +<note><title>Note</title> For plain text and DBM format files the +looked-up keys are cached in-core until the <code>mtime</code> of the +mapfile changes or the server does a restart. This way you can have +map-functions in rules which are used for <strong>every</strong> +request. This is no problem, because the external lookup only happens +once! +</note> + +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>RewriteBase</name> +<description>Sets the base URL for per-directory rewrites</description> +<syntax>RewriteBase <em>URL-path</em></syntax> +<default>RewriteBase <em>physical-directory-path</em></default> +<contextlist><context>directory</context><context>.htaccess</context> +</contextlist> +<override>FileInfo</override> + +<usage> + <p>The <directive>RewriteBase</directive> directive explicitly + sets the base URL for per-directory rewrites. As you will see + below, <directive module="mod_rewrite">RewriteRule</directive> + can be used in per-directory config files + (<code>.htaccess</code>). There it will act locally, + <em>i.e.</em>, the local directory prefix is stripped at this + stage of processing and your rewriting rules act only on the + remainder. At the end it is automatically added back to the + path.</p> + + <p>When a substitution occurs for a new URL, this module has + to re-inject the URL into the server processing. To be able + to do this it needs to know what the corresponding URL-prefix + or URL-base is. By default this prefix is the corresponding + filepath itself. <strong>But at most websites URLs are NOT + directly related to physical filename paths, so this + assumption will usually be wrong!</strong> There you have to + use the <code>RewriteBase</code> directive to specify the + correct URL-prefix.</p> + +<note> If your webserver's URLs are <strong>not</strong> directly +related to physical file paths, you have to use +<directive>RewriteBase</directive> in every <code>.htaccess</code> +files where you want to use <directive +module="mod_rewrite">RewriteRule</directive> directives. +</note> + + <p> For example, assume the following per-directory config file:</p> + +<example> +<pre> +# +# /abc/def/.htaccess -- per-dir config file for directory /abc/def +# Remember: /abc/def is the physical path of /xyz, <em>i.e.</em>, the server +# has a 'Alias /xyz /abc/def' directive <em>e.g.</em> +# + +RewriteEngine On + +# let the server know that we were reached via /xyz and not +# via the physical path prefix /abc/def +RewriteBase /xyz + +# now the rewriting rules +RewriteRule ^oldstuff\.html$ newstuff.html +</pre> +</example> + + <p>In the above example, a request to + <code>/xyz/oldstuff.html</code> gets correctly rewritten to + the physical file <code>/abc/def/newstuff.html</code>.</p> + +<note><title>For Apache Hackers</title> +<p>The following list gives detailed information about + the internal processing steps:</p> +<pre> +<font size="-1">Request: + /xyz/oldstuff.html + +Internal Processing: + /xyz/oldstuff.html -> /abc/def/oldstuff.html (per-server Alias) + /abc/def/oldstuff.html -> /abc/def/newstuff.html (per-dir RewriteRule) + /abc/def/newstuff.html -> /xyz/newstuff.html (per-dir RewriteBase) + /xyz/newstuff.html -> /abc/def/newstuff.html (per-server Alias) + +Result: + /abc/def/newstuff.html +</font> +</pre> + <p><font size="-1">This seems very complicated but is + the correct Apache internal processing, because the + per-directory rewriting comes too late in the + process. So, when it occurs the (rewritten) request + has to be re-injected into the Apache kernel! BUT: + While this seems like a serious overhead, it really + isn't, because this re-injection happens fully + internally to the Apache server and the same + procedure is used by many other operations inside + Apache. So, you can be sure the design and + implementation is correct.</font></p> +</note> + +</usage> + +</directivesynopsis> + +<directivesynopsis> +<name>RewriteCond</name> +<description>Defines a condition under which rewriting will take place +</description> +<syntax> RewriteCond + <em>TestString</em> <em>CondPattern</em></syntax> +<default>None</default> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context></contextlist> +<override>FileInfo</override> + +<usage> + <p>The <directive>RewriteCond</directive> directive defines a + rule condition. Precede a <directive + module="mod_rewrite">RewriteRule</directive> directive with one + or more <directive>RewriteCond</directive> directives. The following + rewriting rule is only used if its pattern matches the current + state of the URI <strong>and</strong> if these additional + conditions apply too.</p> + + <p><em>TestString</em> is a string which can contains the + following expanded constructs in addition to plain text:</p> + + <ul> + <li> + <strong>RewriteRule backreferences</strong>: These are + backreferences of the form + + <blockquote> + <strong><code>$N</code></strong> + </blockquote> + (0 <= N <= 9) which provide access to the grouped + parts (parenthesis!) of the pattern from the + corresponding <code>RewriteRule</code> directive (the one + following the current bunch of <code>RewriteCond</code> + directives). + </li> + + <li> + <strong>RewriteCond backreferences</strong>: These are + backreferences of the form + + <blockquote> + <strong><code>%N</code></strong> + </blockquote> + (1 <= N <= 9) which provide access to the grouped + parts (parentheses!) of the pattern from the last matched + <code>RewriteCond</code> directive in the current bunch + of conditions. + </li> + + <li> + <strong>RewriteMap expansions</strong>: These are + expansions of the form + + <blockquote> + <strong><code>${mapname:key|default}</code></strong> + </blockquote> + See <a href="#mapfunc">the documentation for + RewriteMap</a> for more details. + </li> + + <li> + <strong>Server-Variables</strong>: These are variables of + the form + + <blockquote> + <strong><code>%{</code> <em>NAME_OF_VARIABLE</em> + <code>}</code></strong> + </blockquote> + where <em>NAME_OF_VARIABLE</em> can be a string taken + from the following list: + + <table bgcolor="#F0F0F0" cellspacing="0" cellpadding="5"> + <tr> + <td valign="TOP"> + <strong>HTTP headers:</strong> + + <p><font size="-1">HTTP_USER_AGENT<br /> + HTTP_REFERER<br /> + HTTP_COOKIE<br /> + HTTP_FORWARDED<br /> + HTTP_HOST<br /> + HTTP_PROXY_CONNECTION<br /> + HTTP_ACCEPT<br /> + </font></p> + </td> + + <td valign="TOP"> + <strong>connection & request:</strong> + + <p><font size="-1">REMOTE_ADDR<br /> + REMOTE_HOST<br /> + REMOTE_USER<br /> + REMOTE_IDENT<br /> + REQUEST_METHOD<br /> + SCRIPT_FILENAME<br /> + PATH_INFO<br /> + QUERY_STRING<br /> + AUTH_TYPE<br /> + </font></p> + </td> + </tr> + + <tr> + <td valign="TOP"> + <strong>server internals:</strong> + + <p><font size="-1">DOCUMENT_ROOT<br /> + SERVER_ADMIN<br /> + SERVER_NAME<br /> + SERVER_ADDR<br /> + SERVER_PORT<br /> + SERVER_PROTOCOL<br /> + SERVER_SOFTWARE<br /> + </font></p> + </td> + + <td valign="TOP"> + <strong>system stuff:</strong> + + <p><font size="-1">TIME_YEAR<br /> + TIME_MON<br /> + TIME_DAY<br /> + TIME_HOUR<br /> + TIME_MIN<br /> + TIME_SEC<br /> + TIME_WDAY<br /> + TIME<br /> + </font></p> + </td> + + <td valign="TOP"> + <strong>specials:</strong> + + <p><font size="-1">API_VERSION<br /> + THE_REQUEST<br /> + REQUEST_URI<br /> + REQUEST_FILENAME<br /> + IS_SUBREQ<br /> + </font></p> + </td> + </tr> + </table> + +<note> + <p>These variables all + correspond to the similarly named HTTP + MIME-headers, C variables of the Apache server or + <code>struct tm</code> fields of the Unix system. + Most are documented elsewhere in the Manual or in + the CGI specification. Those that are special to + mod_rewrite include:</p> + + <dl> + <dt><code>IS_SUBREQ</code></dt> + + <dd>Will contain the text "true" if the request + currently being processed is a sub-request, + "false" otherwise. Sub-requests may be generated + by modules that need to resolve additional files + or URIs in order to complete their tasks.</dd> + + <dt><code>API_VERSION</code></dt> + + <dd>This is the version of the Apache module API + (the internal interface between server and + module) in the current httpd build, as defined in + include/ap_mmn.h. The module API version + corresponds to the version of Apache in use (in + the release version of Apache 1.3.14, for + instance, it is 19990320:10), but is mainly of + interest to module authors.</dd> + + <dt><code>THE_REQUEST</code></dt> + + <dd>The full HTTP request line sent by the + browser to the server (e.g., "<code>GET + /index.html HTTP/1.1</code>"). This does not + include any additional headers sent by the + browser.</dd> + + <dt><code>REQUEST_URI</code></dt> + + <dd>The resource requested in the HTTP request + line. (In the example above, this would be + "/index.html".)</dd> + + <dt><code>REQUEST_FILENAME</code></dt> + + <dd>The full local filesystem path to the file or + script matching the request.</dd> + </dl> +</note> + </li> + </ul> + + <p>Special Notes:</p> + + <ol> + <li>The variables SCRIPT_FILENAME and REQUEST_FILENAME + contain the same value, <em>i.e.</em>, the value of the + <code>filename</code> field of the internal + <code>request_rec</code> structure of the Apache server. + The first name is just the commonly known CGI variable name + while the second is the consistent counterpart to + REQUEST_URI (which contains the value of the + <code>uri</code> field of <code>request_rec</code>).</li> + + <li>There is the special format: + <code>%{ENV:variable}</code> where <em>variable</em> can be + any environment variable. This is looked-up via internal + Apache structures and (if not found there) via + <code>getenv()</code> from the Apache server process.</li> + + <li>There is the special format: + <code>%{HTTP:header}</code> where <em>header</em> can be + any HTTP MIME-header name. This is looked-up from the HTTP + request. Example: <code>%{HTTP:Proxy-Connection}</code> is + the value of the HTTP header + ``<code>Proxy-Connection:</code>''.</li> + + <li>There is the special format + <code>%{LA-U:variable}</code> for look-aheads which perform + an internal (URL-based) sub-request to determine the final + value of <em>variable</em>. Use this when you want to use a + variable for rewriting which is actually set later in an + API phase and thus is not available at the current stage. + For instance when you want to rewrite according to the + <code>REMOTE_USER</code> variable from within the + per-server context (<code>httpd.conf</code> file) you have + to use <code>%{LA-U:REMOTE_USER}</code> because this + variable is set by the authorization phases which come + <em>after</em> the URL translation phase where mod_rewrite + operates. On the other hand, because mod_rewrite implements + its per-directory context (<code>.htaccess</code> file) via + the Fixup phase of the API and because the authorization + phases come <em>before</em> this phase, you just can use + <code>%{REMOTE_USER}</code> there.</li> + + <li>There is the special format: + <code>%{LA-F:variable}</code> which performs an internal + (filename-based) sub-request to determine the final value + of <em>variable</em>. Most of the time this is the same as + LA-U above.</li> + </ol> + + <p><em>CondPattern</em> is the condition pattern, + <em>i.e.</em>, a regular expression which is applied to the + current instance of the <em>TestString</em>, <em>i.e.</em>, + <em>TestString</em> is evaluated and then matched against + <em>CondPattern</em>.</p> + + <p><strong>Remember:</strong> <em>CondPattern</em> is a + standard <em>Extended Regular Expression</em> with some + additions:</p> + + <ol> + <li>You can prefix the pattern string with a + '<code>!</code>' character (exclamation mark) to specify a + <strong>non</strong>-matching pattern.</li> + + <li> + There are some special variants of <em>CondPatterns</em>. + Instead of real regular expression strings you can also + use one of the following: + + <ul> + <li>'<strong><CondPattern</strong>' (is lexically + lower)<br /> + Treats the <em>CondPattern</em> as a plain string and + compares it lexically to <em>TestString</em>. True if + <em>TestString</em> is lexically lower than + <em>CondPattern</em>.</li> + + <li>'<strong>>CondPattern</strong>' (is lexically + greater)<br /> + Treats the <em>CondPattern</em> as a plain string and + compares it lexically to <em>TestString</em>. True if + <em>TestString</em> is lexically greater than + <em>CondPattern</em>.</li> + + <li>'<strong>=CondPattern</strong>' (is lexically + equal)<br /> + Treats the <em>CondPattern</em> as a plain string and + compares it lexically to <em>TestString</em>. True if + <em>TestString</em> is lexically equal to + <em>CondPattern</em>, i.e the two strings are exactly + equal (character by character). If <em>CondPattern</em> + is just <samp>""</samp> (two quotation marks) this + compares <em>TestString</em> to the empty string.</li> + + <li>'<strong>-d</strong>' (is + <strong>d</strong>irectory)<br /> + Treats the <em>TestString</em> as a pathname and tests + if it exists and is a directory.</li> + + <li>'<strong>-f</strong>' (is regular + <strong>f</strong>ile)<br /> + Treats the <em>TestString</em> as a pathname and tests + if it exists and is a regular file.</li> + + <li>'<strong>-s</strong>' (is regular file with + <strong>s</strong>ize)<br /> + Treats the <em>TestString</em> as a pathname and tests + if it exists and is a regular file with size greater + than zero.</li> + + <li>'<strong>-l</strong>' (is symbolic + <strong>l</strong>ink)<br /> + Treats the <em>TestString</em> as a pathname and tests + if it exists and is a symbolic link.</li> + + <li>'<strong>-F</strong>' (is existing file via + subrequest)<br /> + Checks if <em>TestString</em> is a valid file and + accessible via all the server's currently-configured + access controls for that path. This uses an internal + subrequest to determine the check, so use it with care + because it decreases your servers performance!</li> + + <li>'<strong>-U</strong>' (is existing URL via + subrequest)<br /> + Checks if <em>TestString</em> is a valid URL and + accessible via all the server's currently-configured + access controls for that path. This uses an internal + subrequest to determine the check, so use it with care + because it decreases your server's performance!</li> + </ul> + +<note><title>Notice</title> + All of these tests can + also be prefixed by an exclamation mark ('!') to + negate their meaning. +</note> + </li> + </ol> + + <p>Additionally you can set special flags for + <em>CondPattern</em> by appending</p> + + <blockquote> + <strong><code>[</code><em>flags</em><code>]</code></strong> + </blockquote> + as the third argument to the <code>RewriteCond</code> + directive. <em>Flags</em> is a comma-separated list of the + following flags: + + <ul> + <li>'<strong><code>nocase|NC</code></strong>' + (<strong>n</strong>o <strong>c</strong>ase)<br /> + This makes the test case-insensitive, <em>i.e.</em>, there + is no difference between 'A-Z' and 'a-z' both in the + expanded <em>TestString</em> and the <em>CondPattern</em>. + This flag is effective only for comparisons between + <em>TestString</em> and <em>CondPattern</em>. It has no + effect on filesystem and subrequest checks.</li> + + <li> + '<strong><code>ornext|OR</code></strong>' + (<strong>or</strong> next condition)<br /> + Use this to combine rule conditions with a local OR + instead of the implicit AND. Typical example: + +<example> +<pre> +RewriteCond %{REMOTE_HOST} ^host1.* [OR] +RewriteCond %{REMOTE_HOST} ^host2.* [OR] +RewriteCond %{REMOTE_HOST} ^host3.* +RewriteRule ...some special stuff for any of these hosts... +</pre> +</example> + + Without this flag you would have to write the cond/rule + three times. + </li> + </ul> + + <p><strong>Example:</strong></p> + + <p>To rewrite the Homepage of a site according to the + ``<code>User-Agent:</code>'' header of the request, you can + use the following: </p> + +<example> +<pre> +RewriteCond %{HTTP_USER_AGENT} ^Mozilla.* +RewriteRule ^/$ /homepage.max.html [L] + +RewriteCond %{HTTP_USER_AGENT} ^Lynx.* +RewriteRule ^/$ /homepage.min.html [L] + +RewriteRule ^/$ /homepage.std.html [L] +</pre> +</example> + + <p>Interpretation: If you use Netscape Navigator as your + browser (which identifies itself as 'Mozilla'), then you + get the max homepage, which includes Frames, <em>etc.</em> + If you use the Lynx browser (which is Terminal-based), then + you get the min homepage, which contains no images, no + tables, <em>etc.</em> If you use any other browser you get + the standard homepage.</p> + +</usage> + +</directivesynopsis> + +<directivesynopsis> +<name>RewriteRule</name> +<description>Defines rules for the rewriting engine</description> +<syntax>RewriteRule + <em>Pattern</em> <em>Substitution</em></syntax> +<default>None</default> +<contextlist><context>server config</context><context>virtual host</context> +<context>directory</context><context>.htaccess</context></contextlist> +<override>FileInfo</override> + +<usage> + <p>The <directive>RewriteRule</directive> directive is the real + rewriting workhorse. The directive can occur more than once. + Each directive then defines one single rewriting rule. The + <strong>definition order</strong> of these rules is + <strong>important</strong>, because this order is used when + applying the rules at run-time.</p> + + <p><a id="patterns" name="patterns"><em>Pattern</em></a> can + be (for Apache 1.1.x a System V8 and for Apache 1.2.x and + later a POSIX) <a id="regexp" name="regexp">regular + expression</a> which gets applied to the current URL. Here + ``current'' means the value of the URL when this rule gets + applied. This may not be the originally requested URL, + because any number of rules may already have matched and made + alterations to it.</p> + + <p>Some hints about the syntax of regular expressions:</p> + + <table bgcolor="#F0F0F0" cellspacing="0" cellpadding="5"> + <tr> + <td valign="TOP"> +<pre> +<strong>Text:</strong> + <strong><code>.</code></strong> Any single character + <strong><code>[</code></strong>chars<strong><code>]</code></strong> Character class: One of chars + <strong><code>[^</code></strong>chars<strong><code>]</code></strong> Character class: None of chars + text1<strong><code>|</code></strong>text2 Alternative: text1 or text2 + +<strong>Quantifiers:</strong> + <strong><code>?</code></strong> 0 or 1 of the preceding text + <strong><code>*</code></strong> 0 or N of the preceding text (N > 0) + <strong><code>+</code></strong> 1 or N of the preceding text (N > 1) + +<strong>Grouping:</strong> + <strong><code>(</code></strong>text<strong><code>)</code></strong> Grouping of text + (either to set the borders of an alternative or + for making backreferences where the <strong>N</strong>th group can + be used on the RHS of a RewriteRule with <code>$</code><strong>N</strong>) + +<strong>Anchors:</strong> + <strong><code>^</code></strong> Start of line anchor + <strong><code>$</code></strong> End of line anchor + +<strong>Escaping:</strong> + <strong><code>\</code></strong>char escape that particular char + (for instance to specify the chars "<code>.[]()</code>" <em>etc.</em>) +</pre> + </td> + </tr> + </table> + + <p>For more information about regular expressions either have + a look at your local regex(3) manpage or its + <code>src/regex/regex.3</code> copy in the Apache 1.3 + distribution. If you are interested in more detailed + information about regular expressions and their variants + (POSIX regex, Perl regex, <em>etc.</em>) have a look at the + following dedicated book on this topic:</p> + + <blockquote> + <em>Mastering Regular Expressions</em><br /> + Jeffrey E.F. Friedl<br /> + Nutshell Handbook Series<br /> + O'Reilly & Associates, Inc. 1997<br /> + ISBN 1-56592-257-3<br /> + </blockquote> + + <p>Additionally in mod_rewrite the NOT character + ('<code>!</code>') is a possible pattern prefix. This gives + you the ability to negate a pattern; to say, for instance: + ``<em>if the current URL does <strong>NOT</strong> match this + pattern</em>''. This can be used for exceptional cases, where + it is easier to match the negative pattern, or as a last + default rule.</p> + +<note><title>Notice</title> +When using the NOT character + to negate a pattern you cannot have grouped wildcard + parts in the pattern. This is impossible because when the + pattern does NOT match, there are no contents for the + groups. In consequence, if negated patterns are used, you + cannot use <code>$N</code> in the substitution + string! +</note> + + <p><a id="rhs" name="rhs"><em>Substitution</em></a> of a + rewriting rule is the string which is substituted for (or + replaces) the original URL for which <em>Pattern</em> + matched. Beside plain text you can use</p> + + <ol> + <li>back-references <code>$N</code> to the RewriteRule + pattern</li> + + <li>back-references <code>%N</code> to the last matched + RewriteCond pattern</li> + + <li>server-variables as in rule condition test-strings + (<code>%{VARNAME}</code>)</li> + + <li><a href="#mapfunc">mapping-function</a> calls + (<code>${mapname:key|default}</code>)</li> + </ol> + Back-references are <code>$</code><strong>N</strong> + (<strong>N</strong>=0..9) identifiers which will be replaced + by the contents of the <strong>N</strong>th group of the + matched <em>Pattern</em>. The server-variables are the same + as for the <em>TestString</em> of a <code>RewriteCond</code> + directive. The mapping-functions come from the + <code>RewriteMap</code> directive and are explained there. + These three types of variables are expanded in the order of + the above list. + + <p>As already mentioned above, all the rewriting rules are + applied to the <em>Substitution</em> (in the order of + definition in the config file). The URL is <strong>completely + replaced</strong> by the <em>Substitution</em> and the + rewriting process goes on until there are no more rules + unless explicitly terminated by a + <code><strong>L</strong></code> flag - see below.</p> + + <p>There is a special substitution string named + '<code>-</code>' which means: <strong>NO + substitution</strong>! Sounds silly? No, it is useful to + provide rewriting rules which <strong>only</strong> match + some URLs but do no substitution, <em>e.g.</em>, in + conjunction with the <strong>C</strong> (chain) flag to be + able to have more than one pattern to be applied before a + substitution occurs.</p> + + <p>One more note: You can even create URLs in the + substitution string containing a query string part. Just use + a question mark inside the substitution string to indicate + that the following stuff should be re-injected into the + QUERY_STRING. When you want to erase an existing query + string, end the substitution string with just the question + mark.</p> + +<note><title>Note</title> +There is a special feature: + When you prefix a substitution field with + <code>http://</code><em>thishost</em>[<em>:thisport</em>] + then <strong>mod_rewrite</strong> automatically strips it + out. This auto-reduction on implicit external redirect + URLs is a useful and important feature when used in + combination with a mapping-function which generates the + hostname part. Have a look at the first example in the + example section below to understand this. +</note> + +<note><title>Remember</title> + An unconditional external + redirect to your own server will not work with the prefix + <code>http://thishost</code> because of this feature. To + achieve such a self-redirect, you have to use the + <strong>R</strong>-flag (see below). +</note> + + <p>Additionally you can set special flags for + <em>Substitution</em> by appending</p> + + <blockquote> + <strong><code>[</code><em>flags</em><code>]</code></strong> + </blockquote> + as the third argument to the <code>RewriteRule</code> + directive. <em>Flags</em> is a comma-separated list of the + following flags: + + <ul> + <li> + '<strong><code>redirect|R</code> + [=<em>code</em>]</strong>' (force <a id="redirect" + name="redirect"><strong>r</strong>edirect</a>)<br /> + Prefix <em>Substitution</em> with + <code>http://thishost[:thisport]/</code> (which makes the + new URL a URI) to force a external redirection. If no + <em>code</em> is given a HTTP response of 302 (MOVED + TEMPORARILY) is used. If you want to use other response + codes in the range 300-400 just specify them as a number + or use one of the following symbolic names: + <code>temp</code> (default), <code>permanent</code>, + <code>seeother</code>. Use it for rules which should + canonicalize the URL and give it back to the client, + <em>e.g.</em>, translate ``<code>/~</code>'' into + ``<code>/u/</code>'' or always append a slash to + <code>/u/</code><em>user</em>, etc.<br /> + + + <p><strong>Note:</strong> When you use this flag, make + sure that the substitution field is a valid URL! If not, + you are redirecting to an invalid location! And remember + that this flag itself only prefixes the URL with + <code>http://thishost[:thisport]/</code>, rewriting + continues. Usually you also want to stop and do the + redirection immediately. To stop the rewriting you also + have to provide the 'L' flag.</p> + </li> + + <li>'<strong><code>forbidden|F</code></strong>' (force URL + to be <strong>f</strong>orbidden)<br /> + This forces the current URL to be forbidden, + <em>i.e.</em>, it immediately sends back a HTTP response of + 403 (FORBIDDEN). Use this flag in conjunction with + appropriate RewriteConds to conditionally block some + URLs.</li> + + <li>'<strong><code>gone|G</code></strong>' (force URL to be + <strong>g</strong>one)<br /> + This forces the current URL to be gone, <em>i.e.</em>, it + immediately sends back a HTTP response of 410 (GONE). Use + this flag to mark pages which no longer exist as gone.</li> + + <li> + '<strong><code>proxy|P</code></strong>' (force + <strong>p</strong>roxy)<br /> + This flag forces the substitution part to be internally + forced as a proxy request and immediately (<em>i.e.</em>, + rewriting rule processing stops here) put through the <a + href="mod_proxy.html">proxy module</a>. You have to make + sure that the substitution string is a valid URI + (<em>e.g.</em>, typically starting with + <code>http://</code><em>hostname</em>) which can be + handled by the Apache proxy module. If not you get an + error from the proxy module. Use this flag to achieve a + more powerful implementation of the <a + href="mod_proxy.html#proxypass">ProxyPass</a> directive, + to map some remote stuff into the namespace of the local + server. + + <p>Notice: To use this functionality make sure you have + the proxy module compiled into your Apache server + program. If you don't know please check whether + <code>mod_proxy.c</code> is part of the ``<code>httpd + -l</code>'' output. If yes, this functionality is + available to mod_rewrite. If not, then you first have to + rebuild the ``<code>httpd</code>'' program with mod_proxy + enabled.</p> + </li> + + <li>'<strong><code>last|L</code></strong>' + (<strong>l</strong>ast rule)<br /> + Stop the rewriting process here and don't apply any more + rewriting rules. This corresponds to the Perl + <code>last</code> command or the <code>break</code> command + from the C language. Use this flag to prevent the currently + rewritten URL from being rewritten further by following + rules. For example, use it to rewrite the root-path URL + ('<code>/</code>') to a real one, <em>e.g.</em>, + '<code>/e/www/</code>'.</li> + + <li>'<strong><code>next|N</code></strong>' + (<strong>n</strong>ext round)<br /> + Re-run the rewriting process (starting again with the + first rewriting rule). Here the URL to match is again not + the original URL but the URL from the last rewriting rule. + This corresponds to the Perl <code>next</code> command or + the <code>continue</code> command from the C language. Use + this flag to restart the rewriting process, <em>i.e.</em>, + to immediately go to the top of the loop.<br /> + <strong>But be careful not to create an infinite + loop!</strong></li> + + <li>'<strong><code>chain|C</code></strong>' + (<strong>c</strong>hained with next rule)<br /> + This flag chains the current rule with the next rule + (which itself can be chained with the following rule, + <em>etc.</em>). This has the following effect: if a rule + matches, then processing continues as usual, <em>i.e.</em>, + the flag has no effect. If the rule does + <strong>not</strong> match, then all following chained + rules are skipped. For instance, use it to remove the + ``<code>.www</code>'' part inside a per-directory rule set + when you let an external redirect happen (where the + ``<code>.www</code>'' part should not to occur!).</li> + + <li> + '<strong><code>type|T</code></strong>=<em>MIME-type</em>' + (force MIME <strong>t</strong>ype)<br /> + Force the MIME-type of the target file to be + <em>MIME-type</em>. For instance, this can be used to + simulate the <code>mod_alias</code> directive + <code>ScriptAlias</code> which internally forces all files + inside the mapped directory to have a MIME type of + ``<code>application/x-httpd-cgi</code>''.</li> + + <li> + '<strong><code>nosubreq|NS</code></strong>' (used only if + <strong>n</strong>o internal + <strong>s</strong>ub-request)<br /> + This flag forces the rewriting engine to skip a + rewriting rule if the current request is an internal + sub-request. For instance, sub-requests occur internally + in Apache when <code>mod_include</code> tries to find out + information about possible directory default files + (<code>index.xxx</code>). On sub-requests it is not + always useful and even sometimes causes a failure to if + the complete set of rules are applied. Use this flag to + exclude some rules.<br /> + + + <p>Use the following rule for your decision: whenever you + prefix some URLs with CGI-scripts to force them to be + processed by the CGI-script, the chance is high that you + will run into problems (or even overhead) on + sub-requests. In these cases, use this flag.</p> + </li> + + <li>'<strong><code>nocase|NC</code></strong>' + (<strong>n</strong>o <strong>c</strong>ase)<br /> + This makes the <em>Pattern</em> case-insensitive, + <em>i.e.</em>, there is no difference between 'A-Z' and + 'a-z' when <em>Pattern</em> is matched against the current + URL.</li> + + <li>'<strong><code>qsappend|QSA</code></strong>' + (<strong>q</strong>uery <strong>s</strong>tring + <strong>a</strong>ppend)<br /> + This flag forces the rewriting engine to append a query + string part in the substitution string to the existing one + instead of replacing it. Use this when you want to add more + data to the query string via a rewrite rule.</li> + + <li> + '<strong><code>noescape|NE</code></strong>' + (<strong>n</strong>o URI <strong>e</strong>scaping of + output)<br /> + This flag keeps mod_rewrite from applying the usual URI + escaping rules to the result of a rewrite. Ordinarily, + special characters (such as '%', '$', ';', and so on) + will be escaped into their hexcode equivalents ('%25', + '%24', and '%3B', respectively); this flag prevents this + from being done. This allows percent symbols to appear in + the output, as in +<example> + RewriteRule /foo/(.*) /bar?arg=P1\%3d$1 [R,NE] +</example> + + which would turn '<code>/foo/zed</code>' into a safe + request for '<code>/bar?arg=P1=zed</code>'. + </li> + + <li> + '<strong><code>passthrough|PT</code></strong>' + (<strong>p</strong>ass <strong>t</strong>hrough to next + handler)<br /> + This flag forces the rewriting engine to set the + <code>uri</code> field of the internal + <code>request_rec</code> structure to the value of the + <code>filename</code> field. This flag is just a hack to + be able to post-process the output of + <code>RewriteRule</code> directives by + <code>Alias</code>, <code>ScriptAlias</code>, + <code>Redirect</code>, <em>etc.</em> directives from + other URI-to-filename translators. A trivial example to + show the semantics: If you want to rewrite + <code>/abc</code> to <code>/def</code> via the rewriting + engine of <code>mod_rewrite</code> and then + <code>/def</code> to <code>/ghi</code> with + <code>mod_alias</code>: +<example> + RewriteRule ^/abc(.*) /def$1 [PT]<br /> + Alias /def /ghi +</example> + If you omit the <code>PT</code> flag then + <code>mod_rewrite</code> will do its job fine, + <em>i.e.</em>, it rewrites <code>uri=/abc/...</code> to + <code>filename=/def/...</code> as a full API-compliant + URI-to-filename translator should do. Then + <code>mod_alias</code> comes and tries to do a + URI-to-filename transition which will not work. + + <p>Note: <strong>You have to use this flag if you want to + intermix directives of different modules which contain + URL-to-filename translators</strong>. The typical example + is the use of <code>mod_alias</code> and + <code>mod_rewrite</code>..</p> + +<note><title>For Apache hackers</title> + If the current Apache API had a filename-to-filename + hook additionally to the URI-to-filename hook then we + wouldn't need this flag! But without such a hook this + flag is the only solution. The Apache Group has + discussed this problem and will add such a hook in + Apache version 2.0. +</note> + </li> + + <li>'<strong><code>skip|S</code></strong>=<em>num</em>' + (<strong>s</strong>kip next rule(s))<br /> + This flag forces the rewriting engine to skip the next + <em>num</em> rules in sequence when the current rule + matches. Use this to make pseudo if-then-else constructs: + The last rule of the then-clause becomes + <code>skip=N</code> where N is the number of rules in the + else-clause. (This is <strong>not</strong> the same as the + 'chain|C' flag!)</li> + + <li> + '<strong><code>env|E=</code></strong><em>VAR</em>:<em>VAL</em>' + (set <strong>e</strong>nvironment variable)<br /> + This forces an environment variable named <em>VAR</em> to + be set to the value <em>VAL</em>, where <em>VAL</em> can + contain regexp backreferences <code>$N</code> and + <code>%N</code> which will be expanded. You can use this + flag more than once to set more than one variable. The + variables can be later dereferenced in many situations, but + usually from within XSSI (via <code><!--#echo + var="VAR"--></code>) or CGI (<em>e.g.</em> + <code>$ENV{'VAR'}</code>). Additionally you can dereference + it in a following RewriteCond pattern via + <code>%{ENV:VAR}</code>. Use this to strip but remember + information from URLs.</li> + </ul> + +<note><title>Note</title> Never forget that <em>Pattern</em> is +applied to a complete URL in per-server configuration +files. <strong>But in per-directory configuration files, the +per-directory prefix (which always is the same for a specific +directory!) is automatically <em>removed</em> for the pattern matching +and automatically <em>added</em> after the substitution has been +done.</strong> This feature is essential for many sorts of rewriting, +because without this prefix stripping you have to match the parent +directory which is not always possible. + + <p>There is one exception: If a substitution string + starts with ``<code>http://</code>'' then the directory + prefix will <strong>not</strong> be added and an + external redirect or proxy throughput (if flag + <strong>P</strong> is used!) is forced!</p> +</note> + +<note><title>Note</title> + To enable the rewriting engine + for per-directory configuration files you need to set + ``<code>RewriteEngine On</code>'' in these files + <strong>and</strong> ``<code>Options + FollowSymLinks</code>'' must be enabled. If your + administrator has disabled override of + <code>FollowSymLinks</code> for a user's directory, then + you cannot use the rewriting engine. This restriction is + needed for security reasons. +</note> + + <p>Here are all possible substitution combinations and their + meanings:</p> + + <p><strong>Inside per-server configuration + (<code>httpd.conf</code>)<br /> + for request ``<code>GET + /somepath/pathinfo</code>'':</strong><br /> + </p> + + <table bgcolor="#F0F0F0" cellspacing="0" cellpadding="5"> + <tr> + <td> +<pre> +<strong>Given Rule</strong> <strong>Resulting Substitution</strong> +---------------------------------------------- ---------------------------------- +^/somepath(.*) otherpath$1 not supported, because invalid! + +^/somepath(.*) otherpath$1 [R] not supported, because invalid! + +^/somepath(.*) otherpath$1 [P] not supported, because invalid! +---------------------------------------------- ---------------------------------- +^/somepath(.*) /otherpath$1 /otherpath/pathinfo + +^/somepath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo + via external redirection + +^/somepath(.*) /otherpath$1 [P] not supported, because silly! +---------------------------------------------- ---------------------------------- +^/somepath(.*) http://thishost/otherpath$1 /otherpath/pathinfo + +^/somepath(.*) http://thishost/otherpath$1 [R] http://thishost/otherpath/pathinfo + via external redirection + +^/somepath(.*) http://thishost/otherpath$1 [P] not supported, because silly! +---------------------------------------------- ---------------------------------- +^/somepath(.*) http://otherhost/otherpath$1 http://otherhost/otherpath/pathinfo + via external redirection + +^/somepath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo + via external redirection + (the [R] flag is redundant) + +^/somepath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo + via internal proxy +</pre> + </td> + </tr> + </table> + + <p><strong>Inside per-directory configuration for + <code>/somepath</code><br /> + (<em>i.e.</em>, file <code>.htaccess</code> in dir + <code>/physical/path/to/somepath</code> containing + <code>RewriteBase /somepath</code>)<br /> + for request ``<code>GET + /somepath/localpath/pathinfo</code>'':</strong><br /> + </p> + + <table bgcolor="#F0F0F0" cellspacing="0" cellpadding="5"> + <tr> + <td> +<pre> +<strong>Given Rule</strong> <strong>Resulting Substitution</strong> +---------------------------------------------- ---------------------------------- +^localpath(.*) otherpath$1 /somepath/otherpath/pathinfo + +^localpath(.*) otherpath$1 [R] http://thishost/somepath/otherpath/pathinfo + via external redirection + +^localpath(.*) otherpath$1 [P] not supported, because silly! +---------------------------------------------- ---------------------------------- +^localpath(.*) /otherpath$1 /otherpath/pathinfo + +^localpath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo + via external redirection + +^localpath(.*) /otherpath$1 [P] not supported, because silly! +---------------------------------------------- ---------------------------------- +^localpath(.*) http://thishost/otherpath$1 /otherpath/pathinfo + +^localpath(.*) http://thishost/otherpath$1 [R] http://thishost/otherpath/pathinfo + via external redirection + +^localpath(.*) http://thishost/otherpath$1 [P] not supported, because silly! +---------------------------------------------- ---------------------------------- +^localpath(.*) http://otherhost/otherpath$1 http://otherhost/otherpath/pathinfo + via external redirection + +^localpath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo + via external redirection + (the [R] flag is redundant) + +^localpath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo + via internal proxy +</pre> + </td> + </tr> + </table> + + <p><strong>Example:</strong></p> + + <p>We want to rewrite URLs of the form </p> + + <blockquote> + <code>/</code> <em>Language</em> <code>/~</code> + <em>Realname</em> <code>/.../</code> <em>File</em> + </blockquote> + into + + <blockquote> + <code>/u/</code> <em>Username</em> <code>/.../</code> + <em>File</em> <code>.</code> <em>Language</em> + </blockquote> + + <p>We take the rewrite mapfile from above and save it under + <code>/path/to/file/map.txt</code>. Then we only have to + add the following lines to the Apache server configuration + file:</p> + +<example> +<pre> +RewriteLog /path/to/file/rewrite.log +RewriteMap real-to-user txt:/path/to/file/map.txt +RewriteRule ^/([^/]+)/~([^/]+)/(.*)$ /u/${real-to-user:$2|nobody}/$3.$1 +</pre> +</example> + +</usage> +</directivesynopsis> + +</modulesynopsis> + diff --git a/docs/manual/mod/mod_setenvif.xml b/docs/manual/mod/mod_setenvif.xml new file mode 100644 index 0000000000..41bc4ddb04 --- /dev/null +++ b/docs/manual/mod/mod_setenvif.xml @@ -0,0 +1,258 @@ +<?xml version="1.0"?> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>mod_setenvif</name> +<status>Base</status> +<identifier>setenvif_module</identifier> +<sourcefile>mod_setenvif.c</sourcefile> +<compatibility>Available in Apache 1.3 and later</compatibility> + +<description>Allows the setting of environment variables based +on characteristics of the request</description> + +<summary> + + <p>The <module>mod_setenvif</module> module allows you to set + environment variables according to whether different aspects of + the request match regular expressions you specify. These + environment variables can be used by other parts of the server + to make decisions about actions to be taken.</p> + + <p>The directives are considered in the order they appear in + the configuration files. So more complex sequences can be used, + such as this example, which sets <code>netscape</code> if the + browser is mozilla but not MSIE.</p> + +<example> + BrowserMatch ^Mozilla netscape<br /> + BrowserMatch MSIE !netscape<br /> +</example> +</summary> + +<seealso><a href="../env.html">Environment Variables in Apache</a></seealso> + +<directivesynopsis> +<name>BrowserMatch</name> +<description>Sets environment variables conditional on HTTP User-Agent +</description> +<syntax>BrowserMatch <em>regex env-variable</em>[=<em>value</em>] +[<em>env-variable</em>[=<em>value</em>]] ...</syntax> +<default><i>none</i></default> +<context>server config, virtual host, directory, .htaccess</context> +<override>FileInfo</override> +<compatibility>Apache 1.2 and + above (in Apache 1.2 this directive was found in the + now-obsolete mod_browser module)</compatibility> + +<usage> + <p>The <directive>BrowserMatch</directive> directive defines + environment variables based on the <code>User-Agent</code> HTTP + request header field. The first argument should be a POSIX.2 + extended regular expression (similar to an + <code>egrep</code>-style regex). The rest of the arguments give + the names of variables to set, and optionally values to which they + should be set. These take the form of</p> + + <ol> + <li><code><em>varname</em></code>, or</li> + + <li><code>!<em>varname</em></code>, or</li> + + <li><code><em>varname</em>=<em>value</em></code></li> + </ol> + + <p>In the first form, the value will be set to "1". The second + will remove the given variable if already defined, and the + third will set the variable to the value given by + <code><em>value</em></code>. If a <code>User-Agent</code> + string matches more than one entry, they will be merged. + Entries are processed in the order in which they appear, and + later entries can override earlier ones.</p> + + <p>For example:</p> +<example> + BrowserMatch ^Mozilla forms jpeg=yes browser=netscape<br /> + BrowserMatch "^Mozilla/[2-3]" tables agif frames javascript<br /> + BrowserMatch MSIE !javascript<br /> +</example> + + <p>Note that the regular expression string is + <strong>case-sensitive</strong>. For case-INsensitive matching, + see the <directive + module="mod_setenvif">BrowserMatchNoCase</directive> + directive.</p> + + <p>The <directive>BrowserMatch</directive> and + <directive>BrowserMatchNoCase</directive> directives are special cases of + the <directive module="mod_setenvif">SetEnvIf</directive> and <directive + module="mod_setenvif">SetEnvIfNoCase</directive> + directives. The following two lines have the same effect:</p> +<example> + BrowserMatchNoCase Robot is_a_robot<br /> + SetEnvIfNoCase User-Agent Robot is_a_robot<br /> +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>BrowserMatchNoCase</name> +<description>Sets environment variables conditional on User-Agent without +respect to case</description> +<syntax>BrowserMatchNoCase <em>regex env-variable</em>[=<em>value</em>] + [<em>env-variable</em>[=<em>value</em>]] ...</syntax> +<default><em>none</em></default> +<context>server config, virtual host, directory, .htaccess</context> +<override>FileInfo</override> +<compatibility>Apache 1.2 and + above (in Apache 1.2 this directive was found in the + now-obsolete mod_browser module)</compatibility> + +<usage> + + <p>The <directive>BrowserMatchNoCase</directive> directive is + semantically identical to the <directive + module="mod_setenvif">BrowserMatch</directive> directive. + However, it provides for case-insensitive matching. For + example:</p> +<example> + BrowserMatchNoCase mac platform=macintosh<br /> + BrowserMatchNoCase win platform=windows<br /> +</example> + + <p>The <directive>BrowserMatch</directive> and + <directive>BrowserMatchNoCase</directive> directives are special cases of + the <directive module="mod_setenvif">SetEnvIf</directive> and <directive + module="mod_setenvif">SetEnvIfNoCase</directive> + directives. The following two lines have the same effect:</p> +<example> + BrowserMatchNoCase Robot is_a_robot<br /> + SetEnvIfNoCase User-Agent Robot is_a_robot<br /> +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>SetEnvIf</name> +<description>Sets environment variables based on attributes of the request +</description> +<syntax>SetEnvIf <em>attribute + regex env-variable</em>[=<em>value</em>] + [<em>env-variable</em>[=<em>value</em>]] ...</syntax> +<default><em>none</em></default> +<context> server config, virtual host, directory, .htaccess</context> +<override>FileInfo</override> +<compatibility>Apache 1.3 and + above; the Request_Protocol keyword and environment-variable + matching are only available with 1.3.7 and later</compatibility> + +<usage> + <p>The <directive>SetEnvIf</directive> directive defines environment + variables based on attributes of the request. These attributes + can be the values of various HTTP request header fields (see <a + href="http://www.rfc-editor.org/rfc/rfc2616.txt">RFC2616</a> + for more information about these), or of other aspects of the + request, including the following:</p> + + <ul> + <li><code>Remote_Host</code> - the hostname (if available) of + the client making the request</li> + + <li><code>Remote_Addr</code> - the IP address of the client + making the request</li> + + <li><code>Remote_User</code> - the authenticated username (if + available)</li> + + <li><code>Request_Method</code> - the name of the method + being used (<code>GET</code>, <code>POST</code>, <em>et + cetera</em>)</li> + + <li><code>Request_Protocol</code> - the name and version of + the protocol with which the request was made (<em>e.g.</em>, + "HTTP/0.9", "HTTP/1.1", <em>etc.</em>)</li> + + <li><code>Request_URI</code> - the portion of the URL + following the scheme and host portion</li> + </ul> + + <p>Some of the more commonly used request header field names + include <code>Host</code>, <code>User-Agent</code>, and + <code>Referer</code>.</p> + + <p>If the <em>attribute</em> name doesn't match any of the + special keywords, nor any of the request's header field names, + it is tested as the name of an environment variable in the list + of those associated with the request. This allows + <directive>SetEnvIf</directive> directives to test against the result of + prior matches.</p> + +<note> + <strong>Only those environment variables defined by earlier + <code>SetEnvIf[NoCase]</code> directives are available for + testing in this manner. 'Earlier' means that they were + defined at a broader scope (such as server-wide) or + previously in the current directive's scope.</strong> +</note> + + <p><em>attribute</em> may be a regular expression when used to + match a request header. If <em>attribute</em> is a regular + expression and it doesn't match any of the request's header + names, then <em>attribute</em> is not tested against the + request's environment variable list.</p> + +<example> +<title>Example:</title> + SetEnvIf Request_URI "\.gif$" object_is_image=gif<br /> + SetEnvIf Request_URI "\.jpg$" object_is_image=jpg<br /> + SetEnvIf Request_URI "\.xbm$" object_is_image=xbm<br /> + :<br /> + SetEnvIf Referer www\.mydomain\.com intra_site_referral<br /> + :<br /> + SetEnvIf object_is_image xbm XBIT_PROCESSING=1<br /> + :<br /> + SetEnvIf ^TS* ^[a-z].* HAVE_TS<br /> +</example> + + <p>The first three will set the environment variable + <code>object_is_image</code> if the request was for an image + file, and the fourth sets <code>intra_site_referral</code> if + the referring page was somewhere on the + <code>www.mydomain.com</code> Web site.</p> + + <p>The last example will set environment variable + <code>HAVE_TS</code> if the request contains any headers that + begin with "TS" whose values begins with any character in the + set [a-z].</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>SetEnvIfNoCase</name> +<description>Sets environment variables based on attributes of the request +without respect to case</description> +<syntax>SetEnvIfNoCase <em>attribute regex env-variable</em>[=<em>value</em>] + [<em>env-variable</em>[=<em>value</em>]] ...</syntax> +<default><em>none</em></default> +<context>server config, virtual host, directory, .htaccess</context> +<override>FileInfo</override> +<compatibility>Apache 1.3 and above</compatibility> + +<usage> + + <p>The <directive>SetEnvIfNoCase</directive> is semantically identical to + the <directive module="mod_setenvif">SetEnvIf</directive> directive, + and differs only in that the regular expression matching is + performed in a case-insensitive manner. For example:</p> +<example> + SetEnvIfNoCase Host Apache\.Org site=apache +</example> + + <p>This will cause the <code>site</code> environment variable + to be set to "<code>apache</code>" if the HTTP request header + field <code>Host:</code> was included and contained + <code>Apache.Org</code>, <code>apache.org</code>, or any other + combination.</p> +</usage> +</directivesynopsis> +</modulesynopsis>
\ No newline at end of file diff --git a/docs/manual/mod/mod_so.xml b/docs/manual/mod/mod_so.xml new file mode 100755 index 0000000000..2c510b9249 --- /dev/null +++ b/docs/manual/mod/mod_so.xml @@ -0,0 +1,157 @@ +<?xml version="1.0"?> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>mod_so</name> +<status>Base (Windows>; Optional (Unix)</status> +<identifier>so_module</identifier> +<sourcefile>mod_so.c</sourcefile> +<compatibility>Available in Apache 1.3 and later.</compatibility> + +<description> +This module provides for loading of executable code and +modules into the server at start-up or restart time.</description> + +<summary> + + <p>On selected operating systems this module can be used to + load modules into Apache at runtime via the <a + href="../dso.html">Dynamic Shared Object</a> (DSO) mechanism, + rather than requiring a recompilation.</p> + + <p>On Unix, the loaded code typically comes from shared object + files (usually with <samp>.so</samp> extension), on Windows + this may either the <samp>.so</samp> or <samp>.dll</samp> + extension. This module is only available in Apache 1.3 and + up.</p> + + <p>In previous releases, the functionality of this module was + provided for Unix by mod_dld, and for Windows by mod_dll. On + Windows, mod_dll was used in beta release 1.3b1 through 1.3b5. + mod_so combines these two modules into a single module for all + operating systems.</p> + + <p><strong>Warning: Apache 1.3 modules cannot be directly used + with Apache 2.0 - the module must be modified to dynamically + load or compile into Apache 2.0</strong>.</p> +</summary> + +<section><title id="creating">Creating Loadable Modules +for Windows</title> + + <p><note>Note: the module name format changed for Windows + with Apache 1.3.15 and 2.0 - the modules are now named as + mod_foo.so</note>. While mod_so still loads modules with + ApacheModuleFoo.dll names, the new naming convention is + preferred; if you are converting your loadable module for 2.0, + please fix the name to this 2.0 convention.</p> + + <p>The Apache module API is unchanged between the Unix and + Windows versions. Many modules will run on Windows with no or + little change from Unix, although others rely on aspects of the + Unix architecture which are not present in Windows, and will + not work.</p> + + <p>When a module does work, it can be added to the server in + one of two ways. As with Unix, it can be compiled into the + server. Because Apache for Windows does not have the + <code>Configure</code> program of Apache for Unix, the module's + source file must be added to the ApacheCore project file, and + its symbols must be added to the + <code>os\win32\modules.c</code> file.</p> + + <p>The second way is to compile the module as a DLL, a shared + library that can be loaded into the server at runtime, using + the <code><directive>LoadModule</directive></code> + directive. These module DLLs can be distributed and run on any + Apache for Windows installation, without recompilation of the + server.</p> + + <p>To create a module DLL, a small change is necessary to the + module's source file: The module record must be exported from + the DLL (which will be created later; see below). To do this, + add the <code>AP_MODULE_DECLARE_DATA</code> (defined in the + Apache header files) to your module's module record definition. + For example, if your module has:</p> + +<example> + module foo_module; +</example> + + <p>Replace the above with:</p> +<example> + module AP_MODULE_DECLARE_DATA foo_module; +</example> + + <p>Note that this will only be activated on Windows, so the + module can continue to be used, unchanged, with Unix if needed. + Also, if you are familiar with <code>.DEF</code> files, you can + export the module record with that method instead.</p> + + <p>Now, create a DLL containing your module. You will need to + link this against the libhttpd.lib export library that is + created when the libhttpd.dll shared library is compiled. You + may also have to change the compiler settings to ensure that + the Apache header files are correctly located. You can find + this library in your server root's modules directory. It is + best to grab an existing module .dsp file from the tree to + assure the build environment is configured correctly, or + alternately compare the compiler and link options to your + .dsp.</p> + + <p>This should create a DLL version of your module. Now simply + place it in the <samp>modules</samp> directory of your server + root, and use the <directive>LoadModule</directive> + directive to load it.</p> + +</section> + +<directivesynopsis> +<name>LoadFile</name> +<syntax>LoadFile <em>filename</em> [<em>filename</em>] ...</syntax> +<default>none</default> +<contextlist> +<context>server config</context> +</contextlist> +<description>Link in the named object file or library</description> + +<usage> + + <p>The LoadFile directive links in the named object files or + libraries when the server is started or restarted; this is used + to load additional code which may be required for some module + to work. <em>Filename</em> is either an absolute path or + relative to <a href="core.html#serverroot">ServerRoot</a>.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>LoadModule</name> +<syntax>LoadModule <em>module filename</em></syntax> +<default>none</default> +<contextlist> +<context>server config</context> +</contextlist> +<description>Links in the object file or library, and adds to the list +of active modules</description> + +<usage> + <p>The LoadModule directive links in the object file or library + <em>filename</em> and adds the module structure named + <em>module</em> to the list of active modules. <em>Module</em> + is the name of the external variable of type + <code>module</code> in the file, and is listed as the <a + href="module-dict.html#ModuleIdentifier">Module Identifier</a> + in the module documentation. Example:</p> + + <example> + LoadModule status_module modules/mod_status.so + </example> + + <p>loads the named module from the modules subdirectory of the + ServerRoot.</p> +</usage> + +</directivesynopsis> +</modulesynopsis> + diff --git a/docs/manual/mod/mod_speling.xml b/docs/manual/mod/mod_speling.xml new file mode 100755 index 0000000000..dd6df25b74 --- /dev/null +++ b/docs/manual/mod/mod_speling.xml @@ -0,0 +1,96 @@ +<?xml version="1.0"?> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>mod_speling</name> +<status>Extension</status> +<identifier>speling_module</identifier> +<sourcefile>mod_speling.c</sourcefile> +<compatibility>Available in Apache 1.3 and later. Available as +an External module in Apache 1.1 and later.</compatibility> + +<description>This module attempts to correct misspellings of URLs that +users might have entered, by ignoring capitalization and by +allowing up to one misspelling.</description> + +<summary> + + <p>Requests to documents sometimes cannot be served by the core + apache server because the request was misspelled or + miscapitalized. This module addresses this problem by trying to + find a matching document, even after all other modules gave up. + It does its work by comparing each document name in the + requested directory against the requested document name + <strong>without regard to case</strong>, and allowing + <strong>up to one misspelling</strong> (character insertion / + omission / transposition or wrong character). A list is built + with all document names which were matched using this + strategy.</p> + + <p>If, after scanning the directory,</p> + + <ul> + <li>no matching document was found, Apache will proceed as + usual and return a "document not found" error.</li> + + <li>only one document is found that "almost" matches the + request, then it is returned in the form of a redirection + response.</li> + + <li>more than one document with a close match was found, then + the list of the matches is returned to the client, and the + client can select the correct candidate.</li> + </ul> + +</summary> + + +<directivesynopsis> +<name>CheckSpelling</name> +<syntax>CheckSpelling on|off</syntax> +<default>CheckSpelling Off</default> +<contextlist> +<context>server config</context> +<context>virtual host</context> +<context>directory</context> +<context>.htaccess</context> +</contextlist> +<override>Options</override> +<compatibility>CheckSpelling was available as a separately available +module for Apache 1.1, but was limited to miscapitalizations. As +of Apache 1.3, it is part of the Apache distribution. Prior to Apache +1.3.2, the <samp>CheckSpelling</samp> directive was only available in the +"server" and "virtual host" contexts.</compatibility> +<description>This directive enables or disables the spelling +module.</description> + +<usage> + + <p>This directive enables or disables the spelling module. When + enabled, keep in mind that</p> + + <ul> + <li>the directory scan which is necessary for the spelling + correction will have an impact on the server's performance + when many spelling corrections have to be performed at the + same time.</li> + + <li>the document trees should not contain sensitive files + which could be matched inadvertently by a spelling + "correction".</li> + + <li>the module is unable to correct misspelled user names (as + in <code>http://my.host/~apahce/</code>), just file names or + directory names.</li> + + <li>spelling corrections apply strictly to existing files, so + a request for the <samp><Location /status></samp> may + get incorrectly treated as the negotiated file + "<samp>/stats.html</samp>".</li> + </ul> +</usage> + +</directivesynopsis> + +</modulesynopsis> + diff --git a/docs/manual/mod/mod_ssl.html b/docs/manual/mod/mod_ssl.html new file mode 100644 index 0000000000..f7ecb633ff --- /dev/null +++ b/docs/manual/mod/mod_ssl.html @@ -0,0 +1,2539 @@ +<html> +<head> +<title>mod_ssl: Reference</title> + +<!-- + Copyright (c) 1998-2001 Ralf S. Engelschall. All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code must retain the above + copyright notice, this list of conditions and the following + disclaimer. + + 2. Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials + provided with the distribution. + + 3. All advertising materials mentioning features or use of this + software must display the following acknowledgment: + "This product includes software developed by + Ralf S. Engelschall <rse@engelschall.com> for use in the + mod_ssl project (http://www.modssl.org/)." + + 4. The name "mod_ssl" must not be used to endorse or promote + products derived from this software without prior written + permission. + + 5. Redistributions of any form whatsoever must retain the + following acknowledgment: + "This product includes software developed by + Ralf S. Engelschall <rse@engelschall.com> for use in the + mod_ssl project (http://www.modssl.org/)." + + THIS SOFTWARE IS PROVIDED BY RALF S. ENGELSCHALL ``AS IS'' AND ANY + EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RALF S. ENGELSCHALL OR + HIS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT + NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; + LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED + OF THE POSSIBILITY OF SUCH DAMAGE. +--> +<style type="text/css"><!-- +A:link { + text-decoration: none; + color: #6666cc; +} +A:active { + text-decoration: none; + color: #6666cc; +} +A:visited { + text-decoration: none; + color: #6666cc; +} +#sf { + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +H1 { + font-weight: bold; + font-size: 24pt; + line-height: 24pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +H2 { + font-weight: bold; + font-size: 18pt; + line-height: 18pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +H3 { + font-weight: bold; + font-size: 14pt; + line-height: 14pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +H4 { + font-weight: bold; + font-size: 12pt; + line-height: 12pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +#H { +} +#D { + background-color: #f0f0f0; +} +#faq { + font-weight: bold; + font-size: 16pt; + line-height: 16pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +#howto { + font-weight: bold; + font-size: 16pt; + line-height: 16pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +#term { + font-weight: bold; + font-size: 16pt; + line-height: 16pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +--></style> +<script type="text/javascript" language="JavaScript"> +<!-- Hiding the code +function ro_imgNormal(imgName) { + if (document.images) { + document[imgName].src = eval(imgName + '_n.src'); + self.status = ''; + } +} +function ro_imgOver(imgName, descript) { + if (document.images) { + document[imgName].src = eval(imgName + '_o.src'); + self.status = descript; + } +} +// done hiding --> +</script> +<script type="text/javascript" language="JavaScript"> +<!-- Hiding the code +if (document.images) { + ro_img_prev_top_n = new Image(); + ro_img_prev_top_n.src = 'ssl_template.navbut-prev-n.gif'; + ro_img_prev_top_o = new Image(); + ro_img_prev_top_o.src = 'ssl_template.navbut-prev-s.gif'; +} +// done hiding --> +</script> +<script type="text/javascript" language="JavaScript"> +<!-- Hiding the code +if (document.images) { + ro_img_prev_bot_n = new Image(); + ro_img_prev_bot_n.src = 'ssl_template.navbut-prev-n.gif'; + ro_img_prev_bot_o = new Image(); + ro_img_prev_bot_o.src = 'ssl_template.navbut-prev-s.gif'; +} +// done hiding --> +</script> +<script type="text/javascript" language="JavaScript"> +<!-- Hiding the code +if (document.images) { + ro_img_next_top_n = new Image(); + ro_img_next_top_n.src = 'ssl_template.navbut-next-n.gif'; + ro_img_next_top_o = new Image(); + ro_img_next_top_o.src = 'ssl_template.navbut-next-s.gif'; +} +// done hiding --> +</script> +<script type="text/javascript" language="JavaScript"> +<!-- Hiding the code +if (document.images) { + ro_img_next_bot_n = new Image(); + ro_img_next_bot_n.src = 'ssl_template.navbut-next-n.gif'; + ro_img_next_bot_o = new Image(); + ro_img_next_bot_o.src = 'ssl_template.navbut-next-s.gif'; +} +// done hiding --> +</script> +</head> +<body bgcolor="#ffffff" text="#000000" link="#333399" alink="#9999ff" vlink="#000066"> +<div align="center"> +<table width="600" cellspacing="0" cellpadding="0" border="0" summary=""> +<tr> + <td> + <img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="600" height="1" align="bottom" border="0"><br> + <table width="600" cellspacing="0" cellpadding="0" summary=""> + <tr> + <td> + <table width="600" summary=""> + <tr> + <td align="left" valign="bottom"> + <font face="Arial,Helvetica" size="+2"><b>mod_ssl</b></font> + </td> + <td align="right"> + <img src="ssl_template.head-chapter.gif" alt="Chapter" width="175" height="94"> <img src="ssl_template.head-num-3.gif" alt="3" width="74" height="89"> + </td> + </tr> + </table> + </td> + </tr> + <tr> + <td><img src="ssl_template.imgdot-1x1-000000.gif" alt="" width="600" height="2" align="bottom" border="0"></td> + </tr> + <tr> + <td> + <table width="600" border="0" summary=""> + <tr> + <td valign="top" align="left" width="250"> +<a href="ssl_intro.html" onmouseover="ro_imgOver('ro_img_prev_top', 'previous page'); return true" onmouseout="ro_imgNormal('ro_img_prev_top'); return true" onfocus="ro_imgOver('ro_img_prev_top', 'previous page'); return true" onblur="ro_imgNormal('ro_img_prev_top'); return true"><img name="ro_img_prev_top" src="ssl_template.navbut-prev-n.gif" alt="previous page" width="70" height="18" border="0"></a><br><font color="#000000">Introduction</font> + </td> + <td valign="top" align="right" width="250"> +<a href="ssl_compat.html" onmouseover="ro_imgOver('ro_img_next_top', 'next page'); return true" onmouseout="ro_imgNormal('ro_img_next_top'); return true" onfocus="ro_imgOver('ro_img_next_top', 'next page'); return true" onblur="ro_imgNormal('ro_img_next_top'); return true"><img name="ro_img_next_top" src="ssl_template.navbut-next-n.gif" alt="next page" width="70" height="18" border="0"></a><br><font color="#000000">Compatibility</font> + </td> + </tr> + </table> + </td> + </tr> + <tr> + <td> + <br> + <img src="ssl_template.title-ref.gif" alt="Reference" width="456" height="60"> + </td> + </tr> + </table> +<div align="right"> +<table cellspacing="0" cellpadding="0" width="150" summary=""> +<tr> +<td> +<em> +``Try to understand everything, +but believe nothing!'' +</em> +</td> +</tr> +<tr> +<td align="right"> +<font size="-1"> +Unknown +</font> +</td> +</tr> +</table> +</div> +<p> +<table cellspacing="0" cellpadding="0" border="0" summary=""> +<tr valign="bottom"> +<td> +<img src="ssl_reference.gfont000.gif" alt="T" width="34" height="34" border="0" align="left"> +his chapter provides a reference to all configuration directives and +additional user visible features mod_ssl provides. It's intended as the +official resource when you want to know how a particilar mod_ssl functionality +is actually configured or activated. Each directive is documented similar to +the way standard Apache directives are documented in the official Apache +documentation set, i.e. for each directive especially the syntax, default and +context where applicable is given. +<p> +Notice that there are three major classes of directives which are used by +mod_ssl: First <em>Global Directives</em> (i.e. directives with context +``server config''), which can occur inside the server config files but only +outside of any sectioning commands like <VirtualHost>. Second +<em>Per-Server Directives</em> (i.e. those with context ``server config, +virtual host''), which can occur inside the server config files both outside +(for the main/default server) and inside <VirtualHost> sections. +</td> +<td> + +</td> +<td> +<div align="right"> +<table cellspacing="0" cellpadding="5" border="0" bgcolor="#ccccff" summary=""> +<tr> +<td bgcolor="#333399"> +<font face="Arial,Helvetica" color="#ccccff"> +<b>Table Of Contents</b> +</font> +</td> +</tr> +<tr> +<td> +<font face="Arial,Helvetica" size="-1"> +<a href="#ToC1"><strong>Configuration Directives</strong></a><br> + <a href="#ToC2"><strong>SSLPassPhraseDialog</strong></a><br> + <a href="#ToC3"><strong>SSLMutex</strong></a><br> + <a href="#ToC4"><strong>SSLRandomSeed</strong></a><br> + <a href="#ToC5"><strong>SSLSessionCache</strong></a><br> + <a href="#ToC6"><strong>SSLSessionCacheTimeout</strong></a><br> + <a href="#ToC7"><strong>SSLEngine</strong></a><br> + <a href="#ToC8"><strong>SSLProtocol</strong></a><br> + <a href="#ToC9"><strong>SSLCipherSuite</strong></a><br> + <a href="#ToC10"><strong>SSLCertificateFile</strong></a><br> + <a href="#ToC11"><strong>SSLCertificateKeyFile</strong></a><br> + <a href="#ToC12"><strong>SSLCertificateChainFile</strong></a><br> + <a href="#ToC13"><strong>SSLCACertificatePath</strong></a><br> + <a href="#ToC14"><strong>SSLCACertificateFile</strong></a><br> + <a href="#ToC15"><strong>SSLCARevocationPath</strong></a><br> + <a href="#ToC16"><strong>SSLCARevocationFile</strong></a><br> + <a href="#ToC17"><strong>SSLVerifyClient</strong></a><br> + <a href="#ToC18"><strong>SSLVerifyDepth</strong></a><br> + <a href="#ToC19"><strong>SSLLog</strong></a><br> + <a href="#ToC20"><strong>SSLLogLevel</strong></a><br> + <a href="#ToC21"><strong>SSLOptions</strong></a><br> + <a href="#ToC22"><strong>SSLRequireSSL</strong></a><br> + <a href="#ToC23"><strong>SSLRequire</strong></a><br> +<a href="#ToC24"><strong>Additional Features</strong></a><br> + <a href="#ToC25"><strong>Environment Variables</strong></a><br> + <a href="#ToC26"><strong>Custom Log Formats</strong></a><br> +</font> +</td> +</tr> +</table> +</div> +</td> +</tr> +</table> +<p> +And third <em>Per-Directory Directives</em> (i.e. those with context ``server +config, virtual host, directory, .htaccess''), which can pretty much occur +everywhere. Especially both inside the server config files and the +per-directory <code>.htaccess</code> files. The three classes are subsets of +each other, i.e. directives from the per-directory class can also be used in +the per-server and global context, and directives from the per-server class +can also be used the in the global context. +<p> +Additional directives and environment variables provided by mod_ssl (via +on-the-fly mapping) for backward compatiblity to other Apache SSL solutions +are documented in the <a href="ssl_compat.html">Compatibility</a> chapter. +<h1><a name="ToC1">Configuration Directives</a></h1> +The most visible and error-prone things of mod_ssl are its configuration +directives. So we document them in great detail here to assist you in setting +up the best possible configuration of your SSL-aware webserver. +<!-- SSLPassPhraseDialog --------------------------------------------> +<p> +<br> +<a name="SSLPassPhraseDialog"></a> +<h2><a name="ToC2">SSLPassPhraseDialog</a></h2> +<p> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLPassPhraseDialog</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Type of pass phrase dialog for encrypted private keys</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLPassPhraseDialog</code> <em>type</em></td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <code>SSLPassPhraseDialog builtin</code></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.1 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<p> +When Apache starts up it has to read the various Certificate (see <a +href="#SSLCertificateFile">SSLCertificateFile</a>) and Private Key (see <a +href="#SSLCertificateKeyFile">SSLCertificateKeyFile</a>) files of the +SSL-enabled virtual servers. Because for security reasons the Private Key +files are usually encrypted, mod_ssl needs to query the administrator for a +Pass Phrase in order to decrypt those files. This query can be done in two ways +which can be configured by <em>type</em>: +<ul> +<li><code>builtin</code> + <p> + This is the default where an interactive terminal dialog occurs at startup + time just before Apache detaches from the terminal. Here the administrator + has to manually enter the Pass Phrase for each encrypted Private Key file. + Because a lot of SSL-enabled virtual hosts can be configured, the + following reuse-scheme is used to minimize the dialog: When a Private Key + file is encrypted, all known Pass Phrases (at the beginning there are + none, of course) are tried. If one of those known Pass Phrases succeeds no + dialog pops up for this particular Private Key file. If none succeeded, + another Pass Phrase is queried on the terminal and remembered for the next + round (where it perhaps can be reused). + <p> + This scheme allows mod_ssl to be maximally flexible (because for N encrypted + Private Key files you <em>can</em> use N different Pass Phrases - but then + you have to enter all of them, of course) while minimizing the terminal + dialog (i.e. when you use a single Pass Phrase for all N Private Key files + this Pass Phrase is queried only once). +<p> +<li><code>exec:/path/to/program</code> + <p> + Here an external program is configured which is called at startup for each + encrypted Private Key file. It is called with two arguments (the first is + of the form ``<code>servername:portnumber</code>'', the second is either + ``<code>RSA</code>'' or ``<code>DSA</code>''), which indicate for which + server and algorithm it has to print the corresponding Pass Phrase to + <code>stdout</code>. The intent is that this external program first runs + security checks to make sure that the system is not compromised by an + attacker, and only when these checks were passed successfully it provides + the Pass Phrase. + <p> + Both these security checks, and the way the Pass Phrase is determined, can + be as complex as you like. Mod_ssl just defines the interface: an + executable program which provides the Pass Phrase on <code>stdout</code>. + Nothing more or less! So, if you're really paranoid about security, here + is your interface. Anything else has to be left as an exercise to the + administrator, because local security requirements are so different. + <p> + The reuse-algorithm above is used here, too. In other words: The external + program is called only once per unique Pass Phrase. +</ul> +<p> +Example: +<blockquote> +<pre> +SSLPassPhraseDialog exec:/usr/local/apache/sbin/pp-filter +</pre> +</blockquote> +<!-- SSLMutex -------------------------------------------------------> +<p> +<br> +<a name="SSLMutex"></a> +<h2><a name="ToC3">SSLMutex</a></h2> +<p> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLMutex</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Semaphore for internal mutual exclusion of operations</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLMutex</code> <em>type</em></td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <code>SSLMutex none</code></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.1 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<p> +This configures the SSL engine's semaphore (aka. lock) which is used for mutual +exclusion of operations which have to be done in a synchronized way between the +pre-forked Apache server processes. This directive can only be used in the +global server context because it's only useful to have one global mutex. +<p> +The following Mutex <em>types</em> are available: +<ul> +<li><code>none</code> + <p> + This is the default where no Mutex is used at all. Use it at your own + risk. But because currently the Mutex is mainly used for synchronizing + write access to the SSL Session Cache you can live without it as long + as you accept a sometimes garbled Session Cache. So it's not recommended + to leave this the default. Instead configure a real Mutex. +<p> +<li><code>file:/path/to/mutex</code> + <p> + This is the portable and (under Unix) always provided Mutex variant where + a physical (lock-)file is used as the Mutex. Always use a local disk + filesystem for <code>/path/to/mutex</code> and never a file residing on a + NFS- or AFS-filesystem. Note: Internally, the Process ID (PID) of the + Apache parent process is automatically appended to + <code>/path/to/mutex</code> to make it unique, so you don't have to worry + about conflicts yourself. Notice that this type of mutex is not available + under the Win32 environment. There you <i>have</i> to use the semaphore + mutex. +<p> +<li><code>sem</code> + <p> + This is the most elegant but also most non-portable Mutex variant where a + SysV IPC Semaphore (under Unix) and a Windows Mutex (under Win32) is used + when possible. It is only available when the underlying platform + supports it. +</ul> +<p> +Example: +<blockquote> +<pre> +SSLMutex file:/usr/local/apache/logs/ssl_mutex +</pre> +</blockquote> +<!-- SSLRandomSeed --------------------------------------------------> +<p> +<br> +<a name="SSLRandomSeed"></a> +<h2><a name="ToC4">SSLRandomSeed</a></h2> +<p> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLRandomSeed</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Pseudo Random Number Generator (PRNG) seeding source</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLRandomSeed</code> <em>context</em> <em>source</em> [<em>bytes</em>]</td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <em>none</em></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.2 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<p> +This configures one or more sources for seeding the Pseudo Random Number +Generator (PRNG) in OpenSSL at startup time (<em>context</em> is +<code>startup</code>) and/or just before a new SSL connection is established +(<em>context</em> is <code>connect</code>). This directive can only be used +in the global server context because the PRNG is a global facility. +<p> +The following <em>source</em> variants are available: +<ul> +<li><code>builtin</code> + <p> This is the always available builtin seeding source. It's usage + consumes minimum CPU cycles under runtime and hence can be always used + without drawbacks. The source used for seeding the PRNG contains of the + current time, the current process id and (when applicable) a randomly + choosen 1KB extract of the inter-process scoreboard structure of Apache. + The drawback is that this is not really a strong source and at startup + time (where the scoreboard is still not available) this source just + produces a few bytes of entropy. So you should always, at least for the + startup, use an additional seeding source. +<p> +<li><code>file:/path/to/source</code> + <p> + This variant uses an external file <code>/path/to/source</code> as the + source for seeding the PRNG. When <em>bytes</em> is specified, only the + first <em>bytes</em> number of bytes of the file form the entropy (and + <em>bytes</em> is given to <code>/path/to/source</code> as the first + argument). When <em>bytes</em> is not specified the whole file forms the + entropy (and <code>0</code> is given to <code>/path/to/source</code> as + the first argument). Use this especially at startup time, for instance + with an available <code>/dev/random</code> and/or + <code>/dev/urandom</code> devices (which usually exist on modern Unix + derivates like FreeBSD and Linux). + <p> + <em>But be careful</em>: Usually <code>/dev/random</code> provides only as + much entropy data as it actually has, i.e. when you request 512 bytes of + entropy, but the device currently has only 100 bytes available two things + can happen: On some platforms you receive only the 100 bytes while on + other platforms the read blocks until enough bytes are available (which + can take a long time). Here using an existing <code>/dev/urandom</code> is + better, because it never blocks and actually gives the amount of requested + data. The drawback is just that the quality of the received data may not + be the best. + <p> + On some platforms like FreeBSD one can even control how the entropy is + actually generated, i.e. by which system interrupts. More details one can + find under <i>rndcontrol(8)</i> on those platforms. Alternatively, when + your system lacks such a random device, you can use tool + like <a href="http://www.lothar.com/tech/crypto/">EGD</a> + (Entropy Gathering Daemon) and run it's client program with the + <code>exec:/path/to/program/</code> variant (see below) or use + <code>egd:/path/to/egd-socket</code> (see below). +<p> +<li><code>exec:/path/to/program</code> + <p> + This variant uses an external executable <code>/path/to/program</code> as + the source for seeding the PRNG. When <em>bytes</em> is specified, only the + first <em>bytes</em> number of bytes of its <code>stdout</code> contents + form the entropy. When <em>bytes</em> is not specified, the entirety of + the data produced on <code>stdout</code> form the entropy. Use this only + at startup time when you need a very strong seeding with the help of an + external program (for instance as in the example above with the + <code>truerand</code> utility you can find in the mod_ssl distribution + which is based on the AT&T <em>truerand</em> library). Using this in + the connection context slows down the server too dramatically, of course. + So usually you should avoid using external programs in that context. +<p> +<li><code>egd:/path/to/egd-socket</code> (Unix only) + <p> + This variant uses the Unix domain socket of the + external Entropy Gathering Daemon (EGD) (see <a + href="http://www.lothar.com/tech/crypto/">http://www.lothar.com/tech + /crypto/</a>) to seed the PRNG. Use this if no random device exists + on your platform. +</ul> +<p> +Example: +<blockquote> +<pre> +SSLRandomSeed startup builtin +SSLRandomSeed startup file:/dev/random +SSLRandomSeed startup file:/dev/urandom 1024 +SSLRandomSeed startup exec:/usr/local/bin/truerand 16 +SSLRandomSeed connect builtin +SSLRandomSeed connect file:/dev/random +SSLRandomSeed connect file:/dev/urandom 1024 +</pre> +</blockquote> +<!-- SSLSessionCache ------------------------------------------------> +<p> +<br> +<a name="SSLSessionCache"></a> +<h2><a name="ToC5">SSLSessionCache</a></h2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLSessionCache</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Type of the global/inter-process SSL Session Cache</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLSessionCache</code> <em>type</em></td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <code>SSLSessionCache none</code></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.1 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<p> +This configures the storage type of the global/inter-process SSL Session +Cache. This cache is an optional facility which speeds up parallel request +processing. For requests to the same server process (via HTTP keep-alive), +OpenSSL already caches the SSL session information locally. But because modern +clients request inlined images and other data via parallel requests (usually +up to four parallel requests are common) those requests are served by +<em>different</em> pre-forked server processes. Here an inter-process cache +helps to avoid unneccessary session handshakes. +<p> +The following two storage <em>type</em>s are currently supported: +<ul> +<li><code>none</code> + <p> + This is the default and just disables the global/inter-process Session + Cache. There is no drawback in functionality, but a noticeable speed + penalty can be observed. +<p> +<li><code>dbm:/path/to/datafile</code> + <p> + This makes use of a DBM hashfile on the local disk to synchronize the + local OpenSSL memory caches of the server processes. The slight increase + in I/O on the server results in a visible request speedup for your + clients, so this type of storage is generally recommended. +<p> +<li><code>shm:/path/to/datafile</code>[<code>(</code><i>size</i><code>)</code>] + <p> + This makes use of a high-performance hash table (approx. <i>size</i> bytes + in size) inside a shared memory segment in RAM (established via + <code>/path/to/datafile</code>) to synchronize the local OpenSSL memory + caches of the server processes. This storage type is not available on all + platforms. See the mod_ssl <code>INSTALL</code> document for details on + how to build Apache+EAPI with shared memory support. +</ul> +<p> +Examples: +<blockquote> +<pre> +SSLSessionCache dbm:/usr/local/apache/logs/ssl_gcache_data +SSLSessionCache shm:/usr/local/apache/logs/ssl_gcache_data(512000) +</pre> +</blockquote> +<!-- SSLSessionCacheTimeout -----------------------------------------> +<p> +<br> +<a name="SSLSessionCacheTimeout"></a> +<h2><a name="ToC6">SSLSessionCacheTimeout</a></h2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLSessionCacheTimeout</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Number of seconds before an SSL session expires in the Session Cache</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLSessionCacheTimeout</code> <em>seconds</em></td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <code>SSLSessionCacheTimeout 300</code></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.0 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<p> +This directive sets the timeout in seconds for the information stored in the +global/inter-process SSL Session Cache and the OpenSSL internal memory cache. +It can be set as low as 15 for testing, but should be set to higher +values like 300 in real life. +<p> +Example: +<blockquote> +<pre> +SSLSessionCacheTimeout 600 +</pre> +</blockquote> +<!-- SSLEngine ------------------------------------------------------> +<p> +<br> +<a name="SSLEngine"></a> +<h2><a name="ToC7">SSLEngine</a></h2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLEngine</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> SSL Engine Operation Switch</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLEngine</code> <em>on|off</em></td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <code>SSLEngine off</code></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.1 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<p> +This directive toggles the usage of the SSL/TLS Protocol Engine. This is +usually used inside a <VirtualHost> section to enable SSL/TLS for a +particular virtual host. By default the SSL/TLS Protocol Engine is disabled +for both the main server and all configured virtual hosts. +<p> +Example: +<blockquote> +<pre> +<VirtualHost _default_:443> +SSLEngine on +... +</VirtualHost> +</pre> +</blockquote> +<!-- SSLProtocol ----------------------------------------------------> +<p> +<br> +<a name="SSLProtocol"></a> +<h2><a name="ToC8">SSLProtocol</a></h2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLProtocol</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Configure usable SSL protocol flavors</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLProtocol</code> [+-]<em>protocol</em> ...</td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <code>SSLProtocol all</code></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> Options</td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.2 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<p> +This directive can be used to control the SSL protocol flavors mod_ssl should +use when establishing its server environment. Clients then can only connect +with one of the provided protocols. +<p> +The available (case-insensitive) <em>protocol</em>s are: +<ul> +<li><code>SSLv2</code> + <p> + This is the Secure Sockets Layer (SSL) protocol, version 2.0. It is the + original SSL protocol as designed by Netscape Corporation. +<p> +<li><code>SSLv3</code> + <p> + This is the Secure Sockets Layer (SSL) protocol, version 3.0. It is the + successor to SSLv2 and the currently (as of February 1999) de-facto + standardized SSL protocol from Netscape Corporation. It's supported by + almost all popular browsers. +<p> +<li><code>TLSv1</code> + <p> + This is the Transport Layer Security (TLS) protocol, version 1.0. It is the + successor to SSLv3 and currently (as of February 1999) still under + construction by the Internet Engineering Task Force (IETF). It's still + not supported by any popular browsers. +<p> +<li><code>All</code> + <p> + This is a shortcut for ``<code>+SSLv2 +SSLv3 +TLSv1</code>'' and a + convinient way for enabling all protocols except one when used in + combination with the minus sign on a protocol as the example above shows. +</ul> +<p> +Example: +<blockquote> +<pre> +# enable SSLv3 and TLSv1, but not SSLv2 +SSLProtocol all -SSLv2 +</pre> +</blockquote> +<!-- SSLCipherSuite -------------------------------------------------> +<p> +<br> +<a name="SSLCipherSuite"></a> +<h2><a name="ToC9">SSLCipherSuite</a></h2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLCipherSuite</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Cipher Suite available for negotiation in SSL handshake</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLCipherSuite</code> <em>cipher-spec</em></td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <code>SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP</code></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host, directory, .htaccess</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> AuthConfig</td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.1 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<p> +This complex directive uses a colon-separated <em>cipher-spec</em> string +consisting of OpenSSL cipher specifications to configure the Cipher Suite the +client is permitted to negotiate in the SSL handshake phase. Notice that this +directive can be used both in per-server and per-directory context. In +per-server context it applies to the standard SSL handshake when a connection +is established. In per-directory context it forces a SSL renegotation with the +reconfigured Cipher Suite after the HTTP request was read but before the HTTP +response is sent. +<p> +An SSL cipher specification in <em>cipher-spec</em> is composed of 4 major +attributes plus a few extra minor ones: +<ul> +<li><em>Key Exchange Algorithm</em>:<br> + RSA or Diffie-Hellman variants. +<p> +<li><em>Authentication Algorithm</em>:<br> + RSA, Diffie-Hellman, DSS or none. +<p> +<li><em>Cipher/Encryption Algorithm</em>:<br> + DES, Triple-DES, RC4, RC2, IDEA or none. +<p> +<li><em>MAC Digest Algorithm</em>:<br> + MD5, SHA or SHA1. +</ul> +An SSL cipher can also be an export cipher and is either a SSLv2 or SSLv3/TLSv1 +cipher (here TLSv1 is equivalent to SSLv3). To specify which ciphers to use, +one can either specify all the Ciphers, one at a time, or use aliases to +specify the preference and order for the ciphers (see <a href="#table1">Table +1</a>). +<p> +<div align="center"> +<a name="table1"></a> +<table width="600" cellspacing="0" cellpadding="1" border="0" summary=""> +<caption align="bottom" id="sf">Table 1: OpenSSL Cipher Specification Tags</caption> +<tr><td bgcolor="#cccccc"> +<table width="598" cellpadding="5" cellspacing="0" border="0" summary=""> +<tr><td valign="top" align="center" bgcolor="#ffffff"> +<table border="0" cellspacing="0" cellpadding="2" width="598" summary=""> +<tr id="D"><td><b>Tag</b></td> <td><b>Description</b></td> +<tr id="H"><td colspan="2"><em>Key Exchange Algorithm:</em></td></tr> +<tr id="D"><td><code>kRSA</code></td> <td>RSA key exchange</td></tr> +<tr id="H"><td><code>kDHr</code></td> <td>Diffie-Hellman key exchange with RSA key</td></tr> +<tr id="D"><td><code>kDHd</code></td> <td>Diffie-Hellman key exchange with DSA key</td></tr> +<tr id="H"><td><code>kEDH</code></td> <td>Ephemeral (temp.key) Diffie-Hellman key exchange (no cert)</td> </tr> +<tr id="H"><td colspan="2"><em>Authentication Algorithm:</em></td></tr> +<tr id="D"><td><code>aNULL</code></td> <td>No authentication</td></tr> +<tr id="H"><td><code>aRSA</code></td> <td>RSA authentication</td></tr> +<tr id="D"><td><code>aDSS</code></td> <td>DSS authentication</td> </tr> +<tr id="H"><td><code>aDH</code></td> <td>Diffie-Hellman authentication</td></tr> +<tr id="D"><td colspan="2"><em>Cipher Encoding Algorithm:</em></td></tr></tr> +<tr id="H"><td><code>eNULL</code></td> <td>No encoding</td> </tr> +<tr id="D"><td><code>DES</code></td> <td>DES encoding</td> </tr> +<tr id="H"><td><code>3DES</code></td> <td>Triple-DES encoding</td> </tr> +<tr id="D"><td><code>RC4</code></td> <td>RC4 encoding</td> </tr> +<tr id="H"><td><code>RC2</code></td> <td>RC2 encoding</td> </tr> +<tr id="D"><td><code>IDEA</code></td> <td>IDEA encoding</td> </tr> +<tr id="H"><td colspan="2"><em>MAC Digest Algorithm</em>:</td></tr> +<tr id="D"><td><code>MD5</code></td> <td>MD5 hash function</td></tr> +<tr id="H"><td><code>SHA1</code></td> <td>SHA1 hash function</td></tr> +<tr id="D"><td><code>SHA</code></td> <td>SHA hash function</td> </tr> +<tr id="H"><td colspan="2"><em>Aliases:</em></td></tr> +<tr id="D"><td><code>SSLv2</code></td> <td>all SSL version 2.0 ciphers</td></tr> +<tr id="H"><td><code>SSLv3</code></td> <td>all SSL version 3.0 ciphers</td> </tr> +<tr id="D"><td><code>TLSv1</code></td> <td>all TLS version 1.0 ciphers</td> </tr> +<tr id="H"><td><code>EXP</code></td> <td>all export ciphers</td> </tr> +<tr id="D"><td><code>EXPORT40</code></td> <td>all 40-bit export ciphers only</td> </tr> +<tr id="H"><td><code>EXPORT56</code></td> <td>all 56-bit export ciphers only</td> </tr> +<tr id="D"><td><code>LOW</code></td> <td>all low strength ciphers (no export, single DES)</td></tr> +<tr id="H"><td><code>MEDIUM</code></td> <td>all ciphers with 128 bit encryption</td> </tr> +<tr id="D"><td><code>HIGH</code></td> <td>all ciphers using Triple-DES</td> </tr> +<tr id="H"><td><code>RSA</code></td> <td>all ciphers using RSA key exchange</td> </tr> +<tr id="D"><td><code>DH</code></td> <td>all ciphers using Diffie-Hellman key exchange</td> </tr> +<tr id="H"><td><code>EDH</code></td> <td>all ciphers using Ephemeral Diffie-Hellman key exchange</td> </tr> +<tr id="D"><td><code>ADH</code></td> <td>all ciphers using Anonymous Diffie-Hellman key exchange</td> </tr> +<tr id="H"><td><code>DSS</code></td> <td>all ciphers using DSS authentication</td> </tr> +<tr id="D"><td><code>NULL</code></td> <td>all ciphers using no encryption</td> </tr> +</table> +</td> +</tr></table> +</td></tr></table> +</div> +<p> +Now where this becomes interesting is that these can be put together +to specify the order and ciphers you wish to use. To speed this up +there are also aliases (<code>SSLv2, SSLv3, TLSv1, EXP, LOW, MEDIUM, +HIGH</code>) for certain groups of ciphers. These tags can be joined +together with prefixes to form the <em>cipher-spec</em>. Available +prefixes are: +<ul> +<li>none: add cipher to list +<li><code>+</code>: add ciphers to list and pull them to current location in list +<li><code>-</code>: remove cipher from list (can be added later again) +<li><code>!</code>: kill cipher from list completely (can <b>not</b> be added later again) +</ul> +A simpler way to look at all of this is to use the ``<code>openssl ciphers +-v</code>'' command which provides a nice way to successively create the +correct <em>cipher-spec</em> string. The default <em>cipher-spec</em> string +is ``<code>ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP</code>'' which +means the following: first, remove from consideration any ciphers that do not +authenticate, i.e. for SSL only the Anonymous Diffie-Hellman ciphers. Next, +use ciphers using RC4 and RSA. Next include the high, medium and then the low +security ciphers. Finally <em>pull</em> all SSLv2 and export ciphers to the +end of the list. +<blockquote> +<pre> +$ openssl ciphers -v 'ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP' +NULL-SHA SSLv3 Kx=RSA Au=RSA Enc=None Mac=SHA1 +NULL-MD5 SSLv3 Kx=RSA Au=RSA Enc=None Mac=MD5 +EDH-RSA-DES-CBC3-SHA SSLv3 Kx=DH Au=RSA Enc=3DES(168) Mac=SHA1 +... ... ... ... ... +EXP-RC4-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export +EXP-RC2-CBC-MD5 SSLv2 Kx=RSA(512) Au=RSA Enc=RC2(40) Mac=MD5 export +EXP-RC4-MD5 SSLv2 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export +</pre> +</blockquote> +The complete list of particular RSA & DH ciphers for SSL is given in <a +href="#table2">Table 2</a>. +<p> +Example: +<blockquote> +<pre> +SSLCipherSuite RSA:!EXP:!NULL:+HIGH:+MEDIUM:-LOW +</pre> +</blockquote> +<p> +<div align="center"> +<a name="table2"></a> +<table width="600" cellspacing="0" cellpadding="1" border="0" summary=""> +<caption align="bottom" id="sf">Table 2: Particular SSL Ciphers</caption> +<tr><td bgcolor="#cccccc"> +<table width="598" cellpadding="5" cellspacing="0" border="0" summary=""> +<tr><td valign="top" align="center" bgcolor="#ffffff"> +<table border="0" cellspacing="0" cellpadding="2" width="598" summary=""> +<tr id="D"><td><b>Cipher-Tag</b></td> <td><b>Protocol</b></td> <td><b>Key Ex.</b></td> <td><b>Auth.</b></td> <td><b>Enc.</b></td> <td><b>MAC</b></td> <td><b>Type</b></td> </tr> +<tr id="H"><td colspan="7"><em>RSA Ciphers:</em></td></tr> +<tr id="D"><td><code>DES-CBC3-SHA</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>3DES(168)</td> <td>SHA1</td> <td> </td> </tr> +<tr id="H"><td><code>DES-CBC3-MD5</code></td> <td>SSLv2</td> <td>RSA</td> <td>RSA</td> <td>3DES(168)</td> <td>MD5</td> <td> </td> </tr> +<tr id="D"><td><code>IDEA-CBC-SHA</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>IDEA(128)</td> <td>SHA1</td> <td> </td> </tr> +<tr id="H"><td><code>RC4-SHA</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>RC4(128)</td> <td>SHA1</td> <td> </td> </tr> +<tr id="D"><td><code>RC4-MD5</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>RC4(128)</td> <td>MD5</td> <td> </td> </tr> +<tr id="H"><td><code>IDEA-CBC-MD5</code></td> <td>SSLv2</td> <td>RSA</td> <td>RSA</td> <td>IDEA(128)</td> <td>MD5</td> <td> </td> </tr> +<tr id="D"><td><code>RC2-CBC-MD5</code></td> <td>SSLv2</td> <td>RSA</td> <td>RSA</td> <td>RC2(128)</td> <td>MD5</td> <td> </td> </tr> +<tr id="H"><td><code>RC4-MD5</code></td> <td>SSLv2</td> <td>RSA</td> <td>RSA</td> <td>RC4(128)</td> <td>MD5</td> <td> </td> </tr> +<tr id="D"><td><code>DES-CBC-SHA</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>DES(56)</td> <td>SHA1</td> <td> </td> </tr> +<tr id="H"><td><code>RC4-64-MD5</code></td> <td>SSLv2</td> <td>RSA</td> <td>RSA</td> <td>RC4(64)</td> <td>MD5</td> <td> </td> </tr> +<tr id="D"><td><code>DES-CBC-MD5</code></td> <td>SSLv2</td> <td>RSA</td> <td>RSA</td> <td>DES(56)</td> <td>MD5</td> <td> </td> </tr> +<tr id="H"><td><code>EXP-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>RSA(512)</td> <td>RSA</td> <td>DES(40)</td> <td>SHA1</td> <td> export</td> </tr> +<tr id="D"><td><code>EXP-RC2-CBC-MD5</code></td> <td>SSLv3</td> <td>RSA(512)</td> <td>RSA</td> <td>RC2(40)</td> <td>MD5</td> <td> export</td> </tr> +<tr id="H"><td><code>EXP-RC4-MD5</code></td> <td>SSLv3</td> <td>RSA(512)</td> <td>RSA</td> <td>RC4(40)</td> <td>MD5</td> <td> export</td> </tr> +<tr id="D"><td><code>EXP-RC2-CBC-MD5</code></td> <td>SSLv2</td> <td>RSA(512)</td> <td>RSA</td> <td>RC2(40)</td> <td>MD5</td> <td> export</td> </tr> +<tr id="H"><td><code>EXP-RC4-MD5</code></td> <td>SSLv2</td> <td>RSA(512)</td> <td>RSA</td> <td>RC4(40)</td> <td>MD5</td> <td> export</td> </tr> +<tr id="D"><td><code>NULL-SHA</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>None</td> <td>SHA1</td> <td> </td> </tr> +<tr id="H"><td><code>NULL-MD5</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>None</td> <td>MD5</td> <td> </td> </tr> +<tr id="D"><td colspan="7"><em>Diffie-Hellman Ciphers:</em></td></tr> +<tr id="H"><td><code>ADH-DES-CBC3-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>None</td> <td>3DES(168)</td> <td>SHA1</td> <td> </td> </tr> +<tr id="D"><td><code>ADH-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>None</td> <td>DES(56)</td> <td>SHA1</td> <td> </td> </tr> +<tr id="H"><td><code>ADH-RC4-MD5</code></td> <td>SSLv3</td> <td>DH</td> <td>None</td> <td>RC4(128)</td> <td>MD5</td> <td> </td> </tr> +<tr id="D"><td><code>EDH-RSA-DES-CBC3-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>RSA</td> <td>3DES(168)</td> <td>SHA1</td> <td> </td> </tr> +<tr id="H"><td><code>EDH-DSS-DES-CBC3-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>DSS</td> <td>3DES(168)</td> <td>SHA1</td> <td> </td> </tr> +<tr id="D"><td><code>EDH-RSA-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>RSA</td> <td>DES(56)</td> <td>SHA1</td> <td> </td> </tr> +<tr id="H"><td><code>EDH-DSS-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>DSS</td> <td>DES(56)</td> <td>SHA1</td> <td> </td> </tr> +<tr id="D"><td><code>EXP-EDH-RSA-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>DH(512)</td> <td>RSA</td> <td>DES(40)</td> <td>SHA1</td> <td> export</td> </tr> +<tr id="H"><td><code>EXP-EDH-DSS-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>DH(512)</td> <td>DSS</td> <td>DES(40)</td> <td>SHA1</td> <td> export</td> </tr> +<tr id="D"><td><code>EXP-ADH-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>DH(512)</td> <td>None</td> <td>DES(40)</td> <td>SHA1</td> <td> export</td> </tr> +<tr id="H"><td><code>EXP-ADH-RC4-MD5</code></td> <td>SSLv3</td> <td>DH(512)</td> <td>None</td> <td>RC4(40)</td> <td>MD5</td> <td> export</td> </tr> +</table> +</td> +</tr></table> +</td></tr></table> +</div> +<!-- SSLCertificateFile ---------------------------------------------> +<p> +<br> +<a name="SSLCertificateFile"></a> +<h2><a name="ToC10">SSLCertificateFile</a></h2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLCertificateFile</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Server PEM-encoded X.509 Certificate file</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLCertificateFile</code> <em>filename</em></td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <em>None</em></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.0 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<p> +This directive points to the PEM-encoded Certificate file for the server and +optionally also to the corresponding RSA or DSA Private Key file for it +(contained in the same file). If the contained Private Key is encrypted the +Pass Phrase dialog is forced at startup time. This directive can be used up to +two times (referencing different filenames) when both a RSA and a DSA based +server certificate is used in parallel. +<p> +Example: +<blockquote> +<pre> +SSLCertificateFile /usr/local/apache/conf/ssl.crt/server.crt +</pre> +</blockquote> +<!-- SSLCertificateKeyFile ------------------------------------------> +<p> +<br> +<a name="SSLCertificateKeyFile"></a> +<h2><a name="ToC11">SSLCertificateKeyFile</a></h2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLCertificateKeyFile</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Server PEM-encoded Private Key file</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLCertificateKeyFile</code> <em>filename</em></td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <em>None</em></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.0 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<p> +This directive points to the PEM-encoded Private Key file for the server. If +the Private Key is not combined with the Certificate in the +<code>SSLCertificateFile</code>, use this additional directive to point to the +file with the stand-alone Private Key. When <code>SSLCertificateFile</code> +is used and the file contains both the Certificate and the Private Key this +directive need not be used. But we strongly discourage this practice. +Instead we recommend you to separate the Certificate and the Private Key. If +the contained Private Key is encrypted, the Pass Phrase dialog is forced at +startup time. This directive can be used up to two times (referencing +different filenames) when both a RSA and a DSA based private key is used in +parallel. +<p> +Example: +<blockquote> +<pre> +SSLCertificateKeyFile /usr/local/apache/conf/ssl.key/server.key +</pre> +</blockquote> +<!-- SSLCertificateChainFile ----------------------------------------> +<p> +<br> +<a name="SSLCertificateChainFile"></a> +<h2><a name="ToC12">SSLCertificateChainFile</a></h2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLCertificateChainFile</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> File of PEM-encoded Server CA Certificates</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLCertificateChainFile</code> <em>filename</em></td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <em>None</em></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.3.6 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<p> +This directive sets the optional <em>all-in-one</em> file where you can +assemble the certificates of Certification Authorities (CA) which form the +certificate chain of the server certificate. This starts with the issuing CA +certificate of of the server certificate and can range up to the root CA +certificate. Such a file is simply the concatenation of the various +PEM-encoded CA Certificate files, usually in certificate chain order. +<p> +This should be used alternatively and/or additionally to <a +href="#SSLCACertificatePath">SSLCACertificatePath</a> for explicitly +constructing the server certificate chain which is sent to the browser in +addition to the server certificate. It is especially useful to avoid conflicts +with CA certificates when using client authentication. Because although +placing a CA certificate of the server certificate chain into <a +href="#SSLCACertificatePath">SSLCACertificatePath</a> has the same effect for +the certificate chain construction, it has the side-effect that client +certificates issued by this same CA certificate are also accepted on client +authentication. That's usually not one expect. +<p> +But be careful: Providing the certificate chain works only if you are using a +<i>single</i> (either RSA <i>or</i> DSA) based server certificate. If you are +using a coupled RSA+DSA certificate pair, this will work only if actually both +certificates use the <i>same</i> certificate chain. Else the browsers will be +confused in this situation. +<p> +Example: +<blockquote> +<pre> +SSLCertificateChainFile /usr/local/apache/conf/ssl.crt/ca.crt +</pre> +</blockquote> +<!-- SSLCACertificatePath -------------------------------------------> +<p> +<br> +<a name="SSLCACertificatePath"></a> +<h2><a name="ToC13">SSLCACertificatePath</a></h2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLCACertificatePath</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Directory of PEM-encoded CA Certificates for Client Auth.</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLCACertificatePath</code> <em>directory</em></td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <em>None</em></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.0 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<p> +This directive sets the directory where you keep the Certificates of +Certification Authorities (CAs) whose clients you deal with. These are used to +verify the client certificate on Client Authentication. +<p> +The files in this directory have to be PEM-encoded and are accessed through +hash filenames. So usually you can't just place the Certificate files +there: you also have to create symbolic links named +<i>hash-value</i><tt>.N</tt>. And you should always make sure this directory +contains the appropriate symbolic links. Use the <code>Makefile</code> which +comes with mod_ssl to accomplish this task. +<p> +Example: +<blockquote> +<pre> +SSLCACertificatePath /usr/local/apache/conf/ssl.crt/ +</pre> +</blockquote> +<!-- SSLCACertificateFile -------------------------------------------> +<p> +<br> +<a name="SSLCACertificateFile"></a> +<h2><a name="ToC14">SSLCACertificateFile</a></h2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLCACertificateFile</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> File of concatenated PEM-encoded CA Certificates for Client Auth.</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLCACertificateFile</code> <em>filename</em></td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <em>None</em></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.0 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<p> +This directive sets the <em>all-in-one</em> file where you can assemble the +Certificates of Certification Authorities (CA) whose <em>clients</em> you deal +with. These are used for Client Authentication. Such a file is simply the +concatenation of the various PEM-encoded Certificate files, in order of +preference. This can be used alternatively and/or additionally to <a +href="#SSLCACertificatePath">SSLCACertificatePath</a>. +<p> +Example: +<blockquote> +<pre> +SSLCACertificateFile /usr/local/apache/conf/ssl.crt/ca-bundle-client.crt +</pre> +</blockquote> +<!-- SSLCARevocationPath --------------------------------------------> +<p> +<br> +<a name="SSLCARevocationPath"></a> +<h2><a name="ToC15">SSLCARevocationPath</a></h2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLCARevocationPath</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Directory of PEM-encoded CA CRLs for Client Auth.</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLCARevocationPath</code> <em>directory</em></td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <em>None</em></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.3 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<p> +This directive sets the directory where you keep the Certificate Revocation +Lists (CRL) of Certification Authorities (CAs) whose clients you deal with. +These are used to revoke the client certificate on Client Authentication. +<p> +The files in this directory have to be PEM-encoded and are accessed through +hash filenames. So usually you have not only to place the CRL files there. +Additionally you have to create symbolic links named +<i>hash-value</i><tt>.rN</tt>. And you should always make sure this directory +contains the appropriate symbolic links. Use the <code>Makefile</code> which +comes with mod_ssl to accomplish this task. +<p> +Example: +<blockquote> +<pre> +SSLCARevocationPath /usr/local/apache/conf/ssl.crl/ +</pre> +</blockquote> +<!-- SSLCARevocationFile --------------------------------------------> +<p> +<br> +<a name="SSLCARevocationFile"></a> +<h2><a name="ToC16">SSLCARevocationFile</a></h2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLCARevocationFile</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> File of concatenated PEM-encoded CA CRLs for Client Auth.</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLCARevocationFile</code> <em>filename</em></td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <em>None</em></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.3 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<p> +This directive sets the <em>all-in-one</em> file where you can assemble the +Certificate Revocation Lists (CRL) of Certification Authorities (CA) whose +<em>clients</em> you deal with. These are used for Client Authentication. +Such a file is simply the concatenation of the various PEM-encoded CRL +files, in order of preference. This can be used alternatively and/or +additionally to <a href="#SSLCARevocationPath">SSLCARevocationPath</a>. +<p> +Example: +<blockquote> +<pre> +SSLCARevocationFile /usr/local/apache/conf/ssl.crl/ca-bundle-client.crl +</pre> +</blockquote> +<!-- SSLVerifyClient -------------------------------------------------> +<p> +<br> +<a name="SSLVerifyClient"></a> +<h2><a name="ToC17">SSLVerifyClient</a></h2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLVerifyClient</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Type of Client Certificate verification</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLVerifyClient</code> <em>level</em></td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <code>SSLVerifyClient none</code></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host, directory, .htaccess</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> AuthConfig</td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.0 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<p> +This directive sets the Certificate verification level for the Client +Authentication. Notice that this directive can be used both in per-server and +per-directory context. In per-server context it applies to the client +authentication process used in the standard SSL handshake when a connection is +established. In per-directory context it forces a SSL renegotation with the +reconfigured client verification level after the HTTP request was read but +before the HTTP response is sent. +<p> +The following levels are available for <em>level</em>: +<ul> +<li><strong>none</strong>: + no client Certificate is required at all +<li><strong>optional</strong>: + the client <em>may</em> present a valid Certificate +<li><strong>require</strong>: + the client <em>has to</em> present a valid Certificate +<li><strong>optional_no_ca</strong>: + the client may present a valid Certificate<br> + but it need not to be (successfully) verifiable. +</ul> +In practice only levels <strong>none</strong> and <strong>require</strong> are +really interesting, because level <strong>optional</strong> doesn't work with +all browsers and level <strong>optional_no_ca</strong> is actually against the +idea of authentication (but can be used to establish SSL test pages, etc.) +<p> +Example: +<blockquote> +<pre> +SSLVerifyClient require +</pre> +</blockquote> +<!-- SSLVerifyDepth -------------------------------------------------> +<p> +<br> +<a name="SSLVerifyDepth"></a> +<h2><a name="ToC18">SSLVerifyDepth</a></h2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLVerifyDepth</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Maximum depth of CA Certificates in Client Certificate verification</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLVerifyDepth</code> <em>number</em></td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <code>SSLVerifyDepth 1</code></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host, directory, .htaccess</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> AuthConfig</td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.0 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<p> +This directive sets how deeply mod_ssl should verify before deciding that the +clients don't have a valid certificate. Notice that this directive can be +used both in per-server and per-directory context. In per-server context it +applies to the client authentication process used in the standard SSL +handshake when a connection is established. In per-directory context it forces +a SSL renegotation with the reconfigured client verification depth after the +HTTP request was read but before the HTTP response is sent. +<p> +The depth actually is the maximum number of intermediate certificate issuers, +i.e. the number of CA certificates which are max allowed to be followed while +verifying the client certificate. A depth of 0 means that self-signed client +certificates are accepted only, the default depth of 1 means the client +certificate can be self-signed or has to be signed by a CA which is directly +known to the server (i.e. the CA's certificate is under +<code>SSLCACertificatePath</code>), etc. +<p> +Example: +<blockquote> +<pre> +SSLVerifyDepth 10 +</pre> +</blockquote> +<!-- SSLLog ---------------------------------------------------------> +<p> +<br> +<a name="SSLLog"></a> +<h2><a name="ToC19">SSLLog</a></h2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLLog</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Where to write the dedicated SSL engine logfile</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLLog</code> <em>filename</em></td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <em>None</em></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.1 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<p> +This directive sets the name of the dedicated SSL protocol engine logfile. +Error type messages are additionally duplicated to the general Apache error +log file (directive <code>ErrorLog</code>). Put this somewhere where it cannot +be used for symlink attacks on a real server (i.e. somewhere where only root +can write). If the <em>filename</em> does not begin with a slash +('<code>/</code>') then it is assumed to be relative to the <em>Server +Root</em>. If <em>filename</em> begins with a bar ('<code>|</code>') then the +following string is assumed to be a path to an executable program to which a +reliable pipe can be established. The directive should occur only once per +virtual server config. +<p> +Example: +<blockquote> +<pre> +SSLLog /usr/local/apache/logs/ssl_engine_log +</pre> +</blockquote> +<!-- SSLLogLevel ----------------------------------------------------> +<p> +<br> +<a name="SSLLogLevel"></a> +<h2><a name="ToC20">SSLLogLevel</a></h2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLLogLevel</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Logging level for the dedicated SSL engine logfile</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLLogLevel</code> <em>level</em></td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <code>SSLLogLevel none</code></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> <em>Not applicable</em></td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.1 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<p> +This directive sets the verbosity degree of the dedicated SSL protocol engine +logfile. The <em>level</em> is one of the following (in ascending order where +higher levels include lower levels): +<ul> +<li><code>none</code><br> + no dedicated SSL logging is done, but messages of level + ``<code>error</code>'' are still written to the general Apache error + logfile. +<p> +<li><code>error</code><br> + log messages of error type only, i.e. messages which show fatal situations + (processing is stopped). Those messages are also duplicated to the + general Apache error logfile. +<p> +<li><code>warn</code><br> + log also warning messages, i.e. messages which show non-fatal problems + (processing is continued). +<p> +<li><code>info</code><br> + log also informational messages, i.e. messages which show major + processing steps. +<p> +<li><code>trace</code><br> + log also trace messages, i.e. messages which show minor processing steps. +<p> +<li><code>debug</code><br> + log also debugging messages, i.e. messages which show development and + low-level I/O information. +</ul> +<p> +Example: +<blockquote> +<pre> +SSLLogLevel warn +</pre> +</blockquote> +<!-- SSLOptions -----------------------------------------------------> +<p> +<br> +<a name="SSLOptions"></a> +<h2><a name="ToC21">SSLOptions</a></h2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLOptions</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Configure various SSL engine run-time options</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLOptions</code> [+-]<em>option</em> ...</td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <em>None</em></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> server config, virtual host, directory, .htaccess</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> Options</td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.1 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<p> +This directive can be used to control various run-time options on a +per-directory basis. Normally, if multiple <code>SSLOptions</code> could +apply to a directory, then the most specific one is taken completely; the +options are not merged. However if <em>all</em> the options on the +<code>SSLOptions</code> directive are preceded by a plus (<code>+</code>) or +minus (<code>-</code>) symbol, the options are merged. Any options preceded by +a <code>+</code> are added to the options currently in force, and any options +preceded by a <code>-</code> are removed from the options currently in force. +<p> +The available <em>option</em>s are: +<ul> +<li><code>StdEnvVars</code> + <p> + When this option is enabled, the standard set of SSL related CGI/SSI + environment variables are created. This per default is disabled for + performance reasons, because the information extraction step is a + rather expensive operation. So one usually enables this option for + CGI and SSI requests only. +<p> +<li><code>CompatEnvVars</code> + <p> + When this option is enabled, additional CGI/SSI environment variables are + created for backward compatibility to other Apache SSL solutions. Look in + the <a href="ssl_compat.html">Compatibility</a> chapter for details + on the particular variables generated. +<p> +<li><code>ExportCertData</code> + <p> + When this option is enabled, additional CGI/SSI environment variables are + created: <code>SSL_SERVER_CERT</code>, <code>SSL_CLIENT_CERT</code> and + <code>SSL_CLIENT_CERT_CHAIN</code><i>n</i> (with <i>n</i> = 0,1,2,..). + These contain the PEM-encoded X.509 Certificates of server and client for + the current HTTPS connection and can be used by CGI scripts for deeper + Certificate checking. Additionally all other certificates of the client + certificate chain are provided, too. This bloats up the environment a + little bit which is why you have to use this option to enable it on + demand. +<p> +<li><code>FakeBasicAuth</code> + <p> + When this option is enabled, the Subject Distinguished Name (DN) of the + Client X509 Certificate is translated into a HTTP Basic Authorization + username. This means that the standard Apache authentication methods can + be used for access control. The user name is just the Subject of the + Client's X509 Certificate (can be determined by running OpenSSL's + <code>openssl x509</code> command: <code>openssl x509 -noout -subject -in + </code><em>certificate</em><code>.crt</code>). Note that no password is + obtained from the user. Every entry in the user file needs this password: + ``<code>xxj31ZMTZzkVA</code>'', which is the DES-encrypted version of the + word `<code>password</code>''. Those who live under MD5-based encryption + (for instance under FreeBSD or BSD/OS, etc.) should use the following MD5 + hash of the same word: ``<code>$1$OXLyS...$Owx8s2/m9/gfkcRVXzgoE/</code>''. +<p> +<li><code>StrictRequire</code> + <p> + This <i>forces</i> forbidden access when <code>SSLRequireSSL</code> or + <code>SSLRequire</code> successfully decided that access should be + forbidden. Usually the default is that in the case where a ``<code>Satisfy + any</code>'' directive is used, and other access restrictions are passed, + denial of access due to <code>SSLRequireSSL</code> or + <code>SSLRequire</code> is overridden (because that's how the Apache + <tt>Satisfy</tt> mechanism should work.) But for strict access restriction + you can use <code>SSLRequireSSL</code> and/or <code>SSLRequire</code> in + combination with an ``<code>SSLOptions +StrictRequire</code>''. Then an + additional ``<code>Satisfy Any</code>'' has no chance once mod_ssl has + decided to deny access. +<p> +<li><code>OptRenegotiate</code> + <p> + This enables optimized SSL connection renegotiation handling when SSL + directives are used in per-directory context. By default a strict + scheme is enabled where <i>every</i> per-directory reconfiguration of + SSL parameters causes a <i>full</i> SSL renegotiation handshake. When this + option is used mod_ssl tries to avoid unnecessary handshakes by doing more + granular (but still safe) parameter checks. Nevertheless these granular + checks sometimes maybe not what the user expects, so enable this on a + per-directory basis only, please. +</ul> +<p> +Example: +<blockquote> +<pre> +SSLOptions +FakeBasicAuth -StrictRequire +<Files ~ "\.(cgi|shtml)$"> + SSLOptions +StdEnvVars +CompatEnvVars -ExportCertData +<Files> +</pre> +</blockquote> +<!-- SSLRequireSSL --------------------------------------------------> +<p> +<br> +<a name="SSLRequireSSL"></a> +<h2><a name="ToC22">SSLRequireSSL</a></h2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLRequireSSL</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Deny access when SSL is not used for the HTTP request</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLRequireSSL</code></td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <em>None</em></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> directory, .htaccess</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> AuthConfig</td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.0 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<p> +This directive forbids access unless HTTP over SSL (i.e. HTTPS) is enabled for +the current connection. This is very handy inside the SSL-enabled virtual +host or directories for defending against configuration errors that expose +stuff that should be protected. When this directive is present all requests +are denied which are not using SSL. +<p> +Example: +<blockquote> +<pre> +SSLRequireSSL +</pre> +</blockquote> +<!-- SSLRequire -----------------------------------------------------> +<p> +<br> +<a name="SSLRequire"></a> +<h2><a name="ToC23">SSLRequire</a></h2> +<table cellspacing="0" cellpadding="1" bgcolor="#cccccc" border="0" summary=""> +<tr> +<td> +<table bgcolor="white" width="600" cellspacing="0" cellpadding="5" border="0" summary=""> +<tr> +<td> +<table cellspacing="0" cellpadding="1" border="0" summary=""> +<tr><td> +<font face="Arial,Helvetica"><b>Name:</b></font></a> </td><td> <b>SSLRequire</b></td></tr> +<tr><td> +<font face="Arial,Helvetica"><b>Description:</b></font></a> </td><td> Allow access only when an arbitrarily complex boolean expression is true</td></tr> +<tr><td><a + href="../directive-dict.html#Syntax" + rel="Help" +><font face="Arial,Helvetica"><b>Syntax:</b></font></a> </td><td> <code>SSLRequire</code> <em>expression</em></td></tr> +<tr><td><a + href="../directive-dict.html#Default" + rel="Help" +><font face="Arial,Helvetica"><b>Default:</b></font></a> </td><td> <em>None</em></td></tr> +<tr><td><a + href="../directive-dict.html#Context" + rel="Help" +><font face="Arial,Helvetica"><b>Context:</b></font></a> </td><td> directory, .htaccess</td></tr> +<tr><td><a + href="../directive-dict.html#Override" + rel="Help" +><font face="Arial,Helvetica"><b>Override:</b></font></a> </td><td> AuthConfig</td></tr> +<tr><td><a + href="../directive-dict.html#Status" + rel="Help" +><font face="Arial,Helvetica"><b>Status:</b></font></a> </td><td> Extension</td></tr> +<tr><td><a + href="../directive-dict.html#Module" + rel="Help" +><font face="Arial,Helvetica"><b>Module:</b></font></a> </td><td> mod_ssl</td></tr> +<tr><td><a + href="../directive-dict.html#Compatibility" + rel="Help" +><font face="Arial,Helvetica"><b>Compatibility:</b></font></a> </td><td> mod_ssl 2.1 </td></tr> +</table> +</td> +</tr> +</table> +</td> +</tr> +</table> +<p> +This directive specifies a general access requirement which has to be +fulfilled in order to allow access. It's a very powerful directive because the +requirement specification is an arbitrarily complex boolean expression +containing any number of access checks. +<p> +The <em>expression</em> must match the following syntax (given as a BNF +grammar notation): +<blockquote> +<pre> +expr ::= "<b>true</b>" | "<b>false</b>" + | "<b>!</b>" expr + | expr "<b>&&</b>" expr + | expr "<b>||</b>" expr + | "<b>(</b>" expr "<b>)</b>" + | comp + +comp ::= word "<b>==</b>" word | word "<b>eq</b>" word + | word "<b>!=</b>" word | word "<b>ne</b>" word + | word "<b><</b>" word | word "<b>lt</b>" word + | word "<b><=</b>" word | word "<b>le</b>" word + | word "<b>></b>" word | word "<b>gt</b>" word + | word "<b>>=</b>" word | word "<b>ge</b>" word + | word "<b>in</b>" "<b>{</b>" wordlist "<b>}</b>" + | word "<b>=~</b>" regex + | word "<b>!~</b>" regex + +wordlist ::= word + | wordlist "<b>,</b>" word + +word ::= digit + | cstring + | variable + | function + +digit ::= [0-9]+ +cstring ::= "..." +variable ::= "<b>%{</b>" varname "<b>}</b>" +function ::= funcname "<b>(</b>" funcargs "<b>)</b>" +</pre> +</blockquote> +while for <code>varname</code> any variable from <a href="#table3">Table 3</a> +can be used. Finally for <code>funcname</code> the following functions +are available: +<ul> +<li><code>file(</code><em>filename</em><code>)</code> + <p> + This function takes one string argument and expands to the contents of the + file. This is especially useful for matching this contents against a + regular expression, etc. +</ul> +Notice that <em>expression</em> is first parsed into an internal machine +representation and then evaluated in a second step. Actually, in Global and +Per-Server Class context <em>expression</em> is parsed at startup time and +at runtime only the machine representation is executed. For Per-Directory +context this is different: here <em>expression</em> has to be parsed and +immediately executed for every request. +<p> +Example: +<blockquote> +<pre> +SSLRequire ( %{SSL_CIPHER} !~ m/^(EXP|NULL)-/ \ + and %{SSL_CLIENT_S_DN_O} eq "Snake Oil, Ltd." \ + and %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"} \ + and %{TIME_WDAY} >= 1 and %{TIME_WDAY} <= 5 \ + and %{TIME_HOUR} >= 8 and %{TIME_HOUR} <= 20 ) \ + or %{REMOTE_ADDR} =~ m/^192\.76\.162\.[0-9]+$/ +</pre> +</blockquote> +<div align="center"> +<a name="table3"></a> +<table width="600" cellspacing="0" cellpadding="1" border="0" summary=""> +<caption align="bottom" id="sf">Table 3: Available Variables for SSLRequire</caption> +<tr><td bgcolor="#cccccc"> +<table width="598" cellpadding="5" cellspacing="0" border="0" summary=""> +<tr><td valign="top" align="center" bgcolor="#ffffff"> +<table summary=""><tr><td> +<em>Standard CGI/1.0 and Apache variables:</em> +<pre> +HTTP_USER_AGENT PATH_INFO AUTH_TYPE +HTTP_REFERER QUERY_STRING SERVER_SOFTWARE +HTTP_COOKIE REMOTE_HOST API_VERSION +HTTP_FORWARDED REMOTE_IDENT TIME_YEAR +HTTP_HOST IS_SUBREQ TIME_MON +HTTP_PROXY_CONNECTION DOCUMENT_ROOT TIME_DAY +HTTP_ACCEPT SERVER_ADMIN TIME_HOUR +HTTP:headername SERVER_NAME TIME_MIN +THE_REQUEST SERVER_PORT TIME_SEC +REQUEST_METHOD SERVER_PROTOCOL TIME_WDAY +REQUEST_SCHEME REMOTE_ADDR TIME +REQUEST_URI REMOTE_USER ENV:<b>variablename</b> +REQUEST_FILENAME +</pre> +<em>SSL-related variables:</em> +<pre> +HTTPS SSL_CLIENT_M_VERSION SSL_SERVER_M_VERSION + SSL_CLIENT_M_SERIAL SSL_SERVER_M_SERIAL +SSL_PROTOCOL SSL_CLIENT_V_START SSL_SERVER_V_START +SSL_SESSION_ID SSL_CLIENT_V_END SSL_SERVER_V_END +SSL_CIPHER SSL_CLIENT_S_DN SSL_SERVER_S_DN +SSL_CIPHER_EXPORT SSL_CLIENT_S_DN_C SSL_SERVER_S_DN_C +SSL_CIPHER_ALGKEYSIZE SSL_CLIENT_S_DN_ST SSL_SERVER_S_DN_ST +SSL_CIPHER_USEKEYSIZE SSL_CLIENT_S_DN_L SSL_SERVER_S_DN_L +SSL_VERSION_LIBRARY SSL_CLIENT_S_DN_O SSL_SERVER_S_DN_O +SSL_VERSION_INTERFACE SSL_CLIENT_S_DN_OU SSL_SERVER_S_DN_OU + SSL_CLIENT_S_DN_CN SSL_SERVER_S_DN_CN + SSL_CLIENT_S_DN_T SSL_SERVER_S_DN_T + SSL_CLIENT_S_DN_I SSL_SERVER_S_DN_I + SSL_CLIENT_S_DN_G SSL_SERVER_S_DN_G + SSL_CLIENT_S_DN_S SSL_SERVER_S_DN_S + SSL_CLIENT_S_DN_D SSL_SERVER_S_DN_D + SSL_CLIENT_S_DN_UID SSL_SERVER_S_DN_UID + SSL_CLIENT_S_DN_Email SSL_SERVER_S_DN_Email + SSL_CLIENT_I_DN SSL_SERVER_I_DN + SSL_CLIENT_I_DN_C SSL_SERVER_I_DN_C + SSL_CLIENT_I_DN_ST SSL_SERVER_I_DN_ST + SSL_CLIENT_I_DN_L SSL_SERVER_I_DN_L + SSL_CLIENT_I_DN_O SSL_SERVER_I_DN_O + SSL_CLIENT_I_DN_OU SSL_SERVER_I_DN_OU + SSL_CLIENT_I_DN_CN SSL_SERVER_I_DN_CN + SSL_CLIENT_I_DN_T SSL_SERVER_I_DN_T + SSL_CLIENT_I_DN_I SSL_SERVER_I_DN_I + SSL_CLIENT_I_DN_G SSL_SERVER_I_DN_G + SSL_CLIENT_I_DN_S SSL_SERVER_I_DN_S + SSL_CLIENT_I_DN_D SSL_SERVER_I_DN_D + SSL_CLIENT_I_DN_UID SSL_SERVER_I_DN_UID + SSL_CLIENT_I_DN_Email SSL_SERVER_I_DN_Email + SSL_CLIENT_A_SIG SSL_SERVER_A_SIG + SSL_CLIENT_A_KEY SSL_SERVER_A_KEY + SSL_CLIENT_CERT SSL_SERVER_CERT + SSL_CLIENT_CERT_CHAIN<b>n</b> + SSL_CLIENT_VERIFY +</pre> +</td></tr></table> +</td> +</tr></table> +</td></tr></table> +</div> +<br> +<br> +<p> +<h1><a name="ToC24">Additional Features</a></h1> +<h2><a name="ToC25">Environment Variables</a></h2> +This module provides a lot of SSL information as additional environment +variables to the SSI and CGI namespace. The generated variables are listed in +<a href="#table4">Table 4</a>. For backward compatibility the information can +be made available under different names, too. Look in the <a +href="ssl_compat.html">Compatibility</a> chapter for details on the +compatibility variables. +<p> +<div align="center"> +<a name="table4"></a> +<table width="600" cellspacing="0" cellpadding="1" border="0" summary=""> +<caption align="bottom" id="sf">Table 4: SSI/CGI Environment Variables</caption> +<tr><td bgcolor="#cccccc"> +<table width="598" cellpadding="5" cellspacing="0" border="0" summary=""> +<tr><td valign="top" align="center" bgcolor="#ffffff"> +<table border="0" cellspacing="0" cellpadding="2" width="598" summary=""> +<tr id="H"> + <td><b>Variable Name:</b></td> + <td><b>Value Type:</b></td> + <td><b>Description:</b></td> +</tr> +<tr id="D"><td><code>HTTPS</code></td> <td>flag</td> <td>HTTPS is being used.</td></tr> +<tr id="H"><td><code>SSL_PROTOCOL</code></td> <td>string</td> <td>The SSL protocol version (SSLv2, SSLv3, TLSv1)</td></tr> +<tr id="H"><td><code>SSL_SESSION_ID</code></td> <td>string</td> <td>The hex-encoded SSL session id</td></tr> +<tr id="D"><td><code>SSL_CIPHER</code></td> <td>string</td> <td>The cipher specification name</td></tr> +<tr id="D"><td><code>SSL_CIPHER_EXPORT</code></td> <td>string</td> <td><code>true</code> if cipher is an export cipher</td></tr> +<tr id="H"><td><code>SSL_CIPHER_USEKEYSIZE</code></td> <td>number</td> <td>Number of cipher bits (actually used)</td></tr> +<tr id="D"><td><code>SSL_CIPHER_ALGKEYSIZE</code></td> <td>number</td> <td>Number of cipher bits (possible)</td></tr> +<tr id="H"><td><code>SSL_VERSION_INTERFACE</code></td> <td>string</td> <td>The mod_ssl program version</td></tr> +<tr id="D"><td><code>SSL_VERSION_LIBRARY</code></td> <td>string</td> <td>The OpenSSL program version</td></tr> +<tr id="H"><td><code>SSL_CLIENT_M_VERSION</code></td> <td>string</td> <td>The version of the client certificate</td></tr> +<tr id="D"><td><code>SSL_CLIENT_M_SERIAL</code></td> <td>string</td> <td>The serial of the client certificate</td></tr> +<tr id="H"><td><code>SSL_CLIENT_S_DN</code></td> <td>string</td> <td>Subject DN in client's certificate</td></tr> +<tr id="D"><td><code>SSL_CLIENT_S_DN_</code><em>x509</em></td> <td>string</td> <td>Component of client's Subject DN</td></tr> +<tr id="H"><td><code>SSL_CLIENT_I_DN</code></td> <td>string</td> <td>Issuer DN of client's certificate</td></tr> +<tr id="D"><td><code>SSL_CLIENT_I_DN_</code><em>x509</em></td> <td>string</td> <td>Component of client's Issuer DN</td></tr> +<tr id="H"><td><code>SSL_CLIENT_V_START</code></td> <td>string</td> <td>Validity of client's certificate (start time)</td></tr> +<tr id="D"><td><code>SSL_CLIENT_V_END</code></td> <td>string</td> <td>Validity of client's certificate (end time)</td></tr> +<tr id="H"><td><code>SSL_CLIENT_A_SIG</code></td> <td>string</td> <td>Algorithm used for the signature of client's certificate</td></tr> +<tr id="D"><td><code>SSL_CLIENT_A_KEY</code></td> <td>string</td> <td>Algorithm used for the public key of client's certificate</td></tr> +<tr id="H"><td><code>SSL_CLIENT_CERT</code></td> <td>string</td> <td>PEM-encoded client certificate</td></tr> +<tr id="D"><td><code>SSL_CLIENT_CERT_CHAIN</code><i>n</i></td> <td>string</td> <td>PEM-encoded certificates in client certificate chain</td></tr> +<tr id="H"><td><code>SSL_CLIENT_VERIFY</code></td> <td>string</td> <td><tt>NONE</tt>, <tt>SUCCESS</tt>, <tt>GENEROUS</tt> or <tt>FAILED:</tt><i>reason</i></td></tr> +<tr id="D"><td><code>SSL_SERVER_M_VERSION</code></td> <td>string</td> <td>The version of the server certificate</td></tr> +<tr id="H"><td><code>SSL_SERVER_M_SERIAL</code></td> <td>string</td> <td>The serial of the server certificate</td></tr> +<tr id="D"><td><code>SSL_SERVER_S_DN</code></td> <td>string</td> <td>Subject DN in server's certificate</td></tr> +<tr id="H"><td><code>SSL_SERVER_S_DN_</code><em>x509</em></td> <td>string</td> <td>Component of server's Subject DN</td></tr> +<tr id="D"><td><code>SSL_SERVER_I_DN</code></td> <td>string</td> <td>Issuer DN of server's certificate</td></tr> +<tr id="H"><td><code>SSL_SERVER_I_DN_</code><em>x509</em></td> <td>string</td> <td>Component of server's Issuer DN</td></tr> +<tr id="D"><td><code>SSL_SERVER_V_START</code></td> <td>string</td> <td>Validity of server's certificate (start time)</td></tr> +<tr id="H"><td><code>SSL_SERVER_V_END</code></td> <td>string</td> <td>Validity of server's certificate (end time)</td></tr> +<tr id="D"><td><code>SSL_SERVER_A_SIG</code></td> <td>string</td> <td>Algorithm used for the signature of server's certificate</td></tr> +<tr id="H"><td><code>SSL_SERVER_A_KEY</code></td> <td>string</td> <td>Algorithm used for the public key of server's certificate</td></tr> +<tr id="D"><td><code>SSL_SERVER_CERT</code></td> <td>string</td> <td>PEM-encoded server certificate</td></tr> +</table> +[ where <em>x509</em> is a component of a X.509 DN: + <code>C,ST,L,O,OU,CN,T,I,G,S,D,UID,Email</code> ] +</td> +</tr></table> +</td></tr></table> +</div> +<p> +<br> +<h2><a name="ToC26">Custom Log Formats</a></h2> +When mod_ssl is built into Apache or at least loaded (under DSO situation) +additional functions exist for the <a +href="../mod_log_config.html#formats">Custom Log Format</a> of <a +href="../mod_log_config.html">mod_log_config</a>. First there is an additional +``<code>%{</code><em>varname</em><code>}x</code>'' eXtension format function +which can be used to expand any variables provided by any module, especially +those provided by mod_ssl which can you find in <a href="#table4">Table 4</a>. +<p> +For backward compatibility there is additionally a special +``<code>%{</code><em>name</em><code>}c</code>'' cryptography format function +provided. Information about this function is provided in the <a +href="ssl_compat.html">Compatibility</a> chapter. +<p> +Example: +<blockquote> +<pre> +CustomLog logs/ssl_request_log \ + "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b" +</pre> +</blockquote> + <p> + <br> + <table summary=""> + <tr> + <td> + <table width="600" border="0" summary=""> + <tr> + <td valign="top" align="left" width="250"> +<a href="ssl_intro.html" onmouseover="ro_imgOver('ro_img_prev_bot', 'previous page'); return true" onmouseout="ro_imgNormal('ro_img_prev_bot'); return true" onfocus="ro_imgOver('ro_img_prev_bot', 'previous page'); return true" onblur="ro_imgNormal('ro_img_prev_bot'); return true"><img name="ro_img_prev_bot" src="ssl_template.navbut-prev-n.gif" alt="previous page" width="70" height="18" border="0"></a><br><font color="#000000">Introduction</font> + </td> + <td valign="top" align="right" width="250"> +<a href="ssl_compat.html" onmouseover="ro_imgOver('ro_img_next_bot', 'next page'); return true" onmouseout="ro_imgNormal('ro_img_next_bot'); return true" onfocus="ro_imgOver('ro_img_next_bot', 'next page'); return true" onblur="ro_imgNormal('ro_img_next_bot'); return true"><img name="ro_img_next_bot" src="ssl_template.navbut-next-n.gif" alt="next page" width="70" height="18" border="0"></a><br><font color="#000000">Compatibility</font> + </td> + </tr> + </table> + </td> + </tr> + <tr> + <td><img src="ssl_template.imgdot-1x1-000000.gif" alt="" width="600" height="2" align="bottom" border="0"></td> + </tr> + <tr> + <td><table width="598" summary=""> + <tr> + <td align="left"><font face="Arial,Helvetica"> + <a href="http://www.modssl.org/">mod_ssl</a> 2.8, User Manual<br> + The Apache Interface to OpenSSL + </font> + </td> + <td align="right"><font face="Arial,Helvetica"> + Copyright © 1998-2001 + <a href="http://www.engelschall.com/">Ralf S. Engelschall</a><br> + All Rights Reserved<br> + </font> + </td> + </tr> + </table> + </td> + </tr> + </table> + </td> +</tr> +</table> +</div> +</body> +</html> diff --git a/docs/manual/mod/mod_ssl.xml b/docs/manual/mod/mod_ssl.xml new file mode 100644 index 0000000000..71f41d7665 --- /dev/null +++ b/docs/manual/mod/mod_ssl.xml @@ -0,0 +1,1256 @@ +<?xml version="1.0"?> +<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd"> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>mod_ssl</name> +<description>Strong cryptography using the Secure Sockets +Layer (SSL) and Transport Layer Security (TLS) protocols</description> +<status>Extension</status> +<sourcefile>mod_ssl.c</sourcefile> +<identifier>ssl_module</identifier> + +<summary> +<p>This module provides SSL v2/v3 and TLS v1 support for the Apache +HTTP Server. It was contributed by Ralf S. Engeschall based on his +mod_ssl project and originally derived from work by Ben Laurie.</p> + +<p>This module relies on <a href="http://www.openssl.org/">OpenSSL</a> +to provide the cryptography engine.</p> + +<p>Further details, discussion, and examples are provided in the +<a href="../ssl/">SSL documentation</a>.</p> +</summary> + +<section id="ToC25"><title>Environment Variables</title> + +<p>This module provides a lot of SSL information as additional environment +variables to the SSI and CGI namespace. The generated variables are listed in +the table below. For backward compatibility the information can +be made available under different names, too. Look in the <a +href="../ssl/ssl_compat.html">Compatibility</a> chapter for details on the +compatibility variables.</p> + +<div align="center"> +<a name="table4"></a> +<table width="600" cellspacing="0" cellpadding="1" border="0" summary=""> +<caption align="bottom" id="sf">SSI/CGI Environment Variables</caption> +<tr><td bgcolor="#cccccc"> +<table width="598" cellpadding="5" cellspacing="0" border="0" summary=""> +<tr><td valign="top" align="center" bgcolor="#ffffff"> +<table border="0" cellspacing="0" cellpadding="2" width="598" summary=""> +<tr id="H"> + <td><strong>Variable Name:</strong></td> + <td><strong>Value Type:</strong></td> + <td><strong>Description:</strong></td> +</tr> +<tr id="D"><td><code>HTTPS</code></td> <td>flag</td> <td>HTTPS is being used.</td></tr> +<tr id="H"><td><code>SSL_PROTOCOL</code></td> <td>string</td> <td>The SSL protocol version (SSLv2, SSLv3, TLSv1)</td></tr> +<tr id="H"><td><code>SSL_SESSION_ID</code></td> <td>string</td> <td>The hex-encoded SSL session id</td></tr> +<tr id="D"><td><code>SSL_CIPHER</code></td> <td>string</td> <td>The cipher specification name</td></tr> +<tr id="D"><td><code>SSL_CIPHER_EXPORT</code></td> <td>string</td> <td><code>true</code> if cipher is an export cipher</td></tr> +<tr id="H"><td><code>SSL_CIPHER_USEKEYSIZE</code></td> <td>number</td> <td>Number of cipher bits (actually used)</td></tr> +<tr id="D"><td><code>SSL_CIPHER_ALGKEYSIZE</code></td> <td>number</td> <td>Number of cipher bits (possible)</td></tr> +<tr id="H"><td><code>SSL_VERSION_INTERFACE</code></td> <td>string</td> <td>The mod_ssl program version</td></tr> +<tr id="D"><td><code>SSL_VERSION_LIBRARY</code></td> <td>string</td> <td>The OpenSSL program version</td></tr> +<tr id="H"><td><code>SSL_CLIENT_M_VERSION</code></td> <td>string</td> <td>The version of the client certificate</td></tr> +<tr id="D"><td><code>SSL_CLIENT_M_SERIAL</code></td> <td>string</td> <td>The serial of the client certificate</td></tr> +<tr id="H"><td><code>SSL_CLIENT_S_DN</code></td> <td>string</td> <td>Subject DN in client's certificate</td></tr> +<tr id="D"><td><code>SSL_CLIENT_S_DN_</code><em>x509</em></td> <td>string</td> <td>Component of client's Subject DN</td></tr> +<tr id="H"><td><code>SSL_CLIENT_I_DN</code></td> <td>string</td> <td>Issuer DN of client's certificate</td></tr> +<tr id="D"><td><code>SSL_CLIENT_I_DN_</code><em>x509</em></td> <td>string</td> <td>Component of client's Issuer DN</td></tr> +<tr id="H"><td><code>SSL_CLIENT_V_START</code></td> <td>string</td> <td>Validity of client's certificate (start time)</td></tr> +<tr id="D"><td><code>SSL_CLIENT_V_END</code></td> <td>string</td> <td>Validity of client's certificate (end time)</td></tr> +<tr id="H"><td><code>SSL_CLIENT_A_SIG</code></td> <td>string</td> <td>Algorithm used for the signature of client's certificate</td></tr> +<tr id="D"><td><code>SSL_CLIENT_A_KEY</code></td> <td>string</td> <td>Algorithm used for the public key of client's certificate</td></tr> +<tr id="H"><td><code>SSL_CLIENT_CERT</code></td> <td>string</td> <td>PEM-encoded client certificate</td></tr> +<tr id="D"><td><code>SSL_CLIENT_CERT_CHAIN</code><em>n</em></td> <td>string</td> <td>PEM-encoded certificates in client certificate chain</td></tr> +<tr id="H"><td><code>SSL_CLIENT_VERIFY</code></td> <td>string</td> <td><code>NONE</code>, <code>SUCCESS</code>, <code>GENEROUS</code> or <code>FAILED:</code><em>reason</em></td></tr> +<tr id="D"><td><code>SSL_SERVER_M_VERSION</code></td> <td>string</td> <td>The version of the server certificate</td></tr> +<tr id="H"><td><code>SSL_SERVER_M_SERIAL</code></td> <td>string</td> <td>The serial of the server certificate</td></tr> +<tr id="D"><td><code>SSL_SERVER_S_DN</code></td> <td>string</td> <td>Subject DN in server's certificate</td></tr> +<tr id="H"><td><code>SSL_SERVER_S_DN_</code><em>x509</em></td> <td>string</td> <td>Component of server's Subject DN</td></tr> +<tr id="D"><td><code>SSL_SERVER_I_DN</code></td> <td>string</td> <td>Issuer DN of server's certificate</td></tr> +<tr id="H"><td><code>SSL_SERVER_I_DN_</code><em>x509</em></td> <td>string</td> <td>Component of server's Issuer DN</td></tr> +<tr id="D"><td><code>SSL_SERVER_V_START</code></td> <td>string</td> <td>Validity of server's certificate (start time)</td></tr> +<tr id="H"><td><code>SSL_SERVER_V_END</code></td> <td>string</td> <td>Validity of server's certificate (end time)</td></tr> +<tr id="D"><td><code>SSL_SERVER_A_SIG</code></td> <td>string</td> <td>Algorithm used for the signature of server's certificate</td></tr> +<tr id="H"><td><code>SSL_SERVER_A_KEY</code></td> <td>string</td> <td>Algorithm used for the public key of server's certificate</td></tr> +<tr id="D"><td><code>SSL_SERVER_CERT</code></td> <td>string</td> <td>PEM-encoded server certificate</td></tr> +</table> +[ where <em>x509</em> is a component of a X.509 DN: + <code>C,ST,L,O,OU,CN,T,I,G,S,D,UID,Email</code> ] +</td> +</tr></table> +</td></tr></table> +</div> +</section> + +<section id="ToC26"><title>Custom Log Formats</title> + +<p>When <module>mod_ssl</module> is built into Apache or at least +loaded (under DSO situation) additional functions exist for the <a +href="../mod_log_config.html#formats">Custom Log Format</a> of +<module>mod_log_config</module>. First there is an +additional ``<code>%{</code><em>varname</em><code>}x</code>'' +eXtension format function which can be used to expand any variables +provided by any module, especially those provided by mod_ssl which can +you find in the above table.</p> +<p> +For backward compatibility there is additionally a special +``<code>%{</code><em>name</em><code>}c</code>'' cryptography format function +provided. Information about this function is provided in the <a +href="../ssl/ssl_compat.html">Compatibility</a> chapter.</p> +<p> +Example:</p> +<example> +CustomLog logs/ssl_request_log \ + "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b" +</example> +</section> + +<directivesynopsis> +<name>SSLPassPhraseDialog</name> +<description>Type of pass phrase dialog for encrypted private +keys</description> +<syntax>SSLPassPhraseDialog <em>type</em></syntax> +<default>SSLPassPhraseDialog builtin</default> +<contextlist><context>server config</context></contextlist> + +<usage> +<p> +When Apache starts up it has to read the various Certificate (see +<directive module="mod_ssl">SSLCertificateFile</directive>) and +Private Key (see <directive +module="mod_ssl">SSLCertificateKeyFile</directive>) files of the +SSL-enabled virtual servers. Because for security reasons the Private +Key files are usually encrypted, mod_ssl needs to query the +administrator for a Pass Phrase in order to decrypt those files. This +query can be done in two ways which can be configured by +<em>type</em>:</p> +<ul> +<li><code>builtin</code> + <p> + This is the default where an interactive terminal dialog occurs at startup + time just before Apache detaches from the terminal. Here the administrator + has to manually enter the Pass Phrase for each encrypted Private Key file. + Because a lot of SSL-enabled virtual hosts can be configured, the + following reuse-scheme is used to minimize the dialog: When a Private Key + file is encrypted, all known Pass Phrases (at the beginning there are + none, of course) are tried. If one of those known Pass Phrases succeeds no + dialog pops up for this particular Private Key file. If none succeeded, + another Pass Phrase is queried on the terminal and remembered for the next + round (where it perhaps can be reused).</p> + <p> + This scheme allows mod_ssl to be maximally flexible (because for N encrypted + Private Key files you <em>can</em> use N different Pass Phrases - but then + you have to enter all of them, of course) while minimizing the terminal + dialog (i.e. when you use a single Pass Phrase for all N Private Key files + this Pass Phrase is queried only once).</p></li> + +<li><code>exec:/path/to/program</code> + <p> + Here an external program is configured which is called at startup for each + encrypted Private Key file. It is called with two arguments (the first is + of the form ``<code>servername:portnumber</code>'', the second is either + ``<code>RSA</code>'' or ``<code>DSA</code>''), which indicate for which + server and algorithm it has to print the corresponding Pass Phrase to + <code>stdout</code>. The intent is that this external program first runs + security checks to make sure that the system is not compromised by an + attacker, and only when these checks were passed successfully it provides + the Pass Phrase.</p> + <p> + Both these security checks, and the way the Pass Phrase is determined, can + be as complex as you like. Mod_ssl just defines the interface: an + executable program which provides the Pass Phrase on <code>stdout</code>. + Nothing more or less! So, if you're really paranoid about security, here + is your interface. Anything else has to be left as an exercise to the + administrator, because local security requirements are so different.</p> + <p> + The reuse-algorithm above is used here, too. In other words: The external + program is called only once per unique Pass Phrase.</p></li> +</ul> +<p> +Example:</p> +<example> +SSLPassPhraseDialog exec:/usr/local/apache/sbin/pp-filter +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>SSLMutex</name> +<description>Semaphore for internal mutual exclusion of +operations</description> +<syntax>SSLMutex <em>type</em></syntax> +<default>SSLMutex none</default> +<contextlist><context>server config</context></contextlist> + +<usage> +<p> +This configures the SSL engine's semaphore (aka. lock) which is used for mutual +exclusion of operations which have to be done in a synchronized way between the +pre-forked Apache server processes. This directive can only be used in the +global server context because it's only useful to have one global mutex.</p> +<p> +The following Mutex <em>types</em> are available:</p> +<ul> +<li><code>none</code> + <p> + This is the default where no Mutex is used at all. Use it at your own + risk. But because currently the Mutex is mainly used for synchronizing + write access to the SSL Session Cache you can live without it as long + as you accept a sometimes garbled Session Cache. So it's not recommended + to leave this the default. Instead configure a real Mutex.</p></li> +<li><code>file:/path/to/mutex</code> + <p> + This is the portable and (under Unix) always provided Mutex variant where + a physical (lock-)file is used as the Mutex. Always use a local disk + filesystem for <code>/path/to/mutex</code> and never a file residing on a + NFS- or AFS-filesystem. Note: Internally, the Process ID (PID) of the + Apache parent process is automatically appended to + <code>/path/to/mutex</code> to make it unique, so you don't have to worry + about conflicts yourself. Notice that this type of mutex is not available + under the Win32 environment. There you <em>have</em> to use the semaphore + mutex.</p></li> +<li><code>sem</code> + <p> + This is the most elegant but also most non-portable Mutex variant where a + SysV IPC Semaphore (under Unix) and a Windows Mutex (under Win32) is used + when possible. It is only available when the underlying platform + supports it.</p></li> +</ul> +<example><title>Example</title> +SSLMutex file:/usr/local/apache/logs/ssl_mutex +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>SSLRandomSeed</name> +<description>Pseudo Random Number Generator (PRNG) seeding +source</description> +<syntax>SSLRandomSeed <em>context</em> <em>source</em> +[<em>bytes</em>]</syntax> +<contextlist><context>server config</context></contextlist> + +<usage> +<p> +This configures one or more sources for seeding the Pseudo Random Number +Generator (PRNG) in OpenSSL at startup time (<em>context</em> is +<code>startup</code>) and/or just before a new SSL connection is established +(<em>context</em> is <code>connect</code>). This directive can only be used +in the global server context because the PRNG is a global facility.</p> +<p> +The following <em>source</em> variants are available:</p> +<ul> +<li><code>builtin</code> + <p> This is the always available builtin seeding source. It's usage + consumes minimum CPU cycles under runtime and hence can be always used + without drawbacks. The source used for seeding the PRNG contains of the + current time, the current process id and (when applicable) a randomly + choosen 1KB extract of the inter-process scoreboard structure of Apache. + The drawback is that this is not really a strong source and at startup + time (where the scoreboard is still not available) this source just + produces a few bytes of entropy. So you should always, at least for the + startup, use an additional seeding source.</p></li> +<li><code>file:/path/to/source</code> + <p> + This variant uses an external file <code>/path/to/source</code> as the + source for seeding the PRNG. When <em>bytes</em> is specified, only the + first <em>bytes</em> number of bytes of the file form the entropy (and + <em>bytes</em> is given to <code>/path/to/source</code> as the first + argument). When <em>bytes</em> is not specified the whole file forms the + entropy (and <code>0</code> is given to <code>/path/to/source</code> as + the first argument). Use this especially at startup time, for instance + with an available <code>/dev/random</code> and/or + <code>/dev/urandom</code> devices (which usually exist on modern Unix + derivates like FreeBSD and Linux).</p> + <p> + <em>But be careful</em>: Usually <code>/dev/random</code> provides only as + much entropy data as it actually has, i.e. when you request 512 bytes of + entropy, but the device currently has only 100 bytes available two things + can happen: On some platforms you receive only the 100 bytes while on + other platforms the read blocks until enough bytes are available (which + can take a long time). Here using an existing <code>/dev/urandom</code> is + better, because it never blocks and actually gives the amount of requested + data. The drawback is just that the quality of the received data may not + be the best.</p> + <p> + On some platforms like FreeBSD one can even control how the entropy is + actually generated, i.e. by which system interrupts. More details one can + find under <em>rndcontrol(8)</em> on those platforms. Alternatively, when + your system lacks such a random device, you can use tool + like <a href="http://www.lothar.com/tech/crypto/">EGD</a> + (Entropy Gathering Daemon) and run it's client program with the + <code>exec:/path/to/program/</code> variant (see below) or use + <code>egd:/path/to/egd-socket</code> (see below).</p></li> + +<li><code>exec:/path/to/program</code> + <p> + This variant uses an external executable + <code>/path/to/program</code> as the source for seeding the + PRNG. When <em>bytes</em> is specified, only the first + <em>bytes</em> number of bytes of its <code>stdout</code> contents + form the entropy. When <em>bytes</em> is not specified, the + entirety of the data produced on <code>stdout</code> form the + entropy. Use this only at startup time when you need a very strong + seeding with the help of an external program (for instance as in + the example above with the <code>truerand</code> utility you can + find in the mod_ssl distribution which is based on the AT&T + <em>truerand</em> library). Using this in the connection context + slows down the server too dramatically, of course. So usually you + should avoid using external programs in that context.</p></li> +<li><code>egd:/path/to/egd-socket</code> (Unix only) + <p> + This variant uses the Unix domain socket of the + external Entropy Gathering Daemon (EGD) (see <a + href="http://www.lothar.com/tech/crypto/">http://www.lothar.com/tech + /crypto/</a>) to seed the PRNG. Use this if no random device exists + on your platform.</p></li> +</ul> +<example><title>Example</title> +SSLRandomSeed startup builtin<br /> +SSLRandomSeed startup file:/dev/random<br /> +SSLRandomSeed startup file:/dev/urandom 1024<br /> +SSLRandomSeed startup exec:/usr/local/bin/truerand 16<br /> +SSLRandomSeed connect builtin<br /> +SSLRandomSeed connect file:/dev/random<br /> +SSLRandomSeed connect file:/dev/urandom 1024<br /> +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>SSLSessionCache</name> +<description>Type of the global/inter-process SSL Session +Cache</description> +<syntax>SSLSessionCache <em>type</em></syntax> +<default>SSLSessionCache none</default> +<contextlist><context>server config</context></contextlist> + +<usage> +<p> +This configures the storage type of the global/inter-process SSL Session +Cache. This cache is an optional facility which speeds up parallel request +processing. For requests to the same server process (via HTTP keep-alive), +OpenSSL already caches the SSL session information locally. But because modern +clients request inlined images and other data via parallel requests (usually +up to four parallel requests are common) those requests are served by +<em>different</em> pre-forked server processes. Here an inter-process cache +helps to avoid unneccessary session handshakes.</p> +<p> +The following two storage <em>type</em>s are currently supported:</p> +<ul> +<li><code>none</code> + <p> + This is the default and just disables the global/inter-process Session + Cache. There is no drawback in functionality, but a noticeable speed + penalty can be observed.</p></li> +<li><code>dbm:/path/to/datafile</code> + <p> + This makes use of a DBM hashfile on the local disk to synchronize the + local OpenSSL memory caches of the server processes. The slight increase + in I/O on the server results in a visible request speedup for your + clients, so this type of storage is generally recommended.</p></li> +<li><code>shm:/path/to/datafile</code>[<code>(</code><em>size</em><code>)</code>] + <p> + This makes use of a high-performance hash table (approx. <em>size</em> bytes + in size) inside a shared memory segment in RAM (established via + <code>/path/to/datafile</code>) to synchronize the local OpenSSL memory + caches of the server processes. This storage type is not available on all + platforms. See the mod_ssl <code>INSTALL</code> document for details on + how to build Apache+EAPI with shared memory support.</p></li> +</ul> +<example><title>Examples</title> +SSLSessionCache dbm:/usr/local/apache/logs/ssl_gcache_data<br /> +SSLSessionCache shm:/usr/local/apache/logs/ssl_gcache_data(512000) +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>SSLSessionCacheTimeout</name> +<description>Number of seconds before an SSL session expires +in the Session Cache</description> +<syntax>SSLSessionCacheTimeout <em>seconds</em></syntax> +<default>SSLSessionCacheTimeout 300</default> +<contextlist><context>server config</context> +<context>virtual host</context></contextlist> + +<usage> +<p> +This directive sets the timeout in seconds for the information stored in the +global/inter-process SSL Session Cache and the OpenSSL internal memory cache. +It can be set as low as 15 for testing, but should be set to higher +values like 300 in real life.</p> +<example><title>Example</title> +SSLSessionCacheTimeout 600 +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>SSLEngine</name> +<description>SSL Engine Operation Switch</description> +<syntax>SSLEngine on|off</syntax> +<default>SSLEngine off</default> +<contextlist><context>server config</context> +<context>virtual host</context></contextlist> + +<usage> +<p> +This directive toggles the usage of the SSL/TLS Protocol Engine. This +is usually used inside a <directive module="core" +type="section">VirtualHost</directive> section to enable SSL/TLS for a +particular virtual host. By default the SSL/TLS Protocol Engine is +disabled for both the main server and all configured virtual hosts.</p> +<example><title>Example</title> +<VirtualHost _default_:443><br /> +SSLEngine on<br /> +...<br /> +</VirtualHost> +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>SSLProtocol</name> +<description>Configure usable SSL protocol flavors</description> +<syntax>SSLProtocol [+|-]<em>protocol</em> ...</syntax> +<default>SSLProtocol all</default> +<contextlist><context>server config</context> +<context>virtual host</context></contextlist> +<override>Options</override> + +<usage><!-- XXX Why does this have an override and not .htaccess context? --> +<p> +This directive can be used to control the SSL protocol flavors mod_ssl should +use when establishing its server environment. Clients then can only connect +with one of the provided protocols.</p> +<p> +The available (case-insensitive) <em>protocol</em>s are:</p> +<ul> +<li><code>SSLv2</code> + <p> + This is the Secure Sockets Layer (SSL) protocol, version 2.0. It is the + original SSL protocol as designed by Netscape Corporation.</p></li> + +<li><code>SSLv3</code> + <p> + This is the Secure Sockets Layer (SSL) protocol, version 3.0. It is the + successor to SSLv2 and the currently (as of February 1999) de-facto + standardized SSL protocol from Netscape Corporation. It's supported by + almost all popular browsers.</p></li> + +<li><code>TLSv1</code> + <p> + This is the Transport Layer Security (TLS) protocol, version 1.0. It is the + successor to SSLv3 and currently (as of February 1999) still under + construction by the Internet Engineering Task Force (IETF). It's still + not supported by any popular browsers.</p></li> + +<li><code>All</code> + <p> + This is a shortcut for ``<code>+SSLv2 +SSLv3 +TLSv1</code>'' and a + convinient way for enabling all protocols except one when used in + combination with the minus sign on a protocol as the example above + shows.</p></li> +</ul> +<example><title>Example</title> +# enable SSLv3 and TLSv1, but not SSLv2<br /> +SSLProtocol all -SSLv2 +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>SSLCipherSuite</name> +<description>Cipher Suite available for negotiation in SSL +handshake</description> +<syntax>SSLCipherSuite <em>cipher-spec</em></syntax> +<default>SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP</default> +<contextlist><context>server config</context> +<context>virtual host</context> +<context>directory</context> +<context>.htaccess</context></contextlist> +<override>AuthConfig</override> + +<usage> +<p> +This complex directive uses a colon-separated <em>cipher-spec</em> string +consisting of OpenSSL cipher specifications to configure the Cipher Suite the +client is permitted to negotiate in the SSL handshake phase. Notice that this +directive can be used both in per-server and per-directory context. In +per-server context it applies to the standard SSL handshake when a connection +is established. In per-directory context it forces a SSL renegotation with the +reconfigured Cipher Suite after the HTTP request was read but before the HTTP +response is sent.</p> +<p> +An SSL cipher specification in <em>cipher-spec</em> is composed of 4 major +attributes plus a few extra minor ones:</p> +<ul> +<li><em>Key Exchange Algorithm</em>:<br /> + RSA or Diffie-Hellman variants. +</li> +<li><em>Authentication Algorithm</em>:<br /> + RSA, Diffie-Hellman, DSS or none. +</li> +<li><em>Cipher/Encryption Algorithm</em>:<br /> + DES, Triple-DES, RC4, RC2, IDEA or none. +</li> +<li><em>MAC Digest Algorithm</em>:<br /> + MD5, SHA or SHA1. +</li> +</ul> +<p>An SSL cipher can also be an export cipher and is either a SSLv2 or SSLv3/TLSv1 +cipher (here TLSv1 is equivalent to SSLv3). To specify which ciphers to use, +one can either specify all the Ciphers, one at a time, or use aliases to +specify the preference and order for the ciphers (see <a href="#table1">Table +1</a>).</p> + +<div align="center"> +<a name="table1"></a> +<table width="600" cellspacing="0" cellpadding="1" border="0" summary=""> +<caption align="bottom" id="sf">Table 1: OpenSSL Cipher Specification Tags</caption> +<tr><td bgcolor="#cccccc"> +<table width="598" cellpadding="5" cellspacing="0" border="0" summary=""> +<tr><td valign="top" align="center" bgcolor="#ffffff"> +<table border="0" cellspacing="0" cellpadding="2" width="598" summary=""> +<tr id="D"><td><strong>Tag</strong></td> <td><strong>Description</strong></td></tr> +<tr id="H"><td colspan="2"><em>Key Exchange Algorithm:</em></td></tr> +<tr id="D"><td><code>kRSA</code></td> <td>RSA key exchange</td></tr> +<tr id="H"><td><code>kDHr</code></td> <td>Diffie-Hellman key exchange with RSA key</td></tr> +<tr id="D"><td><code>kDHd</code></td> <td>Diffie-Hellman key exchange with DSA key</td></tr> +<tr id="H"><td><code>kEDH</code></td> <td>Ephemeral (temp.key) Diffie-Hellman key exchange (no cert)</td> </tr> +<tr id="H"><td colspan="2"><em>Authentication Algorithm:</em></td></tr> +<tr id="D"><td><code>aNULL</code></td> <td>No authentication</td></tr> +<tr id="H"><td><code>aRSA</code></td> <td>RSA authentication</td></tr> +<tr id="D"><td><code>aDSS</code></td> <td>DSS authentication</td> </tr> +<tr id="H"><td><code>aDH</code></td> <td>Diffie-Hellman authentication</td></tr> +<tr id="D"><td colspan="2"><em>Cipher Encoding Algorithm:</em></td></tr> +<tr id="H"><td><code>eNULL</code></td> <td>No encoding</td> </tr> +<tr id="D"><td><code>DES</code></td> <td>DES encoding</td> </tr> +<tr id="H"><td><code>3DES</code></td> <td>Triple-DES encoding</td> </tr> +<tr id="D"><td><code>RC4</code></td> <td>RC4 encoding</td> </tr> +<tr id="H"><td><code>RC2</code></td> <td>RC2 encoding</td> </tr> +<tr id="D"><td><code>IDEA</code></td> <td>IDEA encoding</td> </tr> +<tr id="H"><td colspan="2"><em>MAC Digest Algorithm</em>:</td></tr> +<tr id="D"><td><code>MD5</code></td> <td>MD5 hash function</td></tr> +<tr id="H"><td><code>SHA1</code></td> <td>SHA1 hash function</td></tr> +<tr id="D"><td><code>SHA</code></td> <td>SHA hash function</td> </tr> +<tr id="H"><td colspan="2"><em>Aliases:</em></td></tr> +<tr id="D"><td><code>SSLv2</code></td> <td>all SSL version 2.0 ciphers</td></tr> +<tr id="H"><td><code>SSLv3</code></td> <td>all SSL version 3.0 ciphers</td> </tr> +<tr id="D"><td><code>TLSv1</code></td> <td>all TLS version 1.0 ciphers</td> </tr> +<tr id="H"><td><code>EXP</code></td> <td>all export ciphers</td> </tr> +<tr id="D"><td><code>EXPORT40</code></td> <td>all 40-bit export ciphers only</td> </tr> +<tr id="H"><td><code>EXPORT56</code></td> <td>all 56-bit export ciphers only</td> </tr> +<tr id="D"><td><code>LOW</code></td> <td>all low strength ciphers (no export, single DES)</td></tr> +<tr id="H"><td><code>MEDIUM</code></td> <td>all ciphers with 128 bit encryption</td> </tr> +<tr id="D"><td><code>HIGH</code></td> <td>all ciphers using Triple-DES</td> </tr> +<tr id="H"><td><code>RSA</code></td> <td>all ciphers using RSA key exchange</td> </tr> +<tr id="D"><td><code>DH</code></td> <td>all ciphers using Diffie-Hellman key exchange</td> </tr> +<tr id="H"><td><code>EDH</code></td> <td>all ciphers using Ephemeral Diffie-Hellman key exchange</td> </tr> +<tr id="D"><td><code>ADH</code></td> <td>all ciphers using Anonymous Diffie-Hellman key exchange</td> </tr> +<tr id="H"><td><code>DSS</code></td> <td>all ciphers using DSS authentication</td> </tr> +<tr id="D"><td><code>NULL</code></td> <td>all ciphers using no encryption</td> </tr> +</table> +</td> +</tr></table> +</td></tr></table> +</div> +<p> +Now where this becomes interesting is that these can be put together +to specify the order and ciphers you wish to use. To speed this up +there are also aliases (<code>SSLv2, SSLv3, TLSv1, EXP, LOW, MEDIUM, +HIGH</code>) for certain groups of ciphers. These tags can be joined +together with prefixes to form the <em>cipher-spec</em>. Available +prefixes are:</p> +<ul> +<li>none: add cipher to list</li> +<li><code>+</code>: add ciphers to list and pull them to current location in list</li> +<li><code>-</code>: remove cipher from list (can be added later again)</li> +<li><code>!</code>: kill cipher from list completely (can <strong>not</strong> be added later again)</li> +</ul> +<p>A simpler way to look at all of this is to use the ``<code>openssl ciphers +-v</code>'' command which provides a nice way to successively create the +correct <em>cipher-spec</em> string. The default <em>cipher-spec</em> string +is ``<code>ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP</code>'' which +means the following: first, remove from consideration any ciphers that do not +authenticate, i.e. for SSL only the Anonymous Diffie-Hellman ciphers. Next, +use ciphers using RC4 and RSA. Next include the high, medium and then the low +security ciphers. Finally <em>pull</em> all SSLv2 and export ciphers to the +end of the list.</p> +<example> +<pre> +$ openssl ciphers -v 'ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP' +NULL-SHA SSLv3 Kx=RSA Au=RSA Enc=None Mac=SHA1 +NULL-MD5 SSLv3 Kx=RSA Au=RSA Enc=None Mac=MD5 +EDH-RSA-DES-CBC3-SHA SSLv3 Kx=DH Au=RSA Enc=3DES(168) Mac=SHA1 +... ... ... ... ... +EXP-RC4-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export +EXP-RC2-CBC-MD5 SSLv2 Kx=RSA(512) Au=RSA Enc=RC2(40) Mac=MD5 export +EXP-RC4-MD5 SSLv2 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export +</pre> +</example> +<p>The complete list of particular RSA & DH ciphers for SSL is given in <a +href="#table2">Table 2</a>.</p> +<example><title>Example</title> +SSLCipherSuite RSA:!EXP:!NULL:+HIGH:+MEDIUM:-LOW +</example> +<div align="center"> +<a name="table2"></a> +<table width="600" cellspacing="0" cellpadding="1" border="0" summary=""> +<caption align="bottom" id="sf">Table 2: Particular SSL Ciphers</caption> +<tr><td bgcolor="#cccccc"> +<table width="598" cellpadding="5" cellspacing="0" border="0" summary=""> +<tr><td valign="top" align="center" bgcolor="#ffffff"> +<table border="0" cellspacing="0" cellpadding="2" width="598" summary=""> +<tr id="D"><td><strong>Cipher-Tag</strong></td> <td><strong>Protocol</strong></td> <td><strong>Key Ex.</strong></td> <td><strong>Auth.</strong></td> <td><strong>Enc.</strong></td> <td><strong>MAC</strong></td> <td><strong>Type</strong></td> </tr> +<tr id="H"><td colspan="7"><em>RSA Ciphers:</em></td></tr> +<tr id="D"><td><code>DES-CBC3-SHA</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>3DES(168)</td> <td>SHA1</td> <td> </td> </tr> +<tr id="H"><td><code>DES-CBC3-MD5</code></td> <td>SSLv2</td> <td>RSA</td> <td>RSA</td> <td>3DES(168)</td> <td>MD5</td> <td> </td> </tr> +<tr id="D"><td><code>IDEA-CBC-SHA</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>IDEA(128)</td> <td>SHA1</td> <td> </td> </tr> +<tr id="H"><td><code>RC4-SHA</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>RC4(128)</td> <td>SHA1</td> <td> </td> </tr> +<tr id="D"><td><code>RC4-MD5</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>RC4(128)</td> <td>MD5</td> <td> </td> </tr> +<tr id="H"><td><code>IDEA-CBC-MD5</code></td> <td>SSLv2</td> <td>RSA</td> <td>RSA</td> <td>IDEA(128)</td> <td>MD5</td> <td> </td> </tr> +<tr id="D"><td><code>RC2-CBC-MD5</code></td> <td>SSLv2</td> <td>RSA</td> <td>RSA</td> <td>RC2(128)</td> <td>MD5</td> <td> </td> </tr> +<tr id="H"><td><code>RC4-MD5</code></td> <td>SSLv2</td> <td>RSA</td> <td>RSA</td> <td>RC4(128)</td> <td>MD5</td> <td> </td> </tr> +<tr id="D"><td><code>DES-CBC-SHA</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>DES(56)</td> <td>SHA1</td> <td> </td> </tr> +<tr id="H"><td><code>RC4-64-MD5</code></td> <td>SSLv2</td> <td>RSA</td> <td>RSA</td> <td>RC4(64)</td> <td>MD5</td> <td> </td> </tr> +<tr id="D"><td><code>DES-CBC-MD5</code></td> <td>SSLv2</td> <td>RSA</td> <td>RSA</td> <td>DES(56)</td> <td>MD5</td> <td> </td> </tr> +<tr id="H"><td><code>EXP-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>RSA(512)</td> <td>RSA</td> <td>DES(40)</td> <td>SHA1</td> <td> export</td> </tr> +<tr id="D"><td><code>EXP-RC2-CBC-MD5</code></td> <td>SSLv3</td> <td>RSA(512)</td> <td>RSA</td> <td>RC2(40)</td> <td>MD5</td> <td> export</td> </tr> +<tr id="H"><td><code>EXP-RC4-MD5</code></td> <td>SSLv3</td> <td>RSA(512)</td> <td>RSA</td> <td>RC4(40)</td> <td>MD5</td> <td> export</td> </tr> +<tr id="D"><td><code>EXP-RC2-CBC-MD5</code></td> <td>SSLv2</td> <td>RSA(512)</td> <td>RSA</td> <td>RC2(40)</td> <td>MD5</td> <td> export</td> </tr> +<tr id="H"><td><code>EXP-RC4-MD5</code></td> <td>SSLv2</td> <td>RSA(512)</td> <td>RSA</td> <td>RC4(40)</td> <td>MD5</td> <td> export</td> </tr> +<tr id="D"><td><code>NULL-SHA</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>None</td> <td>SHA1</td> <td> </td> </tr> +<tr id="H"><td><code>NULL-MD5</code></td> <td>SSLv3</td> <td>RSA</td> <td>RSA</td> <td>None</td> <td>MD5</td> <td> </td> </tr> +<tr id="D"><td colspan="7"><em>Diffie-Hellman Ciphers:</em></td></tr> +<tr id="H"><td><code>ADH-DES-CBC3-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>None</td> <td>3DES(168)</td> <td>SHA1</td> <td> </td> </tr> +<tr id="D"><td><code>ADH-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>None</td> <td>DES(56)</td> <td>SHA1</td> <td> </td> </tr> +<tr id="H"><td><code>ADH-RC4-MD5</code></td> <td>SSLv3</td> <td>DH</td> <td>None</td> <td>RC4(128)</td> <td>MD5</td> <td> </td> </tr> +<tr id="D"><td><code>EDH-RSA-DES-CBC3-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>RSA</td> <td>3DES(168)</td> <td>SHA1</td> <td> </td> </tr> +<tr id="H"><td><code>EDH-DSS-DES-CBC3-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>DSS</td> <td>3DES(168)</td> <td>SHA1</td> <td> </td> </tr> +<tr id="D"><td><code>EDH-RSA-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>RSA</td> <td>DES(56)</td> <td>SHA1</td> <td> </td> </tr> +<tr id="H"><td><code>EDH-DSS-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>DH</td> <td>DSS</td> <td>DES(56)</td> <td>SHA1</td> <td> </td> </tr> +<tr id="D"><td><code>EXP-EDH-RSA-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>DH(512)</td> <td>RSA</td> <td>DES(40)</td> <td>SHA1</td> <td> export</td> </tr> +<tr id="H"><td><code>EXP-EDH-DSS-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>DH(512)</td> <td>DSS</td> <td>DES(40)</td> <td>SHA1</td> <td> export</td> </tr> +<tr id="D"><td><code>EXP-ADH-DES-CBC-SHA</code></td> <td>SSLv3</td> <td>DH(512)</td> <td>None</td> <td>DES(40)</td> <td>SHA1</td> <td> export</td> </tr> +<tr id="H"><td><code>EXP-ADH-RC4-MD5</code></td> <td>SSLv3</td> <td>DH(512)</td> <td>None</td> <td>RC4(40)</td> <td>MD5</td> <td> export</td> </tr> +</table> +</td> +</tr></table> +</td></tr></table> +</div> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>SSLCertificateFile</name> +<description>Server PEM-encoded X.509 Certificate file</description> +<syntax>SSLCertificateFile <em>file-path</em></syntax> +<contextlist><context>server config</context> +<context>virtual host</context></contextlist> + +<usage> +<p> +This directive points to the PEM-encoded Certificate file for the server and +optionally also to the corresponding RSA or DSA Private Key file for it +(contained in the same file). If the contained Private Key is encrypted the +Pass Phrase dialog is forced at startup time. This directive can be used up to +two times (referencing different filenames) when both a RSA and a DSA based +server certificate is used in parallel.</p> +<example><title>Example</title> +SSLCertificateFile /usr/local/apache/conf/ssl.crt/server.crt +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>SSLCertificateKeyFile</name> +<description>Server PEM-encoded Private Key file</description> +<syntax>SSLCertificateKeyFile <em>file-path</em></syntax> +<contextlist><context>server config</context> +<context>virtual host</context></contextlist> + +<usage> +<p> +This directive points to the PEM-encoded Private Key file for the +server. If the Private Key is not combined with the Certificate in the +<directive>SSLCertificateFile</directive>, use this additional directive to +point to the file with the stand-alone Private Key. When +<directive>SSLCertificateFile</directive> is used and the file +contains both the Certificate and the Private Key this directive need +not be used. But we strongly discourage this practice. Instead we +recommend you to separate the Certificate and the Private Key. If the +contained Private Key is encrypted, the Pass Phrase dialog is forced +at startup time. This directive can be used up to two times +(referencing different filenames) when both a RSA and a DSA based +private key is used in parallel.</p> +<example><title>Example</title> +SSLCertificateKeyFile /usr/local/apache/conf/ssl.key/server.key +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>SSLCertificateChainFile</name> +<description>File of PEM-encoded Server CA Certificates</description> +<syntax>SSLCertificateChainFile <em>file-path</em></syntax> +<contextlist><context>server config</context> +<context>virtual host</context></contextlist> + +<usage> +<p> +This directive sets the optional <em>all-in-one</em> file where you can +assemble the certificates of Certification Authorities (CA) which form the +certificate chain of the server certificate. This starts with the issuing CA +certificate of of the server certificate and can range up to the root CA +certificate. Such a file is simply the concatenation of the various +PEM-encoded CA Certificate files, usually in certificate chain order.</p> +<p> +This should be used alternatively and/or additionally to <directive +module="mod_ssl">SSLCACertificatePath</directive> for explicitly +constructing the server certificate chain which is sent to the browser +in addition to the server certificate. It is especially useful to +avoid conflicts with CA certificates when using client +authentication. Because although placing a CA certificate of the +server certificate chain into <directive +module="mod_ssl">SSLCACertificatePath</directive> has the same effect +for the certificate chain construction, it has the side-effect that +client certificates issued by this same CA certificate are also +accepted on client authentication. That's usually not one expect.</p> +<p> +But be careful: Providing the certificate chain works only if you are using a +<em>single</em> (either RSA <em>or</em> DSA) based server certificate. If you are +using a coupled RSA+DSA certificate pair, this will work only if actually both +certificates use the <em>same</em> certificate chain. Else the browsers will be +confused in this situation.</p> +<example><title>Example</title> +SSLCertificateChainFile /usr/local/apache/conf/ssl.crt/ca.crt +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>SSLCACertificatePath</name> +<description>Directory of PEM-encoded CA Certificates for +Client Auth</description> +<syntax>SSLCACertificatePath <em>directory-path</em></syntax> +<contextlist><context>server config</context> +<context>virtual host</context></contextlist> + +<usage> +<p> +This directive sets the directory where you keep the Certificates of +Certification Authorities (CAs) whose clients you deal with. These are used to +verify the client certificate on Client Authentication.</p> +<p> +The files in this directory have to be PEM-encoded and are accessed through +hash filenames. So usually you can't just place the Certificate files +there: you also have to create symbolic links named +<em>hash-value</em><code>.N</code>. And you should always make sure this directory +contains the appropriate symbolic links. Use the <code>Makefile</code> which +comes with mod_ssl to accomplish this task.</p> +<example><title>Example</title> +SSLCACertificatePath /usr/local/apache/conf/ssl.crt/ +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>SSLCACertificateFile</name> +<description>File of concatenated PEM-encoded CA Certificates +for Client Auth</description> +<syntax>SSLCACertificateFile <em>file-path</em></syntax> +<contextlist><context>server config</context> +<context>virtual host</context></contextlist> + +<usage> +<p> +This directive sets the <em>all-in-one</em> file where you can assemble the +Certificates of Certification Authorities (CA) whose <em>clients</em> you deal +with. These are used for Client Authentication. Such a file is simply the +concatenation of the various PEM-encoded Certificate files, in order of +preference. This can be used alternatively and/or additionally to +<directive module="mod_ssl">SSLCACertificatePath</directive>.</p> +<example><title>Example</title> +SSLCACertificateFile /usr/local/apache/conf/ssl.crt/ca-bundle-client.crt +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>SSLCARevocationPath</name> +<description>Directory of PEM-encoded CA CRLs for +Client Auth</description> +<syntax>SSLCARevocationPath <em>directory-path</em></syntax> +<contextlist><context>server config</context> +<context>virtual host</context></contextlist> + +<usage> +<p> +This directive sets the directory where you keep the Certificate Revocation +Lists (CRL) of Certification Authorities (CAs) whose clients you deal with. +These are used to revoke the client certificate on Client Authentication.</p> +<p> +The files in this directory have to be PEM-encoded and are accessed through +hash filenames. So usually you have not only to place the CRL files there. +Additionally you have to create symbolic links named +<em>hash-value</em><code>.rN</code>. And you should always make sure this directory +contains the appropriate symbolic links. Use the <code>Makefile</code> which +comes with <module>mod_ssl</module> to accomplish this task.</p> +<example><title>Example</title> +SSLCARevocationPath /usr/local/apache/conf/ssl.crl/ +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>SSLCARevocationFile</name> +<description>File of concatenated PEM-encoded CA CRLs for +Client Auth</description> +<syntax>SSLCARevocationFile <em>file-path</em></syntax> +<contextlist><context>server config</context> +<context>virtual host</context></contextlist> + +<usage> +<p> +This directive sets the <em>all-in-one</em> file where you can +assemble the Certificate Revocation Lists (CRL) of Certification +Authorities (CA) whose <em>clients</em> you deal with. These are used +for Client Authentication. Such a file is simply the concatenation of +the various PEM-encoded CRL files, in order of preference. This can be +used alternatively and/or additionally to <directive +module="mod_ssl">SSLCARevocationPath</directive>.</p> +<example><title>Example</title> +SSLCARevocationFile /usr/local/apache/conf/ssl.crl/ca-bundle-client.crl +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>SSLVerifyClient</name> +<description>Type of Client Certificate verification</description> +<syntax>SSLVerifyClient <em>level</em></syntax> +<default>SSLVerifyClient none</default> +<contextlist><context>server config</context> +<context>virtual host</context> +<context>directory</context> +<context>.htaccess</context></contextlist> +<override>AuthConfig</override> + +<usage> +<p> +This directive sets the Certificate verification level for the Client +Authentication. Notice that this directive can be used both in per-server and +per-directory context. In per-server context it applies to the client +authentication process used in the standard SSL handshake when a connection is +established. In per-directory context it forces a SSL renegotation with the +reconfigured client verification level after the HTTP request was read but +before the HTTP response is sent.</p> +<p> +The following levels are available for <em>level</em>:</p> +<ul> +<li><strong>none</strong>: + no client Certificate is required at all</li> +<li><strong>optional</strong>: + the client <em>may</em> present a valid Certificate</li> +<li><strong>require</strong>: + the client <em>has to</em> present a valid Certificate</li> +<li><strong>optional_no_ca</strong>: + the client may present a valid Certificate<br /> + but it need not to be (successfully) verifiable.</li> +</ul> +<p>In practice only levels <strong>none</strong> and +<strong>require</strong> are really interesting, because level +<strong>optional</strong> doesn't work with all browsers and level +<strong>optional_no_ca</strong> is actually against the idea of +authentication (but can be used to establish SSL test pages, etc.)</p> +<example><title>Example</title> +SSLVerifyClient require +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>SSLVerifyDepth</name> +<description>Maximum depth of CA Certificates in Client +Certificate verification</description> +<syntax>SSLVerifyDepth <em>number</em></syntax> +<default>SSLVerifyDepth 1</default> +<contextlist><context>server config</context> +<context>virtual host</context> +<context>directory</context> +<context>.htaccess</context></contextlist> +<override>AuthConfig</override> + +<usage> +<p> +This directive sets how deeply mod_ssl should verify before deciding that the +clients don't have a valid certificate. Notice that this directive can be +used both in per-server and per-directory context. In per-server context it +applies to the client authentication process used in the standard SSL +handshake when a connection is established. In per-directory context it forces +a SSL renegotation with the reconfigured client verification depth after the +HTTP request was read but before the HTTP response is sent.</p> +<p> +The depth actually is the maximum number of intermediate certificate issuers, +i.e. the number of CA certificates which are max allowed to be followed while +verifying the client certificate. A depth of 0 means that self-signed client +certificates are accepted only, the default depth of 1 means the client +certificate can be self-signed or has to be signed by a CA which is directly +known to the server (i.e. the CA's certificate is under +<directive module="mod_ssl">SSLCACertificatePath</directive>), etc.</p> +<example><title>Example</title> +SSLVerifyDepth 10 +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>SSLLog</name> +<description>Where to write the dedicated SSL engine logfile</description> +<syntax>SSLLog <em>file-path</em></syntax> +<contextlist><context>server config</context> +<context>virtual host</context></contextlist> + +<usage> +<p> +This directive sets the name of the dedicated SSL protocol engine logfile. +Error type messages are additionally duplicated to the general Apache error +log file (directive <code>ErrorLog</code>). Put this somewhere where it cannot +be used for symlink attacks on a real server (i.e. somewhere where only root +can write). If the <em>file-path</em> does not begin with a slash +('<code>/</code>') then it is assumed to be relative to the <em>Server +Root</em>. If <em>file-path</em> begins with a bar ('<code>|</code>') then the +following string is assumed to be a path to an executable program to which a +reliable pipe can be established. The directive should occur only once per +virtual server config.</p> +<example><title>Example</title> +SSLLog /usr/local/apache/logs/ssl_engine_log +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>SSLLogLevel</name> +<description>Logging level for the dedicated SSL engine +logfile</description> +<syntax>SSLLogLevel <em>level</em></syntax> +<default>SSLLogLevel none</default> +<contextlist><context>server config</context> +<context>virtual host</context></contextlist> + +<usage> +<p> +This directive sets the verbosity degree of the dedicated SSL protocol engine +logfile. The <em>level</em> is one of the following (in ascending order where +higher levels include lower levels):</p> +<ul> +<li><code>none</code><br /> + no dedicated SSL logging is done, but messages of level + ``<code>error</code>'' are still written to the general Apache error + logfile. +</li> +<li><code>error</code><br /> + log messages of error type only, i.e. messages which show fatal situations + (processing is stopped). Those messages are also duplicated to the + general Apache error logfile. +</li> +<li><code>warn</code><br /> + log also warning messages, i.e. messages which show non-fatal problems + (processing is continued). +</li> +<li><code>info</code><br /> + log also informational messages, i.e. messages which show major + processing steps. +</li> +<li><code>trace</code><br /> + log also trace messages, i.e. messages which show minor processing steps. +</li> +<li><code>debug</code><br /> + log also debugging messages, i.e. messages which show development and + low-level I/O information. +</li> +</ul> +<example><title>Example</title> +SSLLogLevel warn +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>SSLOptions</name> +<description>Configure various SSL engine run-time options</description> +<syntax>SSLOptions [+|-]<em>option</em> ...</syntax> +<contextlist><context>server config</context> +<context>virtual host</context> +<context>directory</context> +<context>.htaccess</context></contextlist> +<override>Options</override> + +<usage> +<p> +This directive can be used to control various run-time options on a +per-directory basis. Normally, if multiple <code>SSLOptions</code> +could apply to a directory, then the most specific one is taken +completely; the options are not merged. However if <em>all</em> the +options on the <code>SSLOptions</code> directive are preceded by a +plus (<code>+</code>) or minus (<code>-</code>) symbol, the options +are merged. Any options preceded by a <code>+</code> are added to the +options currently in force, and any options preceded by a +<code>-</code> are removed from the options currently in force.</p> +<p> +The available <em>option</em>s are:</p> +<ul> +<li><code>StdEnvVars</code> + <p> + When this option is enabled, the standard set of SSL related CGI/SSI + environment variables are created. This per default is disabled for + performance reasons, because the information extraction step is a + rather expensive operation. So one usually enables this option for + CGI and SSI requests only.</p> +</li> +<li><code>CompatEnvVars</code> + <p> + When this option is enabled, additional CGI/SSI environment variables are + created for backward compatibility to other Apache SSL solutions. Look in + the <a href="../ssl/ssl_compat.html">Compatibility</a> chapter for details + on the particular variables generated.</p> +</li> +<li><code>ExportCertData</code> + <p> + When this option is enabled, additional CGI/SSI environment variables are + created: <code>SSL_SERVER_CERT</code>, <code>SSL_CLIENT_CERT</code> and + <code>SSL_CLIENT_CERT_CHAIN</code><em>n</em> (with <em>n</em> = 0,1,2,..). + These contain the PEM-encoded X.509 Certificates of server and client for + the current HTTPS connection and can be used by CGI scripts for deeper + Certificate checking. Additionally all other certificates of the client + certificate chain are provided, too. This bloats up the environment a + little bit which is why you have to use this option to enable it on + demand.</p> +</li> +<li><code>FakeBasicAuth</code> + <p> + When this option is enabled, the Subject Distinguished Name (DN) of the + Client X509 Certificate is translated into a HTTP Basic Authorization + username. This means that the standard Apache authentication methods can + be used for access control. The user name is just the Subject of the + Client's X509 Certificate (can be determined by running OpenSSL's + <code>openssl x509</code> command: <code>openssl x509 -noout -subject -in + </code><em>certificate</em><code>.crt</code>). Note that no password is + obtained from the user. Every entry in the user file needs this password: + ``<code>xxj31ZMTZzkVA</code>'', which is the DES-encrypted version of the + word `<code>password</code>''. Those who live under MD5-based encryption + (for instance under FreeBSD or BSD/OS, etc.) should use the following MD5 + hash of the same word: ``<code>$1$OXLyS...$Owx8s2/m9/gfkcRVXzgoE/</code>''.</p> +</li> +<li><code>StrictRequire</code> + <p> + This <em>forces</em> forbidden access when <code>SSLRequireSSL</code> or + <code>SSLRequire</code> successfully decided that access should be + forbidden. Usually the default is that in the case where a ``<code>Satisfy + any</code>'' directive is used, and other access restrictions are passed, + denial of access due to <code>SSLRequireSSL</code> or + <code>SSLRequire</code> is overridden (because that's how the Apache + <code>Satisfy</code> mechanism should work.) But for strict access restriction + you can use <code>SSLRequireSSL</code> and/or <code>SSLRequire</code> in + combination with an ``<code>SSLOptions +StrictRequire</code>''. Then an + additional ``<code>Satisfy Any</code>'' has no chance once mod_ssl has + decided to deny access.</p> +</li> +<li><code>OptRenegotiate</code> + <p> + This enables optimized SSL connection renegotiation handling when SSL + directives are used in per-directory context. By default a strict + scheme is enabled where <em>every</em> per-directory reconfiguration of + SSL parameters causes a <em>full</em> SSL renegotiation handshake. When this + option is used mod_ssl tries to avoid unnecessary handshakes by doing more + granular (but still safe) parameter checks. Nevertheless these granular + checks sometimes maybe not what the user expects, so enable this on a + per-directory basis only, please.</p> +</li> +</ul> +<example><title>Example</title> +SSLOptions +FakeBasicAuth -StrictRequire<br /> +<Files ~ "\.(cgi|shtml)$"><br /> + SSLOptions +StdEnvVars +CompatEnvVars -ExportCertData<br /> +<Files> +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>SSLRequireSSL</name> +<description>Deny access when SSL is not used for the +HTTP request</description> +<syntax>SSLRequireSSL</syntax> +<contextlist><context>directory</context> +<context>.htaccess</context></contextlist> +<override>AuthConfig</override> + +<usage> +<p><!-- XXX: I think the syntax is wrong --> +This directive forbids access unless HTTP over SSL (i.e. HTTPS) is enabled for +the current connection. This is very handy inside the SSL-enabled virtual +host or directories for defending against configuration errors that expose +stuff that should be protected. When this directive is present all requests +are denied which are not using SSL.</p> +<example><title>Example</title> +SSLRequireSSL +</example> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>SSLRequire</name> +<description>Allow access only when an arbitrarily complex +boolean expression is true</description> +<syntax>SSLRequire <em>expression</em></syntax> +<contextlist><context>directory</context> +<context>.htaccess</context></contextlist> +<override>AuthConfig</override> + +<usage> +<p> +This directive specifies a general access requirement which has to be +fulfilled in order to allow access. It's a very powerful directive because the +requirement specification is an arbitrarily complex boolean expression +containing any number of access checks.</p> +<p> +The <em>expression</em> must match the following syntax (given as a BNF +grammar notation):</p> +<blockquote> +<pre> +expr ::= "<strong>true</strong>" | "<strong>false</strong>" + | "<strong>!</strong>" expr + | expr "<strong>&&</strong>" expr + | expr "<strong>||</strong>" expr + | "<strong>(</strong>" expr "<strong>)</strong>" + | comp + +comp ::= word "<strong>==</strong>" word | word "<strong>eq</strong>" word + | word "<strong>!=</strong>" word | word "<strong>ne</strong>" word + | word "<strong><</strong>" word | word "<strong>lt</strong>" word + | word "<strong><=</strong>" word | word "<strong>le</strong>" word + | word "<strong>></strong>" word | word "<strong>gt</strong>" word + | word "<strong>>=</strong>" word | word "<strong>ge</strong>" word + | word "<strong>in</strong>" "<strong>{</strong>" wordlist "<strong>}</strong>" + | word "<strong>=~</strong>" regex + | word "<strong>!~</strong>" regex + +wordlist ::= word + | wordlist "<strong>,</strong>" word + +word ::= digit + | cstring + | variable + | function + +digit ::= [0-9]+ +cstring ::= "..." +variable ::= "<strong>%{</strong>" varname "<strong>}</strong>" +function ::= funcname "<strong>(</strong>" funcargs "<strong>)</strong>" +</pre> +</blockquote> +<p>while for <code>varname</code> any variable from <a +href="#table3">Table 3</a> can be used. Finally for +<code>funcname</code> the following functions are available:</p> +<ul> +<li><code>file(</code><em>filename</em><code>)</code> + <p> + This function takes one string argument and expands to the contents of the + file. This is especially useful for matching this contents against a + regular expression, etc.</p> +</li> +</ul> +<p>Notice that <em>expression</em> is first parsed into an internal machine +representation and then evaluated in a second step. Actually, in Global and +Per-Server Class context <em>expression</em> is parsed at startup time and +at runtime only the machine representation is executed. For Per-Directory +context this is different: here <em>expression</em> has to be parsed and +immediately executed for every request.</p> +<example><title>Example</title> +SSLRequire ( %{SSL_CIPHER} !~ m/^(EXP|NULL)-/ \<br /> + and %{SSL_CLIENT_S_DN_O} eq "Snake Oil, Ltd." \<br /> + and %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"} \<br /> + and %{TIME_WDAY} >= 1 and %{TIME_WDAY} <= 5 \<br /> + and %{TIME_HOUR} >= 8 and %{TIME_HOUR} <= 20 ) \<br /> + or %{REMOTE_ADDR} =~ m/^192\.76\.162\.[0-9]+$/ +</example> +<div align="center"> +<a name="table3"></a> +<table width="600" cellspacing="0" cellpadding="1" border="0" summary=""> +<caption align="bottom" id="sf">Table 3: Available Variables for SSLRequire</caption> +<tr><td bgcolor="#cccccc"> +<table width="598" cellpadding="5" cellspacing="0" border="0" summary=""> +<tr><td valign="top" align="center" bgcolor="#ffffff"> +<table summary=""><tr><td> +<em>Standard CGI/1.0 and Apache variables:</em> +<pre> +HTTP_USER_AGENT PATH_INFO AUTH_TYPE +HTTP_REFERER QUERY_STRING SERVER_SOFTWARE +HTTP_COOKIE REMOTE_HOST API_VERSION +HTTP_FORWARDED REMOTE_IDENT TIME_YEAR +HTTP_HOST IS_SUBREQ TIME_MON +HTTP_PROXY_CONNECTION DOCUMENT_ROOT TIME_DAY +HTTP_ACCEPT SERVER_ADMIN TIME_HOUR +HTTP:headername SERVER_NAME TIME_MIN +THE_REQUEST SERVER_PORT TIME_SEC +REQUEST_METHOD SERVER_PROTOCOL TIME_WDAY +REQUEST_SCHEME REMOTE_ADDR TIME +REQUEST_URI REMOTE_USER ENV:<strong>variablename</strong> +REQUEST_FILENAME +</pre> +<em>SSL-related variables:</em> +<pre> +HTTPS SSL_CLIENT_M_VERSION SSL_SERVER_M_VERSION + SSL_CLIENT_M_SERIAL SSL_SERVER_M_SERIAL +SSL_PROTOCOL SSL_CLIENT_V_START SSL_SERVER_V_START +SSL_SESSION_ID SSL_CLIENT_V_END SSL_SERVER_V_END +SSL_CIPHER SSL_CLIENT_S_DN SSL_SERVER_S_DN +SSL_CIPHER_EXPORT SSL_CLIENT_S_DN_C SSL_SERVER_S_DN_C +SSL_CIPHER_ALGKEYSIZE SSL_CLIENT_S_DN_ST SSL_SERVER_S_DN_ST +SSL_CIPHER_USEKEYSIZE SSL_CLIENT_S_DN_L SSL_SERVER_S_DN_L +SSL_VERSION_LIBRARY SSL_CLIENT_S_DN_O SSL_SERVER_S_DN_O +SSL_VERSION_INTERFACE SSL_CLIENT_S_DN_OU SSL_SERVER_S_DN_OU + SSL_CLIENT_S_DN_CN SSL_SERVER_S_DN_CN + SSL_CLIENT_S_DN_T SSL_SERVER_S_DN_T + SSL_CLIENT_S_DN_I SSL_SERVER_S_DN_I + SSL_CLIENT_S_DN_G SSL_SERVER_S_DN_G + SSL_CLIENT_S_DN_S SSL_SERVER_S_DN_S + SSL_CLIENT_S_DN_D SSL_SERVER_S_DN_D + SSL_CLIENT_S_DN_UID SSL_SERVER_S_DN_UID + SSL_CLIENT_S_DN_Email SSL_SERVER_S_DN_Email + SSL_CLIENT_I_DN SSL_SERVER_I_DN + SSL_CLIENT_I_DN_C SSL_SERVER_I_DN_C + SSL_CLIENT_I_DN_ST SSL_SERVER_I_DN_ST + SSL_CLIENT_I_DN_L SSL_SERVER_I_DN_L + SSL_CLIENT_I_DN_O SSL_SERVER_I_DN_O + SSL_CLIENT_I_DN_OU SSL_SERVER_I_DN_OU + SSL_CLIENT_I_DN_CN SSL_SERVER_I_DN_CN + SSL_CLIENT_I_DN_T SSL_SERVER_I_DN_T + SSL_CLIENT_I_DN_I SSL_SERVER_I_DN_I + SSL_CLIENT_I_DN_G SSL_SERVER_I_DN_G + SSL_CLIENT_I_DN_S SSL_SERVER_I_DN_S + SSL_CLIENT_I_DN_D SSL_SERVER_I_DN_D + SSL_CLIENT_I_DN_UID SSL_SERVER_I_DN_UID + SSL_CLIENT_I_DN_Email SSL_SERVER_I_DN_Email + SSL_CLIENT_A_SIG SSL_SERVER_A_SIG + SSL_CLIENT_A_KEY SSL_SERVER_A_KEY + SSL_CLIENT_CERT SSL_SERVER_CERT + SSL_CLIENT_CERT_CHAIN<strong>n</strong> + SSL_CLIENT_VERIFY +</pre> +</td></tr></table> +</td> +</tr></table> +</td></tr></table> +</div> +</usage> +</directivesynopsis> + +</modulesynopsis> diff --git a/docs/manual/mod/mod_status.xml b/docs/manual/mod/mod_status.xml new file mode 100644 index 0000000000..d3a351f12f --- /dev/null +++ b/docs/manual/mod/mod_status.xml @@ -0,0 +1,137 @@ +<?xml version="1.0"?> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>mod_status</name> +<status>Base</status> +<identifier>status_module</identifier> +<sourcefile>mod_status.c</sourcefile> +<compatibility>Available in Apache 1.1 and later</compatibility> + +<description>This module provides information on server activity and +performance.</description> + +<summary> + +<note> + <strong>Warning:</strong> This document has not been updated + to take into account changes made in the 2.0 version of the + Apache HTTP Server. Some of the information may still be + relevant, but please use it with care. +</note> + + <p>The Status module allows a server administrator to find out + how well their server is performing. A HTML page is presented + that gives the current server statistics in an easily readable + form. If required this page can be made to automatically + refresh (given a compatible browser). Another page gives a + simple machine-readable list of the current server state.</p> + + <p>The details given are:</p> + + <ul> + <li>The number of children serving requests</li> + + <li>The number of idle children</li> + + <li>The status of each child, the number of requests that + child has performed and the total number of bytes served by + the child (*)</li> + + <li>A total number of accesses and byte count served (*)</li> + + <li>The time the server was started/restarted and the time it + has been running for</li> + + <li>Averages giving the number of requests per second, the + number of bytes served per second and the average number of + bytes per request (*)</li> + + <li>The current percentage CPU used by each child and in + total by Apache (*)</li> + + <li>The current hosts and requests being processed (*)</li> + </ul> + + A compile-time option must be used to display the details + marked "(*)" as the instrumentation required for obtaining + these statistics does not exist within standard Apache. +</summary> + +<section> + <title>Enabling Status Support</title> + + To enable status reports only for browsers from the foo.com + domain add this code to your <code>httpd.conf</code> + configuration file +<example> + <Location /server-status><br /> + SetHandler server-status<br /> +<br /> + Order Deny,Allow<br /> + Deny from all<br /> + Allow from .foo.com<br /> + </Location> +</example> + + <p>You can now access server statistics by using a Web browser + to access the page + <code>http://your.server.name/server-status</code></p> + + <note><p>Note that <module>mod_status</module> will only work + when you are running Apache in <a + href="core.html#servertype">standalone</a> mode and not + <a href="core.html#servertype">inetd</a> mode.</p></note> +</section> + +<section> + + <title>Automatic Updates</title> + You can get the status page to update itself automatically if + you have a browser that supports "refresh". Access the page + <code>http://your.server.name/server-status?refresh=N</code> to + refresh the page every N seconds. + +</section> + +<section> + + <title>Machine Readable Status File</title> + A machine-readable version of the status file is available by + accessing the page + <code>http://your.server.name/server-status?auto</code>. This + is useful when automatically run, see the Perl program in the + <code>/support</code> directory of Apache, + <code>log_server_status</code>. + + <note> + <strong>It should be noted that if <module>mod_status</module> is + compiled into the server, its handler capability is available + in <em>all</em> configuration files, including + <em>per</em>-directory files (<em>e.g.</em>, + <code>.htaccess</code>). This may have security-related + ramifications for your site.</strong> + </note> + +</section> + +<directivesynopsis> + +<name>ExtendedStatus</name> +<description>This directive controls whether the server keeps track of +extended status information for each request. This is only +useful if the status module is enabled on the server.</description> +<syntax>ExtendedStatus On|Off</syntax> +<default>ExtendedStatus Off</default> +<contextlist><context>server config</context></contextlist> +<compatibility>ExtendedStatus is only available in Apache 1.3.2 and +later.</compatibility> + +<usage> + <p>This setting applies to the entire server, and cannot be + enabled or disabled on a virtualhost-by-virtualhost basis.</p> +</usage> + +</directivesynopsis> +</modulesynopsis> + diff --git a/docs/manual/mod/mod_suexec.xml b/docs/manual/mod/mod_suexec.xml new file mode 100644 index 0000000000..0d575e4913 --- /dev/null +++ b/docs/manual/mod/mod_suexec.xml @@ -0,0 +1,40 @@ +<?xml version="1.0"?> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>mod_suexec</name> +<status>Extension</status> +<identifier>suexec_module</identifier> +<sourcefile>mod_suexec.c</sourcefile> +<compatibility>Available in Apache 2.0 and later</compatibility> + +<description>This module allows CGI scripts to run as a specified user +and Group.</description> + +<summary> + <p>This module allows CGI scripts to run as a specified user + and Group.</p> +</summary> + + +<directivesynopsis> + +<name>SuexecUserGroup</name> +<syntax>SuexecUserGroup <em>User Group</em></syntax> +<default>None</default> +<contextlist><context>server config</context> +<context>virtual host</context></contextlist> +<compatibility>SuexecUserGroup is only available in 2.0 and +later.</compatibility> + +<usage> + <p>The <code>SuexecUserGroup</code> directive allows you to + specify a user and group for CGI programs to run as. Non-CGI + requests are still processes with the user specified in the + User directive. This directive replaces using the User and + Group directives inside of VirtualHosts.</p> +</usage> + +</directivesynopsis> +</modulesynopsis> + diff --git a/docs/manual/mod/mod_unique_id.xml b/docs/manual/mod/mod_unique_id.xml new file mode 100755 index 0000000000..6c4166c1d8 --- /dev/null +++ b/docs/manual/mod/mod_unique_id.xml @@ -0,0 +1,182 @@ +<?xml version="1.0"?> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>mod_unique_id</name> +<status>Extension</status> +<identifier>unique_id_module</identifier> +<sourcefile>mod_unique_id.c</sourcefile> +<compatibility>Available in Apache 1.3 and later.</compatibility> + +<description>This module provides an environment variable with a unique +identifier for each request.</description> + +<summary> + + <p>This module provides a magic token for each request which is + guaranteed to be unique across "all" requests under very + specific conditions. The unique identifier is even unique + across multiple machines in a properly configured cluster of + machines. The environment variable <code>UNIQUE_ID</code> is + set to the identifier for each request. Unique identifiers are + useful for various reasons which are beyond the scope of this + document.</p> +</summary> + +<section> + <title>Theory</title> + + <p>First a brief recap of how the Apache server works on Unix + machines. This feature currently isn't supported on Windows NT. + On Unix machines, Apache creates several children, the children + process requests one at a time. Each child can serve multiple + requests in its lifetime. For the purpose of this discussion, + the children don't share any data with each other. We'll refer + to the children as httpd processes.</p> + + <p>Your website has one or more machines under your + administrative control, together we'll call them a cluster of + machines. Each machine can possibly run multiple instances of + Apache. All of these collectively are considered "the + universe", and with certain assumptions we'll show that in this + universe we can generate unique identifiers for each request, + without extensive communication between machines in the + cluster.</p> + + <p>The machines in your cluster should satisfy these + requirements. (Even if you have only one machine you should + synchronize its clock with NTP.)</p> + + <ul> + <li>The machines' times are synchronized via NTP or other + network time protocol.</li> + + <li>The machines' hostnames all differ, such that the module + can do a hostname lookup on the hostname and receive a + different IP address for each machine in the cluster.</li> + </ul> + + <p>As far as operating system assumptions go, we assume that + pids (process ids) fit in 32-bits. If the operating system uses + more than 32-bits for a pid, the fix is trivial but must be + performed in the code.</p> + + <p>Given those assumptions, at a single point in time we can + identify any httpd process on any machine in the cluster from + all other httpd processes. The machine's IP address and the pid + of the httpd process are sufficient to do this. So in order to + generate unique identifiers for requests we need only + distinguish between different points in time.</p> + + <p>To distinguish time we will use a Unix timestamp (seconds + since January 1, 1970 UTC), and a 16-bit counter. The timestamp + has only one second granularity, so the counter is used to + represent up to 65536 values during a single second. The + quadruple <em>( ip_addr, pid, time_stamp, counter )</em> is + sufficient to enumerate 65536 requests per second per httpd + process. There are issues however with pid reuse over time, and + the counter is used to alleviate this issue.</p> + + <p>When an httpd child is created, the counter is initialized + with ( current microseconds divided by 10 ) modulo 65536 (this + formula was chosen to eliminate some variance problems with the + low order bits of the microsecond timers on some systems). When + a unique identifier is generated, the time stamp used is the + time the request arrived at the web server. The counter is + incremented every time an identifier is generated (and allowed + to roll over).</p> + + <p>The kernel generates a pid for each process as it forks the + process, and pids are allowed to roll over (they're 16-bits on + many Unixes, but newer systems have expanded to 32-bits). So + over time the same pid will be reused. However unless it is + reused within the same second, it does not destroy the + uniqueness of our quadruple. That is, we assume the system does + not spawn 65536 processes in a one second interval (it may even + be 32768 processes on some Unixes, but even this isn't likely + to happen).</p> + + <p>Suppose that time repeats itself for some reason. That is, + suppose that the system's clock is screwed up and it revisits a + past time (or it is too far forward, is reset correctly, and + then revisits the future time). In this case we can easily show + that we can get pid and time stamp reuse. The choice of + initializer for the counter is intended to help defeat this. + Note that we really want a random number to initialize the + counter, but there aren't any readily available numbers on most + systems (<em>i.e.</em>, you can't use rand() because you need + to seed the generator, and can't seed it with the time because + time, at least at one second resolution, has repeated itself). + This is not a perfect defense.</p> + + <p>How good a defense is it? Suppose that one of your machines + serves at most 500 requests per second (which is a very + reasonable upper bound at this writing, because systems + generally do more than just shovel out static files). To do + that it will require a number of children which depends on how + many concurrent clients you have. But we'll be pessimistic and + suppose that a single child is able to serve 500 requests per + second. There are 1000 possible starting counter values such + that two sequences of 500 requests overlap. So there is a 1.5% + chance that if time (at one second resolution) repeats itself + this child will repeat a counter value, and uniqueness will be + broken. This was a very pessimistic example, and with real + world values it's even less likely to occur. If your system is + such that it's still likely to occur, then perhaps you should + make the counter 32 bits (by editing the code).</p> + + <p>You may be concerned about the clock being "set back" during + summer daylight savings. However this isn't an issue because + the times used here are UTC, which "always" go forward. Note + that x86 based Unixes may need proper configuration for this to + be true -- they should be configured to assume that the + motherboard clock is on UTC and compensate appropriately. But + even still, if you're running NTP then your UTC time will be + correct very shortly after reboot.</p> + + <p>The <code>UNIQUE_ID</code> environment variable is + constructed by encoding the 112-bit (32-bit IP address, 32 bit + pid, 32 bit time stamp, 16 bit counter) quadruple using the + alphabet <code>[A-Za-z0-9@-]</code> in a manner similar to MIME + base64 encoding, producing 19 characters. The MIME base64 + alphabet is actually <code>[A-Za-z0-9+/]</code> however + <code>+</code> and <code>/</code> need to be specially encoded + in URLs, which makes them less desirable. All values are + encoded in network byte ordering so that the encoding is + comparable across architectures of different byte ordering. The + actual ordering of the encoding is: time stamp, IP address, + pid, counter. This ordering has a purpose, but it should be + emphasized that applications should not dissect the encoding. + Applications should treat the entire encoded + <code>UNIQUE_ID</code> as an opaque token, which can be + compared against other <code>UNIQUE_ID</code>s for equality + only.</p> + + <p>The ordering was chosen such that it's possible to change + the encoding in the future without worrying about collision + with an existing database of <code>UNIQUE_ID</code>s. The new + encodings should also keep the time stamp as the first element, + and can otherwise use the same alphabet and bit length. Since + the time stamps are essentially an increasing sequence, it's + sufficient to have a <em>flag second</em> in which all machines + in the cluster stop serving and request, and stop using the old + encoding format. Afterwards they can resume requests and begin + issuing the new encodings.</p> + + <p>This we believe is a relatively portable solution to this + problem. It can be extended to multithreaded systems like + Windows NT, and can grow with future needs. The identifiers + generated have essentially an infinite life-time because future + identifiers can be made longer as required. Essentially no + communication is required between machines in the cluster (only + NTP synchronization is required, which is low overhead), and no + communication between httpd processes is required (the + communication is implicit in the pid value assigned by the + kernel). In very specific situations the identifier can be + shortened, but more information needs to be assumed (for + example the 32-bit IP address is overkill for any site, but + there is no portable shorter replacement for it). </p> +</section> + + +</modulesynopsis> diff --git a/docs/manual/mod/mod_userdir.xml b/docs/manual/mod/mod_userdir.xml new file mode 100755 index 0000000000..65777a7e45 --- /dev/null +++ b/docs/manual/mod/mod_userdir.xml @@ -0,0 +1,107 @@ +<?xml version="1.0"?> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>mod_userdir</name> +<status>Base</status> +<description>This module provides for user-specific +directories.</description> +<identifier>userdir_module</identifier> +<sourcefile>mod_userdir.c</sourcefile> + +<summary> +</summary> + + +<directivesynopsis> + +<name>UserDir</name> +<description>Sets the directory from which to serve files when requests +for a particular user are received, denoted by requests containing +<em>~username</em>, such as +<em>http://server.example.com/~bob/</em></description> +<syntax>UserDir <em>directory-filename</em></syntax> +<default>UserDir <em>public_html</em></default> +<contextlist><context>server config</context> <context>virtual +host</context></contextlist> +<compatibility>All forms except the <code>UserDir public_html</code> +form are only available in Apache 1.1 or above. Use of the +<code>enabled</code> keyword, or <code>disabled</code> with a +list of usernames, is only available in Apache 1.3 and +above.</compatibility> + +<usage> + + <p>The UserDir directive sets the real directory in a user's + home directory to use when a request for a document for a user + is received. <em>Directory-filename</em> is one of the + following:</p> + + <ul> + <li>The name of a directory or a pattern such as those shown + below.</li> + + <li>The keyword <code>disabled</code>. This turns off + <em>all</em> username-to-directory translations except those + explicitly named with the <code>enabled</code> keyword (see + below).</li> + + <li>The keyword <code>disabled</code> followed by a + space-delimited list of usernames. Usernames that appear in + such a list will <em>never</em> have directory translation + performed, even if they appear in an <code>enabled</code> + clause.</li> + + <li>The keyword <code>enabled</code> followed by a + space-delimited list of usernames. These usernames will have + directory translation performed even if a global disable is + in effect, but not if they also appear in a + <code>disabled</code> clause.</li> + </ul> + + <p>If neither the <code>enabled</code> nor the + <code>disabled</code> keywords appear in the + <code>Userdir</code> directive, the argument is treated as a + filename pattern, and is used to turn the name into a directory + specification. A request for + <code>http://www.foo.com/~bob/one/two.html</code> will be + translated to:</p> + +<table> +<tr><th>UserDir directive used</th> +<th>Translated path</th></tr> +<tr><td>UserDir public_html</td><td>~bob/public_html/one/two.html</td></tr> +<tr><td>UserDir /usr/web</td><td>/usr/web/bob/one/two.html</td></tr> +<tr><td>UserDir /home/*/www</td><td>/home/bob/www/one/two.html</td></tr> +</table> + + <p>The following directives will send redirects to the client:</p> + +<table> +<tr><th>UserDir directive used</th> +<th>Translated path</th></tr> +<tr><td>UserDir http://www.foo.com/users</td><td>http://www.foo.com/users/bob/one/two.html</td></tr> +<tr><td>UserDir +http://www.foo.com/*/usr</td><td>http://www.foo.com/bob/usr/one/two.html</td></tr> +<tr><td>UserDir +http://www.foo.com/~*/</td><td>http://www.foo.com/~bob/one/two.html</td></tr> +</table> + + <blockquote> + <strong>Be careful when using this directive; for instance, + <code>"UserDir ./"</code> would map + <code>"/~root"</code> to <code>"/"</code> - which is probably + undesirable. If you are running Apache 1.3 or above, it is + strongly recommended that your configuration include a + "<code>UserDir disabled root</code>" declaration. + See also the <directive module="core">Directory</directive> + directive and the <a href="../misc/security_tips.html">Security + Tips</a> page for more information.</strong> + </blockquote> + +</usage> + +</directivesynopsis> +</modulesynopsis> + + diff --git a/docs/manual/mod/mod_usertrack.xml b/docs/manual/mod/mod_usertrack.xml new file mode 100755 index 0000000000..ab6c0e901a --- /dev/null +++ b/docs/manual/mod/mod_usertrack.xml @@ -0,0 +1,228 @@ +<?xml version="1.0"?> +<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd"> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> + +<modulesynopsis> +<name>mod_usertrack</name> +<description> + This module uses cookies to provide for a + <em>clickstream</em> log of user activity on a site. +</description> +<status>Extension</status> +<sourcefile>mod_usertrack.c</sourcefile> +<identifier>usertrack_module</identifier> +<compatibility>Known as mod_cookies prior to Apache 1.3.</compatibility> + +<summary> + + <h2>Summary</h2> + + <p>Previous releases of Apache have included a module which + generates a 'clickstream' log of user activity on a site using + cookies. This was called the "cookies" module, mod_cookies. In + Apache 1.2 and later this module has been renamed the "user + tracking" module, mod_usertrack. This module has been + simplified and new directives added.</p> +</summary> + + +<section> +<title>Logging</title> + + <p>Previously, the cookies module (now the user tracking + module) did its own logging, using the <tt>CookieLog</tt> + directive. In this release, this module does no logging at all. + Instead, a configurable log format file should be used to log + user click-streams. This is possible because the logging module + now allows multiple log files. The cookie itself is logged by + using the text <tt>%{cookie}n</tt> in the log file format. For + example:</p> +<example> +CustomLog logs/clickstream "%{cookie}n %r %t" +</example> + + <p>For backward compatibility the configurable log module + implements the old <tt>CookieLog</tt> directive, but this + should be upgraded to the above <tt>CustomLog</tt> directive. </p> +</section> + +<section> +<title>2-digit or 4-digit dates for cookies?</title> + + <p>(the following is from message + <022701bda43d$9d32bbb0$1201a8c0@christian.office.sane.com> + in the new-httpd archives) +<pre> +From: "Christian Allen" <christian@sane.com> +Subject: Re: Apache Y2K bug in mod_usertrack.c +Date: Tue, 30 Jun 1998 11:41:56 -0400 + +Did some work with cookies and dug up some info that might be useful. + +True, Netscape claims that the correct format NOW is four digit dates, and +four digit dates do in fact work... for Netscape 4.x (Communicator), that +is. However, 3.x and below do NOT accept them. It seems that Netscape +originally had a 2-digit standard, and then with all of the Y2K hype and +probably a few complaints, changed to a four digit date for Communicator. +Fortunately, 4.x also understands the 2-digit format, and so the best way to +ensure that your expiration date is legible to the client's browser is to +use 2-digit dates. + +However, this does not limit expiration dates to the year 2000; if you use +an expiration year of "13", for example, it is interpreted as 2013, NOT +1913! In fact, you can use an expiration year of up to "37", and it will be +understood as "2037" by both MSIE and Netscape versions 3.x and up (not sure +about versions previous to those). Not sure why Netscape used that +particular year as its cut-off point, but my guess is that it was in respect +to UNIX's 2038 problem. Netscape/MSIE 4.x seem to be able to understand +2-digit years beyond that, at least until "50" for sure (I think they +understand up until about "70", but not for sure). + +Summary: Mozilla 3.x and up understands two digit dates up until "37" +(2037). Mozilla 4.x understands up until at least "50" (2050) in 2-digit +form, but also understands 4-digit years, which can probably reach up until +9999. Your best bet for sending a long-life cookie is to send it for some +time late in the year "37". +</pre> +</p> +</section> + +<directivesynopsis> +<name>CookieDomain</name> +<syntax>CookieDomain <i>domain</i></syntax> +<default>None</default> +<contextlist> +<context>server config</context> +<context>virtual host</context> +<context>directory</context> +<context>.htaccess</context> +</contextlist> +<description>controls the setting of the domain to which + the tracking cookie applies.</description> + +<usage> + + <p>This directive controls the setting of the domain to which + the tracking cookie applies. If not present, no domain is + included in the cookie header field.</p> + + <p>The domain string <b>must</b> begin with a dot, and + <b>must</b> include at least one embedded dot. That is, + ".foo.com" is legal, but "foo.bar.com" and ".com" are not.</p> +</usage> +</directivesynopsis> + + +<directivesynopsis> +<name>CookieExpires</name> +<syntax>CookieExpires <em>expiry-period</em></syntax> +<default></default> +<contextlist> +<context>server config</context> +<context>virtual host</context> +<context>directory</context> +<context>.htaccess</context> +</contextlist> +<override></override> +<compatibility>In 1.3.20 and earlier, not usable in directory and +.htaccess</compatibility> + +<usage> + <p>When used, this directive sets an expiry time on the cookie + generated by the usertrack module. The <em>expiry-period</em> + can be given either as a number of seconds, or in the format + such as "2 weeks 3 days 7 hours". Valid denominations are: + years, months, weeks, hours, minutes and seconds. If the expiry + time is in any format other than one number indicating the + number of seconds, it must be enclosed by double quotes.</p> + + <p>If this directive is not used, cookies last only for the + current browser session.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>CookieName</name> +<syntax>CookieName <em>token</em></syntax> +<default>Apache</default> +<contextlist> +<context>server config</context> +<context>virtual host</context> +<context>directory</context> +<context>.htaccess</context> +</contextlist> + +<usage> + <p>This directive allows you to change the name of the cookie + this module uses for its tracking purposes. By default the + cookie is named "<code>Apache</code>".</p> + + <p>You must specify a valid cookie name; results are + unpredictable if you use a name containing unusual characters. + Valid characters include A-Z, a-z, 0-9, "_", and "-".</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>CookieStyle</name> +<syntax>CookieStyle + <i>Netscape|Cookie|Cookie2|RFC2109|RFC2965</i></syntax> +<default></default> +<contextlist> +<context>server config</context> +<context>virtual host</context> +<context>directory</context> +<context>.htaccess</context> +</contextlist> +<description>Controls the format of the cookie header + field</description> + +<usage> + <p>This directive controls the format of the cookie header + field. The three formats allowed are:</p> + + <ul> + <li><b>Netscape</b>, which is the original but now deprecated + syntax. This is the default, and the syntax Apache has + historically used.</li> + + <li><b>Cookie</b> or <b>RFC2109</b>, which is the syntax that + superseded the Netscape syntax.</li> + + <li><b>Cookie2</b> or <b>RFC2965</b>, which is the most + current cookie syntax.</li> + </ul> + + <p>Not all clients can understand all of these formats. but you + should use the newest one that is generally acceptable to your + users' browsers.</p> +</usage> +</directivesynopsis> + + + +<directivesynopsis> +<name>CookieTracking</name> +<syntax>CookieTracking on|off</syntax> +<default></default> +<contextlist> +<context>server config</context> +<context>virtual host</context> +<context>directory</context> +<context>.htaccess</context> +</contextlist> +<override>FileInfo</override> + +<usage> + <p>When the user track module is compiled in, and + "CookieTracking on" is set, Apache will start sending a + user-tracking cookie for all new requests. This directive can + be used to turn this behavior on or off on a per-server or + per-directory basis. By default, compiling mod_usertrack will + not activate cookies. </p> + +</usage> +</directivesynopsis> + +</modulesynopsis> + diff --git a/docs/manual/mod/mod_vhost_alias.xml b/docs/manual/mod/mod_vhost_alias.xml new file mode 100644 index 0000000000..d10d21cb39 --- /dev/null +++ b/docs/manual/mod/mod_vhost_alias.xml @@ -0,0 +1,287 @@ +<?xml version="1.0"?> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>mod_vhost_alias</name> +<status>Extension</status> +<identifier>vhost_alias_module</identifier> +<sourcefile>mod_vhost_alias.c</sourcefile> +<compatibility>Available in Apache 1.3.7 and later.</compatibility> + +<description>This module provides support for <a +href="../vhosts/mass.html">dynamically configured mass virtual +hosting</a>.</description> + +<summary> + + <p>This module creates dynamically configured virtual hosts, by + allowing the IP address and/or the <code>Host:</code> header of + the HTTP request to be used as part of the pathname to + determine what files to serve. This allows for easy use of a + huge number of virtual hosts with similar configurations.</p> + + <seealso>See also: <directive + module="core">UseCanonicalName</directive>.</seealso> + +</summary> + +<section> + <title>Directory Name Interpolation</title> + + <p>All the directives in this module interpolate a string into + a pathname. The interpolated string (henceforth called the + "name") may be either the server name (see the <a + href="core.html#usecanonicalname"><code>UseCanonicalName</code></a> + directive for details on how this is determined) or the IP + address of the virtual host on the server in dotted-quad + format. The interpolation is controlled by specifiers inspired + by <code>printf</code> which have a number of formats:</p> + +<table> + +<tr><td><code>%%</code></td> +<td>insert a <code>%</code></td></tr> + +<tr><td><code>%p</code></td> +<td>insert the port number of the virtual host</td></tr> + +<tr><td><code>%N.M</code></td> +<td>insert (part of) the name</td></tr> + +</table> + + <p><code>N</code> and <code>M</code> are used to specify + substrings of the name. <code>N</code> selects from the + dot-separated components of the name, and <code>M</code> + selects characters within whatever <code>N</code> has selected. + <code>M</code> is optional and defaults to zero if it isn't + present; the dot must be present if and only if <code>M</code> + is present. The interpretation is as follows:</p> + + <table> + <tr><td><code>0</code></td> + <td>the whole name</td></tr> + + <tr><td><code>1</code></td> + <td>the first part</td></tr> + + <tr><td><code>2</code></td> + <td>the second part</td></tr> + + <tr><td><code>-1</code></td> + <td>the last part</td></tr> + + <tr><td><code>-2</code></td> + <td>the penultimate part</td></tr> + + <tr><td><code>2+</code></td> + <td>the second and all subsequent parts</td></tr> + + <tr><td><code>-2+</code></td> + <td>the penultimate and all preceding parts</td></tr> + + <tr><td><code>1+</code> and <code>-1+</code></td> + <td>the same as <code>0</code></td></tr> + </table> + + <p>If <code>N</code> or <code>M</code> is greater than the number + of parts available a single underscore is interpolated. </p> + +</section> + +<section> + <title>Examples</title> + + <p>For simple name-based virtual hosts you might use the + following directives in your server configuration file:</p> + +<example> + UseCanonicalName Off<br /> + VirtualDocumentRoot /usr/local/apache/vhosts/%0 +</example> + + <p>A request for + <code>http://www.example.com/directory/file.html</code> will be + satisfied by the file + <code>/usr/local/apache/vhosts/www.example.com/directory/file.html</code>. + </p> + + <p>For a very large number of virtual hosts it is a good idea + to arrange the files to reduce the size of the + <code>vhosts</code> directory. To do this you might use the + following in your configuration file:</p> + +<example> + UseCanonicalName Off<br /> + VirtualDocumentRoot /usr/local/apache/vhosts/%3+/%2.1/%2.2/%2.3/%2 +</example> + + <p>A request for + <code>http://www.example.isp.com/directory/file.html</code> + will be satisfied by the file + <code>/usr/local/apache/vhosts/isp.com/e/x/a/example/directory/file.html</code>.</p> + + <p>A more even spread of files can be achieved by hashing from the + end of the name, for example: </p> + +<example> + VirtualDocumentRoot /usr/local/apache/vhosts/%3+/%2.-1/%2.-2/%2.-3/%2 +</example> + + <p>The example request would come from + <code>/usr/local/apache/vhosts/isp.com/e/l/p/example/directory/file.html</code>.</p> + + <p>Alternatively you might use: </p> + +<example> + VirtualDocumentRoot /usr/local/apache/vhosts/%3+/%2.1/%2.2/%2.3/%2.4+ +</example> + + <p>The example request would come from + <code>/usr/local/apache/vhosts/isp.com/e/x/a/mple/directory/file.html</code>.</p> + + <p>For IP-based virtual hosting you might use the following in + your configuration file:</p> + +<example> + UseCanonicalName DNS<br /> + VirtualDocumentRootIP /usr/local/apache/vhosts/%1/%2/%3/%4/docs<br /> + VirtualScriptAliasIP /usr/local/apache/vhosts/%1/%2/%3/%4/cgi-bin +</example> + + <p>A request for + <code>http://www.example.isp.com/directory/file.html</code> + would be satisfied by the file + <code>/usr/local/apache/vhosts/10/20/30/40/docs/directory/file.html</code> + if the IP address of <code>www.example.com</code> were + 10.20.30.40. A request for + <code>http://www.example.isp.com/cgi-bin/script.pl</code> would + be satisfied by executing the program + <code>/usr/local/apache/vhosts/10/20/30/40/cgi-bin/script.pl</code>.</p> + + <p>If you want to include the <code>.</code> character in a + <code>VirtualDocumentRoot</code> directive, but it clashes with + a <code>%</code> directive, you can work around the problem in + the following way:</p> + +<example> + VirtualDocumentRoot /usr/local/apache/vhosts/%2.0.%3.0 +</example> + + <p>A request for + <code>http://www.example.isp.com/directory/file.html</code> + will be satisfied by the file + <code>/usr/local/apache/vhosts/example.isp/directory/file.html</code>.</p> + + <p>The <directive module="mod_log_config">LogFormat</directive> + directives <code>%V</code> and <code>%A</code> are useful + in conjunction with this module.</p> +</section> + +<directivesynopsis> +<name>VirtualDocumentRoot</name> +<syntax>VirtualDocumentRoot <em>interpolated-directory</em></syntax> +<default>none</default> +<contextlist> +<context>server config</context> +<context>virtual host</context> +</contextlist> +<override></override> +<compatibility>VirtualDocumentRoot is only available in 1.3.7 and +later.</compatibility> +<description>Dynamically configure the location of the document root +for a given virtual host.</description> + +<usage> + + <p>The <code>VirtualDocumentRoot</code> directive allows you to + determine where Apache will find your documents based on the + value of the server name. The result of expanding + <em>interpolated-directory</em> is used as the root of the + document tree in a similar manner to the <directive + module="core">DocumentRoot</directive> directive's argument. + If <em>interpolated-directory</em> is <code>none</code> then + <code>VirtaulDocumentRoot</code> is turned off. This directive + cannot be used in the same context as + <directive>VirtualDocumentRootIP</directive>.</p> + +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>VirtualDocumentRootIP</name> +<syntax>VirtualDocumentRootIP <em>interpolated-directory</em></syntax> +<default>none</default> +<contextlist> +<context>server config</context> +<context>virtual host</context> +</contextlist> +<override></override> +<compatibility>VirtualDocumentRootIP is only available in 1.3.7 +and later.</compatibility> +<description>Dynamically configure the location of the document root +for a given virtual host</description> + +<usage> + +<p>The <code>VirtualDocumentRootIP</code> directive is like the + <directive>VirtualDocumentRoot</directive> + directive, except that it uses the IP address of the server end + of the connection instead of the server name.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>VirtualScriptAlias</name> +<syntax>VirtualScriptAlias <em>interpolated-directory</em></syntax> +<default>none</default> +<contextlist> +<context>server config</context> +<context>virtual host</context> +</contextlist> +<override></override> +<compatibility>VirtualScriptAlias is only available in 1.3.7 +and later.</compatibility> +<description>Dynamically configure the location of the CGI directory for +a given virtual host.</description> + +<usage> + + <p>The <code>VirtualScriptAlias</code> directive allows you to + determine where Apache will find CGI scripts in a similar + manner to <directive>VirtualDocumentRoot</directive> + does for other documents. It matches requests for URIs starting + <code>/cgi-bin/</code>, much like <directive + module="mod_alias">ScriptAlias</directive> + <code>/cgi-bin/</code> would.</p> + +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>VirtualScriptAliasIP</name> +<syntax>VirtualScriptAliasIP <em>interpolated-directory</em></syntax> +<default>none</default> +<contextlist> +<context>server config</context> +<context>virtual host</context> +</contextlist> +<override></override> +<compatibility>VirtualScriptAliasIP is only available in 1.3.7 +and later.</compatibility> +<description>Dynamically configure the location of the cgi directory for +a given virtual host.</description> + +<usage> + + <p>The <code>VirtualScriptAliasIP</code> directive is like the + <a + href="#virtualscriptalias"><code>VirtualScriptAlias</code></a> + directive, except that it uses the IP address of the server end + of the connection instead of the server name.</p> + + </usage> + +</directivesynopsis> +</modulesynopsis> + diff --git a/docs/manual/mod/mpm_common.xml b/docs/manual/mod/mpm_common.xml new file mode 100644 index 0000000000..3e3e4b7a5f --- /dev/null +++ b/docs/manual/mod/mpm_common.xml @@ -0,0 +1,613 @@ +<?xml version="1.0"?> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>mpm_common</name> +<description>A collection of directives that are implemented by +more than one multi-processing module (MPM)</description> +<status>MPM</status> + +<directivesynopsis> +<name>CoreDumpDirectory</name> +<description>Sets the directory where Apache attempts to +switch before dumping core</description> +<syntax>CoreDumpDirectory <em>directory</em></syntax> +<default>CoreDumpDirectory <em>ServerRoot</em></default> +<contextlist><context>server config</context></contextlist> +<modulelist><module>worker</module><module>perchild</module> +<module>prefork</module><module>mpm_winnt</module> +</modulelist> + +<usage> + + <p>This controls the directory to which Apache attempts to + switch before dumping core. The default is in the + <directive module="core">ServerRoot</directive> directory, however + since this should not be writable by the user the server runs + as, core dumps won't normally get written. If you want a core + dump for debugging, you can use this directive to place it in a + different location.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>Group</name> +<description>Sets the group under which the server will answer +requests</description> +<syntax>Group <em>unix-group</em></syntax> +<default>Group #-1</default> +<contextlist><context>server config</context><context>virtual host</context> +</contextlist> +<modulelist><module>worker</module><module>perchild</module> +<module>prefork</module></modulelist> + +<usage> + <p>The <directive>Group</directive> directive sets the group under + which the server will answer requests. In order to use this + directive, the stand-alone server must be run initially as root. + <em>Unix-group</em> is one of:</p> + + <dl> + <dt>A group name</dt> + + <dd>Refers to the given group by name.</dd> + + <dt># followed by a group number.</dt> + + <dd>Refers to a group by its number.</dd> + </dl> + <p>It is recommended that you set up a new group specifically for + running the server. Some admins use user <code>nobody</code>, + but this is not always possible or desirable.</p> + + <p>Note: if you start the server as a non-root user, it will + fail to change to the specified group, and will instead + continue to run as the group of the original user.</p> + + <p>Special note: Use of this directive in <VirtualHost< is + no longer supported. To implement the <a + href="../suexec.html">suEXEC wrapper</a> with Apache 2.0, use the + <directive module="mod_suexec">SuexecUserGroup</directive> + directive. SECURITY: See <directive + module="mpm_common">User</directive> for a discussion of the + security considerations.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>PidFile</name> +<description>Sets the file where the server records the process ID +of the daemon</description> +<syntax>PidFile <em>filename</em></syntax> +<default>PidFile logs/httpd.pid</default> +<contextlist><context>server config</context></contextlist> +<modulelist><module>worker</module><module>perchilde</module> +<module>prefork</module><module>mpm_winnt</module> +</modulelist> + +<usage> + <p>The <directive>PidFile</directive> directive sets the file to + which the server records the process id of the daemon. If the + filename does not begin with a slash (/) then it is assumed to be + relative to the <directive module="core">ServerRoot</directive>.</p> + + <p>It is often useful to be able to send the server a signal, + so that it closes and then reopens its <directive + module="core">ErrorLog</directive> and TransferLog, and + re-reads its configuration files. This is done by sending a + SIGHUP (kill -1) signal to the process id listed in the + PidFile.</p> + + <p>The PidFile is subject to the same warnings about log file + placement and <a + href="../misc/security_tips.html#serverroot">security</a>.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>Listen</name> +<description>Sets the IP addresses and ports that the server +listens to</description> +<syntax>Listen [<em>IP-address</em>:]<em>portnumber</em></syntax> +<contextlist><context>server config</context></contextlist> +<modulelist><module>worker</module><module>perchild</module> +<module>prefork</module><module>mpm_winnt</module> +</modulelist> + +<usage> + <p>The <directive>Listen</directive> directive instructs Apache to + listen to only specific IP addresses or ports; by default it + responds to requests on all IP interfaces. The Listen directive is + now a required directive. If it is not in the config file, the + server will fail to start. This is a change from previous versions + of Apache.</p> + + <p>The Listen directive tells the server to accept incoming + requests on the specified port or address-and-port combination. + If only a port number is specified, the server listens to the + given port on all interfaces. If an IP address is given as well + as a port, the server will listen on the given port and + interface.</p> + + <p>Multiple Listen directives may be used to specify a number + of addresses and ports to listen to. The server will respond to + requests from any of the listed addresses and ports.</p> + + <p>For example, to make the server accept connections on both + port 80 and port 8000, use:</p> +<example> + Listen 80<br /> + Listen 8000 +</example> + To make the server accept connections on two specified + interfaces and port numbers, use +<example> + Listen 192.170.2.1:80<br /> + Listen 192.170.2.5:8000 +</example> + IPv6 addresses must be surrounded in square brackets, as in the + following example: +<example> + Listen [fe80::a00:20ff:fea7:ccea]:80 +</example> +</usage> + +<seealso><a href="../dns-caveats.html">DNS Issues</a></seealso> +<seealso><a href="../bind.html">Setting + which addresses and ports Apache uses</a></seealso> +</directivesynopsis> + +<directivesynopsis> +<name>ListenBackLog</name> +<description>Maximum length of the queue of pending connections</description> +<syntax>ListenBacklog <em>backlog</em></syntax> +<default>ListenBacklog 511</default> +<contextlist><context>server config</context></contextlist> +<modulelist><module>worker</module><module>perchild</module> +<module>prefork</module><module>mpm_winnt</module> +</modulelist> + +<usage> + <p>The maximum length of the queue of pending connections. + Generally no tuning is needed or desired, however on some + systems it is desirable to increase this when under a TCP SYN + flood attack. See the backlog parameter to the + <code>listen(2)</code> system call.</p> + + <p>This will often be limited to a smaller number by the + operating system. This varies from OS to OS. Also note that + many OSes do not use exactly what is specified as the backlog, + but use a number based on (but normally larger than) what is + set.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>LockFile</name> +<description>Location of the accept serialization lock file</description> +<syntax>LockFile <em>filename</em></syntax> +<default>LockFile logs/accept.lock</default> +<contextlist><context>server config</context></contextlist> +<modulelist><module>worker</module><module>perchild</module> +<module>prefork</module></modulelist> + +<usage> + <p>The <directive>LockFile</directive> directive sets the path to + the lockfile used when Apache is compiled with either + USE_FCNTL_SERIALIZED_ACCEPT or USE_FLOCK_SERIALIZED_ACCEPT. This + directive should normally be left at its default value. The main + reason for changing it is if the <code>logs</code> directory is + NFS mounted, since <strong>the lockfile must be stored on a local + disk</strong>. The PID of the main server process is + automatically appended to the filename.</p> + + <p><strong>SECURITY:</strong> It is best to avoid putting this + file in a world writable directory such as + <code>/var/tmp</code> because someone could create a denial of + service attack and prevent the server from starting by creating + a lockfile with the same name as the one the server will try to + create.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>MaxClients</name> +<description>Maximum number of child processes that will be created +to serve requests</description> +<syntax>MaxClients <em>number</em></syntax> +<default>>MaxClients + 8 (with threads) MaxClients 256</default> +<contextlist><context>server config</context></contextlist> +<modulelist><module>worker</module><module>prefork</module> +</modulelist> + +<usage> + <p>The <directive>MaxClients</directive> directive sets the limit + on the number of child processes that will be created to serve + requests. When the server is built without threading, no more than + this number of clients can be served simultaneously. To configure + more than 256 clients with the prefork MPM, you must use the + <directive module="mpm_common">ServerLimit</directive> directive. + To configure more than 1024 clients with the worker MPM, you must + use the <directive module="mpm_common">ServerLimit</directive> and + <directive module="mpm_common">ThreadLimit</directive> directives.</p> + + <p>Any connection attempts over the + <directive>MaxClients</directive> limit will normally be queued, + up to a number based on the <directive module="mpm_common" + >ListenBacklog</directive> directive. Once a child + process is freed at the end of a different request, the connection + will then be serviced.</p> + + <p>When the server is compiled with threading, then the maximum + number of simultaneous requests that can be served is obtained + from the value of this directive multiplied by + <directive module="mpm_common">ThreadsPerChild</directive>.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>MaxRequestPerChild</name> +<description>Limit on the number of requests that an individual child server +will handle during its life</description> +<syntax>MaxRequestsPerChild <em>number</em></syntax> +<default>MaxRequestsPerChild 10000</default> +<contextlist><context>server config</context></contextlist> +<modulelist><module>worker</module><module>perchild</module> +<module>prefork</module><module>mpm_winnt</module> +</modulelist> + +<usage> + <p>The <directive>MaxRequestsPerChild</directive> directive sets + the limit on the number of requests that an individual child + server process will handle. After + <directive>MaxRequestsPerChild</directive> requests, the child + process will die. If <directive>MaxRequestsPerChild</directive> is + 0, then the process will never expire.</p> + + <p>Setting <directive>MaxRequestsPerChild</directive> to a + non-zero limit has two beneficial effects:</p> + + <ul> + <li>it limits the amount of memory that process can consume + by (accidental) memory leakage;</li> + + <li>by giving processes a finite lifetime, it helps reduce + the number of processes when the server load reduces.</li> + </ul> + + <p><strong>NOTE:</strong> For <em>KeepAlive</em> requests, only + the first request is counted towards this limit. In effect, it + changes the behavior to limit the number of + <em>connections</em> per child.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>MaxSpareThreads</name> +<description>Maximum number of idle threads</description> +<syntax>MaxSpareThreads <em>number</em></syntax> +<default>MaxSpareThreads 10 (Perchild) or 500 (worker)</default> +<contextlist><context>server config</context></contextlist> +<modulelist><module>worker</module><module>perchild</module> +</modulelist> + +<usage> + <p>Maximum number of idle threads. Different MPMs deal with this + directive differently. <module>perchild</module> monitors the + number of idle threads on a per-child basis. If there are too many + idle threads in that child, the server will begin to kill threads + within that child.</p> + + <p><module>worker</module> deals with idle threads on a + server-wide basis. If there are too many idle threads in the + server then child processes are killed until the number of idle + threads is less than this number.</p> + +</usage> +<seealso><directive module="mpm_common">MinSpareThreads</directive></seealso> +<seealso><directive module="mpm_common">StartServers</directive></seealso> +</directivesynopsis> + +<directivesynopsis> +<name>MaxThreadsPerChild</name> +<description>Maximum number of threads per child process</description> +<syntax>MaxThreadsPerChild <em>number</em></syntax> +<default>MaxThreadsPerChild 64</default> +<contextlist><context>server config</context></contextlist> +<modulelist><module>worker</module><module>perchild</module> +</modulelist> + +<usage> + <p>Maximum number of threads per child. For MPMs with a + variable number of threads per child, this directive sets the + maximum number of threads that will be created in each child + process. To increase this value beyond its default, it is + necessary to change the value of the compile-time define + <code>HARD_THREAD_LIMIT</code> and recompile the server.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>MinSpareThreads</name> +<description>Minimum number of idle threads available to handle request +spikes</description> +<syntax>MinSpareServers <em>number</em></syntax> +<default>MinSpareThreads 5 (Perchild) or 250 (worker)</default> +<contextlist><context>server config</context></contextlist> +<modulelist><module>worker</module><module>perchild</module> +</modulelist> + +<usage> + <p>Minimum number of idle threads to handle request spikes. + Different MPMs deal with this directive + differently. <module>perchild</module> monitors the number of idle + threads on a per-child basis. If there aren't enough idle threads + in that child, the server will begin to create new threads within + that child.</p> + + <p><module>worker</module> deals with idle threads on a + server-wide basis. If there aren't enough idle threads in the + server then child processes are created until the number of idle + threads is greater than number.</p> +</usage> +<seealso><directive module="mpm_common">MaxSpareThreads</directive></seealso> +<seealso><directive module="mpm_common">StartServers</directive></seealso> +</directivesynopsis> + +<directivesynopsis> +<name>NumServers</name> +<description>Total number of children alive at the same time</description> +<syntax>NumServers <em>number</em></syntax> +<default>NumServers 2</default> +<contextlist><context>server config</context></contextlist> +<modulelist><module>perchild</module></modulelist> + +<usage> + <p>Number of children alive at the same time. MPMs that use + this directive do not dynamically create new child processes so + this number should be large enough to handle the requests for + the entire site.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>ScoreBoardFile</name> +<description>Location of the file used to store coordination data for +the child processes</description> +<syntax>ScoreBoardFile <em>file-path</em></syntax> +<default>ScoreBoardFile logs/apache_status</default> +<contextlist><context>server config</context></contextlist> +<modulelist><module>worker</module><module>perchild</module> +<module>prefork</module></modulelist> + +<usage> + <p>The <directive>ScoreBoardFile</directive> directive is required + on some architectures to place a file that the server will use to + communicate between its children and the parent. The easiest way + to find out if your architecture requires a scoreboard file is to + run Apache and see if it creates the file named by the + directive. If your architecture requires it then you must ensure + that this file is not used at the same time by more than one + invocation of Apache.</p> + + <p>If you have to use a <directive>ScoreBoardFile</directive> then + you may see improved speed by placing it on a RAM disk. But be + careful that you heed the same warnings about log file placement + and <a href="../misc/security_tips.html">security</a>.</p> +</usage> +<seealso><a + href="../stopping.html">Stopping and Restarting Apache</a></seealso> +</directivesynopsis> + +<directivesynopsis> +<name>SendBufferSize</name> +<description>TCP buffer size</description> +<syntax>SendBufferSize <em>bytes</em></syntax> +<contextlist><context>server config</context></contextlist> +<modulelist><module>worker</module><module>perchild</module> +<module>prefork</module><module>mpm_winnt</module> +</modulelist> + +<usage> + <p>The server will set the TCP buffer size to the number of bytes + specified. Very useful to increase past standard OS defaults on + high speed high latency (<em>i.e.</em>, 100ms or so, such as + transcontinental fast pipes).</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>ServerLimit</name> +<description>Upper limit on configurable number of processes</description> +<syntax>ServerLimit <em>number</em></syntax> +<default>ServerLimit 256 (prefork), ServerLimit 16 (worker)</default> +<contextlist><context>server config</context></contextlist> +<modulelist><module>worker</module><module>prefork</module> +</modulelist> + +<usage> + <p>For the <module>prefork</module> MPM, this directive sets the + maximum configured value for <directive + module="mpm_common">MaxClients</directive> for the lifetime of the + Apache process. For the worker MPM, this directive in combination + with <directive module="mpm_common">ThreadLimit</directive> sets + the maximum configured value for <directive + module="mpm_common">MaxClients</directive> for the lifetime of the + Apache process. Any attempts to change this directive during a + restart will be ignored, but <directive + module="mpm_common">MaxClients</directive> can be modified during + a restart.</p> + + <p>Special care must be taken when using this directive. If + <directive>ServerLimit</directive> is set to a value much higher + than necessary, extra, unused shared memory will be allocated. If + both <directive>ServerLimit</directive> and <directive + module="mpm_common">MaxClients</directive> are set to values + higher than the system can handle, Apache may not start or the + system may become unstable.</p> + + <p>With the <module>prefork</module> MPM, use this directive only + if you need to set <directive + module="mpm_common">MaxClients</directive> higher higher than 256. + Do not set the value of this directive any higher than what you + might want to set <directive + module="mpm_common">MaxClients</directive> to.</p> + + <p>With the <module>worker</module> MPM, use this directive only + if your <directive module="mpm_common">MaxClients</directive> and + <directive module="mpm_common">ThreadsPerChild</directive> + settings require more than 16 server processes. Do not set the + value of this directive any higher than the number of server + processes required by what you may want for <directive + module="mpm_common">MaxClients </directive> and <directive + module="mpm_common">ThreadsPerChild</directive>.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>StartServers</name> +<description>Number of child server processes created at startup</description> +<syntax>StartServers <em>number</em></syntax> +<default>StartServers 5</default> +<contextlist><context>server config</context></contextlist> +<modulelist><module>worker</module></modulelist> + +<usage> + <p>The <directive>StartServers</directive> directive sets the + number of child server processes created on startup. As the number + of processes is dynamically controlled depending on the load, + there is usually little reason to adjust this parameter.</p> +</usage> +<seealso><directive module="mpm_common">MinSpareThreads</directive></seealso> +<seealso><directive module="mpm_common">MaxSpareThreads</directive></seealso> +</directivesynopsis> + +<directivesynopsis> +<name>StartThreads</name> +<description>Nubmer of threads each child creates on startup</description> +<syntax>StartThreads <em>number</em></syntax> +<default>StartThreads 5</default> +<contextlist><context>server config</context></contextlist> +<modulelist><module>perchild</module></modulelist> + +<usage> + <p>Number of threads each child creates on startup. As the + number of threads is dynamically controlled depending on the + load, there is usually little reason to adjust this + parameter.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>ThreadLimit</name> +<description>Sets the upper limit on the configurable number of threads +per child process</description> +<syntax>ThreadLimit <em>number</em></syntax> +<default>ThreadLimit 64</default> +<contextlist><context>server config</context></contextlist> +<modulelist><module>worker</module></modulelist> + +<usage> + <p>This directive sets the maximum configured value for <directive + module="mpm_common">ThreadsPerChild</directive> for the lifetime + of the Apache process. Any attempts to change this directive + during a restart will be ignored, but <directive + module="mpm_common">ThreadsPerChild</directive> can be modified + during a restart up to the value of this directive.</p> + + <p>Special care must be taken when using this directive. If + <directive>ThreadLimit</directive> is set to a value much higher + than <directive module="mpm_common">ThreadsPerChild</directive>, + extra unused shared memory will be allocated. If both + <directive>ThreadLimit</directive> and <directive + module="mpm_common">ThreadsPerChild</directive> are set to values + higher than the system can handle, Apache may not start or the + system may become unstable.</p> + + <p>Use this directive only if you need to set <directive + module="mpm_common">ThreadsPerChild</directive> higher than 64. Do + not set the value of this directive any higher than what you might + want to set <directive + module="mpm_common">ThreadsPerChild</directive> to.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>ThreadsPerChild</name> +<description>Number of threads created by each child process</description> +<syntax>ThreadsPerChild <em>number</em></syntax> +<default>ThreadsPerChild 50</default> +<contextlist><context>server config</context></contextlist> +<modulelist><module>worker</module><module>mpm_winnt</module> +</modulelist> + +<usage> + <p>This directive sets the number of threads created by each + child process. The child creates these threads at startup and + never creates more. if using an MPM like mpmt_winnt, where + there is only one child process, this number should be high + enough to handle the entire load of the server. If using an MPM + like worker, where there are multiple child processes, the + total number of threads should be high enough to handle the + common load on the server.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>User</name> +<description>The userid under which the server will answer +requests</description> +<syntax>User <em>unix-userid</em></syntax> +<default>User #-1</default> +<contextlist><context>server config</context><context>virtual host</context> +</contextlist> +<modulelist><module>worker</module><module>perchild</module> +<module>prefork</module></modulelist> + +<usage> + <p>The <directive>User</directive> directive sets the userid as + which the server will answer requests. In order to use this + directive, the standalone server must be run initially as + root. <em>Unix-userid</em> is one of:</p> + + <dl> + <dt>A username</dt> + + <dd>Refers to the given user by name.</dd> + + <dt># followed by a user number.</dt> + + <dd>Refers to a user by their number.</dd> + </dl> + + <p>The user should have no privileges which result in it being + able to access files which are not intended to be visible to the + outside world, and similarly, the user should not be able to + execute code which is not meant for httpd requests. It is + recommended that you set up a new user and group specifically for + running the server. Some admins use user <code>nobody</code>, but + this is not always possible or desirable. For example + <module>mod_proxy</module>'s cache, when enabled, must be + accessible to this user (see <directive + module="mod_proxy">CacheRoot</directive>).</p> + + <p>Notes: If you start the server as a non-root user, it will + fail to change to the lesser privileged user, and will instead + continue to run as that original user. If you do start the + server as root, then it is normal for the parent process to + remain running as root.</p> + + <p>Special note: Use of this directive in <directive module="core" + type="section">VirtualHost</directive> is no longer supported. To + configure your server for <a href="mod_suexec.html">suexec</a> use + <directive module="mod_suexec">SuexecUserGroup</directive>.</p> + +<note><title>Security</title> <p>Don't set <directive>User</directive> +(or <directive module="mpm_common">Group</directive>) to +<code>root</code> unless you know exactly what you are doing, and what +the dangers are.</p></note> +</usage> +</directivesynopsis> + +</modulesynopsis>
\ No newline at end of file diff --git a/docs/manual/mod/mpm_netware.html b/docs/manual/mod/mpm_netware.html new file mode 100644 index 0000000000..38aef83485 --- /dev/null +++ b/docs/manual/mod/mpm_netware.html @@ -0,0 +1,199 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="Microsoft FrontPage 4.0" /> + + <title>Apache MPM prefork</title> + </head> + <!-- Background white, links blue (unvisited), navy (visited), red (active) --> + + <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" + vlink="#000080" alink="#FF0000"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Multi-Processing Module NetWare</h1> + + <p>This Multi-Processing Module implements an exclusively threaded web + server optimized for Novell NetWare.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> MPM<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> mpm_netware.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + mpm_netware_module</p> + + <h2>Summary</h2> + + <p>This Multi-Processing Module (MPM) implements an exclusively threaded web server + that has been optimized for Novell NetWare.</p> + + <p>The main thread is responsible for launching child + worker threads which listen for connections and serve them when they + arrive. Apache always tries to maintain several <em>spare</em> + or idle worker threads, which stand ready to serve incoming + requests. In this way, clients do not need to wait for a new + child threads to be spawned before their requests can be + served.</p> + + <p>The <code>StartThreads</code>, <code>MinSpareThreads</code>, + <code>MaxSpareThreads</code>, and <code>MaxThreads</code> + regulate how the main thread creates worker threads to serve + requests. In general, Apache is very self-regulating, so most + sites do not need to adjust these directives from their default + values. Sites which need to serve more than 250 simultaneous + requests may need to increase <code>MaxThreads</code>, while + sites with limited memory may need to decrease + <code>MaxThreads</code> to keep the server from thrashing (spawning and + terminating idle threads). More information about + tuning process creation is provided in the <a + href="../misc/perf-tuning.html">performance hints</a> + documentation.</p> + + <p><code>MaxRequestsPerChild</code> controls how frequently the + server recycles processes by killing old ones and launching new + ones. On the NetWare OS it is highly recommended that this directive + remain set to 0. This allows worker threads to continue servicing + requests indefinitely.</p> + + <p>See also: <a href="../bind.html">Setting which addresses and + ports Apache uses</a>.</p> + + <h2>Directives</h2> + + <ul> + + <li><a href="mpm_common.html#listen">Listen</a></li> + + <li><a href="mpm_common.html#listenbacklog">ListenBacklog</a></li> + + <li><a href="#maxthreads">MaxThreads</a></li> + + <li><a href="mpm_common.html#maxrequestsperchild">MaxRequestsPerChild</a></li> + + <li><a href="#maxsparethreads">MaxSpareThreads</a></li> + + <li><a href="#minsparethreads">MinSpareThreads</a></li> + + <li><a href="mpm_common.html#sendbuffersize">SendBufferSize</a></li> + + <li><a href="#startthreads">StartThreads</a></li> + + <li><a href="#threadstacksize">ThreadStackSize</a></li> + + </ul> + <hr /> + + <h2><a id="maxthreads" + name="maxthreads">MaxThreads directive</a></h2> + <!--%plaintext <?INDEX {\tt MaxThreads} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> MaxThreads + <em>number</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <code>MaxThreads 250</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> core<p>The MaxThreads directive sets the desired maximum + number worker threads allowable.</p> + + <p>See also <a href="#minsparethreads">MinSpareThreads</a>, <a href="#maxsparethreads">MaxSpareThreads</a> and + <a href="#startthreads">StartThreads</a>.</p> + <hr /> + + <h2><a id="maxsparethreads" + name="maxspareservers">MaxSpareThreads directive</a></h2> + <!--%plaintext <?INDEX {\tt MaxSpareServers} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> MaxSpareThreads + <em>number</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <code>MaxSpareThreads 100</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> core + + <p>The MaxSpareThreads directive sets the desired maximum + number of <em>idle</em> worker threads. An idle worker thread + is one which is not handling a request. If there are more than + MaxSpareThreads idle, then the main thread will kill off the + excess worker threads.</p> + + <p>Tuning of this parameter should only be necessary on very + busy sites. Setting this parameter to a large number is almost + always a bad idea.</p> + + <p>See also <a href="#minsparethreads">MinSpareThreads</a>, <a href="#maxthreads">MaxThreads</a> and + <a href="#startthreads">StartThreads</a>.</p> + <hr /> + + <h2><a id="minsparethreads" + name="minspareservers">MinSpareThreads directive</a></h2> + <!--%plaintext <?INDEX {\tt MinSpareServers} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> MinSpareThreads + <em>number</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <code>MinSpareThreads 10</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> core<p>The MinSpareThreads directive sets the desired minimum + number of <em>idle</em> worker threads. An idle worker thread + is one which is not handling a request. If there are fewer than MinSpareThreads idle, then the + main thread spawns new worker.</p> + + <p>Tuning of this parameter should only be necessary on very + busy sites. Setting this parameter to a large number is almost + always a bad idea.</p> + + <p>See also <a href="#maxsparethreads">MaxSpareThreads</a>, <a href="#maxthreads">MaxThreads</a> and + <a href="#startthreads">StartThreads</a>. + <hr /> + + <h2><a id="startthreads" + name="startthreads">StartThreads directive</a></h2> + <!--%plaintext <?INDEX {\tt StartThreads} directive> --> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> StartThreads + <em>number</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <code>StartThreads + 50</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> core<p>The StartThreads directive sets the desired + number of worker threads to spawn and startup. </p> + + <p>See also <a href="#maxsparethreads">MaxSpareThreads</a>, <a href="#minsparethreads">MinSpareThreads</a> + and <a href="#maxthreads">MaxThreads</a>. + <hr /> + + <h2><a id="threadstacksize" + name="threadstacksize">ThreadStackSize</a></h2> + <a href="directive-dict.html#Syntax" + rel="Help"><strong>Syntax:</strong></a> ThreadStackSize + <em>number</em><br /> + <a href="directive-dict.html#Default" + rel="Help"><strong>Default:</strong></a> <code>ThreadStackSize + 65536</code><br /> + <a href="directive-dict.html#Context" + rel="Help"><strong>Context:</strong></a> server config<br /> + <a href="directive-dict.html#Status" + rel="Help"><strong>Status:</strong></a> core + <p>This directive tells the server what stack size to use for + each of the running threads. If you ever get a stack overflow + you will need to bump this number to a higher setting.</p> + + <hr /> + + <!--#include virtual="footer.html" --> + </body> +</html> + diff --git a/docs/manual/mod/mpm_netware.xml b/docs/manual/mod/mpm_netware.xml new file mode 100644 index 0000000000..e10f259409 --- /dev/null +++ b/docs/manual/mod/mpm_netware.xml @@ -0,0 +1,131 @@ +<?xml version="1.0"?> +<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd"> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> +<name>mpm_netware</name> +<description>Multi-Processing Module implementing an exclusively threaded web + server optimized for Novell NetWare</description> +<status>MPM</status> +<sourcefile>mpm_netware.c</sourcefile> +<identifier>mpm_netware_module</identifier> + +<summary> + <p>This Multi-Processing Module (MPM) implements an exclusively threaded web server + that has been optimized for Novell NetWare.</p> + + <p>The main thread is responsible for launching child + worker threads which listen for connections and serve them when they + arrive. Apache always tries to maintain several <em>spare</em> + or idle worker threads, which stand ready to serve incoming + requests. In this way, clients do not need to wait for a new + child threads to be spawned before their requests can be + served.</p> + + <p>The <code>StartThreads</code>, <code>MinSpareThreads</code>, + <code>MaxSpareThreads</code>, and <code>MaxThreads</code> + regulate how the main thread creates worker threads to serve + requests. In general, Apache is very self-regulating, so most + sites do not need to adjust these directives from their default + values. Sites which need to serve more than 250 simultaneous + requests may need to increase <code>MaxThreads</code>, while + sites with limited memory may need to decrease + <code>MaxThreads</code> to keep the server from thrashing (spawning and + terminating idle threads). More information about + tuning process creation is provided in the <a + href="../misc/perf-tuning.html">performance hints</a> + documentation.</p> + + <p><code>MaxRequestsPerChild</code> controls how frequently the + server recycles processes by killing old ones and launching new + ones. On the NetWare OS it is highly recommended that this directive + remain set to 0. This allows worker threads to continue servicing + requests indefinitely.</p> + + <p>See also: <a href="../bind.html">Setting which addresses and + ports Apache uses</a>.</p> +</summary> + +<directivesynopsis location="mpm_common"><name>Listen</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"><name>ListenBacklog</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"><name>MaxRequestsPerChild</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"><name>SendBufferSize</name> +</directivesynopsis> + +<directivesynopsis> +<name>MaxThreads</name> +<syntax>MaxThreads <em>number</em></syntax> +<default>MaxThreads 250</default> +<contextlist><context>server config</context></contextlist> + +<usage> +<p>The MaxThreads directive sets the desired maximum + number worker threads allowable.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>MaxSpareThreads</name> +<syntax>MaxSpareThreads <em>number</em></syntax> +<default>MaxSpareThreads 100</default> +<contextlist><context>server config</context></contextlist> + +<usage> + <p>The <directive>MaxSpareThreads</directive> directive sets the + desired maximum number of <em>idle</em> worker threads. An idle + worker thread is one which is not handling a request. If there are + more than MaxSpareThreads idle, then the main thread will kill off + the excess worker threads.</p> + + <p>Tuning of this parameter should only be necessary on very + busy sites. Setting this parameter to a large number is almost + always a bad idea.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>MinSpareThreads</name> +<syntax>MinSpareThreads <em>number</em></syntax> +<default>MinSpareThreads 10</default> +<contextlist><context>server config</context></contextlist> + +<usage> +<p>The <directive>MinSpareThreads</directive> directive sets the +desired minimum number of <em>idle</em> worker threads. An idle worker +thread is one which is not handling a request. If there are fewer than +MinSpareThreads idle, then the main thread spawns new worker.</p> + + <p>Tuning of this parameter should only be necessary on very + busy sites. Setting this parameter to a large number is almost + always a bad idea.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>StartThreads</name> +<syntax>StartThreads <em>number</em></syntax> +<default>StartThreads 50</default> +<contextlist><context>server config</context></contextlist> + +<usage> +<p>The StartThreads directive sets the desired + number of worker threads to spawn and startup</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>ThreadStackSize</name> +<syntax>ThreadStackSize <em>number</em></syntax> +<default>ThreadStackSize 65536</default> +<contextlist><context>server config</context></contextlist> + +<usage> + <p>This directive tells the server what stack size to use for + each of the running threads. If you ever get a stack overflow + you will need to bump this number to a higher setting.</p> +</usage> +</directivesynopsis> + +</modulesynopsis>
\ No newline at end of file diff --git a/docs/manual/mod/mpm_winnt.xml b/docs/manual/mod/mpm_winnt.xml new file mode 100644 index 0000000000..ca51b38063 --- /dev/null +++ b/docs/manual/mod/mpm_winnt.xml @@ -0,0 +1,34 @@ +<?xml version="1.0"?> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>mpm_winnt</name> +<description>This Multi-Processing Module is optimized for Windows + NT.</description> +<status>MPM</status> +<sourcefile>mpm_winnt.c</sourcefile> +<identifier>mpm_winnt_module</identifier> + +<summary> + <p>This Multi-Processing Module (MPM) is the default for the + Windows NT operating systems. It uses a single control process + which launches a single child process which in turn creates + threads to handle requests</p> +</summary> + +<directivesynopsis location="mpm_common"><name>CoreDumpDirectory</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"><name>PidFile</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"><name>Listen</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"><name>ListenBacklog</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"><name>MaxRequestsPerChild</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"><name>SendBufferSize</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"><name>ThreadsPerChild</name> +</directivesynopsis> + +</modulesynopsis>
\ No newline at end of file diff --git a/docs/manual/mod/perchild.xml b/docs/manual/mod/perchild.xml new file mode 100644 index 0000000000..62a9245f9a --- /dev/null +++ b/docs/manual/mod/perchild.xml @@ -0,0 +1,150 @@ +<?xml version="1.0"?> +<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd"> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> + +<name>perchild</name> +<description>Multi-Processing Module allowing for daemon processes + serving requests to be assigned a variety of different + userids</description> +<status>MPM</status> +<sourcefile>perchild.c</sourcefile> +<identifier>mpm_perchild_module</identifier> + +<summary> +<note type="warning"> +This MPM does not currently work on most platforms. Work is ongoing to +make it functional. +</note> + + <p>This Multi-Processing Module (MPM) implements a hybrid + multi-process, multi-threaded web server. A fixed number of + processes create threads to handle requests. Fluctuations in + load are handled by increasing or decreasing the number of + threads in each process.</p> + + <p>A single control process launches the number of child processes + indicated by the <directive + module="mpm_common">NumServers</directive> directive at server + startup. Each child process creates threads as specified in the + <code>StartThreads</code> directive. The individual threads then + listen for connections and serve them when they arrive.</p> + + <p>Apache always tries to maintain a pool of <em>spare</em> or + idle server threads, which stand ready to serve incoming + requests. In this way, clients do not need to wait for new + threads to be created. For each child process, Apache assesses + the number of idle threads and creates or destroys threads to + keep this number within the boundaries specified by + <code>MinSpareThreads</code> and <code>MaxSpareThreads</code>. + Since this process is very self-regulating, it is rarely + necessary to modify these directives from their default values. + The maximum number of clients that may be served simultaneously + is determined by multiplying the number of server processes + that will be created (<code>NumServers</code>) by the maximum + number of threads created in each process + (<code>MaxThreadsPerChild</code>).</p> + + <p>While the parent process is usually started as root under + Unix in order to bind to port 80, the child processes and + threads are launched by Apache as a less-privileged user. The + <code>User</code> and <code>Group</code> directives are used to + set the privileges of the Apache child processes. The child + processes must be able to read all the content that will be + served, but should have as few privileges beyond that as + possible. In addition, unless <a + href="../suexec.html">suexec</a> is used, these directives also + set the privileges which will be inherited by CGI scripts.</p> + + <p><code>MaxRequestsPerChild</code> controls how frequently the + server recycles processes by killing old ones and launching new + ones.</p> + + <p>See also: <a href="../bind.html">Setting which addresses and + ports Apache uses</a>.</p> + + <p>In addition it adds the extra ability to specify that + specific processes should serve requests under different + userids. These processes can then be associated with specific + virtual hosts.</p> + <!-- XXX: This desperately needs more explanation. --> +</summary> + +<directivesynopsis location="mpm_common"> +<name>CoreDumpDirectory</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"> +<name>Group</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"> +<name>PidFile</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"> +<name>Listen</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"> +<name>ListenBacklog</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"> +<name>LockFile</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"> +<name>MaxRequestsPerChild</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"> +<name>MaxSpareThreads</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"> +<name>MaxThreadsPerChild</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"> +<name>MinSpareThreads</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"> +<name>NumServers</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"> +<name>ScoreBoardFile</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"> +<name>SendBufferSize</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"> +<name>StartThreads</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"> +<name>User</name> +</directivesynopsis> + +<directivesynopsis> +<name>AssignUserId</name> +<syntax>AssignUserID <em>user_id</em> <em>group_id</em></syntax> +<contextlist><context>virtual host</context></contextlist> + +<usage> + <p>Tie a virtual host to a specific child process. Requests addressed to +the virtual host where this directive appears will be served by the process +running with the specified user and group id.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>ChildPerUserId</name> +<syntax>ChildPerUserID <em>user_id</em> +<em>group_id</em> <em>child_id</em></syntax> +<contextlist><context>server config</context></contextlist> + +<usage> + <p>Specify a user id and group id for a specific child process. The number of +children if set by the <a href="mpm_common.html#numservers">NumServers</a> +directive. For example, the default value for <a +href="mpm_common.html#numservers">NumServers</a> is 5 and that means +children ids 1,2,3,4 and 5 are available for assigment. If a child does not +have an associated ChildPerUserID, it inherits the <a +href="mpm_common.html#user">User</a> and <a +href="mpm_common.html#group">Group</a> settings from the main server </p> +</usage> +</directivesynopsis> + +</modulesynopsis> + diff --git a/docs/manual/mod/prefork.xml b/docs/manual/mod/prefork.xml new file mode 100644 index 0000000000..1dd788813b --- /dev/null +++ b/docs/manual/mod/prefork.xml @@ -0,0 +1,207 @@ +<?xml version="1.0"?> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> +<name>prefork</name> +<description>Implements a non-threaded, pre-forking web server</description> +<status>MPM</status> +<sourcefile>prefork.c</sourcefile> +<identifier>mpm_prefork_module</identifier> + +<summary> + <p>This Multi-Processing Module (MPM) implements a + non-threaded, pre-forking web server which handles request in a + manner very similar to the default behavior of Apache 1.3 on + Unix.</p> + + <p>A single control process is responsible for launching child + processes which listen for connections and serve them when they + arrive. Apache always tries to maintain several <em>spare</em> + or idle server processes, which stand ready to serve incoming + requests. In this way, clients do not need to wait for a new + child processes to be forked before their requests can be + served.</p> + + <p>The <directive module="mpm_common">StartServers</directive>, + <directive module="prefork">MinSpareServers</directive>, + <directive module="prefork">MaxSpareServers</directive>, and + <directive module="mpm_common">MaxClients</directive> regulate how + the parent process creates children to serve requests. In general, + Apache is very self-regulating, so most sites do not need to + adjust these directives from their default values. Sites which + need to serve more than 256 simultaneous requests may need to + increase <directive module="mpm_common">MaxClients</directive>, + while sites with limited memory may need to decrease <directive + module="mpm_common">MaxClients</directive> to keep the server from + thrashing (swapping memory to disk and back). More information + about tuning process creation is provided in the <a + href="../misc/perf-tuning.html">performance hints</a> + documentation.</p> + + <p>While the parent process is usually started as root under Unix + in order to bind to port 80, the child processes are launched by + Apache as a less-privileged user. The <directive + module="mpm_common">User</directive> and <directive + module="mpm_common">Group</directive> directives are used to set + the privileges of the Apache child processes. The child processes + must be able to read all the content that will be served, but + should have as few privileges beyond that as possible. In + addition, unless <a href="../suexec.html">suexec</a> is used, + these directives also set the privileges which will be inherited + by CGI scripts.</p> + + <p><directive module="mpm_common">MaxRequestsPerChild</directive> + controls how frequently the server recycles processes by killing + old ones and launching new ones.</p> +</summary> +<seealso><a href="../bind.html">Setting which addresses and + ports Apache uses</a></seealso> + +<directivesynopsis location="mpm_common"> +<name>CoreDumpDirectory</name> +</directivesynopsis> + +<directivesynopsis location="mpm_common"> +<name>PidFile</name> +</directivesynopsis> + +<directivesynopsis location="mpm_common"> +<name>Listen</name> +</directivesynopsis> + +<directivesynopsis location="mpm_common"> +<name>ListenBacklog</name> +</directivesynopsis> + +<directivesynopsis location="mpm_common"> +<name>LockFile</name> +</directivesynopsis> + +<directivesynopsis location="mpm_common"> +<name>MaxRequestsPerChild</name> +</directivesynopsis> + +<directivesynopsis location="mpm_common"> +<name>MaxSpareServers</name> +</directivesynopsis> + +<directivesynopsis location="mpm_common"> +<name>MinSpareServers</name> +</directivesynopsis> + +<directivesynopsis location="mpm_common"> +<name>ScoreBoardFile</name> +</directivesynopsis> + +<directivesynopsis location="mpm_common"> +<name>SendBufferSize</name> +</directivesynopsis> + +<directivesynopsis location="mpm_common"> +<name>ServerLimit</name> +</directivesynopsis> + +<directivesynopsis location="mpm_common"> +<name>StartServers</name> +</directivesynopsis> + +<directivesynopsis location="mpm_common"> +<name>User</name> +</directivesynopsis> + +<directivesynopsis> +<name>AcceptMutex</name> +<description>Method that Apache uses to serialize multiple children +accepting requests on network sockets</description> +<syntax>AcceptMutex default|<em>method</em></syntax> +<default>AcceptMutex default</default> +<contextlist><context>server config</context></contextlist> + +<usage> + <p>The <directive>AcceptMutex</directive> directives sets the + method that Apache uses to serialize multiple children accepting + requests on network sockets. Prior to Apache 2.0, the method was + selectable only at compile time. The optimal method to use is + highly architecture and platform dependent. For further details, + see the <a href="../misc/perf-tuning.html">performance tuning</a> + documentation.</p> + + <p>If this directive is set to <code>default</code>, then the + compile-time selected default will be used. Other possible + methods are listed below. Note that not all methods are + available on all platforms. If a method is specified which is + not available, a message will be written to the error log + listing the available methods.</p> + + <dl> + <dt><code>flock</code></dt> + + <dd>uses the <code>flock(2)</code> system call to lock the + file defined by the <directive module="mpm_common" + >LockFile</directive> directive.</dd> + + <dt><code>fcntl</code></dt> + + <dd>uses the <code>fnctl(2)</code> system call to lock the + file defined by the <directive module="mpm_common" + >LockFile</directive> directive.</dd> + + <dt><code>sysvsem</code></dt> + + <dd>uses SySV-style semaphores to implement the mutex.</dd> + + <dt><code>pthread</code></dt> + + <dd>uses POSIX mutexes as implemented by the POSIX Threads + (PThreads) specification.</dd> + </dl> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>MaxSpareServers</name> +<description>Maximum number of idle child server processes</description> +<syntax>MaxSpareServers <em>number</em><br /></syntax> +<default>MaxSpareServers 10</default> +<contextlist><context>server config</context></contextlist> + +<usage> + <p>The <directive>MaxSpareServers</directive> directive sets the + desired maximum number of <em>idle</em> child server processes. An + idle process is one which is not handling a request. If there are + more than MaxSpareServers idle, then the parent process will kill + off the excess processes.</p> + + <p>Tuning of this parameter should only be necessary on very + busy sites. Setting this parameter to a large number is almost + always a bad idea.</p> +</usage> +<seealso><directive module="prefork">MinSpareServers</directive></seealso> +<seealso><directive module="mpm_common">StartServers</directive></seealso> +</directivesynopsis> + +<directivesynopsis> +<name>MinSpareServers</name> +<description>Minimum number of idle child server processes</description> +<syntax>MinSpareServers <em>number</em></syntax> +<default>MinSpareServers 5</default> +<contextlist><context>server config</context></contextlist> + +<usage> + <p>The <directive>MinSpareServers</directive> directive sets the + desired minimum number of <em>idle</em> child server processes. An + idle process is one which is not handling a request. If there are + fewer than MinSpareServers idle, then the parent process creates + new children at a maximum rate of 1 per second.</p> + + <p>Tuning of this parameter should only be necessary on very + busy sites. Setting this parameter to a large number is almost + always a bad idea.</p> + + <p>This directive has no effect on Microsoft Windows.</p> +</usage> +<seealso><directive module="prefork">MaxSpareServers</directive></seealso> +<seealso><directive module="mpm_common">StartServers</directive></seealso> +</directivesynopsis> + +</modulesynopsis> + diff --git a/docs/manual/mod/worker.html b/docs/manual/mod/worker.html new file mode 100644 index 0000000000..48e4d6642c --- /dev/null +++ b/docs/manual/mod/worker.html @@ -0,0 +1,121 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org" /> + + <title>Apache MPM worker</title> + </head> + <!-- Background white, links blue (unvisited), navy (visited), red (active) --> + + <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" + vlink="#000080" alink="#FF0000"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Multi-Processing Module worker</h1> + + <p>This Multi-Processing Module implements a hybrid + multi-threaded multi-process web server.</p> + + <p><a href="module-dict.html#Status" + rel="Help"><strong>Status:</strong></a> MPM<br /> + <a href="module-dict.html#SourceFile" + rel="Help"><strong>Source File:</strong></a> worker.c<br /> + <a href="module-dict.html#ModuleIdentifier" + rel="Help"><strong>Module Identifier:</strong></a> + mpm_worker_module</p> + + <h2>Summary</h2> + + <p>This Multi-Processing Module (MPM) is the default for most + unix-like operating systems. It implements a hybrid + multi-process multi-threaded server. Each process has a fixed + number of threads. The server adjusts to handle load by + increasing or decreasing the number of processes.</p> + + <p>A single control process is responsible for launching child + processes. Each child process creates a fixed number of threads + as specified in the <code>ThreadsPerChild</code> directive. The + individual threads then listen for connections and serve them + when they arrive.</p> + + <p>Apache always tries to maintain a pool of <em>spare</em> or + idle server threads, which stand ready to serve incoming + requests. In this way, clients do not need to wait for a new + threads or processes to be created before their requests can be + served. Apache assesses the total number of idle threads in all + processes, and forks or kills processes to keep this number + within the boundaries specified by <code>MinSpareThreads</code> + and <code>MaxSpareThreads</code>. Since this process is very + self-regulating, it is rarely necessary to modify these + directives from their default values. The maximum number of + clients that may be served simultaneously is determined by + multiplying the maximum number of server processes that will be + created (<code>MaxClients</code>) by the number of threads + created in each process (<code>ThreadsPerChild</code>).</p> + + <p>While the parent process is usually started as root under + Unix in order to bind to port 80, the child processes and + threads are launched by Apache as a less-privileged user. The + <code>User</code> and <code>Group</code> directives are used to + set the privileges of the Apache child processes. The child + processes must be able to read all the content that will be + served, but should have as few privileges beyond that as + possible. In addition, unless <a + href="../suexec.html">suexec</a> is used, these directives also + set the privileges which will be inherited by CGI scripts.</p> + + <p><code>MaxRequestsPerChild</code> controls how frequently the + server recycles processes by killing old ones and launching new + ones.</p> + + <p>See also: <a href="../bind.html">Setting which addresses and + ports Apache uses</a>.</p> + + <h2>Directives</h2> + + <ul> + <li><a + href="mpm_common.html#coredumpdirectory">CoreDumpDirectory</a></li> + + <li><a href="mpm_common.html#group">Group</a></li> + + <li><a href="mpm_common.html#pidfile">PidFile</a></li> + + <li><a href="mpm_common.html#listen">Listen</a></li> + + <li><a + href="mpm_common.html#listenbacklog">ListenBacklog</a></li> + + <li><a href="mpm_common.html#lockfile">LockFile</a></li> + + <li><a href="mpm_common.html#maxclients">MaxClients</a></li> + + <li><a + href="mpm_common.html#maxrequestsperchild">MaxRequestsPerChild</a></li> + + <li><a + href="mpm_common.html#maxsparethreads">MaxSpareThreads</a></li> + + <li><a + href="mpm_common.html#minsparethreads">MinSpareThreads</a></li> + + <li><a + href="mpm_common.html#scoreboardfile">ScoreBoardFile</a></li> + + <li><a + href="mpm_common.html#sendbuffersize">SendBufferSize</a></li> + + <li><a + href="mpm_common.html#startservers">StartServers</a></li> + + <li><a + href="mpm_common.html#threadsperchild">ThreadsPerChild</a></li> + + <li><a href="mpm_common.html#user">User</a></li> + </ul> + <!--#include virtual="footer.html" --> + </body> +</html> + diff --git a/docs/manual/mod/worker.xml b/docs/manual/mod/worker.xml new file mode 100644 index 0000000000..c0d38ce982 --- /dev/null +++ b/docs/manual/mod/worker.xml @@ -0,0 +1,94 @@ +<?xml version="1.0"?> +<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd"> +<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?> +<modulesynopsis> +<name>worker</name> +<description>Multi-Processing Module implementing a hybrid + multi-threaded multi-process web server</description> +<status>MPM</status> +<sourcefile>worker.c</sourcefile> +<identifier>mpm_worker_module</identifier> + +<summary> + <p>This Multi-Processing Module (MPM) is the default for most + unix-like operating systems. It implements a hybrid + multi-process multi-threaded server. Each process has a fixed + number of threads. The server adjusts to handle load by + increasing or decreasing the number of processes.</p> + + <p>A single control process is responsible for launching child + processes. Each child process creates a fixed number of threads + as specified in the <code>ThreadsPerChild</code> directive. The + individual threads then listen for connections and serve them + when they arrive.</p> + + <p>Apache always tries to maintain a pool of <em>spare</em> or + idle server threads, which stand ready to serve incoming + requests. In this way, clients do not need to wait for a new + threads or processes to be created before their requests can be + served. Apache assesses the total number of idle threads in all + processes, and forks or kills processes to keep this number + within the boundaries specified by <code>MinSpareThreads</code> + and <code>MaxSpareThreads</code>. Since this process is very + self-regulating, it is rarely necessary to modify these + directives from their default values. The maximum number of + clients that may be served simultaneously is determined by + multiplying the maximum number of server processes that will be + created (<code>MaxClients</code>) by the number of threads + created in each process (<code>ThreadsPerChild</code>).</p> + + <p>While the parent process is usually started as root under + Unix in order to bind to port 80, the child processes and + threads are launched by Apache as a less-privileged user. The + <code>User</code> and <code>Group</code> directives are used to + set the privileges of the Apache child processes. The child + processes must be able to read all the content that will be + served, but should have as few privileges beyond that as + possible. In addition, unless <a + href="../suexec.html">suexec</a> is used, these directives also + set the privileges which will be inherited by CGI scripts.</p> + + <p><code>MaxRequestsPerChild</code> controls how frequently the + server recycles processes by killing old ones and launching new + ones.</p> + + <p>See also: <a href="../bind.html">Setting which addresses and + ports Apache uses</a>.</p> +</summary> + +<directivesynopsis location="mpm_common"><name>CoreDumpDirectory</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"><name>Group</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"><name>PidFile</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"><name>Listen</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"><name>ListenBacklog</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"><name>LockFile</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"><name>MaxClients</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"><name>MaxRequestsPerChild</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"><name>MaxSpareThreads</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"><name>MinSpareThreads</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"><name>ScoreBoardFile</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"><name>SendBufferSize</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"><name>ServerLimit</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"><name>StartServers</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"><name>ThreadLimit</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"><name>ThreadsPerChild</name> +</directivesynopsis> +<directivesynopsis location="mpm_common"><name>User</name> +</directivesynopsis> + +</modulesynopsis>
\ No newline at end of file diff --git a/docs/manual/new_features_2_0.html.de b/docs/manual/new_features_2_0.html.de new file mode 100644 index 0000000000..b32085498e --- /dev/null +++ b/docs/manual/new_features_2_0.html.de @@ -0,0 +1,180 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta name="generator" content="notepad" /> + + <title>New features with Apache 2.0</title> + </head> + <!-- Background white, links blue (unvisited), navy (visited), red (active) --> + + <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" + vlink="#000080" alink="#FF0000"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Übersicht der neuen Funktionen in Apache 2.0</h1> + <p>übersetzt von simon.putz@t-online.de</p> + <p>Erweiterungen: <a href="#core">Core</a> | <a href="#module">Module</a></p> + + <hr /> + + <h2><a id="core" name="core">Core Erweiterungen:</a></h2> + + <dl> + <dt><strong>Unix Threading</strong></dt> + + <dd>Auf Unix Systemen mit POSIX threads Unterstützung, kann Apache jetzt + in einem hybrid multiprocess im multithreaded mode gestartet werden. Dies + verbessiert die Skalierfähigkeit für viele, aber nicht alle Konfigurationen.</dd> + + <dt><strong>Neues Build System</strong></dt> + + <dd>Das build system wurde komplett auf der Basis von autoconf und libtool neugeschrieben. + Dadurch wird Apaches Konfigurationssystem dem vieler anderer Packages ähnlicher.</dd> + + <dt><strong>Multiprotocol Unterstützung</strong></dt> + + <dd>Apache hat jetzt einiges der Infrastruktur bereit um mehrere Protokolle zu unterstützen. + mod_echo wurde zum Beispiel neugeschrieben.</dd> + + <dt><strong>Bessere Unterstützung von nicht-Unix Plattformen</strong></dt> + + <dd>Apache 2.0 ist schneller und stabiler auf nicht-Unix + Plattformen wie BeOS, OS/2, und Windows. Mit der Einführung von Plattform-spezifischen + <a href="mpm.html">multi-processing Modulen</a> (MPMs) und der + Apache Portable Runtime (APR), sind diese Plattformen jetzt in ihrer + eigenen API implementiert, was die häufigen Fehler der schlecht funktionierenden + POSIX-emulation layer vermeidet.</dd> + + <dt><strong>Neue Apache API</strong></dt> + + <dd>Die API für Module hat sich in 2.0 stark verändert. + Viele der module-ordering Probleme von 1.3 sollten verschwunden sein. + 2.0 macht einiges hiervon automatisch, und das module ordering wird + jetzt per-hook vorgenommen, um mehr Flexibilität zu bieten. Außerdem wurden neue calls + hinzugefügt, die zusätzliche Modul-Fähigkeiten bieten, ohne den core zu patchen.</dd> + + <dt><strong>IPv6 Unterstützung</strong></dt> + + <dd>Auf Systemen, bei denen IPv6 durch die zugrunde liegende + Apache Portable Runtime library unterstützt ist, bekommt Apache standarmäßig IPv6 listening + sockets. Zusätzlich unterstützen die Listen, + NameVirtualHost, and <VirtualHost> Directiven + numerische IPv6 address strings (z.B., "Listen + [fe80::1]:8080").</dd> + + <dt><strong>Filtering</strong></dt> + + <dd>Apache Module können jetzt als Filter die auf den Inhalts-Stream wirken, wie er + von oder zum Server kommt. + Dadurch können z. B. die Ausgabe von CGI scripts von den Server Side Include Direktiven + durch den INCLUDE filter in mod_include bearbeitet werden.</dd> + + <dt><strong>Mehrsprachige Fehlermeldungen</strong></dt> + + <dd>Fehlermeldungen zum Browser werden jetzt, durch SSI Dokumente, in verschiedenen Sprachen zur Verfügung gestellt. + Sie können durch den Administrator angepasst werden, um ein einheitliches Design zu erreichen.</dd> + + <dt><strong>Vereinfachte Konfiguration</strong></dt> + + <dd>Viele komplizierte Direktiven wurden vereinfacht. Die oft verwirrenden + Port und BindAddress Direktiven wurden entfernt; nur die + Listen Direktive wird zum IP address binding benutzt; die + ServerName Direktive bestimmt den Server-Namen und Port-Nummer + nur zur Weiterleitung und vhost Erkennung.</dd> + + <dt><strong>Eingebaute Windows NT Unicode Unterstützung</strong></dt> + + <dd>Apache 2.0 auf Windows NT benutzt jetzt utf-8 für alle Dateinamen + Encodierungen. Diese werden direkt zum zugrunde liegenden unicode Dateisystem übersetzt, + somit wird die Mehrsprach-Unterstützung, fü alle Windows NT-basiernde Installationen, + inclusive Windows 2000 und Windows XP gewährt. + <em>Diese Unterstützung geht nicht auf Windows 95, 98 oder ME über, diese + benutzen noch immer die lokale codepage des Rechners zum Dateisystem-Zugriff.</em></dd> + + </dl> + <hr /> + + <h2><a id="module" name="module">Modul Erweiterungen:</a></h2> + + <dl> + <dt><strong>mod_ssl</strong></dt> + + <dd>Neues Modul in Apache 2.0. Dieses Modul ist ein Interface + zu den SSL/TLS Verschlüsselungs-Protokollen, die von OpenSSL bereitgestellt werden.</dd> + + <dt><strong>mod_dav</strong></dt> + + <dd>Neues Modul in Apache 2.0. Dieses Modul bietet die HTTP + Distributed Authoring and Versioning (DAV) Spezifikation, um + Web-Inhalte zu Posten und zu Warten.</dd> + + <dt><strong>mod_auth_digest</strong></dt> + + <dd>Zusätzliche Unterstützung für prozessübergreifendes session caching mittels shared memory. + </dd> + + <dt><strong>mod_charset_lite</strong></dt> + + <dd>Neues Modul in Apache 2.0. Dieses experimentelle Modul erlaubt Zeichensatz-Übersetung oder Wiederkodierung.</dd> + + <dt><strong>mod_file_cache</strong></dt> + + <dd>Neues Modul in Apache 2.0. Dieses Modul beinhaltet die Funktionen von mod_mmap_static aus Apache 1.3 und + weitere Zwischenspeicherungs-Möglichkeiten.</dd> + + <dt><strong>mod_headers</strong></dt> + + <dd>Dieses Modul ist in Apache 2.0 viel flexibler geworden. Es kann jetzt request-header die von mod_proxy benutzt werden, verändern + und es kann Response-Header nach Fallunterscheidung setzen.</dd> + + <dt><strong>mod_proxy</strong></dt> + + <dd>Das Proxy Modul wurde komplett neugeschrieben um die Funktionen der neuen Filter Infrastruktur auszuschöpfen und + um einen zuverlässigen, mit HTTP/1.1 übereinstimmenden Proxy zu erstellen.</dd> + + <dt><strong>mod_negotiation</strong></dt> + + <dd>Eine neue <a href="mod/mod_negotiation.html#forcelanguagepriority">ForceLanguagePriority</a> + Direktive kann benutzt werden, um zu sichern, dass der Client auf jeden Fall ein einzelnes Dokument anstatt + NOT ACCEPTABLE oder MULTIPLE CHOICES Antworten bekommt. Zusätzlich wurden die Verhandlungs und Multiview + Algorithmen gesäubert um einheitlichere Ergebnisse zu liefern. Außerdem wird eine neue Form der Type Map + die Dokumente einschließen kann, bereitgestellt.</dd> + + <dt><strong>mod_autoindex</strong></dt> + + <dd>Automatisch indizierte Verzeichnis Auflistungen können für bessere Übersichtlichkeit + durch eine HTML Tabelle dargestellt werden. Genauerere Sortierungen, wie Versions-Sorting und Platzhalter-Filtering + des Verzeichnislistings werden unterstützt.</dd> + + <dt><strong>mod_include</strong></dt> + + <dd>Neue Direktiven erlauben es, die Standard Start- und Endtags von SSI Elementen + zu ändern und die Fehler and Zeitformat Konfiguration in der Haupkonfigurationsdatei + anstatt im SSI Dokument stattzufinden. + Ergebnisse von regular expression parsing und grouping können duch die mod_include Variablen $0 bis $9 eingeholt werden.</dd> + + <dt><strong>mod_auth_dbm</strong></dt> + + <dd>DBM-ähnliche Datenbanken werden jetzt durch die <a href="mod/mod_auth_dbm.html#authdbmtype">AuthDBMType</a> + Direktive unterstützt.<a + </dd> + + <dt><strong>mod_auth_db</strong></dt> + + <dd>Berkeley DB 3.0 wird jetzt unterstützt</dd> + + <dt><strong>mod_proxy</strong></dt> + + <dd>Neue <Proxy > Konfigurations Sections bringen eine lesbarere + (und intern schnellere) Kontrolle der zwischengespeicherten Seiten; die überladene + <Directory "proxy:...> Konfiguration wird nicht unterstützt. Das + Modul is jetzt in eigene Protokoll-Unterstützungs Module wie proxy_connect, proxy_ftp and proxy_http gegliedert.</dd> + + </dl> + <!--#include virtual="footer.html" --> + </body> +</html> + + diff --git a/docs/manual/sitemap.html b/docs/manual/sitemap.html new file mode 100644 index 0000000000..34e21dad8a --- /dev/null +++ b/docs/manual/sitemap.html @@ -0,0 +1,201 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <title>Site Map - Apache HTTP Server 2.0</title> + </head> + <!-- Background white, links blue (unvisited), navy (visited), red (active) --> + + <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" + vlink="#000080" alink="#FF0000"> + <!--#include virtual="header.html" --> + + <h1 align="center">Site Map</h1> + +<ul> +<li><a href="index.html">Apache HTTP Server Version 2.0 Documentation</a> + +<ul> +<li>Release Notes +<ul> +<li><a href="upgrading.html">Upgrading to 2.0 from 1.3</a></li> +<li><a href="new_features_2_0.html">New features with Apache 2.0</a></li> +</ul></li> + +<li>Using the Apache HTTP Server +<ul> +<li><a href="install.html">Compiling and Installing Apache</a></li> +<li><a href="invoking.html">Starting Apache</a></li> +<li><a href="stopping.html">Stopping and Restarting the Server</a></li> +<li><a href="configuring.html">Configuration Files</a></li> +<li><a href="sections.html">How Directory, Location and Files sections work</a></li> +<li><a href="server-wide.html">Server-Wide Configuration</a></li> +<li><a href="logs.html">Log Files</a></li> +<li><a href="urlmapping.html">Mapping URLs to Filesystem Locations</a></li> +<li><a href="misc/security_tips.html">Security Tips</a></li> +<li><a href="dso.html">Dynamic Shared Object (DSO) support</a></li> +<li><a href="content-negotiation.html">Content Negotiation</a></li> +<li><a href="custom-error.html">Custom error responses</a></li> +<li><a href="bind.html">Setting which addresses and ports Apache uses</a></li> +<li><a href="mpm.html">Multi-Processing Modules (MPMs)</a></li> +<li><a href="env.html">Environment Variables in Apache</a></li> +<li><a href="handler.html">Apache's Handler Use</a></li> +<li><a href="filter.html">Filters</a></li> +<li><a href="suexec.html">suEXEC Support</a></li> +<li><a href="misc/perf-tuning.html">Performance Hintes</a></li> +<li><a href="misc/rewriteguide.html">URL Rewriting Guide</a></li> +</ul></li> + +<li><a href="vhosts/index.html">Apache Virtual Host documentation</a> +<ul> +<li><a href="vhosts/name-based.html">Name-based Virtual Hosts</a></li> +<li><a href="vhosts/ip-based.html">IP-based Virtual Host Support</a></li> +<li><a href="vhosts/mass.html">Dynamically configured mass virtual hosting</a></li> +<li><a href="vhosts/examples.html">VirtualHost Examples</a></li> +<li><a href="vhosts/details.html">An In-Depth Discussion of Virtual Host Matching</a></li> +<li><a href="vhosts/fd-limits.html">File descriptor limitations</a></li> +<li><a href="dns-caveats.html">Issues Regarding DNS and Apache</a></li> +</ul></li> + +<li><a href="faq/index.html">Apache Server Frequently Asked Questions</a> +<ul> +<li><a href="faq/support.html">Support</a></li> +</ul></li> + +<li><a href="ssl/index.html">Apache SSL/TLS Encryption</a> +<ul> +<li><a href="ssl/ssl_intro.html">SSL/TLS Encryption: An Introduction</a></li> +<li><a href="ssl/ssl_compat.html">SSL/TLS Encryption: Compatibility</a></li> +<li><a href="ssl/ssl_howto.html">SSL/TLS Encryption: How-To</a></li> +<li><a href="ssl/ssl_faq.html">SSL/TLS Encryption: FAQ</a></li> +<li><a href="ssl/ssl_glossary.html">SSL/TLS Encryption: Glossary</a></li> +</ul></li> + + +<li>Guides, Tutorials, and HowTos +<ul> +<li><a href="howto/auth.html">Authentication</a></li> +<li><a href="howto/cgi.html">Apache Tutorial: Dynamic Content with CGI</a></li> +<li><a href="howto/ssi.html">Apache Tutorial: Introduction to Server +Side Includes</a></li> +<li><a href="misc/tutorials.html">Apache Tutorials</a></li> +</ul></li> + + +<li>Platfrom-specific Notes +<ul> +<li><a href="platform/windows.html">Using Apache with Microsoft +Windows</a></li> +<li><a href="platform/win_compiling.html">Compiling Apache for +Microsoft Windows</a></li> +<li><a href="platform/win_service.html">Running Apache for Windows as +a Service</a></li> +<li><a href="platform/netware.html">Using Apache with Novell NetWare</a></li> +<li><a href="platform/perf-hp.html">Running a High-Performance Web +Server on HPUX</a></li> +<li><a href="ebcdic.html">The Apache EBCDIC Port</a></li> +</ul></li> + +<li><a href="programs/index.html">Apache HTTP Server and Supporting Programs</a> +<ul> +<li><a href="programs/httpd.html">Manual Page: httpd</a></li> +<li><a href="programs/ab.html">Manual Page: ab</a></li> +<li><a href="programs/apachectl.html">Manual Page: apachectl</a></li> +<li><a href="programs/apxs.html">Manual Page: apxs</a></li> +<li><a href="programs/dbmmanage.html">Manual Page: dbmmanage</a></li> +<li><a href="programs/htdigest.html">Manual Page: htdigest</a></li> +<li><a href="programs/htpasswd.html">Manual Page: htpasswd</a></li> +<li><a href="programs/logresolve.html">Manual Page: logresolve</a></li> +<li><a href="programs/rotatelogs.html">Manual Page: rotatelogs</a></li> +<li><a href="programs/suexec.html">Manual Page: suexec</a></li> +<li><a href="programs/other.html">Other Programs</a></li> +</ul></li> + +<li><a href="misc/index.html">Apache Miscellaneous Documentation</a> +<ul> +<li><a href="misc/custom_errordocs.html">International Customized Server Error Messages</a></li> +<li><a href="misc/fin_wait_2.html">Connections in FIN_WAIT_2 and Apache</a></li> +<li><a href="misc/known_client_problems.html">Known Client Problems</a></li> +<li><a href="misc/descriptors.html">Descriptors and Apache</a></li> +<li><a href="cgi_path.html">PATH_INFO Changes in the CGI Environment</a></li> +</ul></li> + +<li><a href="mod/index.html">Apache modules</a> +<ul> +<li><a href="mod/index-bytype.html">Apache modules - By Type</a></li> +<li><a href="mod/directives.html">Apache directives</a></li> +<li><a href="mod/module-dict.html">Definitions of terms used to describe Apache modules</a></li> +<li><a href="mod/directive-dict.html">Definitions of terms used to describe Apache directives</a></li> +<li><a href="mod/core.html">Apache Core Features</a></li> +<li><a href="mod/mpm_common.html">Apache MPM Common Directives</a></li> +<li><a href="mod/mpm_netware.html">Apache MPM netware</a></li> +<li><a href="mod/mpm_winnt.html">Apache MPM winnt</a></li> +<li><a href="mod/perchild.html">Apache MPM perchild</a></li> +<li><a href="mod/prefork.html">Apache MPM prefork</a></li> +<li><a href="mod/threaded.html">Apache MPM threaded</a></li> +<li><a href="mod/mod_access.html">Apache module mod_access</a></li> +<li><a href="mod/mod_actions.html">Apache module mod_actions</a></li> +<li><a href="mod/mod_alias.html">Apache module mod_alias</a></li> +<li><a href="mod/mod_asis.html">Apache module mod_asis</a></li> +<li><a href="mod/mod_auth.html">Apache module mod_auth</a></li> +<li><a href="mod/mod_auth_anon.html">Apache module mod_auth_anon.c</a></li> +<li><a href="mod/mod_auth_db.html">Apache module mod_auth_db</a></li> +<li><a href="mod/mod_auth_dbm.html">Apache module mod_auth_dbm</a></li> +<li><a href="mod/mod_auth_digest.html">Apache module mod_auth_digest</a></li> +<li><a href="mod/mod_auth_ldap.html">Apache module mod_ldap</a></li> +<li><a href="mod/mod_autoindex.html">Apache module mod_autoindex</a></li> +<li><a href="mod/mod_cern_meta.html">Apache module mod_cern_meta</a></li> +<li><a href="mod/mod_cgi.html">Apache module mod_cgi</a></li> +<li><a href="mod/mod_cgid.html">Apache module mod_cgi</a></li> +<li><a href="mod/mod_charset_lite.html">Apache module mod_charset_lite</a></li> +<li><a href="mod/mod_dav.html">Apache module mod_dav</a></li> +<li><a href="mod/mod_dir.html">Apache module mod_dir</a></li> +<li><a href="mod/mod_env.html">Apache module mod_env</a></li> +<li><a href="mod/mod_example.html">Apache module mod_example</a></li> +<li><a href="mod/mod_expires.html">Apache module mod_expires</a></li> +<li><a href="mod/mod_ext_filter.html">Apache module mod_ext_filter</a></li> +<li><a href="mod/mod_file_cache.html">Apache module mod_file_cache</a></li> +<li><a href="mod/mod_headers.html">Apache module mod_headers</a></li> +<li><a href="mod/mod_imap.html">Apache module mod_imap</a></li> +<li><a href="mod/mod_include.html">Apache module mod_include</a></li> +<li><a href="mod/mod_info.html">Apache module mod_info</a></li> +<li><a href="mod/mod_isapi.html">Apache module mod_isapi</a></li> +<li><a href="mod/mod_ldap.html">Apache module mod_ldap</a></li> +<li><a href="mod/mod_log_config.html">Apache module mod_log_config</a></li> +<li><a href="mod/mod_mime.html">Apache module mod_mime</a></li> +<li><a href="mod/mod_mime_magic.html">Apache module mod_mime_magic</a></li> +<li><a href="mod/mod_mmap_static.html">Apache module mod_mmap_static</a></li> +<li><a href="mod/mod_negotiation.html">Apache module mod_negotiation</a></li> +<li><a href="mod/mod_proxy.html">Apache module mod_proxy</a></li> +<li><a href="mod/mod_rewrite.html">Apache module mod_rewrite</a></li> +<li><a href="mod/mod_setenvif.html">Apache module mod_setenvif</a></li> +<li><a href="mod/mod_so.html">Apache module mod_so</a></li> +<li><a href="mod/mod_speling.html">Apache module mod_speling</a></li> +<li><a href="mod/mod_ssl.html">Apache module mod_ssl</a></li> +<li><a href="mod/mod_status.html">Apache module mod_status</a></li> +<li><a href="mod/mod_suexec.html">Apache module mod_suexec</a></li> +<li><a href="mod/mod_unique_id.html">Apache module mod_unique_id</a></li> +<li><a href="mod/mod_userdir.html">Apache module mod_userdir</a></li> +<li><a href="mod/mod_usertrack.html">Apache module mod_usertrack</a></li> +<li><a href="mod/mod_vhost_alias.html">Apache module mod_vhost_alias</a></li> +</ul></li> + +<li><a href="developer/index.html">Developer Documentation</a> +<ul> +<li><a href="developer/API.html">Apache API notes</a></li> +<li><a href="developer/debugging.html">Debugging Memory Allocation in APR</a></li> +<li><a href="developer/documenting.html">Documenting Apache 2.0</a></li> +<li><a href="developer/hooks.html">Apache 2.0 Hook Functions</a></li> +<li><a href="developer/layeredio.html">Apache 2.0 Layered I/O</a></li> +<li><a href="developer/modules.html">Converting Modules from Apache 1.3 to Apache 2.0</a></li> +<li><a href="developer/request.html">Request Processing in Apache 2.0</a></li> +</ul></li> + +</ul></li> + +</ul> + + <!--#include virtual="footer.html" --> + </body> +</html>
\ No newline at end of file diff --git a/docs/manual/sitemap.html.en b/docs/manual/sitemap.html.en new file mode 100644 index 0000000000..34e21dad8a --- /dev/null +++ b/docs/manual/sitemap.html.en @@ -0,0 +1,201 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <title>Site Map - Apache HTTP Server 2.0</title> + </head> + <!-- Background white, links blue (unvisited), navy (visited), red (active) --> + + <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" + vlink="#000080" alink="#FF0000"> + <!--#include virtual="header.html" --> + + <h1 align="center">Site Map</h1> + +<ul> +<li><a href="index.html">Apache HTTP Server Version 2.0 Documentation</a> + +<ul> +<li>Release Notes +<ul> +<li><a href="upgrading.html">Upgrading to 2.0 from 1.3</a></li> +<li><a href="new_features_2_0.html">New features with Apache 2.0</a></li> +</ul></li> + +<li>Using the Apache HTTP Server +<ul> +<li><a href="install.html">Compiling and Installing Apache</a></li> +<li><a href="invoking.html">Starting Apache</a></li> +<li><a href="stopping.html">Stopping and Restarting the Server</a></li> +<li><a href="configuring.html">Configuration Files</a></li> +<li><a href="sections.html">How Directory, Location and Files sections work</a></li> +<li><a href="server-wide.html">Server-Wide Configuration</a></li> +<li><a href="logs.html">Log Files</a></li> +<li><a href="urlmapping.html">Mapping URLs to Filesystem Locations</a></li> +<li><a href="misc/security_tips.html">Security Tips</a></li> +<li><a href="dso.html">Dynamic Shared Object (DSO) support</a></li> +<li><a href="content-negotiation.html">Content Negotiation</a></li> +<li><a href="custom-error.html">Custom error responses</a></li> +<li><a href="bind.html">Setting which addresses and ports Apache uses</a></li> +<li><a href="mpm.html">Multi-Processing Modules (MPMs)</a></li> +<li><a href="env.html">Environment Variables in Apache</a></li> +<li><a href="handler.html">Apache's Handler Use</a></li> +<li><a href="filter.html">Filters</a></li> +<li><a href="suexec.html">suEXEC Support</a></li> +<li><a href="misc/perf-tuning.html">Performance Hintes</a></li> +<li><a href="misc/rewriteguide.html">URL Rewriting Guide</a></li> +</ul></li> + +<li><a href="vhosts/index.html">Apache Virtual Host documentation</a> +<ul> +<li><a href="vhosts/name-based.html">Name-based Virtual Hosts</a></li> +<li><a href="vhosts/ip-based.html">IP-based Virtual Host Support</a></li> +<li><a href="vhosts/mass.html">Dynamically configured mass virtual hosting</a></li> +<li><a href="vhosts/examples.html">VirtualHost Examples</a></li> +<li><a href="vhosts/details.html">An In-Depth Discussion of Virtual Host Matching</a></li> +<li><a href="vhosts/fd-limits.html">File descriptor limitations</a></li> +<li><a href="dns-caveats.html">Issues Regarding DNS and Apache</a></li> +</ul></li> + +<li><a href="faq/index.html">Apache Server Frequently Asked Questions</a> +<ul> +<li><a href="faq/support.html">Support</a></li> +</ul></li> + +<li><a href="ssl/index.html">Apache SSL/TLS Encryption</a> +<ul> +<li><a href="ssl/ssl_intro.html">SSL/TLS Encryption: An Introduction</a></li> +<li><a href="ssl/ssl_compat.html">SSL/TLS Encryption: Compatibility</a></li> +<li><a href="ssl/ssl_howto.html">SSL/TLS Encryption: How-To</a></li> +<li><a href="ssl/ssl_faq.html">SSL/TLS Encryption: FAQ</a></li> +<li><a href="ssl/ssl_glossary.html">SSL/TLS Encryption: Glossary</a></li> +</ul></li> + + +<li>Guides, Tutorials, and HowTos +<ul> +<li><a href="howto/auth.html">Authentication</a></li> +<li><a href="howto/cgi.html">Apache Tutorial: Dynamic Content with CGI</a></li> +<li><a href="howto/ssi.html">Apache Tutorial: Introduction to Server +Side Includes</a></li> +<li><a href="misc/tutorials.html">Apache Tutorials</a></li> +</ul></li> + + +<li>Platfrom-specific Notes +<ul> +<li><a href="platform/windows.html">Using Apache with Microsoft +Windows</a></li> +<li><a href="platform/win_compiling.html">Compiling Apache for +Microsoft Windows</a></li> +<li><a href="platform/win_service.html">Running Apache for Windows as +a Service</a></li> +<li><a href="platform/netware.html">Using Apache with Novell NetWare</a></li> +<li><a href="platform/perf-hp.html">Running a High-Performance Web +Server on HPUX</a></li> +<li><a href="ebcdic.html">The Apache EBCDIC Port</a></li> +</ul></li> + +<li><a href="programs/index.html">Apache HTTP Server and Supporting Programs</a> +<ul> +<li><a href="programs/httpd.html">Manual Page: httpd</a></li> +<li><a href="programs/ab.html">Manual Page: ab</a></li> +<li><a href="programs/apachectl.html">Manual Page: apachectl</a></li> +<li><a href="programs/apxs.html">Manual Page: apxs</a></li> +<li><a href="programs/dbmmanage.html">Manual Page: dbmmanage</a></li> +<li><a href="programs/htdigest.html">Manual Page: htdigest</a></li> +<li><a href="programs/htpasswd.html">Manual Page: htpasswd</a></li> +<li><a href="programs/logresolve.html">Manual Page: logresolve</a></li> +<li><a href="programs/rotatelogs.html">Manual Page: rotatelogs</a></li> +<li><a href="programs/suexec.html">Manual Page: suexec</a></li> +<li><a href="programs/other.html">Other Programs</a></li> +</ul></li> + +<li><a href="misc/index.html">Apache Miscellaneous Documentation</a> +<ul> +<li><a href="misc/custom_errordocs.html">International Customized Server Error Messages</a></li> +<li><a href="misc/fin_wait_2.html">Connections in FIN_WAIT_2 and Apache</a></li> +<li><a href="misc/known_client_problems.html">Known Client Problems</a></li> +<li><a href="misc/descriptors.html">Descriptors and Apache</a></li> +<li><a href="cgi_path.html">PATH_INFO Changes in the CGI Environment</a></li> +</ul></li> + +<li><a href="mod/index.html">Apache modules</a> +<ul> +<li><a href="mod/index-bytype.html">Apache modules - By Type</a></li> +<li><a href="mod/directives.html">Apache directives</a></li> +<li><a href="mod/module-dict.html">Definitions of terms used to describe Apache modules</a></li> +<li><a href="mod/directive-dict.html">Definitions of terms used to describe Apache directives</a></li> +<li><a href="mod/core.html">Apache Core Features</a></li> +<li><a href="mod/mpm_common.html">Apache MPM Common Directives</a></li> +<li><a href="mod/mpm_netware.html">Apache MPM netware</a></li> +<li><a href="mod/mpm_winnt.html">Apache MPM winnt</a></li> +<li><a href="mod/perchild.html">Apache MPM perchild</a></li> +<li><a href="mod/prefork.html">Apache MPM prefork</a></li> +<li><a href="mod/threaded.html">Apache MPM threaded</a></li> +<li><a href="mod/mod_access.html">Apache module mod_access</a></li> +<li><a href="mod/mod_actions.html">Apache module mod_actions</a></li> +<li><a href="mod/mod_alias.html">Apache module mod_alias</a></li> +<li><a href="mod/mod_asis.html">Apache module mod_asis</a></li> +<li><a href="mod/mod_auth.html">Apache module mod_auth</a></li> +<li><a href="mod/mod_auth_anon.html">Apache module mod_auth_anon.c</a></li> +<li><a href="mod/mod_auth_db.html">Apache module mod_auth_db</a></li> +<li><a href="mod/mod_auth_dbm.html">Apache module mod_auth_dbm</a></li> +<li><a href="mod/mod_auth_digest.html">Apache module mod_auth_digest</a></li> +<li><a href="mod/mod_auth_ldap.html">Apache module mod_ldap</a></li> +<li><a href="mod/mod_autoindex.html">Apache module mod_autoindex</a></li> +<li><a href="mod/mod_cern_meta.html">Apache module mod_cern_meta</a></li> +<li><a href="mod/mod_cgi.html">Apache module mod_cgi</a></li> +<li><a href="mod/mod_cgid.html">Apache module mod_cgi</a></li> +<li><a href="mod/mod_charset_lite.html">Apache module mod_charset_lite</a></li> +<li><a href="mod/mod_dav.html">Apache module mod_dav</a></li> +<li><a href="mod/mod_dir.html">Apache module mod_dir</a></li> +<li><a href="mod/mod_env.html">Apache module mod_env</a></li> +<li><a href="mod/mod_example.html">Apache module mod_example</a></li> +<li><a href="mod/mod_expires.html">Apache module mod_expires</a></li> +<li><a href="mod/mod_ext_filter.html">Apache module mod_ext_filter</a></li> +<li><a href="mod/mod_file_cache.html">Apache module mod_file_cache</a></li> +<li><a href="mod/mod_headers.html">Apache module mod_headers</a></li> +<li><a href="mod/mod_imap.html">Apache module mod_imap</a></li> +<li><a href="mod/mod_include.html">Apache module mod_include</a></li> +<li><a href="mod/mod_info.html">Apache module mod_info</a></li> +<li><a href="mod/mod_isapi.html">Apache module mod_isapi</a></li> +<li><a href="mod/mod_ldap.html">Apache module mod_ldap</a></li> +<li><a href="mod/mod_log_config.html">Apache module mod_log_config</a></li> +<li><a href="mod/mod_mime.html">Apache module mod_mime</a></li> +<li><a href="mod/mod_mime_magic.html">Apache module mod_mime_magic</a></li> +<li><a href="mod/mod_mmap_static.html">Apache module mod_mmap_static</a></li> +<li><a href="mod/mod_negotiation.html">Apache module mod_negotiation</a></li> +<li><a href="mod/mod_proxy.html">Apache module mod_proxy</a></li> +<li><a href="mod/mod_rewrite.html">Apache module mod_rewrite</a></li> +<li><a href="mod/mod_setenvif.html">Apache module mod_setenvif</a></li> +<li><a href="mod/mod_so.html">Apache module mod_so</a></li> +<li><a href="mod/mod_speling.html">Apache module mod_speling</a></li> +<li><a href="mod/mod_ssl.html">Apache module mod_ssl</a></li> +<li><a href="mod/mod_status.html">Apache module mod_status</a></li> +<li><a href="mod/mod_suexec.html">Apache module mod_suexec</a></li> +<li><a href="mod/mod_unique_id.html">Apache module mod_unique_id</a></li> +<li><a href="mod/mod_userdir.html">Apache module mod_userdir</a></li> +<li><a href="mod/mod_usertrack.html">Apache module mod_usertrack</a></li> +<li><a href="mod/mod_vhost_alias.html">Apache module mod_vhost_alias</a></li> +</ul></li> + +<li><a href="developer/index.html">Developer Documentation</a> +<ul> +<li><a href="developer/API.html">Apache API notes</a></li> +<li><a href="developer/debugging.html">Debugging Memory Allocation in APR</a></li> +<li><a href="developer/documenting.html">Documenting Apache 2.0</a></li> +<li><a href="developer/hooks.html">Apache 2.0 Hook Functions</a></li> +<li><a href="developer/layeredio.html">Apache 2.0 Layered I/O</a></li> +<li><a href="developer/modules.html">Converting Modules from Apache 1.3 to Apache 2.0</a></li> +<li><a href="developer/request.html">Request Processing in Apache 2.0</a></li> +</ul></li> + +</ul></li> + +</ul> + + <!--#include virtual="footer.html" --> + </body> +</html>
\ No newline at end of file diff --git a/docs/manual/ssl/index.html b/docs/manual/ssl/index.html new file mode 100644 index 0000000000..fb39a4440b --- /dev/null +++ b/docs/manual/ssl/index.html @@ -0,0 +1,223 @@ +<html> +<head> +<title>mod_ssl: Title Page</title> + +<!-- + Copyright (c) 1998-2001 Ralf S. Engelschall. All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code must retain the above + copyright notice, this list of conditions and the following + disclaimer. + + 2. Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials + provided with the distribution. + + 3. All advertising materials mentioning features or use of this + software must display the following acknowledgment: + "This product includes software developed by + Ralf S. Engelschall <rse@engelschall.com> for use in the + mod_ssl project (http://www.modssl.org/)." + + 4. The name "mod_ssl" must not be used to endorse or promote + products derived from this software without prior written + permission. + + 5. Redistributions of any form whatsoever must retain the + following acknowledgment: + "This product includes software developed by + Ralf S. Engelschall <rse@engelschall.com> for use in the + mod_ssl project (http://www.modssl.org/)." + + THIS SOFTWARE IS PROVIDED BY RALF S. ENGELSCHALL ``AS IS'' AND ANY + EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RALF S. ENGELSCHALL OR + HIS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT + NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; + LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED + OF THE POSSIBILITY OF SUCH DAMAGE. +--> +<style type="text/css"><!-- +A:link { + text-decoration: none; + color: #6666cc; +} +A:active { + text-decoration: none; + color: #6666cc; +} +A:visited { + text-decoration: none; + color: #6666cc; +} +#sf { + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +H1 { + font-weight: bold; + font-size: 24pt; + line-height: 24pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +H2 { + font-weight: bold; + font-size: 18pt; + line-height: 18pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +H3 { + font-weight: bold; + font-size: 14pt; + line-height: 14pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +H4 { + font-weight: bold; + font-size: 12pt; + line-height: 12pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +#H { +} +#D { + background-color: #f0f0f0; +} +#faq { + font-weight: bold; + font-size: 16pt; + line-height: 16pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +#howto { + font-weight: bold; + font-size: 16pt; + line-height: 16pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +#term { + font-weight: bold; + font-size: 16pt; + line-height: 16pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +--></style> +<script type="text/javascript" language="JavaScript"> +<!-- Hiding the code +function ro_imgNormal(imgName) { + if (document.images) { + document[imgName].src = eval(imgName + '_n.src'); + self.status = ''; + } +} +function ro_imgOver(imgName, descript) { + if (document.images) { + document[imgName].src = eval(imgName + '_o.src'); + self.status = descript; + } +} +// done hiding --> +</script> +<script type="text/javascript" language="JavaScript"> +<!-- Hiding the code +if (document.images) { + ro_img_unknown1_n = new Image(); + ro_img_unknown1_n.src = 'ssl_template.navbut-next-n.gif'; + ro_img_unknown1_o = new Image(); + ro_img_unknown1_o.src = 'ssl_template.navbut-next-s.gif'; +} +// done hiding --> +</script> +</head> +<body bgcolor="#ffffff" text="#000000" link="#333399" alink="#9999ff" vlink="#000066"> +<div align="center"> +<table width="600" cellspacing="0" cellpadding="0" border="0" summary=""> +<tr> + <td> +<br> +<table cellspacing="0" cellpadding="0" border="0" summary=""> +<tr> + <td> + <table cellspacing="0" cellpadding="0" border="0" summary=""> + <tr> + <td> + <img + src="ssl_cover_title.jpg" + alt="User Manual" + width="421" height="73"> + </td> + </tr> + <tr> + <td align="right"> + <font face="Arial,Helvetica">mod_ssl version 2.8</font> + </td> + </tr> + </table> + <br> + </td> +</tr> +<tr> + <td> + <a + href="http://www.modssl.org/" +><img + src="ssl_cover_logo.jpg" + alt="mod_ssl - The Apache Interface to OpenSSL" + border="0" + width="504" height="231"></a> + </td> +</tr> +<tr> + <td align="right"> + <table summary=""> + <tr> + <td> + <tt>Ralf S. Engelschall</tt><br> + <tt>rse@engelschall.com</tt><br> + <tt>www.engelschall.com</tt><br> + </td> + <td> + + </td> + <td align="right" valign="bottom"> +<a href="ssl_overview.html" onmouseover="ro_imgOver('ro_img_unknown1', 'next page'); return true" onmouseout="ro_imgNormal('ro_img_unknown1'); return true" onfocus="ro_imgOver('ro_img_unknown1', 'next page'); return true" onblur="ro_imgNormal('ro_img_unknown1'); return true"><img name="ro_img_unknown1" src="ssl_template.navbut-next-n.gif" alt="next page" width="70" height="18" border="0"></a><br>Overview + </td> + <td> + <img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="30" height="1" align="bottom" border="0"> + </td> + </tr> + </table> + </td> +</tr> +</table> + </td> +</tr> +</table> +</div> +</body> +</html> diff --git a/docs/manual/ssl/index.html.en b/docs/manual/ssl/index.html.en new file mode 100644 index 0000000000..fb39a4440b --- /dev/null +++ b/docs/manual/ssl/index.html.en @@ -0,0 +1,223 @@ +<html> +<head> +<title>mod_ssl: Title Page</title> + +<!-- + Copyright (c) 1998-2001 Ralf S. Engelschall. All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code must retain the above + copyright notice, this list of conditions and the following + disclaimer. + + 2. Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials + provided with the distribution. + + 3. All advertising materials mentioning features or use of this + software must display the following acknowledgment: + "This product includes software developed by + Ralf S. Engelschall <rse@engelschall.com> for use in the + mod_ssl project (http://www.modssl.org/)." + + 4. The name "mod_ssl" must not be used to endorse or promote + products derived from this software without prior written + permission. + + 5. Redistributions of any form whatsoever must retain the + following acknowledgment: + "This product includes software developed by + Ralf S. Engelschall <rse@engelschall.com> for use in the + mod_ssl project (http://www.modssl.org/)." + + THIS SOFTWARE IS PROVIDED BY RALF S. ENGELSCHALL ``AS IS'' AND ANY + EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RALF S. ENGELSCHALL OR + HIS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT + NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; + LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED + OF THE POSSIBILITY OF SUCH DAMAGE. +--> +<style type="text/css"><!-- +A:link { + text-decoration: none; + color: #6666cc; +} +A:active { + text-decoration: none; + color: #6666cc; +} +A:visited { + text-decoration: none; + color: #6666cc; +} +#sf { + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +H1 { + font-weight: bold; + font-size: 24pt; + line-height: 24pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +H2 { + font-weight: bold; + font-size: 18pt; + line-height: 18pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +H3 { + font-weight: bold; + font-size: 14pt; + line-height: 14pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +H4 { + font-weight: bold; + font-size: 12pt; + line-height: 12pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +#H { +} +#D { + background-color: #f0f0f0; +} +#faq { + font-weight: bold; + font-size: 16pt; + line-height: 16pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +#howto { + font-weight: bold; + font-size: 16pt; + line-height: 16pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +#term { + font-weight: bold; + font-size: 16pt; + line-height: 16pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +--></style> +<script type="text/javascript" language="JavaScript"> +<!-- Hiding the code +function ro_imgNormal(imgName) { + if (document.images) { + document[imgName].src = eval(imgName + '_n.src'); + self.status = ''; + } +} +function ro_imgOver(imgName, descript) { + if (document.images) { + document[imgName].src = eval(imgName + '_o.src'); + self.status = descript; + } +} +// done hiding --> +</script> +<script type="text/javascript" language="JavaScript"> +<!-- Hiding the code +if (document.images) { + ro_img_unknown1_n = new Image(); + ro_img_unknown1_n.src = 'ssl_template.navbut-next-n.gif'; + ro_img_unknown1_o = new Image(); + ro_img_unknown1_o.src = 'ssl_template.navbut-next-s.gif'; +} +// done hiding --> +</script> +</head> +<body bgcolor="#ffffff" text="#000000" link="#333399" alink="#9999ff" vlink="#000066"> +<div align="center"> +<table width="600" cellspacing="0" cellpadding="0" border="0" summary=""> +<tr> + <td> +<br> +<table cellspacing="0" cellpadding="0" border="0" summary=""> +<tr> + <td> + <table cellspacing="0" cellpadding="0" border="0" summary=""> + <tr> + <td> + <img + src="ssl_cover_title.jpg" + alt="User Manual" + width="421" height="73"> + </td> + </tr> + <tr> + <td align="right"> + <font face="Arial,Helvetica">mod_ssl version 2.8</font> + </td> + </tr> + </table> + <br> + </td> +</tr> +<tr> + <td> + <a + href="http://www.modssl.org/" +><img + src="ssl_cover_logo.jpg" + alt="mod_ssl - The Apache Interface to OpenSSL" + border="0" + width="504" height="231"></a> + </td> +</tr> +<tr> + <td align="right"> + <table summary=""> + <tr> + <td> + <tt>Ralf S. Engelschall</tt><br> + <tt>rse@engelschall.com</tt><br> + <tt>www.engelschall.com</tt><br> + </td> + <td> + + </td> + <td align="right" valign="bottom"> +<a href="ssl_overview.html" onmouseover="ro_imgOver('ro_img_unknown1', 'next page'); return true" onmouseout="ro_imgNormal('ro_img_unknown1'); return true" onfocus="ro_imgOver('ro_img_unknown1', 'next page'); return true" onblur="ro_imgNormal('ro_img_unknown1'); return true"><img name="ro_img_unknown1" src="ssl_template.navbut-next-n.gif" alt="next page" width="70" height="18" border="0"></a><br>Overview + </td> + <td> + <img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="30" height="1" align="bottom" border="0"> + </td> + </tr> + </table> + </td> +</tr> +</table> + </td> +</tr> +</table> +</div> +</body> +</html> diff --git a/docs/manual/ssl/ssl_compat.html b/docs/manual/ssl/ssl_compat.html new file mode 100644 index 0000000000..391c0668c6 --- /dev/null +++ b/docs/manual/ssl/ssl_compat.html @@ -0,0 +1,551 @@ +<html> +<head> +<title>mod_ssl: Compatibility</title> + +<!-- + Copyright (c) 1998-2001 Ralf S. Engelschall. All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code must retain the above + copyright notice, this list of conditions and the following + disclaimer. + + 2. Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials + provided with the distribution. + + 3. All advertising materials mentioning features or use of this + software must display the following acknowledgment: + "This product includes software developed by + Ralf S. Engelschall <rse@engelschall.com> for use in the + mod_ssl project (http://www.modssl.org/)." + + 4. The name "mod_ssl" must not be used to endorse or promote + products derived from this software without prior written + permission. + + 5. Redistributions of any form whatsoever must retain the + following acknowledgment: + "This product includes software developed by + Ralf S. Engelschall <rse@engelschall.com> for use in the + mod_ssl project (http://www.modssl.org/)." + + THIS SOFTWARE IS PROVIDED BY RALF S. ENGELSCHALL ``AS IS'' AND ANY + EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RALF S. ENGELSCHALL OR + HIS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT + NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; + LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED + OF THE POSSIBILITY OF SUCH DAMAGE. +--> +<style type="text/css"><!-- +A:link { + text-decoration: none; + color: #6666cc; +} +A:active { + text-decoration: none; + color: #6666cc; +} +A:visited { + text-decoration: none; + color: #6666cc; +} +#sf { + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +H1 { + font-weight: bold; + font-size: 24pt; + line-height: 24pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +H2 { + font-weight: bold; + font-size: 18pt; + line-height: 18pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +H3 { + font-weight: bold; + font-size: 14pt; + line-height: 14pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +H4 { + font-weight: bold; + font-size: 12pt; + line-height: 12pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +#H { +} +#D { + background-color: #f0f0f0; +} +#faq { + font-weight: bold; + font-size: 16pt; + line-height: 16pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +#howto { + font-weight: bold; + font-size: 16pt; + line-height: 16pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +#term { + font-weight: bold; + font-size: 16pt; + line-height: 16pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +--></style> +<script type="text/javascript" language="JavaScript"> +<!-- Hiding the code +function ro_imgNormal(imgName) { + if (document.images) { + document[imgName].src = eval(imgName + '_n.src'); + self.status = ''; + } +} +function ro_imgOver(imgName, descript) { + if (document.images) { + document[imgName].src = eval(imgName + '_o.src'); + self.status = descript; + } +} +// done hiding --> +</script> +<script type="text/javascript" language="JavaScript"> +<!-- Hiding the code +if (document.images) { + ro_img_prev_top_n = new Image(); + ro_img_prev_top_n.src = 'ssl_template.navbut-prev-n.gif'; + ro_img_prev_top_o = new Image(); + ro_img_prev_top_o.src = 'ssl_template.navbut-prev-s.gif'; +} +// done hiding --> +</script> +<script type="text/javascript" language="JavaScript"> +<!-- Hiding the code +if (document.images) { + ro_img_prev_bot_n = new Image(); + ro_img_prev_bot_n.src = 'ssl_template.navbut-prev-n.gif'; + ro_img_prev_bot_o = new Image(); + ro_img_prev_bot_o.src = 'ssl_template.navbut-prev-s.gif'; +} +// done hiding --> +</script> +<script type="text/javascript" language="JavaScript"> +<!-- Hiding the code +if (document.images) { + ro_img_next_top_n = new Image(); + ro_img_next_top_n.src = 'ssl_template.navbut-next-n.gif'; + ro_img_next_top_o = new Image(); + ro_img_next_top_o.src = 'ssl_template.navbut-next-s.gif'; +} +// done hiding --> +</script> +<script type="text/javascript" language="JavaScript"> +<!-- Hiding the code +if (document.images) { + ro_img_next_bot_n = new Image(); + ro_img_next_bot_n.src = 'ssl_template.navbut-next-n.gif'; + ro_img_next_bot_o = new Image(); + ro_img_next_bot_o.src = 'ssl_template.navbut-next-s.gif'; +} +// done hiding --> +</script> +</head> +<body bgcolor="#ffffff" text="#000000" link="#333399" alink="#9999ff" vlink="#000066"> +<div align="center"> +<table width="600" cellspacing="0" cellpadding="0" border="0" summary=""> +<tr> + <td> + <img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="600" height="1" align="bottom" border="0"><br> + <table width="600" cellspacing="0" cellpadding="0" summary=""> + <tr> + <td> + <table width="600" summary=""> + <tr> + <td align="left" valign="bottom"> + <font face="Arial,Helvetica" size="+2"><b>mod_ssl</b></font> + </td> + <td align="right"> + <img src="ssl_template.head-chapter.gif" alt="Chapter" width="175" height="94"> <img src="ssl_template.head-num-4.gif" alt="4" width="74" height="89"> + </td> + </tr> + </table> + </td> + </tr> + <tr> + <td><img src="ssl_template.imgdot-1x1-000000.gif" alt="" width="600" height="2" align="bottom" border="0"></td> + </tr> + <tr> + <td> + <table width="600" border="0" summary=""> + <tr> + <td valign="top" align="left" width="250"> +<a href="ssl_reference.html" onmouseover="ro_imgOver('ro_img_prev_top', 'previous page'); return true" onmouseout="ro_imgNormal('ro_img_prev_top'); return true" onfocus="ro_imgOver('ro_img_prev_top', 'previous page'); return true" onblur="ro_imgNormal('ro_img_prev_top'); return true"><img name="ro_img_prev_top" src="ssl_template.navbut-prev-n.gif" alt="previous page" width="70" height="18" border="0"></a><br><font color="#000000">Reference</font> + </td> + <td valign="top" align="right" width="250"> +<a href="ssl_howto.html" onmouseover="ro_imgOver('ro_img_next_top', 'next page'); return true" onmouseout="ro_imgNormal('ro_img_next_top'); return true" onfocus="ro_imgOver('ro_img_next_top', 'next page'); return true" onblur="ro_imgNormal('ro_img_next_top'); return true"><img name="ro_img_next_top" src="ssl_template.navbut-next-n.gif" alt="next page" width="70" height="18" border="0"></a><br><font color="#000000">HowTo</font> + </td> + </tr> + </table> + </td> + </tr> + <tr> + <td> + <br> + <img src="ssl_template.title-compat.gif" alt="Compatibility" width="456" height="60"> + </td> + </tr> + </table> +<div align="right"> +<table cellspacing="0" cellpadding="0" width="200" summary=""> +<tr> +<td> +<em> +All PCs are compatible. But some of +them are more compatible than others. +</em> +</td> +</tr> +<tr> +<td align="right"> +<font size="-1"> +Unknown +</font> +</td> +</tr> +</table> +</div> +<p> +<table cellspacing="0" cellpadding="0" border="0" summary=""> +<tr valign="bottom"> +<td> +<img src="ssl_compat.gfont000.gif" alt="H" width="40" height="34" border="0" align="left"> +ere we talk about backward compatibility to other SSL solutions. As you +perhaps know, mod_ssl is not the only existing SSL solution for Apache. +Actually there are four additional major products available on the market: Ben +Laurie's freely available <a href="http://www.apache-ssl.org/">Apache-SSL</a> +(from where mod_ssl were originally derived in 1998), RedHat's commercial <a +href="http://www.redhat.com/products/product-details.phtml?id=rhsa">Secure Web +Server</a> (which is based on mod_ssl), Covalent's commercial <a +href="http://raven.covalent.net/">Raven SSL Module</a> (also based on mod_ssl) +and finally C2Net's commercial product <a +href="http://www.c2.net/products/stronghold/">Stronghold</a> (based on a +different evolution branch named Sioux up to Stronghold 2.x and based on +mod_ssl since Stronghold 3.x). +</td> +<td> + +</td> +<td> +<div align="right"> +<table cellspacing="0" cellpadding="5" border="0" bgcolor="#ccccff" summary=""> +<tr> +<td bgcolor="#333399"> +<font face="Arial,Helvetica" color="#ccccff"> +<b>Table Of Contents</b> +</font> +</td> +</tr> +<tr> +<td> +<font face="Arial,Helvetica" size="-1"> + <a href="#ToC1"><strong>Configuration Directives</strong></a><br> + <a href="#ToC2"><strong>Environment Variables</strong></a><br> + <a href="#ToC3"><strong>Custom Log Functions</strong></a><br> +</font> +</td> +</tr> +</table> +</div> +</td> +</tr> +</table> +<p> +The idea in mod_ssl is mainly the following: because mod_ssl provides mostly a +superset of the functionality of all other solutions we can easily provide +backward compatibility for most of the cases. Actually there are three +compatibility areas we currently address: configuration directives, +environment variables and custom log functions. +<h2><a name="ToC1">Configuration Directives</a></h2> +For backward compatibility to the configuration directives of other SSL +solutions we do an on-the-fly mapping: directives which have a direct +counterpart in mod_ssl are mapped silently while other directives lead to a +warning message in the logfiles. The currently implemented directive mapping +is listed in <a href="#table1">Table 1</a>. Currently full backward +compatibilty is provided only for Apache-SSL 1.x and mod_ssl 2.0.x. +Compatibility to Sioux 1.x and Stronghold 2.x is only partial because of +special functionality in these interfaces which mod_ssl (still) doesn't +provide. +<p> +<div align="center"> +<a name="table1"></a> +<table width="600" cellspacing="0" cellpadding="1" border="0" summary=""> +<caption align="bottom" id="sf">Table 1: Configuration Directive Mapping</caption> +<tr><td bgcolor="#cccccc"> +<table width="598" cellpadding="5" cellspacing="0" border="0" summary=""> +<tr><td valign="top" align="center" bgcolor="#ffffff"> +<table border="0" cellspacing="0" cellpadding="2" width="598" summary=""> +<tr id="D"> +<td><strong>Old Directive</strong></td> +<td><strong>mod_ssl Directive</strong></td> +<td><strong>Comment</strong></td> +</tr> +<tr id="H"><td colspan="3"><b>Apache-SSL 1.x & mod_ssl 2.0.x compatibility:</b></td></tr> +<tr id="D"><td><code>SSLEnable</code></td><td><code>SSLEngine on</code></td><td>compactified</td></tr> +<tr id="H"><td><code>SSLDisable</code></td><td><code>SSLEngine off</code></td><td>compactified</td></tr> +<tr id="D"><td><code>SSLLogFile</code> <em>file</em></td><td><code>SSLLog</code> <em>file</em></td><td>compactified</td></tr> +<tr id="H"><td><code>SSLRequiredCiphers</code> <em>spec</em></td><td><code>SSLCipherSuite</code> <em>spec</em></td><td>renamed</td></tr> +<tr id="D"><td><code>SSLRequireCipher</code> <em>c1</em> ...</td><td><code>SSLRequire %{SSL_CIPHER} in {"</code><em>c1</em><code>", ...}</code></td><td>generalized</td></tr> +<tr id="H"><td><code>SSLBanCipher</code> <em>c1</em> ...</td><td><code>SSLRequire not (%{SSL_CIPHER} in {"</code><em>c1</em><code>", ...})</code></td><td>generalized</td></tr> +<tr id="D"><td><code>SSLFakeBasicAuth</td><td><code>SSLOptions +FakeBasicAuth</code></td><td>merged</td></tr> +<tr id="H"><td><code>SSLCacheServerPath</code> <em>dir</em></td><td>-</td><td>functionality removed</td></tr> +<tr id="D"><td><code>SSLCacheServerPort</code> <em>integer</em></td><td>-</td><td>functionality removed</td></tr> +<tr id="H"><td colspan="3"><b>Apache-SSL 1.x compatibility:</b></td></tr> +<tr id="D"><td><code>SSLExportClientCertificates</td><td><code>SSLOptions +ExportCertData</code></td><td>merged</td></tr> +<tr id="H"><td><code>SSLCacheServerRunDir</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id="D"><td colspan="3"><b>Sioux 1.x compatibility:</b></td></tr> +<tr id="H"><td><code>SSL_CertFile</code> <em>file</em></td><td><code>SSLCertificateFile</code> <em>file</em></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_KeyFile</code> <em>file</em></td><td><code>SSLCertificateKeyFile</code> <em>file</em></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_CipherSuite</code> <em>arg</em></td><td><code>SSLCipherSuite</code> <em>arg</em></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_X509VerifyDir</code> <em>arg</em></td><td><code>SSLCACertificatePath</code> <em>arg</em></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_Log</code> <em>file</em></td><td><code>SSLLogFile</code> <em>file</em></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_Connect</code> <em>flag</em></td><td><code>SSLEngine</code> <em>flag</em></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_ClientAuth</code> <em>arg</em></td><td><code>SSLVerifyClient</code> <em>arg</em></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_X509VerifyDepth</code> <em>arg</em></td><td><code>SSLVerifyDepth</code> <em>arg</em></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_FetchKeyPhraseFrom</code> <em>arg</em></td><td>-</td><td>not directly mappable; use SSLPassPhraseDialog</td></tr> +<tr id="D"><td><code>SSL_SessionDir</code> <em>dir</em></td><td>-</td><td>not directly mappable; use SSLSessionCache</td></tr> +<tr id="H"><td><code>SSL_Require</code> <em>expr</em></td><td>-</td><td>not directly mappable; use SSLRequire</td></tr> +<tr id="D"><td><code>SSL_CertFileType</code> <em>arg</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id="H"><td><code>SSL_KeyFileType</code> <em>arg</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id="D"><td><code>SSL_X509VerifyPolicy</code> <em>arg</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id="H"><td><code>SSL_LogX509Attributes</code> <em>arg</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id="D"><td colspan="3"><b>Stronghold 2.x compatibility:</b></td></tr> +<tr id="H"><td><code>StrongholdAccelerator</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id="H"><td><code>StrongholdKey</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id="H"><td><code>StrongholdLicenseFile</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id="H"><td><code>SSLFlag</code> <em>flag</em></td><td><code>SSLEngine</code> <em>flag</em></td><td>renamed</td></tr> +<tr id="D"><td><code>SSLSessionLockFile</code> <em>file</em></td><td><code>SSLMutex</code> <em>file</em></td><td>renamed</td></tr> +<tr id="H"><td><code>SSLCipherList</code> <em>spec</em></td><td><code>SSLCipherSuite</code> <em>spec</em></td><td>renamed</td></tr> +<tr id="D"><td><code>RequireSSL</code></td><td><code>SSLRequireSSL</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSLErrorFile</code> <em>file</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id="H"><td><code>SSLRoot</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id="D"><td><code>SSL_CertificateLogDir</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id="H"><td><code>AuthCertDir</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id="D"><td><code>SSL_Group</code> <em>name</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id="H"><td><code>SSLProxyMachineCertPath</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id="D"><td><code>SSLProxyMachineCertFile</code> <em>file</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id="H"><td><code>SSLProxyCACertificatePath</code> <em>dir</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id="D"><td><code>SSLProxyCACertificateFile</code> <em>file</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id="H"><td><code>SSLProxyVerifyDepth</code> <em>number</em></td><td>-</td><td>functionality not supported</td></tr> +<tr id="D"><td><code>SSLProxyCipherList</code> <em>spec</em></td><td>-</td><td>functionality not supported</td></tr> +</table> +</td> +</tr></table> +</td></tr></table> +</div> +<p> +<br> +<h2><a name="ToC2">Environment Variables</a></h2> +When you use ``<code>SSLOptions +CompatEnvVars</code>'' additional environment +variables are generated. They all correspond to existing official mod_ssl +variables. The currently implemented variable derivation is listed in <a +href="#table2">Table 2</a>. +<p> +<div align="center"> +<a name="table2"></a> +<table width="600" cellspacing="0" cellpadding="1" border="0" summary=""> +<caption align="bottom" id="sf">Table 2: Environment Variable Derivation</caption> +<tr><td bgcolor="#cccccc"> +<table width="598" cellpadding="5" cellspacing="0" border="0" summary=""> +<tr><td valign="top" align="center" bgcolor="#ffffff"> +<table border="0" cellspacing="0" cellpadding="2" width="598" summary=""> +<tr id="D"> +<td><strong>Old Variable</strong></td> +<td><strong>mod_ssl Variable</strong></td> +<td><strong>Comment</strong></td> +</tr> +<tr id="H"><td><code>SSL_PROTOCOL_VERSION</code></td><td><code>SSL_PROTOCOL</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSLEAY_VERSION</code></td><td><code>SSL_VERSION_LIBRARY</code></td><td>renamed</td></tr> +<tr id="H"><td><code>HTTPS_SECRETKEYSIZE</code></td><td><code>SSL_CIPHER_USEKEYSIZE</code></td><td>renamed</td></tr> +<tr id="D"><td><code>HTTPS_KEYSIZE</code></td><td><code>SSL_CIPHER_ALGKEYSIZE</code></td><td>renamed</td></tr> +<tr id="H"><td><code>HTTPS_CIPHER</code></td><td><code>SSL_CIPHER</code></td><td>renamed</td></tr> +<tr id="D"><td><code>HTTPS_EXPORT</code></td><td><code>SSL_CIPHER_EXPORT</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_SERVER_KEY_SIZE</code></td><td><code>SSL_CIPHER_ALGKEYSIZE</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_SERVER_CERTIFICATE</code></td><td><code>SSL_SERVER_CERT</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_SERVER_CERT_START</code></td><td><code>SSL_SERVER_V_START</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_SERVER_CERT_END</code></td><td><code>SSL_SERVER_V_END</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_SERVER_CERT_SERIAL</code></td><td><code>SSL_SERVER_M_SERIAL</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_SERVER_SIGNATURE_ALGORITHM</code></td><td><code>SSL_SERVER_A_SIG</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_SERVER_DN</code></td><td><code>SSL_SERVER_S_DN</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_SERVER_CN</code></td><td><code>SSL_SERVER_S_DN_CN</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_SERVER_EMAIL</code></td><td><code>SSL_SERVER_S_DN_Email</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_SERVER_O</code></td><td><code>SSL_SERVER_S_DN_O</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_SERVER_OU</code></td><td><code>SSL_SERVER_S_DN_OU</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_SERVER_C</code></td><td><code>SSL_SERVER_S_DN_C</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_SERVER_SP</code></td><td><code>SSL_SERVER_S_DN_SP</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_SERVER_L</code></td><td><code>SSL_SERVER_S_DN_L</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_SERVER_IDN</code></td><td><code>SSL_SERVER_I_DN</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_SERVER_ICN</code></td><td><code>SSL_SERVER_I_DN_CN</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_SERVER_IEMAIL</code></td><td><code>SSL_SERVER_I_DN_Email</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_SERVER_IO</code></td><td><code>SSL_SERVER_I_DN_O</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_SERVER_IOU</code></td><td><code>SSL_SERVER_I_DN_OU</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_SERVER_IC</code></td><td><code>SSL_SERVER_I_DN_C</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_SERVER_ISP</code></td><td><code>SSL_SERVER_I_DN_SP</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_SERVER_IL</code></td><td><code>SSL_SERVER_I_DN_L</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_CLIENT_CERTIFICATE</code></td><td><code>SSL_CLIENT_CERT</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_CLIENT_CERT_START</code></td><td><code>SSL_CLIENT_V_START</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_CLIENT_CERT_END</code></td><td><code>SSL_CLIENT_V_END</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_CLIENT_CERT_SERIAL</code></td><td><code>SSL_CLIENT_M_SERIAL</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_CLIENT_SIGNATURE_ALGORITHM</code></td><td><code>SSL_CLIENT_A_SIG</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_CLIENT_DN</code></td><td><code>SSL_CLIENT_S_DN</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_CLIENT_CN</code></td><td><code>SSL_CLIENT_S_DN_CN</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_CLIENT_EMAIL</code></td><td><code>SSL_CLIENT_S_DN_Email</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_CLIENT_O</code></td><td><code>SSL_CLIENT_S_DN_O</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_CLIENT_OU</code></td><td><code>SSL_CLIENT_S_DN_OU</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_CLIENT_C</code></td><td><code>SSL_CLIENT_S_DN_C</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_CLIENT_SP</code></td><td><code>SSL_CLIENT_S_DN_SP</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_CLIENT_L</code></td><td><code>SSL_CLIENT_S_DN_L</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_CLIENT_IDN</code></td><td><code>SSL_CLIENT_I_DN</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_CLIENT_ICN</code></td><td><code>SSL_CLIENT_I_DN_CN</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_CLIENT_IEMAIL</code></td><td><code>SSL_CLIENT_I_DN_Email</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_CLIENT_IO</code></td><td><code>SSL_CLIENT_I_DN_O</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_CLIENT_IOU</code></td><td><code>SSL_CLIENT_I_DN_OU</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_CLIENT_IC</code></td><td><code>SSL_CLIENT_I_DN_C</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_CLIENT_ISP</code></td><td><code>SSL_CLIENT_I_DN_SP</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_CLIENT_IL</code></td><td><code>SSL_CLIENT_I_DN_L</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_EXPORT</code></td><td><code>SSL_CIPHER_EXPORT</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_KEYSIZE</code></td><td><code>SSL_CIPHER_ALGKEYSIZE</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_SECKEYSIZE</code></td><td><code>SSL_CIPHER_USEKEYSIZE</code></td><td>renamed</td></tr> +<tr id="H"><td><code>SSL_SSLEAY_VERSION</code></td><td><code>SSL_VERSION_LIBRARY</code></td><td>renamed</td></tr> +<tr id="D"><td><code>SSL_STRONG_CRYPTO</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr> +<tr id="D"><td><code>SSL_SERVER_KEY_EXP</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr> +<tr id="H"><td><code>SSL_SERVER_KEY_ALGORITHM</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr> +<tr id="D"><td><code>SSL_SERVER_KEY_SIZE</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr> +<tr id="H"><td><code>SSL_SERVER_SESSIONDIR</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr> +<tr id="D"><td><code>SSL_SERVER_CERTIFICATELOGDIR</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr> +<tr id="H"><td><code>SSL_SERVER_CERTFILE</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr> +<tr id="D"><td><code>SSL_SERVER_KEYFILE</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr> +<tr id="H"><td><code>SSL_SERVER_KEYFILETYPE</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr> +<tr id="D"><td><code>SSL_CLIENT_KEY_EXP</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr> +<tr id="H"><td><code>SSL_CLIENT_KEY_ALGORITHM</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr> +<tr id="D"><td><code>SSL_CLIENT_KEY_SIZE</code></td><td><code>-</code></td><td>Not supported by mod_ssl</td></tr> +</table> +</td> +</tr></table> +</td></tr></table> +</div> +<p> +<br> +<h2><a name="ToC3">Custom Log Functions</a></h2> +When mod_ssl is built into Apache or at least loaded (under DSO situation) +additional functions exist for the <a +href="../mod_log_config.html#formats">Custom Log Format</a> of <a +href="../mod_log_config.html">mod_log_config</a> as documented in the Reference +Chapter. Beside the ``<code>%{</code><em>varname</em><code>}x</code>'' +eXtension format function which can be used to expand any variables provided +by any module, an additional Cryptography +``<code>%{</code><em>name</em><code>}c</code>'' cryptography format function +exists for backward compatibility. The currently implemented function calls +are listed in <a href="#table3">Table 3</a>. +<p> +<div align="center"> +<a name="table3"></a> +<table width="600" cellspacing="0" cellpadding="1" border="0" summary=""> +<caption align="bottom" id="sf">Table 3: Custom Log Cryptography Function</caption> +<tr><td bgcolor="#cccccc"> +<table width="598" cellpadding="5" cellspacing="0" border="0" summary=""> +<tr><td valign="top" align="center" bgcolor="#ffffff"> +<table border="0" cellspacing="0" cellpadding="2" width="598" summary=""> +<tr id="H"> + <td><strong>Function Call</strong></td> + <td><strong>Description</strong></td> +</tr> +<tr id="D"><td><code>%...{version}c</code></td> <td>SSL protocol version</td></tr> +<tr id="H"><td><code>%...{cipher}c</code></td> <td>SSL cipher</td></tr> +<tr id="D"><td><code>%...{subjectdn}c</code></td> <td>Client Certificate Subject Distinguished Name</td></tr> +<tr id="H"><td><code>%...{issuerdn}c</code></td> <td>Client Certificate Issuer Distinguished Name</td></tr> +<tr id="D"><td><code>%...{errcode}c</code></td> <td>Certificate Verification Error (numerical)</td></tr> +<tr id="H"><td><code>%...{errstr}c</code></td> <td>Certificate Verification Error (string)</td></tr> +</table> +</td> +</tr></table> +</td></tr></table> +</div> + <p> + <br> + <table summary=""> + <tr> + <td> + <table width="600" border="0" summary=""> + <tr> + <td valign="top" align="left" width="250"> +<a href="ssl_reference.html" onmouseover="ro_imgOver('ro_img_prev_bot', 'previous page'); return true" onmouseout="ro_imgNormal('ro_img_prev_bot'); return true" onfocus="ro_imgOver('ro_img_prev_bot', 'previous page'); return true" onblur="ro_imgNormal('ro_img_prev_bot'); return true"><img name="ro_img_prev_bot" src="ssl_template.navbut-prev-n.gif" alt="previous page" width="70" height="18" border="0"></a><br><font color="#000000">Reference</font> + </td> + <td valign="top" align="right" width="250"> +<a href="ssl_howto.html" onmouseover="ro_imgOver('ro_img_next_bot', 'next page'); return true" onmouseout="ro_imgNormal('ro_img_next_bot'); return true" onfocus="ro_imgOver('ro_img_next_bot', 'next page'); return true" onblur="ro_imgNormal('ro_img_next_bot'); return true"><img name="ro_img_next_bot" src="ssl_template.navbut-next-n.gif" alt="next page" width="70" height="18" border="0"></a><br><font color="#000000">HowTo</font> + </td> + </tr> + </table> + </td> + </tr> + <tr> + <td><img src="ssl_template.imgdot-1x1-000000.gif" alt="" width="600" height="2" align="bottom" border="0"></td> + </tr> + <tr> + <td><table width="598" summary=""> + <tr> + <td align="left"><font face="Arial,Helvetica"> + <a href="http://www.modssl.org/">mod_ssl</a> 2.8, User Manual<br> + The Apache Interface to OpenSSL + </font> + </td> + <td align="right"><font face="Arial,Helvetica"> + Copyright © 1998-2001 + <a href="http://www.engelschall.com/">Ralf S. Engelschall</a><br> + All Rights Reserved<br> + </font> + </td> + </tr> + </table> + </td> + </tr> + </table> + </td> +</tr> +</table> +</div> +</body> +</html> diff --git a/docs/manual/ssl/ssl_faq.html b/docs/manual/ssl/ssl_faq.html new file mode 100644 index 0000000000..e3d3aa8f26 --- /dev/null +++ b/docs/manual/ssl/ssl_faq.html @@ -0,0 +1,1643 @@ +<html> +<head> +<title>mod_ssl: F.A.Q.</title> + +<!-- + Copyright (c) 1998-2001 Ralf S. Engelschall. All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code must retain the above + copyright notice, this list of conditions and the following + disclaimer. + + 2. Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials + provided with the distribution. + + 3. All advertising materials mentioning features or use of this + software must display the following acknowledgment: + "This product includes software developed by + Ralf S. Engelschall <rse@engelschall.com> for use in the + mod_ssl project (http://www.modssl.org/)." + + 4. The name "mod_ssl" must not be used to endorse or promote + products derived from this software without prior written + permission. + + 5. Redistributions of any form whatsoever must retain the + following acknowledgment: + "This product includes software developed by + Ralf S. Engelschall <rse@engelschall.com> for use in the + mod_ssl project (http://www.modssl.org/)." + + THIS SOFTWARE IS PROVIDED BY RALF S. ENGELSCHALL ``AS IS'' AND ANY + EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RALF S. ENGELSCHALL OR + HIS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT + NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; + LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED + OF THE POSSIBILITY OF SUCH DAMAGE. +--> +<style type="text/css"><!-- +A:link { + text-decoration: none; + color: #6666cc; +} +A:active { + text-decoration: none; + color: #6666cc; +} +A:visited { + text-decoration: none; + color: #6666cc; +} +#sf { + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +H1 { + font-weight: bold; + font-size: 24pt; + line-height: 24pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +H2 { + font-weight: bold; + font-size: 18pt; + line-height: 18pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +H3 { + font-weight: bold; + font-size: 14pt; + line-height: 14pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +H4 { + font-weight: bold; + font-size: 12pt; + line-height: 12pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +#H { +} +#D { + background-color: #f0f0f0; +} +#faq { + font-weight: bold; + font-size: 16pt; + line-height: 16pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +#howto { + font-weight: bold; + font-size: 16pt; + line-height: 16pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +#term { + font-weight: bold; + font-size: 16pt; + line-height: 16pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +--></style> +<script type="text/javascript" language="JavaScript"> +<!-- Hiding the code +function ro_imgNormal(imgName) { + if (document.images) { + document[imgName].src = eval(imgName + '_n.src'); + self.status = ''; + } +} +function ro_imgOver(imgName, descript) { + if (document.images) { + document[imgName].src = eval(imgName + '_o.src'); + self.status = descript; + } +} +// done hiding --> +</script> +<script type="text/javascript" language="JavaScript"> +<!-- Hiding the code +if (document.images) { + ro_img_prev_top_n = new Image(); + ro_img_prev_top_n.src = 'ssl_template.navbut-prev-n.gif'; + ro_img_prev_top_o = new Image(); + ro_img_prev_top_o.src = 'ssl_template.navbut-prev-s.gif'; +} +// done hiding --> +</script> +<script type="text/javascript" language="JavaScript"> +<!-- Hiding the code +if (document.images) { + ro_img_prev_bot_n = new Image(); + ro_img_prev_bot_n.src = 'ssl_template.navbut-prev-n.gif'; + ro_img_prev_bot_o = new Image(); + ro_img_prev_bot_o.src = 'ssl_template.navbut-prev-s.gif'; +} +// done hiding --> +</script> +<script type="text/javascript" language="JavaScript"> +<!-- Hiding the code +if (document.images) { + ro_img_next_top_n = new Image(); + ro_img_next_top_n.src = 'ssl_template.navbut-next-n.gif'; + ro_img_next_top_o = new Image(); + ro_img_next_top_o.src = 'ssl_template.navbut-next-s.gif'; +} +// done hiding --> +</script> +<script type="text/javascript" language="JavaScript"> +<!-- Hiding the code +if (document.images) { + ro_img_next_bot_n = new Image(); + ro_img_next_bot_n.src = 'ssl_template.navbut-next-n.gif'; + ro_img_next_bot_o = new Image(); + ro_img_next_bot_o.src = 'ssl_template.navbut-next-s.gif'; +} +// done hiding --> +</script> +</head> +<body bgcolor="#ffffff" text="#000000" link="#333399" alink="#9999ff" vlink="#000066"> +<div align="center"> +<table width="600" cellspacing="0" cellpadding="0" border="0" summary=""> +<tr> + <td> + <img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="600" height="1" align="bottom" border="0"><br> + <table width="600" cellspacing="0" cellpadding="0" summary=""> + <tr> + <td> + <table width="600" summary=""> + <tr> + <td align="left" valign="bottom"> + <font face="Arial,Helvetica" size="+2"><b>mod_ssl</b></font> + </td> + <td align="right"> + <img src="ssl_template.head-chapter.gif" alt="Chapter" width="175" height="94"> <img src="ssl_template.head-num-6.gif" alt="6" width="74" height="89"> + </td> + </tr> + </table> + </td> + </tr> + <tr> + <td><img src="ssl_template.imgdot-1x1-000000.gif" alt="" width="600" height="2" align="bottom" border="0"></td> + </tr> + <tr> + <td> + <table width="600" border="0" summary=""> + <tr> + <td valign="top" align="left" width="250"> +<a href="ssl_howto.html" onmouseover="ro_imgOver('ro_img_prev_top', 'previous page'); return true" onmouseout="ro_imgNormal('ro_img_prev_top'); return true" onfocus="ro_imgOver('ro_img_prev_top', 'previous page'); return true" onblur="ro_imgNormal('ro_img_prev_top'); return true"><img name="ro_img_prev_top" src="ssl_template.navbut-prev-n.gif" alt="previous page" width="70" height="18" border="0"></a><br><font color="#000000">HowTo</font> + </td> + <td valign="top" align="right" width="250"> +<a href="ssl_glossary.html" onmouseover="ro_imgOver('ro_img_next_top', 'next page'); return true" onmouseout="ro_imgNormal('ro_img_next_top'); return true" onfocus="ro_imgOver('ro_img_next_top', 'next page'); return true" onblur="ro_imgNormal('ro_img_next_top'); return true"><img name="ro_img_next_top" src="ssl_template.navbut-next-n.gif" alt="next page" width="70" height="18" border="0"></a><br><font color="#000000">Glossary</font> + </td> + </tr> + </table> + </td> + </tr> + <tr> + <td> + <br> + <img src="ssl_template.title-faq.gif" alt="F.A.Q." width="456" height="60"> + </td> + </tr> + </table> +<div align="right"> +<table cellspacing="0" cellpadding="0" width="200" summary=""> +<tr> +<td> +<em> +``The wise man doesn't give the right answers, +he poses the right questions.'' +</em> +</td> +</tr> +<tr> +<td align="right"> +<font size="-1"> +Claude Levi-Strauss +</font> +</td> +</tr> +</table> +</div> +<p> +<table cellspacing="0" cellpadding="0" border="0" summary=""> +<tr valign="bottom"> +<td> +<img src="ssl_faq.gfont000.gif" alt="T" width="34" height="34" border="0" align="left"> +his chapter is a collection of frequently asked questions (FAQ) and +corresponding answers following the popular USENET tradition. Most of these +questions occured on the Newsgroup <a +href="news:comp.infosystems.www.servers.unix"> +<code>comp.infosystems.www.servers.unix</code></a> or the mod_ssl Support +Mailing List <a href="mailto:modssl-users@modssl.org"> +<code>modssl-users@modssl.org</code></a>. They are collected at this place +to avoid answering the same questions over and over. +<p> +Please read this chapter at least once when installing mod_ssl or at least +search for your problem here before submitting a problem report to the +author. +</td> +<td> + +</td> +<td> +<div align="right"> +<table cellspacing="0" cellpadding="5" border="0" bgcolor="#ccccff" width="350" summary=""> +<tr> +<td bgcolor="#333399"> +<font face="Arial,Helvetica" color="#ccccff"> +<b>Table Of Contents</b> +</font> +</td> +</tr> +<tr> +<td> +<font face="Arial,Helvetica" size="-1"> + <a href="#ToC1"><strong>About the module</strong></a><br> + <a href="#ToC2"><strong>What is the history of mod_ssl?</strong></a><br> + <a href="#ToC3"><strong>Apache-SSL vs. mod_ssl: differences?</strong></a><br> + <a href="#ToC4"><strong>mod_ssl vs. commercial alternatives?</strong></a><br> + <a href="#ToC5"><strong>mod_ssl/Apache versions?</strong></a><br> + <a href="#ToC6"><strong>mod_ssl and Year 2000?</strong></a><br> + <a href="#ToC7"><strong>mod_ssl and Wassenaar Arrangement?</strong></a><br> + <a href="#ToC8"><strong>About Installation</strong></a><br> + <a href="#ToC9"><strong>Core dumps for HTTPS requests?</strong></a><br> + <a href="#ToC10"><strong>Core dumps for Apache+mod_ssl+PHP3?</strong></a><br> + <a href="#ToC11"><strong>Undefined symbols on startup?</strong></a><br> + <a href="#ToC12"><strong>Permission problem on SSLMutex</strong></a><br> + <a href="#ToC13"><strong>Shared memory and process size?</strong></a><br> + <a href="#ToC14"><strong>Shared memory and pathname?</strong></a><br> + <a href="#ToC15"><strong>PRNG and not enough entropy?</strong></a><br> + <a href="#ToC16"><strong>About Configuration</strong></a><br> + <a href="#ToC17"><strong>HTTP and HTTPS with a single server?</strong></a><br> + <a href="#ToC18"><strong>Where is the HTTPS port?</strong></a><br> + <a href="#ToC19"><strong>How to test HTTPS manually?</strong></a><br> + <a href="#ToC20"><strong>Why does my connection hang?</strong></a><br> + <a href="#ToC21"><strong>Why do I get connection refused?</strong></a><br> + <a href="#ToC22"><strong>Why are the SSL_XXX variables missing?</strong></a><br> + <a href="#ToC23"><strong>How to switch with relative hyperlinks?</strong></a><br> + <a href="#ToC24"><strong>About Certificates</strong></a><br> + <a href="#ToC25"><strong>What are Keys, CSRs and Certs?</strong></a><br> + <a href="#ToC26"><strong>Difference on startup?</strong></a><br> + <a href="#ToC27"><strong>How to create a dummy cert?</strong></a><br> + <a href="#ToC28"><strong>How to create a real cert?</strong></a><br> + <a href="#ToC29"><strong>How to create my own CA?</strong></a><br> + <a href="#ToC30"><strong>How to change a pass phrase?</strong></a><br> + <a href="#ToC31"><strong>How to remove a pass phrase?</strong></a><br> + <a href="#ToC32"><strong>How to verify a key/cert pair?</strong></a><br> + <a href="#ToC33"><strong>Bad Certificate Error?</strong></a><br> + <a href="#ToC34"><strong>Why does a 2048-bit key not work?</strong></a><br> + <a href="#ToC35"><strong>Why is client auth broken?</strong></a><br> + <a href="#ToC36"><strong>How to convert from PEM to DER?</strong></a><br> + <a href="#ToC37"><strong>Verisign and the magic getca program?</strong></a><br> + <a href="#ToC38"><strong>Global IDs or SGC?</strong></a><br> + <a href="#ToC39"><strong>Global IDs and Cert Chain?</strong></a><br> + <a href="#ToC40"><strong>About SSL Protocol</strong></a><br> + <a href="#ToC41"><strong>Random SSL errors under heavy load?</strong></a><br> + <a href="#ToC42"><strong>Why has the server a higher load?</strong></a><br> + <a href="#ToC43"><strong>Why are connections horribly slow?</strong></a><br> + <a href="#ToC44"><strong>Which ciphers are supported?</strong></a><br> + <a href="#ToC45"><strong>How to use Anonymous-DH ciphers</strong></a><br> + <a href="#ToC46"><strong>Why do I get 'no shared ciphers'?</strong></a><br> + <a href="#ToC47"><strong>HTTPS and name-based vhosts</strong></a><br> + <a href="#ToC48"><strong>The lock icon in Netscape locks very late</strong></a><br> + <a href="#ToC49"><strong>Why do I get I/O errors with MSIE clients?</strong></a><br> + <a href="#ToC50"><strong>Why do I get I/O errors with NS clients?</strong></a><br> + <a href="#ToC51"><strong>About Support</strong></a><br> + <a href="#ToC52"><strong>Resources in case of problems?</strong></a><br> + <a href="#ToC53"><strong>Support in case of problems?</strong></a><br> + <a href="#ToC54"><strong>How to write a problem report?</strong></a><br> + <a href="#ToC55"><strong>I got a core dump, can you help me?</strong></a><br> + <a href="#ToC56"><strong>How to get a backtrace?</strong></a><br> +</font> +</td> +</tr> +</table> +</div> +</td> +</tr> +</table> +<h2><a name="ToC1">About the module</a></h2> +<ul> +<p> +<li><a name="ToC2"></a> + <a name="history"></a> + <strong id="faq"> +What is the history of mod_ssl? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#history"><b>L</b></a>] + <p> + The mod_ssl v1 package was initially created in April 1998 by <a + href="mailto:rse@engelschall.com">Ralf S. Engelschall</a> via porting <a + href="mailto:ben@algroup.co.uk">Ben Laurie</a>'s <a + href="http://www.apache-ssl.org/">Apache-SSL</a> 1.17 source patches for + Apache 1.2.6 to Apache 1.3b6. Because of conflicts with Ben + Laurie's development cycle it then was re-assembled from scratch for + Apache 1.3.0 by merging the old mod_ssl 1.x with the newer Apache-SSL + 1.18. From this point on mod_ssl lived its own life as mod_ssl v2. The + first publically released version was mod_ssl 2.0.0 from August 10th, + 1998. As of this writing (August 1999) the current mod_ssl version is 2.4.0. + <p> + After one year of very active development with over 1000 working hours and + over 40 releases mod_ssl reached its current state. The result is an + already very clean source base implementing a very rich functionality. + The code size increased by a factor of 4 to currently a total of over + 10.000 lines of ANSI C consisting of approx. 70% code and 30% code + documentation. From the original Apache-SSL code currently approx. 5% is + remaining only. +<p> +<li><a name="ToC3"></a> + <a name="apssl-diff"></a> + <strong id="faq"> +What are the functional differences between mod_ssl and Apache-SSL, from where +it is originally derived? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#apssl-diff"><b>L</b></a>] + <p> + This neither can be answered in short (there were too many code changes) + nor can be answered at all by the author (there would immediately be flame + wars with no reasonable results at the end). But as you easily can guess + from the 5% of remaining Apache-SSL code, a lot of differences exists, + although user-visible backward compatibility exists for most things. + <p> + When you really want a detailed comparison you have to read the entries in + the large <code>CHANGES</code> file that is in the mod_ssl + distribution. Usually this is much too hard-core. So I recommend you to + either believe in the opinion and recommendations of other users (the + simplest approach) or do a comparison yourself (the most reasonable + approach). For the latter, grab distributions of mod_ssl (from <a + href="http://www.modssl.org/">http://www.modssl.org</a>) and Apache-SSL + (from <a href="http://www.apache-ssl.org/">http://www.apache-ssl.org</a>), + install both packages, read their documentation and try them out yourself. + Then choose the one which pleases you most. + <p> + A few final hints to help direct your comparison: quality of documentation + ("can you easily find answers and are they sufficient?"), quality of + source code ("is the source code reviewable so you can make sure there + aren't any trapdoors or inherent security risks because of bad programming + style?"), easy and clean installation ("can the SSL functionality easily + added to an Apache source tree without manual editing or patching?"), + clean integration into Apache ("is the SSL functionality encapsulated and + cleanly separated from the remaining Apache functionality?"), support for + Dynamic Shared Object (DSO) facility ("can the SSL functionality built as + a separate DSO for maximum flexibility?"), Win32 port ("is the SSL + functionality available also under the Win32 platform?"), amount and + quality of functionality ("is the provided SSL functionality and control + possibilities sufficient for your situation?"), quality of problem tracing + ("is it possible for you to easily trace down the problems via logfiles, + etc?"), etc. pp. +<p> +<li><a name="ToC4"></a> + <a name="apssl-diff"></a> + <strong id="faq"> +What are the major differences between mod_ssl and +the commercial alternatives like Raven or Stronghold? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#apssl-diff"><b>L</b></a>] + <p> + In the past (until September 20th, 2000) the major difference was + the RSA license which one received (very cheaply in contrast to + a direct licensing from RSA DSI) with the commercial Apache SSL + products. On the other hand, one needed this license only in the US, + of course. So for non-US citizens this point was useless. But now + even for US citizens the situations changed because the RSA patent + expired on September 20th, 2000 and RSA DSI also placed the RSA + algorithm explicitly into the public domain. + <p> + Second, there is the point that one has guaranteed support from + the commercial vendors. On the other hand, if you monitored the + Open Source quality of mod_ssl and the support activities + found on <a href="mailto:modssl-users@modssl.org"> + <code>modssl-users@modssl.org</code></a>, you could ask yourself + whether you are really convinced that you can get better support + from a commercial vendor. + <p> + Third, people often think they would receive perhaps at least a + better technical SSL solution than mod_ssl from the commercial + vendors. But this is not really true, because all commercial + alternatives (Raven 1.4.x, Stronghold 3.x, RedHat SWS 2.x, etc.) + <i>are</i> actually based on mod_ssl and OpenSSL. The reason for + this common misunderstanding is mainly because some vendors make no + attempt to make it reasonably clear that their product is actually + mod_ssl based. So, do not think, just because the commercial + alternatives are usually more expensive, that you are also receiving + an alternative <i>technical</i> SSL solution. This is usually not + the case. Actually the vendor versions of Apache, mod_ssl and OpenSSL + often stay behind the latest free versions and perhaps this way still do not + include important bug and security fixes. On the other hand, + it sometimes occurs that a vendor version includes useful changes + which are not available through the official freely available + packages. But most vendors play fair and contribute back those + changes to the free software world, of course. + <p> + So, in short: There are lots of commercial versions of the popular + Apache+mod_ssl+OpenSSL server combination available. Every user + should decide carefully whether they really need to buy a commercial + version or whether it would not be sufficient to directly use the + free and official versions of the Apache, mod_ssl and OpenSSL + packages. +<p> +<li><a name="ToC5"></a> + <a name="what-version"></a> + <strong id="faq"> +How do I know which mod_ssl version is for which Apache version? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#what-version"><b>L</b></a>] + <p> + That's trivial: mod_ssl uses version strings of the syntax + <em><mod_ssl-version></em>-<em><apache-version></em>, for + instance <code>2.4.0-1.3.9</code>. This directly indicates that it's + mod_ssl version 2.4.0 for Apache version 1.3.9. And this also means you + <em>only</em> can apply this mod_ssl version to exactly this Apache + version (unless you use the <code>--force</code> option to mod_ssl's + <code>configure</code> command ;-). +<p> +<li><a name="ToC6"></a> + <a name="y2k"></a> + <strong id="faq"> +Is mod_ssl Year 2000 compliant? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#y2k"><b>L</b></a>] + <p> + Yes, mod_ssl is Year 2000 compliant. + <p> + Because first mod_ssl internally never stores years as two digits. + Instead it always uses the ANSI C & POSIX numerical data type + <code>time_t</code> type, which on almost all Unix platforms at the moment + is a <code>signed long</code> (usually 32-bits) representing seconds since + epoch of January 1st, 1970, 00:00 UTC. This signed value overflows in + early January 2038 and not in the year 2000. Second, date and time + presentations (for instance the variable ``<code>%{TIME_YEAR}</code>'') + are done with full year value instead of abbreviating to two digits. + <p> + Additionally according to a <a + href="http://www.apache.org/docs/misc/FAQ.html#year2000">Year 2000 + statement</a> from the Apache Group, the Apache webserver is Year 2000 + compliant, too. But whether OpenSSL or the underlaying Operating System + (either a Unix or Win32 platform) is Year 2000 compliant is a different + question which cannot be answered here. +<p> +<li><a name="ToC7"></a> + <a name="wassenaar"></a> + <strong id="faq"> +What about mod_ssl and the Wassenaar Arrangement? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#wassenaar"><b>L</b></a>] + <p> + First, let us explain what <i>Wassenaar</i> and it's <i>Arrangement on + Export Controls for Conventional Arms and Dual-Use Goods and + Technologies</i> is: This is a international regime, established 1995, to + control trade in conventional arms and dual-use goods and technology. It + replaced the previous <i>CoCom</i> regime. 33 countries are signatories: + Argentina, Australia, Austria, Belgium, Bulgaria, Canada, Czech Republic, + Denmark, Finland, France, Germany, Greece, Hungary, Ireland, Italy, Japan, + Luxembourg, Netherlands, New Zealand, Norway, Poland, Portugal, Republic + of Korea, Romania, Russian Federation, Slovak Republic, Spain, Sweden, + Switzerland, Turkey, Ukraine, United Kingdom and United States. For more + details look at <a + href="http://www.wassenaar.org/">http://www.wassenaar.org/</a>. + <p> + In short: The aim of the Wassenaar Arrangement is to prevent the build up + of military capabilities that threaten regional and international security + and stability. The Wassenaar Arrangement controls the export of + cryptography as a dual-use good, i.e., one that has both military and + civilian applications. However, the Wassenaar Arrangement also provides an + exemption from export controls for mass-market software and free software. + <p> + In the current Wassenaar ``<i>List of Dual Use Goods and Technologies And + Munitions</i>'', under ``<i>GENERAL SOFTWARE NOTE</i>'' (GSN) it says + ``<i>The Lists do not control "software" which is either: 1. [...] 2. "in + the public domain".</i>'' And under ``<i>DEFINITIONS OF TERMS USED IN + THESE LISTS</i>'' one can find the definition: ``<i>"In the public + domain": This means "technology" or "software" which has been made + available without restrictions upon its further dissemination. N.B. + Copyright restrictions do not remove "technology" or "software" from being + "in the public domain".</i>'' + <p> + So, both mod_ssl and OpenSSL are ``in the public domain'' for the purposes + of the Wassenaar Agreement and its ``<i>List of Dual Use Goods and + Technologies And Munitions List</i>''. + <p> + Additionally the Wassenaar Agreement itself has no direct consequence for + exporting cryptography software. What is actually allowed or forbidden to + be exported from the countries has still to be defined in the local laws + of each country. And at least according to official press releases from + the German BMWi (see <a + href="http://www.bmwi.de/presse/1998/1208prm2.html">here</a>) and the + Switzerland Bawi (see <a href="http://jya.com/wass-ch.htm">here</a>) there + will be no forthcoming export restriction for free cryptography software + for their countries. Remember that mod_ssl is created in Germany and + distributed from Switzerland. + <p> + So, mod_ssl and OpenSSL are not affected by the Wassenaar Agreement. +</ul> +<p> +<br> +<h2><a name="ToC8">About Installation</a></h2> +<ul> +<p> +<li><a name="ToC9"></a> + <a name="core-dbm"></a> + <strong id="faq"> +When I access my website the first time via HTTPS I get a core dump? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#core-dbm"><b>L</b></a>] + <p> + There can be a lot of reasons why a core dump can occur, of course. + Ranging from buggy third-party modules, over buggy vendor libraries up to + a buggy mod_ssl version. But the above situation is often caused by old or + broken vendor DBM libraries. To solve it either build mod_ssl with the + built-in SDBM library (specify <tt>--enable-rule=SSL_SDBM</tt> at the + APACI command line) or switch from ``<tt>SSLSessionCache dbm:</tt>'' to the + newer ``<tt>SSLSessionCache shm:</tt>'' variant (after you have rebuilt + Apache with MM, of course). +<p> +<li><a name="ToC10"></a> + <a name="core-php3"></a> + <strong id="faq"> +My Apache dumps core when I add both mod_ssl and PHP3? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#core-php3"><b>L</b></a>] + <p> + Make sure you add mod_ssl to the Apache source tree first and then do a + fresh configuration and installation of PHP3. For SSL support EAPI patches + are required which have to change internal Apache structures. PHP3 needs + to know about these in order to work correctly. Always make sure that + <tt>-DEAPI</tt> is contained in the compiler flags when PHP3 is build. +<p> +<li><a name="ToC11"></a> + <a name="dso-sym"></a> + <strong id="faq"> +When I startup Apache I get errors about undefined symbols like ap_global_ctx? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#dso-sym"><b>L</b></a>] + <p> + This actually means you installed mod_ssl as a DSO, but without rebuilding + Apache with EAPI. Because EAPI is a requirement for mod_ssl, you need an + extra patched Apache (containing the EAPI patches) and you have to build + this Apache with EAPI enabled (explicitly specify + <tt>--enable-rule=EAPI</tt> at the APACI command line). +<p> +<li><a name="ToC12"></a> + <a name="mutex-perm"></a> + <strong id="faq"> +When I startup Apache I get permission errors related to SSLMutex? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#mutex-perm"><b>L</b></a>] + <p> + When you receive entries like ``<code>mod_ssl: Child could not open + SSLMutex lockfile /opt/apache/logs/ssl_mutex.18332 (System error follows) + [...] System: Permission denied (errno: 13)</code>'' this is usually + caused by to restrictive permissions on the <i>parent</i> directories. + Make sure that all parent directories (here <code>/opt</code>, + <code>/opt/apache</code> and <code>/opt/apache/logs</code>) have the x-bit + set at least for the UID under which Apache's children are running (see + the <code>User</code> directive of Apache). +<p> +<li><a name="ToC13"></a> + <a name="mm"></a> + <strong id="faq"> +When I use the MM library and the shared memory cache each process grows +1.5MB according to `top' although I specified 512000 as the cache size? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#mm"><b>L</b></a>] + <p> + The additional 1MB are caused by the global shared memory pool EAPI + allocates for all modules and which is not used by mod_ssl for + various reasons. So the actually allocated shared memory is always + 1MB more than what you specify on <code>SSLSessionCache</code>. + But don't be confused by the display of `top': although is + indicates that <i>each</i> process grow, this is not reality, of + course. Instead the additional memory consumption is shared by + all processes, i.e. the 1.5MB are allocated only once per Apache + instance and not once per Apache server process. +<p> +<li><a name="ToC14"></a> + <a name="mmpath"></a> + <strong id="faq"> +Apache creates files in a directory declared by the internal +EAPI_MM_CORE_PATH define. Is there a way to override the path using a +configuration directive? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#mmpath"><b>L</b></a>] + <p> + No, there is not configuration directive, because for technical + bootstrapping reasons, a directive not possible at all. Instead + use ``<code>CFLAGS='-DEAPI_MM_CORE_PATH="/path/to/wherever/"' + ./configure ...</code>'' when building Apache or use option + <b>-d</b> when starting <code>httpd</code>. +<p> +<li><a name="ToC15"></a> + <a name="entropy"></a> + <strong id="faq"> +When I fire up the server, mod_ssl stops with the error +"Failed to generate temporary 512 bit RSA private key", why? +And a "PRNG not seeded" error occurs if I try "make certificate". +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#entropy"><b>L</b></a>] + <p> + Cryptographic software needs a source of unpredictable data + to work correctly. Many open source operating systems provide + a "randomness device" that serves this purpose (usually named + <code>/dev/random</code>). On other systems, applications have to + seed the OpenSSL Pseudo Random Number Generator (PRNG) manually with + appropriate data before generating keys or performing public key + encryption. As of version 0.9.5, the OpenSSL functions that need + randomness report an error if the PRNG has not been seeded with + at least 128 bits of randomness. So mod_ssl has to provide enough + entropy to the PRNG to work correctly. For this one has to use the + <code>SSLRandomSeed</code> directives (to solve the run-time problem) + and create a <code>$HOME/.rnd</code> file to make sure enough + entropy is available also for the "<code>make certificate</code>" + step (in case the "<code>make certificate</code>" procedure is not + able to gather enough entropy theirself by searching for system + files). +</ul> +<p> +<br> +<h2><a name="ToC16">About Configuration</a></h2> +<ul> +<p> +<li><a name="ToC17"></a> + <a name="https-parallel"></a> + <strong id="faq"> +Is it possible to provide HTTP and HTTPS with a single server?</strong> +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#https-parallel"><b>L</b></a>] + <p> + Yes, HTTP and HTTPS use different server ports, so there is no direct + conflict between them. Either run two separate server instances (one binds + to port 80, the other to port 443) or even use Apache's elegant virtual + hosting facility where you can easily create two virtual servers which + Apache dispatches: one responding to port 80 and speaking HTTP and one + responding to port 443 speaking HTTPS. +<p> +<li><a name="ToC18"></a> + <a name="https-port"></a> + <strong id="faq"> +I know that HTTP is on port 80, but where is HTTPS? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#https-port"><b>L</b></a>] + <p> + You can run HTTPS on any port, but the standards specify port 443, which + is where any HTTPS compliant browser will look by default. You can force + your browser to look on a different port by specifying it in the URL like + this (for port 666): <code>https://secure.server.dom:666/</code> +<p> +<li><a name="ToC19"></a> + <a name="https-test"></a> + <strong id="faq"> +How can I speak HTTPS manually for testing purposes? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#https-test"><b>L</b></a>] + <p> + While you usually just use + <p> + <code><b>$ telnet localhost 80</b></code><br> + <code><b>GET / HTTP/1.0</b></code> + <p> + for simple testing the HTTP protocol of Apache, it's not such easy for + HTTPS because of the SSL protocol between TCP and HTTP. But with the + help of OpenSSL's <code>s_client</code> command you can do a similar + check even for HTTPS: + <p> + <code><b>$ openssl s_client -connect localhost:443 -state -debug</b></code><br> + <code><b>GET / HTTP/1.0</b></code> + <p> + Before the actual HTTP response you receive detailed information about the + SSL handshake. For a more general command line client which directly + understands both the HTTP and HTTPS scheme, can perform GET and POST + methods, can use a proxy, supports byte ranges, etc. you should have a + look at nifty <a href="http://curl.haxx.nu/">cURL</a> + tool. With it you can directly check if your Apache is running fine on + Port 80 and 443 as following: + <p> + <code><b>$ curl http://localhost/</b></code><br> + <code><b>$ curl https://localhost/</b></code><br> +<p> +<li><a name="ToC20"></a> + <a name="hang"></a> + <strong id="faq"> +Why does the connection hang when I connect to my SSL-aware Apache server? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#hang"><b>L</b></a>] + <p> + Because you connected with HTTP to the HTTPS port, i.e. you used an URL of + the form ``<code>http://</code>'' instead of ``<code>https://</code>''. + This also happens the other way round when you connect via HTTPS to a HTTP + port, i.e. when you try to use ``<code>https://</code>'' on a server that + doesn't support SSL (on this port). Make sure you are connecting to a + virtual server that supports SSL, which is probably the IP associated with + your hostname, not localhost (127.0.0.1). +<p> +<li><a name="ToC21"></a> + <a name="hang"></a> + <strong id="faq"> +Why do I get ``Connection Refused'' messages when trying to access my freshly +installed Apache+mod_ssl server via HTTPS? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#hang"><b>L</b></a>] + <p> + There can be various reasons. Some of the common mistakes is that people + start Apache with just ``<tt>apachectl start</tt>'' (or + ``<tt>httpd</tt>'') instead of ``<tt>apachectl startssl</tt>'' (or + ``<tt>httpd -DSSL</tt>''. Or you're configuration is not correct. At + least make sure that your ``<tt>Listen</tt>'' directives match your + ``<tt><VirtualHost></tt>'' directives. And if all fails, please do + yourself a favor and start over with the default configuration mod_ssl + provides you. +<p> +<li><a name="ToC22"></a> + <a name="env-vars"></a> + <strong id="faq"> +In my CGI programs and SSI scripts the various documented +<code>SSL_XXX</code> variables do not exists. Why? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#env-vars"><b>L</b></a>] + <p> + Just make sure you have ``<code>SSLOptions +StdEnvVars</code>'' + enabled for the context of your CGI/SSI requests. +<p> +<li><a name="ToC23"></a> + <a name="relative-links"></a> + <strong id="faq"> +How can I use relative hyperlinks to switch between HTTP and HTTPS? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#relative-links"><b>L</b></a>] + <p> + Usually you have to use fully-qualified hyperlinks because + you have to change the URL scheme. But with the help of some URL + manipulations through mod_rewrite you can achieve the same effect while + you still can use relative URLs: + <pre> + RewriteEngine on + RewriteRule ^/(.*):SSL$ https://%{SERVER_NAME}/$1 [R,L] + RewriteRule ^/(.*):NOSSL$ http://%{SERVER_NAME}/$1 [R,L] + </pre> + This rewrite ruleset lets you use hyperlinks of the form + <pre> + <a href="document.html:SSL"> + </pre> +</ul> +<p> +<br> +<h2><a name="ToC24">About Certificates</a></h2> +<ul> +<p> +<li><a name="ToC25"></a> + <a name="what-is"></a> + <strong id="faq"> +What are RSA Private Keys, CSRs and Certificates?</strong> +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#what-is"><b>L</b></a>] + <p> + The RSA private key file is a digital file that you can use to decrypt + messages sent to you. It has a public component which you distribute (via + your Certificate file) which allows people to encrypt those messages to + you. A Certificate Signing Request (CSR) is a digital file which contains + your public key and your name. You send the CSR to a Certifying Authority + (CA) to be converted into a real Certificate. A Certificate contains your + RSA public key, your name, the name of the CA, and is digitally signed by + your CA. Browsers that know the CA can verify the signature on that + Certificate, thereby obtaining your RSA public key. That enables them to + send messages which only you can decrypt. + See the <a href="ssl_intro.html">Introduction</a> chapter for a general + description of the SSL protocol. +<p> +<li><a name="ToC26"></a> + <a name="startup"></a> + <strong id="faq"> +Seems like there is a difference on startup between the original Apache and an SSL-aware Apache? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#startup"><b>L</b></a>] + <p> + Yes, in general, starting Apache with a built-in mod_ssl is just like + starting an unencumbered Apache, except for the fact that when you have a + pass phrase on your SSL private key file. Then a startup dialog pops up + asking you to enter the pass phrase. + <p> + To type in the pass phrase manually when starting the server can be + problematic, for instance when starting the server from the system boot + scripts. As an alternative to this situation you can follow the steps + below under ``How can I get rid of the pass-phrase dialog at Apache + startup time?''. +<p> +<li><a name="ToC27"></a> + <a name="cert-dummy"></a> + <strong id="faq"> +How can I create a dummy SSL server Certificate for testing purposes? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#cert-dummy"><b>L</b></a>] + <p> + A Certificate does not have to be signed by a public CA. You can use your + private key to sign the Certificate which contains your public key. You + can install this Certificate into your server, and people using Netscape + Navigator (not MSIE) will be able to connect after clicking OK to a + warning dialogue. You can get MSIE to work, and your customers can + eliminate the dialogue, by installing that Certificate manually into their + browsers. + <p> + Just use the ``<code>make certificate</code>'' command at the top-level + directory of the Apache source tree right before installing Apache via + ``<code>make install</code>''. This creates a self-signed SSL Certificate + which expires after 30 days and isn't encrypted (which means you don't + need to enter a pass-phrase at Apache startup time). + <p> + BUT REMEMBER: YOU REALLY HAVE TO CREATE A REAL CERTIFICATE FOR THE LONG + RUN! HOW THIS IS DONE IS DESCRIBED IN THE NEXT ANSWER. +<p> +<li><a name="ToC28"></a> + <a name="cert-real"></a> + <strong id="faq"> +Ok, I've got my server installed and want to create a real SSL +server Certificate for it. How do I do it? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#cert-real"><b>L</b></a>] + <p> + Here is a step-by-step description: + <p> + <ol> + <li>Make sure OpenSSL is really installed and in your <code>PATH</code>. + But some commands even work ok when you just run the + ``<code>openssl</code>'' program from within the OpenSSL source tree as + ``<code>./apps/openssl</code>''. + <p> + <li>Create a RSA private key for your Apache server + (will be Triple-DES encrypted and PEM formatted): + <p> + <code><strong>$ openssl genrsa -des3 -out server.key 1024</strong></code> + <p> + Please backup this <code>server.key</code> file and remember the + pass-phrase you had to enter at a secure location. + You can see the details of this RSA private key via the command: + <p> + <code><strong>$ openssl rsa -noout -text -in server.key</strong></code> + <p> + And you could create a decrypted PEM version (not recommended) + of this RSA private key via: + <p> + <code><strong>$ openssl rsa -in server.key -out server.key.unsecure</strong></code> + <p> + <li>Create a Certificate Signing Request (CSR) with the server RSA private + key (output will be PEM formatted): + <p> + <code><strong>$ openssl req -new -key server.key -out server.csr</strong></code> + <p> + Make sure you enter the FQDN ("Fully Qualified Domain Name") of the + server when OpenSSL prompts you for the "CommonName", i.e. when you + generate a CSR for a website which will be later accessed via + <code>https://www.foo.dom/</code>, enter "www.foo.dom" here. + You can see the details of this CSR via the command + <p> + <code><strong>$ openssl req -noout -text -in server.csr</strong></code> + <p> + <li>You now have to send this Certificate Signing Request (CSR) to + a Certifying Authority (CA) for signing. The result is then a real + Certificate which can be used for Apache. Here you have two options: + First you can let the CSR sign by a commercial CA like Verisign or + Thawte. Then you usually have to post the CSR into a web form, pay for + the signing and await the signed Certificate you then can store into a + server.crt file. For more information about commercial CAs have a look + at the following locations: + <p> + <ul> + <li> Verisign<br> + <a href="http://digitalid.verisign.com/server/apacheNotice.htm"> + http://digitalid.verisign.com/server/apacheNotice.htm + </a> + <li> Thawte Consulting<br> + <a href="http://www.thawte.com/certs/server/request.html"> + http://www.thawte.com/certs/server/request.html + </a> + <li> CertiSign Certificadora Digital Ltda.<br> + <a href="http://www.certisign.com.br"> + http://www.certisign.com.br + </a> + <li> IKS GmbH<br> + <a href="http://www.iks-jena.de/produkte/ca/"> + http://www.iks-jena.de/produkte/ca/ + </a> + <li> Uptime Commerce Ltd.<br> + <a href="http://www.uptimecommerce.com"> + http://www.uptimecommerce.com + </a> + <li> BelSign NV/SA<br> + <a href="http://www.belsign.be"> + http://www.belsign.be + </a> + </ul> + <p> + Second you can use your own CA and now have to sign the CSR yourself by + this CA. Read the next answer in this FAQ on how to sign a CSR with + your CA yourself. + You can see the details of the received Certificate via the command: + <p> + <code><strong>$ openssl x509 -noout -text -in server.crt</strong></code> + <p> + <li>Now you have two files: <code>server.key</code> and + <code>server.crt</code>. These now can be used as following inside your + Apache's <code>httpd.conf</code> file: + <pre> + SSLCertificateFile /path/to/this/server.crt + SSLCertificateKeyFile /path/to/this/server.key + </pre> + The <code>server.csr</code> file is no longer needed. + </ol> +<p> +<li><a name="ToC29"></a> + <a name="cert-ownca"></a> + <strong id="faq"> +How can I create and use my own Certificate Authority (CA)? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#cert-ownca"><b>L</b></a>] + <p> + The short answer is to use the <code>CA.sh</code> or <code>CA.pl</code> + script provided by OpenSSL. The long and manual answer is this: + <p> + <ol> + <li>Create a RSA private key for your CA + (will be Triple-DES encrypted and PEM formatted): + <p> + <code><strong>$ openssl genrsa -des3 -out ca.key 1024</strong></code> + <p> + Please backup this <code>ca.key</code> file and remember the + pass-phrase you currently entered at a secure location. + You can see the details of this RSA private key via the command + <p> + <code><strong>$ openssl rsa -noout -text -in ca.key</strong></code> + <p> + And you can create a decrypted PEM version (not recommended) of this + private key via: + <p> + <code><strong>$ openssl rsa -in ca.key -out ca.key.unsecure</strong></code> + <p> + <li>Create a self-signed CA Certificate (X509 structure) + with the RSA key of the CA (output will be PEM formatted): + <p> + <code><strong>$ openssl req -new -x509 -days 365 -key ca.key -out ca.crt</strong></code> + <p> + You can see the details of this Certificate via the command: + <p> + <code><strong>$ openssl x509 -noout -text -in ca.crt</strong></code> + <p> + <li>Prepare a script for signing which is needed because + the ``<code>openssl ca</code>'' command has some strange requirements + and the default OpenSSL config doesn't allow one easily to use + ``<code>openssl ca</code>'' directly. So a script named + <code>sign.sh</code> is distributed with the mod_ssl distribution + (subdir <code>pkg.contrib/</code>). Use this script for signing. + <p> + <li>Now you can use this CA to sign server CSR's in order to create real + SSL Certificates for use inside an Apache webserver (assuming + you already have a <code>server.csr</code> at hand): + <p> + <code><strong>$ ./sign.sh server.csr</strong></code> + <p> + This signs the server CSR and results in a <code>server.crt</code> file. + </ol> +<p> +<li><a name="ToC30"></a> + <a name="change-passphrase"></a> + <strong id="faq"> +How can I change the pass-phrase on my private key file? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#change-passphrase"><b>L</b></a>] + <p> + You simply have to read it with the old pass-phrase and write it again + by specifying the new pass-phrase. You can accomplish this with the following + commands: + <p> + <code><strong>$ openssl rsa -des3 -in server.key -out server.key.new</strong></code><br> + <code><strong>$ mv server.key.new server.key</strong></code><br> + <p> + Here you're asked two times for a PEM pass-phrase. At the first + prompt enter the old pass-phrase and at the second prompt + enter the new pass-phrase. +<p> +<li><a name="ToC31"></a> + <a name="remove-passphrase"></a> + <strong id="faq"> +How can I get rid of the pass-phrase dialog at Apache startup time? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#remove-passphrase"><b>L</b></a>] + <p> + The reason why this dialog pops up at startup and every re-start + is that the RSA private key inside your server.key file is stored in + encrypted format for security reasons. The pass-phrase is needed to be + able to read and parse this file. When you can be sure that your server is + secure enough you perform two steps: + <p> + <ol> + <li>Remove the encryption from the RSA private key (while + preserving the original file): + <p> + <code><strong>$ cp server.key server.key.org</strong></code><br> + <code><strong>$ openssl rsa -in server.key.org -out server.key</strong></code> + <p> + <li>Make sure the server.key file is now only readable by root: + <p> + <code><strong>$ chmod 400 server.key</strong></code> + </ol> + <p> + Now <code>server.key</code> will contain an unencrypted copy of the key. + If you point your server at this file it will not prompt you for a + pass-phrase. HOWEVER, if anyone gets this key they will be able to + impersonate you on the net. PLEASE make sure that the permissions on that + file are really such that only root or the web server user can read it + (preferably get your web server to start as root but run as another + server, and have the key readable only by root). + <p> + As an alternative approach you can use the ``<code>SSLPassPhraseDialog + exec:/path/to/program</code>'' facility. But keep in mind that this is + neither more nor less secure, of course. +<p> +<li><a name="ToC32"></a> + <a name="verify-key"></a> + <strong id="faq"> +How do I verify that a private key matches its Certificate? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#verify-key"><b>L</b></a>] + <p> + The private key contains a series of numbers. Two of those numbers form + the "public key", the others are part of your "private key". The "public + key" bits are also embedded in your Certificate (we get them from your + CSR). To check that the public key in your cert matches the public + portion of your private key, you need to view the cert and the key and + compare the numbers. To view the Certificate and the key run the + commands: + <p> + <code><strong>$ openssl x509 -noout -text -in server.crt</strong></code><br> + <code><strong>$ openssl rsa -noout -text -in server.key</strong></code> + <p> + The `modulus' and the `public exponent' portions in the key and the + Certificate must match. But since the public exponent is usually 65537 + and it's bothering comparing long modulus you can use the following + approach: + <p> + <code><strong>$ openssl x509 -noout -modulus -in server.crt | openssl md5</strong></code><br> + <code><strong>$ openssl rsa -noout -modulus -in server.key | openssl md5</strong></code> + <p> + And then compare these really shorter numbers. With overwhelming + probability they will differ if the keys are different. BTW, if I want to + check to which key or certificate a particular CSR belongs you can compute + <p> + <code><strong>$ openssl req -noout -modulus -in server.csr | openssl md5</strong></code> +<p> +<li><a name="ToC33"></a> + <a name="keysize1"></a> + <strong id="faq"> +What does it mean when my connections fail with an "alert bad certificate" +error? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#keysize1"><b>L</b></a>] + <p> + Usually when you see errors like ``<tt>OpenSSL: error:14094412: SSL + routines:SSL3_READ_BYTES:sslv3 alert bad certificate</tt>'' in the SSL + logfile, this means that the browser was unable to handle the server + certificate/private-key which perhaps contain a RSA-key not equal to 1024 + bits. For instance Netscape Navigator 3.x is one of those browsers. +<p> +<li><a name="ToC34"></a> + <a name="keysize2"></a> + <strong id="faq"> +Why does my 2048-bit private key not work? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#keysize2"><b>L</b></a>] + <p> + The private key sizes for SSL must be either 512 or 1024 for compatibility + with certain web browsers. A keysize of 1024 bits is recommended because + keys larger than 1024 bits are incompatible with some versions of Netscape + Navigator and Microsoft Internet Explorer, and with other browsers that + use RSA's BSAFE cryptography toolkit. +<p> +<li><a name="ToC35"></a> + <a name="hash-symlinks"></a> + <strong id="faq"> +Why is client authentication broken after upgrading from +SSLeay version 0.8 to 0.9? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#hash-symlinks"><b>L</b></a>] + <p> + The CA certificates under the path you configured with + <code>SSLCACertificatePath</code> are found by SSLeay through hash + symlinks. These hash values are generated by the `<code>openssl x509 -noout + -hash</code>' command. But the algorithm used to calculate the hash for a + certificate has changed between SSLeay 0.8 and 0.9. So you have to remove + all old hash symlinks and re-create new ones after upgrading. Use the + <code>Makefile</code> mod_ssl placed into this directory. +<p> +<li><a name="ToC36"></a> + <a name="pem-to-der"></a> + <strong id="faq"> +How can I convert a certificate from PEM to DER format? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#pem-to-der"><b>L</b></a>] + <p> + The default certificate format for SSLeay/OpenSSL is PEM, which actually + is Base64 encoded DER with header and footer lines. For some applications + (e.g. Microsoft Internet Explorer) you need the certificate in plain DER + format. You can convert a PEM file <code>cert.pem</code> into the + corresponding DER file <code>cert.der</code> with the following command: + <code><strong>$ openssl x509 -in cert.pem -out cert.der -outform DER</strong></code> +<p> +<li><a name="ToC37"></a> + <a name="verisign-getca"></a> + <strong id="faq"> +I try to install a Verisign certificate. Why can't I find neither the +<code>getca</code> nor <code>getverisign</code> programs Verisign mentions? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#verisign-getca"><b>L</b></a>] + <p> + This is because Verisign has never provided specific instructions + for Apache+mod_ssl. Rather they tell you what you should do + if you were using C2Net's Stronghold (a commercial Apache + based server with SSL support). The only thing you have to do + is to save the certificate into a file and give the name of + that file to the <code>SSLCertificateFile</code> directive. + Remember that you need to give the key file in as well (see + <code>SSLCertificateKeyFile</code> directive). For a better + CA-related overview on SSL certificate fiddling you can look at <a + href="http://www.thawte.com/certs/server/keygen/mod_ssl.html"> + Thawte's mod_ssl instructions</a>. +<p> +<li><a name="ToC38"></a> + <a name="gid"></a> + <strong id="faq"> +Can I use the Server Gated Cryptography (SGC) facility (aka Verisign Global +ID) also with mod_ssl? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#gid"><b>L</b></a>] + <p> + Yes, mod_ssl since version 2.1 supports the SGC facility. You don't have + to configure anything special for this, just use a Global ID as your + server certificate. The <i>step up</i> of the clients are then + automatically handled by mod_ssl under run-time. For details please read + the <tt>README.GlobalID</tt> document in the mod_ssl distribution. +<p> +<li><a name="ToC39"></a> + <a name="gid"></a> + <strong id="faq"> +After I have installed my new Verisign Global ID server certificate, the +browsers complain that they cannot verify the server certificate? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#gid"><b>L</b></a>] + <p> + That is because Verisign uses an intermediate CA certificate between + the root CA certificate (which is installed in the browsers) and + the server certificate (which you installed in the server). You + should have received this additional CA certificate from Verisign. + If not, complain to them. Then configure this certificate with the + <code>SSLCertificateChainFile</code> directive in the server. This + makes sure the intermediate CA certificate is send to the browser + and this way fills the gap in the certificate chain. +</ul> +<p> +<br> +<h2><a name="ToC40">About SSL Protocol</a></h2> +<ul> +<p> +<li><a name="ToC41"></a> + <a name="random-errors"></a> + <strong id="faq"> +Why do I get lots of random SSL protocol errors under heavy server load? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#random-errors"><b>L</b></a>] + <p> + There can be a number of reasons for this, but the main one + is problems with the SSL session Cache specified by the + <tt>SSLSessionCache</tt> directive. The DBM session cache is most + likely the source of the problem, so trying the SHM session cache or + no cache at all may help. +<p> +<li><a name="ToC42"></a> + <a name="load"></a> + <strong id="faq"> +Why has my webserver a higher load now that I run SSL there? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#load"><b>L</b></a>] + <p> + Because SSL uses strong cryptographic encryption and this needs a lot of + number crunching. And because when you request a webpage via HTTPS even + the images are transfered encrypted. So, when you have a lot of HTTPS + traffic the load increases. +<p> +<li><a name="ToC43"></a> + <a name="random"></a> + <strong id="faq"> +Often HTTPS connections to my server require up to 30 seconds for establishing +the connection, although sometimes it works faster? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#random"><b>L</b></a>] + <p> + Usually this is caused by using a <code>/dev/random</code> device for + <code>SSLRandomSeed</code> which is blocking in read(2) calls if not + enough entropy is available. Read more about this problem in the refernce + chapter under <code>SSLRandomSeed</code>. +<p> +<li><a name="ToC44"></a> + <a name="ciphers"></a> + <strong id="faq"> +What SSL Ciphers are supported by mod_ssl? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#ciphers"><b>L</b></a>] + <p> + Usually just all SSL ciphers which are supported by the + version of OpenSSL in use (can depend on the way you built + OpenSSL). Typically this at least includes the following: + <p> + <ul> + <li>RC4 with MD5 + <li>RC4 with MD5 (export version restricted to 40-bit key) + <li>RC2 with MD5 + <li>RC2 with MD5 (export version restricted to 40-bit key) + <li>IDEA with MD5 + <li>DES with MD5 + <li>Triple-DES with MD5 + </ul> + <p> + To determine the actual list of supported ciphers you can + run the following command: + <p> + <code><strong>$ openssl ciphers -v</strong></code><br> +<p> +<li><a name="ToC45"></a> + <a name="cipher-adh"></a> + <strong id="faq"> +I want to use Anonymous Diffie-Hellman (ADH) ciphers, but I always get ``no +shared cipher'' errors? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#cipher-adh"><b>L</b></a>] + <p> + In order to use Anonymous Diffie-Hellman (ADH) ciphers, it is not enough + to just put ``<code>ADH</code>'' into your <code>SSLCipherSuite</code>. + Additionally you have to build OpenSSL with + ``<code>-DSSL_ALLOW_ADH</code>''. Because per default OpenSSL does not + allow ADH ciphers for security reasons. So if you are actually enabling + these ciphers make sure you are informed about the side-effects. +<p> +<li><a name="ToC46"></a> + <a name="cipher-shared"></a> + <strong id="faq"> +I always just get a 'no shared ciphers' error if +I try to connect to my freshly installed server? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#cipher-shared"><b>L</b></a>] + <p> + Either you have messed up your <code>SSLCipherSuite</code> + directive (compare it with the pre-configured example in + <code>httpd.conf-dist</code>) or you have choosen the DSA/DH + algorithms instead of RSA under "<code>make certificate</code>" + and ignored or overseen the warnings. Because if you have choosen + DSA/DH, then your server no longer speaks RSA-based SSL ciphers + (at least not until you also configure an additional RSA-based + certificate/key pair). But current browsers like NS or IE only speak + RSA ciphers. The result is the "no shared ciphers" error. To fix + this, regenerate your server certificate/key pair and this time + choose the RSA algorithm. +<p> +<li><a name="ToC47"></a> + <a name="vhosts"></a> + <strong id="faq"> +Why can't I use SSL with name-based/non-IP-based virtual hosts? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#vhosts"><b>L</b></a>] + <p> + The reason is very technical. Actually it's some sort of a chicken and + egg problem: The SSL protocol layer stays below the HTTP protocol layer + and encapsulates HTTP. When an SSL connection (HTTPS) is established + Apache/mod_ssl has to negotiate the SSL protocol parameters with the + client. For this mod_ssl has to consult the configuration of the virtual + server (for instance it has to look for the cipher suite, the server + certificate, etc.). But in order to dispatch to the correct virtual server + Apache has to know the <code>Host</code> HTTP header field. For this the + HTTP request header has to be read. This cannot be done before the SSL + handshake is finished. But the information is already needed at the SSL + handshake phase. Bingo! +<p> +<li><a name="ToC48"></a> + <a name="lock-icon"></a> + <strong id="faq"> +When I use Basic Authentication over HTTPS the lock icon in Netscape browsers +still show the unlocked state when the dialog pops up. Does this mean the +username/password is still transmitted unencrypted? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#lock-icon"><b>L</b></a>] + <p> + No, the username/password is already transmitted encrypted. The icon in + Netscape browsers is just not really synchronized with the SSL/TLS layer + (it toggles to the locked state when the first part of the actual webpage + data is transferred which is not quite correct) and this way confuses + people. The Basic Authentication facility is part of the HTTP layer and + this layer is above the SSL/TLS layer in HTTPS. And before any HTTP data + communication takes place in HTTPS the SSL/TLS layer has already done the + handshake phase and switched to encrypted communication. So, don't get + confused by this icon. +<p> +<li><a name="ToC49"></a> + <a name="io-ie"></a> + <strong id="faq"> +When I connect via HTTPS to an Apache+mod_ssl+OpenSSL server with Microsoft Internet +Explorer (MSIE) I get various I/O errors. What is the reason? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#io-ie"><b>L</b></a>] + <p> + The first reason is that the SSL implementation in some MSIE versions has + some subtle bugs related to the HTTP keep-alive facility and the SSL close + notify alerts on socket connection close. Additionally the interaction + between SSL and HTTP/1.1 features are problematic with some MSIE versions, + too. You've to work-around these problems by forcing + Apache+mod_ssl+OpenSSL to not use HTTP/1.1, keep-alive connections or + sending the SSL close notify messages to MSIE clients. This can be done by + using the following directive in your SSL-aware virtual host section: + <pre> + SetEnvIf User-Agent ".*MSIE.*" \ + <b>nokeepalive ssl-unclean-shutdown \ + downgrade-1.0 force-response-1.0</b></pre> + Additionally it is known some MSIE versions have also problems + with particular ciphers. Unfortunately one cannot workaround these + bugs only for those MSIE particular clients, because the ciphers + are already used in the SSL handshake phase. So a MSIE-specific + <tt>SetEnvIf</tt> doesn't work to solve these problems. Instead one + has to do more drastic adjustments to the global parameters. But + before you decide to do this, make sure your clients really have + problems. If not, do not do this, because it affects all(!) your + clients, i.e., also your non-MSIE clients. + <p> + The next problem is that 56bit export versions of MSIE 5.x browsers have a + broken SSLv3 implementation which badly interacts with OpenSSL versions + greater than 0.9.4. You can either accept this and force your clients to + upgrade their browsers, or you downgrade to OpenSSL 0.9.4 (hmmm), or you + can decide to workaround it by accepting the drawback that your workaround + will horribly affect also other browsers: + <pre> + SSLProtocol all <b>-SSLv3</b></pre> + This completely disables the SSLv3 protocol and lets those browsers work. + But usually this is an even less acceptable workaround. A more reasonable + workaround is to address the problem more closely and disable only the + ciphers which cause trouble. + <pre> + SSLCipherSuite ALL:!ADH:<b>!EXPORT56</b>:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP</pre> + This also lets the broken MSIE versions work, but only removes the + newer 56bit TLS ciphers. + <p> + Another problem with MSIE 5.x clients is that they refuse to connect to + URLs of the form <tt>https://12.34.56.78/</tt> (IP-addresses are used + instead of the hostname), if the server is using the Server Gated + Cryptography (SGC) facility. This can only be avoided by using the fully + qualified domain name (FQDN) of the website in hyperlinks instead, because + MSIE 5.x has an error in the way it handles the SGC negotiation. + <p> + And finally there are versions of MSIE which seem to require that + an SSL session can be reused (a totally non standard-conforming + behaviour, of course). Connection with those MSIE versions only work + if a SSL session cache is used. So, as a work-around, make sure you + are using a session cache (see <tt>SSLSessionCache</tt> directive). +<p> +<li><a name="ToC50"></a> + <a name="io-ns"></a> + <strong id="faq"> +When I connect via HTTPS to an Apache+mod_ssl server with Netscape Navigator I +get I/O errors and the message "Netscape has encountered bad data from the +server" What's the reason? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#io-ns"><b>L</b></a>] + <p> + The problem usually is that you had created a new server certificate with + the same DN, but you had told your browser to accept forever the old + server certificate. Once you clear the entry in your browser for the old + certificate, everything usually will work fine. Netscape's SSL + implementation is correct, so when you encounter I/O errors with Netscape + Navigator it is most of the time caused by the configured certificates. +</ul> +<p> +<br> +<h2><a name="ToC51">About Support</a></h2> +<ul> +<p> +<li><a name="ToC52"></a> + <a name="resources"></a> + <strong id="faq"> +What information resources are available in case of mod_ssl problems? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#resources"><b>L</b></a>] + <p> +The following information resources are available. +In case of problems you should search here first. +<p> +<ol> +<li><em>Answers in the User Manual's F.A.Q. List (this)</em><br> + <a href="http://www.modssl.org/docs/2.8/ssl_faq.html"> + http://www.modssl.org/docs/2.8/ssl_faq.html</a><br> + First look inside the F.A.Q. (this text), perhaps your problem is such + popular that it was already answered a lot of times in the past. +<p> +<li><em>Postings from the modssl-users Support Mailing List</em> + <a href="http://www.modssl.org/support/"> + http://www.modssl.org/support/</a><br> + Second search for your problem in one of the existing archives of the + modssl-users mailing list. Perhaps your problem popped up at least once for + another user, too. +<p> +<li><em>Problem Reports in the Bug Database</em> + <a href="http://www.modssl.org/support/bugdb/"> + http://www.modssl.org/support/bugdb/</a><br> + Third look inside the mod_ssl Bug Database. Perhaps + someone else already has reported the problem. +</ol> +<p> +<li><a name="ToC53"></a> + <a name="contact"></a> + <strong id="faq"> +What support contacts are available in case of mod_ssl problems? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#contact"><b>L</b></a>] + <p> +The following lists all support possibilities for mod_ssl, in order of +preference, i.e. start in this order and do not pick the support possibility +you just like most, please. +<p> +<ol> +<li><em>Write a Problem Report into the Bug Database</em><br> + <a href="http://www.modssl.org/support/bugdb/"> + http://www.modssl.org/support/bugdb/</a><br> + This is the preferred way of submitting your problem report, because this + way it gets filed into the bug database (it cannot be lost) <em>and</em> + send to the modssl-users mailing list (others see the current problems and + learn from answers). +<p> +<li><em>Write a Problem Report to the modssl-users Support Mailing List</em><br> + <a href="mailto:modssl-users@modssl.org"> + modssl-users @ modssl.org</a><br> + This is the second way of submitting your problem report. You have to + subscribe to the list first, but then you can easily discuss your problem + with both the author and the whole mod_ssl user community. +<p> +<li><em>Write a Problem Report to the author</em><br> + <a href="mailto:rse@engelschall.com"> + rse @ engelschall.com</a><br> + This is the last way of submitting your problem report. Please avoid this + in your own interest because the author is really a very busy men. Your + mail will always be filed to one of his various mail-folders and is + usually not processed as fast as a posting on modssl-users. +</ol> +<p> +<li><a name="ToC54"></a> + <a name="report-details"></a> + <strong id="faq"> +What information and details I've to provide to +the author when writing a bug report? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#report-details"><b>L</b></a>] + <p> +You have to at least always provide the following information: +<p> +<ul> +<li><em>Apache, mod_ssl and OpenSSL version information</em><br> + The mod_ssl version you should really know. For instance, it's the version + number in the distribution tarball. The Apache version can be determined + by running ``<code>httpd -v</code>''. The OpenSSL version can be + determined by running ``<code>openssl version</code>''. Alternatively when + you have Lynx installed you can run the command ``<code>lynx -mime_header + http://localhost/ | grep Server</code>'' to determine all information in a + single step. +<p> +<li><em>The details on how you built and installed Apache+mod_ssl+OpenSSL</em><br> + For this you can provide a logfile of your terminal session which shows + the configuration and install steps. Alternatively you can at least + provide the author with the APACI `<code>configure</code>'' command line + you used (assuming you used APACI, of course). +<p> +<li><em>In case of core dumps please include a Backtrace</em><br> + In case your Apache+mod_ssl+OpenSSL should really dumped core please attach + a stack-frame ``backtrace'' (see the next question on how to get it). + Without this information the reason for your core dump cannot be found. + So you have to provide the backtrace, please. +<p> +<li><em>A detailed description of your problem</em><br> + Don't laugh, I'm totally serious. I already got a lot of problem reports + where the people not really said what's the actual problem is. So, in your + own interest (you want the problem be solved, don't you?) include as much + details as possible, please. But start with the essentials first, of + course. +</ul> +<p> +<li><a name="ToC55"></a> + <a name="core-dumped"></a> + <strong id="faq"> +I got a core dump, can you help me? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#core-dumped"><b>L</b></a>] + <p> + In general no, at least not unless you provide more details about the code + location where Apache dumped core. What is usually always required in + order to help you is a backtrace (see next question). Without this + information it is mostly impossible to find the problem and help you in + fixing it. +<p> +<li><a name="ToC56"></a> + <a name="report-backtrace"></a> + <strong id="faq"> +Ok, I got a core dump but how do I get a backtrace to find out the reason for it? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_faq.html#report-backtrace"><b>L</b></a>] + <p> +Follow the following steps: +<p> +<ol> +<li>Make sure you have debugging symbols available in at least + Apache and mod_ssl. On platforms where you use GCC/GDB you have to build + Apache+mod_ssl with ``<code>OPTIM="-g -ggdb3"</code>'' to achieve this. On + other platforms at least ``<code>OPTIM="-g"</code>'' is needed. +<p> +<li>Startup the server and try to produce the core-dump. For this you perhaps + want to use a directive like ``<code>CoreDumpDirectory /tmp</code>'' to + make sure that the core-dump file can be written. You then should get a + <code>/tmp/core</code> or <code>/tmp/httpd.core</code> file. When you + don't get this, try to run your server under an UID != 0 (root), because + most "current" kernels do not allow a process to dump core after it has + done a <code>setuid()</code> (unless it does an <code>exec()</code>) for + security reasons (there can be privileged information left over in + memory). Additionally you can run ``<code>/path/to/httpd -X</code>'' + manually to force Apache to not fork. +<p> +<li>Analyze the core-dump. For this run ``<code>gdb /path/to/httpd + /tmp/httpd.core</code>'' or a similar command has to run. In GDB you then + just have to enter the ``<code>bt</code>'' command and, voila, you get the + backtrace. For other debuggers consult your local debugger manual. Send + this backtrace to the author. +</ol> +</ul> + <p> + <br> + <table summary=""> + <tr> + <td> + <table width="600" border="0" summary=""> + <tr> + <td valign="top" align="left" width="250"> +<a href="ssl_howto.html" onmouseover="ro_imgOver('ro_img_prev_bot', 'previous page'); return true" onmouseout="ro_imgNormal('ro_img_prev_bot'); return true" onfocus="ro_imgOver('ro_img_prev_bot', 'previous page'); return true" onblur="ro_imgNormal('ro_img_prev_bot'); return true"><img name="ro_img_prev_bot" src="ssl_template.navbut-prev-n.gif" alt="previous page" width="70" height="18" border="0"></a><br><font color="#000000">HowTo</font> + </td> + <td valign="top" align="right" width="250"> +<a href="ssl_glossary.html" onmouseover="ro_imgOver('ro_img_next_bot', 'next page'); return true" onmouseout="ro_imgNormal('ro_img_next_bot'); return true" onfocus="ro_imgOver('ro_img_next_bot', 'next page'); return true" onblur="ro_imgNormal('ro_img_next_bot'); return true"><img name="ro_img_next_bot" src="ssl_template.navbut-next-n.gif" alt="next page" width="70" height="18" border="0"></a><br><font color="#000000">Glossary</font> + </td> + </tr> + </table> + </td> + </tr> + <tr> + <td><img src="ssl_template.imgdot-1x1-000000.gif" alt="" width="600" height="2" align="bottom" border="0"></td> + </tr> + <tr> + <td><table width="598" summary=""> + <tr> + <td align="left"><font face="Arial,Helvetica"> + <a href="http://www.modssl.org/">mod_ssl</a> 2.8, User Manual<br> + The Apache Interface to OpenSSL + </font> + </td> + <td align="right"><font face="Arial,Helvetica"> + Copyright © 1998-2001 + <a href="http://www.engelschall.com/">Ralf S. Engelschall</a><br> + All Rights Reserved<br> + </font> + </td> + </tr> + </table> + </td> + </tr> + </table> + </td> +</tr> +</table> +</div> +</body> +</html> diff --git a/docs/manual/ssl/ssl_howto.html b/docs/manual/ssl/ssl_howto.html new file mode 100644 index 0000000000..01ff7a99ac --- /dev/null +++ b/docs/manual/ssl/ssl_howto.html @@ -0,0 +1,929 @@ +<html> +<head> +<title>mod_ssl: HowTo</title> + +<!-- + Copyright (c) 1998-2001 Ralf S. Engelschall. All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code must retain the above + copyright notice, this list of conditions and the following + disclaimer. + + 2. Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials + provided with the distribution. + + 3. All advertising materials mentioning features or use of this + software must display the following acknowledgment: + "This product includes software developed by + Ralf S. Engelschall <rse@engelschall.com> for use in the + mod_ssl project (http://www.modssl.org/)." + + 4. The name "mod_ssl" must not be used to endorse or promote + products derived from this software without prior written + permission. + + 5. Redistributions of any form whatsoever must retain the + following acknowledgment: + "This product includes software developed by + Ralf S. Engelschall <rse@engelschall.com> for use in the + mod_ssl project (http://www.modssl.org/)." + + THIS SOFTWARE IS PROVIDED BY RALF S. ENGELSCHALL ``AS IS'' AND ANY + EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RALF S. ENGELSCHALL OR + HIS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT + NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; + LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED + OF THE POSSIBILITY OF SUCH DAMAGE. +--> +<style type="text/css"><!-- +A:link { + text-decoration: none; + color: #6666cc; +} +A:active { + text-decoration: none; + color: #6666cc; +} +A:visited { + text-decoration: none; + color: #6666cc; +} +#sf { + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +H1 { + font-weight: bold; + font-size: 24pt; + line-height: 24pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +H2 { + font-weight: bold; + font-size: 18pt; + line-height: 18pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +H3 { + font-weight: bold; + font-size: 14pt; + line-height: 14pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +H4 { + font-weight: bold; + font-size: 12pt; + line-height: 12pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +#H { +} +#D { + background-color: #f0f0f0; +} +#faq { + font-weight: bold; + font-size: 16pt; + line-height: 16pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +#howto { + font-weight: bold; + font-size: 16pt; + line-height: 16pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +#term { + font-weight: bold; + font-size: 16pt; + line-height: 16pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +--></style> +<script type="text/javascript" language="JavaScript"> +<!-- Hiding the code +function ro_imgNormal(imgName) { + if (document.images) { + document[imgName].src = eval(imgName + '_n.src'); + self.status = ''; + } +} +function ro_imgOver(imgName, descript) { + if (document.images) { + document[imgName].src = eval(imgName + '_o.src'); + self.status = descript; + } +} +// done hiding --> +</script> +<script type="text/javascript" language="JavaScript"> +<!-- Hiding the code +if (document.images) { + ro_img_prev_top_n = new Image(); + ro_img_prev_top_n.src = 'ssl_template.navbut-prev-n.gif'; + ro_img_prev_top_o = new Image(); + ro_img_prev_top_o.src = 'ssl_template.navbut-prev-s.gif'; +} +// done hiding --> +</script> +<script type="text/javascript" language="JavaScript"> +<!-- Hiding the code +if (document.images) { + ro_img_prev_bot_n = new Image(); + ro_img_prev_bot_n.src = 'ssl_template.navbut-prev-n.gif'; + ro_img_prev_bot_o = new Image(); + ro_img_prev_bot_o.src = 'ssl_template.navbut-prev-s.gif'; +} +// done hiding --> +</script> +<script type="text/javascript" language="JavaScript"> +<!-- Hiding the code +if (document.images) { + ro_img_next_top_n = new Image(); + ro_img_next_top_n.src = 'ssl_template.navbut-next-n.gif'; + ro_img_next_top_o = new Image(); + ro_img_next_top_o.src = 'ssl_template.navbut-next-s.gif'; +} +// done hiding --> +</script> +<script type="text/javascript" language="JavaScript"> +<!-- Hiding the code +if (document.images) { + ro_img_next_bot_n = new Image(); + ro_img_next_bot_n.src = 'ssl_template.navbut-next-n.gif'; + ro_img_next_bot_o = new Image(); + ro_img_next_bot_o.src = 'ssl_template.navbut-next-s.gif'; +} +// done hiding --> +</script> +</head> +<body bgcolor="#ffffff" text="#000000" link="#333399" alink="#9999ff" vlink="#000066"> +<div align="center"> +<table width="600" cellspacing="0" cellpadding="0" border="0" summary=""> +<tr> + <td> + <img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="600" height="1" align="bottom" border="0"><br> + <table width="600" cellspacing="0" cellpadding="0" summary=""> + <tr> + <td> + <table width="600" summary=""> + <tr> + <td align="left" valign="bottom"> + <font face="Arial,Helvetica" size="+2"><b>mod_ssl</b></font> + </td> + <td align="right"> + <img src="ssl_template.head-chapter.gif" alt="Chapter" width="175" height="94"> <img src="ssl_template.head-num-5.gif" alt="5" width="74" height="89"> + </td> + </tr> + </table> + </td> + </tr> + <tr> + <td><img src="ssl_template.imgdot-1x1-000000.gif" alt="" width="600" height="2" align="bottom" border="0"></td> + </tr> + <tr> + <td> + <table width="600" border="0" summary=""> + <tr> + <td valign="top" align="left" width="250"> +<a href="ssl_compat.html" onmouseover="ro_imgOver('ro_img_prev_top', 'previous page'); return true" onmouseout="ro_imgNormal('ro_img_prev_top'); return true" onfocus="ro_imgOver('ro_img_prev_top', 'previous page'); return true" onblur="ro_imgNormal('ro_img_prev_top'); return true"><img name="ro_img_prev_top" src="ssl_template.navbut-prev-n.gif" alt="previous page" width="70" height="18" border="0"></a><br><font color="#000000">Compatibility</font> + </td> + <td valign="top" align="right" width="250"> +<a href="ssl_faq.html" onmouseover="ro_imgOver('ro_img_next_top', 'next page'); return true" onmouseout="ro_imgNormal('ro_img_next_top'); return true" onfocus="ro_imgOver('ro_img_next_top', 'next page'); return true" onblur="ro_imgNormal('ro_img_next_top'); return true"><img name="ro_img_next_top" src="ssl_template.navbut-next-n.gif" alt="next page" width="70" height="18" border="0"></a><br><font color="#000000">F.A.Q. List</font> + </td> + </tr> + </table> + </td> + </tr> + <tr> + <td> + <br> + <img src="ssl_template.title-howto.gif" alt="HowTo" width="456" height="60"> + </td> + </tr> + </table> +<div align="right"> +<table cellspacing="0" cellpadding="0" width="200" summary=""> +<tr> +<td> +<em> +``The solution of this problem is trivial + and is left as an exercise for the reader.'' +</em> +</td> +</tr> +<tr> +<td align="right"> +<font size="-1"> +Standard textbook cookie +</font> +</td> +</tr> +</table> +</div> +<p> +<table cellspacing="0" cellpadding="0" border="0" summary=""> +<tr valign="bottom"> +<td> +<img src="ssl_howto.gfont000.gif" alt="H" width="40" height="34" border="0" align="left"> +ow to solve particular security constraints for an SSL-aware webserver +is not always obvious because of the coherences between SSL, HTTP and Apache's +way of processing requests. This chapter gives instructions on how to solve +such typical situations. Treat is as a first step to find out the final +solution, but always try to understand the stuff before you use it. Nothing is +worse than using a security solution without knowing it's restrictions and +coherences. +</td> +<td> + +</td> +<td> +<div align="right"> +<table cellspacing="0" cellpadding="5" border="0" bgcolor="#ccccff" width="300" summary=""> +<tr> +<td bgcolor="#333399"> +<font face="Arial,Helvetica" color="#ccccff"> +<b>Table Of Contents</b> +</font> +</td> +</tr> +<tr> +<td> +<font face="Arial,Helvetica" size="-1"> + <a href="#ToC1"><strong>Cipher Suites and Enforced Strong Security</strong></a><br> + <a href="#ToC2"><strong>SSLv2 only server</strong></a><br> + <a href="#ToC3"><strong>strong encryption only server</strong></a><br> + <a href="#ToC4"><strong>server gated cryptography</strong></a><br> + <a href="#ToC5"><strong>stronger per-directory requirements</strong></a><br> + <a href="#ToC6"><strong>Client Authentication and Access Control</strong></a><br> + <a href="#ToC7"><strong>simple certificate-based client authentication</strong></a><br> + <a href="#ToC8"><strong>selective certificate-based client authentication</strong></a><br> + <a href="#ToC9"><strong>particular certificate-based client authentication</strong></a><br> + <a href="#ToC10"><strong>intranet vs. internet authentication</strong></a><br> +</font> +</td> +</tr> +</table> +</div> +</td> +</tr> +</table> +<h2><a name="ToC1">Cipher Suites and Enforced Strong Security</a></h2> +<ul> +<p> +<li><a name="ToC2"></a> + <a name="cipher-sslv2"></a> + <strong id="howto"> +How can I create a real SSLv2-only server? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_howto.html#cipher-sslv2"><b>L</b></a>] + <p> +The following creates an SSL server which speaks only the SSLv2 protocol and +its ciphers. +<p> +<table border="0" cellpadding="0" cellspacing="0" summary=""> + <tr> + <td colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="8" align="bottom" border="0"></td> + <td rowspan="3"> <font face="Arial,Helvetica" color="#999999">httpd.conf</font> </td> + <td colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc" colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + <td bgcolor="#cccccc" colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="5" align="bottom" border="0"></td> + <td bgcolor="#ffffff"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="40" height="1" align="bottom" border="0"></td> + <td bgcolor="#ffffff"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="300" height="1" align="bottom" border="0"></td> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="5" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + <td colspan="3" bgcolor="#ffffff"> + <table border="0" cellspacing="4" summary=""> + <tr> + <td> +<pre> + +SSLProtocol -all +SSLv2 +SSLCipherSuite SSLv2:+HIGH:+MEDIUM:+LOW:+EXP + +</pre> +</td> + </tr> + </table> + </td> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td colspan="5" bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> +</table> +<p> +<li><a name="ToC3"></a> + <a name="cipher-strong"></a> + <strong id="howto"> +How can I create an SSL server which accepts strong encryption only? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_howto.html#cipher-strong"><b>L</b></a>] + <p> +The following enables only the seven strongest ciphers: +<p> +<table border="0" cellpadding="0" cellspacing="0" summary=""> + <tr> + <td colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="8" align="bottom" border="0"></td> + <td rowspan="3"> <font face="Arial,Helvetica" color="#999999">httpd.conf</font> </td> + <td colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc" colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + <td bgcolor="#cccccc" colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="5" align="bottom" border="0"></td> + <td bgcolor="#ffffff"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="40" height="1" align="bottom" border="0"></td> + <td bgcolor="#ffffff"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="300" height="1" align="bottom" border="0"></td> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="5" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + <td colspan="3" bgcolor="#ffffff"> + <table border="0" cellspacing="4" summary=""> + <tr> + <td> +<pre> + +SSLProtocol all +SSLCipherSuite HIGH:MEDIUM + +</pre> +</td> + </tr> + </table> + </td> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td colspan="5" bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> +</table> +<p> +<li><a name="ToC4"></a> + <a name="cipher-sgc"></a> + <strong id="howto"> +How can I create an SSL server which accepts strong encryption only, +but allows export browsers to upgrade to stronger encryption? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_howto.html#cipher-sgc"><b>L</b></a>] + <p> +This facility is called Server Gated Cryptography (SGC) and details you can +find in the <code>README.GlobalID</code> document in the mod_ssl distribution. +In short: The server has a Global ID server certificate, signed by a special +CA certificate from Verisign which enables strong encryption in export +browsers. This works as following: The browser connects with an export cipher, +the server sends it's Global ID certificate, the browser verifies it and +subsequently upgrades the cipher suite before any HTTP communication takes +place. The question now is: How can we allow this upgrade, but enforce strong +encryption. Or in other words: Browser either have to initially connect with +strong encryption or have to upgrade to strong encryption, but are not allowed +to keep the export ciphers. The following does the trick: +<p> +<table border="0" cellpadding="0" cellspacing="0" summary=""> + <tr> + <td colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="8" align="bottom" border="0"></td> + <td rowspan="3"> <font face="Arial,Helvetica" color="#999999">httpd.conf</font> </td> + <td colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc" colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + <td bgcolor="#cccccc" colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="5" align="bottom" border="0"></td> + <td bgcolor="#ffffff"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="40" height="1" align="bottom" border="0"></td> + <td bgcolor="#ffffff"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="300" height="1" align="bottom" border="0"></td> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="5" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + <td colspan="3" bgcolor="#ffffff"> + <table border="0" cellspacing="4" summary=""> + <tr> + <td> +<pre> + +# allow all ciphers for the inital handshake, +# so export browsers can upgrade via SGC facility +SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL +<Directory /usr/local/apache/htdocs> +# but finally deny all browsers which haven't upgraded +SSLRequire %{SSL_CIPHER_USEKEYSIZE} >= 128 +</Directory> + +</pre> +</td> + </tr> + </table> + </td> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td colspan="5" bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> +</table> +<p> +<li><a name="ToC5"></a> + <a name="cipher-perdir"></a> + <strong id="howto"> +How can I create an SSL server which accepts all types of ciphers in general, +but requires a strong ciphers for access to a particular URL? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_howto.html#cipher-perdir"><b>L</b></a>] + <p> +Obviously you cannot just use a server-wide <code>SSLCipherSuite</code> which +restricts the ciphers to the strong variants. But mod_ssl allows you to +reconfigure the cipher suite in per-directory context and automatically forces +a renegotiation of the SSL parameters to meet the new configuration. So, the +solution is: +<p> +<table border="0" cellpadding="0" cellspacing="0" summary=""> + <tr> + <td colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="8" align="bottom" border="0"></td> + <td rowspan="3"> <font face="Arial,Helvetica" color="#999999">httpd.conf</font> </td> + <td colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc" colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + <td bgcolor="#cccccc" colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="5" align="bottom" border="0"></td> + <td bgcolor="#ffffff"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="40" height="1" align="bottom" border="0"></td> + <td bgcolor="#ffffff"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="300" height="1" align="bottom" border="0"></td> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="5" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + <td colspan="3" bgcolor="#ffffff"> + <table border="0" cellspacing="4" summary=""> + <tr> + <td> +<pre> + +# be liberal in general +SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL +<Location /strong/area> +# but https://hostname/strong/area/ and below requires strong ciphers +SSLCipherSuite HIGH:MEDIUM +</Location> + +</pre> +</td> + </tr> + </table> + </td> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td colspan="5" bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> +</table> +</ul> +<h2><a name="ToC6">Client Authentication and Access Control</a></h2> +<ul> +<p> +<li><a name="ToC7"></a> + <a name="auth-simple"></a> + <strong id="howto"> +How can I authenticate clients based on certificates when I know all my +clients? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_howto.html#auth-simple"><b>L</b></a>] + <p> +When you know your user community (i.e. a closed user group situation), as +it's the case for instance in an Intranet, you can use plain certificate +authentication. All you have to do is to create client certificates signed by +your own CA certificate <code>ca.crt</code> and then verifiy the clients +against this certificate. +<p> +<table border="0" cellpadding="0" cellspacing="0" summary=""> + <tr> + <td colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="8" align="bottom" border="0"></td> + <td rowspan="3"> <font face="Arial,Helvetica" color="#999999">httpd.conf</font> </td> + <td colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc" colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + <td bgcolor="#cccccc" colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="5" align="bottom" border="0"></td> + <td bgcolor="#ffffff"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="40" height="1" align="bottom" border="0"></td> + <td bgcolor="#ffffff"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="300" height="1" align="bottom" border="0"></td> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="5" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + <td colspan="3" bgcolor="#ffffff"> + <table border="0" cellspacing="4" summary=""> + <tr> + <td> +<pre> + +# require a client certificate which has to be directly +# signed by our CA certificate in ca.crt +SSLVerifyClient require +SSLVerifyDepth 1 +SSLCACertificateFile conf/ssl.crt/ca.crt + +</pre> +</td> + </tr> + </table> + </td> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td colspan="5" bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> +</table> +<p> +<li><a name="ToC8"></a> + <a name="auth-selective"></a> + <strong id="howto"> +How can I authenticate my clients for a particular URL based on certificates +but still allow arbitrary clients to access the remaining parts of the server? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_howto.html#auth-selective"><b>L</b></a>] + <p> +For this we again use the per-directory reconfiguration feature of mod_ssl: +<p> +<table border="0" cellpadding="0" cellspacing="0" summary=""> + <tr> + <td colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="8" align="bottom" border="0"></td> + <td rowspan="3"> <font face="Arial,Helvetica" color="#999999">httpd.conf</font> </td> + <td colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc" colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + <td bgcolor="#cccccc" colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="5" align="bottom" border="0"></td> + <td bgcolor="#ffffff"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="40" height="1" align="bottom" border="0"></td> + <td bgcolor="#ffffff"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="300" height="1" align="bottom" border="0"></td> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="5" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + <td colspan="3" bgcolor="#ffffff"> + <table border="0" cellspacing="4" summary=""> + <tr> + <td> +<pre> + +SSLVerifyClient none +SSLCACertificateFile conf/ssl.crt/ca.crt +<Location /secure/area> +SSLVerifyClient require +SSLVerifyDepth 1 +</Location> + +</pre> +</td> + </tr> + </table> + </td> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td colspan="5" bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> +</table> +<p> +<li><a name="ToC9"></a> + <a name="auth-particular"></a> + <strong id="howto"> +How can I authenticate only particular clients for a some URLs based +on certificates but still allow arbitrary clients to access the remaining +parts of the server? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_howto.html#auth-particular"><b>L</b></a>] + <p> +The key is to check for various ingredients of the client certficate. Usually +this means to check the whole or part of the Distinguished Name (DN) of the +Subject. For this two methods exists: The <code>mod_auth</code> based variant +and the <code>SSLRequire</code> variant. The first method is good when the +clients are of totally different type, i.e. when their DNs have no common +fields (usually the organisation, etc.). In this case you've to establish a +password database containing <em>all</em> clients. The second method is better +when your clients are all part of a common hierarchy which is encoded into the +DN. Then you can match them more easily. +<p> +The first method: +<p> +<table border="0" cellpadding="0" cellspacing="0" summary=""> + <tr> + <td colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="8" align="bottom" border="0"></td> + <td rowspan="3"> <font face="Arial,Helvetica" color="#999999">/usr/local/apache/conf/httpd.conf</font> </td> + <td colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc" colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + <td bgcolor="#cccccc" colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="5" align="bottom" border="0"></td> + <td bgcolor="#ffffff"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="40" height="1" align="bottom" border="0"></td> + <td bgcolor="#ffffff"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="300" height="1" align="bottom" border="0"></td> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="5" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + <td colspan="3" bgcolor="#ffffff"> + <table border="0" cellspacing="4" summary=""> + <tr> + <td> +<pre> + +SSLVerifyClient none +<Directory /usr/local/apache/htdocs/secure/area> +SSLVerifyClient require +SSLVerifyDepth 5 +SSLCACertificateFile conf/ssl.crt/ca.crt +SSLCACertificatePath conf/ssl.crt +SSLOptions +FakeBasicAuth +SSLRequireSSL +AuthName "Snake Oil Authentication" +AuthType Basic +AuthUserFile /usr/local/apache/conf/httpd.passwd +require valid-user +</Directory> + +</pre> +</td> + </tr> + </table> + </td> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td colspan="5" bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> +</table> +<p> +<table border="0" cellpadding="0" cellspacing="0" summary=""> + <tr> + <td colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="8" align="bottom" border="0"></td> + <td rowspan="3"> <font face="Arial,Helvetica" color="#999999">/usr/local/apache/conf/httpd.passwd</font> </td> + <td colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc" colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + <td bgcolor="#cccccc" colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="5" align="bottom" border="0"></td> + <td bgcolor="#ffffff"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="40" height="1" align="bottom" border="0"></td> + <td bgcolor="#ffffff"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="300" height="1" align="bottom" border="0"></td> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="5" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + <td colspan="3" bgcolor="#ffffff"> + <table border="0" cellspacing="4" summary=""> + <tr> + <td> +<pre> + +/C=DE/L=Munich/O=Snake Oil, Ltd./OU=Staff/CN=Foo:xxj31ZMTZzkVA +/C=US/L=S.F./O=Snake Oil, Ltd./OU=CA/CN=Bar:xxj31ZMTZzkVA +/C=US/L=L.A./O=Snake Oil, Ltd./OU=Dev/CN=Quux:xxj31ZMTZzkVA + +</pre> +</td> + </tr> + </table> + </td> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td colspan="5" bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> +</table> +<p> +The second method: +<p> +<table border="0" cellpadding="0" cellspacing="0" summary=""> + <tr> + <td colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="8" align="bottom" border="0"></td> + <td rowspan="3"> <font face="Arial,Helvetica" color="#999999">httpd.conf</font> </td> + <td colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc" colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + <td bgcolor="#cccccc" colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="5" align="bottom" border="0"></td> + <td bgcolor="#ffffff"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="40" height="1" align="bottom" border="0"></td> + <td bgcolor="#ffffff"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="300" height="1" align="bottom" border="0"></td> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="5" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + <td colspan="3" bgcolor="#ffffff"> + <table border="0" cellspacing="4" summary=""> + <tr> + <td> +<pre> + +SSLVerifyClient none +<Directory /usr/local/apache/htdocs/secure/area> +SSLVerifyClient require +SSLVerifyDepth 5 +SSLCACertificateFile conf/ssl.crt/ca.crt +SSLCACertificatePath conf/ssl.crt +SSLOptions +FakeBasicAuth +SSLRequireSSL +SSLRequire %{SSL_CLIENT_S_DN_O} eq "Snake Oil, Ltd." and \ + %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"} +</Directory> + +</pre> +</td> + </tr> + </table> + </td> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td colspan="5" bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> +</table> +<p> +<li><a name="ToC10"></a> + <a name="auth-intranet"></a> + <strong id="howto"> How can +I require HTTPS with strong ciphers and either basic authentication or client +certificates for access to a subarea on the Intranet website for clients +coming from the Internet but still allow plain HTTP access for clients on the +Intranet? +</strong> + [<a href="http://www.modssl.org/docs/2.8/ssl_howto.html#auth-intranet"><b>L</b></a>] + <p> +Let us assume the Intranet can be distinguished through the IP network +192.160.1.0/24 and the subarea on the Intranet website has the URL +<tt>/subarea</tt>. Then configure the following outside your HTTPS virtual +host (so it applies to both HTTPS and HTTP): +<p> +<table border="0" cellpadding="0" cellspacing="0" summary=""> + <tr> + <td colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="8" align="bottom" border="0"></td> + <td rowspan="3"> <font face="Arial,Helvetica" color="#999999">httpd.conf</font> </td> + <td colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc" colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + <td bgcolor="#cccccc" colspan="2"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="5" align="bottom" border="0"></td> + <td bgcolor="#ffffff"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="40" height="1" align="bottom" border="0"></td> + <td bgcolor="#ffffff"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="300" height="1" align="bottom" border="0"></td> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="5" align="bottom" border="0"></td> + </tr> + <tr> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + <td colspan="3" bgcolor="#ffffff"> + <table border="0" cellspacing="4" summary=""> + <tr> + <td> +<pre> + +SSLCACertificateFile conf/ssl.crt/company-ca.crt + +<Directory /usr/local/apache/htdocs> +# Outside the subarea only Intranet access is granted +Order deny,allow +Deny from all +Allow from 192.168.1.0/24 +</Directory> + +<Directory /usr/local/apache/htdocs/subarea> +# Inside the subarea any Intranet access is allowed +# but from the Internet only HTTPS + Strong-Cipher + Password +# or the alternative HTTPS + Strong-Cipher + Client-Certificate + +# If HTTPS is used, make sure a strong cipher is used. +# Additionally allow client certs as alternative to basic auth. +SSLVerifyClient optional +SSLVerifyDepth 1 +SSLOptions +FakeBasicAuth +StrictRequire +SSLRequire %{SSL_CIPHER_USEKEYSIZE} >= 128 + +# Force clients from the Internet to use HTTPS +RewriteEngine on +RewriteCond %{REMOTE_ADDR} !^192\.168\.1\.[0-9]+$ +RewriteCond %{HTTPS} !=on +RewriteRule .* - [F] + +# Allow Network Access and/or Basic Auth +Satisfy any + +# Network Access Control +Order deny,allow +Deny from all +Allow 192.168.1.0/24 + +# HTTP Basic Authentication +AuthType basic +AuthName "Protected Intranet Area" +AuthUserFile conf/protected.passwd +Require valid-user +</Directory> + +</pre> +</td> + </tr> + </table> + </td> + <td bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> + <tr> + <td colspan="5" bgcolor="#cccccc"><img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="1" height="1" align="bottom" border="0"></td> + </tr> +</table> +</ul> + <p> + <br> + <table summary=""> + <tr> + <td> + <table width="600" border="0" summary=""> + <tr> + <td valign="top" align="left" width="250"> +<a href="ssl_compat.html" onmouseover="ro_imgOver('ro_img_prev_bot', 'previous page'); return true" onmouseout="ro_imgNormal('ro_img_prev_bot'); return true" onfocus="ro_imgOver('ro_img_prev_bot', 'previous page'); return true" onblur="ro_imgNormal('ro_img_prev_bot'); return true"><img name="ro_img_prev_bot" src="ssl_template.navbut-prev-n.gif" alt="previous page" width="70" height="18" border="0"></a><br><font color="#000000">Compatibility</font> + </td> + <td valign="top" align="right" width="250"> +<a href="ssl_faq.html" onmouseover="ro_imgOver('ro_img_next_bot', 'next page'); return true" onmouseout="ro_imgNormal('ro_img_next_bot'); return true" onfocus="ro_imgOver('ro_img_next_bot', 'next page'); return true" onblur="ro_imgNormal('ro_img_next_bot'); return true"><img name="ro_img_next_bot" src="ssl_template.navbut-next-n.gif" alt="next page" width="70" height="18" border="0"></a><br><font color="#000000">F.A.Q. List</font> + </td> + </tr> + </table> + </td> + </tr> + <tr> + <td><img src="ssl_template.imgdot-1x1-000000.gif" alt="" width="600" height="2" align="bottom" border="0"></td> + </tr> + <tr> + <td><table width="598" summary=""> + <tr> + <td align="left"><font face="Arial,Helvetica"> + <a href="http://www.modssl.org/">mod_ssl</a> 2.8, User Manual<br> + The Apache Interface to OpenSSL + </font> + </td> + <td align="right"><font face="Arial,Helvetica"> + Copyright © 1998-2001 + <a href="http://www.engelschall.com/">Ralf S. Engelschall</a><br> + All Rights Reserved<br> + </font> + </td> + </tr> + </table> + </td> + </tr> + </table> + </td> +</tr> +</table> +</div> +</body> +</html> diff --git a/docs/manual/ssl/ssl_intro.html b/docs/manual/ssl/ssl_intro.html new file mode 100644 index 0000000000..fae805f07a --- /dev/null +++ b/docs/manual/ssl/ssl_intro.html @@ -0,0 +1,919 @@ +<html> +<head> +<title>mod_ssl: Introduction</title> + +<!-- + Copyright (c) 1998-2001 Ralf S. Engelschall. All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code must retain the above + copyright notice, this list of conditions and the following + disclaimer. + + 2. Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials + provided with the distribution. + + 3. All advertising materials mentioning features or use of this + software must display the following acknowledgment: + "This product includes software developed by + Ralf S. Engelschall <rse@engelschall.com> for use in the + mod_ssl project (http://www.modssl.org/)." + + 4. The name "mod_ssl" must not be used to endorse or promote + products derived from this software without prior written + permission. + + 5. Redistributions of any form whatsoever must retain the + following acknowledgment: + "This product includes software developed by + Ralf S. Engelschall <rse@engelschall.com> for use in the + mod_ssl project (http://www.modssl.org/)." + + THIS SOFTWARE IS PROVIDED BY RALF S. ENGELSCHALL ``AS IS'' AND ANY + EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RALF S. ENGELSCHALL OR + HIS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT + NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; + LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED + OF THE POSSIBILITY OF SUCH DAMAGE. +--> +<style type="text/css"><!-- +A:link { + text-decoration: none; + color: #6666cc; +} +A:active { + text-decoration: none; + color: #6666cc; +} +A:visited { + text-decoration: none; + color: #6666cc; +} +#sf { + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +H1 { + font-weight: bold; + font-size: 24pt; + line-height: 24pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +H2 { + font-weight: bold; + font-size: 18pt; + line-height: 18pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +H3 { + font-weight: bold; + font-size: 14pt; + line-height: 14pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +H4 { + font-weight: bold; + font-size: 12pt; + line-height: 12pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +#H { +} +#D { + background-color: #f0f0f0; +} +#faq { + font-weight: bold; + font-size: 16pt; + line-height: 16pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +#howto { + font-weight: bold; + font-size: 16pt; + line-height: 16pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +#term { + font-weight: bold; + font-size: 16pt; + line-height: 16pt; + font-family: arial,helvetica; + font-variant: normal; + font-style: normal; +} +--></style> +<script type="text/javascript" language="JavaScript"> +<!-- Hiding the code +function ro_imgNormal(imgName) { + if (document.images) { + document[imgName].src = eval(imgName + '_n.src'); + self.status = ''; + } +} +function ro_imgOver(imgName, descript) { + if (document.images) { + document[imgName].src = eval(imgName + '_o.src'); + self.status = descript; + } +} +// done hiding --> +</script> +<script type="text/javascript" language="JavaScript"> +<!-- Hiding the code +if (document.images) { + ro_img_prev_top_n = new Image(); + ro_img_prev_top_n.src = 'ssl_template.navbut-prev-n.gif'; + ro_img_prev_top_o = new Image(); + ro_img_prev_top_o.src = 'ssl_template.navbut-prev-s.gif'; +} +// done hiding --> +</script> +<script type="text/javascript" language="JavaScript"> +<!-- Hiding the code +if (document.images) { + ro_img_prev_bot_n = new Image(); + ro_img_prev_bot_n.src = 'ssl_template.navbut-prev-n.gif'; + ro_img_prev_bot_o = new Image(); + ro_img_prev_bot_o.src = 'ssl_template.navbut-prev-s.gif'; +} +// done hiding --> +</script> +<script type="text/javascript" language="JavaScript"> +<!-- Hiding the code +if (document.images) { + ro_img_next_top_n = new Image(); + ro_img_next_top_n.src = 'ssl_template.navbut-next-n.gif'; + ro_img_next_top_o = new Image(); + ro_img_next_top_o.src = 'ssl_template.navbut-next-s.gif'; +} +// done hiding --> +</script> +<script type="text/javascript" language="JavaScript"> +<!-- Hiding the code +if (document.images) { + ro_img_next_bot_n = new Image(); + ro_img_next_bot_n.src = 'ssl_template.navbut-next-n.gif'; + ro_img_next_bot_o = new Image(); + ro_img_next_bot_o.src = 'ssl_template.navbut-next-s.gif'; +} +// done hiding --> +</script> +</head> +<body bgcolor="#ffffff" text="#000000" link="#333399" alink="#9999ff" vlink="#000066"> +<div align="center"> +<table width="600" cellspacing="0" cellpadding="0" border="0" summary=""> +<tr> + <td> + <img src="ssl_template.imgdot-1x1-transp.gif" alt="" width="600" height="1" align="bottom" border="0"><br> + <table width="600" cellspacing="0" cellpadding="0" summary=""> + <tr> + <td> + <table width="600" summary=""> + <tr> + <td align="left" valign="bottom"> + <font face="Arial,Helvetica" size="+2"><b>mod_ssl</b></font> + </td> + <td align="right"> + <img src="ssl_template.head-chapter.gif" alt="Chapter" width="175" height="94"> <img src="ssl_template.head-num-2.gif" alt="2" width="74" height="89"> + </td> + </tr> + </table> + </td> + </tr> + <tr> + <td><img src="ssl_template.imgdot-1x1-000000.gif" alt="" width="600" height="2" align="bottom" border="0"></td> + </tr> + <tr> + <td> + <table width="600" border="0" summary=""> + <tr> + <td valign="top" align="left" width="250"> +<a href="ssl_overview.html" onmouseover="ro_imgOver('ro_img_prev_top', 'previous page'); return true" onmouseout="ro_imgNormal('ro_img_prev_top'); return true" onfocus="ro_imgOver('ro_img_prev_top', 'previous page'); return true" onblur="ro_imgNormal('ro_img_prev_top'); return true"><img name="ro_img_prev_top" src="ssl_template.navbut-prev-n.gif" alt="previous page" width="70" height="18" border="0"></a><br><font color="#000000">Overview</font> + </td> + <td valign="top" align="right" width="250"> +<a href="ssl_reference.html" onmouseover="ro_imgOver('ro_img_next_top', 'next page'); return true" onmouseout="ro_imgNormal('ro_img_next_top'); return true" onfocus="ro_imgOver('ro_img_next_top', 'next page'); return true" onblur="ro_imgNormal('ro_img_next_top'); return true"><img name="ro_img_next_top" src="ssl_template.navbut-next-n.gif" alt="next page" width="70" height="18" border="0"></a><br><font color="#000000">Reference</font> + </td> + </tr> + </table> + </td> + </tr> + <tr> + <td> + <br> + <img src="ssl_template.title-intro.gif" alt="Introduction" width="456" height="60"> + </td> + </tr> + </table> +<div align="right"> +<table cellspacing="0" cellpadding="0" width="400" summary=""> +<tr> +<td> +<em> +``The nice thing about standards is that there are so many to choose from. +And if you really don't like all the standards you just have to wait another +year until the one arises you are looking for.'' +</em> +</td> +</tr> +<tr> +<td align="right"> +<font size="-1"> +A. Tanenbaum, ``Introduction to Computer Networks'' +</font> +</td> +</tr> +</table> +</div> +<p> +<table cellspacing="0" cellpadding="0" border="0" summary=""> +<tr valign="bottom"> +<td> +<img src="ssl_intro.gfont000.gif" alt="A" width="37" height="35" border="0" align="left"> +s an introduction this chapter is aimed at readers who are familiar +with the Web, HTTP, and Apache, but are not security experts. It is not +intended to be a definitive guide to the SSL protocol, nor does it discuss +specific techniques for managing certificates in an organization, or the +important legal issues of patents and import and export restrictions. Rather, +it is intended to provide a common background to mod_ssl users by pulling +together various concepts, definitions, and examples as a starting point for +further exploration. +<p> +The presented content is mainly derived, with permission by the author, from +the article <a +href="http://www.ultranet.com/~fhirsch/Papers/wwwj/index.html"><em>Introducing SSL +and Certificates using SSLeay</em></a> from <a +href="http://www.ultranet.com/~fhirsch/">Frederick J. Hirsch</a>, of The Open +Group Research Institute, which was published in <a +href="http://www.ora.com/catalog/wjsum97/"><em>Web Security: A Matter of +Trust</em></a>, World Wide Web Journal, Volume 2, Issue 3, Summer 1997. +Please send any postive feedback to <a +href="mailto:fjh@alum.mit.edu">Frederick Hirsch</a> (the original +article author) and all negative feedback to <a +href="mailto:rse@engelschall.com">Ralf S. Engelschall</a> (the mod_ssl +author). +</td> +<td> + +</td> +<td> +<div align="right"> +<table cellspacing="0" cellpadding="5" border="0" bgcolor="#ccccff" summary=""> +<tr> +<td bgcolor="#333399"> +<font face="Arial,Helvetica" color="#ccccff"> +<b>Table Of Contents</b> +</font> +</td> +</tr> +<tr> +<td> +<font face="Arial,Helvetica" size="-1"> + <a href="#ToC1"><strong>Cryptographic Techniques</strong></a><br> + <a href="#ToC2"><strong>Cryptographic Algorithms</strong></a><br> + <a href="#ToC3"><strong>Message Digests</strong></a><br> + <a href="#ToC4"><strong>Digital Signatures</strong></a><br> + <a href="#ToC5"><strong>Certificates</strong></a><br> + <a href="#ToC6"><strong>Certificate Contents</strong></a><br> + <a href="#ToC7"><strong>Certificate Authorities</strong></a><br> + <a href="#ToC8"><strong>Certificate Chains</strong></a><br> + <a href="#ToC9"><strong>Creating a Root-Level CA</strong></a><br> + <a href="#ToC10"><strong>Certificate Management</strong></a><br> + <a href="#ToC11"><strong>Secure Sockets Layer (SSL)</strong></a><br> + <a href="#ToC12"><strong>Session Establishment</strong></a><br> + <a href="#ToC13"><strong>Key Exchange Method</strong></a><br> + <a href="#ToC14"><strong>Cipher for Data Transfer</strong></a><br> + <a href="#ToC15"><strong>Digest Function</strong></a><br> + <a href="#ToC16"><strong>Handshake Sequence Protocol</strong></a><br> + <a href="#ToC17"><strong>Data Transfer</strong></a><br> + <a href="#ToC18"><strong>Securing HTTP Communication</strong></a><br> + <a href="#ToC19"><strong>References</strong></a><br> +</font> +</td> +</tr> +</table> +</div> +</td> +</tr> +</table> +<h2><a name="ToC1">Cryptographic Techniques</a></h2> +Understanding SSL requires an understanding of cryptographic algorithms, +message digest functions (aka. one-way or hash functions), and digital +signatures. These techniques are the subject of entire books (see for instance +[<a href="#AC96">AC96</a>]) and provide the basis for privacy, integrity, and +authentication. +<h3><a name="ToC2">Cryptographic Algorithms</a></h3> +Suppose Alice wants to send a message to her bank to transfer some money. +Alice would like the message to be private, since it will include information +such as her account number and transfer amount. One solution is to use a +cryptographic algorithm, a technique that would transform her message into an +encrypted form, unreadable except by those it is intended for. Once in this +form, the message may only be interpreted through the use of a secret key. +Without the key the message is useless: good cryptographic algorithms make it +so difficult for intruders to decode the original text that it isn't worth +their effort. +<p> +There are two categories of cryptographic algorithms: +conventional and public key. +<ul> +<li><em>Conventional cryptography</em>, also known as symmetric +cryptography, requires the sender and receiver to share a key: a secret +piece of information that may be used to encrypt or decrypt a message. +If this key is secret, then nobody other than the sender or receiver may +read the message. If Alice and the bank know a secret key, then they +may send each other private messages. The task of privately choosing a key +before communicating, however, can be problematic. +<p> +<li><em>Public key cryptography</em>, also known as asymmetric cryptography, +solves the key exchange problem by defining an algorithm which uses two keys, +each of which may be used to encrypt a message. If one key is used to encrypt +a message then the other must be used to decrypt it. This makes it possible +to receive secure messages by simply publishing one key (the public key) and +keeping the other secret (the private key). +<p> +Anyone may encrypt a message using the public key, but only the owner of the +private key will be able to read it. In this way, Alice may send private +messages to the owner of a key-pair (the bank), by encrypting it using their +public key. Only the bank will be able to decrypt it. +</ul> +<h3><a name="ToC3">Message Digests</a></h3> +Although Alice may encrypt her message to make it private, there is still a +concern that someone might modify her original message or substitute +it with a different one, in order to transfer the money to themselves, for +instance. One way of guaranteeing the integrity of Alice's message is to +create a concise summary of her message and send this to the bank as well. +Upon receipt of the message, the bank creates its own summary and compares it +with the one Alice sent. If they agree then the message was received intact. +<p> +A summary such as this is called a <em>message digest</em>, <em>one-way +function</em> or <em>hash function</em>. Message digests are used to create +short, fixed-length representations of longer, variable-length messages. +Digest algorithms are designed to produce unique digests for different +messages. Message digests are designed to make it too difficult to determine +the message from the digest, and also impossible to find two different +messages which create the same digest -- thus eliminating the possibility of +substituting one message for another while maintaining the same digest. +<p> +Another challenge that Alice faces is finding a way to send the digest to the +bank securely; when this is achieved, the integrity of the associated message +is assured. One way to to this is to include the digest in a digital +signature. +<h3><a name="ToC4">Digital Signatures</a></h3> +When Alice sends a message to the bank, the bank needs to ensure that the +message is really from her, so an intruder does not request a transaction +involving her account. A <em>digital signature</em>, created by Alice and +included with the message, serves this purpose. +<p> +Digital signatures are created by encrypting a digest of the message, +and other information (such as a sequence number) with the sender's +private key. Though anyone may <em>decrypt</em> the signature using the public +key, only the signer knows the private key. This means that only they may +have signed it. Including the digest in the signature means the signature is +only good for that message; it also ensures the integrity of the message since +no one can change the digest and still sign it. +<p> +To guard against interception and reuse of the signature by an intruder at a +later date, the signature contains a unique sequence number. This protects +the bank from a fraudulent claim from Alice that she did not send the message +-- only she could have signed it (non-repudiation). +<h2><a name="ToC5">Certificates</a></h2> +Although Alice could have sent a private message to the bank, signed it, and +ensured the integrity of the message, she still needs to be sure that she is +really communicating with the bank. This means that she needs to be sure that +the public key she is using corresponds to the bank's private key. Similarly, +the bank also needs to verify that the message signature really corresponds to +Alice's signature. +<p> +If each party has a certificate which validates the other's identity, confirms +the public key, and is signed by a trusted agency, then they both will be +assured that they are communicating with whom they think they are. Such a +trusted agency is called a <em>Certificate Authority</em>, and certificates are +used for authentication. +<h3><a name="ToC6">Certificate Contents</a></h3> +A certificate associates a public key with the real identity of an individual, +server, or other entity, known as the subject. As shown in <a +href="#table1">Table 1</a>, information about the subject includes identifying +information (the distinguished name), and the public key. It also includes +the identification and signature of the Certificate Authority that issued the +certificate, and the period of time during which the certificate is valid. It +may have additional information (or extensions) as well as administrative +information for the Certificate Authority's use, such as a serial number. +<p> +<div align="center"> +<a name="table1"></a> +<table width="600" cellspacing="0" cellpadding="1" border="0" summary=""> +<caption align="bottom" id="sf">Table 1: Certificate Information</caption> +<tr><td bgcolor="#cccccc"> +<table width="598" cellpadding="5" cellspacing="0" border="0" summary=""> +<tr><td valign="top" align="center" bgcolor="#ffffff"> +<table summary=""> +<tr valign="top"><td><b>Subject:</b></td> +<td>Distinguished Name, Public Key</td></tr> +<tr valign="top"><td><b>Issuer:</b></td> +<td>Distinguished Name, Signature</td></tr> +<tr><td><b>Period of Validity:</b></td> +<td>Not Before Date, Not After Date</td></tr> +<tr><td><b>Administrative Information:</b></td> +<td>Version, Serial Number</td></TR> +<tr><td><b>Extended Information:</b></td> +<td>Basic Contraints, Netscape Flags, etc.</td></TR> +</table> +</td> +</tr></table> +</td></tr></table> +</div> +<p> +A distinguished name is used to provide an identity in a specific context -- +for instance, an individual might have a personal certificate as well as one +for their identity as an employee. Distinguished names are defined by the +X.509 standard [<a href="#X509">X509</A>], which defines the fields, field +names, and abbreviations used to refer to the fields +(see <a href="#table2">Table 2</a>). +<p> +<div align="center"> +<a name="table2"></a> +<table width="600" cellspacing="0" cellpadding="1" border="0" summary=""> +<caption align="bottom" id="sf">Table 2: Distinguished Name Information</caption> +<tr><td bgcolor="#cccccc"> +<table width="598" cellpadding="5" cellspacing="0" border="0" summary=""> +<tr><td valign="top" align="center" bgcolor="#ffffff"> +<table summary=""> +<tr valign="top"><td><b>DN Field:</b></td><td><b>Abbrev.:</b></td><td><b>Description:</b></td> +<td><b>Example:</b></td> +</t> +<tr valign="top"><td>Common Name</td><td>CN</td> +<td>Name being certified</td><td>CN=Joe Average</td></tr> +<tr valign="top"><td>Organization or Company</td><td>O</td> +<td>Name is associated with this<br>organization</td><td>O=Snake Oil, Ltd.</td></tr> +<tr valign="top"><td>Organizational Unit</td><td>OU</td> +<td>Name is associated with this <br>organization unit, such as a department</td><td>OU=Research Institute</td></tr> +<tr valign="top"><td>City/Locality</td><td>L</td> +<td>Name is located in this City</td><td>L=Snake City</td></tr> +<tr valign="top"><td>State/Province</td><td>ST</td> +<td>Name is located in this State/Province</td><td>ST=Desert</td></tr> +<tr valign="top"><td>Country</td><td>C</td> +<td>Name is located in this Country (ISO code)</td><td>C=XZ</td></tr> +</table> +</td> +</tr></table> +</td></tr></table> +</div> +<p> +A Certificate Authority may define a policy specifying which distinguished +field names are optional, and which are required. It may also place +requirements upon the field contents, as may users of certificates. As an +example, a Netscape browser requires that the Common Name for a certificate +representing a server has a name which matches a wildcard pattern for the +domain name of that server, such as <code>*.snakeoil.com</code>. +<p> +The binary format of a certificate is defined using the ASN.1 notation [ <a +href="#X208">X208</a>] [<a href="#PKCS">PKCS</a>]. This notation defines how to +specify the contents, and encoding rules define how this information is +translated into binary form. The binary encoding of the certificate is +defined using Distinguished Encoding Rules (DER), which are based on the more +general Basic Encoding Rules (BER). For those transmissions which cannot +handle binary, the binary form may be translated into an ASCII form by using +Base64 encoding [<a href="#MIME">MIME</a>]. This encoded version is called PEM +encoded (the name comes from "Privacy Enhanced Mail"), when placed between +begin and end delimiter lines as illustrated in <a href="#table3">Table 3</a>. +<p> +<div align="center"> +<a name="table3"></a> +<table width="600" cellspacing="0" cellpadding="1" border="0" summary=""> +<caption align="bottom" id="sf">Table 3: Example of a PEM-encoded certificate (snakeoil.crt)</caption> +<tr><td bgcolor="#cccccc"> +<table width="598" cellpadding="5" cellspacing="0" border="0" summary=""> +<tr><td valign="top" align="center" bgcolor="#ffffff"> +<table cellspacing="0" cellpadding="0" summary=""><tr><td> +<div class="code"><pre> +-----BEGIN CERTIFICATE----- +MIIC7jCCAlegAwIBAgIBATANBgkqhkiG9w0BAQQFADCBqTELMAkGA1UEBhMCWFkx +FTATBgNVBAgTDFNuYWtlIERlc2VydDETMBEGA1UEBxMKU25ha2UgVG93bjEXMBUG +A1UEChMOU25ha2UgT2lsLCBMdGQxHjAcBgNVBAsTFUNlcnRpZmljYXRlIEF1dGhv +cml0eTEVMBMGA1UEAxMMU25ha2UgT2lsIENBMR4wHAYJKoZIhvcNAQkBFg9jYUBz +bmFrZW9pbC5kb20wHhcNOTgxMDIxMDg1ODM2WhcNOTkxMDIxMDg1ODM2WjCBpzEL +MAkGA1UEBhMCWFkxFTATBgNVBAgTDFNuYWtlIERlc2VydDETMBEGA1UEBxMKU25h +a2UgVG93bjEXMBUGA1UEChMOU25ha2UgT2lsLCBMdGQxFzAVBgNVBAsTDldlYnNl +cnZlciBUZWFtMRkwFwYDVQQDExB3d3cuc25ha2VvaWwuZG9tMR8wHQYJKoZIhvcN +AQkBFhB3d3dAc25ha2VvaWwuZG9tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKB +gQDH9Ge/s2zcH+da+rPTx/DPRp3xGjHZ4GG6pCmvADIEtBtKBFAcZ64n+Dy7Np8b +vKR+yy5DGQiijsH1D/j8HlGE+q4TZ8OFk7BNBFazHxFbYI4OKMiCxdKzdif1yfaa +lWoANFlAzlSdbxeGVHoT0K+gT5w3UxwZKv2DLbCTzLZyPwIDAQABoyYwJDAPBgNV +HRMECDAGAQH/AgEAMBEGCWCGSAGG+EIBAQQEAwIAQDANBgkqhkiG9w0BAQQFAAOB +gQAZUIHAL4D09oE6Lv2k56Gp38OBDuILvwLg1v1KL8mQR+KFjghCrtpqaztZqcDt +2q2QoyulCgSzHbEGmi0EsdkPfg6mp0penssIFePYNI+/8u9HT4LuKMJX15hxBam7 +dUHzICxBVC1lnHyYGjDuAMhe396lYAn8bCld1/L4NMGBCQ== +-----END CERTIFICATE-----</pre></div> +</td></tr></table> +</td> +</tr></table> +</td></tr></table> +</div> +<h3><a name="ToC7">Certificate Authorities</a></h3> +By first verifying the information in a certificate request before granting +the certificate, the Certificate Authority assures the identity of the private +key owner of a key-pair. For instance, if Alice requests a personal +certificate, the Certificate Authority must first make sure that Alice really +is the person the certificate request claims. +<h4><a name="ToC8">Certificate Chains</a></h4> +A Certificate Authority may also issue a certificate for another Certificate +Authority. When examining a certificate, Alice may need to examine the +certificate of the issuer, for each parent Certificate Authority, until +reaching one which she has confidence in. She may decide to trust only +certificates with a limited chain of issuers, to reduce her risk of a "bad" +certificate in the chain. +<h4><a name="ToC9">Creating a Root-Level CA</a></h4> +As noted earlier, each certificate requires an issuer to assert the validity +of the identity of the certificate subject, up to the top-level Certificate +Authority (CA). This presents a problem: Since this is who vouches for the +certificate of the top-level authority, which has no issuer? +In this unique case, the certificate is "self-signed", so the issuer of the +certificate is the same as the subject. As a result, one must exercise extra +care in trusting a self-signed certificate. The wide publication of a public +key by the root authority reduces the risk in trusting this key -- it would be +obvious if someone else publicized a key claiming to be the authority. +Browsers are preconfigured to trust well-known certificate authorities. +<p> +A number of companies, such as <a href="http://www.thawte.com/">Thawte</a> and +<a href="http://www.verisign.com/">VeriSign</a> have established themselves as +Certificate Authorities. These companies provide the following services: +<ul> +<li>Verifying certificate requests +<li>Processing certificate requests +<li>Issuing and managing certificates +</ul> +<p> +It is also possible to create your own Certificate Authority. Although risky +in the Internet environment, it may be useful within an Intranet where the +organization can easily verify the identities of individuals and servers. +<h4><a name="ToC10">Certificate Management</a></h4> +Establishing a Certificate Authority is a responsibility which requires a +solid administrative, technical, and management framework. +Certificate Authorities not only issue certificates, they also manage them -- +that is, they determine how long certificates are valid, they renew them, and +they keep lists of certificates that have already been issued but are no +longer valid (Certificate Revocation Lists, or CRLs). +Say Alice is entitled to a certificate as an employee of a company. Say too, +that the certificate needs to be revoked when Alice leaves the company. Since +certificates are objects that get passed around, it is impossible to tell from +the certificate alone that it has been revoked. +When examining certificates for validity, therefore, it is necessary to +contact the issuing Certificate Authority to check CRLs -- this is not usually +an automated part of the process. +<p> +<div align="center"><B>Note:</B></div> +If you use a Certificate Authority that is not configured into browsers by +default, it is necessary to load the Certificate Authority certificate into +the browser, enabling the browser to validate server certificates signed by +that Certificate Authority. Doing so may be dangerous, since once loaded, the +browser will accept all certificates signed by that Certificate Authority. +<h2><a name="ToC11">Secure Sockets Layer (SSL)</a></h2> +The Secure Sockets Layer protocol is a protocol layer which may be placed +between a reliable connection-oriented network layer protocol (e.g. TCP/IP) +and the application protocol layer (e.g. HTTP). SSL provides for secure +communication between client and server by allowing mutual authentication, the +use of digital signatures for integrity, and encryption for privacy. +<p> +The protocol is designed to support a range of choices for specific algorithms +used for cryptography, digests, and signatures. This allows algorithm +selection for specific servers to be made based on legal, export or other +concerns, and also enables the protocol to take advantage of new algorithms. +Choices are negotiated between client and server at the start of establishing +a protocol session. +<p> +<div align="center"> +<a name="table4"></a> +<table width="600" cellspacing="0" cellpadding="1" border="0" summary=""> +<caption align="bottom" id="sf">Table 4: Versions of the SSL protocol</caption> +<tr><td bgcolor="#cccccc"> +<table width="598" cellpadding="5" cellspacing="0" border="0" summary=""> +<tr><td valign="top" align="center" bgcolor="#ffffff"> +<table summary=""> +<tr valign="top"> +<td><b>Version:</b></td> +<td><b>Source:</b></td> +<td><b>Description:</b></td> +<td><b>Browser Support:</b></td> +</tr> +<tr valign="top"> +<td>SSL v2.0</td> +<td>Vendor Standard (from Netscape Corp.) [<a href="#SSL2">SSL2</a>]</td> +<td>First SSL protocol for which implementations exists</td> +<td>- NS Navigator 1.x/2.x<br> + - MS IE 3.x<br> + - Lynx/2.8+OpenSSL +</td> +</tr> +<tr valign="top"> +<td>SSL v3.0</td> +<td>Expired Internet Draft (from Netscape Corp.) [<a href="#SSL3">SSL3</a>]</td> +<td>Revisions to prevent specific security attacks, add non-RSA ciphers, and support for certificate chains</td> +<td>- NS Navigator 2.x/3.x/4.x<br> + - MS IE 3.x/4.x<br> + - Lynx/2.8+OpenSSL +</td> +</tr> +<tr valign="top"> +<td>TLS v1.0</td> +<td>Proposed Internet Standard (from IETF) [<a href="#TLS1">TLS1</a>]</td> +<td>Revision of SSL 3.0 to update the MAC layer to HMAC, add block padding for + block ciphers, message order standardization and more alert messages. +</td> +<td>- Lynx/2.8+OpenSSL</td> +</table> +</td> +</tr></table> +</td></tr></table> +</div> +<p> +There are a number of versions of the SSL protocol, as shown in <a +href="#table4">Table 4</a>. As noted there, one of the benefits in SSL 3.0 is +that it adds support of certificate chain loading. This feature allows a +server to pass a server certificate along with issuer certificates to the +browser. Chain loading also permits the browser to validate the server +certificate, even if Certificate Authority certificates are not installed for +the intermediate issuers, since they are included in the certificate chain. +SSL 3.0 is the basis for the Transport Layer Security [<A +HREF="#TLS1">TLS</A>] protocol standard, currently in development by the +Internet Engineering Task Force (IETF). +<h3><a name="ToC12">Session Establishment</a></h3> +The SSL session is established by following a <I>handshake sequence</I> +between client and server, as shown in <a href="#figure1">Figure 1</a>. This +sequence may vary, depending on whether the server is configured to provide a +server certificate or request a client certificate. Though cases exist where +additional handshake steps are required for management of cipher information, +this article summarizes one common scenario: see the SSL specification for the +full range of possibilities. +<p> +<div align="center"><b>Note</b></div> +Once an SSL session has been established it may be reused, thus avoiding the +performance penalty of repeating the many steps needed to start a session. +For this the server assigns each SSL session a unique session identifier which +is cached in the server and which the client can use on forthcoming +connections to reduce the handshake (until the session identifer expires in +the cache of the server). +<p> +<div align="center"> +<a name="figure1"></a> +<table width="600" cellspacing="0" cellpadding="1" border="0" summary=""> +<caption align="bottom" id="sf">Figure 1: Simplified SSL Handshake Sequence</caption> +<tr><td bgcolor="#cccccc"> +<table width="598" cellpadding="5" cellspacing="0" border="0" summary=""> +<tr><td valign="top" align="center" bgcolor="#ffffff"> +<img src="ssl_intro_fig1.gif" alt="" width="423" height="327"> +</td> +</tr></table> +</td></tr></table> +</div> +<p> +The elements of the handshake sequence, as used by the client and server, are +listed below: +<ol> +<li>Negotiate the Cipher Suite to be used during data transfer +<li>Establish and share a session key between client and server +<li>Optionally authenticate the server to the client +<li>Optionally authenticate the client to the server +</ol> +<p> +The first step, Cipher Suite Negotiation, allows the client and server to +choose a Cipher Suite supportable by both of them. The SSL3.0 protocol +specification defines 31 Cipher Suites. A Cipher Suite is defined by the +following components: +<ul> +<li>Key Exchange Method +<li>Cipher for Data Transfer +<li>Message Digest for creating the Message Authentication Code (MAC) +</ul> +These three elements are described in the sections that follow. +<h3><a name="ToC13">Key Exchange Method</a></h3> +The key exchange method defines how the shared secret symmetric cryptography +key used for application data transfer will be agreed upon by client and +server. SSL 2.0 uses RSA key exchange only, while SSL 3.0 supports a choice of +key exchange algorithms including the RSA key exchange when certificates are +used, and Diffie-Hellman key exchange for exchanging keys without certificates +and without prior communication between client and server. +<p> +One variable in the choice of key exchange methods is digital signatures -- +whether or not to use them, and if so, what kind of signatures to use. +Signing with a private key provides assurance against a +man-in-the-middle-attack during the information exchange used in generating +the shared key [<a href="#AC96">AC96</a>, p516]. +<h3><a name="ToC14">Cipher for Data Transfer</a></h3> +SSL uses the conventional cryptography algorithm (symmetric cryptography) +described earlier for encrypting messages in a session. There are nine +choices, including the choice to perform no encryption: +<ul> +<li>No encryption +<li>Stream Ciphers + <ul> + <li>RC4 with 40-bit keys + <li>RC4 with 128-bit keys + </ul> +<li>CBC Block Ciphers + <ul> + <li>RC2 with 40 bit key + <li>DES with 40 bit key + <li>DES with 56 bit key + <li>Triple-DES with 168 bit key + <li>Idea (128 bit key) + <li>Fortezza (96 bit key) + </ul> +</ul> +Here "CBC" refers to Cipher Block Chaining, which means that a portion of the +previously encrypted cipher text is used in the encryption of the current +block. "DES" refers to the Data Encryption Standard [<a href="#AC96">AC96</a>, +ch12], which has a number of variants (including DES40 and 3DES_EDE). "Idea" +is one of the best and cryptographically strongest available algorithms, and +"RC2" is a proprietary algorithm from RSA DSI [<a href="#AC96">AC96</a>, +ch13]. +<h3><a name="ToC15">Digest Function</a></h3> +The choice of digest function determines how a digest is created from a record +unit. SSL supports the following: +<ul> +<li>No digest (Null choice) +<li>MD5, a 128-bit hash +<li>Secure Hash Algorithm (SHA-1), a 160-bit hash +</ul> +The message digest is used to create a Message Authentication Code (MAC) which +is encrypted with the message to provide integrity and to prevent against +replay attacks. +<h3><a name="ToC16">Handshake Sequence Protocol</a></h3> +The handshake sequence uses three protocols: +<ul> +<li>The <em>SSL Handshake Protocol</em> + for performing the client and server SSL session establishment. +<li>The <em>SSL Change Cipher Spec Protocol</em> for actually establishing agreement + on the Cipher Suite for the session. +<li>The <em>SSL Alert Protocol</em> for + conveying SSL error messages between client and server. +</ul> +These protocols, as well as application protocol data, are encapsulated in the +<em>SSL Record Protocol</em>, as shown in <a href="#figure2">Figure 2</a>. An +encapsulated protocol is transferred as data by the lower layer protocol, +which does not examine the data. The encapsulated protocol has no knowledge of +the underlying protocol. +<p> +<div align="center"> +<a name="figure2"></a> +<table width="600" cellspacing="0" cellpadding="1" border="0" summary=""> +<caption align="bottom" id="sf">Figure 2: SSL Protocol Stack</caption> +<tr><td bgcolor="#cccccc"> +<table width="598" cellpadding="5" cellspacing="0" border="0" summary=""> +<tr><td valign="top" align="center" bgcolor="#ffffff"> +<img src="ssl_intro_fig2.gif" alt="" width="428" height="217"> +</td> +</tr></table> +</td></tr></table> +</div> +<p> +The encapsulation of SSL control protocols by the record protocol means that +if an active session is renegotiated the control protocols will be transmitted +securely. If there were no session before, then the Null cipher suite is +used, which means there is no encryption and messages have no integrity +digests until the session has been established. +<h3><a name="ToC17">Data Transfer</a></h3> +The SSL Record Protocol, shown in <a href="#figure3">Figure 3</a>, is used to +transfer application and SSL Control data between the client and server, +possibly fragmenting this data into smaller units, or combining multiple +higher level protocol data messages into single units. It may compress, attach +digest signatures, and encrypt these units before transmitting them using the +underlying reliable transport protocol (Note: currently all major SSL +implementations lack support for compression). +<p> +<div align="center"> +<a name="figure3"></a> +<table width="600" cellspacing="0" cellpadding="1" border="0" summary=""> +<caption align="bottom" id="sf">Figure 3: SSL Record Protocol</caption> +<tr><td bgcolor="#cccccc"> +<table width="598" cellpadding="5" cellspacing="0" border="0" summary=""> +<tr><td valign="top" align="center" bgcolor="#ffffff"> +<img src="ssl_intro_fig3.gif" alt="" width="423" height="323"> +</td> +</tr></table> +</td></tr></table> +</div> +<h3><a name="ToC18">Securing HTTP Communication</a></h3> +One common use of SSL is to secure Web HTTP communication between a browser +and a webserver. This case does not preclude the use of non-secured HTTP. The +secure version is mainly plain HTTP over SSL (named HTTPS), but with one major +difference: it uses the URL scheme <code>https</code> rather than +<code>http</code> and a different server port (by default 443). This mainly +is what mod_ssl provides to you for the Apache webserver... +<h2><a name="ToC19">References</a></h2> +<ul> +<p> +<li><a name="AC96"></a> +[AC96] Bruce Schneier, <em>Applied Cryptography</em>, 2nd Edition, Wiley, + 1996. See <a href="http://www.counterpane.com/">http://www.counterpane.com/</a> for + various other materials by Bruce Schneier. +<p> +<li><a name="X208"></a> +[X208] ITU-T Recommendation X.208, <em>Specification of Abstract Syntax Notation + One (ASN.1)</em>, 1988. See for instance <a + href="ftp://ftp.neda.com/pub/itu/x.series/x208.ps"> + ftp://ftp.neda.com/pub/itu/x.series/x208.ps</a>. +<p> +<li><a name="X509"></a> +[X509] ITU-T Recommendation X.509, <em>The Directory - Authentication + Framework</em>, 1988. See for instance <a + href="ftp://ftp.bull.com/pub/OSIdirectory/ITUnov96/X.509/97x509final.doc"> + ftp://ftp.bull.com/pub/OSIdirectory/ITUnov96/X.509/97x509final.doc</a>. +<p> +<li><a name="PKCS"></a> +[PKCS] Kaliski, Burton S., Jr., <em>An Overview of the PKCS Standards</em>, An RSA + Laboratories Technical Note, revised November 1, 1993. + See <a href="http://www.rsa.com/rsalabs/pubs/PKCS/"> + http://www.rsa.com/rsalabs/pubs/PKCS/</a>. +<p> +<li><a name="MIME"></a> +[MIME] N. Freed, N. Borenstein, <em>Multipurpose Internet Mail Extensions + (MIME) Part One: Format of Internet Message Bodies</em>, RFC2045. + See for instance <a href="ftp://ftp.isi.edu/in-notes/rfc2045.txt"> + ftp://ftp.isi.edu/in-notes/rfc2045.txt</a>. +<p> +<li><a name="SSL2"></a> +[SSL2] Kipp E.B. Hickman, <em>The SSL Protocol</em>, 1995. + See <a href="http://www.netscape.com/eng/security/SSL_2.html"> + http://www.netscape.com/eng/security/SSL_2.html</a>. +<p> +<li><a name="SSL3"></a> +[SSL3] Alan O. Freier, Philip Karlton, Paul C. Kocher, <em>The SSL Protocol + Version 3.0</em>, 1996. See <a + href="http://www.netscape.com/eng/ssl3/draft302.txt"> + http://www.netscape.com/eng/ssl3/draft302.txt</a>. +<p> +<li><a name="TLS1"></a> +[TLS1] Tim Dierks, Christopher Allen, <em>The TLS Protocol Version 1.0</em>, + 1997. See <a + href="ftp://ftp.ietf.org/internet-drafts/draft-ietf-tls-protocol-06.txt"> + ftp://ftp.ietf.org/internet-drafts/draft-ietf-tls-protocol-06.txt</a>. +</ul> + <p> + <br> + <table summary=""> + <tr> + <td> + <table width="600" border="0" summary=""> + <tr> + <td valign="top" align="left" width="250"> +<a href="ssl_overview.html" onmouseover="ro_imgOver('ro_img_prev_bot', 'previous page'); return true" onmouseout="ro_imgNormal('ro_img_prev_bot'); return true" onfocus="ro_imgOver('ro_img_prev_bot', 'previous page'); return true" onblur="ro_imgNormal('ro_img_prev_bot'); return true"><img name="ro_img_prev_bot" src="ssl_template.navbut-prev-n.gif" alt="previous page" width="70" height="18" border="0"></a><br><font color="#000000">Overview</font> + </td> + <td valign="top" align="right" width="250"> +<a href="ssl_reference.html" onmouseover="ro_imgOver('ro_img_next_bot', 'next page'); return true" onmouseout="ro_imgNormal('ro_img_next_bot'); return true" onfocus="ro_imgOver('ro_img_next_bot', 'next page'); return true" onblur="ro_imgNormal('ro_img_next_bot'); return true"><img name="ro_img_next_bot" src="ssl_template.navbut-next-n.gif" alt="next page" width="70" height="18" border="0"></a><br><font color="#000000">Reference</font> + </td> + </tr> + </table> + </td> + </tr> + <tr> + <td><img src="ssl_template.imgdot-1x1-000000.gif" alt="" width="600" height="2" align="bottom" border="0"></td> + </tr> + <tr> + <td><table width="598" summary=""> + <tr> + <td align="left"><font face="Arial,Helvetica"> + <a href="http://www.modssl.org/">mod_ssl</a> 2.8, User Manual<br> + The Apache Interface to OpenSSL + </font> + </td> + <td align="right"><font face="Arial,Helvetica"> + Copyright © 1998-2001 + <a href="http://www.engelschall.com/">Ralf S. Engelschall</a><br> + All Rights Reserved<br> + </font> + </td> + </tr> + </table> + </td> + </tr> + </table> + </td> +</tr> +</table> +</div> +</body> +</html> diff --git a/docs/manual/ssl/ssl_intro_fig1.gif b/docs/manual/ssl/ssl_intro_fig1.gif Binary files differnew file mode 100644 index 0000000000..3c209864f1 --- /dev/null +++ b/docs/manual/ssl/ssl_intro_fig1.gif diff --git a/docs/manual/ssl/ssl_intro_fig2.gif b/docs/manual/ssl/ssl_intro_fig2.gif Binary files differnew file mode 100644 index 0000000000..26b295a67b --- /dev/null +++ b/docs/manual/ssl/ssl_intro_fig2.gif diff --git a/docs/manual/ssl/ssl_intro_fig3.gif b/docs/manual/ssl/ssl_intro_fig3.gif Binary files differnew file mode 100644 index 0000000000..00a975b5a4 --- /dev/null +++ b/docs/manual/ssl/ssl_intro_fig3.gif diff --git a/docs/manual/style/modulesynopsis.dtd b/docs/manual/style/modulesynopsis.dtd new file mode 100644 index 0000000000..65b3c30a76 --- /dev/null +++ b/docs/manual/style/modulesynopsis.dtd @@ -0,0 +1,109 @@ +<?xml version='1.0' encoding='UTF-8' ?> + +<!ENTITY nbsp " "> + +<!ENTITY % inlinetags "em | strong | code | a | br | directive | module"> + +<!ENTITY % blocktags "p | example | note | table | ul | ol | dl | pre +| blockquote"> + +<!ENTITY % Block "(%blocktags;)*"> + +<!ENTITY % Inline "(#PCDATA | %inlinetags;)*"> + +<!ENTITY % BlockOrInline "(#PCDATA | %inlinetags; | %blocktags;)*"> + +<!ELEMENT modulesynopsis (name , description, status , sourcefile?, +identifier? , compatibility? , summary? , seealso* , section*, +directivesynopsis+)> + +<!ELEMENT directivesynopsis (name , description? , syntax? , default? +, contextlist? , override? , modulelist?, compatibility? , usage?, seealso*)> + +<!ELEMENT name (#PCDATA)> + +<!ELEMENT status (#PCDATA)> + +<!ELEMENT identifier (#PCDATA)> + +<!ELEMENT sourcefile (#PCDATA)> + +<!ELEMENT compatibility %Inline;> + +<!ELEMENT description %Inline;> + +<!ELEMENT section (section | title | %blocktags;)*> + +<!ELEMENT module (#PCDATA)> + +<!ELEMENT example (#PCDATA | title | %inlinetags; | %blocktags;)*> + +<!ELEMENT seealso %Inline;> + +<!ELEMENT a %Inline;> + +<!ATTLIST a href CDATA #REQUIRED > + +<!ATTLIST directivesynopsis type CDATA #IMPLIED + location CDATA #IMPLIED > + +<!ELEMENT syntax %Inline;> + +<!ELEMENT default (#PCDATA)> + +<!ELEMENT contextlist (context+)+> + +<!ELEMENT modulelist (module)+> + +<!ELEMENT context (#PCDATA)> + +<!ELEMENT override (#PCDATA)> + +<!ELEMENT note (#PCDATA | title | %inlinetags; | %blocktags;)*> +<!ATTLIST note type CDATA #IMPLIED> + +<!ELEMENT title %Inline;> + +<!ELEMENT p %Inline;> + +<!ELEMENT ul (li+)> + +<!ELEMENT ol (li+)> + +<!ELEMENT li %BlockOrInline;> + +<!ELEMENT strong %Inline;> + +<!ELEMENT br EMPTY> + +<!ELEMENT table (tr)+> + +<!ELEMENT tr (td)+> + +<!ELEMENT td %BlockOrInline;> + +<!ATTLIST td colspan CDATA #IMPLIED + rowspan CDATA #IMPLIED + class CDATA #IMPLIED > +<!ELEMENT directive (#PCDATA)> + +<!ATTLIST directive module CDATA #IMPLIED + type CDATA #IMPLIED > + +<!ELEMENT code %Inline;> + +<!ELEMENT dl (dd | dt)+> + +<!ELEMENT dt %Inline;> + +<!ELEMENT dd %BlockOrInline;> + +<!ELEMENT em %Inline;> + +<!ELEMENT usage %Block;> + +<!ELEMENT summary %Block;> + +<!ELEMENT blockquote %BlockOrInline;> + +<!ELEMENT pre %Inline;>
\ No newline at end of file diff --git a/modules/NWGNUmakefile b/modules/NWGNUmakefile new file mode 100644 index 0000000000..ca36291d9e --- /dev/null +++ b/modules/NWGNUmakefile @@ -0,0 +1,35 @@ +# +# Declare the sub-directories to be built here +# + +SUBDIRS = \ + aaa \ + dav\main \ + dav\fs \ + echo \ + generators \ + mappers \ + metadata \ + proxy \ + $(EOLIST) + +# +# Get the 'head' of the build environment. This includes default targets and +# paths to tools +# + +include $(AP_WORK)\build\NWGNUhead.inc + +# +# build this level's files + +ifeq "$(wildcard NWGNUmakefile.mak)" "NWGNUmakefile.mak" +include NWGNUmakefile.mak +endif + +# +# You can use this target if all that is needed is to copy files to the +# installation area +# +install :: nlms FORCE + diff --git a/modules/aaa/NWGNUmakefile b/modules/aaa/NWGNUmakefile new file mode 100644 index 0000000000..fc72c7355e --- /dev/null +++ b/modules/aaa/NWGNUmakefile @@ -0,0 +1,246 @@ +# +# Declare the sub-directories to be built here +# + +SUBDIRS = \ + $(EOLIST) + +# +# Get the 'head' of the build environment. This includes default targets and +# paths to tools +# + +include $(AP_WORK)\build\NWGNUhead.inc + +# +# build this level's files + +# +# Make sure all needed macro's are defined +# + +# +# These directories will be at the beginning of the include list, followed by +# INCDIRS +# +XINCDIRS += \ + $(EOLIST) + +# +# These flags will come after CFLAGS +# +XCFLAGS += \ + $(EOLIST) + +# +# These defines will come after DEFINES +# +XDEFINES += \ + $(EOLIST) + +# +# These flags will be added to the link.opt file +# +XLFLAGS += \ + $(EOLIST) + +# +# These values will be appended to the correct variables based on the value of +# RELEASE +# +ifeq "$(RELEASE)" "debug" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "noopt" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "release" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +# +# These are used by the link target if an NLM is being generated +# This is used by the link 'name' directive to name the nlm. If left blank +# TARGET_nlm (see below) will be used. +# +NLM_NAME = + +# +# This is used by the link '-desc ' directive. +# If left blank, NLM_NAME will be used. +# +NLM_DESCRIPTION = + +# +# This is used by the '-threadname' directive. If left blank, +# NLM_NAME Thread will be used. +# +NLM_THREAD_NAME = + +# +# If this is specified, it will override VERSION value in +# $(AP_WORK)\build\NWGNUenvironment.inc +# +NLM_VERSION = + +# +# If this is specified, it will override the default of 64K +# +NLM_STACK_SIZE = + + +# +# If this is specified it will be used by the link '-entry' directive +# +NLM_ENTRY_SYM = + +# +# If this is specified it will be used by the link '-exit' directive +# +NLM_EXIT_SYM = + +# +# If this is specified it will be used by the link '-check' directive +# +NLM_CHECK_SYM = + +# +# If these are specified it will be used by the link '-flags' directive +# +NLM_FLAGS = + +# +# If this is specified it will be linked in with the XDCData option in the def +# file instead of the default of $(NWOS)/apache.xdc. XDCData can be disabled +# by setting APACHE_UNIPROC in the environment +# +XDCDATA = + +# +# If there is an NLM target, put it here +# +TARGET_nlm = \ + $(OBJDIR)/authanon.nlm \ + $(OBJDIR)/authdbm.nlm \ + $(OBJDIR)/digest.nlm \ + $(EOLIST) + +# +# If there is an LIB target, put it here +# +TARGET_lib = \ + $(EOLIST) + +# +# These are the OBJ files needed to create the NLM target above. +# Paths must all use the '/' character +# +FILES_nlm_objs = \ + $(EOLIST) + +# +# These are the LIB files needed to create the NLM target above. +# These will be added as a library command in the link.opt file. +# +FILES_nlm_libs = \ + $(EOLIST) + +# +# These are the modules that the above NLM target depends on to load. +# These will be added as a module command in the link.opt file. +# +FILES_nlm_modules = \ + $(EOLIST) + +# +# If the nlm has a msg file, put it's path here +# +FILE_nlm_msg = + +# +# If the nlm has a hlp file put it's path here +# +FILE_nlm_hlp = + +# +# If this is specified, it will override $(NWOS)\copyright.txt. +# +FILE_nlm_copyright = + +# +# Any additional imports go here +# +FILES_nlm_Ximports = \ + $(EOLIST) + +# +# Any symbols exported to here +# +FILES_nlm_exports = \ + $(EOLIST) + +# +# These are the OBJ files needed to create the LIB target above. +# Paths must all use the '/' character +# +FILES_lib_objs = \ + $(EOLIST) + +# +# implement targets and dependancies (leave this section alone) +# + +libs :: $(OBJDIR) $(TARGET_lib) + +nlms :: libs $(TARGET_nlm) + +# +# Updated this target to create necessary directories and copy files to the +# correct place. (See $(AP_WORK)\build\NWGNUhead.inc for examples) +# +install :: nlms FORCE + copy $(OBJDIR)\*.nlm $(INSTALL)\Apache2\modules\*.* + +# +# Any specialized rules here +# + +# +# Include the 'tail' makefile that has targets that depend on variables defined +# in this makefile +# + +include $(AP_WORK)\build\NWGNUtail.inc + diff --git a/modules/arch/netware/libprews.c b/modules/arch/netware/libprews.c new file mode 100644 index 0000000000..efa475fc69 --- /dev/null +++ b/modules/arch/netware/libprews.c @@ -0,0 +1,54 @@ +/*------------------------------------------------------------------ + These functions are to be called when the shared NLM starts and + stops. By using these functions instead of defining a main() + and calling ExitThread(TSR_THREAD, 0), the load time of the + shared NLM is faster and memory size reduced. + + You may also want to override these in your own Apache module + to do any cleanup other than the mechanism Apache modules + provide. +------------------------------------------------------------------*/ +#include <netware.h> +//#include "stddef.h" +#include "ws2nlm.h" + +int _NonAppStart +( + void *NLMHandle, + void *errorScreen, + const char *cmdLine, + const char *loadDirPath, + size_t uninitializedDataLength, + void *NLMFileHandle, + int (*readRoutineP)( int conn, void *fileHandle, size_t offset, + size_t nbytes, size_t *bytesRead, void *buffer ), + size_t customDataOffset, + size_t customDataSize, + int messageCount, + const char **messages +) +{ +#pragma unused(cmdLine) +#pragma unused(loadDirPath) +#pragma unused(uninitializedDataLength) +#pragma unused(NLMFileHandle) +#pragma unused(readRoutineP) +#pragma unused(customDataOffset) +#pragma unused(customDataSize) +#pragma unused(messageCount) +#pragma unused(messages) + + WSADATA wsaData; + + return WSAStartup((WORD) MAKEWORD(2, 0), &wsaData); +} + +void _NonAppStop( void ) +{ + WSACleanup(); +} + +int _NonAppCheckUnload( void ) +{ + return 0; +} diff --git a/modules/arch/netware/mod_auth_digest.def b/modules/arch/netware/mod_auth_digest.def new file mode 100644 index 0000000000..6a3aa085d2 --- /dev/null +++ b/modules/arch/netware/mod_auth_digest.def @@ -0,0 +1 @@ +EXPORT auth_digest_module diff --git a/modules/arch/netware/mod_cache.def b/modules/arch/netware/mod_cache.def new file mode 100644 index 0000000000..c7ab6ca4e9 --- /dev/null +++ b/modules/arch/netware/mod_cache.def @@ -0,0 +1,6 @@ +EXPORT cache_module +EXPORT cache_hook_create_entity +EXPORT cache_hook_open_entity +EXPORT cache_hook_remove_url + + diff --git a/modules/arch/netware/mod_cern_meta.def b/modules/arch/netware/mod_cern_meta.def new file mode 100644 index 0000000000..5638325bbd --- /dev/null +++ b/modules/arch/netware/mod_cern_meta.def @@ -0,0 +1 @@ +EXPORT cern_meta_module diff --git a/modules/arch/netware/mod_dav.def b/modules/arch/netware/mod_dav.def new file mode 100644 index 0000000000..fb56c92fc6 --- /dev/null +++ b/modules/arch/netware/mod_dav.def @@ -0,0 +1,3 @@ +EXPORT dav_module +EXPORT @dav.imp + diff --git a/modules/arch/netware/mod_echo.def b/modules/arch/netware/mod_echo.def new file mode 100644 index 0000000000..694135a52c --- /dev/null +++ b/modules/arch/netware/mod_echo.def @@ -0,0 +1,2 @@ +EXPORT echo_module + diff --git a/modules/arch/netware/mod_expires.def b/modules/arch/netware/mod_expires.def new file mode 100644 index 0000000000..bc416630b0 --- /dev/null +++ b/modules/arch/netware/mod_expires.def @@ -0,0 +1 @@ +EXPORT expires_module diff --git a/modules/arch/netware/mod_file_cache.def b/modules/arch/netware/mod_file_cache.def new file mode 100644 index 0000000000..8ab98cfb22 --- /dev/null +++ b/modules/arch/netware/mod_file_cache.def @@ -0,0 +1,2 @@ +EXPORT file_cache_module + diff --git a/modules/arch/netware/mod_headers.def b/modules/arch/netware/mod_headers.def new file mode 100644 index 0000000000..2fe35a858b --- /dev/null +++ b/modules/arch/netware/mod_headers.def @@ -0,0 +1 @@ +EXPORT headers_module diff --git a/modules/arch/netware/mod_info.def b/modules/arch/netware/mod_info.def new file mode 100644 index 0000000000..ce71cb37cf --- /dev/null +++ b/modules/arch/netware/mod_info.def @@ -0,0 +1 @@ +EXPORT info_module diff --git a/modules/arch/netware/mod_mem_cache.def b/modules/arch/netware/mod_mem_cache.def new file mode 100644 index 0000000000..ce8b67a5ca --- /dev/null +++ b/modules/arch/netware/mod_mem_cache.def @@ -0,0 +1,5 @@ +IMPORT cache_hook_create_entity +IMPORT cache_hook_open_entity +IMPORT cache_hook_remove_url +EXPORT mem_cache_module + diff --git a/modules/arch/netware/mod_mime_magic.def b/modules/arch/netware/mod_mime_magic.def new file mode 100644 index 0000000000..95307476de --- /dev/null +++ b/modules/arch/netware/mod_mime_magic.def @@ -0,0 +1 @@ +EXPORT mime_magic_module diff --git a/modules/arch/netware/mod_nw_ssl.c b/modules/arch/netware/mod_nw_ssl.c new file mode 100644 index 0000000000..c29d6bda31 --- /dev/null +++ b/modules/arch/netware/mod_nw_ssl.c @@ -0,0 +1,462 @@ +/* ==================================================================== + * The Apache Software License, Version 1.1 + * + * Copyright (c) 2000 The Apache Software Foundation. All rights + * reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * 3. The end-user documentation included with the redistribution, + * if any, must include the following acknowledgment: + * "This product includes software developed by the + * Apache Software Foundation (http://www.apache.org/)." + * Alternately, this acknowledgment may appear in the software itself, + * if and wherever such third-party acknowledgments normally appear. + * + * 4. The names "Apache" and "Apache Software Foundation" must + * not be used to endorse or promote products derived from this + * software without prior written permission. For written + * permission, please contact apache@apache.org. + * + * 5. Products derived from this software may not be called "Apache", + * nor may "Apache" appear in their name, without prior written + * permission of the Apache Software Foundation. + * + * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED + * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR + * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF + * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND + * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, + * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT + * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + * SUCH DAMAGE. + * ==================================================================== + * + * This software consists of voluntary contributions made by many + * individuals on behalf of the Apache Software Foundation. For more + * information on the Apache Software Foundation, please see + * <http://www.apache.org/>. + * + * Portions of this software are based upon public domain software + * originally written at the National Center for Supercomputing Applications, + * University of Illinois, Urbana-Champaign. + */ + +/* + * mod_tls.c - Apache SSL/TLS module for NetWare by Mike Gardiner. + * + * This module gives Apache the ability to do SSL/TLS with a minimum amount + * of effort. All of the SSL/TLS logic is already on NetWare versions 5 and + * above and is interfaced through WinSock on NetWare. As you can see in + * the code below SSL/TLS sockets can be created with three WinSock calls. + * + * To load, simply place the module in the modules directory under the main + * apache tree. Then add a "SecureListen" with two arguments. The first + * argument is an address and/or port. The second argument is the key pair + * name as created in ConsoleOne. + * + * Examples: + * + * SecureListen 443 "SSL CertificateIP" + * SecureListen 123.45.67.89:443 mycert + */ + +#define WS_SSL + +#define MAX_ADDRESS 512 +#define MAX_KEY 80 + + +#include "httpd.h" +#include "http_config.h" +#include "http_log.h" +#include "ap_listen.h" +#include "apr_strings.h" + +module AP_MODULE_DECLARE_DATA nwssl_module; + +typedef struct NWSSLSrvConfigRec NWSSLSrvConfigRec; +typedef struct seclisten_rec seclisten_rec; + +struct seclisten_rec { + seclisten_rec *next; + struct sockaddr_in local_addr; /* local IP address and port */ + int fd; + int used; /* Only used during restart */ + char key[MAX_KEY]; + int mutual; + char *addr; + int port; +}; + +struct NWSSLSrvConfigRec { + apr_table_t *sltable; +}; + +static seclisten_rec* ap_seclisteners = NULL; + +#define get_nwssl_cfg(srv) (NWSSLSrvConfigRec *) ap_get_module_config(srv->module_config, &nwssl_module) + +/* + * Parses a host of the form <address>[:port] + * :port is permitted if 'port' is not NULL + */ +static unsigned long parse_addr(const char *w, unsigned short *ports) +{ + struct hostent *hep; + unsigned long my_addr; + char *p; + + p = strchr(w, ':'); + if (ports != NULL) { + *ports = 0; + if (p != NULL && strcmp(p + 1, "*") != 0) + *ports = atoi(p + 1); + } + + if (p != NULL) + *p = '\0'; + if (strcmp(w, "*") == 0) { + if (p != NULL) + *p = ':'; + return htonl(INADDR_ANY); + } + + my_addr = apr_inet_addr((char *)w); + if (my_addr != INADDR_NONE) { + if (p != NULL) + *p = ':'; + return my_addr; + } + + hep = gethostbyname(w); + + if ((!hep) || (hep->h_addrtype != AF_INET || !hep->h_addr_list[0])) { + fprintf(stderr, "Cannot resolve host name %s --- exiting!\n", w); + exit(1); + } + + if (hep->h_addr_list[1]) { + fprintf(stderr, "Host %s has multiple addresses ---\n", w); + fprintf(stderr, "you must choose one explicitly for use as\n"); + fprintf(stderr, "a secure port. Exiting!!!\n"); + exit(1); + } + + if (p != NULL) + *p = ':'; + + return ((struct in_addr *) (hep->h_addr))->s_addr; +} + +static int find_secure_listener(seclisten_rec *lr) +{ + seclisten_rec *sl; + + for (sl = ap_seclisteners; sl; sl = sl->next) { + if (!memcmp(&sl->local_addr, &lr->local_addr, sizeof(sl->local_addr))) { + sl->used = 1; + return sl->fd; + } + } + return -1; +} + + +static int make_secure_socket(apr_pool_t *pconf, const struct sockaddr_in *server, + char* key, int mutual, server_rec *server_conf) +{ + int s; + int one = 1; + char addr[MAX_ADDRESS]; + struct sslserveropts opts; + unsigned int optParam; + WSAPROTOCOL_INFO SecureProtoInfo; + int no = 1; + + if (server->sin_addr.s_addr != htonl(INADDR_ANY)) + apr_snprintf(addr, sizeof(addr), "address %s port %d", + inet_ntoa(server->sin_addr), ntohs(server->sin_port)); + else + apr_snprintf(addr, sizeof(addr), "port %d", ntohs(server->sin_port)); + + /* note that because we're about to slack we don't use psocket */ + memset(&SecureProtoInfo, 0, sizeof(WSAPROTOCOL_INFO)); + + SecureProtoInfo.iAddressFamily = AF_INET; + SecureProtoInfo.iSocketType = SOCK_STREAM; + SecureProtoInfo.iProtocol = IPPROTO_TCP; + SecureProtoInfo.iSecurityScheme = SECURITY_PROTOCOL_SSL; + + s = WSASocket(AF_INET, SOCK_STREAM, IPPROTO_TCP, + (LPWSAPROTOCOL_INFO)&SecureProtoInfo, 0, 0); + + if (s == INVALID_SOCKET) { + errno = WSAGetLastError(); + ap_log_error(APLOG_MARK, APLOG_CRIT, errno, server_conf, + "make_secure_socket: failed to get a socket for %s", addr); + return -1; + } + + if (!mutual) { + optParam = SO_SSL_ENABLE | SO_SSL_SERVER; + + if (WSAIoctl(s, SO_SSL_SET_FLAGS, (char *)&optParam, + sizeof(optParam), NULL, 0, NULL, NULL, NULL)) { + errno = WSAGetLastError(); + ap_log_error(APLOG_MARK, APLOG_CRIT, errno, server_conf, + "make_secure_socket: for %s, WSAIoctl: (SO_SSL_SET_FLAGS)", addr); + return -1; + } + } + + opts.cert = key; + opts.certlen = strlen(key); + opts.sidtimeout = 0; + opts.sidentries = 0; + opts.siddir = NULL; + + if (WSAIoctl(s, SO_SSL_SET_SERVER, (char *)&opts, sizeof(opts), + NULL, 0, NULL, NULL, NULL) != 0) { + errno = WSAGetLastError(); + ap_log_error(APLOG_MARK, APLOG_CRIT, errno, server_conf, + "make_secure_socket: for %s, WSAIoctl: (SO_SSL_SET_SERVER)", addr); + return -1; + } + + if (mutual) { + optParam = 0x07; // SO_SSL_AUTH_CLIENT + + if(WSAIoctl(s, SO_SSL_SET_FLAGS, (char*)&optParam, + sizeof(optParam), NULL, 0, NULL, NULL, NULL)) { + errno = WSAGetLastError(); + ap_log_error( APLOG_MARK, APLOG_CRIT, errno, server_conf, + "make_secure_socket: for %s, WSAIoctl: (SO_SSL_SET_FLAGS)", addr ); + return -1; + } + } + + return s; +} + +static const char *set_secure_listener(cmd_parms *cmd, void *dummy, + const char *ips, const char* key, + const char* mutual) +{ + NWSSLSrvConfigRec* sc = get_nwssl_cfg(cmd->server); + const char *err = ap_check_cmd_context(cmd, GLOBAL_ONLY); + char *ports, *addr; + unsigned short port; + seclisten_rec *new; + + + if (err != NULL) + return err; + + ports = strchr(ips, ':'); + + if (ports != NULL) { + if (ports == ips) + return "Missing IP address"; + else if (ports[1] == '\0') + return "Address must end in :<port-number>"; + + *(ports++) = '\0'; + } + else { + ports = (char*)ips; + } + + new = apr_pcalloc(cmd->pool, sizeof(seclisten_rec)); + new->local_addr.sin_family = AF_INET; + + if (ports == ips) { + new->local_addr.sin_addr.s_addr = htonl(INADDR_ANY); + addr = apr_pstrdup(cmd->pool, "0.0.0.0"); + } + else { + new->local_addr.sin_addr.s_addr = parse_addr(ips, NULL); + addr = apr_pstrdup(cmd->pool, ips); + } + + port = atoi(ports); + + if (!port) + return "Port must be numeric"; + + apr_table_set(sc->sltable, ports, "T"); + + new->local_addr.sin_port = htons(port); + new->fd = -1; + new->used = 0; + new->next = ap_seclisteners; + strcpy(new->key, key); + new->mutual = (mutual) ? 1 : 0; + new->addr = addr; + new->port = port; + ap_seclisteners = new; + return NULL; +} + +static apr_status_t nwssl_socket_cleanup(void *data) +{ + ap_listen_rec* slr = (ap_listen_rec*)data; + ap_listen_rec* lr; + + /* Remove our secure listener from the listener list */ + for (lr = ap_listeners; lr; lr = lr->next) { + /* slr is at the head of the list */ + if (lr == slr) { + ap_listeners = slr->next; + break; + } + /* slr is somewhere in between or at the end*/ + if (lr->next == slr) { + lr->next = slr->next; + break; + } + } + return APR_SUCCESS; +} + +static void nwssl_pre_config(apr_pool_t *pconf, apr_pool_t *plog, + apr_pool_t *ptemp) +{ + ap_seclisteners = NULL; +} + +static void nwssl_post_config(apr_pool_t *pconf, apr_pool_t *plog, + apr_pool_t *ptemp, server_rec *s) +{ + seclisten_rec* sl; + ap_listen_rec* lr; + apr_socket_t* sd; + apr_status_t status; + + for (sl = ap_seclisteners; sl != NULL; sl = sl->next) { + sl->fd = find_secure_listener(sl); + + if (sl->fd < 0) + sl->fd = make_secure_socket(pconf, &sl->local_addr, sl->key, sl->mutual, s); + + if (sl->fd >= 0) { + apr_os_sock_info_t sock_info; + + sock_info.os_sock = &(sl->fd); + sock_info.local = (struct sockaddr*)&(sl->local_addr); + sock_info.remote = NULL; + sock_info.family = APR_INET; + sock_info.type = SOCK_STREAM; + + apr_os_sock_make(&sd, &sock_info, pconf); + + lr = apr_pcalloc(pconf, sizeof(ap_listen_rec)); + + if (lr) { + lr->sd = sd; + if ((status = apr_sockaddr_info_get(&lr->bind_addr, sl->addr, APR_UNSPEC, sl->port, 0, + pconf)) != APR_SUCCESS) { + ap_log_perror(APLOG_MARK, APLOG_CRIT, status, pconf, + "alloc_listener: failed to set up sockaddr for %s:%d", sl->addr, sl->port); + exit(1); + } + lr->next = ap_listeners; + ap_listeners = lr; + apr_pool_cleanup_register(pconf, lr, nwssl_socket_cleanup, apr_pool_cleanup_null); + } + } else { + exit(1); + } + } +} + +static void *nwssl_config_server_create(apr_pool_t *p, server_rec *s) +{ + NWSSLSrvConfigRec *new = apr_palloc(p, sizeof(NWSSLSrvConfigRec)); + new->sltable = apr_table_make(p, 5); + return new; +} + +static void *nwssl_config_server_merge(apr_pool_t *p, void *basev, void *addv) +{ + NWSSLSrvConfigRec *base = (NWSSLSrvConfigRec *)basev; + NWSSLSrvConfigRec *add = (NWSSLSrvConfigRec *)addv; + NWSSLSrvConfigRec *merged = (NWSSLSrvConfigRec *)apr_palloc(p, sizeof(NWSSLSrvConfigRec)); + return merged; +} + +static int isSecure (const request_rec *r) +{ + NWSSLSrvConfigRec *sc = get_nwssl_cfg(r->server); + const char *s_secure = NULL; + char port[8]; + int ret = 0; + + itoa(((r->connection)->local_addr)->port, port, 10); + s_secure = apr_table_get(sc->sltable, port); + if (s_secure) + ret = 1; + + return ret; +} + +static int nwssl_hook_Fixup(request_rec *r) +{ + apr_table_t *e = r->subprocess_env; + if (!isSecure(r)) + return DECLINED; + + apr_table_set(e, "HTTPS", "on"); + + return DECLINED; +} + +static const char *nwssl_hook_http_method (const request_rec *r) +{ + if (isSecure(r)) + return "https"; + + return NULL; +} + +static const command_rec nwssl_module_cmds[] = +{ + AP_INIT_TAKE23("SecureListen", set_secure_listener, NULL, RSRC_CONF, + "specify an address and/or port with a key pair name.\n" + "Optional third parameter of MUTUAL configures the port for mutual authentication."), + {NULL} +}; + +static void register_hooks(apr_pool_t *p) +{ + ap_hook_pre_config(nwssl_pre_config, NULL, NULL, APR_HOOK_MIDDLE); + ap_hook_post_config(nwssl_post_config, NULL, NULL, APR_HOOK_MIDDLE); + ap_hook_fixups(nwssl_hook_Fixup, NULL, NULL, APR_HOOK_MIDDLE); + ap_hook_http_method(nwssl_hook_http_method, NULL,NULL, APR_HOOK_MIDDLE); +} + +module AP_MODULE_DECLARE_DATA nwssl_module = +{ + STANDARD20_MODULE_STUFF, + NULL, /* dir config creater */ + NULL, /* dir merger --- default is to override */ + nwssl_config_server_create, /* server config */ + nwssl_config_server_merge, /* merge server config */ + nwssl_module_cmds, /* command apr_table_t */ + register_hooks +}; + diff --git a/modules/arch/netware/mod_proxy.def b/modules/arch/netware/mod_proxy.def new file mode 100644 index 0000000000..6e51eedb50 --- /dev/null +++ b/modules/arch/netware/mod_proxy.def @@ -0,0 +1 @@ +EXPORT proxy_module diff --git a/modules/arch/netware/mod_rewrite.def b/modules/arch/netware/mod_rewrite.def new file mode 100644 index 0000000000..cfdcf6b132 --- /dev/null +++ b/modules/arch/netware/mod_rewrite.def @@ -0,0 +1 @@ +EXPORT rewrite_module diff --git a/modules/arch/netware/mod_speling.def b/modules/arch/netware/mod_speling.def new file mode 100644 index 0000000000..3d45a6aa1a --- /dev/null +++ b/modules/arch/netware/mod_speling.def @@ -0,0 +1 @@ +EXPORT speling_module diff --git a/modules/arch/netware/mod_status.def b/modules/arch/netware/mod_status.def new file mode 100644 index 0000000000..9a5a32d46c --- /dev/null +++ b/modules/arch/netware/mod_status.def @@ -0,0 +1,2 @@ +EXPORT status_module + diff --git a/modules/arch/netware/mod_unique_id.def b/modules/arch/netware/mod_unique_id.def new file mode 100644 index 0000000000..0b72c1ecc0 --- /dev/null +++ b/modules/arch/netware/mod_unique_id.def @@ -0,0 +1 @@ +EXPORT unique_id_module diff --git a/modules/arch/netware/mod_usertrack.def b/modules/arch/netware/mod_usertrack.def new file mode 100644 index 0000000000..7264c41ecf --- /dev/null +++ b/modules/arch/netware/mod_usertrack.def @@ -0,0 +1 @@ +EXPORT usertrack_module diff --git a/modules/arch/netware/mod_vhost_alias.def b/modules/arch/netware/mod_vhost_alias.def new file mode 100644 index 0000000000..574b85f987 --- /dev/null +++ b/modules/arch/netware/mod_vhost_alias.def @@ -0,0 +1,2 @@ +EXPORT vhost_alias_module + diff --git a/modules/arch/netware/moddavfs.def b/modules/arch/netware/moddavfs.def new file mode 100644 index 0000000000..67ec311758 --- /dev/null +++ b/modules/arch/netware/moddavfs.def @@ -0,0 +1 @@ +EXPORT dav_fs_module diff --git a/modules/arch/win32/.cvsignore b/modules/arch/win32/.cvsignore new file mode 100644 index 0000000000..14ac4568b5 --- /dev/null +++ b/modules/arch/win32/.cvsignore @@ -0,0 +1,4 @@ +Debug +Release +*.mak +*.rc diff --git a/modules/arch/win32/mod_isapi.dsp b/modules/arch/win32/mod_isapi.dsp new file mode 100644 index 0000000000..bf9fb802fa --- /dev/null +++ b/modules/arch/win32/mod_isapi.dsp @@ -0,0 +1,128 @@ +# Microsoft Developer Studio Project File - Name="mod_isapi" - Package Owner=<4> +# Microsoft Developer Studio Generated Build File, Format Version 6.00 +# ** DO NOT EDIT ** + +# TARGTYPE "Win32 (x86) Dynamic-Link Library" 0x0102 + +CFG=mod_isapi - Win32 Release +!MESSAGE This is not a valid makefile. To build this project using NMAKE, +!MESSAGE use the Export Makefile command and run +!MESSAGE +!MESSAGE NMAKE /f "mod_isapi.mak". +!MESSAGE +!MESSAGE You can specify a configuration when running NMAKE +!MESSAGE by defining the macro CFG on the command line. For example: +!MESSAGE +!MESSAGE NMAKE /f "mod_isapi.mak" CFG="mod_isapi - Win32 Release" +!MESSAGE +!MESSAGE Possible choices for configuration are: +!MESSAGE +!MESSAGE "mod_isapi - Win32 Release" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE "mod_isapi - Win32 Debug" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE + +# Begin Project +# PROP AllowPerConfigDependencies 0 +# PROP Scc_ProjName "" +# PROP Scc_LocalPath "" +CPP=cl.exe +MTL=midl.exe +RSC=rc.exe + +!IF "$(CFG)" == "mod_isapi - Win32 Release" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 0 +# PROP BASE Output_Dir "Release" +# PROP BASE Intermediate_Dir "Release" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 0 +# PROP Output_Dir "Release" +# PROP Intermediate_Dir "Release" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MD /W3 /O2 /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /FD /c +# ADD CPP /nologo /MD /W3 /O2 /I "../../../include" /I "../../../srclib/apr/include" /I "../../../srclib/apr-util/include" /D "NDEBUG" /D "WIN32" /D "_WINDOWS" /Fd"Release\mod_isapi" /FD /c +# ADD BASE MTL /nologo /D "NDEBUG" /win32 +# ADD MTL /nologo /D "NDEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x409 /d "NDEBUG" +# ADD RSC /l 0x409 /d "NDEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib ws2_32.lib mswsock.lib /nologo /subsystem:windows /dll /map /machine:I386 /out:"Release/mod_isapi.so" /base:@..\..\..\os\win32\BaseAddr.ref,mod_isapi +# ADD LINK32 kernel32.lib ws2_32.lib mswsock.lib /nologo /subsystem:windows /dll /map /machine:I386 /out:"Release/mod_isapi.so" /base:@..\..\..\os\win32\BaseAddr.ref,mod_isapi + +!ELSEIF "$(CFG)" == "mod_isapi - Win32 Debug" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 1 +# PROP BASE Output_Dir "Debug" +# PROP BASE Intermediate_Dir "Debug" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 1 +# PROP Output_Dir "Debug" +# PROP Intermediate_Dir "Debug" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MDd /W3 /GX /Zi /Od /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /FD /c +# ADD CPP /nologo /MDd /W3 /GX /Zi /Od /I "../../../include" /I "../../../srclib/apr/include" /I "../../../srclib/apr-util/include" /D "_DEBUG" /D "WIN32" /D "_WINDOWS" /Fd"Debug\mod_isapi" /FD /c +# ADD BASE MTL /nologo /D "_DEBUG" /win32 +# ADD MTL /nologo /D "_DEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x409 /d "_DEBUG" +# ADD RSC /l 0x409 /d "_DEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib ws2_32.lib mswsock.lib /nologo /subsystem:windows /dll /incremental:no /map /debug /machine:I386 /out:"Debug/mod_isapi.so" /base:@..\..\..\os\win32\BaseAddr.ref,mod_isapi +# ADD LINK32 kernel32.lib ws2_32.lib mswsock.lib /nologo /subsystem:windows /dll /map /debug /machine:I386 /out:"Debug/mod_isapi.so" /base:@..\..\..\os\win32\BaseAddr.ref,mod_isapi + +!ENDIF + +# Begin Target + +# Name "mod_isapi - Win32 Release" +# Name "mod_isapi - Win32 Debug" +# Begin Source File + +SOURCE=.\mod_isapi.c +# End Source File +# Begin Source File + +SOURCE=.\mod_isapi.rc +# End Source File +# Begin Source File + +SOURCE=..\..\..\build\win32\win32ver.awk + +!IF "$(CFG)" == "mod_isapi - Win32 Release" + +# PROP Ignore_Default_Tool 1 +# Begin Custom Build - Creating Version Resource +InputPath=..\..\..\build\win32\win32ver.awk + +".\mod_isapi.rc" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)" + awk -f ../../../build/win32/win32ver.awk mod_isapi "isapi_module for Apache" ../../../include/ap_release.h > .\mod_isapi.rc + +# End Custom Build + +!ELSEIF "$(CFG)" == "mod_isapi - Win32 Debug" + +# PROP Ignore_Default_Tool 1 +# Begin Custom Build - Creating Version Resource +InputPath=..\..\..\build\win32\win32ver.awk + +".\mod_isapi.rc" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)" + awk -f ../../../build/win32/win32ver.awk mod_isapi "isapi_module for Apache" ../../../include/ap_release.h > .\mod_isapi.rc + +# End Custom Build + +!ENDIF + +# End Source File +# End Target +# End Project diff --git a/modules/arch/win32/mod_win32.c b/modules/arch/win32/mod_win32.c new file mode 100644 index 0000000000..77fb0cdec0 --- /dev/null +++ b/modules/arch/win32/mod_win32.c @@ -0,0 +1,510 @@ +/* ==================================================================== + * The Apache Software License, Version 1.1 + * + * Copyright (c) 2000-2001 The Apache Software Foundation. All rights + * reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * 3. The end-user documentation included with the redistribution, + * if any, must include the following acknowledgment: + * "This product includes software developed by the + * Apache Software Foundation (http://www.apache.org/)." + * Alternately, this acknowledgment may appear in the software itself, + * if and wherever such third-party acknowledgments normally appear. + * + * 4. The names "Apache" and "Apache Software Foundation" must + * not be used to endorse or promote products derived from this + * software without prior written permission. For written + * permission, please contact apache@apache.org. + * + * 5. Products derived from this software may not be called "Apache", + * nor may "Apache" appear in their name, without prior written + * permission of the Apache Software Foundation. + * + * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED + * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR + * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF + * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND + * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, + * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT + * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + * SUCH DAMAGE. + * ==================================================================== + * + * This software consists of voluntary contributions made by many + * individuals on behalf of the Apache Software Foundation. For more + * information on the Apache Software Foundation, please see + * <http://www.apache.org/>. + * + * Portions of this software are based upon public domain software + * originally written at the National Center for Supercomputing Applications, + * University of Illinois, Urbana-Champaign. + */ + + +#include "apr_strings.h" +#include "apr_portable.h" +#include "apr_buckets.h" +#include "ap_config.h" +#include "httpd.h" +#include "http_config.h" +#include "http_core.h" +#include "http_protocol.h" +#include "http_request.h" +#include "http_log.h" +#include "util_script.h" +#include "mod_core.h" +#include "apr_optional.h" +#include "apr_lib.h" + +#ifdef WIN32 + +/* + * CGI Script stuff for Win32... + */ +typedef enum { eFileTypeUNKNOWN, eFileTypeBIN, eFileTypeEXE16, eFileTypeEXE32, + eFileTypeSCRIPT } file_type_e; +typedef enum { INTERPRETER_SOURCE_UNSET, INTERPRETER_SOURCE_REGISTRY_STRICT, + INTERPRETER_SOURCE_REGISTRY, INTERPRETER_SOURCE_SHEBANG + } interpreter_source_e; +AP_DECLARE(file_type_e) ap_get_win32_interpreter(const request_rec *, + char **interpreter, + char **arguments); + +module AP_MODULE_DECLARE_DATA win32_module; + +typedef struct { + /* Where to find interpreter to run scripts */ + interpreter_source_e script_interpreter_source; +} win32_dir_conf; + +static void *create_win32_dir_config(apr_pool_t *p, char *dir) +{ + win32_dir_conf *conf = (win32_dir_conf*)apr_palloc(p, sizeof(win32_dir_conf)); + conf->script_interpreter_source = INTERPRETER_SOURCE_UNSET; + return conf; +} + +static void *merge_win32_dir_configs(apr_pool_t *p, void *basev, void *addv) +{ + win32_dir_conf *new = (win32_dir_conf *) apr_pcalloc(p, sizeof(win32_dir_conf)); + win32_dir_conf *base = (win32_dir_conf *) basev; + win32_dir_conf *add = (win32_dir_conf *) addv; + + new->script_interpreter_source = (add->script_interpreter_source + != INTERPRETER_SOURCE_UNSET) + ? add->script_interpreter_source + : base->script_interpreter_source; + return new; +} + +static const char *set_interpreter_source(cmd_parms *cmd, void *dv, + char *arg) +{ + win32_dir_conf *d = (win32_dir_conf *)dv; + if (!strcasecmp(arg, "registry")) { + d->script_interpreter_source = INTERPRETER_SOURCE_REGISTRY; + } else if (!strcasecmp(arg, "registry-strict")) { + d->script_interpreter_source = INTERPRETER_SOURCE_REGISTRY_STRICT; + } else if (!strcasecmp(arg, "script")) { + d->script_interpreter_source = INTERPRETER_SOURCE_SHEBANG; + } else { + return apr_pstrcat(cmd->temp_pool, "ScriptInterpreterSource \"", arg, + "\" must be \"registry\", \"registry-strict\" or " + "\"script\"", NULL); + } + return NULL; +} + +/* Pretty unexciting ... yank a registry value, and explode any envvars + * that the system has configured (e.g. %SystemRoot%/someapp.exe) + * + * XXX: Need Unicode versions for i18n + */ +static apr_status_t get_win32_registry_default_value(apr_pool_t *p, HKEY hkey, + char* relativepath, + char **value) +{ + HKEY hkeyOpen; + DWORD type; + DWORD size = 0; + DWORD result = RegOpenKeyEx(hkey, relativepath, 0, + KEY_QUERY_VALUE, &hkeyOpen); + + if (result != ERROR_SUCCESS) + return APR_FROM_OS_ERROR(result); + + /* Read to NULL buffer to determine value size */ + result = RegQueryValueEx(hkeyOpen, "", 0, &type, NULL, &size); + + if (result == ERROR_SUCCESS) { + if ((size < 2) || (type != REG_SZ && type != REG_EXPAND_SZ)) { + result = ERROR_INVALID_PARAMETER; + } + else { + *value = apr_palloc(p, size); + /* Read value based on size query above */ + result = RegQueryValueEx(hkeyOpen, "", 0, &type, *value, &size); + } + } + + /* TODO: This might look fine, but we need to provide some warning + * somewhere that some environment variables may -not- be translated, + * seeing as we may have chopped the environment table down somewhat. + */ + if ((result == ERROR_SUCCESS) && (type == REG_EXPAND_SZ)) + { + char *tmp = *value; + size = ExpandEnvironmentStrings(tmp, *value, 0); + if (size) { + *value = apr_palloc(p, size); + size = ExpandEnvironmentStrings(tmp, *value, size); + } + } + + RegCloseKey(hkeyOpen); + return APR_FROM_OS_ERROR(result); +} + +/* Somewhat more exciting ... figure out where the registry has stashed the + * ExecCGI or Open command - it may be nested one level deep (or more???) + */ +static char* get_interpreter_from_win32_registry(apr_pool_t *p, + const char* ext, + int strict) +{ + char execcgi_path[] = "SHELL\\EXECCGI\\COMMAND"; + char execopen_path[] = "SHELL\\OPEN\\COMMAND"; + char typeName[MAX_PATH]; + int cmdOfName = FALSE; + HKEY hkeyName; + HKEY hkeyType; + DWORD type; + int size; + int result; + char *buffer; + + if (!ext) + return NULL; + /* + * Future optimization: + * When the registry is successfully searched, store the strings for + * interpreter and arguments in an ext hash to speed up subsequent look-ups + */ + + /* Open the key associated with the script filetype extension */ + result = RegOpenKeyEx(HKEY_CLASSES_ROOT, ext, 0, KEY_QUERY_VALUE, + &hkeyType); + + if (result != ERROR_SUCCESS) + return NULL; + + /* Retrieve the name of the script filetype extension */ + size = sizeof(typeName); + result = RegQueryValueEx(hkeyType, "", NULL, &type, typeName, &size); + + if (result == ERROR_SUCCESS && type == REG_SZ && typeName[0]) { + /* Open the key associated with the script filetype extension */ + result = RegOpenKeyEx(HKEY_CLASSES_ROOT, typeName, 0, + KEY_QUERY_VALUE, &hkeyName); + + if (result == ERROR_SUCCESS) + cmdOfName = TRUE; + } + + /* Open the key for the script command path by: + * + * 1) the 'named' filetype key for ExecCGI/Command + * 2) the extension's type key for ExecCGI/Command + * + * and if the strict arg is false, then continue trying: + * + * 3) the 'named' filetype key for Open/Command + * 4) the extension's type key for Open/Command + */ + + if (cmdOfName) { + result = get_win32_registry_default_value(p, hkeyName, + execcgi_path, &buffer); + } + + if (!cmdOfName || (result != ERROR_SUCCESS)) { + result = get_win32_registry_default_value(p, hkeyType, + execcgi_path, &buffer); + } + + if (!strict && cmdOfName && (result != ERROR_SUCCESS)) { + result = get_win32_registry_default_value(p, hkeyName, + execopen_path, &buffer); + } + + if (!strict && (result != ERROR_SUCCESS)) { + result = get_win32_registry_default_value(p, hkeyType, + execopen_path, &buffer); + } + + if (cmdOfName) + RegCloseKey(hkeyName); + + RegCloseKey(hkeyType); + + if (result != ERROR_SUCCESS || !buffer[0]) + return NULL; + + return buffer; +} + + +static apr_array_header_t *split_argv(apr_pool_t *p, const char *interp, const char *cgiprg, const char *cgiargs) +{ + apr_array_header_t *args = apr_array_make(p, 8, sizeof(char*)); + char *d = apr_palloc(p, strlen(interp)); + const char *ch = interp; + const char **arg; + int prgtaken = 0; + int argtaken = 0; + int inquo; + int sl; + + while (*ch) { + /* Skip on through Deep Space */ + if (isspace(*ch)) { + ++ch; continue; + } + /* One Arg */ + if (((*ch == '$') || (*ch == '%')) && (*(ch + 1) == '*')) { + const char *cgiarg = cgiargs; + argtaken = 1; + for (;;) { + char *w = ap_getword_nulls(p, &cgiarg, '+'); + if (!*w) + break; + ap_unescape_url(w); + arg = (const char**)apr_array_push(args); + *arg = ap_escape_shell_cmd(p, w); + } + ch += 2; + continue; + } + if (((*ch == '$') || (*ch == '%')) && (*(ch + 1) == '1')) { + prgtaken = 1; + arg = (const char**)apr_array_push(args); + *arg = cgiprg; + ch += 2; + continue; + } + if ((*ch == '\"') && ((*(ch + 1) == '$') + || (*(ch + 1) == '%')) && (*(ch + 2) == '1') + && (*(ch + 3) == '\"')) { + prgtaken = 1; + arg = (const char**)apr_array_push(args); + *arg = cgiprg; + ch += 4; + continue; + } + arg = (const char**)apr_array_push(args); + *arg = d; + inquo = 0; + while (*ch) { + if (isspace(*ch) && !inquo) { + ++ch; break; + } + /* Get 'em backslashes */ + for (sl = 0; *ch == '\\'; ++sl) + *d++ = *ch++; + if (sl & 1) { + /* last unmatched '\' + '"' sequence is a '"' */ + if (*ch == '\"') + *(d - 1) = *ch++; + continue; + } + if (*ch == '\"') { + /* '""' sequence within quotes is a '"' */ + if (*++ch == '\"' && inquo) { + *d++ = *ch++; continue; + } + /* Flip quote state */ + inquo = !inquo; + if (isspace(*ch) && !inquo) { + ++ch; break; + } + /* All other '"'s are Munched */ + continue; + } + /* Anything else is, well, something else */ + *d++ = *ch++; + } + /* Term that arg, already pushed on args */ + *d++ = '\0'; + } + + if (!prgtaken) { + arg = (const char**)apr_array_push(args); + *arg = cgiprg; + } + + if (!argtaken) { + char *cgiargs = cgiarg; + for (;;) { + char *w = ap_getword_nulls(p, &cgiargs, '+'); + if (!*w) + break; + ap_unescape_url(w); + arg = (const char**)apr_array_push(args); + *arg = ap_escape_shell_cmd(p, w); + } + } + + arg = (const char**)apr_array_push(args); + *arg = NULL; + + return args; +} + + +static apr_status_t ap_cgi_build_command(const char **cmd, const char ***argv, + request_rec *r, apr_pool_t *p) +{ + const char *ext = NULL; + const char *interpreter = NULL; + win32_dir_conf *d = + (win32_dir_conf *)ap_get_module_config(r->per_dir_config, + &win32_module); + apr_file_t *fh; + const char *args = r->args; + + /* Handle the complete file name, we DON'T want to follow suexec, since + * an unrooted command is as predictable as shooting craps in Win32. + * + * Notice that unlike most mime extension parsing, we have to use the + * win32 parsing here, therefore the final extension is the only one + * we will consider + */ + ext = strrchr(apr_filename_of_pathname(r->filename), '.'); + if (ext) + ++ext; + + /* If the file has an extension and it is not .com and not .exe and + * we've been instructed to search the registry, then do so. + */ + if (ext && (!strcasecmp(ext,".exe") || !strcasecmp(ext,".com") + || !strcasecmp(ext,".bat") || !strcasecmp(ext,".cmd"))) { + interpreter = ""; + } + if (!interpreter) + { + apr_status_t rv; + char buffer[1024]; + apr_size_t bytes = sizeof(buffer); + int i; + + /* Need to peek into the file figure out what it really is... + * ### aught to go back and build a cache for this one of these days. + */ + if (((rv = apr_file_open(&fh, r->filename, APR_READ | APR_BUFFERED, + APR_OS_DEFAULT, r->pool)) != APR_SUCCESS) + || ((rv = apr_file_read(fh, buffer, &bytes)) != APR_SUCCESS)) { + ap_log_rerror(APLOG_MARK, APLOG_ERR, rv, r, + "Failed to read cgi file %s for testing", r->filename); + return rv; + } + apr_file_close(fh); + + /* Script or executable, that is the question... */ + if ((buffer[0] == '#') && (buffer[1] == '!')) { + /* Assuming file is a script since it starts with a shebang */ + for (i = 2; i < sizeof(buffer); i++) { + if ((buffer[i] == '\r') || (buffer[i] == '\n')) { + buffer[i] = '\0'; + break; + } + } + if (i < sizeof(buffer)) { + interpreter = buffer + 2; + while (isspace(*interpreter)) + ++interpreter; + } + } + else { + /* Not a script, is it an executable? */ + IMAGE_DOS_HEADER *hdr = (IMAGE_DOS_HEADER*)buffer; + if ((bytes >= sizeof(IMAGE_DOS_HEADER)) && (hdr->e_magic == IMAGE_DOS_SIGNATURE)) { + if (hdr->e_lfarlc < 0x40) + /* Aught to invoke this 16 bit exe by a stub, (cmd /c?) */ + interpreter = ""; + else + interpreter = ""; + } + } + } + if (!interpreter && ext && + (d->script_interpreter_source == INTERPRETER_SOURCE_REGISTRY || + d->script_interpreter_source == INTERPRETER_SOURCE_REGISTRY_STRICT)) { + /* Check the registry */ + int strict = (d->script_interpreter_source + == INTERPRETER_SOURCE_REGISTRY_STRICT); + interpreter = get_interpreter_from_win32_registry(r->pool, ext, strict); + if (!interpreter) { + ap_log_error(APLOG_MARK, APLOG_NOERRNO|APLOG_INFO, 0, r->server, + strict ? "No ExecCGI verb found for files of type '%s'." + : "No ExecCGI or Open verb found for files of type '%s'.", + ext); + } + } + if (!interpreter) { + ap_log_rerror(APLOG_MARK, APLOG_ERR|APLOG_NOERRNO, 0, r, + "%s is not executable; ensure interpreted scripts have " + "\"#!\" first line", + r->filename); + return APR_EBADF; + } + + if (!args || ap_strchr_c(args, '=')) + args = ""; + + *argv = (const char **)(split_argv(p, interpreter, r->filename, args)->elts); + *cmd = (*argv)[0]; + return APR_SUCCESS; +} + +APR_DECLARE_OPTIONAL_FN(apr_status_t, ap_cgi_build_command, (const char **cmd, + const char ***argv, request_rec *r, apr_pool_t *p)); + +static void register_hooks(apr_pool_t *p) +{ + APR_REGISTER_OPTIONAL_FN(ap_cgi_build_command); +} + +static const command_rec win32_cmds[] = { +AP_INIT_TAKE1("ScriptInterpreterSource", set_interpreter_source, NULL, + OR_FILEINFO, + "Where to find interpreter to run Win32 scripts (Registry or script shebang line)"), +{ NULL } +}; + +module AP_MODULE_DECLARE_DATA win32_module = { + STANDARD20_MODULE_STUFF, + create_win32_dir_config, /* create per-dir config */ + merge_win32_dir_configs, /* merge per-dir config */ + NULL, /* server config */ + NULL, /* merge server config */ + win32_cmds, /* command apr_table_t */ + register_hooks /* register hooks */ +}; + +#endif
\ No newline at end of file diff --git a/modules/cache/mod_file_cache.exp b/modules/cache/mod_file_cache.exp new file mode 100644 index 0000000000..23b092a640 --- /dev/null +++ b/modules/cache/mod_file_cache.exp @@ -0,0 +1 @@ +file_cache_module diff --git a/modules/dav/fs/NWGNUmakefile b/modules/dav/fs/NWGNUmakefile new file mode 100644 index 0000000000..eb3c0fc5a4 --- /dev/null +++ b/modules/dav/fs/NWGNUmakefile @@ -0,0 +1,270 @@ +# +# Declare the sub-directories to be built here +# + +SUBDIRS = \ + $(EOLIST) + +# +# Get the 'head' of the build environment. This includes default targets and +# paths to tools +# + +include $(AP_WORK)\build\NWGNUhead.inc + +# +# build this level's files + +# +# Make sure all needed macro's are defined +# + +# +# These directories will be at the beginning of the include list, followed by +# INCDIRS +# +XINCDIRS += \ + $(AP_WORK)/srclib/apr/include \ + $(AP_WORK)/srclib/include/arch/NetWare \ + $(AP_WORK)/srclib/apr-util/include \ + $(AP_WORK)/include \ + $(AP_WORK)/os/NetWare \ + $(AP_WORK)/server/mpm/NetWare \ + $(AP_WORK)/srclib/pcre \ + $(AP_WORK)/modules/dav/main \ + $(NWOS) \ + $(EOLIST) + +# +# These flags will come after CFLAGS +# +XCFLAGS += \ + $(EOLIST) + +# +# These defines will come after DEFINES +# +XDEFINES += \ + $(EOLIST) + +# +# These flags will be added to the link.opt file +# +XLFLAGS += \ + XDCData $(NWOS)\apache.xdc \ + $(EOLIST) + +# +# These values will be appended to the correct variables based on the value of +# RELEASE +# +ifeq "$(RELEASE)" "debug" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "noopt" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "release" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +# +# These are used by the link target if an NLM is being generated +# This is used by the link 'name' directive to name the nlm. If left blank +# TARGET_nlm (see below) will be used. +# +NLM_NAME = modDAVFS + +# +# This is used by the link '-desc ' directive. +# If left blank, NLM_NAME will be used. +# +NLM_DESCRIPTION = Apache DAV_FS module + +# +# This is used by the '-threadname' directive. If left blank, +# NLM_NAME Thread will be used. +# +NLM_THREAD_NAME = modDAVFS Thread + +# +# If this is specified, it will override VERSION value in +# $(AP_WORK)\build\NWGNUenvironment.inc +# +NLM_VERSION = + +# +# If this is specified, it will override the default of 64K +# +NLM_STACK_SIZE = 65536 + + +# +# If this is specified it will be used by the link '-entry' directive +# +NLM_ENTRY_SYM = _LibCPrelude + +# +# If this is specified it will be used by the link '-exit' directive +# +NLM_EXIT_SYM = _LibCPostlude + +# +# If this is specified it will be used by the link '-check' directive +# +NLM_CHECK_SYM = + +# +# If this is specified it will be used by the link '-flags' directive +# +NLM_FLAGS = AUTOUNLOAD, PSEUDOPREEMPTION + +# +# Declare all target files (you must add your files here) +# + +# +# If there is an NLM target, put it here +# +TARGET_nlm = \ + $(OBJDIR)/moddavfs.nlm \ + $(EOLIST) + +# +# If there is an LIB target, put it here +# +TARGET_lib = \ + $(EOLIST) + +# +# These are the OBJ files needed to create the NLM target above. +# Paths must all use the '/' character +# +FILES_nlm_objs = \ + $(OBJDIR)/mod_dav_fs.o \ + $(OBJDIR)/dbm.o \ + $(OBJDIR)/lock.o \ + $(OBJDIR)/repos.o \ + $(OBJDIR)/libprews.o \ + $(EOLIST) + +# +# These are the LIB files needed to create the NLM target above. +# These will be added as a library command in the link.opt file. +# +FILES_nlm_libs = \ + libcpre.o \ + $(EOLIST) + +# +# These are the modules that the above NLM target depends on to load. +# These will be added as a module command in the link.opt file. +# +FILES_nlm_modules = \ + Apache2 \ + Libc \ + $(EOLIST) + +# +# If the nlm has a msg file, put it's path here +# +FILE_nlm_msg = + +# +# If the nlm has a hlp file put it's path here +# +FILE_nlm_hlp = + +# +# If this is specified, it will override $(NWOS)\copyright.txt. +# +FILE_nlm_copyright = + +# +# Any additional imports go here +# +FILES_nlm_Ximports = \ + @libc.imp \ + @$(APR)/aprlib.imp \ + @httpd.imp \ + @ws2nlm.imp \ + @../main/dav.imp \ + $(EOLIST) + +# +# Any symbols exported to here +# +FILES_nlm_exports = \ + dav_fs_module \ + $(EOLIST) + +# +# These are the OBJ files needed to create the LIB target above. +# Paths must all use the '/' character +# +FILES_lib_objs = \ + $(EOLIST) + +# +# implement targets and dependancies (leave this section alone) +# + +libs :: $(OBJDIR) $(TARGET_lib) + +nlms :: libs $(TARGET_nlm) + +# +# Updated this target to create necessary directories and copy files to the +# correct place. (See $(AP_WORK)\build\NWGNUhead.inc for examples) +# +install :: nlms FORCE + copy $(OBJDIR)\moddavfs.nlm $(INSTALL)\Apache2\modules +# +# Any specialized rules here +# + +$(OBJDIR)/%.o: ../../arch/netware/%.c $(OBJDIR)\cc.opt + @echo compiling $< + $(CC) $< -o=$(OBJDIR)\$(@F) @$(OBJDIR)\cc.opt + +# +# Include the 'tail' makefile that has targets that depend on variables defined +# in this makefile +# + +include $(AP_WORK)\build\NWGNUtail.inc + + + diff --git a/modules/dav/main/NWGNUmakefile b/modules/dav/main/NWGNUmakefile new file mode 100644 index 0000000000..507384276f --- /dev/null +++ b/modules/dav/main/NWGNUmakefile @@ -0,0 +1,272 @@ +# +# Declare the sub-directories to be built here +# + +SUBDIRS = \ + $(EOLIST) + +# +# Get the 'head' of the build environment. This includes default targets and +# paths to tools +# + +include $(AP_WORK)\build\NWGNUhead.inc + +# +# build this level's files +# +# Make sure all needed macro's are defined +# + +# +# These directories will be at the beginning of the include list, followed by +# INCDIRS +# +XINCDIRS += \ + $(AP_WORK)/srclib/apr/include \ + $(AP_WORK)/srclib/include/arch/NetWare \ + $(AP_WORK)/srclib/apr-util/include \ + $(AP_WORK)/include \ + $(AP_WORK)/os/NetWare \ + $(AP_WORK)/server/mpm/NetWare \ + $(AP_WORK)/srclib/pcre \ + $(NWOS) \ + $(EOLIST) + +# +# These flags will come after CFLAGS +# +XCFLAGS += \ + $(EOLIST) + +# +# These defines will come after DEFINES +# +XDEFINES += \ + $(EOLIST) + +# +# These flags will be added to the link.opt file +# +XLFLAGS += \ + $(EOLIST) + +# +# These values will be appended to the correct variables based on the value of +# RELEASE +# +ifeq "$(RELEASE)" "debug" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "noopt" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "release" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +# +# These are used by the link target if an NLM is being generated +# This is used by the link 'name' directive to name the nlm. If left blank +# TARGET_nlm (see below) will be used. +# +NLM_NAME = mod_DAV + +# +# This is used by the link '-desc ' directive. +# If left blank, NLM_NAME will be used. +# +NLM_DESCRIPTION = Apache DAV module + +# +# This is used by the '-threadname' directive. If left blank, +# NLM_NAME Thread will be used. +# +NLM_THREAD_NAME = mod_DAV + +# +# If this is specified, it will override VERSION value in +# $(AP_WORK)\build\NWGNUenvironment.inc +# +NLM_VERSION = + +# +# If this is specified, it will override the default of 64K +# +NLM_STACK_SIZE = 65536 + + +# +# If this is specified it will be used by the link '-entry' directive +# +NLM_ENTRY_SYM = _LibCPrelude + +# +# If this is specified it will be used by the link '-exit' directive +# +NLM_EXIT_SYM = _LibCPostlude + +# +# If this is specified it will be used by the link '-check' directive +# +NLM_CHECK_SYM = + +# +# If this is specified it will be used by the link '-flags' directive +# +NLM_FLAGS = AUTOUNLOAD, PSEUDOPREEMPTION + +# +# If this is specified it will be linked in with the XDCData option in the def +# file instead of the default of $(NWOS)/apache.xdc. XDCData can be disabled +# by setting APACHE_UNIPROC in the environment +# +XDCDATA = + +# +# Declare all target files (you must add your files here) +# + +# +# If there is an NLM target, put it here +# +TARGET_nlm = \ + $(OBJDIR)/mod_dav.nlm \ + $(EOLIST) + +# +# If there is an LIB target, put it here +# +TARGET_lib = \ + $(EOLIST) + +# +# These are the OBJ files needed to create the NLM target above. +# Paths must all use the '/' character +# +FILES_nlm_objs = \ + $(OBJDIR)/mod_dav.o \ + $(OBJDIR)/props.o \ + $(OBJDIR)/util.o \ + $(OBJDIR)/util_lock.o \ + $(OBJDIR)/liveprop.o \ + $(OBJDIR)/providers.o \ + $(OBJDIR)/std_liveprop.o \ + $(EOLIST) + +# +# These are the LIB files needed to create the NLM target above. +# These will be added as a library command in the link.opt file. +# +FILES_nlm_libs = \ + libcpre.o \ + $(EOLIST) + +# +# These are the modules that the above NLM target depends on to load. +# These will be added as a module command in the link.opt file. +# +FILES_nlm_modules = \ + Apache2 \ + Libc \ + $(EOLIST) + +# +# If the nlm has a msg file, put it's path here +# +FILE_nlm_msg = + +# +# If the nlm has a hlp file put it's path here +# +FILE_nlm_hlp = + +# +# If this is specified, it will override $(NWOS)\copyright.txt. +# +FILE_nlm_copyright = + +# +# Any additional imports go here +# +FILES_nlm_Ximports = \ + @libc.imp \ + @$(APR)/aprlib.imp \ + @httpd.imp \ + $(EOLIST) + +# +# Any symbols exported to here +# +FILES_nlm_exports = \ + dav_module \ + @dav.imp \ + $(EOLIST) + +# +# These are the OBJ files needed to create the LIB target above. +# Paths must all use the '/' character +# +FILES_lib_objs = \ + $(EOLIST) + +# +# implement targets and dependancies (leave this section alone) +# + +libs :: $(OBJDIR) $(TARGET_lib) + +nlms :: libs $(TARGET_nlm) + +# +# Updated this target to create necessary directories and copy files to the +# correct place. (See $(AP_WORK)\build\NWGNUhead.inc for examples) +# +install :: nlms FORCE + copy $(OBJDIR)\mod_dav.nlm $(INSTALL)\Apache2\modules\*.* + +# +# Any specialized rules here +# + +# +# Include the 'tail' makefile that has targets that depend on variables defined +# in this makefile +# + +include $(AP_WORK)\build\NWGNUtail.inc + + + diff --git a/modules/dav/main/dav.imp b/modules/dav/main/dav.imp new file mode 100644 index 0000000000..725bfb4ba0 --- /dev/null +++ b/modules/dav/main/dav.imp @@ -0,0 +1,19 @@ +(mod_dav) +dav_hook_gather_propsets, +dav_hook_find_liveprop, +dav_hook_insert_all_liveprops, +dav_new_error, +dav_set_bufsize, +dav_xmlns_add, +dav_check_bufsize, +dav_push_error, +dav_buffer_init, +dav_buffer_place, +dav_buffer_append, +dav_add_response, +dav_buffer_place_mem, +dav_lock_query, +dav_get_liveprop_info, +dav_do_find_liveprop, +dav_register_liveprop_group, +dav_register_provider
\ No newline at end of file diff --git a/modules/echo/NWGNUmakefile b/modules/echo/NWGNUmakefile new file mode 100644 index 0000000000..afc3734284 --- /dev/null +++ b/modules/echo/NWGNUmakefile @@ -0,0 +1,261 @@ +# +# Declare the sub-directories to be built here +# + +SUBDIRS = \ + $(EOLIST) + +# +# Get the 'head' of the build environment. This includes default targets and +# paths to tools +# + +include $(AP_WORK)\build\NWGNUhead.inc + +# +# build this level's files + +# +# Make sure all needed macro's are defined +# + +# +# These directories will be at the beginning of the include list, followed by +# INCDIRS +# +XINCDIRS += \ + $(AP_WORK)/include \ + $(NWOS) \ + $(AP_WORK)/modules/arch/netware \ + $(AP_WORK)/srclib/apr/include \ + $(AP_WORK)/srclib/apr-util/include \ + $(AP_WORK)/srclib/apr \ + $(EOLIST) + +# +# These flags will come after CFLAGS +# +XCFLAGS += \ + -prefix pre_nw.h \ + $(EOLIST) + +# +# These defines will come after DEFINES +# +XDEFINES += \ + $(EOLIST) + +# +# These flags will be added to the link.opt file +# +XLFLAGS += \ + $(EOLIST) + +# +# These values will be appended to the correct variables based on the value of +# RELEASE +# +ifeq "$(RELEASE)" "debug" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "noopt" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "release" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +# +# These are used by the link target if an NLM is being generated +# This is used by the link 'name' directive to name the nlm. If left blank +# TARGET_nlm (see below) will be used. +# +NLM_NAME = echo + +# +# This is used by the link '-desc ' directive. +# If left blank, NLM_NAME will be used. +# +NLM_DESCRIPTION = Echo Module + +# +# This is used by the '-threadname' directive. If left blank, +# NLM_NAME Thread will be used. +# +NLM_THREAD_NAME = Echo Module + +# +# If this is specified, it will override VERSION value in +# $(AP_WORK)\build\NWGNUenvironment.inc +# +NLM_VERSION = + +# +# If this is specified, it will override the default of 64K +# +NLM_STACK_SIZE = 8192 + + +# +# If this is specified it will be used by the link '-entry' directive +# +NLM_ENTRY_SYM = _LibCPrelude + +# +# If this is specified it will be used by the link '-exit' directive +# +NLM_EXIT_SYM = _LibCPostlude + +# +# If this is specified it will be used by the link '-check' directive +# +NLM_CHECK_SYM = + +# +# If these are specified it will be used by the link '-flags' directive +# +NLM_FLAGS = AUTOUNLOAD, PSEUDOPREEMPTION + +# +# If this is specified it will be linked in with the XDCData option in the def +# file instead of the default of $(NWOS)/apache.xdc. XDCData can be disabled +# by setting APACHE_UNIPROC in the environment +# +XDCDATA = + +# +# If there is an NLM target, put it here +# +TARGET_nlm = \ + $(OBJDIR)/echo.nlm \ + $(EOLIST) + +# +# If there is an LIB target, put it here +# +TARGET_lib = \ + $(EOLIST) + +# +# These are the OBJ files needed to create the NLM target above. +# Paths must all use the '/' character +# +FILES_nlm_objs = \ + $(OBJDIR)/mod_echo.o \ + $(EOLIST) + +# +# These are the LIB files needed to create the NLM target above. +# These will be added as a library command in the link.opt file. +# +FILES_nlm_libs = \ + libcpre.o \ + $(EOLIST) + +# +# These are the modules that the above NLM target depends on to load. +# These will be added as a module command in the link.opt file. +# +FILES_nlm_modules = \ + aprlib \ + libc \ + $(EOLIST) + +# +# If the nlm has a msg file, put it's path here +# +FILE_nlm_msg = + +# +# If the nlm has a hlp file put it's path here +# +FILE_nlm_hlp = + +# +# If this is specified, it will override $(NWOS)\copyright.txt. +# +FILE_nlm_copyright = + +# +# Any additional imports go here +# +FILES_nlm_Ximports = \ + @$(APR)/aprlib.imp \ + @$(NWOS)/httpd.imp \ + @libc.imp \ + $(EOLIST) + +# +# Any symbols exported to here +# +FILES_nlm_exports = \ + echo_module \ + $(EOLIST) + +# +# These are the OBJ files needed to create the LIB target above. +# Paths must all use the '/' character +# +FILES_lib_objs = \ + $(EOLIST) + +# +# implement targets and dependancies (leave this section alone) +# + +libs :: $(OBJDIR) $(TARGET_lib) + +nlms :: libs $(TARGET_nlm) + +# +# Updated this target to create necessary directories and copy files to the +# correct place. (See $(AP_WORK)\build\NWGNUhead.inc for examples) +# +install :: nlms FORCE + copy $(OBJDIR)\*.nlm $(INSTALL)\Apache2\modules\*.* + +# +# Any specialized rules here +# + +# +# Include the 'tail' makefile that has targets that depend on variables defined +# in this makefile +# + +include $(AP_WORK)\build\NWGNUtail.inc + + + diff --git a/modules/experimental/mod_auth_ldap.def b/modules/experimental/mod_auth_ldap.def new file mode 100644 index 0000000000..599636fb49 --- /dev/null +++ b/modules/experimental/mod_auth_ldap.def @@ -0,0 +1,6 @@ +IMPORT util_ldap_connection_find +IMPORT util_ldap_connection_close +IMPORT util_ldap_cache_checkuserid +IMPORT util_ldap_cache_compare +IMPORT util_ldap_cache_comparedn +EXPORT auth_ldap_module diff --git a/modules/experimental/mod_charset_lite.exp b/modules/experimental/mod_charset_lite.exp new file mode 100644 index 0000000000..3f0bf14b4a --- /dev/null +++ b/modules/experimental/mod_charset_lite.exp @@ -0,0 +1 @@ +charset_lite_module diff --git a/modules/experimental/mod_disk_cache.dsp b/modules/experimental/mod_disk_cache.dsp new file mode 100644 index 0000000000..c008ffc1ff --- /dev/null +++ b/modules/experimental/mod_disk_cache.dsp @@ -0,0 +1,110 @@ +# Microsoft Developer Studio Project File - Name="mod_disk_cache" - Package Owner=<4> +# Microsoft Developer Studio Generated Build File, Format Version 6.00 +# ** DO NOT EDIT ** + +# TARGTYPE "Win32 (x86) Dynamic-Link Library" 0x0102 + +CFG=mod_disk_cache - Win32 Debug +!MESSAGE This is not a valid makefile. To build this project using NMAKE, +!MESSAGE use the Export Makefile command and run +!MESSAGE +!MESSAGE NMAKE /f "mod_disk_cache.mak". +!MESSAGE +!MESSAGE You can specify a configuration when running NMAKE +!MESSAGE by defining the macro CFG on the command line. For example: +!MESSAGE +!MESSAGE NMAKE /f "mod_disk_cache.mak" CFG="mod_disk_cache - Win32 Debug" +!MESSAGE +!MESSAGE Possible choices for configuration are: +!MESSAGE +!MESSAGE "mod_disk_cache - Win32 Release" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE "mod_disk_cache - Win32 Debug" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE + +# Begin Project +# PROP AllowPerConfigDependencies 0 +# PROP Scc_ProjName "" +# PROP Scc_LocalPath "" +CPP=cl.exe +MTL=midl.exe +RSC=rc.exe + +!IF "$(CFG)" == "mod_disk_cache - Win32 Release" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 0 +# PROP BASE Output_Dir "Release" +# PROP BASE Intermediate_Dir "Release" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 0 +# PROP Output_Dir "Release" +# PROP Intermediate_Dir "Release" +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MT /W3 /GX /O2 /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "MOD_DISK_CACHE_EXPORTS" /YX /FD /c +# ADD CPP /nologo /MT /W3 /GX /O2 /I "../../srclib/apr-util/include" /I "../../srclib/apr/include" /I "../../include" /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "MOD_DISK_CACHE_EXPORTS" /YX /FD /c +# ADD BASE MTL /nologo /D "NDEBUG" /mktyplib203 /win32 +# ADD MTL /nologo /D "NDEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x409 /d "NDEBUG" +# ADD RSC /l 0x409 /d "NDEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /dll /machine:I386 +# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /dll /machine:I386 + +!ELSEIF "$(CFG)" == "mod_disk_cache - Win32 Debug" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 1 +# PROP BASE Output_Dir "Debug" +# PROP BASE Intermediate_Dir "Debug" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 1 +# PROP Output_Dir "Debug" +# PROP Intermediate_Dir "Debug" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MTd /W3 /Gm /GX /ZI /Od /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "MOD_DISK_CACHE_EXPORTS" /YX /FD /GZ /c +# ADD CPP /nologo /MTd /W3 /Gm /GX /ZI /Od /I "../../srclib/apr-util/include" /I "../../srclib/apr/include" /I "../../include" /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "MOD_DISK_CACHE_EXPORTS" /YX /FD /GZ /c +# ADD BASE MTL /nologo /D "_DEBUG" /mktyplib203 /win32 +# ADD MTL /nologo /D "_DEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x409 /d "_DEBUG" +# ADD RSC /l 0x409 /d "_DEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /dll /debug /machine:I386 /pdbtype:sept +# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /dll /debug /machine:I386 /pdbtype:sept + +!ENDIF + +# Begin Target + +# Name "mod_disk_cache - Win32 Release" +# Name "mod_disk_cache - Win32 Debug" +# Begin Group "Source Files" + +# PROP Default_Filter "cpp;c;cxx;rc;def;r;odl;idl;hpj;bat" +# Begin Source File + +SOURCE=.\mod_disk_cache.c +# End Source File +# End Group +# Begin Group "Header Files" + +# PROP Default_Filter "h;hpp;hxx;hm;inl" +# Begin Source File + +SOURCE=.\mod_cache.h +# End Source File +# End Group +# Begin Group "Resource Files" + +# PROP Default_Filter "ico;cur;bmp;dlg;rc2;rct;bin;rgs;gif;jpg;jpeg;jpe" +# End Group +# End Target +# End Project diff --git a/modules/experimental/mod_mem_cache.dsp b/modules/experimental/mod_mem_cache.dsp new file mode 100644 index 0000000000..bbc9129134 --- /dev/null +++ b/modules/experimental/mod_mem_cache.dsp @@ -0,0 +1,111 @@ +# Microsoft Developer Studio Project File - Name="mod_mem_cache" - Package Owner=<4> +# Microsoft Developer Studio Generated Build File, Format Version 6.00 +# ** DO NOT EDIT ** + +# TARGTYPE "Win32 (x86) Dynamic-Link Library" 0x0102 + +CFG=mod_mem_cache - Win32 Debug +!MESSAGE This is not a valid makefile. To build this project using NMAKE, +!MESSAGE use the Export Makefile command and run +!MESSAGE +!MESSAGE NMAKE /f "mod_mem_cache.mak". +!MESSAGE +!MESSAGE You can specify a configuration when running NMAKE +!MESSAGE by defining the macro CFG on the command line. For example: +!MESSAGE +!MESSAGE NMAKE /f "mod_mem_cache.mak" CFG="mod_mem_cache - Win32 Debug" +!MESSAGE +!MESSAGE Possible choices for configuration are: +!MESSAGE +!MESSAGE "mod_mem_cache - Win32 Release" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE "mod_mem_cache - Win32 Debug" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE + +# Begin Project +# PROP AllowPerConfigDependencies 0 +# PROP Scc_ProjName "" +# PROP Scc_LocalPath "" +CPP=cl.exe +MTL=midl.exe +RSC=rc.exe + +!IF "$(CFG)" == "mod_mem_cache - Win32 Release" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 0 +# PROP BASE Output_Dir "Release" +# PROP BASE Intermediate_Dir "Release" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 0 +# PROP Output_Dir "Release" +# PROP Intermediate_Dir "Release" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MT /W3 /GX /O2 /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "mod_mem_cache_EXPORTS" /YX /FD /c +# ADD CPP /nologo /MT /W3 /GX /O2 /I "../../srclib/apr-util/include" /I "../../srclib/apr/include" /I "../../include" /I "../../os/win32" /D "NDEBUG" /D "WIN32" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /YX /FD /c +# ADD BASE MTL /nologo /D "NDEBUG" /mktyplib203 /win32 +# ADD MTL /nologo /D "NDEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x409 /d "NDEBUG" +# ADD RSC /l 0x409 /d "NDEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /dll /machine:I386 +# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /dll /machine:I386 /out:"Release/mod_mem_cache.so" + +!ELSEIF "$(CFG)" == "mod_mem_cache - Win32 Debug" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 1 +# PROP BASE Output_Dir "Debug" +# PROP BASE Intermediate_Dir "Debug" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 1 +# PROP Output_Dir "Debug" +# PROP Intermediate_Dir "Debug" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MTd /W3 /Gm /GX /Zi /Od /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /D "mod_mem_cache_EXPORTS" /YX /FD /GZ /c +# ADD CPP /nologo /MTd /W3 /Gm /GX /Zi /Od /I "../../srclib/apr-util/include" /I "../../srclib/apr/include" /I "../../include" /I "../../os/win32" /D "_DEBUG" /D "WIN32" /D "_WINDOWS" /D "_MBCS" /D "_USRDLL" /YX /FD /GZ /c +# ADD BASE MTL /nologo /D "_DEBUG" /mktyplib203 /win32 +# ADD MTL /nologo /D "_DEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x409 /d "_DEBUG" +# ADD RSC /l 0x409 /d "_DEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /dll /debug /machine:I386 /pdbtype:sept +# ADD LINK32 kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /dll /debug /machine:I386 /out:"Debug/mod_mem_cache.so" /pdbtype:sept + +!ENDIF + +# Begin Target + +# Name "mod_mem_cache - Win32 Release" +# Name "mod_mem_cache - Win32 Debug" +# Begin Group "Source Files" + +# PROP Default_Filter "cpp;c;cxx;rc;def;r;odl;idl;hpj;bat" +# Begin Source File + +SOURCE=.\mod_mem_cache.c +# End Source File +# End Group +# Begin Group "Header Files" + +# PROP Default_Filter "h;hpp;hxx;hm;inl" +# Begin Source File + +SOURCE=.\mod_cache.h +# End Source File +# End Group +# Begin Group "Resource Files" + +# PROP Default_Filter "ico;cur;bmp;dlg;rc2;rct;bin;rgs;gif;jpg;jpeg;jpe" +# End Group +# End Target +# End Project diff --git a/modules/experimental/util_ldap.def b/modules/experimental/util_ldap.def new file mode 100644 index 0000000000..d1fac89b35 --- /dev/null +++ b/modules/experimental/util_ldap.def @@ -0,0 +1,6 @@ +EXPORT ldap_module +EXPORT util_ldap_connection_find +EXPORT util_ldap_connection_close +EXPORT util_ldap_cache_checkuserid +EXPORT util_ldap_cache_compare +EXPORT util_ldap_cache_comparedn diff --git a/modules/filters/mod_include.dsp b/modules/filters/mod_include.dsp new file mode 100644 index 0000000000..94b6dfb9b8 --- /dev/null +++ b/modules/filters/mod_include.dsp @@ -0,0 +1,132 @@ +# Microsoft Developer Studio Project File - Name="mod_include" - Package Owner=<4> +# Microsoft Developer Studio Generated Build File, Format Version 6.00 +# ** DO NOT EDIT ** + +# TARGTYPE "Win32 (x86) Dynamic-Link Library" 0x0102 + +CFG=mod_include - Win32 Release +!MESSAGE This is not a valid makefile. To build this project using NMAKE, +!MESSAGE use the Export Makefile command and run +!MESSAGE +!MESSAGE NMAKE /f "mod_include.mak". +!MESSAGE +!MESSAGE You can specify a configuration when running NMAKE +!MESSAGE by defining the macro CFG on the command line. For example: +!MESSAGE +!MESSAGE NMAKE /f "mod_include.mak" CFG="mod_include - Win32 Release" +!MESSAGE +!MESSAGE Possible choices for configuration are: +!MESSAGE +!MESSAGE "mod_include - Win32 Release" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE "mod_include - Win32 Debug" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE + +# Begin Project +# PROP AllowPerConfigDependencies 0 +# PROP Scc_ProjName "" +# PROP Scc_LocalPath "" +CPP=cl.exe +MTL=midl.exe +RSC=rc.exe + +!IF "$(CFG)" == "mod_include - Win32 Release" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 0 +# PROP BASE Output_Dir "Release" +# PROP BASE Intermediate_Dir "Release" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 0 +# PROP Output_Dir "Release" +# PROP Intermediate_Dir "Release" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MD /W3 /O2 /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /FD /c +# ADD CPP /nologo /MD /W3 /O2 /I "../../include" /I "../../srclib/apr/include" /I "../../srclib/apr-util/include" /D "NDEBUG" /D "WIN32" /D "_WINDOWS" /Fd"Release\mod_include" /FD /c +# ADD BASE MTL /nologo /D "NDEBUG" /win32 +# ADD MTL /nologo /D "NDEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x409 /d "NDEBUG" +# ADD RSC /l 0x409 /d "NDEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib /nologo /subsystem:windows /dll /map /machine:I386 /out:"Release/mod_include.so" /base:@..\..\os\win32\BaseAddr.ref,mod_include +# ADD LINK32 kernel32.lib /nologo /subsystem:windows /dll /map /machine:I386 /out:"Release/mod_include.so" /base:@..\..\os\win32\BaseAddr.ref,mod_include + +!ELSEIF "$(CFG)" == "mod_include - Win32 Debug" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 1 +# PROP BASE Output_Dir "Debug" +# PROP BASE Intermediate_Dir "Debug" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 1 +# PROP Output_Dir "Debug" +# PROP Intermediate_Dir "Debug" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MDd /W3 /GX /Zi /Od /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /FD /c +# ADD CPP /nologo /MDd /W3 /GX /Zi /Od /I "../../include" /I "../../srclib/apr/include" /I "../../srclib/apr-util/include" /D "_DEBUG" /D "WIN32" /D "_WINDOWS" /Fd"Debug\mod_include" /FD /c +# ADD BASE MTL /nologo /D "_DEBUG" /win32 +# ADD MTL /nologo /D "_DEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x409 /d "_DEBUG" +# ADD RSC /l 0x409 /d "_DEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib /nologo /subsystem:windows /dll /incremental:no /map /debug /machine:I386 /out:"Debug/mod_include.so" /base:@..\..\os\win32\BaseAddr.ref,mod_include +# ADD LINK32 kernel32.lib /nologo /subsystem:windows /dll /incremental:no /map /debug /machine:I386 /out:"Debug/mod_include.so" /base:@..\..\os\win32\BaseAddr.ref,mod_include + +!ENDIF + +# Begin Target + +# Name "mod_include - Win32 Release" +# Name "mod_include - Win32 Debug" +# Begin Source File + +SOURCE=.\mod_include.c +# End Source File +# Begin Source File + +SOURCE=.\mod_include.h +# End Source File +# Begin Source File + +SOURCE=.\mod_include.rc +# End Source File +# Begin Source File + +SOURCE=..\..\build\win32\win32ver.awk + +!IF "$(CFG)" == "mod_include - Win32 Release" + +# PROP Ignore_Default_Tool 1 +# Begin Custom Build - Creating Version Resource +InputPath=..\..\build\win32\win32ver.awk + +".\mod_include.rc" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)" + awk -f ../../build/win32/win32ver.awk mod_include "include_module for Apache" ../../include/ap_release.h > .\mod_include.rc + +# End Custom Build + +!ELSEIF "$(CFG)" == "mod_include - Win32 Debug" + +# PROP Ignore_Default_Tool 1 +# Begin Custom Build - Creating Version Resource +InputPath=..\..\build\win32\win32ver.awk + +".\mod_include.rc" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)" + awk -f ../../build/win32/win32ver.awk mod_include "include_module for Apache" ../../include/ap_release.h > .\mod_include.rc + +# End Custom Build + +!ENDIF + +# End Source File +# End Target +# End Project diff --git a/modules/generators/NWGNUinfo b/modules/generators/NWGNUinfo new file mode 100644 index 0000000000..4cad0688b2 --- /dev/null +++ b/modules/generators/NWGNUinfo @@ -0,0 +1,250 @@ +# +# Make sure all needed macro's are defined +# + +# +# Get the 'head' of the build environment if necessary. This includes default +# targets and paths to tools +# + +ifndef EnvironmentDefined +include $(AP_WORK)\build\NWGNUhead.inc +endif + +# +# These directories will be at the beginning of the include list, followed by +# INCDIRS +# +XINCDIRS += \ + $(AP_WORK)/include \ + $(NWOS) \ + $(AP_WORK)/modules/arch/netware \ + $(AP_WORK)/srclib/apr/include \ + $(AP_WORK)/srclib/apr-util/include \ + $(AP_WORK)/srclib/apr \ + $(EOLIST) + +# +# These flags will come after CFLAGS +# +XCFLAGS += \ + -prefix pre_nw.h \ + $(EOLIST) + +# +# These defines will come after DEFINES +# +XDEFINES += \ + $(EOLIST) + +# +# These flags will be added to the link.opt file +# +XLFLAGS += \ + $(EOLIST) + +# +# These values will be appended to the correct variables based on the value of +# RELEASE +# +ifeq "$(RELEASE)" "debug" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "noopt" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "release" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +# +# These are used by the link target if an NLM is being generated +# This is used by the link 'name' directive to name the nlm. If left blank +# TARGET_nlm (see below) will be used. +# +NLM_NAME = info + +# +# This is used by the link '-desc ' directive. +# If left blank, NLM_NAME will be used. +# +NLM_DESCRIPTION = Info Module + +# +# This is used by the '-threadname' directive. If left blank, +# NLM_NAME Thread will be used. +# +NLM_THREAD_NAME = Info Module + +# +# If this is specified, it will override VERSION value in +# $(AP_WORK)\build\NWGNUenvironment.inc +# +NLM_VERSION = + +# +# If this is specified, it will override the default of 64K +# +NLM_STACK_SIZE = 8192 + + +# +# If this is specified it will be used by the link '-entry' directive +# +NLM_ENTRY_SYM = _LibCPrelude + +# +# If this is specified it will be used by the link '-exit' directive +# +NLM_EXIT_SYM = _LibCPostlude + +# +# If this is specified it will be used by the link '-check' directive +# +NLM_CHECK_SYM = + +# +# If these are specified it will be used by the link '-flags' directive +# +NLM_FLAGS = AUTOUNLOAD, PSEUDOPREEMPTION + +# +# If this is specified it will be linked in with the XDCData option in the def +# file instead of the default of $(NWOS)/apache.xdc. XDCData can be disabled +# by setting APACHE_UNIPROC in the environment +# +XDCDATA = + +# +# If there is an NLM target, put it here +# +TARGET_nlm = \ + $(OBJDIR)/info.nlm \ + $(EOLIST) + +# +# If there is an LIB target, put it here +# +TARGET_lib = \ + $(EOLIST) + +# +# These are the OBJ files needed to create the NLM target above. +# Paths must all use the '/' character +# +FILES_nlm_objs = \ + $(OBJDIR)/mod_info.o \ + $(EOLIST) + +# +# These are the LIB files needed to create the NLM target above. +# These will be added as a library command in the link.opt file. +# +FILES_nlm_libs = \ + libcpre.o \ + $(EOLIST) + +# +# These are the modules that the above NLM target depends on to load. +# These will be added as a module command in the link.opt file. +# +FILES_nlm_modules = \ + aprlib \ + libc \ + $(EOLIST) + +# +# If the nlm has a msg file, put it's path here +# +FILE_nlm_msg = + +# +# If the nlm has a hlp file put it's path here +# +FILE_nlm_hlp = + +# +# If this is specified, it will override $(NWOS)\copyright.txt. +# +FILE_nlm_copyright = + +# +# Any additional imports go here +# +FILES_nlm_Ximports = \ + @$(APR)/aprlib.imp \ + @$(NWOS)/httpd.imp \ + @libc.imp \ + $(EOLIST) + +# +# Any symbols exported to here +# +FILES_nlm_exports = \ + info_module \ + $(EOLIST) + +# +# These are the OBJ files needed to create the LIB target above. +# Paths must all use the '/' character +# +FILES_lib_objs = \ + $(EOLIST) + +# +# implement targets and dependancies (leave this section alone) +# + +libs :: $(OBJDIR) $(TARGET_lib) + +nlms :: libs $(TARGET_nlm) + +# +# Updated this target to create necessary directories and copy files to the +# correct place. (See $(AP_WORK)\build\NWGNUhead.inc for examples) +# +install :: nlms FORCE + +# +# Any specialized rules here +# + +# +# Include the 'tail' makefile that has targets that depend on variables defined +# in this makefile +# + +include $(AP_WORK)\build\NWGNUtail.inc + diff --git a/modules/generators/NWGNUmakefile b/modules/generators/NWGNUmakefile new file mode 100644 index 0000000000..7f7d343bde --- /dev/null +++ b/modules/generators/NWGNUmakefile @@ -0,0 +1,247 @@ +# +# Declare the sub-directories to be built here +# + +SUBDIRS = \ + $(EOLIST) + +# +# Get the 'head' of the build environment. This includes default targets and +# paths to tools +# + +include $(AP_WORK)\build\NWGNUhead.inc + +# +# build this level's files + +# +# Make sure all needed macro's are defined +# + +# +# These directories will be at the beginning of the include list, followed by +# INCDIRS +# +XINCDIRS += \ + $(EOLIST) + +# +# These flags will come after CFLAGS +# +XCFLAGS += \ + $(EOLIST) + +# +# These defines will come after DEFINES +# +XDEFINES += \ + $(EOLIST) + +# +# These flags will be added to the link.opt file +# +XLFLAGS += \ + $(EOLIST) + +# +# These values will be appended to the correct variables based on the value of +# RELEASE +# +ifeq "$(RELEASE)" "debug" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "noopt" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "release" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +# +# These are used by the link target if an NLM is being generated +# This is used by the link 'name' directive to name the nlm. If left blank +# TARGET_nlm (see below) will be used. +# +NLM_NAME = + +# +# This is used by the link '-desc ' directive. +# If left blank, NLM_NAME will be used. +# +NLM_DESCRIPTION = + +# +# This is used by the '-threadname' directive. If left blank, +# NLM_NAME Thread will be used. +# +NLM_THREAD_NAME = + +# +# If this is specified, it will override VERSION value in +# $(AP_WORK)\build\NWGNUenvironment.inc +# +NLM_VERSION = + +# +# If this is specified, it will override the default of 64K +# +NLM_STACK_SIZE = + + +# +# If this is specified it will be used by the link '-entry' directive +# +NLM_ENTRY_SYM = + +# +# If this is specified it will be used by the link '-exit' directive +# +NLM_EXIT_SYM = + +# +# If this is specified it will be used by the link '-check' directive +# +NLM_CHECK_SYM = + +# +# If these are specified it will be used by the link '-flags' directive +# +NLM_FLAGS = + +# +# If this is specified it will be linked in with the XDCData option in the def +# file instead of the default of $(NWOS)/apache.xdc. XDCData can be disabled +# by setting APACHE_UNIPROC in the environment +# +XDCDATA = + +# +# If there is an NLM target, put it here +# +TARGET_nlm = \ + $(OBJDIR)/info.nlm \ + $(OBJDIR)/status.nlm \ + $(EOLIST) + +# +# If there is an LIB target, put it here +# +TARGET_lib = \ + $(EOLIST) + +# +# These are the OBJ files needed to create the NLM target above. +# Paths must all use the '/' character +# +FILES_nlm_objs = \ + $(EOLIST) + +# +# These are the LIB files needed to create the NLM target above. +# These will be added as a library command in the link.opt file. +# +FILES_nlm_libs = \ + $(EOLIST) + +# +# These are the modules that the above NLM target depends on to load. +# These will be added as a module command in the link.opt file. +# +FILES_nlm_modules = \ + $(EOLIST) + +# +# If the nlm has a msg file, put it's path here +# +FILE_nlm_msg = + +# +# If the nlm has a hlp file put it's path here +# +FILE_nlm_hlp = + +# +# If this is specified, it will override $(NWOS)\copyright.txt. +# +FILE_nlm_copyright = + +# +# Any additional imports go here +# +FILES_nlm_Ximports = \ + $(EOLIST) + +# +# Any symbols exported to here +# +FILES_nlm_exports = \ + $(EOLIST) + +# +# These are the OBJ files needed to create the LIB target above. +# Paths must all use the '/' character +# +FILES_lib_objs = \ + $(EOLIST) + +# +# implement targets and dependancies (leave this section alone) +# + +libs :: $(OBJDIR) $(TARGET_lib) + +nlms :: libs $(TARGET_nlm) + +# +# Updated this target to create necessary directories and copy files to the +# correct place. (See $(AP_WORK)\build\NWGNUhead.inc for examples) +# +install :: nlms FORCE + copy $(OBJDIR)\*.nlm $(INSTALL)\Apache2\modules\*.* + +# +# Any specialized rules here +# + +# +# Include the 'tail' makefile that has targets that depend on variables defined +# in this makefile +# + +include $(AP_WORK)\build\NWGNUtail.inc + + + diff --git a/modules/generators/NWGNUstatus b/modules/generators/NWGNUstatus new file mode 100644 index 0000000000..9a91236852 --- /dev/null +++ b/modules/generators/NWGNUstatus @@ -0,0 +1,250 @@ +# +# Make sure all needed macro's are defined +# + +# +# Get the 'head' of the build environment if necessary. This includes default +# targets and paths to tools +# + +ifndef EnvironmentDefined +include $(AP_WORK)\build\NWGNUhead.inc +endif + +# +# These directories will be at the beginning of the include list, followed by +# INCDIRS +# +XINCDIRS += \ + $(AP_WORK)/include \ + $(NWOS) \ + $(AP_WORK)/modules/arch/netware \ + $(AP_WORK)/srclib/apr/include \ + $(AP_WORK)/srclib/apr-util/include \ + $(AP_WORK)/srclib/apr \ + $(EOLIST) + +# +# These flags will come after CFLAGS +# +XCFLAGS += \ + -prefix pre_nw.h \ + $(EOLIST) + +# +# These defines will come after DEFINES +# +XDEFINES += \ + $(EOLIST) + +# +# These flags will be added to the link.opt file +# +XLFLAGS += \ + $(EOLIST) + +# +# These values will be appended to the correct variables based on the value of +# RELEASE +# +ifeq "$(RELEASE)" "debug" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "noopt" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "release" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +# +# These are used by the link target if an NLM is being generated +# This is used by the link 'name' directive to name the nlm. If left blank +# TARGET_nlm (see below) will be used. +# +NLM_NAME = status + +# +# This is used by the link '-desc ' directive. +# If left blank, NLM_NAME will be used. +# +NLM_DESCRIPTION = Status Module + +# +# This is used by the '-threadname' directive. If left blank, +# NLM_NAME Thread will be used. +# +NLM_THREAD_NAME = Status Module + +# +# If this is specified, it will override VERSION value in +# $(AP_WORK)\build\NWGNUenvironment.inc +# +NLM_VERSION = + +# +# If this is specified, it will override the default of 64K +# +NLM_STACK_SIZE = 8192 + + +# +# If this is specified it will be used by the link '-entry' directive +# +NLM_ENTRY_SYM = _LibCPrelude + +# +# If this is specified it will be used by the link '-exit' directive +# +NLM_EXIT_SYM = _LibCPostlude + +# +# If this is specified it will be used by the link '-check' directive +# +NLM_CHECK_SYM = + +# +# If these are specified it will be used by the link '-flags' directive +# +NLM_FLAGS = AUTOUNLOAD, PSEUDOPREEMPTION + +# +# If this is specified it will be linked in with the XDCData option in the def +# file instead of the default of $(NWOS)/apache.xdc. XDCData can be disabled +# by setting APACHE_UNIPROC in the environment +# +XDCDATA = + +# +# If there is an NLM target, put it here +# +TARGET_nlm = \ + $(OBJDIR)/status.nlm \ + $(EOLIST) + +# +# If there is an LIB target, put it here +# +TARGET_lib = \ + $(EOLIST) + +# +# These are the OBJ files needed to create the NLM target above. +# Paths must all use the '/' character +# +FILES_nlm_objs = \ + $(OBJDIR)/mod_status.o \ + $(EOLIST) + +# +# These are the LIB files needed to create the NLM target above. +# These will be added as a library command in the link.opt file. +# +FILES_nlm_libs = \ + libcpre.o \ + $(EOLIST) + +# +# These are the modules that the above NLM target depends on to load. +# These will be added as a module command in the link.opt file. +# +FILES_nlm_modules = \ + aprlib \ + libc \ + $(EOLIST) + +# +# If the nlm has a msg file, put it's path here +# +FILE_nlm_msg = + +# +# If the nlm has a hlp file put it's path here +# +FILE_nlm_hlp = + +# +# If this is specified, it will override $(NWOS)\copyright.txt. +# +FILE_nlm_copyright = + +# +# Any additional imports go here +# +FILES_nlm_Ximports = \ + @$(APR)/aprlib.imp \ + @$(NWOS)/httpd.imp \ + @libc.imp \ + $(EOLIST) + +# +# Any symbols exported to here +# +FILES_nlm_exports = \ + status_module \ + $(EOLIST) + +# +# These are the OBJ files needed to create the LIB target above. +# Paths must all use the '/' character +# +FILES_lib_objs = \ + $(EOLIST) + +# +# implement targets and dependancies (leave this section alone) +# + +libs :: $(OBJDIR) $(TARGET_lib) + +nlms :: libs $(TARGET_nlm) + +# +# Updated this target to create necessary directories and copy files to the +# correct place. (See $(AP_WORK)\build\NWGNUhead.inc for examples) +# +install :: nlms FORCE + +# +# Any specialized rules here +# + +# +# Include the 'tail' makefile that has targets that depend on variables defined +# in this makefile +# + +include $(AP_WORK)\build\NWGNUtail.inc + diff --git a/modules/generators/mod_asis.dsp b/modules/generators/mod_asis.dsp new file mode 100644 index 0000000000..b4d2a47de3 --- /dev/null +++ b/modules/generators/mod_asis.dsp @@ -0,0 +1,128 @@ +# Microsoft Developer Studio Project File - Name="mod_asis" - Package Owner=<4> +# Microsoft Developer Studio Generated Build File, Format Version 6.00 +# ** DO NOT EDIT ** + +# TARGTYPE "Win32 (x86) Dynamic-Link Library" 0x0102 + +CFG=mod_asis - Win32 Release +!MESSAGE This is not a valid makefile. To build this project using NMAKE, +!MESSAGE use the Export Makefile command and run +!MESSAGE +!MESSAGE NMAKE /f "mod_asis.mak". +!MESSAGE +!MESSAGE You can specify a configuration when running NMAKE +!MESSAGE by defining the macro CFG on the command line. For example: +!MESSAGE +!MESSAGE NMAKE /f "mod_asis.mak" CFG="mod_asis - Win32 Release" +!MESSAGE +!MESSAGE Possible choices for configuration are: +!MESSAGE +!MESSAGE "mod_asis - Win32 Release" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE "mod_asis - Win32 Debug" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE + +# Begin Project +# PROP AllowPerConfigDependencies 0 +# PROP Scc_ProjName "" +# PROP Scc_LocalPath "" +CPP=cl.exe +MTL=midl.exe +RSC=rc.exe + +!IF "$(CFG)" == "mod_asis - Win32 Release" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 0 +# PROP BASE Output_Dir "Release" +# PROP BASE Intermediate_Dir "Release" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 0 +# PROP Output_Dir "Release" +# PROP Intermediate_Dir "Release" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MD /W3 /O2 /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /FD /c +# ADD CPP /nologo /MD /W3 /O2 /I "../../include" /I "../../srclib/apr/include" /I "../../srclib/apr-util/include" /D "NDEBUG" /D "WIN32" /D "_WINDOWS" /Fd"Release\mod_asis" /FD /c +# ADD BASE MTL /nologo /D "NDEBUG" /win32 +# ADD MTL /nologo /D "NDEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x409 /d "NDEBUG" +# ADD RSC /l 0x409 /d "NDEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib /nologo /subsystem:windows /dll /map /machine:I386 /out:"Release/mod_asis.so" /base:@..\..\os\win32\BaseAddr.ref,mod_asis +# ADD LINK32 kernel32.lib /nologo /subsystem:windows /dll /map /machine:I386 /out:"Release/mod_asis.so" /base:@..\..\os\win32\BaseAddr.ref,mod_asis + +!ELSEIF "$(CFG)" == "mod_asis - Win32 Debug" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 1 +# PROP BASE Output_Dir "Debug" +# PROP BASE Intermediate_Dir "Debug" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 1 +# PROP Output_Dir "Debug" +# PROP Intermediate_Dir "Debug" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MDd /W3 /GX /Zi /Od /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /FD /c +# ADD CPP /nologo /MDd /W3 /GX /Zi /Od /I "../../include" /I "../../srclib/apr/include" /I "../../srclib/apr-util/include" /D "_DEBUG" /D "WIN32" /D "_WINDOWS" /Fd"Debug\mod_asis" /FD /c +# ADD BASE MTL /nologo /D "_DEBUG" /win32 +# ADD MTL /nologo /D "_DEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x409 /d "_DEBUG" +# ADD RSC /l 0x409 /d "_DEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib /nologo /subsystem:windows /dll /incremental:no /map /debug /machine:I386 /out:"Debug/mod_asis.so" /base:@..\..\os\win32\BaseAddr.ref,mod_asis +# ADD LINK32 kernel32.lib /nologo /subsystem:windows /dll /incremental:no /map /debug /machine:I386 /out:"Debug/mod_asis.so" /base:@..\..\os\win32\BaseAddr.ref,mod_asis + +!ENDIF + +# Begin Target + +# Name "mod_asis - Win32 Release" +# Name "mod_asis - Win32 Debug" +# Begin Source File + +SOURCE=.\mod_asis.c +# End Source File +# Begin Source File + +SOURCE=.\mod_asis.rc +# End Source File +# Begin Source File + +SOURCE=..\..\build\win32\win32ver.awk + +!IF "$(CFG)" == "mod_asis - Win32 Release" + +# PROP Ignore_Default_Tool 1 +# Begin Custom Build - Creating Version Resource +InputPath=..\..\build\win32\win32ver.awk + +".\mod_asis.rc" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)" + awk -f ../../build/win32/win32ver.awk mod_asis "asis_module for Apache" ../../include/ap_release.h > .\mod_asis.rc + +# End Custom Build + +!ELSEIF "$(CFG)" == "mod_asis - Win32 Debug" + +# PROP Ignore_Default_Tool 1 +# Begin Custom Build - Creating Version Resource +InputPath=..\..\build\win32\win32ver.awk + +".\mod_asis.rc" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)" + awk -f ../../build/win32/win32ver.awk mod_asis "asis_module for Apache" ../../include/ap_release.h > .\mod_asis.rc + +# End Custom Build + +!ENDIF + +# End Source File +# End Target +# End Project diff --git a/modules/generators/mod_autoindex.dsp b/modules/generators/mod_autoindex.dsp new file mode 100644 index 0000000000..4030391905 --- /dev/null +++ b/modules/generators/mod_autoindex.dsp @@ -0,0 +1,128 @@ +# Microsoft Developer Studio Project File - Name="mod_autoindex" - Package Owner=<4> +# Microsoft Developer Studio Generated Build File, Format Version 6.00 +# ** DO NOT EDIT ** + +# TARGTYPE "Win32 (x86) Dynamic-Link Library" 0x0102 + +CFG=mod_autoindex - Win32 Release +!MESSAGE This is not a valid makefile. To build this project using NMAKE, +!MESSAGE use the Export Makefile command and run +!MESSAGE +!MESSAGE NMAKE /f "mod_autoindex.mak". +!MESSAGE +!MESSAGE You can specify a configuration when running NMAKE +!MESSAGE by defining the macro CFG on the command line. For example: +!MESSAGE +!MESSAGE NMAKE /f "mod_autoindex.mak" CFG="mod_autoindex - Win32 Release" +!MESSAGE +!MESSAGE Possible choices for configuration are: +!MESSAGE +!MESSAGE "mod_autoindex - Win32 Release" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE "mod_autoindex - Win32 Debug" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE + +# Begin Project +# PROP AllowPerConfigDependencies 0 +# PROP Scc_ProjName "" +# PROP Scc_LocalPath "" +CPP=cl.exe +MTL=midl.exe +RSC=rc.exe + +!IF "$(CFG)" == "mod_autoindex - Win32 Release" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 0 +# PROP BASE Output_Dir "Release" +# PROP BASE Intermediate_Dir "Release" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 0 +# PROP Output_Dir "Release" +# PROP Intermediate_Dir "Release" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MD /W3 /O2 /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /FD /c +# ADD CPP /nologo /MD /W3 /O2 /I "../../include" /I "../../srclib/apr/include" /I "../../srclib/apr-util/include" /D "NDEBUG" /D "WIN32" /D "_WINDOWS" /Fd"Release\mod_autoindex" /FD /c +# ADD BASE MTL /nologo /D "NDEBUG" /win32 +# ADD MTL /nologo /D "NDEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x409 /d "NDEBUG" +# ADD RSC /l 0x409 /d "NDEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib /nologo /subsystem:windows /dll /map /machine:I386 /out:"Release/mod_autoindex.so" /base:@..\..\os\win32\BaseAddr.ref,mod_autoindex +# ADD LINK32 kernel32.lib /nologo /subsystem:windows /dll /map /machine:I386 /out:"Release/mod_autoindex.so" /base:@..\..\os\win32\BaseAddr.ref,mod_autoindex + +!ELSEIF "$(CFG)" == "mod_autoindex - Win32 Debug" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 1 +# PROP BASE Output_Dir "Debug" +# PROP BASE Intermediate_Dir "Debug" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 1 +# PROP Output_Dir "Debug" +# PROP Intermediate_Dir "Debug" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MDd /W3 /GX /Zi /Od /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /FD /c +# ADD CPP /nologo /MDd /W3 /GX /Zi /Od /I "../../include" /I "../../srclib/apr/include" /I "../../srclib/apr-util/include" /D "_DEBUG" /D "WIN32" /D "_WINDOWS" /Fd"Debug\mod_autoindex" /FD /c +# ADD BASE MTL /nologo /D "_DEBUG" /win32 +# ADD MTL /nologo /D "_DEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x409 /d "_DEBUG" +# ADD RSC /l 0x409 /d "_DEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib /nologo /subsystem:windows /dll /incremental:no /map /debug /machine:I386 /out:"Debug/mod_autoindex.so" /base:@..\..\os\win32\BaseAddr.ref,mod_autoindex +# ADD LINK32 kernel32.lib /nologo /subsystem:windows /dll /incremental:no /map /debug /machine:I386 /out:"Debug/mod_autoindex.so" /base:@..\..\os\win32\BaseAddr.ref,mod_autoindex + +!ENDIF + +# Begin Target + +# Name "mod_autoindex - Win32 Release" +# Name "mod_autoindex - Win32 Debug" +# Begin Source File + +SOURCE=.\mod_autoindex.c +# End Source File +# Begin Source File + +SOURCE=.\mod_autoindex.rc +# End Source File +# Begin Source File + +SOURCE=..\..\build\win32\win32ver.awk + +!IF "$(CFG)" == "mod_autoindex - Win32 Release" + +# PROP Ignore_Default_Tool 1 +# Begin Custom Build - Creating Version Resource +InputPath=..\..\build\win32\win32ver.awk + +".\mod_autoindex.rc" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)" + awk -f ../../build/win32/win32ver.awk mod_autoindex "autoindex_module for Apache" ../../include/ap_release.h > .\mod_autoindex.rc + +# End Custom Build + +!ELSEIF "$(CFG)" == "mod_autoindex - Win32 Debug" + +# PROP Ignore_Default_Tool 1 +# Begin Custom Build - Creating Version Resource +InputPath=..\..\build\win32\win32ver.awk + +".\mod_autoindex.rc" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)" + awk -f ../../build/win32/win32ver.awk mod_autoindex "autoindex_module for Apache" ../../include/ap_release.h > .\mod_autoindex.rc + +# End Custom Build + +!ENDIF + +# End Source File +# End Target +# End Project diff --git a/modules/generators/mod_cgi.dsp b/modules/generators/mod_cgi.dsp new file mode 100644 index 0000000000..be4d4a9647 --- /dev/null +++ b/modules/generators/mod_cgi.dsp @@ -0,0 +1,132 @@ +# Microsoft Developer Studio Project File - Name="mod_cgi" - Package Owner=<4> +# Microsoft Developer Studio Generated Build File, Format Version 6.00 +# ** DO NOT EDIT ** + +# TARGTYPE "Win32 (x86) Dynamic-Link Library" 0x0102 + +CFG=mod_cgi - Win32 Release +!MESSAGE This is not a valid makefile. To build this project using NMAKE, +!MESSAGE use the Export Makefile command and run +!MESSAGE +!MESSAGE NMAKE /f "mod_cgi.mak". +!MESSAGE +!MESSAGE You can specify a configuration when running NMAKE +!MESSAGE by defining the macro CFG on the command line. For example: +!MESSAGE +!MESSAGE NMAKE /f "mod_cgi.mak" CFG="mod_cgi - Win32 Release" +!MESSAGE +!MESSAGE Possible choices for configuration are: +!MESSAGE +!MESSAGE "mod_cgi - Win32 Release" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE "mod_cgi - Win32 Debug" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE + +# Begin Project +# PROP AllowPerConfigDependencies 0 +# PROP Scc_ProjName "" +# PROP Scc_LocalPath "" +CPP=cl.exe +MTL=midl.exe +RSC=rc.exe + +!IF "$(CFG)" == "mod_cgi - Win32 Release" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 0 +# PROP BASE Output_Dir "Release" +# PROP BASE Intermediate_Dir "Release" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 0 +# PROP Output_Dir "Release" +# PROP Intermediate_Dir "Release" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MD /W3 /O2 /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /FD /c +# ADD CPP /nologo /MD /W3 /O2 /I "../../include" /I "../../srclib/apr/include" /I "../../srclib/apr-util/include" /D "NDEBUG" /D "WIN32" /D "_WINDOWS" /Fd"Release\mod_cgi" /FD /c +# ADD BASE MTL /nologo /D "NDEBUG" /win32 +# ADD MTL /nologo /D "NDEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x409 /d "NDEBUG" +# ADD RSC /l 0x409 /d "NDEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib /nologo /subsystem:windows /dll /map /machine:I386 /out:"Release/mod_cgi.so" /base:@..\..\os\win32\BaseAddr.ref,mod_cgi +# ADD LINK32 kernel32.lib /nologo /subsystem:windows /dll /map /machine:I386 /out:"Release/mod_cgi.so" /base:@..\..\os\win32\BaseAddr.ref,mod_cgi + +!ELSEIF "$(CFG)" == "mod_cgi - Win32 Debug" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 1 +# PROP BASE Output_Dir "Debug" +# PROP BASE Intermediate_Dir "Debug" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 1 +# PROP Output_Dir "Debug" +# PROP Intermediate_Dir "Debug" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MDd /W3 /GX /Zi /Od /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /FD /c +# ADD CPP /nologo /MDd /W3 /GX /Zi /Od /I "../../include" /I "../../srclib/apr/include" /I "../../srclib/apr-util/include" /D "_DEBUG" /D "WIN32" /D "_WINDOWS" /Fd"Debug\mod_cgi" /FD /c +# ADD BASE MTL /nologo /D "_DEBUG" /win32 +# ADD MTL /nologo /D "_DEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x409 /d "_DEBUG" +# ADD RSC /l 0x409 /d "_DEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib /nologo /subsystem:windows /dll /incremental:no /map /debug /machine:I386 /out:"Debug/mod_cgi.so" /base:@..\..\os\win32\BaseAddr.ref,mod_cgi +# ADD LINK32 kernel32.lib /nologo /subsystem:windows /dll /incremental:no /map /debug /machine:I386 /out:"Debug/mod_cgi.so" /base:@..\..\os\win32\BaseAddr.ref,mod_cgi + +!ENDIF + +# Begin Target + +# Name "mod_cgi - Win32 Release" +# Name "mod_cgi - Win32 Debug" +# Begin Source File + +SOURCE=.\mod_cgi.c +# End Source File +# Begin Source File + +SOURCE=.\mod_cgi.h +# End Source File +# Begin Source File + +SOURCE=.\mod_cgi.rc +# End Source File +# Begin Source File + +SOURCE=..\..\build\win32\win32ver.awk + +!IF "$(CFG)" == "mod_cgi - Win32 Release" + +# PROP Ignore_Default_Tool 1 +# Begin Custom Build - Creating Version Resource +InputPath=..\..\build\win32\win32ver.awk + +".\mod_cgi.rc" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)" + awk -f ../../build/win32/win32ver.awk mod_cgi "cgi_module for Apache" ../../include/ap_release.h > .\mod_cgi.rc + +# End Custom Build + +!ELSEIF "$(CFG)" == "mod_cgi - Win32 Debug" + +# PROP Ignore_Default_Tool 1 +# Begin Custom Build - Creating Version Resource +InputPath=..\..\build\win32\win32ver.awk + +".\mod_cgi.rc" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)" + awk -f ../../build/win32/win32ver.awk mod_cgi "cgi_module for Apache" ../../include/ap_release.h > .\mod_cgi.rc + +# End Custom Build + +!ENDIF + +# End Source File +# End Target +# End Project diff --git a/modules/generators/mod_cgid.exp b/modules/generators/mod_cgid.exp new file mode 100644 index 0000000000..5f10d486da --- /dev/null +++ b/modules/generators/mod_cgid.exp @@ -0,0 +1 @@ +cgid_module diff --git a/modules/http/mod_mime.dsp b/modules/http/mod_mime.dsp new file mode 100644 index 0000000000..4af27fb68f --- /dev/null +++ b/modules/http/mod_mime.dsp @@ -0,0 +1,128 @@ +# Microsoft Developer Studio Project File - Name="mod_mime" - Package Owner=<4> +# Microsoft Developer Studio Generated Build File, Format Version 6.00 +# ** DO NOT EDIT ** + +# TARGTYPE "Win32 (x86) Dynamic-Link Library" 0x0102 + +CFG=mod_mime - Win32 Release +!MESSAGE This is not a valid makefile. To build this project using NMAKE, +!MESSAGE use the Export Makefile command and run +!MESSAGE +!MESSAGE NMAKE /f "mod_mime.mak". +!MESSAGE +!MESSAGE You can specify a configuration when running NMAKE +!MESSAGE by defining the macro CFG on the command line. For example: +!MESSAGE +!MESSAGE NMAKE /f "mod_mime.mak" CFG="mod_mime - Win32 Release" +!MESSAGE +!MESSAGE Possible choices for configuration are: +!MESSAGE +!MESSAGE "mod_mime - Win32 Release" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE "mod_mime - Win32 Debug" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE + +# Begin Project +# PROP AllowPerConfigDependencies 0 +# PROP Scc_ProjName "" +# PROP Scc_LocalPath "" +CPP=cl.exe +MTL=midl.exe +RSC=rc.exe + +!IF "$(CFG)" == "mod_mime - Win32 Release" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 0 +# PROP BASE Output_Dir "Release" +# PROP BASE Intermediate_Dir "Release" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 0 +# PROP Output_Dir "Release" +# PROP Intermediate_Dir "Release" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MD /W3 /O2 /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /FD /c +# ADD CPP /nologo /MD /W3 /O2 /I "../../include" /I "../../srclib/apr/include" /I "../../srclib/apr-util/include" /D "NDEBUG" /D "WIN32" /D "_WINDOWS" /Fd"Release\mod_mime" /FD /c +# ADD BASE MTL /nologo /D "NDEBUG" /win32 +# ADD MTL /nologo /D "NDEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x409 /d "NDEBUG" +# ADD RSC /l 0x409 /d "NDEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib /nologo /subsystem:windows /dll /map /machine:I386 /out:"Release/mod_mime.so" /base:@..\..\os\win32\BaseAddr.ref,mod_mime +# ADD LINK32 kernel32.lib /nologo /subsystem:windows /dll /map /machine:I386 /out:"Release/mod_mime.so" /base:@..\..\os\win32\BaseAddr.ref,mod_mime + +!ELSEIF "$(CFG)" == "mod_mime - Win32 Debug" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 1 +# PROP BASE Output_Dir "Debug" +# PROP BASE Intermediate_Dir "Debug" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 1 +# PROP Output_Dir "Debug" +# PROP Intermediate_Dir "Debug" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MDd /W3 /GX /Zi /Od /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /FD /c +# ADD CPP /nologo /MDd /W3 /GX /Zi /Od /I "../../include" /I "../../srclib/apr/include" /I "../../srclib/apr-util/include" /D "_DEBUG" /D "WIN32" /D "_WINDOWS" /Fd"Debug\mod_mime" /FD /c +# ADD BASE MTL /nologo /D "_DEBUG" /win32 +# ADD MTL /nologo /D "_DEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x409 /d "_DEBUG" +# ADD RSC /l 0x409 /d "_DEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib /nologo /subsystem:windows /dll /incremental:no /map /debug /machine:I386 /out:"Debug/mod_mime.so" /base:@..\..\os\win32\BaseAddr.ref,mod_mime +# ADD LINK32 kernel32.lib /nologo /subsystem:windows /dll /incremental:no /map /debug /machine:I386 /out:"Debug/mod_mime.so" /base:@..\..\os\win32\BaseAddr.ref,mod_mime + +!ENDIF + +# Begin Target + +# Name "mod_mime - Win32 Release" +# Name "mod_mime - Win32 Debug" +# Begin Source File + +SOURCE=.\mod_mime.c +# End Source File +# Begin Source File + +SOURCE=.\mod_mime.rc +# End Source File +# Begin Source File + +SOURCE=..\..\build\win32\win32ver.awk + +!IF "$(CFG)" == "mod_mime - Win32 Release" + +# PROP Ignore_Default_Tool 1 +# Begin Custom Build - Creating Version Resource +InputPath=..\..\build\win32\win32ver.awk + +".\mod_mime.rc" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)" + awk -f ../../build/win32/win32ver.awk mod_mime "mime_module for Apache" ../../include/ap_release.h > .\mod_mime.rc + +# End Custom Build + +!ELSEIF "$(CFG)" == "mod_mime - Win32 Debug" + +# PROP Ignore_Default_Tool 1 +# Begin Custom Build - Creating Version Resource +InputPath=..\..\build\win32\win32ver.awk + +".\mod_mime.rc" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)" + awk -f ../../build/win32/win32ver.awk mod_mime "mime_module for Apache" ../../include/ap_release.h > .\mod_mime.rc + +# End Custom Build + +!ENDIF + +# End Source File +# End Target +# End Project diff --git a/modules/loggers/mod_log_config.dsp b/modules/loggers/mod_log_config.dsp new file mode 100644 index 0000000000..e043dabec9 --- /dev/null +++ b/modules/loggers/mod_log_config.dsp @@ -0,0 +1,128 @@ +# Microsoft Developer Studio Project File - Name="mod_log_config" - Package Owner=<4> +# Microsoft Developer Studio Generated Build File, Format Version 6.00 +# ** DO NOT EDIT ** + +# TARGTYPE "Win32 (x86) Dynamic-Link Library" 0x0102 + +CFG=mod_log_config - Win32 Release +!MESSAGE This is not a valid makefile. To build this project using NMAKE, +!MESSAGE use the Export Makefile command and run +!MESSAGE +!MESSAGE NMAKE /f "mod_log_config.mak". +!MESSAGE +!MESSAGE You can specify a configuration when running NMAKE +!MESSAGE by defining the macro CFG on the command line. For example: +!MESSAGE +!MESSAGE NMAKE /f "mod_log_config.mak" CFG="mod_log_config - Win32 Release" +!MESSAGE +!MESSAGE Possible choices for configuration are: +!MESSAGE +!MESSAGE "mod_log_config - Win32 Release" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE "mod_log_config - Win32 Debug" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE + +# Begin Project +# PROP AllowPerConfigDependencies 0 +# PROP Scc_ProjName "" +# PROP Scc_LocalPath "" +CPP=cl.exe +MTL=midl.exe +RSC=rc.exe + +!IF "$(CFG)" == "mod_log_config - Win32 Release" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 0 +# PROP BASE Output_Dir "Release" +# PROP BASE Intermediate_Dir "Release" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 0 +# PROP Output_Dir "Release" +# PROP Intermediate_Dir "Release" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MD /W3 /O2 /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /FD /c +# ADD CPP /nologo /MD /W3 /O2 /I "../../include" /I "../../srclib/apr/include" /I "../../srclib/apr-util/include" /D "NDEBUG" /D "WIN32" /D "_WINDOWS" /Fd"Release\mod_log_config" /FD /c +# ADD BASE MTL /nologo /D "NDEBUG" /win32 +# ADD MTL /nologo /D "NDEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x409 /d "NDEBUG" +# ADD RSC /l 0x409 /d "NDEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib /nologo /subsystem:windows /dll /map /machine:I386 /out:"Release/mod_log_config.so" /base:@..\..\os\win32\BaseAddr.ref,mod_log_config +# ADD LINK32 kernel32.lib /nologo /subsystem:windows /dll /map /machine:I386 /out:"Release/mod_log_config.so" /base:@..\..\os\win32\BaseAddr.ref,mod_log_config + +!ELSEIF "$(CFG)" == "mod_log_config - Win32 Debug" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 1 +# PROP BASE Output_Dir "Debug" +# PROP BASE Intermediate_Dir "Debug" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 1 +# PROP Output_Dir "Debug" +# PROP Intermediate_Dir "Debug" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MDd /W3 /GX /Zi /Od /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /FD /c +# ADD CPP /nologo /MDd /W3 /GX /Zi /Od /I "../../include" /I "../../srclib/apr/include" /I "../../srclib/apr-util/include" /D "_DEBUG" /D "WIN32" /D "_WINDOWS" /Fd"Debug\mod_log_config" /FD /c +# ADD BASE MTL /nologo /D "_DEBUG" /win32 +# ADD MTL /nologo /D "_DEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x409 /d "_DEBUG" +# ADD RSC /l 0x409 /d "_DEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib /nologo /subsystem:windows /dll /incremental:no /map /debug /machine:I386 /out:"Debug/mod_log_config.so" /base:@..\..\os\win32\BaseAddr.ref,mod_log_config +# ADD LINK32 kernel32.lib /nologo /subsystem:windows /dll /incremental:no /map /debug /machine:I386 /out:"Debug/mod_log_config.so" /base:@..\..\os\win32\BaseAddr.ref,mod_log_config + +!ENDIF + +# Begin Target + +# Name "mod_log_config - Win32 Release" +# Name "mod_log_config - Win32 Debug" +# Begin Source File + +SOURCE=.\mod_log_config.c +# End Source File +# Begin Source File + +SOURCE=.\mod_log_config.rc +# End Source File +# Begin Source File + +SOURCE=..\..\build\win32\win32ver.awk + +!IF "$(CFG)" == "mod_log_config - Win32 Release" + +# PROP Ignore_Default_Tool 1 +# Begin Custom Build - Creating Version Resource +InputPath=..\..\build\win32\win32ver.awk + +".\mod_log_config.rc" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)" + awk -f ../../build/win32/win32ver.awk mod_log_config "log_config_module for Apache" ../../include/ap_release.h > .\mod_log_config.rc + +# End Custom Build + +!ELSEIF "$(CFG)" == "mod_log_config - Win32 Debug" + +# PROP Ignore_Default_Tool 1 +# Begin Custom Build - Creating Version Resource +InputPath=..\..\build\win32\win32ver.awk + +".\mod_log_config.rc" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)" + awk -f ../../build/win32/win32ver.awk mod_log_config "log_config_module for Apache" ../../include/ap_release.h > .\mod_log_config.rc + +# End Custom Build + +!ENDIF + +# End Source File +# End Target +# End Project diff --git a/modules/mappers/NWGNUmakefile b/modules/mappers/NWGNUmakefile new file mode 100644 index 0000000000..62c9624d97 --- /dev/null +++ b/modules/mappers/NWGNUmakefile @@ -0,0 +1,247 @@ +# +# Declare the sub-directories to be built here +# + +SUBDIRS = \ + $(EOLIST) + +# +# Get the 'head' of the build environment. This includes default targets and +# paths to tools +# + +include $(AP_WORK)\build\NWGNUhead.inc + +# +# build this level's files + +# +# Make sure all needed macro's are defined +# + +# +# These directories will be at the beginning of the include list, followed by +# INCDIRS +# +XINCDIRS += \ + $(EOLIST) + +# +# These flags will come after CFLAGS +# +XCFLAGS += \ + $(EOLIST) + +# +# These defines will come after DEFINES +# +XDEFINES += \ + $(EOLIST) + +# +# These flags will be added to the link.opt file +# +XLFLAGS += \ + $(EOLIST) + +# +# These values will be appended to the correct variables based on the value of +# RELEASE +# +ifeq "$(RELEASE)" "debug" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "noopt" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "release" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +# +# These are used by the link target if an NLM is being generated +# This is used by the link 'name' directive to name the nlm. If left blank +# TARGET_nlm (see below) will be used. +# +NLM_NAME = + +# +# This is used by the link '-desc ' directive. +# If left blank, NLM_NAME will be used. +# +NLM_DESCRIPTION = + +# +# This is used by the '-threadname' directive. If left blank, +# NLM_NAME Thread will be used. +# +NLM_THREAD_NAME = + +# +# If this is specified, it will override VERSION value in +# $(AP_WORK)\build\NWGNUenvironment.inc +# +NLM_VERSION = + +# +# If this is specified, it will override the default of 64K +# +NLM_STACK_SIZE = + + +# +# If this is specified it will be used by the link '-entry' directive +# +NLM_ENTRY_SYM = + +# +# If this is specified it will be used by the link '-exit' directive +# +NLM_EXIT_SYM = + +# +# If this is specified it will be used by the link '-check' directive +# +NLM_CHECK_SYM = + +# +# If these are specified it will be used by the link '-flags' directive +# +NLM_FLAGS = + +# +# If this is specified it will be linked in with the XDCData option in the def +# file instead of the default of $(NWOS)/apache.xdc. XDCData can be disabled +# by setting APACHE_UNIPROC in the environment +# +XDCDATA = + +# +# If there is an NLM target, put it here +# +TARGET_nlm = \ + $(OBJDIR)/rewrite.nlm \ + $(OBJDIR)/speling.nlm \ + $(OBJDIR)/vhost.nlm \ + $(EOLIST) + +# +# If there is an LIB target, put it here +# +TARGET_lib = \ + $(EOLIST) + +# +# These are the OBJ files needed to create the NLM target above. +# Paths must all use the '/' character +# +FILES_nlm_objs = \ + $(EOLIST) + +# +# These are the LIB files needed to create the NLM target above. +# These will be added as a library command in the link.opt file. +# +FILES_nlm_libs = \ + $(EOLIST) + +# +# These are the modules that the above NLM target depends on to load. +# These will be added as a module command in the link.opt file. +# +FILES_nlm_modules = \ + $(EOLIST) + +# +# If the nlm has a msg file, put it's path here +# +FILE_nlm_msg = + +# +# If the nlm has a hlp file put it's path here +# +FILE_nlm_hlp = + +# +# If this is specified, it will override $(NWOS)\copyright.txt. +# +FILE_nlm_copyright = + +# +# Any additional imports go here +# +FILES_nlm_Ximports = \ + $(EOLIST) + +# +# Any symbols exported to here +# +FILES_nlm_exports = \ + $(EOLIST) + +# +# These are the OBJ files needed to create the LIB target above. +# Paths must all use the '/' character +# +FILES_lib_objs = \ + $(EOLIST) + +# +# implement targets and dependancies (leave this section alone) +# + +libs :: $(OBJDIR) $(TARGET_lib) + +nlms :: libs $(TARGET_nlm) + +# +# Updated this target to create necessary directories and copy files to the +# correct place. (See $(AP_WORK)\build\NWGNUhead.inc for examples) +# +install :: nlms FORCE + copy $(OBJDIR)\*.nlm $(INSTALL)\Apache2\modules\*.* + +# +# Any specialized rules here +# + +# +# Include the 'tail' makefile that has targets that depend on variables defined +# in this makefile +# + +include $(AP_WORK)\build\NWGNUtail.inc + + diff --git a/modules/mappers/NWGNUrewrite b/modules/mappers/NWGNUrewrite new file mode 100644 index 0000000000..9e8b21f960 --- /dev/null +++ b/modules/mappers/NWGNUrewrite @@ -0,0 +1,249 @@ +# +# Make sure all needed macro's are defined +# + +# +# Get the 'head' of the build environment if necessary. This includes default +# targets and paths to tools +# + +ifndef EnvironmentDefined +include $(AP_WORK)\build\NWGNUhead.inc +endif + +# +# These directories will be at the beginning of the include list, followed by +# INCDIRS +# +XINCDIRS += \ + $(AP_WORK)/include \ + $(NWOS) \ + $(AP_WORK)/modules/arch/netware \ + $(AP_WORK)/srclib/apr/include \ + $(AP_WORK)/srclib/apr-util/include \ + $(AP_WORK)/srclib/apr \ + $(EOLIST) + +# +# These flags will come after CFLAGS +# +XCFLAGS += \ + $(EOLIST) + +# +# These defines will come after DEFINES +# +XDEFINES += \ + $(EOLIST) + +# +# These flags will be added to the link.opt file +# +XLFLAGS += \ + $(EOLIST) + +# +# These values will be appended to the correct variables based on the value of +# RELEASE +# +ifeq "$(RELEASE)" "debug" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "noopt" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "release" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +# +# These are used by the link target if an NLM is being generated +# This is used by the link 'name' directive to name the nlm. If left blank +# TARGET_nlm (see below) will be used. +# +NLM_NAME = rewrite + +# +# This is used by the link '-desc ' directive. +# If left blank, NLM_NAME will be used. +# +NLM_DESCRIPTION = Rewrite Module + +# +# This is used by the '-threadname' directive. If left blank, +# NLM_NAME Thread will be used. +# +NLM_THREAD_NAME = Rewrite Module + +# +# If this is specified, it will override VERSION value in +# $(AP_WORK)\build\NWGNUenvironment.inc +# +NLM_VERSION = + +# +# If this is specified, it will override the default of 64K +# +NLM_STACK_SIZE = 8192 + + +# +# If this is specified it will be used by the link '-entry' directive +# +NLM_ENTRY_SYM = _LibCPrelude + +# +# If this is specified it will be used by the link '-exit' directive +# +NLM_EXIT_SYM = _LibCPostlude + +# +# If this is specified it will be used by the link '-check' directive +# +NLM_CHECK_SYM = + +# +# If these are specified it will be used by the link '-flags' directive +# +NLM_FLAGS = AUTOUNLOAD, PSEUDOPREEMPTION + +# +# If this is specified it will be linked in with the XDCData option in the def +# file instead of the default of $(NWOS)/apache.xdc. XDCData can be disabled +# by setting APACHE_UNIPROC in the environment +# +XDCDATA = + +# +# If there is an NLM target, put it here +# +TARGET_nlm = \ + $(OBJDIR)/rewrite.nlm \ + $(EOLIST) + +# +# If there is an LIB target, put it here +# +TARGET_lib = \ + $(EOLIST) + +# +# These are the OBJ files needed to create the NLM target above. +# Paths must all use the '/' character +# +FILES_nlm_objs = \ + $(OBJDIR)/mod_rewrite.o \ + $(EOLIST) + +# +# These are the LIB files needed to create the NLM target above. +# These will be added as a library command in the link.opt file. +# +FILES_nlm_libs = \ + libcpre.o \ + $(EOLIST) + +# +# These are the modules that the above NLM target depends on to load. +# These will be added as a module command in the link.opt file. +# +FILES_nlm_modules = \ + aprlib \ + libc \ + $(EOLIST) + +# +# If the nlm has a msg file, put it's path here +# +FILE_nlm_msg = + +# +# If the nlm has a hlp file put it's path here +# +FILE_nlm_hlp = + +# +# If this is specified, it will override $(NWOS)\copyright.txt. +# +FILE_nlm_copyright = + +# +# Any additional imports go here +# +FILES_nlm_Ximports = \ + @$(APR)/aprlib.imp \ + @$(NWOS)/httpd.imp \ + @libc.imp \ + $(EOLIST) + +# +# Any symbols exported to here +# +FILES_nlm_exports = \ + rewrite_module \ + $(EOLIST) + +# +# These are the OBJ files needed to create the LIB target above. +# Paths must all use the '/' character +# +FILES_lib_objs = \ + $(EOLIST) + +# +# implement targets and dependancies (leave this section alone) +# + +libs :: $(OBJDIR) $(TARGET_lib) + +nlms :: libs $(TARGET_nlm) + +# +# Updated this target to create necessary directories and copy files to the +# correct place. (See $(AP_WORK)\build\NWGNUhead.inc for examples) +# +install :: nlms FORCE + +# +# Any specialized rules here +# + +# +# Include the 'tail' makefile that has targets that depend on variables defined +# in this makefile +# + +include $(AP_WORK)\build\NWGNUtail.inc + diff --git a/modules/mappers/NWGNUspeling b/modules/mappers/NWGNUspeling new file mode 100644 index 0000000000..fdd42631cf --- /dev/null +++ b/modules/mappers/NWGNUspeling @@ -0,0 +1,249 @@ +# +# Make sure all needed macro's are defined +# + +# +# Get the 'head' of the build environment if necessary. This includes default +# targets and paths to tools +# + +ifndef EnvironmentDefined +include $(AP_WORK)\build\NWGNUhead.inc +endif + +# +# These directories will be at the beginning of the include list, followed by +# INCDIRS +# +XINCDIRS += \ + $(AP_WORK)/include \ + $(NWOS) \ + $(AP_WORK)/modules/arch/netware \ + $(AP_WORK)/srclib/apr/include \ + $(AP_WORK)/srclib/apr-util/include \ + $(AP_WORK)/srclib/apr \ + $(EOLIST) + +# +# These flags will come after CFLAGS +# +XCFLAGS += \ + $(EOLIST) + +# +# These defines will come after DEFINES +# +XDEFINES += \ + $(EOLIST) + +# +# These flags will be added to the link.opt file +# +XLFLAGS += \ + $(EOLIST) + +# +# These values will be appended to the correct variables based on the value of +# RELEASE +# +ifeq "$(RELEASE)" "debug" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "noopt" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "release" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +# +# These are used by the link target if an NLM is being generated +# This is used by the link 'name' directive to name the nlm. If left blank +# TARGET_nlm (see below) will be used. +# +NLM_NAME = speling + +# +# This is used by the link '-desc ' directive. +# If left blank, NLM_NAME will be used. +# +NLM_DESCRIPTION = Speling Module + +# +# This is used by the '-threadname' directive. If left blank, +# NLM_NAME Thread will be used. +# +NLM_THREAD_NAME = Speling Module + +# +# If this is specified, it will override VERSION value in +# $(AP_WORK)\build\NWGNUenvironment.inc +# +NLM_VERSION = + +# +# If this is specified, it will override the default of 64K +# +NLM_STACK_SIZE = 8192 + + +# +# If this is specified it will be used by the link '-entry' directive +# +NLM_ENTRY_SYM = _LibCPrelude + +# +# If this is specified it will be used by the link '-exit' directive +# +NLM_EXIT_SYM = _LibCPostlude + +# +# If this is specified it will be used by the link '-check' directive +# +NLM_CHECK_SYM = + +# +# If these are specified it will be used by the link '-flags' directive +# +NLM_FLAGS = AUTOUNLOAD, PSEUDOPREEMPTION + +# +# If this is specified it will be linked in with the XDCData option in the def +# file instead of the default of $(NWOS)/apache.xdc. XDCData can be disabled +# by setting APACHE_UNIPROC in the environment +# +XDCDATA = + +# +# If there is an NLM target, put it here +# +TARGET_nlm = \ + $(OBJDIR)/speling.nlm \ + $(EOLIST) + +# +# If there is an LIB target, put it here +# +TARGET_lib = \ + $(EOLIST) + +# +# These are the OBJ files needed to create the NLM target above. +# Paths must all use the '/' character +# +FILES_nlm_objs = \ + $(OBJDIR)/mod_speling.o \ + $(EOLIST) + +# +# These are the LIB files needed to create the NLM target above. +# These will be added as a library command in the link.opt file. +# +FILES_nlm_libs = \ + libcpre.o \ + $(EOLIST) + +# +# These are the modules that the above NLM target depends on to load. +# These will be added as a module command in the link.opt file. +# +FILES_nlm_modules = \ + aprlib \ + libc \ + $(EOLIST) + +# +# If the nlm has a msg file, put it's path here +# +FILE_nlm_msg = + +# +# If the nlm has a hlp file put it's path here +# +FILE_nlm_hlp = + +# +# If this is specified, it will override $(NWOS)\copyright.txt. +# +FILE_nlm_copyright = + +# +# Any additional imports go here +# +FILES_nlm_Ximports = \ + @$(APR)/aprlib.imp \ + @$(NWOS)/httpd.imp \ + @libc.imp \ + $(EOLIST) + +# +# Any symbols exported to here +# +FILES_nlm_exports = \ + speling_module \ + $(EOLIST) + +# +# These are the OBJ files needed to create the LIB target above. +# Paths must all use the '/' character +# +FILES_lib_objs = \ + $(EOLIST) + +# +# implement targets and dependancies (leave this section alone) +# + +libs :: $(OBJDIR) $(TARGET_lib) + +nlms :: libs $(TARGET_nlm) + +# +# Updated this target to create necessary directories and copy files to the +# correct place. (See $(AP_WORK)\build\NWGNUhead.inc for examples) +# +install :: nlms FORCE + +# +# Any specialized rules here +# + +# +# Include the 'tail' makefile that has targets that depend on variables defined +# in this makefile +# + +include $(AP_WORK)\build\NWGNUtail.inc + diff --git a/modules/mappers/NWGNUvhost b/modules/mappers/NWGNUvhost new file mode 100644 index 0000000000..a2ee7789bb --- /dev/null +++ b/modules/mappers/NWGNUvhost @@ -0,0 +1,249 @@ +# +# Make sure all needed macro's are defined +# + +# +# Get the 'head' of the build environment if necessary. This includes default +# targets and paths to tools +# + +ifndef EnvironmentDefined +include $(AP_WORK)\build\NWGNUhead.inc +endif + +# +# These directories will be at the beginning of the include list, followed by +# INCDIRS +# +XINCDIRS += \ + $(AP_WORK)/include \ + $(NWOS) \ + $(AP_WORK)/modules/arch/netware \ + $(AP_WORK)/srclib/apr/include \ + $(AP_WORK)/srclib/apr-util/include \ + $(AP_WORK)/srclib/apr \ + $(EOLIST) + +# +# These flags will come after CFLAGS +# +XCFLAGS += \ + $(EOLIST) + +# +# These defines will come after DEFINES +# +XDEFINES += \ + $(EOLIST) + +# +# These flags will be added to the link.opt file +# +XLFLAGS += \ + $(EOLIST) + +# +# These values will be appended to the correct variables based on the value of +# RELEASE +# +ifeq "$(RELEASE)" "debug" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "noopt" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "release" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +# +# These are used by the link target if an NLM is being generated +# This is used by the link 'name' directive to name the nlm. If left blank +# TARGET_nlm (see below) will be used. +# +NLM_NAME = vhost + +# +# This is used by the link '-desc ' directive. +# If left blank, NLM_NAME will be used. +# +NLM_DESCRIPTION = Vhost Alias Module + +# +# This is used by the '-threadname' directive. If left blank, +# NLM_NAME Thread will be used. +# +NLM_THREAD_NAME = Vhost Alias Module + +# +# If this is specified, it will override VERSION value in +# $(AP_WORK)\build\NWGNUenvironment.inc +# +NLM_VERSION = + +# +# If this is specified, it will override the default of 64K +# +NLM_STACK_SIZE = 8192 + + +# +# If this is specified it will be used by the link '-entry' directive +# +NLM_ENTRY_SYM = _LibCPrelude + +# +# If this is specified it will be used by the link '-exit' directive +# +NLM_EXIT_SYM = _LibCPostlude + +# +# If this is specified it will be used by the link '-check' directive +# +NLM_CHECK_SYM = + +# +# If these are specified it will be used by the link '-flags' directive +# +NLM_FLAGS = AUTOUNLOAD, PSEUDOPREEMPTION + +# +# If this is specified it will be linked in with the XDCData option in the def +# file instead of the default of $(NWOS)/apache.xdc. XDCData can be disabled +# by setting APACHE_UNIPROC in the environment +# +XDCDATA = + +# +# If there is an NLM target, put it here +# +TARGET_nlm = \ + $(OBJDIR)/vhost.nlm \ + $(EOLIST) + +# +# If there is an LIB target, put it here +# +TARGET_lib = \ + $(EOLIST) + +# +# These are the OBJ files needed to create the NLM target above. +# Paths must all use the '/' character +# +FILES_nlm_objs = \ + $(OBJDIR)/mod_vhost_alias.o \ + $(EOLIST) + +# +# These are the LIB files needed to create the NLM target above. +# These will be added as a library command in the link.opt file. +# +FILES_nlm_libs = \ + libcpre.o \ + $(EOLIST) + +# +# These are the modules that the above NLM target depends on to load. +# These will be added as a module command in the link.opt file. +# +FILES_nlm_modules = \ + aprlib \ + libc \ + $(EOLIST) + +# +# If the nlm has a msg file, put it's path here +# +FILE_nlm_msg = + +# +# If the nlm has a hlp file put it's path here +# +FILE_nlm_hlp = + +# +# If this is specified, it will override $(NWOS)\copyright.txt. +# +FILE_nlm_copyright = + +# +# Any additional imports go here +# +FILES_nlm_Ximports = \ + @$(APR)/aprlib.imp \ + @$(NWOS)/httpd.imp \ + @libc.imp \ + $(EOLIST) + +# +# Any symbols exported to here +# +FILES_nlm_exports = \ + vhost_alias_module \ + $(EOLIST) + +# +# These are the OBJ files needed to create the LIB target above. +# Paths must all use the '/' character +# +FILES_lib_objs = \ + $(EOLIST) + +# +# implement targets and dependancies (leave this section alone) +# + +libs :: $(OBJDIR) $(TARGET_lib) + +nlms :: libs $(TARGET_nlm) + +# +# Updated this target to create necessary directories and copy files to the +# correct place. (See $(AP_WORK)\build\NWGNUhead.inc for examples) +# +install :: nlms FORCE + +# +# Any specialized rules here +# + +# +# Include the 'tail' makefile that has targets that depend on variables defined +# in this makefile +# + +include $(AP_WORK)\build\NWGNUtail.inc + diff --git a/modules/mappers/mod_actions.dsp b/modules/mappers/mod_actions.dsp new file mode 100644 index 0000000000..39fed166db --- /dev/null +++ b/modules/mappers/mod_actions.dsp @@ -0,0 +1,128 @@ +# Microsoft Developer Studio Project File - Name="mod_actions" - Package Owner=<4> +# Microsoft Developer Studio Generated Build File, Format Version 6.00 +# ** DO NOT EDIT ** + +# TARGTYPE "Win32 (x86) Dynamic-Link Library" 0x0102 + +CFG=mod_actions - Win32 Release +!MESSAGE This is not a valid makefile. To build this project using NMAKE, +!MESSAGE use the Export Makefile command and run +!MESSAGE +!MESSAGE NMAKE /f "mod_actions.mak". +!MESSAGE +!MESSAGE You can specify a configuration when running NMAKE +!MESSAGE by defining the macro CFG on the command line. For example: +!MESSAGE +!MESSAGE NMAKE /f "mod_actions.mak" CFG="mod_actions - Win32 Release" +!MESSAGE +!MESSAGE Possible choices for configuration are: +!MESSAGE +!MESSAGE "mod_actions - Win32 Release" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE "mod_actions - Win32 Debug" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE + +# Begin Project +# PROP AllowPerConfigDependencies 0 +# PROP Scc_ProjName "" +# PROP Scc_LocalPath "" +CPP=cl.exe +MTL=midl.exe +RSC=rc.exe + +!IF "$(CFG)" == "mod_actions - Win32 Release" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 0 +# PROP BASE Output_Dir "Release" +# PROP BASE Intermediate_Dir "Release" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 0 +# PROP Output_Dir "Release" +# PROP Intermediate_Dir "Release" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MD /W3 /O2 /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /FD /c +# ADD CPP /nologo /MD /W3 /O2 /I "../../include" /I "../../srclib/apr/include" /I "../../srclib/apr-util/include" /D "NDEBUG" /D "WIN32" /D "_WINDOWS" /Fd"Release\mod_actions" /FD /c +# ADD BASE MTL /nologo /D "NDEBUG" /win32 +# ADD MTL /nologo /D "NDEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x409 /d "NDEBUG" +# ADD RSC /l 0x409 /d "NDEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib /nologo /subsystem:windows /dll /map /machine:I386 /out:"Release/mod_actions.so" /base:@..\..\os\win32\BaseAddr.ref,mod_actions +# ADD LINK32 kernel32.lib /nologo /subsystem:windows /dll /map /machine:I386 /out:"Release/mod_actions.so" /base:@..\..\os\win32\BaseAddr.ref,mod_actions + +!ELSEIF "$(CFG)" == "mod_actions - Win32 Debug" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 1 +# PROP BASE Output_Dir "Debug" +# PROP BASE Intermediate_Dir "Debug" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 1 +# PROP Output_Dir "Debug" +# PROP Intermediate_Dir "Debug" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MDd /W3 /GX /Zi /Od /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /FD /c +# ADD CPP /nologo /MDd /W3 /GX /Zi /Od /I "../../include" /I "../../srclib/apr/include" /I "../../srclib/apr-util/include" /D "_DEBUG" /D "WIN32" /D "_WINDOWS" /Fd"Debug\mod_actions" /FD /c +# ADD BASE MTL /nologo /D "_DEBUG" /win32 +# ADD MTL /nologo /D "_DEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x409 /d "_DEBUG" +# ADD RSC /l 0x409 /d "_DEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib /nologo /subsystem:windows /dll /incremental:no /map /debug /machine:I386 /out:"Debug/mod_actions.so" /base:@..\..\os\win32\BaseAddr.ref,mod_actions +# ADD LINK32 kernel32.lib /nologo /subsystem:windows /dll /incremental:no /map /debug /machine:I386 /out:"Debug/mod_actions.so" /base:@..\..\os\win32\BaseAddr.ref,mod_actions + +!ENDIF + +# Begin Target + +# Name "mod_actions - Win32 Release" +# Name "mod_actions - Win32 Debug" +# Begin Source File + +SOURCE=.\mod_actions.c +# End Source File +# Begin Source File + +SOURCE=.\mod_actions.rc +# End Source File +# Begin Source File + +SOURCE=..\..\build\win32\win32ver.awk + +!IF "$(CFG)" == "mod_actions - Win32 Release" + +# PROP Ignore_Default_Tool 1 +# Begin Custom Build - Creating Version Resource +InputPath=..\..\build\win32\win32ver.awk + +".\mod_actions.rc" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)" + awk -f ../../build/win32/win32ver.awk mod_actions "actions_module for Apache" ../../include/ap_release.h > .\mod_actions.rc + +# End Custom Build + +!ELSEIF "$(CFG)" == "mod_actions - Win32 Debug" + +# PROP Ignore_Default_Tool 1 +# Begin Custom Build - Creating Version Resource +InputPath=..\..\build\win32\win32ver.awk + +".\mod_actions.rc" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)" + awk -f ../../build/win32/win32ver.awk mod_actions "actions_module for Apache" ../../include/ap_release.h > .\mod_actions.rc + +# End Custom Build + +!ENDIF + +# End Source File +# End Target +# End Project diff --git a/modules/mappers/mod_alias.dsp b/modules/mappers/mod_alias.dsp new file mode 100644 index 0000000000..d09c7affec --- /dev/null +++ b/modules/mappers/mod_alias.dsp @@ -0,0 +1,128 @@ +# Microsoft Developer Studio Project File - Name="mod_alias" - Package Owner=<4> +# Microsoft Developer Studio Generated Build File, Format Version 6.00 +# ** DO NOT EDIT ** + +# TARGTYPE "Win32 (x86) Dynamic-Link Library" 0x0102 + +CFG=mod_alias - Win32 Release +!MESSAGE This is not a valid makefile. To build this project using NMAKE, +!MESSAGE use the Export Makefile command and run +!MESSAGE +!MESSAGE NMAKE /f "mod_alias.mak". +!MESSAGE +!MESSAGE You can specify a configuration when running NMAKE +!MESSAGE by defining the macro CFG on the command line. For example: +!MESSAGE +!MESSAGE NMAKE /f "mod_alias.mak" CFG="mod_alias - Win32 Release" +!MESSAGE +!MESSAGE Possible choices for configuration are: +!MESSAGE +!MESSAGE "mod_alias - Win32 Release" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE "mod_alias - Win32 Debug" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE + +# Begin Project +# PROP AllowPerConfigDependencies 0 +# PROP Scc_ProjName "" +# PROP Scc_LocalPath "" +CPP=cl.exe +MTL=midl.exe +RSC=rc.exe + +!IF "$(CFG)" == "mod_alias - Win32 Release" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 0 +# PROP BASE Output_Dir "Release" +# PROP BASE Intermediate_Dir "Release" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 0 +# PROP Output_Dir "Release" +# PROP Intermediate_Dir "Release" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MD /W3 /O2 /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /FD /c +# ADD CPP /nologo /MD /W3 /O2 /I "../../include" /I "../../srclib/apr/include" /I "../../srclib/apr-util/include" /D "NDEBUG" /D "WIN32" /D "_WINDOWS" /Fd"Release\mod_alias" /FD /c +# ADD BASE MTL /nologo /D "NDEBUG" /win32 +# ADD MTL /nologo /D "NDEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x409 /d "NDEBUG" +# ADD RSC /l 0x409 /d "NDEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib /nologo /subsystem:windows /dll /map /machine:I386 /out:"Release/mod_alias.so" /base:@..\..\os\win32\BaseAddr.ref,mod_alias +# ADD LINK32 kernel32.lib /nologo /subsystem:windows /dll /map /machine:I386 /out:"Release/mod_alias.so" /base:@..\..\os\win32\BaseAddr.ref,mod_alias + +!ELSEIF "$(CFG)" == "mod_alias - Win32 Debug" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 1 +# PROP BASE Output_Dir "Debug" +# PROP BASE Intermediate_Dir "Debug" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 1 +# PROP Output_Dir "Debug" +# PROP Intermediate_Dir "Debug" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MDd /W3 /GX /Zi /Od /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /FD /c +# ADD CPP /nologo /MDd /W3 /GX /Zi /Od /I "../../include" /I "../../srclib/apr/include" /I "../../srclib/apr-util/include" /D "_DEBUG" /D "WIN32" /D "_WINDOWS" /Fd"Debug\mod_alias" /FD /c +# ADD BASE MTL /nologo /D "_DEBUG" /win32 +# ADD MTL /nologo /D "_DEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x409 /d "_DEBUG" +# ADD RSC /l 0x409 /d "_DEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib /nologo /subsystem:windows /dll /incremental:no /map /debug /machine:I386 /out:"Debug/mod_alias.so" /base:@..\..\os\win32\BaseAddr.ref,mod_alias +# ADD LINK32 kernel32.lib /nologo /subsystem:windows /dll /incremental:no /map /debug /machine:I386 /out:"Debug/mod_alias.so" /base:@..\..\os\win32\BaseAddr.ref,mod_alias + +!ENDIF + +# Begin Target + +# Name "mod_alias - Win32 Release" +# Name "mod_alias - Win32 Debug" +# Begin Source File + +SOURCE=.\mod_alias.c +# End Source File +# Begin Source File + +SOURCE=.\mod_alias.rc +# End Source File +# Begin Source File + +SOURCE=..\..\build\win32\win32ver.awk + +!IF "$(CFG)" == "mod_alias - Win32 Release" + +# PROP Ignore_Default_Tool 1 +# Begin Custom Build - Creating Version Resource +InputPath=..\..\build\win32\win32ver.awk + +".\mod_alias.rc" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)" + awk -f ../../build/win32/win32ver.awk mod_alias "alias_module for Apache" ../../include/ap_release.h > .\mod_alias.rc + +# End Custom Build + +!ELSEIF "$(CFG)" == "mod_alias - Win32 Debug" + +# PROP Ignore_Default_Tool 1 +# Begin Custom Build - Creating Version Resource +InputPath=..\..\build\win32\win32ver.awk + +".\mod_alias.rc" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)" + awk -f ../../build/win32/win32ver.awk mod_alias "alias_module for Apache" ../../include/ap_release.h > .\mod_alias.rc + +# End Custom Build + +!ENDIF + +# End Source File +# End Target +# End Project diff --git a/modules/mappers/mod_dir.dsp b/modules/mappers/mod_dir.dsp new file mode 100644 index 0000000000..aad198e881 --- /dev/null +++ b/modules/mappers/mod_dir.dsp @@ -0,0 +1,128 @@ +# Microsoft Developer Studio Project File - Name="mod_dir" - Package Owner=<4> +# Microsoft Developer Studio Generated Build File, Format Version 6.00 +# ** DO NOT EDIT ** + +# TARGTYPE "Win32 (x86) Dynamic-Link Library" 0x0102 + +CFG=mod_dir - Win32 Release +!MESSAGE This is not a valid makefile. To build this project using NMAKE, +!MESSAGE use the Export Makefile command and run +!MESSAGE +!MESSAGE NMAKE /f "mod_dir.mak". +!MESSAGE +!MESSAGE You can specify a configuration when running NMAKE +!MESSAGE by defining the macro CFG on the command line. For example: +!MESSAGE +!MESSAGE NMAKE /f "mod_dir.mak" CFG="mod_dir - Win32 Release" +!MESSAGE +!MESSAGE Possible choices for configuration are: +!MESSAGE +!MESSAGE "mod_dir - Win32 Release" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE "mod_dir - Win32 Debug" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE + +# Begin Project +# PROP AllowPerConfigDependencies 0 +# PROP Scc_ProjName "" +# PROP Scc_LocalPath "" +CPP=cl.exe +MTL=midl.exe +RSC=rc.exe + +!IF "$(CFG)" == "mod_dir - Win32 Release" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 0 +# PROP BASE Output_Dir "Release" +# PROP BASE Intermediate_Dir "Release" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 0 +# PROP Output_Dir "Release" +# PROP Intermediate_Dir "Release" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MD /W3 /O2 /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /FD /c +# ADD CPP /nologo /MD /W3 /O2 /I "../../include" /I "../../srclib/apr/include" /I "../../srclib/apr-util/include" /D "NDEBUG" /D "WIN32" /D "_WINDOWS" /Fd"Release\mod_dir" /FD /c +# ADD BASE MTL /nologo /D "NDEBUG" /win32 +# ADD MTL /nologo /D "NDEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x409 /d "NDEBUG" +# ADD RSC /l 0x409 /d "NDEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib /nologo /subsystem:windows /dll /map /machine:I386 /out:"Release/mod_dir.so" /base:@..\..\os\win32\BaseAddr.ref,mod_dir +# ADD LINK32 kernel32.lib /nologo /subsystem:windows /dll /map /machine:I386 /out:"Release/mod_dir.so" /base:@..\..\os\win32\BaseAddr.ref,mod_dir + +!ELSEIF "$(CFG)" == "mod_dir - Win32 Debug" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 1 +# PROP BASE Output_Dir "Debug" +# PROP BASE Intermediate_Dir "Debug" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 1 +# PROP Output_Dir "Debug" +# PROP Intermediate_Dir "Debug" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MDd /W3 /GX /Zi /Od /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /FD /c +# ADD CPP /nologo /MDd /W3 /GX /Zi /Od /I "../../include" /I "../../srclib/apr/include" /I "../../srclib/apr-util/include" /D "_DEBUG" /D "WIN32" /D "_WINDOWS" /Fd"Debug\mod_dir" /FD /c +# ADD BASE MTL /nologo /D "_DEBUG" /win32 +# ADD MTL /nologo /D "_DEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x409 /d "_DEBUG" +# ADD RSC /l 0x409 /d "_DEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib /nologo /subsystem:windows /dll /incremental:no /map /debug /machine:I386 /out:"Debug/mod_dir.so" /base:@..\..\os\win32\BaseAddr.ref,mod_dir +# ADD LINK32 kernel32.lib /nologo /subsystem:windows /dll /incremental:no /map /debug /machine:I386 /out:"Debug/mod_dir.so" /base:@..\..\os\win32\BaseAddr.ref,mod_dir + +!ENDIF + +# Begin Target + +# Name "mod_dir - Win32 Release" +# Name "mod_dir - Win32 Debug" +# Begin Source File + +SOURCE=.\mod_dir.c +# End Source File +# Begin Source File + +SOURCE=.\mod_dir.rc +# End Source File +# Begin Source File + +SOURCE=..\..\build\win32\win32ver.awk + +!IF "$(CFG)" == "mod_dir - Win32 Release" + +# PROP Ignore_Default_Tool 1 +# Begin Custom Build - Creating Version Resource +InputPath=..\..\build\win32\win32ver.awk + +".\mod_dir.rc" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)" + awk -f ../../build/win32/win32ver.awk mod_dir "dir_module for Apache" ../../include/ap_release.h > .\mod_dir.rc + +# End Custom Build + +!ELSEIF "$(CFG)" == "mod_dir - Win32 Debug" + +# PROP Ignore_Default_Tool 1 +# Begin Custom Build - Creating Version Resource +InputPath=..\..\build\win32\win32ver.awk + +".\mod_dir.rc" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)" + awk -f ../../build/win32/win32ver.awk mod_dir "dir_module for Apache" ../../include/ap_release.h > .\mod_dir.rc + +# End Custom Build + +!ENDIF + +# End Source File +# End Target +# End Project diff --git a/modules/mappers/mod_imap.dsp b/modules/mappers/mod_imap.dsp new file mode 100644 index 0000000000..94570696f6 --- /dev/null +++ b/modules/mappers/mod_imap.dsp @@ -0,0 +1,128 @@ +# Microsoft Developer Studio Project File - Name="mod_imap" - Package Owner=<4> +# Microsoft Developer Studio Generated Build File, Format Version 6.00 +# ** DO NOT EDIT ** + +# TARGTYPE "Win32 (x86) Dynamic-Link Library" 0x0102 + +CFG=mod_imap - Win32 Release +!MESSAGE This is not a valid makefile. To build this project using NMAKE, +!MESSAGE use the Export Makefile command and run +!MESSAGE +!MESSAGE NMAKE /f "mod_imap.mak". +!MESSAGE +!MESSAGE You can specify a configuration when running NMAKE +!MESSAGE by defining the macro CFG on the command line. For example: +!MESSAGE +!MESSAGE NMAKE /f "mod_imap.mak" CFG="mod_imap - Win32 Release" +!MESSAGE +!MESSAGE Possible choices for configuration are: +!MESSAGE +!MESSAGE "mod_imap - Win32 Release" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE "mod_imap - Win32 Debug" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE + +# Begin Project +# PROP AllowPerConfigDependencies 0 +# PROP Scc_ProjName "" +# PROP Scc_LocalPath "" +CPP=cl.exe +MTL=midl.exe +RSC=rc.exe + +!IF "$(CFG)" == "mod_imap - Win32 Release" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 0 +# PROP BASE Output_Dir "Release" +# PROP BASE Intermediate_Dir "Release" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 0 +# PROP Output_Dir "Release" +# PROP Intermediate_Dir "Release" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MD /W3 /O2 /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /FD /c +# ADD CPP /nologo /MD /W3 /O2 /I "../../include" /I "../../srclib/apr/include" /I "../../srclib/apr-util/include" /D "NDEBUG" /D "WIN32" /D "_WINDOWS" /Fd"Release\mod_imap" /FD /c +# ADD BASE MTL /nologo /D "NDEBUG" /win32 +# ADD MTL /nologo /D "NDEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x409 /d "NDEBUG" +# ADD RSC /l 0x409 /d "NDEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib /nologo /subsystem:windows /dll /map /machine:I386 /out:"Release/mod_imap.so" /base:@..\..\os\win32\BaseAddr.ref,mod_imap +# ADD LINK32 kernel32.lib /nologo /subsystem:windows /dll /map /machine:I386 /out:"Release/mod_imap.so" /base:@..\..\os\win32\BaseAddr.ref,mod_imap + +!ELSEIF "$(CFG)" == "mod_imap - Win32 Debug" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 1 +# PROP BASE Output_Dir "Debug" +# PROP BASE Intermediate_Dir "Debug" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 1 +# PROP Output_Dir "Debug" +# PROP Intermediate_Dir "Debug" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MDd /W3 /GX /Zi /Od /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /FD /c +# ADD CPP /nologo /MDd /W3 /GX /Zi /Od /I "../../include" /I "../../srclib/apr/include" /I "../../srclib/apr-util/include" /D "_DEBUG" /D "WIN32" /D "_WINDOWS" /Fd"Debug\mod_imap" /FD /c +# ADD BASE MTL /nologo /D "_DEBUG" /win32 +# ADD MTL /nologo /D "_DEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x409 /d "_DEBUG" +# ADD RSC /l 0x409 /d "_DEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib /nologo /subsystem:windows /dll /incremental:no /map /debug /machine:I386 /out:"Debug/mod_imap.so" /base:@..\..\os\win32\BaseAddr.ref,mod_imap +# ADD LINK32 kernel32.lib /nologo /subsystem:windows /dll /incremental:no /map /debug /machine:I386 /out:"Debug/mod_imap.so" /base:@..\..\os\win32\BaseAddr.ref,mod_imap + +!ENDIF + +# Begin Target + +# Name "mod_imap - Win32 Release" +# Name "mod_imap - Win32 Debug" +# Begin Source File + +SOURCE=.\mod_imap.c +# End Source File +# Begin Source File + +SOURCE=.\mod_imap.rc +# End Source File +# Begin Source File + +SOURCE=..\..\build\win32\win32ver.awk + +!IF "$(CFG)" == "mod_imap - Win32 Release" + +# PROP Ignore_Default_Tool 1 +# Begin Custom Build - Creating Version Resource +InputPath=..\..\build\win32\win32ver.awk + +".\mod_imap.rc" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)" + awk -f ../../build/win32/win32ver.awk mod_imap "imap_module for Apache" ../../include/ap_release.h > .\mod_imap.rc + +# End Custom Build + +!ELSEIF "$(CFG)" == "mod_imap - Win32 Debug" + +# PROP Ignore_Default_Tool 1 +# Begin Custom Build - Creating Version Resource +InputPath=..\..\build\win32\win32ver.awk + +".\mod_imap.rc" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)" + awk -f ../../build/win32/win32ver.awk mod_imap "imap_module for Apache" ../../include/ap_release.h > .\mod_imap.rc + +# End Custom Build + +!ENDIF + +# End Source File +# End Target +# End Project diff --git a/modules/mappers/mod_negotiation.dsp b/modules/mappers/mod_negotiation.dsp new file mode 100644 index 0000000000..fd264fb1de --- /dev/null +++ b/modules/mappers/mod_negotiation.dsp @@ -0,0 +1,128 @@ +# Microsoft Developer Studio Project File - Name="mod_negotiation" - Package Owner=<4> +# Microsoft Developer Studio Generated Build File, Format Version 6.00 +# ** DO NOT EDIT ** + +# TARGTYPE "Win32 (x86) Dynamic-Link Library" 0x0102 + +CFG=mod_negotiation - Win32 Release +!MESSAGE This is not a valid makefile. To build this project using NMAKE, +!MESSAGE use the Export Makefile command and run +!MESSAGE +!MESSAGE NMAKE /f "mod_negotiation.mak". +!MESSAGE +!MESSAGE You can specify a configuration when running NMAKE +!MESSAGE by defining the macro CFG on the command line. For example: +!MESSAGE +!MESSAGE NMAKE /f "mod_negotiation.mak" CFG="mod_negotiation - Win32 Release" +!MESSAGE +!MESSAGE Possible choices for configuration are: +!MESSAGE +!MESSAGE "mod_negotiation - Win32 Release" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE "mod_negotiation - Win32 Debug" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE + +# Begin Project +# PROP AllowPerConfigDependencies 0 +# PROP Scc_ProjName "" +# PROP Scc_LocalPath "" +CPP=cl.exe +MTL=midl.exe +RSC=rc.exe + +!IF "$(CFG)" == "mod_negotiation - Win32 Release" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 0 +# PROP BASE Output_Dir "Release" +# PROP BASE Intermediate_Dir "Release" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 0 +# PROP Output_Dir "Release" +# PROP Intermediate_Dir "Release" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MD /W3 /O2 /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /FD /c +# ADD CPP /nologo /MD /W3 /O2 /I "../../include" /I "../../srclib/apr/include" /I "../../srclib/apr-util/include" /D "NDEBUG" /D "WIN32" /D "_WINDOWS" /Fd"Release\mod_negotiation" /FD /c +# ADD BASE MTL /nologo /D "NDEBUG" /win32 +# ADD MTL /nologo /D "NDEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x409 /d "NDEBUG" +# ADD RSC /l 0x409 /d "NDEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib /nologo /subsystem:windows /dll /map /machine:I386 /out:"Release/mod_negotiation.so" /base:@..\..\os\win32\BaseAddr.ref,mod_negotiation +# ADD LINK32 kernel32.lib /nologo /subsystem:windows /dll /map /machine:I386 /out:"Release/mod_negotiation.so" /base:@..\..\os\win32\BaseAddr.ref,mod_negotiation + +!ELSEIF "$(CFG)" == "mod_negotiation - Win32 Debug" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 1 +# PROP BASE Output_Dir "Debug" +# PROP BASE Intermediate_Dir "Debug" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 1 +# PROP Output_Dir "Debug" +# PROP Intermediate_Dir "Debug" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MDd /W3 /GX /Zi /Od /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /FD /c +# ADD CPP /nologo /MDd /W3 /GX /Zi /Od /I "../../include" /I "../../srclib/apr/include" /I "../../srclib/apr-util/include" /D "_DEBUG" /D "WIN32" /D "_WINDOWS" /Fd"Debug\mod_negotiation" /FD /c +# ADD BASE MTL /nologo /D "_DEBUG" /win32 +# ADD MTL /nologo /D "_DEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x409 /d "_DEBUG" +# ADD RSC /l 0x409 /d "_DEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib /nologo /subsystem:windows /dll /incremental:no /map /debug /machine:I386 /out:"Debug/mod_negotiation.so" /base:@..\..\os\win32\BaseAddr.ref,mod_negotiation +# ADD LINK32 kernel32.lib /nologo /subsystem:windows /dll /incremental:no /map /debug /machine:I386 /out:"Debug/mod_negotiation.so" /base:@..\..\os\win32\BaseAddr.ref,mod_negotiation + +!ENDIF + +# Begin Target + +# Name "mod_negotiation - Win32 Release" +# Name "mod_negotiation - Win32 Debug" +# Begin Source File + +SOURCE=.\mod_negotiation.c +# End Source File +# Begin Source File + +SOURCE=.\mod_negotiation.rc +# End Source File +# Begin Source File + +SOURCE=..\..\build\win32\win32ver.awk + +!IF "$(CFG)" == "mod_negotiation - Win32 Release" + +# PROP Ignore_Default_Tool 1 +# Begin Custom Build - Creating Version Resource +InputPath=..\..\build\win32\win32ver.awk + +".\mod_negotiation.rc" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)" + awk -f ../../build/win32/win32ver.awk mod_negotiation "negotiation_module for Apache" ../../include/ap_release.h > .\mod_negotiation.rc + +# End Custom Build + +!ELSEIF "$(CFG)" == "mod_negotiation - Win32 Debug" + +# PROP Ignore_Default_Tool 1 +# Begin Custom Build - Creating Version Resource +InputPath=..\..\build\win32\win32ver.awk + +".\mod_negotiation.rc" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)" + awk -f ../../build/win32/win32ver.awk mod_negotiation "negotiation_module for Apache" ../../include/ap_release.h > .\mod_negotiation.rc + +# End Custom Build + +!ENDIF + +# End Source File +# End Target +# End Project diff --git a/modules/mappers/mod_userdir.dsp b/modules/mappers/mod_userdir.dsp new file mode 100644 index 0000000000..be606a9550 --- /dev/null +++ b/modules/mappers/mod_userdir.dsp @@ -0,0 +1,128 @@ +# Microsoft Developer Studio Project File - Name="mod_userdir" - Package Owner=<4> +# Microsoft Developer Studio Generated Build File, Format Version 6.00 +# ** DO NOT EDIT ** + +# TARGTYPE "Win32 (x86) Dynamic-Link Library" 0x0102 + +CFG=mod_userdir - Win32 Release +!MESSAGE This is not a valid makefile. To build this project using NMAKE, +!MESSAGE use the Export Makefile command and run +!MESSAGE +!MESSAGE NMAKE /f "mod_userdir.mak". +!MESSAGE +!MESSAGE You can specify a configuration when running NMAKE +!MESSAGE by defining the macro CFG on the command line. For example: +!MESSAGE +!MESSAGE NMAKE /f "mod_userdir.mak" CFG="mod_userdir - Win32 Release" +!MESSAGE +!MESSAGE Possible choices for configuration are: +!MESSAGE +!MESSAGE "mod_userdir - Win32 Release" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE "mod_userdir - Win32 Debug" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE + +# Begin Project +# PROP AllowPerConfigDependencies 0 +# PROP Scc_ProjName "" +# PROP Scc_LocalPath "" +CPP=cl.exe +MTL=midl.exe +RSC=rc.exe + +!IF "$(CFG)" == "mod_userdir - Win32 Release" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 0 +# PROP BASE Output_Dir "Release" +# PROP BASE Intermediate_Dir "Release" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 0 +# PROP Output_Dir "Release" +# PROP Intermediate_Dir "Release" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MD /W3 /O2 /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /FD /c +# ADD CPP /nologo /MD /W3 /O2 /I "../../include" /I "../../srclib/apr/include" /I "../../srclib/apr-util/include" /D "NDEBUG" /D "WIN32" /D "_WINDOWS" /Fd"Release\mod_userdir" /FD /c +# ADD BASE MTL /nologo /D "NDEBUG" /win32 +# ADD MTL /nologo /D "NDEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x409 /d "NDEBUG" +# ADD RSC /l 0x409 /d "NDEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib /nologo /subsystem:windows /dll /map /machine:I386 /out:"Release/mod_userdir.so" /base:@..\..\os\win32\BaseAddr.ref,mod_userdir +# ADD LINK32 kernel32.lib /nologo /subsystem:windows /dll /map /machine:I386 /out:"Release/mod_userdir.so" /base:@..\..\os\win32\BaseAddr.ref,mod_userdir + +!ELSEIF "$(CFG)" == "mod_userdir - Win32 Debug" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 1 +# PROP BASE Output_Dir "Debug" +# PROP BASE Intermediate_Dir "Debug" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 1 +# PROP Output_Dir "Debug" +# PROP Intermediate_Dir "Debug" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MDd /W3 /GX /Zi /Od /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /FD /c +# ADD CPP /nologo /MDd /W3 /GX /Zi /Od /I "../../include" /I "../../srclib/apr/include" /I "../../srclib/apr-util/include" /D "_DEBUG" /D "WIN32" /D "_WINDOWS" /Fd"Debug\mod_userdir" /FD /c +# ADD BASE MTL /nologo /D "_DEBUG" /win32 +# ADD MTL /nologo /D "_DEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x409 /d "_DEBUG" +# ADD RSC /l 0x409 /d "_DEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib /nologo /subsystem:windows /dll /incremental:no /map /debug /machine:I386 /out:"Debug/mod_userdir.so" /base:@..\..\os\win32\BaseAddr.ref,mod_userdir +# ADD LINK32 kernel32.lib /nologo /subsystem:windows /dll /incremental:no /map /debug /machine:I386 /out:"Debug/mod_userdir.so" /base:@..\..\os\win32\BaseAddr.ref,mod_userdir + +!ENDIF + +# Begin Target + +# Name "mod_userdir - Win32 Release" +# Name "mod_userdir - Win32 Debug" +# Begin Source File + +SOURCE=.\mod_userdir.c +# End Source File +# Begin Source File + +SOURCE=.\mod_userdir.rc +# End Source File +# Begin Source File + +SOURCE=..\..\build\win32\win32ver.awk + +!IF "$(CFG)" == "mod_userdir - Win32 Release" + +# PROP Ignore_Default_Tool 1 +# Begin Custom Build - Creating Version Resource +InputPath=..\..\build\win32\win32ver.awk + +".\mod_userdir.rc" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)" + awk -f ../../build/win32/win32ver.awk mod_userdir "userdir_module for Apache" ../../include/ap_release.h > .\mod_userdir.rc + +# End Custom Build + +!ELSEIF "$(CFG)" == "mod_userdir - Win32 Debug" + +# PROP Ignore_Default_Tool 1 +# Begin Custom Build - Creating Version Resource +InputPath=..\..\build\win32\win32ver.awk + +".\mod_userdir.rc" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)" + awk -f ../../build/win32/win32ver.awk mod_userdir "userdir_module for Apache" ../../include/ap_release.h > .\mod_userdir.rc + +# End Custom Build + +!ENDIF + +# End Source File +# End Target +# End Project diff --git a/modules/mappers/mod_vhost_alias.exp b/modules/mappers/mod_vhost_alias.exp new file mode 100644 index 0000000000..b17666fc86 --- /dev/null +++ b/modules/mappers/mod_vhost_alias.exp @@ -0,0 +1 @@ +vhost_alias_module diff --git a/modules/metadata/NWGNUcernmeta b/modules/metadata/NWGNUcernmeta new file mode 100644 index 0000000000..abc4cab1e3 --- /dev/null +++ b/modules/metadata/NWGNUcernmeta @@ -0,0 +1,250 @@ +# +# Make sure all needed macro's are defined +# + +# +# Get the 'head' of the build environment if necessary. This includes default +# targets and paths to tools +# + +ifndef EnvironmentDefined +include $(AP_WORK)\build\NWGNUhead.inc +endif + +# +# These directories will be at the beginning of the include list, followed by +# INCDIRS +# +XINCDIRS += \ + $(AP_WORK)/include \ + $(NWOS) \ + $(AP_WORK)/modules/arch/netware \ + $(AP_WORK)/srclib/apr/include \ + $(AP_WORK)/srclib/apr-util/include \ + $(AP_WORK)/srclib/apr \ + $(EOLIST) + +# +# These flags will come after CFLAGS +# +XCFLAGS += \ + -prefix pre_nw.h \ + $(EOLIST) + +# +# These defines will come after DEFINES +# +XDEFINES += \ + $(EOLIST) + +# +# These flags will be added to the link.opt file +# +XLFLAGS += \ + $(EOLIST) + +# +# These values will be appended to the correct variables based on the value of +# RELEASE +# +ifeq "$(RELEASE)" "debug" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "noopt" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "release" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +# +# These are used by the link target if an NLM is being generated +# This is used by the link 'name' directive to name the nlm. If left blank +# TARGET_nlm (see below) will be used. +# +NLM_NAME = cernmeta + +# +# This is used by the link '-desc ' directive. +# If left blank, NLM_NAME will be used. +# +NLM_DESCRIPTION = CERN Meta Module + +# +# This is used by the '-threadname' directive. If left blank, +# NLM_NAME Thread will be used. +# +NLM_THREAD_NAME = CERN Meta Module + +# +# If this is specified, it will override VERSION value in +# $(AP_WORK)\build\NWGNUenvironment.inc +# +NLM_VERSION = + +# +# If this is specified, it will override the default of 64K +# +NLM_STACK_SIZE = 8192 + + +# +# If this is specified it will be used by the link '-entry' directive +# +NLM_ENTRY_SYM = _LibCPrelude + +# +# If this is specified it will be used by the link '-exit' directive +# +NLM_EXIT_SYM = _LibCPostlude + +# +# If this is specified it will be used by the link '-check' directive +# +NLM_CHECK_SYM = + +# +# If these are specified it will be used by the link '-flags' directive +# +NLM_FLAGS = AUTOUNLOAD, PSEUDOPREEMPTION + +# +# If this is specified it will be linked in with the XDCData option in the def +# file instead of the default of $(NWOS)/apache.xdc. XDCData can be disabled +# by setting APACHE_UNIPROC in the environment +# +XDCDATA = + +# +# If there is an NLM target, put it here +# +TARGET_nlm = \ + $(OBJDIR)/cernmeta.nlm \ + $(EOLIST) + +# +# If there is an LIB target, put it here +# +TARGET_lib = \ + $(EOLIST) + +# +# These are the OBJ files needed to create the NLM target above. +# Paths must all use the '/' character +# +FILES_nlm_objs = \ + $(OBJDIR)/mod_cern_meta.o \ + $(EOLIST) + +# +# These are the LIB files needed to create the NLM target above. +# These will be added as a library command in the link.opt file. +# +FILES_nlm_libs = \ + libcpre.o \ + $(EOLIST) + +# +# These are the modules that the above NLM target depends on to load. +# These will be added as a module command in the link.opt file. +# +FILES_nlm_modules = \ + aprlib \ + libc \ + $(EOLIST) + +# +# If the nlm has a msg file, put it's path here +# +FILE_nlm_msg = + +# +# If the nlm has a hlp file put it's path here +# +FILE_nlm_hlp = + +# +# If this is specified, it will override $(NWOS)\copyright.txt. +# +FILE_nlm_copyright = + +# +# Any additional imports go here +# +FILES_nlm_Ximports = \ + @$(APR)/aprlib.imp \ + @$(NWOS)/httpd.imp \ + @libc.imp \ + $(EOLIST) + +# +# Any symbols exported to here +# +FILES_nlm_exports = \ + cern_meta_module \ + $(EOLIST) + +# +# These are the OBJ files needed to create the LIB target above. +# Paths must all use the '/' character +# +FILES_lib_objs = \ + $(EOLIST) + +# +# implement targets and dependancies (leave this section alone) +# + +libs :: $(OBJDIR) $(TARGET_lib) + +nlms :: libs $(TARGET_nlm) + +# +# Updated this target to create necessary directories and copy files to the +# correct place. (See $(AP_WORK)\build\NWGNUhead.inc for examples) +# +install :: nlms FORCE + +# +# Any specialized rules here +# + +# +# Include the 'tail' makefile that has targets that depend on variables defined +# in this makefile +# + +include $(AP_WORK)\build\NWGNUtail.inc + diff --git a/modules/metadata/NWGNUexpires b/modules/metadata/NWGNUexpires new file mode 100644 index 0000000000..e55fa0dad7 --- /dev/null +++ b/modules/metadata/NWGNUexpires @@ -0,0 +1,250 @@ +# +# Make sure all needed macro's are defined +# + +# +# Get the 'head' of the build environment if necessary. This includes default +# targets and paths to tools +# + +ifndef EnvironmentDefined +include $(AP_WORK)\build\NWGNUhead.inc +endif + +# +# These directories will be at the beginning of the include list, followed by +# INCDIRS +# +XINCDIRS += \ + $(AP_WORK)/include \ + $(NWOS) \ + $(AP_WORK)/modules/arch/netware \ + $(AP_WORK)/srclib/apr/include \ + $(AP_WORK)/srclib/apr-util/include \ + $(AP_WORK)/srclib/apr \ + $(EOLIST) + +# +# These flags will come after CFLAGS +# +XCFLAGS += \ + -prefix pre_nw.h \ + $(EOLIST) + +# +# These defines will come after DEFINES +# +XDEFINES += \ + $(EOLIST) + +# +# These flags will be added to the link.opt file +# +XLFLAGS += \ + $(EOLIST) + +# +# These values will be appended to the correct variables based on the value of +# RELEASE +# +ifeq "$(RELEASE)" "debug" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "noopt" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "release" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +# +# These are used by the link target if an NLM is being generated +# This is used by the link 'name' directive to name the nlm. If left blank +# TARGET_nlm (see below) will be used. +# +NLM_NAME = expires + +# +# This is used by the link '-desc ' directive. +# If left blank, NLM_NAME will be used. +# +NLM_DESCRIPTION = Expires Module + +# +# This is used by the '-threadname' directive. If left blank, +# NLM_NAME Thread will be used. +# +NLM_THREAD_NAME = Expires Module + +# +# If this is specified, it will override VERSION value in +# $(AP_WORK)\build\NWGNUenvironment.inc +# +NLM_VERSION = + +# +# If this is specified, it will override the default of 64K +# +NLM_STACK_SIZE = 8192 + + +# +# If this is specified it will be used by the link '-entry' directive +# +NLM_ENTRY_SYM = _LibCPrelude + +# +# If this is specified it will be used by the link '-exit' directive +# +NLM_EXIT_SYM = _LibCPostlude + +# +# If this is specified it will be used by the link '-check' directive +# +NLM_CHECK_SYM = + +# +# If these are specified it will be used by the link '-flags' directive +# +NLM_FLAGS = AUTOUNLOAD, PSEUDOPREEMPTION + +# +# If this is specified it will be linked in with the XDCData option in the def +# file instead of the default of $(NWOS)/apache.xdc. XDCData can be disabled +# by setting APACHE_UNIPROC in the environment +# +XDCDATA = + +# +# If there is an NLM target, put it here +# +TARGET_nlm = \ + $(OBJDIR)/expires.nlm \ + $(EOLIST) + +# +# If there is an LIB target, put it here +# +TARGET_lib = \ + $(EOLIST) + +# +# These are the OBJ files needed to create the NLM target above. +# Paths must all use the '/' character +# +FILES_nlm_objs = \ + $(OBJDIR)/mod_expires.o \ + $(EOLIST) + +# +# These are the LIB files needed to create the NLM target above. +# These will be added as a library command in the link.opt file. +# +FILES_nlm_libs = \ + libcpre.o \ + $(EOLIST) + +# +# These are the modules that the above NLM target depends on to load. +# These will be added as a module command in the link.opt file. +# +FILES_nlm_modules = \ + aprlib \ + libc \ + $(EOLIST) + +# +# If the nlm has a msg file, put it's path here +# +FILE_nlm_msg = + +# +# If the nlm has a hlp file put it's path here +# +FILE_nlm_hlp = + +# +# If this is specified, it will override $(NWOS)\copyright.txt. +# +FILE_nlm_copyright = + +# +# Any additional imports go here +# +FILES_nlm_Ximports = \ + @$(APR)/aprlib.imp \ + @$(NWOS)/httpd.imp \ + @libc.imp \ + $(EOLIST) + +# +# Any symbols exported to here +# +FILES_nlm_exports = \ + expires_module \ + $(EOLIST) + +# +# These are the OBJ files needed to create the LIB target above. +# Paths must all use the '/' character +# +FILES_lib_objs = \ + $(EOLIST) + +# +# implement targets and dependancies (leave this section alone) +# + +libs :: $(OBJDIR) $(TARGET_lib) + +nlms :: libs $(TARGET_nlm) + +# +# Updated this target to create necessary directories and copy files to the +# correct place. (See $(AP_WORK)\build\NWGNUhead.inc for examples) +# +install :: nlms FORCE + +# +# Any specialized rules here +# + +# +# Include the 'tail' makefile that has targets that depend on variables defined +# in this makefile +# + +include $(AP_WORK)\build\NWGNUtail.inc + diff --git a/modules/metadata/NWGNUheaders b/modules/metadata/NWGNUheaders new file mode 100644 index 0000000000..88be58ee34 --- /dev/null +++ b/modules/metadata/NWGNUheaders @@ -0,0 +1,250 @@ +# +# Make sure all needed macro's are defined +# + +# +# Get the 'head' of the build environment if necessary. This includes default +# targets and paths to tools +# + +ifndef EnvironmentDefined +include $(AP_WORK)\build\NWGNUhead.inc +endif + +# +# These directories will be at the beginning of the include list, followed by +# INCDIRS +# +XINCDIRS += \ + $(AP_WORK)/include \ + $(NWOS) \ + $(AP_WORK)/modules/arch/netware \ + $(AP_WORK)/srclib/apr/include \ + $(AP_WORK)/srclib/apr-util/include \ + $(AP_WORK)/srclib/apr \ + $(EOLIST) + +# +# These flags will come after CFLAGS +# +XCFLAGS += \ + -prefix pre_nw.h \ + $(EOLIST) + +# +# These defines will come after DEFINES +# +XDEFINES += \ + $(EOLIST) + +# +# These flags will be added to the link.opt file +# +XLFLAGS += \ + $(EOLIST) + +# +# These values will be appended to the correct variables based on the value of +# RELEASE +# +ifeq "$(RELEASE)" "debug" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "noopt" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "release" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +# +# These are used by the link target if an NLM is being generated +# This is used by the link 'name' directive to name the nlm. If left blank +# TARGET_nlm (see below) will be used. +# +NLM_NAME = headers + +# +# This is used by the link '-desc ' directive. +# If left blank, NLM_NAME will be used. +# +NLM_DESCRIPTION = Headers Module + +# +# This is used by the '-threadname' directive. If left blank, +# NLM_NAME Thread will be used. +# +NLM_THREAD_NAME = Headers Module + +# +# If this is specified, it will override VERSION value in +# $(AP_WORK)\build\NWGNUenvironment.inc +# +NLM_VERSION = + +# +# If this is specified, it will override the default of 64K +# +NLM_STACK_SIZE = 8192 + + +# +# If this is specified it will be used by the link '-entry' directive +# +NLM_ENTRY_SYM = _LibCPrelude + +# +# If this is specified it will be used by the link '-exit' directive +# +NLM_EXIT_SYM = _LibCPostlude + +# +# If this is specified it will be used by the link '-check' directive +# +NLM_CHECK_SYM = + +# +# If these are specified it will be used by the link '-flags' directive +# +NLM_FLAGS = AUTOUNLOAD, PSEUDOPREEMPTION + +# +# If this is specified it will be linked in with the XDCData option in the def +# file instead of the default of $(NWOS)/apache.xdc. XDCData can be disabled +# by setting APACHE_UNIPROC in the environment +# +XDCDATA = + +# +# If there is an NLM target, put it here +# +TARGET_nlm = \ + $(OBJDIR)/headers.nlm \ + $(EOLIST) + +# +# If there is an LIB target, put it here +# +TARGET_lib = \ + $(EOLIST) + +# +# These are the OBJ files needed to create the NLM target above. +# Paths must all use the '/' character +# +FILES_nlm_objs = \ + $(OBJDIR)/mod_headers.o \ + $(EOLIST) + +# +# These are the LIB files needed to create the NLM target above. +# These will be added as a library command in the link.opt file. +# +FILES_nlm_libs = \ + libcpre.o \ + $(EOLIST) + +# +# These are the modules that the above NLM target depends on to load. +# These will be added as a module command in the link.opt file. +# +FILES_nlm_modules = \ + aprlib \ + libc \ + $(EOLIST) + +# +# If the nlm has a msg file, put it's path here +# +FILE_nlm_msg = + +# +# If the nlm has a hlp file put it's path here +# +FILE_nlm_hlp = + +# +# If this is specified, it will override $(NWOS)\copyright.txt. +# +FILE_nlm_copyright = + +# +# Any additional imports go here +# +FILES_nlm_Ximports = \ + @$(APR)/aprlib.imp \ + @$(NWOS)/httpd.imp \ + @libc.imp \ + $(EOLIST) + +# +# Any symbols exported to here +# +FILES_nlm_exports = \ + headers_module \ + $(EOLIST) + +# +# These are the OBJ files needed to create the LIB target above. +# Paths must all use the '/' character +# +FILES_lib_objs = \ + $(EOLIST) + +# +# implement targets and dependancies (leave this section alone) +# + +libs :: $(OBJDIR) $(TARGET_lib) + +nlms :: libs $(TARGET_nlm) + +# +# Updated this target to create necessary directories and copy files to the +# correct place. (See $(AP_WORK)\build\NWGNUhead.inc for examples) +# +install :: nlms FORCE + +# +# Any specialized rules here +# + +# +# Include the 'tail' makefile that has targets that depend on variables defined +# in this makefile +# + +include $(AP_WORK)\build\NWGNUtail.inc + diff --git a/modules/metadata/NWGNUmakefile b/modules/metadata/NWGNUmakefile new file mode 100644 index 0000000000..c23e762a0f --- /dev/null +++ b/modules/metadata/NWGNUmakefile @@ -0,0 +1,251 @@ +# +# Declare the sub-directories to be built here +# + +SUBDIRS = \ + $(EOLIST) + +# +# Get the 'head' of the build environment. This includes default targets and +# paths to tools +# + +include $(AP_WORK)\build\NWGNUhead.inc + +# +# build this level's files + +# +# Make sure all needed macro's are defined +# + + +# +# These directories will be at the beginning of the include list, followed by +# INCDIRS +# +XINCDIRS += \ + $(EOLIST) + +# +# These flags will come after CFLAGS +# +XCFLAGS += \ + $(EOLIST) + +# +# These defines will come after DEFINES +# +XDEFINES += \ + $(EOLIST) + +# +# These flags will be added to the link.opt file +# +XLFLAGS += \ + $(EOLIST) + +# +# These values will be appended to the correct variables based on the value of +# RELEASE +# +ifeq "$(RELEASE)" "debug" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "noopt" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "release" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +# +# These are used by the link target if an NLM is being generated +# This is used by the link 'name' directive to name the nlm. If left blank +# TARGET_nlm (see below) will be used. +# +NLM_NAME = + +# +# This is used by the link '-desc ' directive. +# If left blank, NLM_NAME will be used. +# +NLM_DESCRIPTION = + +# +# This is used by the '-threadname' directive. If left blank, +# NLM_NAME Thread will be used. +# +NLM_THREAD_NAME = + +# +# If this is specified, it will override VERSION value in +# $(AP_WORK)\build\NWGNUenvironment.inc +# +NLM_VERSION = + +# +# If this is specified, it will override the default of 64K +# +NLM_STACK_SIZE = + + +# +# If this is specified it will be used by the link '-entry' directive +# +NLM_ENTRY_SYM = + +# +# If this is specified it will be used by the link '-exit' directive +# +NLM_EXIT_SYM = + +# +# If this is specified it will be used by the link '-check' directive +# +NLM_CHECK_SYM = + +# +# If these are specified it will be used by the link '-flags' directive +# +NLM_FLAGS = + +# +# If this is specified it will be linked in with the XDCData option in the def +# file instead of the default of $(NWOS)/apache.xdc. XDCData can be disabled +# by setting APACHE_UNIPROC in the environment +# +XDCDATA = + +# +# If there is an NLM target, put it here +# +TARGET_nlm = \ + $(OBJDIR)/cernmeta.nlm \ + $(OBJDIR)/expires.nlm \ + $(OBJDIR)/headers.nlm \ + $(OBJDIR)/mimemagi.nlm \ + $(OBJDIR)/uniqueid.nlm \ + $(OBJDIR)/usertrk.nlm \ + $(EOLIST) + +# +# If there is an LIB target, put it here +# +TARGET_lib = \ + $(EOLIST) + +# +# These are the OBJ files needed to create the NLM target above. +# Paths must all use the '/' character +# +FILES_nlm_objs = \ + $(EOLIST) + +# +# These are the LIB files needed to create the NLM target above. +# These will be added as a library command in the link.opt file. +# +FILES_nlm_libs = \ + $(EOLIST) + +# +# These are the modules that the above NLM target depends on to load. +# These will be added as a module command in the link.opt file. +# +FILES_nlm_modules = \ + $(EOLIST) + +# +# If the nlm has a msg file, put it's path here +# +FILE_nlm_msg = + +# +# If the nlm has a hlp file put it's path here +# +FILE_nlm_hlp = + +# +# If this is specified, it will override $(NWOS)\copyright.txt. +# +FILE_nlm_copyright = + +# +# Any additional imports go here +# +FILES_nlm_Ximports = \ + $(EOLIST) + +# +# Any symbols exported to here +# +FILES_nlm_exports = \ + $(EOLIST) + +# +# These are the OBJ files needed to create the LIB target above. +# Paths must all use the '/' character +# +FILES_lib_objs = \ + $(EOLIST) + +# +# implement targets and dependancies (leave this section alone) +# + +libs :: $(OBJDIR) $(TARGET_lib) + +nlms :: libs $(TARGET_nlm) + +# +# Updated this target to create necessary directories and copy files to the +# correct place. (See $(AP_WORK)\build\NWGNUhead.inc for examples) +# +install :: nlms FORCE + copy $(OBJDIR)\*.nlm $(INSTALL)\Apache2\modules\*.* + +# +# Any specialized rules here +# + +# +# Include the 'tail' makefile that has targets that depend on variables defined +# in this makefile +# + +include $(AP_WORK)\build\NWGNUtail.inc + + diff --git a/modules/metadata/NWGNUmimemagi b/modules/metadata/NWGNUmimemagi new file mode 100644 index 0000000000..8a989e323b --- /dev/null +++ b/modules/metadata/NWGNUmimemagi @@ -0,0 +1,250 @@ +# +# Make sure all needed macro's are defined +# + +# +# Get the 'head' of the build environment if necessary. This includes default +# targets and paths to tools +# + +ifndef EnvironmentDefined +include $(AP_WORK)\build\NWGNUhead.inc +endif + +# +# These directories will be at the beginning of the include list, followed by +# INCDIRS +# +XINCDIRS += \ + $(AP_WORK)/include \ + $(NWOS) \ + $(AP_WORK)/modules/arch/netware \ + $(AP_WORK)/srclib/apr/include \ + $(AP_WORK)/srclib/apr-util/include \ + $(AP_WORK)/srclib/apr \ + $(EOLIST) + +# +# These flags will come after CFLAGS +# +XCFLAGS += \ + -prefix pre_nw.h \ + $(EOLIST) + +# +# These defines will come after DEFINES +# +XDEFINES += \ + $(EOLIST) + +# +# These flags will be added to the link.opt file +# +XLFLAGS += \ + $(EOLIST) + +# +# These values will be appended to the correct variables based on the value of +# RELEASE +# +ifeq "$(RELEASE)" "debug" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "noopt" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "release" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +# +# These are used by the link target if an NLM is being generated +# This is used by the link 'name' directive to name the nlm. If left blank +# TARGET_nlm (see below) will be used. +# +NLM_NAME = mimemagi + +# +# This is used by the link '-desc ' directive. +# If left blank, NLM_NAME will be used. +# +NLM_DESCRIPTION = CERN Meta Module + +# +# This is used by the '-threadname' directive. If left blank, +# NLM_NAME Thread will be used. +# +NLM_THREAD_NAME = CERN Meta Module + +# +# If this is specified, it will override VERSION value in +# $(AP_WORK)\build\NWGNUenvironment.inc +# +NLM_VERSION = + +# +# If this is specified, it will override the default of 64K +# +NLM_STACK_SIZE = 8192 + + +# +# If this is specified it will be used by the link '-entry' directive +# +NLM_ENTRY_SYM = _LibCPrelude + +# +# If this is specified it will be used by the link '-exit' directive +# +NLM_EXIT_SYM = _LibCPostlude + +# +# If this is specified it will be used by the link '-check' directive +# +NLM_CHECK_SYM = + +# +# If these are specified it will be used by the link '-flags' directive +# +NLM_FLAGS = AUTOUNLOAD, PSEUDOPREEMPTION + +# +# If this is specified it will be linked in with the XDCData option in the def +# file instead of the default of $(NWOS)/apache.xdc. XDCData can be disabled +# by setting APACHE_UNIPROC in the environment +# +XDCDATA = + +# +# If there is an NLM target, put it here +# +TARGET_nlm = \ + $(OBJDIR)/mimemagi.nlm \ + $(EOLIST) + +# +# If there is an LIB target, put it here +# +TARGET_lib = \ + $(EOLIST) + +# +# These are the OBJ files needed to create the NLM target above. +# Paths must all use the '/' character +# +FILES_nlm_objs = \ + $(OBJDIR)/mod_mime_magic.o \ + $(EOLIST) + +# +# These are the LIB files needed to create the NLM target above. +# These will be added as a library command in the link.opt file. +# +FILES_nlm_libs = \ + libcpre.o \ + $(EOLIST) + +# +# These are the modules that the above NLM target depends on to load. +# These will be added as a module command in the link.opt file. +# +FILES_nlm_modules = \ + aprlib \ + libc \ + $(EOLIST) + +# +# If the nlm has a msg file, put it's path here +# +FILE_nlm_msg = + +# +# If the nlm has a hlp file put it's path here +# +FILE_nlm_hlp = + +# +# If this is specified, it will override $(NWOS)\copyright.txt. +# +FILE_nlm_copyright = + +# +# Any additional imports go here +# +FILES_nlm_Ximports = \ + @$(APR)/aprlib.imp \ + @$(NWOS)/httpd.imp \ + @libc.imp \ + $(EOLIST) + +# +# Any symbols exported to here +# +FILES_nlm_exports = \ + mime_magic_module \ + $(EOLIST) + +# +# These are the OBJ files needed to create the LIB target above. +# Paths must all use the '/' character +# +FILES_lib_objs = \ + $(EOLIST) + +# +# implement targets and dependancies (leave this section alone) +# + +libs :: $(OBJDIR) $(TARGET_lib) + +nlms :: libs $(TARGET_nlm) + +# +# Updated this target to create necessary directories and copy files to the +# correct place. (See $(AP_WORK)\build\NWGNUhead.inc for examples) +# +install :: nlms FORCE + +# +# Any specialized rules here +# + +# +# Include the 'tail' makefile that has targets that depend on variables defined +# in this makefile +# + +include $(AP_WORK)\build\NWGNUtail.inc + diff --git a/modules/metadata/NWGNUuniqueid b/modules/metadata/NWGNUuniqueid new file mode 100644 index 0000000000..c7dace40df --- /dev/null +++ b/modules/metadata/NWGNUuniqueid @@ -0,0 +1,256 @@ +# +# Make sure all needed macro's are defined +# + +# +# Get the 'head' of the build environment if necessary. This includes default +# targets and paths to tools +# + +ifndef EnvironmentDefined +include $(AP_WORK)\build\NWGNUhead.inc +endif + +# +# These directories will be at the beginning of the include list, followed by +# INCDIRS +# +XINCDIRS += \ + $(AP_WORK)/include \ + $(NWOS) \ + $(AP_WORK)/modules/arch/netware \ + $(AP_WORK)/srclib/apr/include \ + $(AP_WORK)/srclib/apr-util/include \ + $(AP_WORK)/srclib/apr \ + $(EOLIST) + +# +# These flags will come after CFLAGS +# +XCFLAGS += \ + -prefix pre_nw.h \ + $(EOLIST) + +# +# These defines will come after DEFINES +# +XDEFINES += \ + $(EOLIST) + +# +# These flags will be added to the link.opt file +# +XLFLAGS += \ + $(EOLIST) + +# +# These values will be appended to the correct variables based on the value of +# RELEASE +# +ifeq "$(RELEASE)" "debug" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "noopt" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "release" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +# +# These are used by the link target if an NLM is being generated +# This is used by the link 'name' directive to name the nlm. If left blank +# TARGET_nlm (see below) will be used. +# +NLM_NAME = uniqueid + +# +# This is used by the link '-desc ' directive. +# If left blank, NLM_NAME will be used. +# +NLM_DESCRIPTION = Unique ID Module + +# +# This is used by the '-threadname' directive. If left blank, +# NLM_NAME Thread will be used. +# +NLM_THREAD_NAME = Unique ID Module + +# +# If this is specified, it will override VERSION value in +# $(AP_WORK)\build\NWGNUenvironment.inc +# +NLM_VERSION = + +# +# If this is specified, it will override the default of 64K +# +NLM_STACK_SIZE = 8192 + + +# +# If this is specified it will be used by the link '-entry' directive +# +NLM_ENTRY_SYM = _LibCPrelude + +# +# If this is specified it will be used by the link '-exit' directive +# +NLM_EXIT_SYM = _LibCPostlude + +# +# If this is specified it will be used by the link '-check' directive +# +NLM_CHECK_SYM = + +# +# If these are specified it will be used by the link '-flags' directive +# +NLM_FLAGS = AUTOUNLOAD, PSEUDOPREEMPTION + +# +# If this is specified it will be linked in with the XDCData option in the def +# file instead of the default of $(NWOS)/apache.xdc. XDCData can be disabled +# by setting APACHE_UNIPROC in the environment +# +XDCDATA = + +# +# If there is an NLM target, put it here +# +TARGET_nlm = \ + $(OBJDIR)/uniqueid.nlm \ + $(EOLIST) + +# +# If there is an LIB target, put it here +# +TARGET_lib = \ + $(EOLIST) + +# +# These are the OBJ files needed to create the NLM target above. +# Paths must all use the '/' character +# +FILES_nlm_objs = \ + $(OBJDIR)/mod_unique_id.o \ + $(OBJDIR)/libprews.o \ + $(EOLIST) + +# +# These are the LIB files needed to create the NLM target above. +# These will be added as a library command in the link.opt file. +# +FILES_nlm_libs = \ + libcpre.o \ + $(EOLIST) + +# +# These are the modules that the above NLM target depends on to load. +# These will be added as a module command in the link.opt file. +# +FILES_nlm_modules = \ + aprlib \ + libc \ + $(EOLIST) + +# +# If the nlm has a msg file, put it's path here +# +FILE_nlm_msg = + +# +# If the nlm has a hlp file put it's path here +# +FILE_nlm_hlp = + +# +# If this is specified, it will override $(NWOS)\copyright.txt. +# +FILE_nlm_copyright = + +# +# Any additional imports go here +# +FILES_nlm_Ximports = \ + @$(APR)/aprlib.imp \ + @$(NWOS)/httpd.imp \ + @libc.imp \ + @ws2nlm.imp \ + $(EOLIST) + +# +# Any symbols exported to here +# +FILES_nlm_exports = \ + unique_id_module \ + $(EOLIST) + +# +# These are the OBJ files needed to create the LIB target above. +# Paths must all use the '/' character +# +FILES_lib_objs = \ + $(EOLIST) + +# +# implement targets and dependancies (leave this section alone) +# + +libs :: $(OBJDIR) $(TARGET_lib) + +nlms :: libs $(TARGET_nlm) + +# +# Updated this target to create necessary directories and copy files to the +# correct place. (See $(AP_WORK)\build\NWGNUhead.inc for examples) +# +install :: nlms FORCE + +# +# Any specialized rules here +# + +$(OBJDIR)/%.o: ../arch/netware/%.c $(OBJDIR)\cc.opt + @echo compiling $< + $(CC) $< -o=$(OBJDIR)\$(@F) @$(OBJDIR)\cc.opt + +# +# Include the 'tail' makefile that has targets that depend on variables defined +# in this makefile +# + +include $(AP_WORK)\build\NWGNUtail.inc + diff --git a/modules/metadata/NWGNUusertrk b/modules/metadata/NWGNUusertrk new file mode 100644 index 0000000000..44bcb48a8a --- /dev/null +++ b/modules/metadata/NWGNUusertrk @@ -0,0 +1,250 @@ +# +# Make sure all needed macro's are defined +# + +# +# Get the 'head' of the build environment if necessary. This includes default +# targets and paths to tools +# + +ifndef EnvironmentDefined +include $(AP_WORK)\build\NWGNUhead.inc +endif + +# +# These directories will be at the beginning of the include list, followed by +# INCDIRS +# +XINCDIRS += \ + $(AP_WORK)/include \ + $(NWOS) \ + $(AP_WORK)/modules/arch/netware \ + $(AP_WORK)/srclib/apr/include \ + $(AP_WORK)/srclib/apr-util/include \ + $(AP_WORK)/srclib/apr \ + $(EOLIST) + +# +# These flags will come after CFLAGS +# +XCFLAGS += \ + -prefix pre_nw.h \ + $(EOLIST) + +# +# These defines will come after DEFINES +# +XDEFINES += \ + $(EOLIST) + +# +# These flags will be added to the link.opt file +# +XLFLAGS += \ + $(EOLIST) + +# +# These values will be appended to the correct variables based on the value of +# RELEASE +# +ifeq "$(RELEASE)" "debug" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "noopt" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "release" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +# +# These are used by the link target if an NLM is being generated +# This is used by the link 'name' directive to name the nlm. If left blank +# TARGET_nlm (see below) will be used. +# +NLM_NAME = usertrk + +# +# This is used by the link '-desc ' directive. +# If left blank, NLM_NAME will be used. +# +NLM_DESCRIPTION = User Track Module + +# +# This is used by the '-threadname' directive. If left blank, +# NLM_NAME Thread will be used. +# +NLM_THREAD_NAME = User Track Module + +# +# If this is specified, it will override VERSION value in +# $(AP_WORK)\build\NWGNUenvironment.inc +# +NLM_VERSION = + +# +# If this is specified, it will override the default of 64K +# +NLM_STACK_SIZE = 8192 + + +# +# If this is specified it will be used by the link '-entry' directive +# +NLM_ENTRY_SYM = _LibCPrelude + +# +# If this is specified it will be used by the link '-exit' directive +# +NLM_EXIT_SYM = _LibCPostlude + +# +# If this is specified it will be used by the link '-check' directive +# +NLM_CHECK_SYM = + +# +# If these are specified it will be used by the link '-flags' directive +# +NLM_FLAGS = AUTOUNLOAD, PSEUDOPREEMPTION + +# +# If this is specified it will be linked in with the XDCData option in the def +# file instead of the default of $(NWOS)/apache.xdc. XDCData can be disabled +# by setting APACHE_UNIPROC in the environment +# +XDCDATA = + +# +# If there is an NLM target, put it here +# +TARGET_nlm = \ + $(OBJDIR)/usertrk.nlm \ + $(EOLIST) + +# +# If there is an LIB target, put it here +# +TARGET_lib = \ + $(EOLIST) + +# +# These are the OBJ files needed to create the NLM target above. +# Paths must all use the '/' character +# +FILES_nlm_objs = \ + $(OBJDIR)/mod_usertrack.o \ + $(EOLIST) + +# +# These are the LIB files needed to create the NLM target above. +# These will be added as a library command in the link.opt file. +# +FILES_nlm_libs = \ + libcpre.o \ + $(EOLIST) + +# +# These are the modules that the above NLM target depends on to load. +# These will be added as a module command in the link.opt file. +# +FILES_nlm_modules = \ + aprlib \ + libc \ + $(EOLIST) + +# +# If the nlm has a msg file, put it's path here +# +FILE_nlm_msg = + +# +# If the nlm has a hlp file put it's path here +# +FILE_nlm_hlp = + +# +# If this is specified, it will override $(NWOS)\copyright.txt. +# +FILE_nlm_copyright = + +# +# Any additional imports go here +# +FILES_nlm_Ximports = \ + @$(APR)/aprlib.imp \ + @$(NWOS)/httpd.imp \ + @libc.imp \ + $(EOLIST) + +# +# Any symbols exported to here +# +FILES_nlm_exports = \ + usertrack_module \ + $(EOLIST) + +# +# These are the OBJ files needed to create the LIB target above. +# Paths must all use the '/' character +# +FILES_lib_objs = \ + $(EOLIST) + +# +# implement targets and dependancies (leave this section alone) +# + +libs :: $(OBJDIR) $(TARGET_lib) + +nlms :: libs $(TARGET_nlm) + +# +# Updated this target to create necessary directories and copy files to the +# correct place. (See $(AP_WORK)\build\NWGNUhead.inc for examples) +# +install :: nlms FORCE + +# +# Any specialized rules here +# + +# +# Include the 'tail' makefile that has targets that depend on variables defined +# in this makefile +# + +include $(AP_WORK)\build\NWGNUtail.inc + diff --git a/modules/metadata/mod_env.dsp b/modules/metadata/mod_env.dsp new file mode 100644 index 0000000000..13a4123ec1 --- /dev/null +++ b/modules/metadata/mod_env.dsp @@ -0,0 +1,128 @@ +# Microsoft Developer Studio Project File - Name="mod_env" - Package Owner=<4> +# Microsoft Developer Studio Generated Build File, Format Version 6.00 +# ** DO NOT EDIT ** + +# TARGTYPE "Win32 (x86) Dynamic-Link Library" 0x0102 + +CFG=mod_env - Win32 Release +!MESSAGE This is not a valid makefile. To build this project using NMAKE, +!MESSAGE use the Export Makefile command and run +!MESSAGE +!MESSAGE NMAKE /f "mod_env.mak". +!MESSAGE +!MESSAGE You can specify a configuration when running NMAKE +!MESSAGE by defining the macro CFG on the command line. For example: +!MESSAGE +!MESSAGE NMAKE /f "mod_env.mak" CFG="mod_env - Win32 Release" +!MESSAGE +!MESSAGE Possible choices for configuration are: +!MESSAGE +!MESSAGE "mod_env - Win32 Release" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE "mod_env - Win32 Debug" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE + +# Begin Project +# PROP AllowPerConfigDependencies 0 +# PROP Scc_ProjName "" +# PROP Scc_LocalPath "" +CPP=cl.exe +MTL=midl.exe +RSC=rc.exe + +!IF "$(CFG)" == "mod_env - Win32 Release" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 0 +# PROP BASE Output_Dir "Release" +# PROP BASE Intermediate_Dir "Release" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 0 +# PROP Output_Dir "Release" +# PROP Intermediate_Dir "Release" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MD /W3 /O2 /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /FD /c +# ADD CPP /nologo /MD /W3 /O2 /I "../../include" /I "../../srclib/apr/include" /I "../../srclib/apr-util/include" /D "NDEBUG" /D "WIN32" /D "_WINDOWS" /Fd"Release\mod_env" /FD /c +# ADD BASE MTL /nologo /D "NDEBUG" /win32 +# ADD MTL /nologo /D "NDEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x409 /d "NDEBUG" +# ADD RSC /l 0x409 /d "NDEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib /nologo /subsystem:windows /dll /map /machine:I386 /out:"Release/mod_env.so" /base:@..\..\os\win32\BaseAddr.ref,mod_env +# ADD LINK32 kernel32.lib /nologo /subsystem:windows /dll /map /machine:I386 /out:"Release/mod_env.so" /base:@..\..\os\win32\BaseAddr.ref,mod_env + +!ELSEIF "$(CFG)" == "mod_env - Win32 Debug" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 1 +# PROP BASE Output_Dir "Debug" +# PROP BASE Intermediate_Dir "Debug" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 1 +# PROP Output_Dir "Debug" +# PROP Intermediate_Dir "Debug" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MDd /W3 /GX /Zi /Od /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /FD /c +# ADD CPP /nologo /MDd /W3 /GX /Zi /Od /I "../../include" /I "../../srclib/apr/include" /I "../../srclib/apr-util/include" /D "_DEBUG" /D "WIN32" /D "_WINDOWS" /Fd"Debug\mod_env" /FD /c +# ADD BASE MTL /nologo /D "_DEBUG" /win32 +# ADD MTL /nologo /D "_DEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x409 /d "_DEBUG" +# ADD RSC /l 0x409 /d "_DEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib /nologo /subsystem:windows /dll /incremental:no /map /debug /machine:I386 /out:"Debug/mod_env.so" /base:@..\..\os\win32\BaseAddr.ref,mod_env +# ADD LINK32 kernel32.lib /nologo /subsystem:windows /dll /incremental:no /map /debug /machine:I386 /out:"Debug/mod_env.so" /base:@..\..\os\win32\BaseAddr.ref,mod_env + +!ENDIF + +# Begin Target + +# Name "mod_env - Win32 Release" +# Name "mod_env - Win32 Debug" +# Begin Source File + +SOURCE=.\mod_env.c +# End Source File +# Begin Source File + +SOURCE=.\mod_env.rc +# End Source File +# Begin Source File + +SOURCE=..\..\build\win32\win32ver.awk + +!IF "$(CFG)" == "mod_env - Win32 Release" + +# PROP Ignore_Default_Tool 1 +# Begin Custom Build - Creating Version Resource +InputPath=..\..\build\win32\win32ver.awk + +".\mod_env.rc" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)" + awk -f ../../build/win32/win32ver.awk mod_env "env_module for Apache" ../../include/ap_release.h > .\mod_env.rc + +# End Custom Build + +!ELSEIF "$(CFG)" == "mod_env - Win32 Debug" + +# PROP Ignore_Default_Tool 1 +# Begin Custom Build - Creating Version Resource +InputPath=..\..\build\win32\win32ver.awk + +".\mod_env.rc" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)" + awk -f ../../build/win32/win32ver.awk mod_env "env_module for Apache" ../../include/ap_release.h > .\mod_env.rc + +# End Custom Build + +!ENDIF + +# End Source File +# End Target +# End Project diff --git a/modules/metadata/mod_setenvif.dsp b/modules/metadata/mod_setenvif.dsp new file mode 100644 index 0000000000..8779ec8ce8 --- /dev/null +++ b/modules/metadata/mod_setenvif.dsp @@ -0,0 +1,128 @@ +# Microsoft Developer Studio Project File - Name="mod_setenvif" - Package Owner=<4> +# Microsoft Developer Studio Generated Build File, Format Version 6.00 +# ** DO NOT EDIT ** + +# TARGTYPE "Win32 (x86) Dynamic-Link Library" 0x0102 + +CFG=mod_setenvif - Win32 Release +!MESSAGE This is not a valid makefile. To build this project using NMAKE, +!MESSAGE use the Export Makefile command and run +!MESSAGE +!MESSAGE NMAKE /f "mod_setenvif.mak". +!MESSAGE +!MESSAGE You can specify a configuration when running NMAKE +!MESSAGE by defining the macro CFG on the command line. For example: +!MESSAGE +!MESSAGE NMAKE /f "mod_setenvif.mak" CFG="mod_setenvif - Win32 Release" +!MESSAGE +!MESSAGE Possible choices for configuration are: +!MESSAGE +!MESSAGE "mod_setenvif - Win32 Release" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE "mod_setenvif - Win32 Debug" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE + +# Begin Project +# PROP AllowPerConfigDependencies 0 +# PROP Scc_ProjName "" +# PROP Scc_LocalPath "" +CPP=cl.exe +MTL=midl.exe +RSC=rc.exe + +!IF "$(CFG)" == "mod_setenvif - Win32 Release" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 0 +# PROP BASE Output_Dir "Release" +# PROP BASE Intermediate_Dir "Release" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 0 +# PROP Output_Dir "Release" +# PROP Intermediate_Dir "Release" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MD /W3 /O2 /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /FD /c +# ADD CPP /nologo /MD /W3 /O2 /I "../../include" /I "../../srclib/apr/include" /I "../../srclib/apr-util/include" /D "NDEBUG" /D "WIN32" /D "_WINDOWS" /Fd"Release\mod_setenvif" /FD /c +# ADD BASE MTL /nologo /D "NDEBUG" /win32 +# ADD MTL /nologo /D "NDEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x409 /d "NDEBUG" +# ADD RSC /l 0x409 /d "NDEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib /nologo /subsystem:windows /dll /map /machine:I386 /out:"Release/mod_setenvif.so" /base:@..\..\os\win32\BaseAddr.ref,mod_setenvif +# ADD LINK32 kernel32.lib /nologo /subsystem:windows /dll /map /machine:I386 /out:"Release/mod_setenvif.so" /base:@..\..\os\win32\BaseAddr.ref,mod_setenvif + +!ELSEIF "$(CFG)" == "mod_setenvif - Win32 Debug" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 1 +# PROP BASE Output_Dir "Debug" +# PROP BASE Intermediate_Dir "Debug" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 1 +# PROP Output_Dir "Debug" +# PROP Intermediate_Dir "Debug" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MDd /W3 /GX /Zi /Od /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /FD /c +# ADD CPP /nologo /MDd /W3 /GX /Zi /Od /I "../../include" /I "../../srclib/apr/include" /I "../../srclib/apr-util/include" /D "_DEBUG" /D "WIN32" /D "_WINDOWS" /Fd"Debug\mod_setenvif" /FD /c +# ADD BASE MTL /nologo /D "_DEBUG" /win32 +# ADD MTL /nologo /D "_DEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x409 /d "_DEBUG" +# ADD RSC /l 0x409 /d "_DEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib /nologo /subsystem:windows /dll /incremental:no /map /debug /machine:I386 /out:"Debug/mod_setenvif.so" /base:@..\..\os\win32\BaseAddr.ref,mod_setenvif +# ADD LINK32 kernel32.lib /nologo /subsystem:windows /dll /incremental:no /map /debug /machine:I386 /out:"Debug/mod_setenvif.so" /base:@..\..\os\win32\BaseAddr.ref,mod_setenvif + +!ENDIF + +# Begin Target + +# Name "mod_setenvif - Win32 Release" +# Name "mod_setenvif - Win32 Debug" +# Begin Source File + +SOURCE=.\mod_setenvif.c +# End Source File +# Begin Source File + +SOURCE=.\mod_setenvif.rc +# End Source File +# Begin Source File + +SOURCE=..\..\build\win32\win32ver.awk + +!IF "$(CFG)" == "mod_setenvif - Win32 Release" + +# PROP Ignore_Default_Tool 1 +# Begin Custom Build - Creating Version Resource +InputPath=..\..\build\win32\win32ver.awk + +".\mod_setenvif.rc" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)" + awk -f ../../build/win32/win32ver.awk mod_setenvif "setenvif_module for Apache" ../../include/ap_release.h > .\mod_setenvif.rc + +# End Custom Build + +!ELSEIF "$(CFG)" == "mod_setenvif - Win32 Debug" + +# PROP Ignore_Default_Tool 1 +# Begin Custom Build - Creating Version Resource +InputPath=..\..\build\win32\win32ver.awk + +".\mod_setenvif.rc" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)" + awk -f ../../build/win32/win32ver.awk mod_setenvif "setenvif_module for Apache" ../../include/ap_release.h > .\mod_setenvif.rc + +# End Custom Build + +!ENDIF + +# End Source File +# End Target +# End Project diff --git a/modules/proxy/NWGNUmakefile b/modules/proxy/NWGNUmakefile new file mode 100644 index 0000000000..b86fab5e67 --- /dev/null +++ b/modules/proxy/NWGNUmakefile @@ -0,0 +1,271 @@ +# +# Declare the sub-directories to be built here +# + +SUBDIRS = \ + $(EOLIST) + +# +# Get the 'head' of the build environment. This includes default targets and +# paths to tools +# + +include $(AP_WORK)\build\NWGNUhead.inc + +# +# build this level's files +# +# Make sure all needed macro's are defined +# + + +# +# These directories will be at the beginning of the include list, followed by +# INCDIRS +# +XINCDIRS += \ + $(AP_WORK)/include \ + $(NWOS) \ + $(AP_WORK)/modules/http \ + $(AP_WORK)/modules/arch/netware \ + $(AP_WORK)/srclib/apr/include \ + $(AP_WORK)/srclib/apr-util/include \ + $(AP_WORK)/srclib/apr \ + $(EOLIST) + +# +# These flags will come after CFLAGS +# +XCFLAGS += \ + -prefix pre_nw.h \ + $(EOLIST) + +# +# These defines will come after DEFINES +# +XDEFINES += \ + $(EOLIST) + +# +# These flags will be added to the link.opt file +# +XLFLAGS += \ + $(EOLIST) + +# +# These values will be appended to the correct variables based on the value of +# RELEASE +# +ifeq "$(RELEASE)" "debug" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "noopt" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "release" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +# +# These are used by the link target if an NLM is being generated +# This is used by the link 'name' directive to name the nlm. If left blank +# TARGET_nlm (see below) will be used. +# +NLM_NAME = proxy + +# +# This is used by the link '-desc ' directive. +# If left blank, NLM_NAME will be used. +# +NLM_DESCRIPTION = Proxy Module + +# +# This is used by the '-threadname' directive. If left blank, +# NLM_NAME Thread will be used. +# +NLM_THREAD_NAME = Proxy Module + +# +# If this is specified, it will override VERSION value in +# $(AP_WORK)\build\NWGNUenvironment.inc +# +NLM_VERSION = + +# +# If this is specified, it will override the default of 64K +# +NLM_STACK_SIZE = 8192 + + +# +# If this is specified it will be used by the link '-entry' directive +# +NLM_ENTRY_SYM = _LibCPrelude + +# +# If this is specified it will be used by the link '-exit' directive +# +NLM_EXIT_SYM = _LibCPostlude + +# +# If this is specified it will be used by the link '-check' directive +# +NLM_CHECK_SYM = + +# +# If these are specified it will be used by the link '-flags' directive +# +NLM_FLAGS = AUTOUNLOAD, PSEUDOPREEMPTION + +# +# If this is specified it will be linked in with the XDCData option in the def +# file instead of the default of $(NWOS)/apache.xdc. XDCData can be disabled +# by setting APACHE_UNIPROC in the environment +# +XDCDATA = + +# +# If there is an NLM target, put it here +# +TARGET_nlm = \ + $(OBJDIR)/proxy.nlm \ + $(EOLIST) + +# +# If there is an LIB target, put it here +# +TARGET_lib = \ + $(EOLIST) + +# +# These are the OBJ files needed to create the NLM target above. +# Paths must all use the '/' character +# +FILES_nlm_objs = \ + $(OBJDIR)/mod_proxy.o \ + $(OBJDIR)/proxy_connect.o \ + $(OBJDIR)/proxy_ftp.o \ + $(OBJDIR)/proxy_http.o \ + $(OBJDIR)/proxy_util.o \ + $(OBJDIR)/libprews.o \ + $(EOLIST) + +# +# These are the LIB files needed to create the NLM target above. +# These will be added as a library command in the link.opt file. +# +FILES_nlm_libs = \ + libcpre.o \ + $(EOLIST) + +# +# These are the modules that the above NLM target depends on to load. +# These will be added as a module command in the link.opt file. +# +FILES_nlm_modules = \ + aprlib \ + libc \ + $(EOLIST) + +# +# If the nlm has a msg file, put it's path here +# +FILE_nlm_msg = + +# +# If the nlm has a hlp file put it's path here +# +FILE_nlm_hlp = + +# +# If this is specified, it will override $(NWOS)\copyright.txt. +# +FILE_nlm_copyright = + +# +# Any additional imports go here +# +FILES_nlm_Ximports = \ + @$(APR)/aprlib.imp \ + @$(NWOS)/httpd.imp \ + @libc.imp \ + @ws2nlm.imp \ + $(EOLIST) + +# +# Any symbols exported to here +# +FILES_nlm_exports = \ + proxy_module \ + $(EOLIST) + +# +# These are the OBJ files needed to create the LIB target above. +# Paths must all use the '/' character +# +FILES_lib_objs = \ + $(EOLIST) + +# +# implement targets and dependancies (leave this section alone) +# + +libs :: $(OBJDIR) $(TARGET_lib) + +nlms :: libs $(TARGET_nlm) + +# +# Updated this target to create necessary directories and copy files to the +# correct place. (See $(AP_WORK)\build\NWGNUhead.inc for examples) +# +install :: nlms FORCE + copy $(OBJDIR)\*.nlm $(INSTALL)\Apache2\modules\*.* + +# +# Any specialized rules here +# + +$(OBJDIR)/%.o: ../arch/netware/%.c $(OBJDIR)\cc.opt + @echo compiling $< + $(CC) $< -o=$(OBJDIR)\$(@F) @$(OBJDIR)\cc.opt + +# +# Include the 'tail' makefile that has targets that depend on variables defined +# in this makefile +# + +include $(AP_WORK)\build\NWGNUtail.inc + + diff --git a/modules/proxy/mod_proxy_connect.dsp b/modules/proxy/mod_proxy_connect.dsp new file mode 100644 index 0000000000..c6b9d5f650 --- /dev/null +++ b/modules/proxy/mod_proxy_connect.dsp @@ -0,0 +1,136 @@ +# Microsoft Developer Studio Project File - Name="mod_proxy_connect" - Package Owner=<4> +# Microsoft Developer Studio Generated Build File, Format Version 6.00 +# ** DO NOT EDIT ** + +# TARGTYPE "Win32 (x86) Dynamic-Link Library" 0x0102 + +CFG=mod_proxy_connect - Win32 Release +!MESSAGE This is not a valid makefile. To build this project using NMAKE, +!MESSAGE use the Export Makefile command and run +!MESSAGE +!MESSAGE NMAKE /f "mod_proxy_connect.mak". +!MESSAGE +!MESSAGE You can specify a configuration when running NMAKE +!MESSAGE by defining the macro CFG on the command line. For example: +!MESSAGE +!MESSAGE NMAKE /f "mod_proxy_connect.mak" CFG="mod_proxy_connect - Win32 Release" +!MESSAGE +!MESSAGE Possible choices for configuration are: +!MESSAGE +!MESSAGE "mod_proxy_connect - Win32 Release" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE "mod_proxy_connect - Win32 Debug" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE + +# Begin Project +# PROP AllowPerConfigDependencies 0 +# PROP Scc_ProjName "" +# PROP Scc_LocalPath "" +CPP=cl.exe +MTL=midl.exe +RSC=rc.exe + +!IF "$(CFG)" == "mod_proxy_connect - Win32 Release" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 0 +# PROP BASE Output_Dir "Release" +# PROP BASE Intermediate_Dir "Release" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 0 +# PROP Output_Dir "Release" +# PROP Intermediate_Dir "Release" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MD /W3 /O2 /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /FD /c +# ADD CPP /nologo /MD /W3 /O2 /I "../../include" /I "../../srclib/apr/include" /I "../../srclib/apr-util/include" /D "NDEBUG" /D "WIN32" /D "_WINDOWS" /Fd"Release\mod_proxy_connect" /FD /c +# ADD BASE MTL /nologo /D "NDEBUG" /win32 +# ADD MTL /nologo /D "NDEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x809 /d "NDEBUG" +# ADD RSC /l 0x809 /d "NDEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib ws2_32.lib mswsock.lib /nologo /subsystem:windows /dll /map /machine:I386 /out:"Release/mod_proxy_connect.so" /base:@..\..\os\win32\BaseAddr.ref,mod_proxy_connect +# ADD LINK32 kernel32.lib ws2_32.lib mswsock.lib /nologo /subsystem:windows /dll /map /machine:I386 /out:"Release/mod_proxy_connect.so" /base:@..\..\os\win32\BaseAddr.ref,mod_proxy_connect + +!ELSEIF "$(CFG)" == "mod_proxy_connect - Win32 Debug" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 1 +# PROP BASE Output_Dir "Debug" +# PROP BASE Intermediate_Dir "Debug" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 1 +# PROP Output_Dir "Debug" +# PROP Intermediate_Dir "Debug" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MDd /W3 /GX /Zi /Od /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /FD /c +# ADD CPP /nologo /MDd /W3 /GX /Zi /Od /I "../../include" /I "../../srclib/apr/include" /I "../../srclib/apr-util/include" /D "_DEBUG" /D "WIN32" /D "_WINDOWS" /Fd"Debug\mod_proxy_connect" /FD /c +# ADD BASE MTL /nologo /D "_DEBUG" /win32 +# ADD MTL /nologo /D "_DEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x809 /d "_DEBUG" +# ADD RSC /l 0x809 /d "_DEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib ws2_32.lib mswsock.lib /nologo /subsystem:windows /dll /incremental:no /map /debug /machine:I386 /out:"Debug/mod_proxy_connect.so" /base:@..\..\os\win32\BaseAddr.ref,mod_proxy_connect +# ADD LINK32 kernel32.lib ws2_32.lib mswsock.lib /nologo /subsystem:windows /dll /incremental:no /map /debug /machine:I386 /out:"Debug/mod_proxy_connect.so" /base:@..\..\os\win32\BaseAddr.ref,mod_proxy_connect + +!ENDIF + +# Begin Target + +# Name "mod_proxy_connect - Win32 Release" +# Name "mod_proxy_connect - Win32 Debug" +# Begin Group "Source Files" + +# PROP Default_Filter "cpp;c;cxx;rc;def;r;odl;hpj;bat;for;f90" +# Begin Source File + +SOURCE=.\proxy_connect.c +# End Source File +# End Group +# Begin Group "Header Files" + +# PROP Default_Filter ".h" +# Begin Source File + +SOURCE=.\mod_proxy.h +# End Source File +# End Group +# Begin Source File + +SOURCE=..\..\build\win32\win32ver.awk + +!IF "$(CFG)" == "mod_proxy_connect - Win32 Release" + +# PROP Ignore_Default_Tool 1 +# Begin Custom Build - Creating Version Resource +InputPath=..\..\build\win32\win32ver.awk + +".\mod_proxy_connect.rc" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)" + awk -f ../../build/win32/win32ver.awk mod_proxy_connect "proxy_connect_module for Apache" ../../include/ap_release.h > .\mod_proxy_connect.rc + +# End Custom Build + +!ELSEIF "$(CFG)" == "mod_proxy_connect - Win32 Debug" + +# PROP Ignore_Default_Tool 1 +# Begin Custom Build - Creating Version Resource +InputPath=..\..\build\win32\win32ver.awk + +".\mod_proxy_connect.rc" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)" + awk -f ../../build/win32/win32ver.awk mod_proxy_connect "proxy_connect_module for Apache" ../../include/ap_release.h > .\mod_proxy_connect.rc + +# End Custom Build + +!ENDIF + +# End Source File +# End Target +# End Project diff --git a/modules/proxy/mod_proxy_ftp.dsp b/modules/proxy/mod_proxy_ftp.dsp new file mode 100644 index 0000000000..9a232fbb4d --- /dev/null +++ b/modules/proxy/mod_proxy_ftp.dsp @@ -0,0 +1,136 @@ +# Microsoft Developer Studio Project File - Name="mod_proxy_ftp" - Package Owner=<4> +# Microsoft Developer Studio Generated Build File, Format Version 6.00 +# ** DO NOT EDIT ** + +# TARGTYPE "Win32 (x86) Dynamic-Link Library" 0x0102 + +CFG=mod_proxy_ftp - Win32 Release +!MESSAGE This is not a valid makefile. To build this project using NMAKE, +!MESSAGE use the Export Makefile command and run +!MESSAGE +!MESSAGE NMAKE /f "mod_proxy_ftp.mak". +!MESSAGE +!MESSAGE You can specify a configuration when running NMAKE +!MESSAGE by defining the macro CFG on the command line. For example: +!MESSAGE +!MESSAGE NMAKE /f "mod_proxy_ftp.mak" CFG="mod_proxy_ftp - Win32 Release" +!MESSAGE +!MESSAGE Possible choices for configuration are: +!MESSAGE +!MESSAGE "mod_proxy_ftp - Win32 Release" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE "mod_proxy_ftp - Win32 Debug" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE + +# Begin Project +# PROP AllowPerConfigDependencies 0 +# PROP Scc_ProjName "" +# PROP Scc_LocalPath "" +CPP=cl.exe +MTL=midl.exe +RSC=rc.exe + +!IF "$(CFG)" == "mod_proxy_ftp - Win32 Release" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 0 +# PROP BASE Output_Dir "Release" +# PROP BASE Intermediate_Dir "Release" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 0 +# PROP Output_Dir "Release" +# PROP Intermediate_Dir "Release" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MD /W3 /O2 /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /FD /c +# ADD CPP /nologo /MD /W3 /O2 /I "../../include" /I "../../srclib/apr/include" /I "../../srclib/apr-util/include" /D "NDEBUG" /D "WIN32" /D "_WINDOWS" /Fd"Release\mod_proxy_ftp" /FD /c +# ADD BASE MTL /nologo /D "NDEBUG" /win32 +# ADD MTL /nologo /D "NDEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x809 /d "NDEBUG" +# ADD RSC /l 0x809 /d "NDEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib ws2_32.lib mswsock.lib /nologo /subsystem:windows /dll /map /machine:I386 /out:"Release/mod_proxy_ftp.so" /base:@..\..\os\win32\BaseAddr.ref,mod_proxy_ftp +# ADD LINK32 kernel32.lib ws2_32.lib mswsock.lib /nologo /subsystem:windows /dll /map /machine:I386 /out:"Release/mod_proxy_ftp.so" /base:@..\..\os\win32\BaseAddr.ref,mod_proxy_ftp + +!ELSEIF "$(CFG)" == "mod_proxy_ftp - Win32 Debug" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 1 +# PROP BASE Output_Dir "Debug" +# PROP BASE Intermediate_Dir "Debug" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 1 +# PROP Output_Dir "Debug" +# PROP Intermediate_Dir "Debug" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MDd /W3 /GX /Zi /Od /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /FD /c +# ADD CPP /nologo /MDd /W3 /GX /Zi /Od /I "../../include" /I "../../srclib/apr/include" /I "../../srclib/apr-util/include" /D "_DEBUG" /D "WIN32" /D "_WINDOWS" /Fd"Debug\mod_proxy_ftp" /FD /c +# ADD BASE MTL /nologo /D "_DEBUG" /win32 +# ADD MTL /nologo /D "_DEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x809 /d "_DEBUG" +# ADD RSC /l 0x809 /d "_DEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib ws2_32.lib mswsock.lib /nologo /subsystem:windows /dll /incremental:no /map /debug /machine:I386 /out:"Debug/mod_proxy_ftp.so" /base:@..\..\os\win32\BaseAddr.ref,mod_proxy_ftp +# ADD LINK32 kernel32.lib ws2_32.lib mswsock.lib /nologo /subsystem:windows /dll /incremental:no /map /debug /machine:I386 /out:"Debug/mod_proxy_ftp.so" /base:@..\..\os\win32\BaseAddr.ref,mod_proxy_ftp + +!ENDIF + +# Begin Target + +# Name "mod_proxy_ftp - Win32 Release" +# Name "mod_proxy_ftp - Win32 Debug" +# Begin Group "Source Files" + +# PROP Default_Filter "cpp;c;cxx;rc;def;r;odl;hpj;bat;for;f90" +# Begin Source File + +SOURCE=.\proxy_ftp.c +# End Source File +# End Group +# Begin Group "Header Files" + +# PROP Default_Filter ".h" +# Begin Source File + +SOURCE=.\mod_proxy.h +# End Source File +# End Group +# Begin Source File + +SOURCE=..\..\build\win32\win32ver.awk + +!IF "$(CFG)" == "mod_proxy_ftp - Win32 Release" + +# PROP Ignore_Default_Tool 1 +# Begin Custom Build - Creating Version Resource +InputPath=..\..\build\win32\win32ver.awk + +".\mod_proxy_ftp.rc" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)" + awk -f ../../build/win32/win32ver.awk mod_proxy_ftp "proxy_ftp_module for Apache" ../../include/ap_release.h > .\mod_proxy_ftp.rc + +# End Custom Build + +!ELSEIF "$(CFG)" == "mod_proxy_ftp - Win32 Debug" + +# PROP Ignore_Default_Tool 1 +# Begin Custom Build - Creating Version Resource +InputPath=..\..\build\win32\win32ver.awk + +".\mod_proxy_ftp.rc" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)" + awk -f ../../build/win32/win32ver.awk mod_proxy_ftp "proxy_ftp_module for Apache" ../../include/ap_release.h > .\mod_proxy_ftp.rc + +# End Custom Build + +!ENDIF + +# End Source File +# End Target +# End Project diff --git a/modules/proxy/mod_proxy_http.dsp b/modules/proxy/mod_proxy_http.dsp new file mode 100644 index 0000000000..8764b548ee --- /dev/null +++ b/modules/proxy/mod_proxy_http.dsp @@ -0,0 +1,136 @@ +# Microsoft Developer Studio Project File - Name="mod_proxy_http" - Package Owner=<4> +# Microsoft Developer Studio Generated Build File, Format Version 6.00 +# ** DO NOT EDIT ** + +# TARGTYPE "Win32 (x86) Dynamic-Link Library" 0x0102 + +CFG=mod_proxy_http - Win32 Release +!MESSAGE This is not a valid makefile. To build this project using NMAKE, +!MESSAGE use the Export Makefile command and run +!MESSAGE +!MESSAGE NMAKE /f "mod_proxy_http.mak". +!MESSAGE +!MESSAGE You can specify a configuration when running NMAKE +!MESSAGE by defining the macro CFG on the command line. For example: +!MESSAGE +!MESSAGE NMAKE /f "mod_proxy_http.mak" CFG="mod_proxy_http - Win32 Release" +!MESSAGE +!MESSAGE Possible choices for configuration are: +!MESSAGE +!MESSAGE "mod_proxy_http - Win32 Release" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE "mod_proxy_http - Win32 Debug" (based on "Win32 (x86) Dynamic-Link Library") +!MESSAGE + +# Begin Project +# PROP AllowPerConfigDependencies 0 +# PROP Scc_ProjName "" +# PROP Scc_LocalPath "" +CPP=cl.exe +MTL=midl.exe +RSC=rc.exe + +!IF "$(CFG)" == "mod_proxy_http - Win32 Release" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 0 +# PROP BASE Output_Dir "Release" +# PROP BASE Intermediate_Dir "Release" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 0 +# PROP Output_Dir "Release" +# PROP Intermediate_Dir "Release" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MD /W3 /O2 /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /FD /c +# ADD CPP /nologo /MD /W3 /O2 /I "../../include" /I "../../srclib/apr/include" /I "../../srclib/apr-util/include" /D "NDEBUG" /D "WIN32" /D "_WINDOWS" /Fd"Release\mod_proxy_http" /FD /c +# ADD BASE MTL /nologo /D "NDEBUG" /win32 +# ADD MTL /nologo /D "NDEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x809 /d "NDEBUG" +# ADD RSC /l 0x809 /d "NDEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib ws2_32.lib mswsock.lib /nologo /subsystem:windows /dll /map /machine:I386 /out:"Release/mod_proxy_http.so" /base:@..\..\os\win32\BaseAddr.ref,mod_proxy_http +# ADD LINK32 kernel32.lib ws2_32.lib mswsock.lib /nologo /subsystem:windows /dll /map /machine:I386 /out:"Release/mod_proxy_http.so" /base:@..\..\os\win32\BaseAddr.ref,mod_proxy_http + +!ELSEIF "$(CFG)" == "mod_proxy_http - Win32 Debug" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 1 +# PROP BASE Output_Dir "Debug" +# PROP BASE Intermediate_Dir "Debug" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 1 +# PROP Output_Dir "Debug" +# PROP Intermediate_Dir "Debug" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MDd /W3 /GX /Zi /Od /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /FD /c +# ADD CPP /nologo /MDd /W3 /GX /Zi /Od /I "../../include" /I "../../srclib/apr/include" /I "../../srclib/apr-util/include" /D "_DEBUG" /D "WIN32" /D "_WINDOWS" /Fd"Debug\mod_proxy_http" /FD /c +# ADD BASE MTL /nologo /D "_DEBUG" /win32 +# ADD MTL /nologo /D "_DEBUG" /mktyplib203 /win32 +# ADD BASE RSC /l 0x809 /d "_DEBUG" +# ADD RSC /l 0x809 /d "_DEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib ws2_32.lib mswsock.lib /nologo /subsystem:windows /dll /incremental:no /map /debug /machine:I386 /out:"Debug/mod_proxy_http.so" /base:@..\..\os\win32\BaseAddr.ref,mod_proxy_http +# ADD LINK32 kernel32.lib ws2_32.lib mswsock.lib /nologo /subsystem:windows /dll /incremental:no /map /debug /machine:I386 /out:"Debug/mod_proxy_http.so" /base:@..\..\os\win32\BaseAddr.ref,mod_proxy_http + +!ENDIF + +# Begin Target + +# Name "mod_proxy_http - Win32 Release" +# Name "mod_proxy_http - Win32 Debug" +# Begin Group "Source Files" + +# PROP Default_Filter "cpp;c;cxx;rc;def;r;odl;hpj;bat;for;f90" +# Begin Source File + +SOURCE=.\proxy_http.c +# End Source File +# End Group +# Begin Group "Header Files" + +# PROP Default_Filter ".h" +# Begin Source File + +SOURCE=.\mod_proxy.h +# End Source File +# End Group +# Begin Source File + +SOURCE=..\..\build\win32\win32ver.awk + +!IF "$(CFG)" == "mod_proxy_http - Win32 Release" + +# PROP Ignore_Default_Tool 1 +# Begin Custom Build - Creating Version Resource +InputPath=..\..\build\win32\win32ver.awk + +".\mod_proxy_http.rc" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)" + awk -f ../../build/win32/win32ver.awk mod_proxy_http "proxy_http_module for Apache" ../../include/ap_release.h > .\mod_proxy_http.rc + +# End Custom Build + +!ELSEIF "$(CFG)" == "mod_proxy_http - Win32 Debug" + +# PROP Ignore_Default_Tool 1 +# Begin Custom Build - Creating Version Resource +InputPath=..\..\build\win32\win32ver.awk + +".\mod_proxy_http.rc" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)" + awk -f ../../build/win32/win32ver.awk mod_proxy_http "proxy_http_module for Apache" ../../include/ap_release.h > .\mod_proxy_http.rc + +# End Custom Build + +!ENDIF + +# End Source File +# End Target +# End Project diff --git a/modules/test/mod_bucketeer.c b/modules/test/mod_bucketeer.c new file mode 100644 index 0000000000..b77c86a2f6 --- /dev/null +++ b/modules/test/mod_bucketeer.c @@ -0,0 +1,224 @@ +/* ==================================================================== + * The Apache Software License, Version 1.1 + * + * Copyright (c) 2000-2001 The Apache Software Foundation. All rights + * reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * 3. The end-user documentation included with the redistribution, + * if any, must include the following acknowledgment: + * "This product includes software developed by the + * Apache Software Foundation (http://www.apache.org/)." + * Alternately, this acknowledgment may appear in the software itself, + * if and wherever such third-party acknowledgments normally appear. + * + * 4. The names "Apache" and "Apache Software Foundation" must + * not be used to endorse or promote products derived from this + * software without prior written permission. For written + * permission, please contact apache@apache.org. + * + * 5. Products derived from this software may not be called "Apache", + * nor may "Apache" appear in their name, without prior written + * permission of the Apache Software Foundation. + * + * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED + * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR + * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF + * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND + * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, + * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT + * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + * SUCH DAMAGE. + * ==================================================================== + * + * This software consists of voluntary contributions made by many + * individuals on behalf of the Apache Software Foundation. For more + * information on the Apache Software Foundation, please see + * <http://www.apache.org/>. + * + * Portions of this software are based upon public domain software + * (zlib functions gz_open and gzwrite) + */ + +/* + * mod_bucketeer.c: split buckets whenever we find a control-char + * + * Written by Ian Holsman (IanH@apache.org) + * + */ + +#include "httpd.h" +#include "http_config.h" +#include "http_log.h" +#include "apr_strings.h" +#include "apr_general.h" +#include "util_filter.h" +#include "apr_buckets.h" +#include "http_request.h" + + +static const char bucketeerFilterName[] = "BUCKETEER"; +module AP_MODULE_DECLARE_DATA bucketeer_module; + +typedef struct bucketeer_filter_config_t +{ + char bucketdelimter; + char flushdelimiter; + +} bucketeer_filter_config_t; + + +static void *create_bucketeer_server_config(apr_pool_t *p, server_rec *s) +{ + bucketeer_filter_config_t *c = apr_pcalloc(p, sizeof *c); + + c->bucketdelimter = 0x02; /* ^B */ + c->flushdelimiter = 0x06; /* ^F */ + + return c; +} + + +typedef struct bucketeer_ctx_t +{ + apr_bucket_brigade *bb; +} bucketeer_ctx_t; + +static apr_status_t bucketeer_out_filter(ap_filter_t *f, + apr_bucket_brigade *bb) +{ + apr_bucket *e; + request_rec *r = f->r; + bucketeer_ctx_t *ctx = f->ctx; + + bucketeer_filter_config_t *c = ap_get_module_config(r->server->module_config, + &bucketeer_module); + + /* If we don't have a context, we need to ensure that it is okay to send + * the deflated content. If we have a context, that means we've done + * this before and we liked it. + * This could be not so nice if we always fail. But, if we succeed, + * we're in better shape. + */ + if (!ctx) { + if (strncmp(r->content_type, "text/", 5)) { + ap_remove_output_filter(f); + return ap_pass_brigade(f->next, bb); + } + + /* We're cool with filtering this. */ + ctx = f->ctx = apr_pcalloc(f->r->pool, sizeof(*ctx)); + ctx->bb = apr_brigade_create(f->r->pool); + } + + APR_BRIGADE_FOREACH(e, bb) { + const char *data; + apr_size_t len; + + int done = 0; + apr_size_t i; + apr_size_t lastpos; + + if (APR_BUCKET_IS_EOS(e)) { + + APR_BUCKET_REMOVE(e); + APR_BRIGADE_INSERT_TAIL(ctx->bb, e); + + /* Okay, we've seen the EOS. + * Time to pass it along down the chain. + */ + return ap_pass_brigade(f->next, ctx->bb); + } + + if (APR_BUCKET_IS_FLUSH(e)) { + /* + * Ignore flush buckets for the moment.. + * we decide what to stream + */ + continue; + } + + /* read */ + apr_bucket_read(e, &data, &len, APR_BLOCK_READ); + if (len>0) { + lastpos=0; + for (i=0; i<len;i++) { + if ( data[i] == c->flushdelimiter ) { + apr_bucket *p; + if ( i-lastpos>0) { + p = apr_bucket_pool_create(apr_pmemdup( f->r->pool, + &data[lastpos], + i-lastpos), + i-lastpos, + f->r->pool); + APR_BRIGADE_INSERT_TAIL(ctx->bb,p); + } + lastpos=i+1; + + p = apr_bucket_flush_create(); + APR_BRIGADE_INSERT_TAIL(ctx->bb,p); + + } + else { + if (data[i] == c->bucketdelimter) { + apr_bucket *p; + if ( i-lastpos>0) { + p = apr_bucket_pool_create(apr_pmemdup( f->r->pool, + &data[lastpos], + i-lastpos), + i-lastpos, + f->r->pool); + + APR_BRIGADE_INSERT_TAIL(ctx->bb,p); + } + lastpos=i+1; + } + } + } + /* XXX: really should append this to the next 'real' bucket */ + if ( lastpos < i ) { + apr_bucket *p; + p = apr_bucket_pool_create(apr_pmemdup( f->r->pool,&data[lastpos],i-lastpos),i-lastpos,f->r->pool); + lastpos=i; + APR_BRIGADE_INSERT_TAIL(ctx->bb,p); + } + } + } + + return APR_SUCCESS; +} + +static void register_hooks(apr_pool_t * p) +{ + ap_register_output_filter(bucketeerFilterName, bucketeer_out_filter, + AP_FTYPE_CONTENT-1); +} + +static const command_rec bucketeer_filter_cmds[] = { + {NULL} +}; + +module AP_MODULE_DECLARE_DATA bucketeer_module = { + STANDARD20_MODULE_STUFF, + NULL, + NULL, + create_bucketeer_server_config, + NULL, + bucketeer_filter_cmds, + register_hooks +}; diff --git a/os/netware/Apache.def b/os/netware/Apache.def new file mode 100644 index 0000000000..ef051ebf23 --- /dev/null +++ b/os/netware/Apache.def @@ -0,0 +1,4 @@ +#MODULE APRLIB.NLM +MODULE LIBC.NLM +MODULE WS2_32.NLM +FLAG_ON 3 diff --git a/os/netware/apache.xdc b/os/netware/apache.xdc Binary files differnew file mode 100644 index 0000000000..12a7f6ba2d --- /dev/null +++ b/os/netware/apache.xdc diff --git a/os/netware/modules.c b/os/netware/modules.c new file mode 100644 index 0000000000..3868521c85 --- /dev/null +++ b/os/netware/modules.c @@ -0,0 +1,77 @@ +/* modules.c --- major modules compiled into Apache for NetWare. + * Only insert an entry for a module if it must be compiled into + * the core server + */ + +#define CORE_PRIVATE +#include "httpd.h" +#include "http_config.h" + +extern module core_module; +extern module mpm_netware_module; +extern module http_module; +extern module so_module; +extern module mime_module; +extern module access_module; +extern module auth_module; +extern module negotiation_module; +extern module include_module; +extern module autoindex_module; +extern module dir_module; +extern module cgi_module; +extern module userdir_module; +extern module alias_module; +extern module env_module; +extern module log_config_module; +extern module asis_module; +extern module imap_module; +extern module actions_module; +extern module setenvif_module; + +module *ap_prelinked_modules[] = { + &core_module, + &mpm_netware_module, + &http_module, + &so_module, + &mime_module, + &access_module, + &auth_module, + &negotiation_module, + &include_module, + &autoindex_module, + &dir_module, + &cgi_module, + &userdir_module, + &alias_module, + &env_module, + &log_config_module, + &asis_module, + &imap_module, + &actions_module, + &setenvif_module, + NULL +}; + +module *ap_preloaded_modules[] = { + &core_module, + &mpm_netware_module, + &http_module, + &so_module, + &mime_module, + &access_module, + &auth_module, + &negotiation_module, + &include_module, + &autoindex_module, + &dir_module, + &cgi_module, + &userdir_module, + &alias_module, + &env_module, + &log_config_module, + &asis_module, + &imap_module, + &actions_module, + &setenvif_module, + NULL +}; diff --git a/os/netware/os.h b/os/netware/os.h new file mode 100644 index 0000000000..df9e1feabe --- /dev/null +++ b/os/netware/os.h @@ -0,0 +1,74 @@ +/* ==================================================================== + * The Apache Software License, Version 1.1 + * + * Copyright (c) 2000-2001 The Apache Software Foundation. All rights + * reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * 3. The end-user documentation included with the redistribution, + * if any, must include the following acknowledgment: + * "This product includes software developed by the + * Apache Software Foundation (http://www.apache.org/)." + * Alternately, this acknowledgment may appear in the software itself, + * if and wherever such third-party acknowledgments normally appear. + * + * 4. The names "Apache" and "Apache Software Foundation" must + * not be used to endorse or promote products derived from this + * software without prior written permission. For written + * permission, please contact apache@apache.org. + * + * 5. Products derived from this software may not be called "Apache", + * nor may "Apache" appear in their name, without prior written + * permission of the Apache Software Foundation. + * + * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED + * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR + * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF + * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND + * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, + * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT + * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + * SUCH DAMAGE. + * ==================================================================== + * + * This software consists of voluntary contributions made by many + * individuals on behalf of the Apache Software Foundation. For more + * information on the Apache Software Foundation, please see + * <http://www.apache.org/>. + * + * Portions of this software are based upon public domain software + * originally written at the National Center for Supercomputing Applications, + * University of Illinois, Urbana-Champaign. + */ + +#ifndef APACHE_OS_H +#define APACHE_OS_H + +#ifndef PLATFORM +#define PLATFORM "NETWARE" +#endif + +#define CASE_BLIND_FILESYSTEM +#define NO_WRITEV + +#define APACHE_MPM_DIR "server/mpm/netware" /* generated on unix */ + +#define getpid NXThreadGetId +//#define exit(s) _exit(s) + +#endif /* ! APACHE_OS_H */ diff --git a/os/netware/pre_nw.h b/os/netware/pre_nw.h new file mode 100644 index 0000000000..6a3d99c45d --- /dev/null +++ b/os/netware/pre_nw.h @@ -0,0 +1,43 @@ +#ifndef __pre_nw__ +#define __pre_nw__ + +#pragma precompile_target "precomp.mch" +#define NETWARE + + +#define N_PLAT_NLM + +/* hint for MSL C++ that we're on NetWare platform */ +#define __NETWARE__ + +/* the FAR keyword has no meaning in a 32-bit environment + but is used in the SDK headers so we take it out */ +#define FAR +#define far + +/* no-op for Codewarrior C compiler; a functions are cdecl + by default */ +#define cdecl + +/* if we have wchar_t enabled in C++, predefine this type to avoid + a conflict in Novell's header files */ +#if (__option(cplusplus) && __option(wchar_type)) +#define _WCHAR_T +#endif + +/* C9X defintion used by MSL C++ library */ +#define DECIMAL_DIG 17 + +/* define long long typedefs for Watcom compatiblity */ +typedef long long int64_t; +typedef unsigned long long uint64_t; + +/* some code may want to use the MS convention for long long */ +#ifndef __int64 +#define __int64 long long +#endif + +#endif + + + diff --git a/os/netware/util_nw.c b/os/netware/util_nw.c new file mode 100644 index 0000000000..77219815be --- /dev/null +++ b/os/netware/util_nw.c @@ -0,0 +1,76 @@ +/* ==================================================================== + * The Apache Software License, Version 1.1 + * + * Copyright (c) 2000-2001 The Apache Software Foundation. All rights + * reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * 3. The end-user documentation included with the redistribution, + * if any, must include the following acknowledgment: + * "This product includes software developed by the + * Apache Software Foundation (http://www.apache.org/)." + * Alternately, this acknowledgment may appear in the software itself, + * if and wherever such third-party acknowledgments normally appear. + * + * 4. The names "Apache" and "Apache Software Foundation" must + * not be used to endorse or promote products derived from this + * software without prior written permission. For written + * permission, please contact apache@apache.org. + * + * 5. Products derived from this software may not be called "Apache", + * nor may "Apache" appear in their name, without prior written + * permission of the Apache Software Foundation. + * + * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED + * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR + * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF + * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND + * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, + * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT + * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + * SUCH DAMAGE. + * ==================================================================== + * + * This software consists of voluntary contributions made by many + * individuals on behalf of the Apache Software Foundation. For more + * information on the Apache Software Foundation, please see + * <http://www.apache.org/>. + * + * Portions of this software are based upon public domain software + * originally written at the National Center for Supercomputing Applications, + * University of Illinois, Urbana-Champaign. + */ + +#include "httpd.h" +#include "http_log.h" +#include "apr_strings.h" + +#include <stdarg.h> +#include <time.h> +#include <stdlib.h> + + +AP_DECLARE(apr_status_t) ap_os_create_privileged_process( + const request_rec *r, + apr_proc_t *newproc, const char *progname, + const char * const *args, + const char * const *env, + apr_procattr_t *attr, apr_pool_t *p) +{ + return APR_ENOTIMPL; +} diff --git a/server/NWGNUmakefile b/server/NWGNUmakefile new file mode 100644 index 0000000000..7dabc8ec67 --- /dev/null +++ b/server/NWGNUmakefile @@ -0,0 +1,250 @@ +# +# Declare the sub-directories to be built here +# + +SUBDIRS = \ + $(EOLIST) + +# +# Get the 'head' of the build environment. This includes default targets and +# paths to tools +# + +include $(AP_WORK)\build\NWGNUhead.inc + +# +# build this level's files + +# +# These directories will be at the beginning of the include list, followed by +# INCDIRS +# +XINCDIRS += \ + $(NWOS) \ + $(APR)/include \ + $(AP_WORK)/include \ + $(APRUTIL)/include \ + $(EOLIST) + +# +# These flags will come after CFLAGS +# +XCFLAGS += \ + $(EOLIST) + +# +# These defines will come after DEFINES +# +XDEFINES += \ + $(EOLIST) + +# +# These flags will be added to the link.opt file +# +XLFLAGS += \ + $(EOLIST) + +# +# These values will be appended to the correct variables based on the value of +# RELEASE +# +ifeq "$(RELEASE)" "debug" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "noopt" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "release" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +# +# These are used by the link target if an NLM is being generated +# This is used by the link 'name' directive to name the nlm. If left blank +# TARGET_nlm (see below) will be used. +# +NLM_NAME = genchars + +# +# This is used by the link '-desc ' directive. +# If left blank, NLM_NAME will be used. +# +NLM_DESCRIPTION = Generate Test Characters + +# +# This is used by the '-threadname' directive. If left blank, +# NLM_NAME Thread will be used. +# +NLM_THREAD_NAME = genchars + +# +# If this is specified, it will override VERSION value in +# $(AP_WORK)\NWGNUNetWare.rul +# +NLM_VERSION = 1,0,0 + +# +# If this is specified, it will override the default of 64K +# +NLM_STACK_SIZE = 8192 + +# +# If this is specified it will be used by the link '-entry' directive +# +NLM_ENTRY_SYM =_LibCPrelude + +# +# If this is specified it will be used by the link '-exit' directive +# +NLM_EXIT_SYM =_LibCPostlude + +# +# If this is specified it will be used by the link '-check' directive +# +NLM_CHECK_SYM = + +# +# If this is specified it will be used by the link '-flags' directive +# +NLM_FLAGS = PSEUDOPREEMPTION + +# +# If this is specified it will be linked in with the XDCData option in the def +# file instead of the default of $(NWOS)/apache.xdc. XDCData can be disabled +# by setting APACHE_UNIPROC in the environment +# +XDCDATA = + +# +# Declare all target files (you must add your files here) +# + +# +# If there is an NLM target, put it here +# +TARGET_nlm = \ +$(OBJDIR)/genchars.nlm \ + $(EOLIST) + +# +# If there is an LIB target, put it here +# +TARGET_lib = \ + $(EOLIST) + +# +# These are the OBJ files needed to create the NLM target above. +# Paths must all use the '/' character +# +FILES_nlm_objs = \ + $(OBJDIR)/gen_test_char.o \ + $(EOLIST) + +# +# These are the LIB files needed to create the NLM target above. +# These will be added as a library command in the link.opt file. +# +FILES_nlm_libs = \ + libcpre.o \ + $(EOLIST) + +# +# These are the modules that the above NLM target depends on to load. +# These will be added as a module command in the link.opt file. +# +FILES_nlm_modules = \ + Libc \ + $(EOLIST) + +# +# If the nlm has a msg file, put it's path here +# +FILE_nlm_msg = + +# +# If the nlm has a hlp file put it's path here +# +FILE_nlm_hlp = + +# +# If this is specified, it will override $(NWOS)\copyright.txt. +# +FILE_nlm_copyright = + +# +# Any additional imports go here +# +FILES_nlm_Ximports = \ + @libc.imp \ + $(EOLIST) + +# +# Any symbols exported to here +# +FILES_nlm_exports = \ + $(EOLIST) + +# +# These are the OBJ files needed to create the LIB target above. +# Paths must all use the '/' character +# +FILES_lib_objs = \ + $(EOLIST) + +# +# implement targets and dependancies (leave this section alone) +# + +libs :: $(OBJDIR) $(TARGET_lib) + +nlms :: libs $(TARGET_nlm) + +# +# Updated this target to create necessary directories and copy files to the +# correct place. +# +install :: nlms FORCE + +# +# Any specialized rules here +# + +# +# Include the 'tail' makefile that has targets that depend on variables defined +# in this makefile +# + +include $(AP_WORK)\build\NWGNUtail.inc + diff --git a/server/mpm/netware/mpm.h b/server/mpm/netware/mpm.h new file mode 100644 index 0000000000..1ce59331e5 --- /dev/null +++ b/server/mpm/netware/mpm.h @@ -0,0 +1,87 @@ +/* ==================================================================== + * The Apache Software License, Version 1.1 + * + * Copyright (c) 2000-2001 The Apache Software Foundation. All rights + * reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * 3. The end-user documentation included with the redistribution, + * if any, must include the following acknowledgment: + * "This product includes software developed by the + * Apache Software Foundation (http://www.apache.org/)." + * Alternately, this acknowledgment may appear in the software itself, + * if and wherever such third-party acknowledgments normally appear. + * + * 4. The names "Apache" and "Apache Software Foundation" must + * not be used to endorse or promote products derived from this + * software without prior written permission. For written + * permission, please contact apache@apache.org. + * + * 5. Products derived from this software may not be called "Apache", + * nor may "Apache" appear in their name, without prior written + * permission of the Apache Software Foundation. + * + * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED + * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR + * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF + * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND + * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, + * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT + * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + * SUCH DAMAGE. + * ==================================================================== + * + * This software consists of voluntary contributions made by many + * individuals on behalf of the Apache Software Foundation. For more + * information on the Apache Software Foundation, please see + * <http://www.apache.org/>. + * + * Portions of this software are based upon public domain software + * originally written at the National Center for Supercomputing Applications, + * University of Illinois, Urbana-Champaign. + */ +#include "scoreboard.h" +//#include "unixd.h" + +#ifndef APACHE_MPM_THREADED_H +#define APACHE_MPM_THREADED_H + +#define THREADED_MPM + +#define MPM_NAME "NetWare_Threaded" + +//#define AP_MPM_WANT_RECLAIM_CHILD_PROCESSES +#define AP_MPM_WANT_WAIT_OR_TIMEOUT +//#define AP_MPM_WANT_PROCESS_CHILD_STATUS +#define AP_MPM_WANT_SET_PIDFILE +#define AP_MPM_WANT_SET_SCOREBOARD +#define AP_MPM_WANT_SET_LOCKFILE +#define AP_MPM_WANT_SET_MAX_REQUESTS +#define AP_MPM_WANT_SET_COREDUMPDIR +//#define AP_MPM_WANT_SET_ACCEPT_LOCK_MECH + +#define MPM_SYNC_CHILD_TABLE() (ap_sync_scoreboard_image()) +#define MPM_CHILD_PID(i) (ap_scoreboard_image->parent[i].pid) +#define MPM_NOTE_CHILD_KILLED(i) (MPM_CHILD_PID(i) = 0) + +extern int ap_threads_per_child; +extern int ap_thread_stack_size; +extern int ap_max_workers_limit; +extern server_rec *ap_server_conf; + +#endif /* APACHE_MPM_THREADED_H */ diff --git a/server/mpm/netware/mpm_default.h b/server/mpm/netware/mpm_default.h new file mode 100644 index 0000000000..6ae8d1a81b --- /dev/null +++ b/server/mpm/netware/mpm_default.h @@ -0,0 +1,145 @@ +/* ==================================================================== + * The Apache Software License, Version 1.1 + * + * Copyright (c) 2000-2001 The Apache Software Foundation. All rights + * reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * 3. The end-user documentation included with the redistribution, + * if any, must include the following acknowledgment: + * "This product includes software developed by the + * Apache Software Foundation (http://www.apache.org/)." + * Alternately, this acknowledgment may appear in the software itself, + * if and wherever such third-party acknowledgments normally appear. + * + * 4. The names "Apache" and "Apache Software Foundation" must + * not be used to endorse or promote products derived from this + * software without prior written permission. For written + * permission, please contact apache@apache.org. + * + * 5. Products derived from this software may not be called "Apache", + * nor may "Apache" appear in their name, without prior written + * permission of the Apache Software Foundation. + * + * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED + * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR + * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF + * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND + * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, + * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT + * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + * SUCH DAMAGE. + * ==================================================================== + * + * This software consists of voluntary contributions made by many + * individuals on behalf of the Apache Software Foundation. For more + * information on the Apache Software Foundation, please see + * <http://www.apache.org/>. + * + * Portions of this software are based upon public domain software + * originally written at the National Center for Supercomputing Applications, + * University of Illinois, Urbana-Champaign. + */ + +#ifndef APACHE_MPM_DEFAULT_H +#define APACHE_MPM_DEFAULT_H + +#define AP_ID_FROM_CHILD_THREAD(c, t) ((c * HARD_THREAD_LIMIT) + t) +#define AP_CHILD_THREAD_FROM_ID(i) (0), (i) + +/* Number of servers to spawn off by default --- also, if fewer than + * this free when the caretaker checks, it will spawn more. + */ +#ifndef DEFAULT_START_DAEMON +#define DEFAULT_START_DAEMON 1 +#endif + +/* Maximum number of *free* server processes --- more than this, and + * they will die off. + */ + +#ifndef DEFAULT_MAX_FREE_DAEMON +#define DEFAULT_MAX_FREE_DAEMON 1 +#endif + +/* Minimum --- fewer than this, and more will be created */ + +#ifndef DEFAULT_MIN_FREE_DAEMON +#define DEFAULT_MIN_FREE_DAEMON 1 +#endif + +/* Limit on the total --- clients will be locked out if more servers than + * this are needed. It is intended solely to keep the server from crashing + * when things get out of hand. + * + * We keep a hard maximum number of servers, for two reasons --- first off, + * in case something goes seriously wrong, we want to stop the fork bomb + * short of actually crashing the machine we're running on by filling some + * kernel table. Secondly, it keeps the size of the scoreboard file small + * enough that we can read the whole thing without worrying too much about + * the overhead. + */ +#ifndef HARD_SERVER_LIMIT +#define HARD_SERVER_LIMIT 1 +#endif + +/* Limit on the threads per process. Clients will be locked out if more than + * this * HARD_SERVER_LIMIT are needed. + * + * We keep this for one reason it keeps the size of the scoreboard file small + * enough that we can read the whole thing without worrying too much about + * the overhead. + */ +#ifndef HARD_THREAD_LIMIT +#define HARD_THREAD_LIMIT 2048 +#endif + +#ifndef DEFAULT_THREADS_PER_CHILD +#define DEFAULT_THREADS_PER_CHILD 50 +#endif + +/* File used for accept locking, when we use a file */ +#ifndef DEFAULT_LOCKFILE +#define DEFAULT_LOCKFILE "logs/accept.lock" +#endif + +/* Scoreboard file, if there is one */ +#ifndef DEFAULT_SCOREBOARD +#define DEFAULT_SCOREBOARD "logs/apache_runtime_status" +#endif + +/* Where the main/parent process's pid is logged */ +#ifndef DEFAULT_PIDLOG +#define DEFAULT_PIDLOG "logs/httpd.pid" +#endif + +/* + * Interval, in microseconds, between scoreboard maintenance. + */ +#ifndef SCOREBOARD_MAINTENANCE_INTERVAL +#define SCOREBOARD_MAINTENANCE_INTERVAL 1000000 +#endif + +/* Number of requests to try to handle in a single process. If <= 0, + * the children don't die off. + */ +#ifndef DEFAULT_MAX_REQUESTS_PER_CHILD +#define DEFAULT_MAX_REQUESTS_PER_CHILD 10000 +#endif + +#endif /* AP_MPM_DEFAULT_H */ diff --git a/server/mpm/netware/mpm_netware.c b/server/mpm/netware/mpm_netware.c new file mode 100644 index 0000000000..e16a7ab592 --- /dev/null +++ b/server/mpm/netware/mpm_netware.c @@ -0,0 +1,1255 @@ +/* ==================================================================== + * The Apache Software License, Version 1.1 + * + * Copyright (c) 2000-2001 The Apache Software Foundation. All rights + * reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * 3. The end-user documentation included with the redistribution, + * if any, must include the following acknowledgment: + * "This product includes software developed by the + * Apache Software Foundation (http://www.apache.org/)." + * Alternately, this acknowledgment may appear in the software itself, + * if and wherever such third-party acknowledgments normally appear. + * + * 4. The names "Apache" and "Apache Software Foundation" must + * not be used to endorse or promote products derived from this + * software without prior written permission. For written + * permission, please contact apache@apache.org. + * + * 5. Products derived from this software may not be called "Apache", + * nor may "Apache" appear in their name, without prior written + * permission of the Apache Software Foundation. + * + * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED + * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR + * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF + * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND + * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, + * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT + * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + * SUCH DAMAGE. + * ==================================================================== + * + * This software consists of voluntary contributions made by many + * individuals on behalf of the Apache Software Foundation. For more + * information on the Apache Software Foundation, please see + * <http://www.apache.org/>. + * + * Portions of this software are based upon public domain software + * originally written at the National Center for Supercomputing Applications, + * University of Illinois, Urbana-Champaign. + */ + +/* + * httpd.c: simple http daemon for answering WWW file requests + * + * + * 03-21-93 Rob McCool wrote original code (up to NCSA HTTPd 1.3) + * + * 03-06-95 blong + * changed server number for child-alone processes to 0 and changed name + * of processes + * + * 03-10-95 blong + * Added numerous speed hacks proposed by Robert S. Thau (rst@ai.mit.edu) + * including set group before fork, and call gettime before to fork + * to set up libraries. + * + * 04-14-95 rst / rh + * Brandon's code snarfed from NCSA 1.4, but tinkered to work with the + * Apache server, and also to have child processes do accept() directly. + * + * April-July '95 rst + * Extensive rework for Apache. + */ + +/* TODO: this is a cobbled together prefork MPM example... it should mostly + * TODO: behave like apache-1.3... here's a short list of things I think + * TODO: need cleaning up still: + */ + +#include "apr.h" +#include "apr_portable.h" +#include "apr_strings.h" +#include "apr_thread_proc.h" +#include "apr_signal.h" +#include "apr_tables.h" +#include "apr_getopt.h" + +#define APR_WANT_STDIO +#define APR_WANT_STRFUNC +#include "apr_want.h" + +#if APR_HAVE_UNISTD_H +#include <unistd.h> +#endif +#if APR_HAVE_SYS_TYPES_H +#include <sys/types.h> +#endif + +#define CORE_PRIVATE + +#include "ap_config.h" +#include "httpd.h" +#include "mpm_default.h" +#include "http_main.h" +#include "http_log.h" +#include "http_config.h" +#include "http_core.h" /* for get_remote_host */ +#include "http_connection.h" +#include "scoreboard.h" +#include "ap_mpm.h" +#include "mpm_common.h" +#include "ap_listen.h" +#include "ap_mmn.h" + +#ifdef HAVE_TIME_H +#include <time.h> +#endif + +#include <signal.h> + +#define WORKER_DEAD SERVER_DEAD +#define WORKER_STARTING SERVER_STARTING +#define WORKER_READY SERVER_READY + +/* config globals */ + +int ap_threads_per_child=0; /* Worker threads per child */ +int ap_thread_stack_size=65536; +static apr_lock_t *accept_lock; +static int ap_threads_to_start=0; +static int ap_threads_min_free=0; +static int ap_threads_max_free=0; +static int ap_threads_limit=0; + +/* + * The max child slot ever assigned, preserved across restarts. Necessary + * to deal with MaxClients changes across SIGWINCH restarts. We use this + * value to optimize routines that have to scan the entire scoreboard. + */ +int ap_max_workers_limit = -1; +server_rec *ap_server_conf; + +/* *Non*-shared http_main globals... */ + +static apr_socket_t *sd; +static fd_set listenfds; +static int listenmaxfd; + +/* one_process --- debugging mode variable; can be set from the command line + * with the -X flag. If set, this gets you the child_main loop running + * in the process which originally started up (no detach, no make_child), + * which is a pretty nice debugging environment. (You'll get a SIGHUP + * early in standalone_main; just continue through. This is the server + * trying to kill off any child processes which it might have lying + * around --- Apache doesn't keep track of their pids, it just sends + * SIGHUP to the process group, ignoring it in the root process. + * Continue through and you'll be fine.). + */ + +static int one_process = 0; + +static apr_pool_t *pconf; /* Pool for config stuff */ +static apr_pool_t *pmain; /* Pool for httpd child stuff */ + +static pid_t ap_my_pid; /* it seems silly to call getpid all the time */ +static pid_t parent_pid; +#ifndef MULTITHREAD +static int my_child_num; +#endif + +static int die_now = 0; +static apr_lock_t *accept_mutex = NULL; + +/* Keep track of the number of worker threads currently active */ +static int worker_thread_count; +static apr_lock_t *worker_thread_count_mutex; + + +#ifdef GPROF +/* + * change directory for gprof to plop the gmon.out file + * configure in httpd.conf: + * GprofDir logs/ -> $ServerRoot/logs/gmon.out + * GprofDir logs/% -> $ServerRoot/logs/gprof.$pid/gmon.out + */ +static void chdir_for_gprof(void) +{ + core_server_config *sconf = + ap_get_module_config(ap_server_conf->module_config, &core_module); + char *dir = sconf->gprof_dir; + const char *use_dir; + + if(dir) { + apr_status_t res; + char buf[512]; + int len = strlen(sconf->gprof_dir) - 1; + if(*(dir + len) == '%') { + dir[len] = '\0'; + apr_snprintf(buf, sizeof(buf), "%sgprof.%d", dir, (int)getpid()); + } + use_dir = ap_server_root_relative(pconf, buf[0] ? buf : dir); + res = apr_dir_make(use_dir, 0755, pconf); + if(res != APR_SUCCESS && !APR_STATUS_IS_EEXIST(res)) { + ap_log_error(APLOG_MARK, APLOG_ERR, errno, ap_server_conf, + "gprof: error creating directory %s", dir); + } + } + else { + use_dir = ap_server_root_relative(pconf, "logs"); + } + + chdir(dir); +} +#else +#define chdir_for_gprof() +#endif + +/* XXX - I don't know if TPF will ever use this module or not, so leave + * the ap_check_signals calls in but disable them - manoj */ +#define ap_check_signals() + +/* a clean exit from a child with proper cleanup */ +static void clean_child_exit(int code) __attribute__ ((noreturn)); +static void clean_child_exit(int code) +{ + apr_thread_mutex_lock(worker_thread_count_mutex); + worker_thread_count--; + apr_thread_mutex_unlock(worker_thread_count_mutex); + NXThreadExit((void*)&code); +} + +static apr_status_t accept_mutex_child_cleanup(void *foo) +{ + return apr_thread_mutex_unlock(accept_mutex); +} + +/* Initialize mutex lock. + * Done by each child at its birth + */ +static void accept_mutex_child_init(apr_pool_t *p) +{ + apr_pool_cleanup_register(p, NULL, accept_mutex_child_cleanup, apr_pool_cleanup_null); +} + +static void accept_mutex_on(void) +{ + apr_status_t rc = apr_thread_mutex_lock(accept_mutex); + + if (rc != APR_SUCCESS) { + ap_log_error(APLOG_MARK, APLOG_EMERG, rc, ap_server_conf, + "Error getting accept lock. Exiting!"); + clean_child_exit(APEXIT_CHILDFATAL); + } +} + +static void accept_mutex_off(void) +{ + apr_status_t rc = apr_thread_mutex_unlock(accept_mutex); + + if (rc != APR_SUCCESS) { + ap_log_error(APLOG_MARK, APLOG_EMERG, rc, ap_server_conf, + "Error freeing accept lock. Exiting!"); + clean_child_exit(APEXIT_CHILDFATAL); + } +} + +/* On some architectures it's safe to do unserialized accept()s in the single + * Listen case. But it's never safe to do it in the case where there's + * multiple Listen statements. Define SINGLE_LISTEN_UNSERIALIZED_ACCEPT + * when it's safe in the single Listen case. + */ +#ifdef SINGLE_LISTEN_UNSERIALIZED_ACCEPT +#define SAFE_ACCEPT(stmt) do {if (ap_listeners->next) {stmt;}} while(0) +#else +#define SAFE_ACCEPT(stmt) do {stmt;} while(0) +#endif + +//#ifdef NO_SERIALIZED_ACCEPT +//#define SAFE_ACCEPT(stmt) APR_SUCCESS +//#else +//#define SAFE_ACCEPT(stmt) (stmt) +//#endif + +AP_DECLARE(apr_status_t) ap_mpm_query(int query_code, int *result) +{ + switch(query_code){ + case AP_MPMQ_MAX_DAEMON_USED: + *result = ap_threads_limit; + return APR_SUCCESS; + case AP_MPMQ_IS_THREADED: + *result = AP_MPMQ_NOT_SUPPORTED; + return APR_SUCCESS; + case AP_MPMQ_IS_FORKED: + *result = AP_MPMQ_DYNAMIC; + return APR_SUCCESS; + case AP_MPMQ_HARD_LIMIT_DAEMONS: + *result = HARD_SERVER_LIMIT; + return APR_SUCCESS; + case AP_MPMQ_HARD_LIMIT_THREADS: + *result = HARD_THREAD_LIMIT; + return APR_SUCCESS; + case AP_MPMQ_MAX_THREADS: + *result = 0; + return APR_SUCCESS; + case AP_MPMQ_MIN_SPARE_DEAMONS: + *result = ap_threads_min_free; + return APR_SUCCESS; + case AP_MPMQ_MIN_SPARE_THREADS: + *result = 0; + return APR_SUCCESS; + case AP_MPMQ_MAX_SPARE_DAEMONS: + *result = ap_threads_max_free; + return APR_SUCCESS; + case AP_MPMQ_MAX_SPARE_THREADS: + *result = 0; + return APR_SUCCESS; + case AP_MPMQ_MAX_REQUESTS_DEAMON: + *result = ap_max_requests_per_child; + return APR_SUCCESS; + case AP_MPMQ_MAX_DAEMONS: + *result = ap_threads_limit; + return APR_SUCCESS; + } + return APR_ENOTIMPL; +} + + +/***************************************************************** + * Connection structures and accounting... + */ + +static void just_die(int sig) +{ + clean_child_exit(0); +} + +/* volatile just in case */ +static int volatile shutdown_pending; +static int volatile restart_pending; +static int volatile is_graceful; +static int volatile wait_to_finish=1; +ap_generation_t volatile ap_my_generation=0; + +static void sig_term(int sig) +{ + if (shutdown_pending == 1) { + /* Um, is this _probably_ not an error, if the user has + * tried to do a shutdown twice quickly, so we won't + * worry about reporting it. + */ + return; + } + shutdown_pending = 1; + + while (wait_to_finish) + delay(500); +// NXThreadYield(); + delay(2000); +// The shut down flag wait_to_finish needs to be set in +// the atexit() routine when it is finally working. +} + +/* restart() is the signal handler for SIGHUP and SIGWINCH + * in the parent process, unless running in ONE_PROCESS mode + */ +static void restart(int sig) +{ + if (restart_pending == 1) { + /* Probably not an error - don't bother reporting it */ + return; + } + restart_pending = 1; +} + +static void set_signals(void) +{ + apr_signal(SIGTERM, sig_term); +} + +/***************************************************************** + * Child process main loop. + * The following vars are static to avoid getting clobbered by longjmp(); + * they are really private to child_main. + */ + +//static int srv; +//static apr_socket_t *csd; +//static int requests_this_child; +static fd_set main_fds; + +int ap_graceful_stop_signalled(void) +{ + /* not ever called anymore... */ + return 0; +} + +static int setup_listen_poll(apr_pool_t *pmain, apr_pollfd_t **listen_poll) +{ + ap_listen_rec *lr; + int numfds = 0; + + for (lr = ap_listeners; lr; lr = lr->next) { + numfds++; + } + + apr_poll_setup(listen_poll, numfds, pmain); + + for (lr = ap_listeners; lr; lr = lr->next) { + apr_poll_socket_add(*listen_poll, lr->sd, APR_POLLIN); + } + return 0; +} + + +static void worker_main(void *arg) +{ + ap_listen_rec *lr; + ap_listen_rec *last_lr; + ap_listen_rec *first_lr; + apr_pool_t *ptrans; + conn_rec *current_conn; + apr_status_t stat = APR_EINIT; + int sockdes; + int worker_num_arg = *((int*)arg); + apr_pollfd_t *listen_poll; + int nsds, rv; + + int my_worker_num = worker_num_arg; + apr_socket_t *csd = NULL; + int requests_this_child = 0; + int srv; + struct timeval tv; + + last_lr = NULL; + tv.tv_sec = 1; + tv.tv_usec = 0; + + apr_pool_create(&ptrans, pmain); + + apr_thread_mutex_lock(worker_thread_count_mutex); + worker_thread_count++; + apr_thread_mutex_unlock(worker_thread_count_mutex); + + if (setup_listen_poll(pmain, &listen_poll)) { + clean_child_exit(1); + } + + ap_update_child_status(AP_CHILD_THREAD_FROM_ID(my_child_num), WORKER_READY, (request_rec *) NULL); + +// ap_sync_scoreboard_image(); + while (!die_now) { + /* + * (Re)initialize this child to a pre-connection state. + */ + current_conn = NULL; + apr_pool_clear(ptrans); + + if ((ap_max_requests_per_child > 0 + && requests_this_child++ >= ap_max_requests_per_child)) { + clean_child_exit(0); + } + + ap_update_child_status(AP_CHILD_THREAD_FROM_ID(my_child_num), WORKER_READY, (request_rec *) NULL); + + /* + * Wait for an acceptable connection to arrive. + */ + + /* Lock around "accept", if necessary */ + SAFE_ACCEPT(accept_mutex_on()); + + for (;;) { + if (shutdown_pending) { +printf ("Thread %d is shutting down\n", getpid()); + SAFE_ACCEPT(accept_mutex_off()); + clean_child_exit(0); + } + + /* more than one socket */ + memcpy(&main_fds, &listenfds, sizeof(fd_set)); + srv = select(listenmaxfd + 1, &main_fds, NULL, NULL, &tv); + + if (srv < 0 && h_errno != EINTR) { + /* Single Unix documents select as returning errnos + * EBADF, EINTR, and EINVAL... and in none of those + * cases does it make sense to continue. In fact + * on Linux 2.0.x we seem to end up with EFAULT + * occasionally, and we'd loop forever due to it. + */ + ap_log_error(APLOG_MARK, APLOG_ERR, h_errno, ap_server_conf, "select: (listen)"); + clean_child_exit(1); + } + + if (srv <= 0) + continue; + + /* we remember the last_lr we searched last time around so that + we don't end up starving any particular listening socket */ + if (last_lr == NULL) { + lr = ap_listeners; + } + else { + lr = last_lr->next; + if (!lr) + lr = ap_listeners; + } + first_lr = lr; + do { + apr_os_sock_get(&sockdes, lr->sd); + if (FD_ISSET(sockdes, &main_fds)) + goto got_listener; + lr = lr->next; + if (!lr) + lr = ap_listeners; + } while (lr != first_lr); + /* FIXME: if we get here, something bad has happened, and we're + probably gonna spin forever. + */ + continue; +got_listener: + last_lr = lr; + sd = lr->sd; + + /* if we accept() something we don't want to die, so we have to + * defer the exit + */ + for (;;) { +// ap_sync_scoreboard_image(); + stat = apr_accept(&csd, sd, ptrans); + if (stat == APR_SUCCESS || !APR_STATUS_IS_EINTR(stat)) + break; + } + + if (stat == APR_SUCCESS) + break; /* We have a socket ready for reading */ + else { + /* Our old behaviour here was to continue after accept() + * errors. But this leads us into lots of troubles + * because most of the errors are quite fatal. For + * example, EMFILE can be caused by slow descriptor + * leaks (say in a 3rd party module, or libc). It's + * foolish for us to continue after an EMFILE. We also + * seem to tickle kernel bugs on some platforms which + * lead to never-ending loops here. So it seems best + * to just exit in most cases. + */ + switch (stat) { + + /* Linux generates the rest of these, other tcp + * stacks (i.e. bsd) tend to hide them behind + * getsockopt() interfaces. They occur when + * the net goes sour or the client disconnects + * after the three-way handshake has been done + * in the kernel but before userland has picked + * up the socket. + */ + case ECONNRESET: + case ETIMEDOUT: + case EHOSTUNREACH: + case ENETUNREACH: + break; + + case ENETDOWN: + /* + * When the network layer has been shut down, there + * is not much use in simply exiting: the parent + * would simply re-create us (and we'd fail again). + * Use the CHILDFATAL code to tear the server down. + * @@@ Martin's idea for possible improvement: + * A different approach would be to define + * a new APEXIT_NETDOWN exit code, the reception + * of which would make the parent shutdown all + * children, then idle-loop until it detected that + * the network is up again, and restart the children. + * Ben Hyde noted that temporary ENETDOWN situations + * occur in mobile IP. + */ + ap_log_error(APLOG_MARK, APLOG_EMERG, stat, ap_server_conf, + "apr_accept: giving up."); + clean_child_exit(APEXIT_CHILDFATAL); + + default: + ap_log_error(APLOG_MARK, APLOG_ERR, stat, ap_server_conf, + "apr_accept: (client socket)"); + clean_child_exit(1); + } + } + +// ap_sync_scoreboard_image(); + } + + SAFE_ACCEPT(accept_mutex_off()); /* unlock after "accept" */ + + /* + * We now have a connection, so set it up with the appropriate + * socket options, file descriptors, and read/write buffers. + */ + + apr_os_sock_get(&sockdes, csd); + + if (sockdes >= FD_SETSIZE) { + ap_log_error(APLOG_MARK, APLOG_NOERRNO|APLOG_WARNING, 0, NULL, + "new file descriptor %d is too large; you probably need " + "to rebuild Apache with a larger FD_SETSIZE " + "(currently %d)", + sockdes, FD_SETSIZE); + apr_socket_close(csd); +// ap_sync_scoreboard_image(); + continue; + } + + ap_sock_disable_nagle(csd); + + current_conn = ap_new_connection(ptrans, ap_server_conf, csd, + my_child_num); + if (current_conn) { + ap_process_connection(current_conn); + ap_lingering_close(current_conn); + } + +// ap_sync_scoreboard_image(); + } + clean_child_exit(0); +} + + +static int make_child(server_rec *s, int slot) +{ + int tid; + int err=0; + NXContext_t ctx; + + if (slot + 1 > ap_max_workers_limit) { + ap_max_workers_limit = slot + 1; + } + + if (one_process) { + apr_signal(SIGINT, just_die); + apr_signal(SIGTERM, just_die); + worker_main((void*)&slot); + } + + ap_update_child_status(AP_CHILD_THREAD_FROM_ID(slot), WORKER_STARTING, (request_rec *) NULL); + + if (ctx = NXContextAlloc((void (*)(void *)) worker_main, &slot, NX_PRIO_MED, ap_thread_stack_size, NX_CTX_NORMAL, &err)) { + char threadName[32]; + + sprintf (threadName, "Apache_Worker %d", slot); + NXContextSetName(ctx, threadName); + err = NXThreadCreate(ctx, NX_THR_BIND_CONTEXT, &tid); + if (err) { + NXContextFree (ctx); + } + } + + if (err) { + /* create thread didn't succeed. Fix the scoreboard or else + * it will say SERVER_STARTING forever and ever + */ + ap_update_child_status(AP_CHILD_THREAD_FROM_ID(slot), WORKER_DEAD, (request_rec *) NULL); + + /* In case system resources are maxxed out, we don't want + Apache running away with the CPU trying to fork over and + over and over again. */ + apr_thread_yield(); + + return -1; + } + + ap_scoreboard_image->servers[0][slot].tid = tid; + + return 0; +} + + +/* start up a bunch of worker threads */ +static void startup_workers(int number_to_start) +{ + int i; + + for (i = 0; number_to_start && i < ap_threads_limit; ++i) { + if (ap_scoreboard_image->servers[0][i].status != WORKER_DEAD) { + continue; + } + if (make_child(ap_server_conf, i) < 0) { + break; + } + --number_to_start; + } +} + + +/* + * idle_spawn_rate is the number of children that will be spawned on the + * next maintenance cycle if there aren't enough idle servers. It is + * doubled up to MAX_SPAWN_RATE, and reset only when a cycle goes by + * without the need to spawn. + */ +static int idle_spawn_rate = 1; +#ifndef MAX_SPAWN_RATE +#define MAX_SPAWN_RATE (32) +#endif +static int hold_off_on_exponential_spawning; + +static void perform_idle_server_maintenance(apr_pool_t *p) +{ + int i; + int to_kill; + int idle_count; + worker_score *ws; + int free_length; + int free_slots[MAX_SPAWN_RATE]; + int last_non_dead; + int total_non_dead; + + /* initialize the free_list */ + free_length = 0; + + to_kill = -1; + idle_count = 0; + last_non_dead = -1; + total_non_dead = 0; + + ap_sync_scoreboard_image(); + for (i = 0; i < ap_threads_limit; ++i) { + int status; + + if (i >= ap_max_workers_limit && free_length == idle_spawn_rate) + break; + ws = &ap_scoreboard_image->servers[i][0]; + status = ws->status; + if (status == WORKER_DEAD) { + /* try to keep children numbers as low as possible */ + if (free_length < idle_spawn_rate) { + free_slots[free_length] = i; + ++free_length; + } + } + else { + /* We consider a starting server as idle because we started it + * at least a cycle ago, and if it still hasn't finished starting + * then we're just going to swamp things worse by forking more. + * So we hopefully won't need to fork more if we count it. + * This depends on the ordering of SERVER_READY and SERVER_STARTING. + */ + if (status <= SERVER_READY) { + ++ idle_count; + /* always kill the highest numbered child if we have to... + * no really well thought out reason ... other than observing + * the server behaviour under linux where lower numbered children + * tend to service more hits (and hence are more likely to have + * their data in cpu caches). + */ + to_kill = i; + } + + ++total_non_dead; + last_non_dead = i; + } + } + ap_max_workers_limit = last_non_dead + 1; + if (idle_count > ap_threads_max_free) { + /* kill off one child... we use the pod because that'll cause it to + * shut down gracefully, in case it happened to pick up a request + * while we were counting + */ + idle_spawn_rate = 1; + } + else if (idle_count < ap_threads_min_free) { + /* terminate the free list */ + if (free_length == 0) { + /* only report this condition once */ + static int reported = 0; + + if (!reported) { + ap_log_error(APLOG_MARK, APLOG_NOERRNO|APLOG_ERR, 0, ap_server_conf, + "server reached MaxClients setting, consider" + " raising the MaxClients setting"); + reported = 1; + } + idle_spawn_rate = 1; + } + else { + if (idle_spawn_rate >= 8) { + ap_log_error(APLOG_MARK, APLOG_NOERRNO|APLOG_INFO, 0, ap_server_conf, + "server seems busy, (you may need " + "to increase StartServers, or Min/MaxSpareServers), " + "spawning %d children, there are %d idle, and " + "%d total children", idle_spawn_rate, + idle_count, total_non_dead); + } + for (i = 0; i < free_length; ++i) { + make_child(ap_server_conf, free_slots[i]); + } + /* the next time around we want to spawn twice as many if this + * wasn't good enough, but not if we've just done a graceful + */ + if (hold_off_on_exponential_spawning) { + --hold_off_on_exponential_spawning; + } + else if (idle_spawn_rate < MAX_SPAWN_RATE) { + idle_spawn_rate *= 2; + } + } + } + else { + idle_spawn_rate = 1; + } +} + +static int setup_listeners(server_rec *s) +{ + ap_listen_rec *lr; + int sockdes; + + if (ap_setup_listeners(s) < 1 ) { + ap_log_error(APLOG_MARK, APLOG_NOERRNO|APLOG_ALERT, 0, s, + "no listening sockets available, shutting down"); + return -1; + } + + listenmaxfd = -1; + FD_ZERO(&listenfds); + for (lr = ap_listeners; lr; lr = lr->next) { + apr_os_sock_get(&sockdes, lr->sd); + FD_SET(sockdes, &listenfds); + if (sockdes > listenmaxfd) { + listenmaxfd = sockdes; + } + } + return 0; +} + +/***************************************************************** + * Executive routines. + */ + +int ap_mpm_run(apr_pool_t *_pconf, apr_pool_t *plog, server_rec *s) +{ + int index; + int remaining_workers_to_start; + apr_status_t status=0; + + pconf = _pconf; + ap_server_conf = s; + + if (setup_listeners(s)) { + ap_log_error(APLOG_MARK, APLOG_NOERRNO|APLOG_ALERT, status, s, + "no listening sockets available, shutting down"); + return -1; + } + + ap_log_pid(pconf, ap_pid_fname); + + worker_thread_count = 0; + apr_thread_mutex_create(&worker_thread_count_mutex, pconf); + apr_thread_mutex_create(&accept_mutex, pconf); + if (!is_graceful) { + ap_run_pre_mpm(pconf, SB_NOT_SHARED); + } + + set_signals(); + +/* Normal child main stuff */ + + apr_pool_create(&pmain, pconf); + + /* needs to be done before we switch UIDs so we have permissions */ + reopen_scoreboard(pmain); + + ap_run_child_init(pmain, ap_server_conf); + + +/* End Normal child main stuff */ + + if (ap_threads_max_free < ap_threads_min_free + 1) /* Don't thrash... */ + ap_threads_max_free = ap_threads_min_free + 1; + + /* If we're doing a graceful_restart then we're going to see a lot + * of children exiting immediately when we get into the main loop + * below (because we just sent them SIGWINCH). This happens pretty + * rapidly... and for each one that exits we'll start a new one until + * we reach at least daemons_min_free. But we may be permitted to + * start more than that, so we'll just keep track of how many we're + * supposed to start up without the 1 second penalty between each fork. + */ + remaining_workers_to_start = ap_threads_to_start; + if (remaining_workers_to_start > ap_threads_limit) { + remaining_workers_to_start = ap_threads_limit; + } + if (!is_graceful) { + startup_workers(remaining_workers_to_start); + remaining_workers_to_start = 0; + } + else { + /* give the system some time to recover before kicking into + * exponential mode */ + hold_off_on_exponential_spawning = 10; + } + + ap_log_error(APLOG_MARK, APLOG_NOERRNO|APLOG_NOTICE, 0, ap_server_conf, + "%s configured -- resuming normal operations", + ap_get_server_version()); + ap_log_error(APLOG_MARK, APLOG_NOERRNO|APLOG_INFO, 0, ap_server_conf, + "Server built: %s", ap_get_server_built()); + restart_pending = shutdown_pending = 0; + + printf("%s \n", ap_get_server_version()); + + while (!restart_pending && !shutdown_pending) { + int worker_slot; + apr_wait_t status; + +// /* this is a memory leak, but I'll fix it later. */ +// apr_proc_t pid; +// +// ap_wait_or_timeout(&status, &pid, pconf); +// +// /* XXX: if it takes longer than 1 second for all our children +// * to start up and get into IDLE state then we may spawn an +// * extra child +// */ +// if (pid.pid != -1) { +// ap_process_child_status(&pid, status); +// /* non-fatal death... note that it's gone in the scoreboard. */ +// ap_sync_scoreboard_image(); +// child_slot = find_child_by_pid(&pid); +// if (child_slot >= 0) { +// ap_update_child_status(AP_CHILD_THREAD_FROM_ID(child_slot), WORKER_DEAD, +// (request_rec *) NULL); +// if (remaining_workers_to_start && child_slot < ap_threads_limit) { +// /* we're still doing a 1-for-1 replacement of dead +// * children with new children +// */ +// make_child(ap_server_conf, child_slot); +// --remaining_workers_to_start; +// } +//#if APR_HAS_OTHER_CHILD +// } +// else if (apr_proc_other_child_read(&pid, status) == 0) { +// /* handled */ +//#endif +// } +// else if (is_graceful) { +// /* Great, we've probably just lost a slot in the +// * scoreboard. Somehow we don't know about this +// * child. +// */ +// ap_log_error(APLOG_MARK, APLOG_NOERRNO|APLOG_WARNING, +// 0, ap_server_conf, +// "long lost child came home! (pid %ld)", (long)pid.pid); +// } +// /* Don't perform idle maintenance when a child dies, +// * only do it when there's a timeout. Remember only a +// * finite number of children can die, and it's pretty +// * pathological for a lot to die suddenly. +// */ +// continue; +// } +// else if (remaining_workers_to_start) { +// /* we hit a 1 second timeout in which none of the previous +// * generation of children needed to be reaped... so assume +// * they're all done, and pick up the slack if any is left. +// */ +// startup_children(remaining_workers_to_start); +// remaining_workers_to_start = 0; +// /* In any event we really shouldn't do the code below because +// * few of the servers we just started are in the IDLE state +// * yet, so we'd mistakenly create an extra server. +// */ +// continue; +// } + +// perform_idle_server_maintenance(pconf); + apr_thread_yield(); + } + + if (shutdown_pending) { + ap_log_error(APLOG_MARK, APLOG_NOERRNO|APLOG_NOTICE, 0, ap_server_conf, + "caught SIGTERM, shutting down"); + + while (worker_thread_count > 0) + apr_thread_yield(); + + printf ("Press any key to continue..."); + getc(stdin); + wait_to_finish = 0; + return 1; + } + + /* we've been told to restart */ +// apr_signal(SIGHUP, SIG_IGN); + if (one_process) { + /* not worth thinking about */ + return 1; + } + + /* advance to the next generation */ + /* XXX: we really need to make sure this new generation number isn't in + * use by any of the children. + */ + ++ap_my_generation; + ap_scoreboard_image->global.running_generation = ap_my_generation; + update_scoreboard_global(); + + if (is_graceful) { + ap_log_error(APLOG_MARK, APLOG_NOERRNO|APLOG_NOTICE, 0, ap_server_conf, + "Graceful restart requested, doing restart"); + + /* kill off the idle ones */ + +#ifndef SCOREBOARD_FILE + /* This is mostly for debugging... so that we know what is still + * gracefully dealing with existing request. But we can't really + * do it if we're in a SCOREBOARD_FILE because it'll cause + * corruption too easily. + */ + ap_sync_scoreboard_image(); + for (index = 0; index < ap_threads_limit; ++index) { + if (ap_scoreboard_image->servers[0][index].status != WORKER_DEAD) { + ap_scoreboard_image->servers[0][index].status = SERVER_GRACEFUL; + } + } +#endif + } + else { + /* Kill 'em off */ + ap_log_error(APLOG_MARK, APLOG_NOERRNO|APLOG_NOTICE, 0, ap_server_conf, + "SIGHUP received. Attempting to restart"); + } + + return 0; +} + +static void netware_pre_config(apr_pool_t *p, apr_pool_t *plog, apr_pool_t *ptemp) +{ + static int restart_num = 0; + int no_detach, debug; + + debug = ap_exists_config_define("DEBUG"); + + if (debug) + no_detach = one_process = 1; + else + { + no_detach = ap_exists_config_define("NO_DETACH"); + one_process = ap_exists_config_define("ONE_PROCESS"); + } + + /* sigh, want this only the second time around */ + if (restart_num++ == 1) { + is_graceful = 0; + + if (!one_process && !no_detach) { + apr_proc_detach(); + } + + parent_pid = ap_my_pid = getpid(); + } + + ap_listen_pre_config(); + ap_threads_to_start = DEFAULT_START_DAEMON; + ap_threads_min_free = DEFAULT_MIN_FREE_DAEMON; + ap_threads_max_free = DEFAULT_MAX_FREE_DAEMON; + ap_threads_limit = HARD_THREAD_LIMIT; + ap_pid_fname = DEFAULT_PIDLOG; + ap_scoreboard_fname = DEFAULT_SCOREBOARD; + ap_lock_fname = DEFAULT_LOCKFILE; + ap_max_requests_per_child = DEFAULT_MAX_REQUESTS_PER_CHILD; + ap_extended_status = 0; + + apr_cpystrn(ap_coredump_dir, ap_server_root, sizeof(ap_coredump_dir)); +} + +static void netware_mpm_hooks(apr_pool_t *p) +{ + ap_hook_pre_config(netware_pre_config, NULL, NULL, APR_HOOK_MIDDLE); +} + +void netware_rewrite_args(process_rec *process) +{ + char *def_server_root; + char optbuf[3]; + const char *optarg; + apr_getopt_t *opt; + apr_array_header_t *mpm_new_argv; + + + /* Rewrite process->argv[]; + * + * add default -d serverroot from the path of this executable + * + * The end result will look like: + * The -d serverroot default from the running executable + */ + if (process->argc > 0) { + char *s = apr_pstrdup (process->pconf, process->argv[0]); + if (s) { + int i, len = strlen(s); + + for (i=len; i; i--) { + if (s[i] == '\\' || s[i] == '/') { + s[i] = NULL; + apr_filepath_merge(&def_server_root, NULL, s, + APR_FILEPATH_TRUENAME, process->pool); + break; + } + } + /* Use process->pool so that the rewritten argv + * lasts for the lifetime of the server process, + * because pconf will be destroyed after the + * initial pre-flight of the config parser. + */ + mpm_new_argv = apr_array_make(process->pool, process->argc + 2, + sizeof(const char *)); + *(const char **)apr_array_push(mpm_new_argv) = process->argv[0]; + *(const char **)apr_array_push(mpm_new_argv) = "-d"; + *(const char **)apr_array_push(mpm_new_argv) = def_server_root; + + optbuf[0] = '-'; + optbuf[2] = '\0'; + apr_getopt_init(&opt, process->pool, process->argc, (char**) process->argv); + while (apr_getopt(opt, AP_SERVER_BASEARGS, optbuf + 1, &optarg) == APR_SUCCESS) { + switch (optbuf[1]) { + default: + *(const char **)apr_array_push(mpm_new_argv) = + apr_pstrdup(process->pool, optbuf); + + if (optarg) { + *(const char **)apr_array_push(mpm_new_argv) = optarg; + } + break; + } + } + process->argc = mpm_new_argv->nelts; + process->argv = (const char * const *) mpm_new_argv->elts; + } + } +} + +static const char *set_threads_to_start(cmd_parms *cmd, void *dummy, const char *arg) +{ + const char *err = ap_check_cmd_context(cmd, GLOBAL_ONLY); + if (err != NULL) { + return err; + } + + ap_threads_to_start = atoi(arg); + return NULL; +} + +static const char *set_min_free_threads(cmd_parms *cmd, void *dummy, const char *arg) +{ + const char *err = ap_check_cmd_context(cmd, GLOBAL_ONLY); + if (err != NULL) { + return err; + } + + ap_threads_min_free = atoi(arg); + if (ap_threads_min_free <= 0) { + ap_log_error(APLOG_MARK, APLOG_STARTUP | APLOG_NOERRNO, 0, NULL, + "WARNING: detected MinSpareServers set to non-positive."); + ap_log_error(APLOG_MARK, APLOG_STARTUP | APLOG_NOERRNO, 0, NULL, + "Resetting to 1 to avoid almost certain Apache failure."); + ap_log_error(APLOG_MARK, APLOG_STARTUP | APLOG_NOERRNO, 0, NULL, + "Please read the documentation."); + ap_threads_min_free = 1; + } + + return NULL; +} + +static const char *set_max_free_threads(cmd_parms *cmd, void *dummy, const char *arg) +{ + const char *err = ap_check_cmd_context(cmd, GLOBAL_ONLY); + if (err != NULL) { + return err; + } + + ap_threads_max_free = atoi(arg); + return NULL; +} + +static const char *set_thread_limit (cmd_parms *cmd, void *dummy, const char *arg) +{ + const char *err = ap_check_cmd_context(cmd, GLOBAL_ONLY); + if (err != NULL) { + return err; + } + + ap_threads_limit = atoi(arg); + if (ap_threads_limit > HARD_THREAD_LIMIT) { + ap_log_error(APLOG_MARK, APLOG_STARTUP | APLOG_NOERRNO, 0, NULL, + "WARNING: MaxClients of %d exceeds compile time limit " + "of %d servers,", ap_threads_limit, HARD_SERVER_LIMIT); + ap_log_error(APLOG_MARK, APLOG_STARTUP | APLOG_NOERRNO, 0, NULL, + " lowering MaxClients to %d. To increase, please " + "see the", HARD_SERVER_LIMIT); + ap_log_error(APLOG_MARK, APLOG_STARTUP | APLOG_NOERRNO, 0, NULL, + " HARD_SERVER_LIMIT define in %s.", + AP_MPM_HARD_LIMITS_FILE); + ap_threads_limit = HARD_THREAD_LIMIT; + } + else if (ap_threads_limit < 1) { + ap_log_error(APLOG_MARK, APLOG_STARTUP | APLOG_NOERRNO, 0, NULL, + "WARNING: Require MaxClients > 0, setting to 1"); + ap_threads_limit = 1; + } + return NULL; +} + +static const char *set_thread_stacksize(cmd_parms *cmd, void *dummy, + const char *arg) +{ + const char *err = ap_check_cmd_context(cmd, GLOBAL_ONLY); + if (err != NULL) { + return err; + } + + ap_thread_stack_size = atoi(arg); + return NULL; +} + +static const command_rec netware_mpm_cmds[] = { +AP_INIT_TAKE1("ThreadStackSize", set_thread_stacksize, NULL, RSRC_CONF, + "Stack size each created thread will use."), +LISTEN_COMMANDS +AP_INIT_TAKE1("StartThreads", set_threads_to_start, NULL, RSRC_CONF, + "Number of worker threads launched at server startup"), +AP_INIT_TAKE1("MinSpareThreads", set_min_free_threads, NULL, RSRC_CONF, + "Minimum number of idle threads, to handle request spikes"), +AP_INIT_TAKE1("MaxSpareThreads", set_max_free_threads, NULL, RSRC_CONF, + "Maximum number of idle threads"), +AP_INIT_TAKE1("MaxThreads", set_thread_limit, NULL, RSRC_CONF, + "Maximum number of worker threads alive at the same time"), +{ NULL } +}; + +module AP_MODULE_DECLARE_DATA mpm_netware_module = { + MPM20_MODULE_STUFF, + netware_rewrite_args, /* hook to run before apache parses args */ + NULL, /* create per-directory config structure */ + NULL, /* merge per-directory config structures */ + NULL, /* create per-server config structure */ + NULL, /* merge per-server config structures */ + netware_mpm_cmds, /* command apr_table_t */ + netware_mpm_hooks, /* register hooks */ +}; diff --git a/server/mpm/winnt/nt_eventlog.c b/server/mpm/winnt/nt_eventlog.c new file mode 100644 index 0000000000..962ebc77a4 --- /dev/null +++ b/server/mpm/winnt/nt_eventlog.c @@ -0,0 +1,225 @@ +/* ==================================================================== + * The Apache Software License, Version 1.1 + * + * Copyright (c) 2000-2002 The Apache Software Foundation. All rights + * reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * 3. The end-user documentation included with the redistribution, + * if any, must include the following acknowledgment: + * "This product includes software developed by the + * Apache Software Foundation (http://www.apache.org/)." + * Alternately, this acknowledgment may appear in the software itself, + * if and wherever such third-party acknowledgments normally appear. + * + * 4. The names "Apache" and "Apache Software Foundation" must + * not be used to endorse or promote products derived from this + * software without prior written permission. For written + * permission, please contact apache@apache.org. + * + * 5. Products derived from this software may not be called "Apache", + * nor may "Apache" appear in their name, without prior written + * permission of the Apache Software Foundation. + * + * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED + * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR + * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF + * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND + * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, + * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT + * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + * SUCH DAMAGE. + * ==================================================================== + * + * This software consists of voluntary contributions made by many + * individuals on behalf of the Apache Software Foundation. For more + * information on the Apache Software Foundation, please see + * <http://www.apache.org/>. + * + * Portions of this software are based upon public domain software + * originally written at the National Center for Supercomputing Applications, + * University of Illinois, Urbana-Champaign. + */ + +#define CORE_PRIVATE + +#include "httpd.h" +#include "http_log.h" +#include "mpm_winnt.h" +#include "apr_strings.h" +#include "apr_lib.h" + +#include "apr_dbg_win32_handles.h" + + +static char *display_name = NULL; +static HANDLE stderr_thread = NULL; +static HANDLE stderr_ready; + +static DWORD WINAPI service_stderr_thread(LPVOID hPipe) +{ + HANDLE hPipeRead = (HANDLE) hPipe; + HANDLE hEventSource; + char errbuf[256]; + char *errmsg = errbuf; + const char *errarg[9]; + DWORD errres; + HKEY hk; + + errarg[0] = "The Apache service named"; + errarg[1] = display_name; + errarg[2] = "reported the following error:\r\n>>>"; + errarg[3] = errbuf; + errarg[4] = NULL; + errarg[5] = NULL; + errarg[6] = NULL; + errarg[7] = NULL; + errarg[8] = NULL; + + /* What are we going to do in here, bail on the user? not. */ + if (!RegCreateKey(HKEY_LOCAL_MACHINE, "SYSTEM\\CurrentControlSet\\Services" + "\\EventLog\\Application\\Apache Service", &hk)) + { + /* The stock message file */ + char *netmsgkey = "%SystemRoot%\\System32\\netmsg.dll"; + DWORD dwData = EVENTLOG_ERROR_TYPE | EVENTLOG_WARNING_TYPE | + EVENTLOG_INFORMATION_TYPE; + + RegSetValueEx(hk, "EventMessageFile", 0, REG_EXPAND_SZ, + (LPBYTE) netmsgkey, strlen(netmsgkey) + 1); + + RegSetValueEx(hk, "TypesSupported", 0, REG_DWORD, + (LPBYTE) &dwData, sizeof(dwData)); + RegCloseKey(hk); + } + + hEventSource = RegisterEventSource(NULL, "Apache Service"); + + SetEvent(stderr_ready); + + while (ReadFile(hPipeRead, errmsg, 1, &errres, NULL) && (errres == 1)) + { + if ((errmsg > errbuf) || !isspace(*errmsg)) + { + ++errmsg; + if ((*(errmsg - 1) == '\n') + || (errmsg >= errbuf + sizeof(errbuf) - 1)) + { + while ((errmsg > errbuf) && isspace(*(errmsg - 1))) { + --errmsg; + } + *errmsg = '\0'; + + /* Generic message: '%1 %2 %3 %4 %5 %6 %7 %8 %9' + * The event code in netmsg.dll is 3299 + */ + ReportEvent(hEventSource, EVENTLOG_ERROR_TYPE, 0, + 3299, NULL, 9, 0, errarg, NULL); + errmsg = errbuf; + } + } + } + + if ((errres = GetLastError()) != ERROR_BROKEN_PIPE) { + apr_snprintf(errbuf, sizeof(errbuf), + "Win32 error %d reading stderr pipe stream\r\n", + GetLastError()); + + ReportEvent(hEventSource, EVENTLOG_ERROR_TYPE, 0, + 3299, NULL, 9, 0, errarg, NULL); + } + + CloseHandle(hPipeRead); + DeregisterEventSource(hEventSource); + CloseHandle(stderr_thread); + stderr_thread = NULL; + return 0; +} + + +void mpm_nt_eventlog_stderr_flush(void) +{ + HANDLE cleanup_thread = stderr_thread; + + if (cleanup_thread) { + HANDLE hErr = GetStdHandle(STD_ERROR_HANDLE); + fclose(stderr); + CloseHandle(hErr); + WaitForSingleObject(cleanup_thread, 30000); + CloseHandle(cleanup_thread); + } +} + + +void mpm_nt_eventlog_stderr_open(char *argv0, apr_pool_t *p) +{ + SECURITY_ATTRIBUTES sa; + HANDLE hProc = GetCurrentProcess(); + HANDLE hPipeRead = NULL; + HANDLE hPipeWrite = NULL; + HANDLE hDup = NULL; + DWORD threadid; + int fd; + + display_name = argv0; + + /* Create a pipe to send stderr messages to the system error log. + * + * _dup2() duplicates the write handle inheritable for us. + */ + sa.nLength = sizeof(sa); + sa.lpSecurityDescriptor = NULL; + sa.bInheritHandle = FALSE; + CreatePipe(&hPipeRead, &hPipeWrite, NULL, 0); + ap_assert(hPipeRead && hPipeWrite); + + stderr_ready = CreateEvent(NULL, FALSE, FALSE, NULL); + stderr_thread = CreateThread(NULL, 0, service_stderr_thread, + (LPVOID) hPipeRead, 0, &threadid); + ap_assert(stderr_ready && stderr_thread); + + WaitForSingleObject(stderr_ready, INFINITE); + + /* Flush stderr and unset its buffer, then commit and replace stderr. + * This is typically a noop for Win2K/XP since services with NULL std + * handles [but valid FILE *'s, oddly enough], but is required + * for NT 4.0 and to use this code outside of services. + */ + fflush(stderr); + setvbuf(stderr, NULL, _IONBF, 0); + _commit(2 /* stderr */); + fd = _open_osfhandle((long) hPipeWrite, + _O_WRONLY | _O_BINARY); + _dup2(fd, 2); + _close(fd); + _setmode(2, _O_BINARY); + + /* hPipeWrite was _close()'ed above, and _dup2()'ed + * to fd 2 creating a new, inherited Win32 handle. + * Recover that real handle from fd 2. + */ + hPipeWrite = (HANDLE)_get_osfhandle(2); + + SetStdHandle(STD_ERROR_HANDLE, hPipeWrite); + + /* The code above _will_ corrupt the StdHandle... + * and we must do so anyways. We set this up only + * after we initialized the posix stderr API. + */ + ap_open_stderr_log(p); +} diff --git a/server/mpm/worker/pod.c b/server/mpm/worker/pod.c new file mode 100644 index 0000000000..c869e43832 --- /dev/null +++ b/server/mpm/worker/pod.c @@ -0,0 +1,234 @@ +/* ==================================================================== + * The Apache Software License, Version 1.1 + * + * Copyright (c) 2000-2001 The Apache Software Foundation. All rights + * reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * 3. The end-user documentation included with the redistribution, + * if any, must include the following acknowledgment: + * "This product includes software developed by the + * Apache Software Foundation (http://www.apache.org/)." + * Alternately, this acknowledgment may appear in the software itself, + * if and wherever such third-party acknowledgments normally appear. + * + * 4. The names "Apache" and "Apache Software Foundation" must + * not be used to endorse or promote products derived from this + * software without prior written permission. For written + * permission, please contact apache@apache.org. + * + * 5. Products derived from this software may not be called "Apache", + * nor may "Apache" appear in their name, without prior written + * permission of the Apache Software Foundation. + * + * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED + * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR + * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF + * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND + * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, + * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT + * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + * SUCH DAMAGE. + * ==================================================================== + * + * This software consists of voluntary contributions made by many + * individuals on behalf of the Apache Software Foundation. For more + * information on the Apache Software Foundation, please see + * <http://www.apache.org/>. + * + * Portions of this software are based upon public domain software + * originally written at the National Center for Supercomputing Applications, + * University of Illinois, Urbana-Champaign. + */ + +#include "apr.h" +#include "apr_strings.h" +#include "apr_lock.h" +#define APR_WANT_STRFUNC +#include "apr_want.h" + +#include "httpd.h" +#include "http_config.h" +#include "http_log.h" +#include "http_main.h" +#include "mpm.h" +#include "pod.h" +#include "mpm_common.h" +#include "ap_mpm.h" +#include "ap_listen.h" +#include "mpm_default.h" + +AP_DECLARE(apr_status_t) ap_mpm_pod_open(apr_pool_t *p, ap_pod_t **pod) +{ + apr_status_t rv; + + *pod = apr_palloc(p, sizeof(**pod)); + rv = apr_file_pipe_create(&((*pod)->pod_in), &((*pod)->pod_out), p); + if (rv != APR_SUCCESS) { + return rv; + } +/* + apr_file_pipe_timeout_set((*pod)->pod_in, 0); +*/ + (*pod)->p = p; + + apr_sockaddr_info_get(&(*pod)->sa, ap_listeners->bind_addr->hostname, + APR_UNSPEC, ap_listeners->bind_addr->port, 0, p); + + return APR_SUCCESS; +} + +AP_DECLARE(int) ap_mpm_pod_check(ap_pod_t *pod) +{ + char c; + apr_size_t len = 1; + apr_status_t rv; + + rv = apr_file_read(pod->pod_in, &c, &len); + + if ((rv == APR_SUCCESS) && (len ==1)) { + if (c == RESTART_CHAR) { + return AP_RESTART; + } + if (c == GRACEFUL_CHAR) { + return AP_GRACEFUL; + } + } + else if (rv != APR_SUCCESS) { + return rv; + } + return AP_NORESTART; +} + +AP_DECLARE(apr_status_t) ap_mpm_pod_close(ap_pod_t *pod) +{ + apr_status_t rv; + + rv = apr_file_close(pod->pod_out); + if (rv != APR_SUCCESS) { + return rv; + } + + rv = apr_file_close(pod->pod_in); + if (rv != APR_SUCCESS) { + return rv; + } + return rv; +} + +static apr_status_t pod_signal_internal(ap_pod_t *pod, int graceful) +{ + apr_status_t rv; + char char_of_death = graceful ? GRACEFUL_CHAR : RESTART_CHAR; + apr_size_t one = 1; + + do { + rv = apr_file_write(pod->pod_out, &char_of_death, &one); + } while (APR_STATUS_IS_EINTR(rv)); + if (rv != APR_SUCCESS) { + ap_log_error(APLOG_MARK, APLOG_WARNING, rv, ap_server_conf, + "write pipe_of_death"); + } + return rv; +} + +/* This function connects to the server, then immediately closes the connection. + * This permits the MPM to skip the poll when there is only one listening + * socket, because it provides a alternate way to unblock an accept() when + * the pod is used. + */ + +static apr_status_t dummy_connection(ap_pod_t *pod) +{ + apr_status_t rv; + apr_socket_t *sock; + apr_pool_t *p; + + /* create a temporary pool for the socket. pconf stays around too long */ + rv = apr_pool_create(&p, pod->p); + if (rv != APR_SUCCESS) { + return rv; + } + + rv = apr_socket_create(&sock, pod->sa->family, SOCK_STREAM, p); + if (rv != APR_SUCCESS) { + ap_log_error(APLOG_MARK, APLOG_WARNING, rv, ap_server_conf, + "get socket to connect to listener"); + return rv; + } + /* on some platforms (e.g., FreeBSD), the kernel won't accept many + * queued connections before it starts blocking local connects... + * we need to keep from blocking too long and instead return an error, + * because the MPM won't want to hold up a graceful restart for a + * long time + */ + rv = apr_setsocketopt(sock, APR_SO_TIMEOUT, 3 * APR_USEC_PER_SEC); + if (rv != APR_SUCCESS) { + ap_log_error(APLOG_MARK, APLOG_WARNING, rv, ap_server_conf, + "set timeout on socket to connect to listener"); + return rv; + } + + rv = apr_connect(sock, pod->sa); + if (rv != APR_SUCCESS) { + int log_level = APLOG_WARNING; + + if (APR_STATUS_IS_TIMEUP(rv)) { + /* probably some server processes bailed out already and there + * is nobody around to call accept and clear out the kernel + * connection queue; usually this is not worth logging + */ + log_level = APLOG_DEBUG; + } + + ap_log_error(APLOG_MARK, log_level, rv, ap_server_conf, + "connect to listener"); + } + + apr_socket_close(sock); + apr_pool_destroy(p); + + return rv; +} + +AP_DECLARE(apr_status_t) ap_mpm_pod_signal(ap_pod_t *pod, int graceful) +{ + apr_status_t rv; + + rv = pod_signal_internal(pod, graceful); + if (rv != APR_SUCCESS) { + return rv; + } + return dummy_connection(pod); +} + +AP_DECLARE(void) ap_mpm_pod_killpg(ap_pod_t *pod, int num, int graceful) +{ + int i; + apr_status_t rv = APR_SUCCESS; + + for (i = 0; i < num && rv == APR_SUCCESS; i++) { + rv = pod_signal_internal(pod, graceful); + } + if (rv == APR_SUCCESS) { + for (i = 0; i < num && rv == APR_SUCCESS; i++) { + rv = dummy_connection(pod); + } + } +} + diff --git a/server/mpm/worker/pod.h b/server/mpm/worker/pod.h new file mode 100644 index 0000000000..cc68b4b6e3 --- /dev/null +++ b/server/mpm/worker/pod.h @@ -0,0 +1,94 @@ +/* ==================================================================== + * The Apache Software License, Version 1.1 + * + * Copyright (c) 2000-2001 The Apache Software Foundation. All rights + * reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * 3. The end-user documentation included with the redistribution, + * if any, must include the following acknowledgment: + * "This product includes software developed by the + * Apache Software Foundation (http://www.apache.org/)." + * Alternately, this acknowledgment may appear in the software itself, + * if and wherever such third-party acknowledgments normally appear. + * + * 4. The names "Apache" and "Apache Software Foundation" must + * not be used to endorse or promote products derived from this + * software without prior written permission. For written + * permission, please contact apache@apache.org. + * + * 5. Products derived from this software may not be called "Apache", + * nor may "Apache" appear in their name, without prior written + * permission of the Apache Software Foundation. + * + * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED + * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR + * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF + * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND + * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, + * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT + * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + * SUCH DAMAGE. + * ==================================================================== + * + * This software consists of voluntary contributions made by many + * individuals on behalf of the Apache Software Foundation. For more + * information on the Apache Software Foundation, please see + * <http://www.apache.org/>. + * + * Portions of this software are based upon public domain software + * originally written at the National Center for Supercomputing Applications, + * University of Illinois, Urbana-Champaign. + */ + +#include "apr.h" +#include "apr_strings.h" +#include "apr_lock.h" +#define APR_WANT_STRFUNC +#include "apr_want.h" + +#include "httpd.h" +#include "http_config.h" +#include "http_log.h" +#include "http_main.h" +#include "mpm.h" +#include "mpm_common.h" +#include "ap_mpm.h" +#include "ap_listen.h" +#include "mpm_default.h" + +#define RESTART_CHAR '$' +#define GRACEFUL_CHAR '!' + +#define AP_RESTART 0 +#define AP_GRACEFUL 1 + +typedef struct ap_pod_t ap_pod_t; + +struct ap_pod_t { + apr_file_t *pod_in; + apr_file_t *pod_out; + apr_pool_t *p; + apr_sockaddr_t *sa; +}; + +AP_DECLARE(apr_status_t) ap_mpm_pod_open(apr_pool_t *p, ap_pod_t **pod); +AP_DECLARE(int) ap_mpm_pod_check(ap_pod_t *pod); +AP_DECLARE(apr_status_t) ap_mpm_pod_close(ap_pod_t *pod); +AP_DECLARE(apr_status_t) ap_mpm_pod_signal(ap_pod_t *pod, int graceful); +AP_DECLARE(void) ap_mpm_pod_killpg(ap_pod_t *pod, int num, int graceful); diff --git a/srclib/pcre/RunTest.in b/srclib/pcre/RunTest.in new file mode 100755 index 0000000000..63c4b26b15 --- /dev/null +++ b/srclib/pcre/RunTest.in @@ -0,0 +1,149 @@ +#! /bin/sh + +# This file is generated by configure from RunTest.in. Make any changes +# to that file. + +# Run PCRE tests + +cf=diff +testdata=@top_srcdir@/testdata + +# Select which tests to run; if no selection, run all + +do1=no +do2=no +do3=no +do4=no +do5=no +do6=no + +while [ $# -gt 0 ] ; do + case $1 in + 1) do1=yes;; + 2) do2=yes;; + 3) do3=yes;; + 4) do4=yes;; + 5) do5=yes;; + 6) do6=yes;; + *) echo "Unknown test number $1"; exit 1;; + esac + shift +done + +if [ "@UTF8@" = "" ] ; then + if [ $do5 = yes ] ; then + echo "Can't run test 5 because UFT8 support is not configured" + exit 1 + fi + if [ $do6 = yes ] ; then + echo "Can't run test 6 because UFT8 support is not configured" + exit 1 + fi +fi + +if [ $do1 = no -a $do2 = no -a $do3 = no -a $do4 = no -a\ + $do5 = no -a $do6 = no ] ; then + do1=yes + do2=yes + do3=yes + do4=yes + if [ "@UTF8@" != "" ] ; then do5=yes; fi + if [ "@UTF8@" != "" ] ; then do6=yes; fi +fi + +# Primary test, Perl-compatible + +if [ $do1 = yes ] ; then + echo "Testing main functionality (Perl compatible)" + ./pcretest $testdata/testinput1 testtry + if [ $? = 0 ] ; then + $cf testtry $testdata/testoutput1 + if [ $? != 0 ] ; then exit 1; fi + else exit 1 + fi +fi + +# PCRE tests that are not Perl-compatible - API & error tests, mostly + +if [ $do2 = yes ] ; then + echo "Testing API and error handling (not Perl compatible)" + ./pcretest -i $testdata/testinput2 testtry + if [ $? = 0 ] ; then + $cf testtry $testdata/testoutput2 + if [ $? != 0 ] ; then exit 1; fi + else exit 1 + fi +fi + +# Additional Perl-compatible tests for Perl 5.005's new features + +if [ $do3 = yes ] ; then + echo "Testing Perl 5.005 features (Perl 5.005 compatible)" + ./pcretest $testdata/testinput3 testtry + if [ $? = 0 ] ; then + $cf testtry $testdata/testoutput3 + if [ $? != 0 ] ; then exit 1; fi + else exit 1 + fi +fi + +if [ $do1 = yes -a $do2 = yes -a $do3 = yes ] ; then + echo " " + echo "The three main tests all ran OK" + echo " " +fi + +# Locale-specific tests, provided the "fr" locale is available + +if [ $do4 = yes ] ; then + locale -a | grep '^fr$' >/dev/null + if [ $? -eq 0 ] ; then + echo "Testing locale-specific features (using 'fr' locale)" + ./pcretest $testdata/testinput4 testtry + if [ $? = 0 ] ; then + $cf testtry $testdata/testoutput4 + if [ $? != 0 ] ; then + echo " " + echo "Locale test did not run entirely successfully." + echo "This usually means that there is a problem with the locale" + echo "settings rather than a bug in PCRE." + else + echo "Locale test ran OK" + fi + echo " " + else exit 1 + fi + else + echo "Cannot test locale-specific features - 'fr' locale not found," + echo "or the \"locale\" command is not available to check for it." + echo " " + fi +fi + +# Additional tests for UTF8 support + +if [ $do5 = yes ] ; then + echo "Testing experimental, incomplete UTF8 support (Perl compatible)" + ./pcretest $testdata/testinput5 testtry + if [ $? = 0 ] ; then + $cf testtry $testdata/testoutput5 + if [ $? != 0 ] ; then exit 1; fi + else exit 1 + fi + echo "UTF8 test ran OK" + echo " " +fi + +if [ $do6 = yes ] ; then + echo "Testing API and internals for UTF8 support (not Perl compatible)" + ./pcretest $testdata/testinput6 testtry + if [ $? = 0 ] ; then + $cf testtry $testdata/testoutput6 + if [ $? != 0 ] ; then exit 1; fi + else exit 1 + fi + echo "UTF8 internals test ran OK" + echo " " +fi + +# End diff --git a/srclib/pcre/doc/pcregrep.1 b/srclib/pcre/doc/pcregrep.1 new file mode 100644 index 0000000000..5d3151e867 --- /dev/null +++ b/srclib/pcre/doc/pcregrep.1 @@ -0,0 +1,88 @@ +.TH PCREGREP 1 +.SH NAME +pcregrep - a grep with Perl-compatible regular expressions. +.SH SYNOPSIS +.B pcregrep [-Vcfhilnrsvx] pattern [file] ... + + +.SH DESCRIPTION +\fBpcregrep\fR searches files for character patterns, in the same way as other +grep commands do, but it uses the PCRE regular expression library to support +patterns that are compatible with the regular expressions of Perl 5. See +\fBpcre(3)\fR for a full description of syntax and semantics. + +If no files are specified, \fBpcregrep\fR reads the standard input. By default, +each line that matches the pattern is copied to the standard output, and if +there is more than one file, the file name is printed before each line of +output. However, there are options that can change how \fBpcregrep\fR behaves. + +Lines are limited to BUFSIZ characters. BUFSIZ is defined in \fB<stdio.h>\fR. +The newline character is removed from the end of each line before it is matched +against the pattern. + + +.SH OPTIONS +.TP 10 +\fB-V\fR +Write the version number of the PCRE library being used to the standard error +stream. +.TP +\fB-c\fR +Do not print individual lines; instead just print a count of the number of +lines that would otherwise have been printed. If several files are given, a +count is printed for each of them. +.TP +\fB-f\fIfilename\fR +Read patterns from the file, one per line, and match all patterns against each +line. There is a maximum of 100 patterns. Trailing white space is removed, and +blank lines are ignored. An empty file contains no patterns and therefore +matches nothing. +.TP +\fB-h\fR +Suppress printing of filenames when searching multiple files. +.TP +\fB-i\fR +Ignore upper/lower case distinctions during comparisons. +.TP +\fB-l\fR +Instead of printing lines from the files, just print the names of the files +containing lines that would have been printed. Each file name is printed +once, on a separate line. +.TP +\fB-n\fR +Precede each line by its line number in the file. +.TP +\fB-r\fR +If any file is a directory, recursively scan the files it contains. Without +\fB-r\fR a directory is scanned as a normal file. +.TP +\fB-s\fR +Work silently, that is, display nothing except error messages. +The exit status indicates whether any matches were found. +.TP +\fB-v\fR +Invert the sense of the match, so that lines which do \fInot\fR match the +pattern are now the ones that are found. +.TP +\fB-x\fR +Force the pattern to be anchored (it must start matching at the beginning of +the line) and in addition, require it to match the entire line. This is +equivalent to having ^ and $ characters at the start and end of each +alternative branch in the regular expression. + + +.SH SEE ALSO +\fBpcre(3)\fR, Perl 5 documentation + + +.SH DIAGNOSTICS +Exit status is 0 if any matches were found, 1 if no matches were found, and 2 +for syntax errors or inacessible files (even if matches were found). + + +.SH AUTHOR +Philip Hazel <ph10@cam.ac.uk> + +Last updated: 15 August 2001 +.br +Copyright (c) 1997-2001 University of Cambridge. diff --git a/srclib/pcre/doc/pcregrep.html b/srclib/pcre/doc/pcregrep.html new file mode 100644 index 0000000000..7bc210c65a --- /dev/null +++ b/srclib/pcre/doc/pcregrep.html @@ -0,0 +1,120 @@ +<HTML> +<HEAD> +<TITLE>pcregrep specification</TITLE> +</HEAD> +<body bgcolor="#FFFFFF" text="#00005A"> +<H1>pcregrep specification</H1> +This HTML document has been generated automatically from the original man page. +If there is any nonsense in it, please consult the man page in case the +conversion went wrong. +<UL> +<LI><A NAME="TOC1" HREF="#SEC1">NAME</A> +<LI><A NAME="TOC2" HREF="#SEC2">SYNOPSIS</A> +<LI><A NAME="TOC3" HREF="#SEC3">DESCRIPTION</A> +<LI><A NAME="TOC4" HREF="#SEC4">OPTIONS</A> +<LI><A NAME="TOC5" HREF="#SEC5">SEE ALSO</A> +<LI><A NAME="TOC6" HREF="#SEC6">DIAGNOSTICS</A> +<LI><A NAME="TOC7" HREF="#SEC7">AUTHOR</A> +</UL> +<LI><A NAME="SEC1" HREF="#TOC1">NAME</A> +<P> +pcregrep - a grep with Perl-compatible regular expressions. +</P> +<LI><A NAME="SEC2" HREF="#TOC1">SYNOPSIS</A> +<P> +<B>pcregrep [-Vcfhilnrsvx] pattern [file] ...</B> +</P> +<LI><A NAME="SEC3" HREF="#TOC1">DESCRIPTION</A> +<P> +<B>pcregrep</B> searches files for character patterns, in the same way as other +grep commands do, but it uses the PCRE regular expression library to support +patterns that are compatible with the regular expressions of Perl 5. See +<B>pcre(3)</B> for a full description of syntax and semantics. +</P> +<P> +If no files are specified, <B>pcregrep</B> reads the standard input. By default, +each line that matches the pattern is copied to the standard output, and if +there is more than one file, the file name is printed before each line of +output. However, there are options that can change how <B>pcregrep</B> behaves. +</P> +<P> +Lines are limited to BUFSIZ characters. BUFSIZ is defined in <B><stdio.h></B>. +The newline character is removed from the end of each line before it is matched +against the pattern. +</P> +<LI><A NAME="SEC4" HREF="#TOC1">OPTIONS</A> +<P> +<B>-V</B> +Write the version number of the PCRE library being used to the standard error +stream. +</P> +<P> +<B>-c</B> +Do not print individual lines; instead just print a count of the number of +lines that would otherwise have been printed. If several files are given, a +count is printed for each of them. +</P> +<P> +\fB-f<I>filename</I> +Read patterns from the file, one per line, and match all patterns against each +line. There is a maximum of 100 patterns. Trailing white space is removed, and +blank lines are ignored. An empty file contains no patterns and therefore +matches nothing. +</P> +<P> +<B>-h</B> +Suppress printing of filenames when searching multiple files. +</P> +<P> +<B>-i</B> +Ignore upper/lower case distinctions during comparisons. +</P> +<P> +<B>-l</B> +Instead of printing lines from the files, just print the names of the files +containing lines that would have been printed. Each file name is printed +once, on a separate line. +</P> +<P> +<B>-n</B> +Precede each line by its line number in the file. +</P> +<P> +<B>-r</B> +If any file is a directory, recursively scan the files it contains. Without +<B>-r</B> a directory is scanned as a normal file. +</P> +<P> +<B>-s</B> +Work silently, that is, display nothing except error messages. +The exit status indicates whether any matches were found. +</P> +<P> +<B>-v</B> +Invert the sense of the match, so that lines which do <I>not</I> match the +pattern are now the ones that are found. +</P> +<P> +<B>-x</B> +Force the pattern to be anchored (it must start matching at the beginning of +the line) and in addition, require it to match the entire line. This is +equivalent to having ^ and $ characters at the start and end of each +alternative branch in the regular expression. +</P> +<LI><A NAME="SEC5" HREF="#TOC1">SEE ALSO</A> +<P> +<B>pcre(3)</B>, Perl 5 documentation +</P> +<LI><A NAME="SEC6" HREF="#TOC1">DIAGNOSTICS</A> +<P> +Exit status is 0 if any matches were found, 1 if no matches were found, and 2 +for syntax errors or inacessible files (even if matches were found). +</P> +<LI><A NAME="SEC7" HREF="#TOC1">AUTHOR</A> +<P> +Philip Hazel <ph10@cam.ac.uk> +</P> +<P> +Last updated: 15 August 2001 +<BR> +Copyright (c) 1997-2001 University of Cambridge. diff --git a/srclib/pcre/doc/pcregrep.txt b/srclib/pcre/doc/pcregrep.txt new file mode 100644 index 0000000000..1600228402 --- /dev/null +++ b/srclib/pcre/doc/pcregrep.txt @@ -0,0 +1,101 @@ +NAME + pcregrep - a grep with Perl-compatible regular expressions. + + + +SYNOPSIS + pcregrep [-Vcfhilnrsvx] pattern [file] ... + + + +DESCRIPTION + pcregrep searches files for character patterns, in the same + way as other grep commands do, but it uses the PCRE regular + expression library to support patterns that are compatible + with the regular expressions of Perl 5. See pcre(3) for a + full description of syntax and semantics. + + If no files are specified, pcregrep reads the standard + input. By default, each line that matches the pattern is + copied to the standard output, and if there is more than one + file, the file name is printed before each line of output. + However, there are options that can change how pcregrep + behaves. + + Lines are limited to BUFSIZ characters. BUFSIZ is defined in + <stdio.h>. The newline character is removed from the end of + each line before it is matched against the pattern. + + + +OPTIONS + -V Write the version number of the PCRE library being + used to the standard error stream. + + -c Do not print individual lines; instead just print + a count of the number of lines that would other- + wise have been printed. If several files are + given, a count is printed for each of them. + + -ffilename + Read patterns from the file, one per line, and + match all patterns against each line. There is a + maximum of 100 patterns. Trailing white space is + removed, and blank lines are ignored. An empty + file contains no patterns and therefore matches + nothing. + + -h Suppress printing of filenames when searching mul- + tiple files. + + -i Ignore upper/lower case distinctions during com- + parisons. + + -l Instead of printing lines from the files, just + + print the names of the files containing lines that + would have been printed. Each file name is printed + once, on a separate line. + + -n Precede each line by its line number in the file. + + -r If any file is a directory, recursively scan the + files it contains. Without -r a directory is + scanned as a normal file. + + -s Work silently, that is, display nothing except + error messages. The exit status indicates whether + any matches were found. + + -v Invert the sense of the match, so that lines which + do not match the pattern are now the ones that are + found. + + -x Force the pattern to be anchored (it must start + matching at the beginning of the line) and in + addition, require it to match the entire line. + This is equivalent to having ^ and $ characters at + the start and end of each alternative branch in + the regular expression. + + + +SEE ALSO + pcre(3), Perl 5 documentation + + + + + +DIAGNOSTICS + Exit status is 0 if any matches were found, 1 if no matches + were found, and 2 for syntax errors or inacessible files + (even if matches were found). + + + +AUTHOR + Philip Hazel <ph10@cam.ac.uk> + + Last updated: 15 August 2001 + Copyright (c) 1997-2001 University of Cambridge. diff --git a/srclib/pcre/doc/pcretest.1 b/srclib/pcre/doc/pcretest.1 new file mode 100644 index 0000000000..b2e25560d7 --- /dev/null +++ b/srclib/pcre/doc/pcretest.1 @@ -0,0 +1,282 @@ +.TH PCRETEST 1 +.SH NAME +pcretest - a program for testing Perl-compatible regular expressions. +.SH SYNOPSIS +.B pcretest "[-d] [-i] [-m] [-o osize] [-p] [-t] [source] [destination]" + +\fBpcretest\fR was written as a test program for the PCRE regular expression +library itself, but it can also be used for experimenting with regular +expressions. This man page describes the features of the test program; for +details of the regular expressions themselves, see the \fBpcre\fR man page. + +.SH OPTIONS +.TP 10 +\fB-d\fR +Behave as if each regex had the \fB/D\fR modifier (see below); the internal +form is output after compilation. +.TP 10 +\fB-i\fR +Behave as if each regex had the \fB/I\fR modifier; information about the +compiled pattern is given after compilation. +.TP 10 +\fB-m\fR +Output the size of each compiled pattern after it has been compiled. This is +equivalent to adding /M to each regular expression. For compatibility with +earlier versions of pcretest, \fB-s\fR is a synonym for \fB-m\fR. +.TP 10 +\fB-o\fR \fIosize\fR +Set the number of elements in the output vector that is used when calling PCRE +to be \fIosize\fR. The default value is 45, which is enough for 14 capturing +subexpressions. The vector size can be changed for individual matching calls by +including \\O in the data line (see below). +.TP 10 +\fB-p\fR +Behave as if each regex has \fB/P\fR modifier; the POSIX wrapper API is used +to call PCRE. None of the other options has any effect when \fB-p\fR is set. +.TP 10 +\fB-t\fR +Run each compile, study, and match 20000 times with a timer, and output +resulting time per compile or match (in milliseconds). Do not set \fB-t\fR with +\fB-m\fR, because you will then get the size output 20000 times and the timing +will be distorted. + + +.SH DESCRIPTION + +If \fBpcretest\fR is given two filename arguments, it reads from the first and +writes to the second. If it is given only one filename argument, it reads from +that file and writes to stdout. Otherwise, it reads from stdin and writes to +stdout, and prompts for each line of input, using "re>" to prompt for regular +expressions, and "data>" to prompt for data lines. + +The program handles any number of sets of input on a single input file. Each +set starts with a regular expression, and continues with any number of data +lines to be matched against the pattern. An empty line signals the end of the +data lines, at which point a new regular expression is read. The regular +expressions are given enclosed in any non-alphameric delimiters other than +backslash, for example + + /(a|bc)x+yz/ + +White space before the initial delimiter is ignored. A regular expression may +be continued over several input lines, in which case the newline characters are +included within it. It is possible to include the delimiter within the pattern +by escaping it, for example + + /abc\\/def/ + +If you do so, the escape and the delimiter form part of the pattern, but since +delimiters are always non-alphameric, this does not affect its interpretation. +If the terminating delimiter is immediately followed by a backslash, for +example, + + /abc/\\ + +then a backslash is added to the end of the pattern. This is done to provide a +way of testing the error condition that arises if a pattern finishes with a +backslash, because + + /abc\\/ + +is interpreted as the first line of a pattern that starts with "abc/", causing +pcretest to read the next line as a continuation of the regular expression. + + +.SH PATTERN MODIFIERS + +The pattern may be followed by \fBi\fR, \fBm\fR, \fBs\fR, or \fBx\fR to set the +PCRE_CASELESS, PCRE_MULTILINE, PCRE_DOTALL, or PCRE_EXTENDED options, +respectively. For example: + + /caseless/i + +These modifier letters have the same effect as they do in Perl. There are +others which set PCRE options that do not correspond to anything in Perl: +\fB/A\fR, \fB/E\fR, and \fB/X\fR set PCRE_ANCHORED, PCRE_DOLLAR_ENDONLY, and +PCRE_EXTRA respectively. + +Searching for all possible matches within each subject string can be requested +by the \fB/g\fR or \fB/G\fR modifier. After finding a match, PCRE is called +again to search the remainder of the subject string. The difference between +\fB/g\fR and \fB/G\fR is that the former uses the \fIstartoffset\fR argument to +\fBpcre_exec()\fR to start searching at a new point within the entire string +(which is in effect what Perl does), whereas the latter passes over a shortened +substring. This makes a difference to the matching process if the pattern +begins with a lookbehind assertion (including \\b or \\B). + +If any call to \fBpcre_exec()\fR in a \fB/g\fR or \fB/G\fR sequence matches an +empty string, the next call is done with the PCRE_NOTEMPTY and PCRE_ANCHORED +flags set in order to search for another, non-empty, match at the same point. +If this second match fails, the start offset is advanced by one, and the normal +match is retried. This imitates the way Perl handles such cases when using the +\fB/g\fR modifier or the \fBsplit()\fR function. + +There are a number of other modifiers for controlling the way \fBpcretest\fR +operates. + +The \fB/+\fR modifier requests that as well as outputting the substring that +matched the entire pattern, pcretest should in addition output the remainder of +the subject string. This is useful for tests where the subject contains +multiple copies of the same substring. + +The \fB/L\fR modifier must be followed directly by the name of a locale, for +example, + + /pattern/Lfr + +For this reason, it must be the last modifier letter. The given locale is set, +\fBpcre_maketables()\fR is called to build a set of character tables for the +locale, and this is then passed to \fBpcre_compile()\fR when compiling the +regular expression. Without an \fB/L\fR modifier, NULL is passed as the tables +pointer; that is, \fB/L\fR applies only to the expression on which it appears. + +The \fB/I\fR modifier requests that \fBpcretest\fR output information about the +compiled expression (whether it is anchored, has a fixed first character, and +so on). It does this by calling \fBpcre_fullinfo()\fR after compiling an +expression, and outputting the information it gets back. If the pattern is +studied, the results of that are also output. + +The \fB/D\fR modifier is a PCRE debugging feature, which also assumes \fB/I\fR. +It causes the internal form of compiled regular expressions to be output after +compilation. + +The \fB/S\fR modifier causes \fBpcre_study()\fR to be called after the +expression has been compiled, and the results used when the expression is +matched. + +The \fB/M\fR modifier causes the size of memory block used to hold the compiled +pattern to be output. + +The \fB/P\fR modifier causes \fBpcretest\fR to call PCRE via the POSIX wrapper +API rather than its native API. When this is done, all other modifiers except +\fB/i\fR, \fB/m\fR, and \fB/+\fR are ignored. REG_ICASE is set if \fB/i\fR is +present, and REG_NEWLINE is set if \fB/m\fR is present. The wrapper functions +force PCRE_DOLLAR_ENDONLY always, and PCRE_DOTALL unless REG_NEWLINE is set. + +The \fB/8\fR modifier causes \fBpcretest\fR to call PCRE with the PCRE_UTF8 +option set. This turns on the (currently incomplete) support for UTF-8 +character handling in PCRE, provided that it was compiled with this support +enabled. This modifier also causes any non-printing characters in output +strings to be printed using the \\x{hh...} notation if they are valid UTF-8 +sequences. + + +.SH DATA LINES + +Before each data line is passed to \fBpcre_exec()\fR, leading and trailing +whitespace is removed, and it is then scanned for \\ escapes. The following are +recognized: + + \\a alarm (= BEL) + \\b backspace + \\e escape + \\f formfeed + \\n newline + \\r carriage return + \\t tab + \\v vertical tab + \\nnn octal character (up to 3 octal digits) + \\xhh hexadecimal character (up to 2 hex digits) + \\x{hh...} hexadecimal UTF-8 character + + \\A pass the PCRE_ANCHORED option to \fBpcre_exec()\fR + \\B pass the PCRE_NOTBOL option to \fBpcre_exec()\fR + \\Cdd call pcre_copy_substring() for substring dd + after a successful match (any decimal number + less than 32) + \\Gdd call pcre_get_substring() for substring dd + after a successful match (any decimal number + less than 32) + \\L call pcre_get_substringlist() after a + successful match + \\N pass the PCRE_NOTEMPTY option to \fBpcre_exec()\fR + \\Odd set the size of the output vector passed to + \fBpcre_exec()\fR to dd (any number of decimal + digits) + \\Z pass the PCRE_NOTEOL option to \fBpcre_exec()\fR + +When \\O is used, it may be higher or lower than the size set by the \fB-O\fR +option (or defaulted to 45); \\O applies only to the call of \fBpcre_exec()\fR +for the line in which it appears. + +A backslash followed by anything else just escapes the anything else. If the +very last character is a backslash, it is ignored. This gives a way of passing +an empty line as data, since a real empty line terminates the data input. + +If \fB/P\fR was present on the regex, causing the POSIX wrapper API to be used, +only \fB\B\fR, and \fB\Z\fR have any effect, causing REG_NOTBOL and REG_NOTEOL +to be passed to \fBregexec()\fR respectively. + +The use of \\x{hh...} to represent UTF-8 characters is not dependent on the use +of the \fB/8\fR modifier on the pattern. It is recognized always. There may be +any number of hexadecimal digits inside the braces. The result is from one to +six bytes, encoded according to the UTF-8 rules. + + +.SH OUTPUT FROM PCRETEST + +When a match succeeds, pcretest outputs the list of captured substrings that +\fBpcre_exec()\fR returns, starting with number 0 for the string that matched +the whole pattern. Here is an example of an interactive pcretest run. + + $ pcretest + PCRE version 2.06 08-Jun-1999 + + re> /^abc(\\d+)/ + data> abc123 + 0: abc123 + 1: 123 + data> xyz + No match + +If the strings contain any non-printing characters, they are output as \\0x +escapes, or as \\x{...} escapes if the \fB/8\fR modifier was present on the +pattern. If the pattern has the \fB/+\fR modifier, then the output for +substring 0 is followed by the the rest of the subject string, identified by +"0+" like this: + + re> /cat/+ + data> cataract + 0: cat + 0+ aract + +If the pattern has the \fB/g\fR or \fB/G\fR modifier, the results of successive +matching attempts are output in sequence, like this: + + re> /\\Bi(\\w\\w)/g + data> Mississippi + 0: iss + 1: ss + 0: iss + 1: ss + 0: ipp + 1: pp + +"No match" is output only if the first match attempt fails. + +If any of the sequences \fB\\C\fR, \fB\\G\fR, or \fB\\L\fR are present in a +data line that is successfully matched, the substrings extracted by the +convenience functions are output with C, G, or L after the string number +instead of a colon. This is in addition to the normal full list. The string +length (that is, the return from the extraction function) is given in +parentheses after each string for \fB\\C\fR and \fB\\G\fR. + +Note that while patterns can be continued over several lines (a plain ">" +prompt is used for continuations), data lines may not. However newlines can be +included in data by means of the \\n escape. + + +.SH AUTHOR +Philip Hazel <ph10@cam.ac.uk> +.br +University Computing Service, +.br +New Museums Site, +.br +Cambridge CB2 3QG, England. +.br +Phone: +44 1223 334714 + +Last updated: 15 August 2001 +.br +Copyright (c) 1997-2001 University of Cambridge. diff --git a/srclib/pcre/doc/pcretest.html b/srclib/pcre/doc/pcretest.html new file mode 100644 index 0000000000..918e6dec2b --- /dev/null +++ b/srclib/pcre/doc/pcretest.html @@ -0,0 +1,369 @@ +<HTML> +<HEAD> +<TITLE>pcretest specification</TITLE> +</HEAD> +<body bgcolor="#FFFFFF" text="#00005A"> +<H1>pcretest specification</H1> +This HTML document has been generated automatically from the original man page. +If there is any nonsense in it, please consult the man page in case the +conversion went wrong. +<UL> +<LI><A NAME="TOC1" HREF="#SEC1">NAME</A> +<LI><A NAME="TOC2" HREF="#SEC2">SYNOPSIS</A> +<LI><A NAME="TOC3" HREF="#SEC3">OPTIONS</A> +<LI><A NAME="TOC4" HREF="#SEC4">DESCRIPTION</A> +<LI><A NAME="TOC5" HREF="#SEC5">PATTERN MODIFIERS</A> +<LI><A NAME="TOC6" HREF="#SEC6">DATA LINES</A> +<LI><A NAME="TOC7" HREF="#SEC7">OUTPUT FROM PCRETEST</A> +<LI><A NAME="TOC8" HREF="#SEC8">AUTHOR</A> +</UL> +<LI><A NAME="SEC1" HREF="#TOC1">NAME</A> +<P> +pcretest - a program for testing Perl-compatible regular expressions. +</P> +<LI><A NAME="SEC2" HREF="#TOC1">SYNOPSIS</A> +<P> +<B>pcretest [-d] [-i] [-m] [-o osize] [-p] [-t] [source] [destination]</B> +</P> +<P> +<B>pcretest</B> was written as a test program for the PCRE regular expression +library itself, but it can also be used for experimenting with regular +expressions. This man page describes the features of the test program; for +details of the regular expressions themselves, see the <B>pcre</B> man page. +</P> +<LI><A NAME="SEC3" HREF="#TOC1">OPTIONS</A> +<P> +<B>-d</B> +Behave as if each regex had the <B>/D</B> modifier (see below); the internal +form is output after compilation. +</P> +<P> +<B>-i</B> +Behave as if each regex had the <B>/I</B> modifier; information about the +compiled pattern is given after compilation. +</P> +<P> +<B>-m</B> +Output the size of each compiled pattern after it has been compiled. This is +equivalent to adding /M to each regular expression. For compatibility with +earlier versions of pcretest, <B>-s</B> is a synonym for <B>-m</B>. +</P> +<P> +<B>-o</B> <I>osize</I> +Set the number of elements in the output vector that is used when calling PCRE +to be <I>osize</I>. The default value is 45, which is enough for 14 capturing +subexpressions. The vector size can be changed for individual matching calls by +including \O in the data line (see below). +</P> +<P> +<B>-p</B> +Behave as if each regex has <B>/P</B> modifier; the POSIX wrapper API is used +to call PCRE. None of the other options has any effect when <B>-p</B> is set. +</P> +<P> +<B>-t</B> +Run each compile, study, and match 20000 times with a timer, and output +resulting time per compile or match (in milliseconds). Do not set <B>-t</B> with +<B>-m</B>, because you will then get the size output 20000 times and the timing +will be distorted. +</P> +<LI><A NAME="SEC4" HREF="#TOC1">DESCRIPTION</A> +<P> +If <B>pcretest</B> is given two filename arguments, it reads from the first and +writes to the second. If it is given only one filename argument, it reads from +that file and writes to stdout. Otherwise, it reads from stdin and writes to +stdout, and prompts for each line of input, using "re>" to prompt for regular +expressions, and "data>" to prompt for data lines. +</P> +<P> +The program handles any number of sets of input on a single input file. Each +set starts with a regular expression, and continues with any number of data +lines to be matched against the pattern. An empty line signals the end of the +data lines, at which point a new regular expression is read. The regular +expressions are given enclosed in any non-alphameric delimiters other than +backslash, for example +</P> +<P> +<PRE> + /(a|bc)x+yz/ +</PRE> +</P> +<P> +White space before the initial delimiter is ignored. A regular expression may +be continued over several input lines, in which case the newline characters are +included within it. It is possible to include the delimiter within the pattern +by escaping it, for example +</P> +<P> +<PRE> + /abc\/def/ +</PRE> +</P> +<P> +If you do so, the escape and the delimiter form part of the pattern, but since +delimiters are always non-alphameric, this does not affect its interpretation. +If the terminating delimiter is immediately followed by a backslash, for +example, +</P> +<P> +<PRE> + /abc/\ +</PRE> +</P> +<P> +then a backslash is added to the end of the pattern. This is done to provide a +way of testing the error condition that arises if a pattern finishes with a +backslash, because +</P> +<P> +<PRE> + /abc\/ +</PRE> +</P> +<P> +is interpreted as the first line of a pattern that starts with "abc/", causing +pcretest to read the next line as a continuation of the regular expression. +</P> +<LI><A NAME="SEC5" HREF="#TOC1">PATTERN MODIFIERS</A> +<P> +The pattern may be followed by <B>i</B>, <B>m</B>, <B>s</B>, or <B>x</B> to set the +PCRE_CASELESS, PCRE_MULTILINE, PCRE_DOTALL, or PCRE_EXTENDED options, +respectively. For example: +</P> +<P> +<PRE> + /caseless/i +</PRE> +</P> +<P> +These modifier letters have the same effect as they do in Perl. There are +others which set PCRE options that do not correspond to anything in Perl: +<B>/A</B>, <B>/E</B>, and <B>/X</B> set PCRE_ANCHORED, PCRE_DOLLAR_ENDONLY, and +PCRE_EXTRA respectively. +</P> +<P> +Searching for all possible matches within each subject string can be requested +by the <B>/g</B> or <B>/G</B> modifier. After finding a match, PCRE is called +again to search the remainder of the subject string. The difference between +<B>/g</B> and <B>/G</B> is that the former uses the <I>startoffset</I> argument to +<B>pcre_exec()</B> to start searching at a new point within the entire string +(which is in effect what Perl does), whereas the latter passes over a shortened +substring. This makes a difference to the matching process if the pattern +begins with a lookbehind assertion (including \b or \B). +</P> +<P> +If any call to <B>pcre_exec()</B> in a <B>/g</B> or <B>/G</B> sequence matches an +empty string, the next call is done with the PCRE_NOTEMPTY and PCRE_ANCHORED +flags set in order to search for another, non-empty, match at the same point. +If this second match fails, the start offset is advanced by one, and the normal +match is retried. This imitates the way Perl handles such cases when using the +<B>/g</B> modifier or the <B>split()</B> function. +</P> +<P> +There are a number of other modifiers for controlling the way <B>pcretest</B> +operates. +</P> +<P> +The <B>/+</B> modifier requests that as well as outputting the substring that +matched the entire pattern, pcretest should in addition output the remainder of +the subject string. This is useful for tests where the subject contains +multiple copies of the same substring. +</P> +<P> +The <B>/L</B> modifier must be followed directly by the name of a locale, for +example, +</P> +<P> +<PRE> + /pattern/Lfr +</PRE> +</P> +<P> +For this reason, it must be the last modifier letter. The given locale is set, +<B>pcre_maketables()</B> is called to build a set of character tables for the +locale, and this is then passed to <B>pcre_compile()</B> when compiling the +regular expression. Without an <B>/L</B> modifier, NULL is passed as the tables +pointer; that is, <B>/L</B> applies only to the expression on which it appears. +</P> +<P> +The <B>/I</B> modifier requests that <B>pcretest</B> output information about the +compiled expression (whether it is anchored, has a fixed first character, and +so on). It does this by calling <B>pcre_fullinfo()</B> after compiling an +expression, and outputting the information it gets back. If the pattern is +studied, the results of that are also output. +</P> +<P> +The <B>/D</B> modifier is a PCRE debugging feature, which also assumes <B>/I</B>. +It causes the internal form of compiled regular expressions to be output after +compilation. +</P> +<P> +The <B>/S</B> modifier causes <B>pcre_study()</B> to be called after the +expression has been compiled, and the results used when the expression is +matched. +</P> +<P> +The <B>/M</B> modifier causes the size of memory block used to hold the compiled +pattern to be output. +</P> +<P> +The <B>/P</B> modifier causes <B>pcretest</B> to call PCRE via the POSIX wrapper +API rather than its native API. When this is done, all other modifiers except +<B>/i</B>, <B>/m</B>, and <B>/+</B> are ignored. REG_ICASE is set if <B>/i</B> is +present, and REG_NEWLINE is set if <B>/m</B> is present. The wrapper functions +force PCRE_DOLLAR_ENDONLY always, and PCRE_DOTALL unless REG_NEWLINE is set. +</P> +<P> +The <B>/8</B> modifier causes <B>pcretest</B> to call PCRE with the PCRE_UTF8 +option set. This turns on the (currently incomplete) support for UTF-8 +character handling in PCRE, provided that it was compiled with this support +enabled. This modifier also causes any non-printing characters in output +strings to be printed using the \x{hh...} notation if they are valid UTF-8 +sequences. +</P> +<LI><A NAME="SEC6" HREF="#TOC1">DATA LINES</A> +<P> +Before each data line is passed to <B>pcre_exec()</B>, leading and trailing +whitespace is removed, and it is then scanned for \ escapes. The following are +recognized: +</P> +<P> +<PRE> + \a alarm (= BEL) + \b backspace + \e escape + \f formfeed + \n newline + \r carriage return + \t tab + \v vertical tab + \nnn octal character (up to 3 octal digits) + \xhh hexadecimal character (up to 2 hex digits) + \x{hh...} hexadecimal UTF-8 character +</PRE> +</P> +<P> +<PRE> + \A pass the PCRE_ANCHORED option to <B>pcre_exec()</B> + \B pass the PCRE_NOTBOL option to <B>pcre_exec()</B> + \Cdd call pcre_copy_substring() for substring dd + after a successful match (any decimal number + less than 32) + \Gdd call pcre_get_substring() for substring dd + after a successful match (any decimal number + less than 32) + \L call pcre_get_substringlist() after a + successful match + \N pass the PCRE_NOTEMPTY option to <B>pcre_exec()</B> + \Odd set the size of the output vector passed to + <B>pcre_exec()</B> to dd (any number of decimal + digits) + \Z pass the PCRE_NOTEOL option to <B>pcre_exec()</B> +</PRE> +</P> +<P> +When \O is used, it may be higher or lower than the size set by the <B>-O</B> +option (or defaulted to 45); \O applies only to the call of <B>pcre_exec()</B> +for the line in which it appears. +</P> +<P> +A backslash followed by anything else just escapes the anything else. If the +very last character is a backslash, it is ignored. This gives a way of passing +an empty line as data, since a real empty line terminates the data input. +</P> +<P> +If <B>/P</B> was present on the regex, causing the POSIX wrapper API to be used, +only <B>\B</B>, and <B>\Z</B> have any effect, causing REG_NOTBOL and REG_NOTEOL +to be passed to <B>regexec()</B> respectively. +</P> +<P> +The use of \x{hh...} to represent UTF-8 characters is not dependent on the use +of the <B>/8</B> modifier on the pattern. It is recognized always. There may be +any number of hexadecimal digits inside the braces. The result is from one to +six bytes, encoded according to the UTF-8 rules. +</P> +<LI><A NAME="SEC7" HREF="#TOC1">OUTPUT FROM PCRETEST</A> +<P> +When a match succeeds, pcretest outputs the list of captured substrings that +<B>pcre_exec()</B> returns, starting with number 0 for the string that matched +the whole pattern. Here is an example of an interactive pcretest run. +</P> +<P> +<PRE> + $ pcretest + PCRE version 2.06 08-Jun-1999 +</PRE> +</P> +<P> +<PRE> + re> /^abc(\d+)/ + data> abc123 + 0: abc123 + 1: 123 + data> xyz + No match +</PRE> +</P> +<P> +If the strings contain any non-printing characters, they are output as \0x +escapes, or as \x{...} escapes if the <B>/8</B> modifier was present on the +pattern. If the pattern has the <B>/+</B> modifier, then the output for +substring 0 is followed by the the rest of the subject string, identified by +"0+" like this: +</P> +<P> +<PRE> + re> /cat/+ + data> cataract + 0: cat + 0+ aract +</PRE> +</P> +<P> +If the pattern has the <B>/g</B> or <B>/G</B> modifier, the results of successive +matching attempts are output in sequence, like this: +</P> +<P> +<PRE> + re> /\Bi(\w\w)/g + data> Mississippi + 0: iss + 1: ss + 0: iss + 1: ss + 0: ipp + 1: pp +</PRE> +</P> +<P> +"No match" is output only if the first match attempt fails. +</P> +<P> +If any of the sequences <B>\C</B>, <B>\G</B>, or <B>\L</B> are present in a +data line that is successfully matched, the substrings extracted by the +convenience functions are output with C, G, or L after the string number +instead of a colon. This is in addition to the normal full list. The string +length (that is, the return from the extraction function) is given in +parentheses after each string for <B>\C</B> and <B>\G</B>. +</P> +<P> +Note that while patterns can be continued over several lines (a plain ">" +prompt is used for continuations), data lines may not. However newlines can be +included in data by means of the \n escape. +</P> +<LI><A NAME="SEC8" HREF="#TOC1">AUTHOR</A> +<P> +Philip Hazel <ph10@cam.ac.uk> +<BR> +University Computing Service, +<BR> +New Museums Site, +<BR> +Cambridge CB2 3QG, England. +<BR> +Phone: +44 1223 334714 +</P> +<P> +Last updated: 15 August 2001 +<BR> +Copyright (c) 1997-2001 University of Cambridge. diff --git a/srclib/pcre/pcredemo.c b/srclib/pcre/pcredemo.c new file mode 100644 index 0000000000..cb4e46f137 --- /dev/null +++ b/srclib/pcre/pcredemo.c @@ -0,0 +1,94 @@ +#include <stdio.h> +#include <string.h> +#include <pcre.h> + +/* Compile thuswise: + gcc -Wall pcredemo.c -I/opt/local/include -L/opt/local/lib \ + -R/opt/local/lib -lpcre +*/ + +#define OVECCOUNT 30 /* should be a multiple of 3 */ + +int main(int argc, char **argv) +{ +pcre *re; +const char *error; +int erroffset; +int ovector[OVECCOUNT]; +int rc, i; + +if (argc != 3) + { + printf("Two arguments required: a regex and a subject string\n"); + return 1; + } + +/* Compile the regular expression in the first argument */ + +re = pcre_compile( + argv[1], /* the pattern */ + 0, /* default options */ + &error, /* for error message */ + &erroffset, /* for error offset */ + NULL); /* use default character tables */ + +/* Compilation failed: print the error message and exit */ + +if (re == NULL) + { + printf("PCRE compilation failed at offset %d: %s\n", erroffset, error); + return 1; + } + +/* Compilation succeeded: match the subject in the second argument */ + +rc = pcre_exec( + re, /* the compiled pattern */ + NULL, /* no extra data - we didn't study the pattern */ + argv[2], /* the subject string */ + (int)strlen(argv[2]), /* the length of the subject */ + 0, /* start at offset 0 in the subject */ + 0, /* default options */ + ovector, /* output vector for substring information */ + OVECCOUNT); /* number of elements in the output vector */ + +/* Matching failed: handle error cases */ + +if (rc < 0) + { + switch(rc) + { + case PCRE_ERROR_NOMATCH: printf("No match\n"); break; + /* + Handle other special cases if you like + */ + default: printf("Matching error %d\n", rc); break; + } + return 1; + } + +/* Match succeded */ + +printf("Match succeeded\n"); + +/* The output vector wasn't big enough */ + +if (rc == 0) + { + rc = OVECCOUNT/3; + printf("ovector only has room for %d captured substrings\n", rc - 1); + } + +/* Show substrings stored in the output vector */ + +for (i = 0; i < rc; i++) + { + char *substring_start = argv[2] + ovector[2*i]; + int substring_length = ovector[2*i+1] - ovector[2*i]; + printf("%2d: %.*s\n", i, substring_length, substring_start); + } + +return 0; +} + + diff --git a/srclib/pcre/pcregrep.c b/srclib/pcre/pcregrep.c new file mode 100644 index 0000000000..b50ed0780b --- /dev/null +++ b/srclib/pcre/pcregrep.c @@ -0,0 +1,540 @@ +/************************************************* +* pcregrep program * +*************************************************/ + +/* This is a grep program that uses the PCRE regular expression library to do +its pattern matching. On a Unix system it can recurse into directories. */ + +#include <ctype.h> +#include <stdio.h> +#include <string.h> +#include <stdlib.h> +#include <errno.h> +#include "config.h" +#include "pcre.h" + +#define FALSE 0 +#define TRUE 1 + +typedef int BOOL; + +#define VERSION "2.0 01-Aug-2001" +#define MAX_PATTERN_COUNT 100 + + +/************************************************* +* Global variables * +*************************************************/ + +static char *pattern_filename = NULL; +static int pattern_count = 0; +static pcre **pattern_list; +static pcre_extra **hints_list; + +static BOOL count_only = FALSE; +static BOOL filenames = TRUE; +static BOOL filenames_only = FALSE; +static BOOL invert = FALSE; +static BOOL number = FALSE; +static BOOL recurse = FALSE; +static BOOL silent = FALSE; +static BOOL whole_lines = FALSE; + +/* Structure for options and list of them */ + +typedef struct option_item { + int one_char; + char *long_name; + char *help_text; +} option_item; + +static option_item optionlist[] = { + { -1, "help", "display this help and exit" }, + { 'c', "count", "print only a count of matching lines per FILE" }, + { 'h', "no-filename", "suppress the prefixing filename on output" }, + { 'i', "ignore-case", "ignore case distinctions" }, + { 'l', "files-with-matches", "print only FILE names containing matches" }, + { 'n', "line-number", "print line number with output lines" }, + { 'r', "recursive", "recursively scan sub-directories" }, + { 's', "no-messages", "suppress error messages" }, + { 'V', "version", "print version information and exit" }, + { 'v', "invert-match", "select non-matching lines" }, + { 'x', "line-regex", "force PATTERN to match only whole lines" }, + { 'x', "line-regexp", "force PATTERN to match only whole lines" }, + { 0, NULL, NULL } +}; + + +/************************************************* +* Functions for directory scanning * +*************************************************/ + +/* These functions are defined so that they can be made system specific, +although at present the only ones are for Unix, and for "no directory recursion +support". */ + + +/************* Directory scanning in Unix ***********/ + +#if IS_UNIX +#include <sys/types.h> +#include <sys/stat.h> +#include <dirent.h> + +typedef DIR directory_type; + +int +isdirectory(char *filename) +{ +struct stat statbuf; +if (stat(filename, &statbuf) < 0) + return 0; /* In the expectation that opening as a file will fail */ +return ((statbuf.st_mode & S_IFMT) == S_IFDIR)? '/' : 0; +} + +directory_type * +opendirectory(char *filename) +{ +return opendir(filename); +} + +char * +readdirectory(directory_type *dir) +{ +for (;;) + { + struct dirent *dent = readdir(dir); + if (dent == NULL) return NULL; + if (strcmp(dent->d_name, ".") != 0 && strcmp(dent->d_name, "..") != 0) + return dent->d_name; + } +return NULL; /* Keep compiler happy; never executed */ +} + +void +closedirectory(directory_type *dir) +{ +closedir(dir); +} + + +#else + + +/************* Directory scanning when we can't do it ***********/ + +/* The type is void, and apart from isdirectory(), the functions do nothing. */ + +typedef void directory_type; + +int isdirectory(char *filename) { return FALSE; } +directory_type * opendirectory(char *filename) {} +char *readdirectory(directory_type *dir) {} +void closedirectory(directory_type *dir) {} + +#endif + + + +#if ! HAVE_STRERROR +/************************************************* +* Provide strerror() for non-ANSI libraries * +*************************************************/ + +/* Some old-fashioned systems still around (e.g. SunOS4) don't have strerror() +in their libraries, but can provide the same facility by this simple +alternative function. */ + +extern int sys_nerr; +extern char *sys_errlist[]; + +char * +strerror(int n) +{ +if (n < 0 || n >= sys_nerr) return "unknown error number"; +return sys_errlist[n]; +} +#endif /* HAVE_STRERROR */ + + + +/************************************************* +* Grep an individual file * +*************************************************/ + +static int +pcregrep(FILE *in, char *name) +{ +int rc = 1; +int linenumber = 0; +int count = 0; +int offsets[99]; +char buffer[BUFSIZ]; + +while (fgets(buffer, sizeof(buffer), in) != NULL) + { + BOOL match = FALSE; + int i; + int length = (int)strlen(buffer); + if (length > 0 && buffer[length-1] == '\n') buffer[--length] = 0; + linenumber++; + + for (i = 0; !match && i < pattern_count; i++) + { + match = pcre_exec(pattern_list[i], hints_list[i], buffer, length, 0, 0, + offsets, 99) >= 0; + if (match && whole_lines && offsets[1] != length) match = FALSE; + } + + if (match != invert) + { + if (count_only) count++; + + else if (filenames_only) + { + fprintf(stdout, "%s\n", (name == NULL)? "<stdin>" : name); + return 0; + } + + else if (silent) return 0; + + else + { + if (name != NULL) fprintf(stdout, "%s:", name); + if (number) fprintf(stdout, "%d:", linenumber); + fprintf(stdout, "%s\n", buffer); + } + + rc = 0; + } + } + +if (count_only) + { + if (name != NULL) fprintf(stdout, "%s:", name); + fprintf(stdout, "%d\n", count); + } + +return rc; +} + + + + +/************************************************* +* Grep a file or recurse into a directory * +*************************************************/ + +static int +grep_or_recurse(char *filename, BOOL recurse, BOOL show_filenames, + BOOL only_one_at_top) +{ +int rc = 1; +int sep; +FILE *in; + +/* If the file is a directory and we are recursing, scan each file within it. +The scanning code is localized so it can be made system-specific. */ + +if ((sep = isdirectory(filename)) != 0 && recurse) + { + char buffer[1024]; + char *nextfile; + directory_type *dir = opendirectory(filename); + + if (dir == NULL) + { + fprintf(stderr, "pcregrep: Failed to open directory %s: %s\n", filename, + strerror(errno)); + return 2; + } + + while ((nextfile = readdirectory(dir)) != NULL) + { + int frc; + sprintf(buffer, "%.512s%c%.128s", filename, sep, nextfile); + frc = grep_or_recurse(buffer, recurse, TRUE, FALSE); + if (frc == 0 && rc == 1) rc = 0; + } + + closedirectory(dir); + return rc; + } + +/* If the file is not a directory, or we are not recursing, scan it. If this is +the first and only argument at top level, we don't show the file name. +Otherwise, control is via the show_filenames variable. */ + +in = fopen(filename, "r"); +if (in == NULL) + { + fprintf(stderr, "pcregrep: Failed to open %s: %s\n", filename, strerror(errno)); + return 2; + } + +rc = pcregrep(in, (show_filenames && !only_one_at_top)? filename : NULL); +fclose(in); +return rc; +} + + + + +/************************************************* +* Usage function * +*************************************************/ + +static int +usage(int rc) +{ +fprintf(stderr, "Usage: pcregrep [-Vcfhilnrsvx] [long-options] pattern [file] ...\n"); +fprintf(stderr, "Type `pcregrep --help' for more information.\n"); +return rc; +} + + + + +/************************************************* +* Help function * +*************************************************/ + +static void +help(void) +{ +option_item *op; + +printf("Usage: pcregrep [OPTION]... PATTERN [FILE] ...\n"); +printf("Search for PATTERN in each FILE or standard input.\n"); +printf("Example: pcregrep -i 'hello.*world' menu.h main.c\n\n"); + +printf("Options:\n"); + +for (op = optionlist; op->one_char != 0; op++) + { + int n; + char s[4]; + if (op->one_char > 0) sprintf(s, "-%c,", op->one_char); else strcpy(s, " "); + printf(" %s --%s%n", s, op->long_name, &n); + n = 30 - n; + if (n < 1) n = 1; + printf("%.*s%s\n", n, " ", op->help_text); + } + +printf("\n -f<filename> or --file=<filename>\n"); +printf(" Read patterns from <filename> instead of using a command line option.\n"); +printf(" Trailing white space is removed; blanks lines are ignored.\n"); +printf(" There is a maximum of %d patterns.\n", MAX_PATTERN_COUNT); + +printf("\nWith no FILE, read standard input. If fewer than two FILEs given, assume -h.\n"); +printf("Exit status is 0 if any matches, 1 if no matches, and 2 if trouble.\n"); +} + + + + +/************************************************* +* Handle an option * +*************************************************/ + +static int +handle_option(int letter, int options) +{ +switch(letter) + { + case -1: help(); exit(0); + case 'c': count_only = TRUE; break; + case 'h': filenames = FALSE; break; + case 'i': options |= PCRE_CASELESS; break; + case 'l': filenames_only = TRUE; + case 'n': number = TRUE; break; + case 'r': recurse = TRUE; break; + case 's': silent = TRUE; break; + case 'v': invert = TRUE; break; + case 'x': whole_lines = TRUE; options |= PCRE_ANCHORED; break; + + case 'V': + fprintf(stderr, "pcregrep version %s using ", VERSION); + fprintf(stderr, "PCRE version %s\n", pcre_version()); + exit(0); + break; + + default: + fprintf(stderr, "pcregrep: Unknown option -%c\n", letter); + exit(usage(2)); + } + +return options; +} + + + + +/************************************************* +* Main program * +*************************************************/ + +int +main(int argc, char **argv) +{ +int i, j; +int rc = 1; +int options = 0; +int errptr; +const char *error; +BOOL only_one_at_top; + +/* Process the options */ + +for (i = 1; i < argc; i++) + { + if (argv[i][0] != '-') break; + + /* Long name options */ + + if (argv[i][1] == '-') + { + option_item *op; + + if (strncmp(argv[i]+2, "file=", 5) == 0) + { + pattern_filename = argv[i] + 7; + continue; + } + + for (op = optionlist; op->one_char != 0; op++) + { + if (strcmp(argv[i]+2, op->long_name) == 0) + { + options = handle_option(op->one_char, options); + break; + } + } + if (op->one_char == 0) + { + fprintf(stderr, "pcregrep: Unknown option %s\n", argv[i]); + exit(usage(2)); + } + } + + /* One-char options */ + + else + { + char *s = argv[i] + 1; + while (*s != 0) + { + if (*s == 'f') + { + pattern_filename = s + 1; + if (pattern_filename[0] == 0) + { + if (i >= argc - 1) + { + fprintf(stderr, "pcregrep: File name missing after -f\n"); + exit(usage(2)); + } + pattern_filename = argv[++i]; + } + break; + } + else options = handle_option(*s++, options); + } + } + } + +pattern_list = malloc(MAX_PATTERN_COUNT * sizeof(pcre *)); +hints_list = malloc(MAX_PATTERN_COUNT * sizeof(pcre_extra *)); + +if (pattern_list == NULL || hints_list == NULL) + { + fprintf(stderr, "pcregrep: malloc failed\n"); + return 2; + } + +/* Compile the regular expression(s). */ + +if (pattern_filename != NULL) + { + FILE *f = fopen(pattern_filename, "r"); + char buffer[BUFSIZ]; + if (f == NULL) + { + fprintf(stderr, "pcregrep: Failed to open %s: %s\n", pattern_filename, + strerror(errno)); + return 2; + } + while (fgets(buffer, sizeof(buffer), f) != NULL) + { + char *s = buffer + (int)strlen(buffer); + if (pattern_count >= MAX_PATTERN_COUNT) + { + fprintf(stderr, "pcregrep: Too many patterns in file (max %d)\n", + MAX_PATTERN_COUNT); + return 2; + } + while (s > buffer && isspace((unsigned char)(s[-1]))) s--; + if (s == buffer) continue; + *s = 0; + pattern_list[pattern_count] = pcre_compile(buffer, options, &error, + &errptr, NULL); + if (pattern_list[pattern_count++] == NULL) + { + fprintf(stderr, "pcregrep: Error in regex number %d at offset %d: %s\n", + pattern_count, errptr, error); + return 2; + } + } + fclose(f); + } + +/* If no file name, a single regex must be given inline */ + +else + { + if (i >= argc) return usage(0); + pattern_list[0] = pcre_compile(argv[i++], options, &error, &errptr, NULL); + if (pattern_list[0] == NULL) + { + fprintf(stderr, "pcregrep: Error in regex at offset %d: %s\n", errptr, + error); + return 2; + } + pattern_count++; + } + +/* Study the regular expressions, as we will be running them may times */ + +for (j = 0; j < pattern_count; j++) + { + hints_list[j] = pcre_study(pattern_list[j], 0, &error); + if (error != NULL) + { + char s[16]; + if (pattern_count == 1) s[0] = 0; else sprintf(s, " number %d", j); + fprintf(stderr, "pcregrep: Error while studying regex%s: %s\n", s, error); + return 2; + } + } + +/* If there are no further arguments, do the business on stdin and exit */ + +if (i >= argc) return pcregrep(stdin, NULL); + +/* Otherwise, work through the remaining arguments as files or directories. +Pass in the fact that there is only one argument at top level - this suppresses +the file name if the argument is not a directory. */ + +only_one_at_top = (i == argc - 1); +if (filenames_only) filenames = TRUE; + +for (; i < argc; i++) + { + int frc = grep_or_recurse(argv[i], recurse, filenames, only_one_at_top); + if (frc == 0 && rc == 1) rc = 0; + } + +return rc; +} + +/* End */ diff --git a/srclib/pcre/perltest8 b/srclib/pcre/perltest8 new file mode 100755 index 0000000000..2fe522d60d --- /dev/null +++ b/srclib/pcre/perltest8 @@ -0,0 +1,208 @@ +#! /usr/bin/perl + +# Program for testing regular expressions with perl to check that PCRE handles +# them the same. This is the version that supports /8 for UTF-8 testing. It +# requires at least Perl 5.6. + + +# Function for turning a string into a string of printing chars. There are +# currently problems with UTF-8 strings; this fudges round them. + +sub pchars { +my($t) = ""; + +if ($utf8) + { + use utf8; + @p = unpack('U*', $_[0]); + foreach $c (@p) + { + if ($c >= 32 && $c < 127) { $t .= chr $c; } + else { $t .= sprintf("\\x{%02x}", $c); } + } + } + +else + { + foreach $c (split(//, $_[0])) + { + if (ord $c >= 32 && ord $c < 127) { $t .= $c; } + else { $t .= sprintf("\\x%02x", ord $c); } + } + } + +$t; +} + + + +# Read lines from named file or stdin and write to named file or stdout; lines +# consist of a regular expression, in delimiters and optionally followed by +# options, followed by a set of test data, terminated by an empty line. + +# Sort out the input and output files + +if (@ARGV > 0) + { + open(INFILE, "<$ARGV[0]") || die "Failed to open $ARGV[0]\n"; + $infile = "INFILE"; + } +else { $infile = "STDIN"; } + +if (@ARGV > 1) + { + open(OUTFILE, ">$ARGV[1]") || die "Failed to open $ARGV[1]\n"; + $outfile = "OUTFILE"; + } +else { $outfile = "STDOUT"; } + +printf($outfile "Perl $] Regular Expressions\n\n"); + +# Main loop + +NEXT_RE: +for (;;) + { + printf " re> " if $infile eq "STDIN"; + last if ! ($_ = <$infile>); + printf $outfile "$_" if $infile ne "STDIN"; + next if ($_ eq ""); + + $pattern = $_; + + while ($pattern !~ /^\s*(.).*\1/s) + { + printf " > " if $infile eq "STDIN"; + last if ! ($_ = <$infile>); + printf $outfile "$_" if $infile ne "STDIN"; + $pattern .= $_; + } + + chomp($pattern); + $pattern =~ s/\s+$//; + + # The private /+ modifier means "print $' afterwards". + + $showrest = ($pattern =~ s/\+(?=[a-z]*$)//); + + # The private /8 modifier means "operate in UTF-8". Currently, Perl + # has bugs that we try to work around using this flag. + + $utf8 = ($pattern =~ s/8(?=[a-z]*$)//); + + # Check that the pattern is valid + + if ($utf8) + { + use utf8; + eval "\$_ =~ ${pattern}"; + } + else + { + eval "\$_ =~ ${pattern}"; + } + + if ($@) + { + printf $outfile "Error: $@"; + next NEXT_RE; + } + + # If the /g modifier is present, we want to put a loop round the matching; + # otherwise just a single "if". + + $cmd = ($pattern =~ /g[a-z]*$/)? "while" : "if"; + + # If the pattern is actually the null string, Perl uses the most recently + # executed (and successfully compiled) regex is used instead. This is a + # nasty trap for the unwary! The PCRE test suite does contain null strings + # in places - if they are allowed through here all sorts of weird and + # unexpected effects happen. To avoid this, we replace such patterns with + # a non-null pattern that has the same effect. + + $pattern = "/(?#)/$2" if ($pattern =~ /^(.)\1(.*)$/); + + # Read data lines and test them + + for (;;) + { + printf "data> " if $infile eq "STDIN"; + last NEXT_RE if ! ($_ = <$infile>); + chomp; + printf $outfile "$_\n" if $infile ne "STDIN"; + + s/\s+$//; + s/^\s+//; + + last if ($_ eq ""); + + $x = eval "\"$_\""; # To get escapes processed + + # Empty array for holding results, then do the matching. + + @subs = (); + + $pushes = "push \@subs,\$&;" . + "push \@subs,\$1;" . + "push \@subs,\$2;" . + "push \@subs,\$3;" . + "push \@subs,\$4;" . + "push \@subs,\$5;" . + "push \@subs,\$6;" . + "push \@subs,\$7;" . + "push \@subs,\$8;" . + "push \@subs,\$9;" . + "push \@subs,\$10;" . + "push \@subs,\$11;" . + "push \@subs,\$12;" . + "push \@subs,\$13;" . + "push \@subs,\$14;" . + "push \@subs,\$15;" . + "push \@subs,\$16;" . + "push \@subs,\$'; }"; + + if ($utf8) + { + use utf8; + eval "${cmd} (\$x =~ ${pattern}) {" . $pushes; + } + else + { + eval "${cmd} (\$x =~ ${pattern}) {" . $pushes; + } + + if ($@) + { + printf $outfile "Error: $@\n"; + next NEXT_RE; + } + elsif (scalar(@subs) == 0) + { + printf $outfile "No match\n"; + } + else + { + while (scalar(@subs) != 0) + { + printf $outfile (" 0: %s\n", &pchars($subs[0])); + printf $outfile (" 0+ %s\n", &pchars($subs[17])) if $showrest; + $last_printed = 0; + for ($i = 1; $i <= 16; $i++) + { + if (defined $subs[$i]) + { + while ($last_printed++ < $i-1) + { printf $outfile ("%2d: <unset>\n", $last_printed); } + printf $outfile ("%2d: %s\n", $i, &pchars($subs[$i])); + $last_printed = $i; + } + } + splice(@subs, 0, 18); + } + } + } + } + +printf $outfile "\n"; + +# End diff --git a/srclib/pcre/testdata/testinput5 b/srclib/pcre/testdata/testinput5 new file mode 100644 index 0000000000..d66cfbddf3 --- /dev/null +++ b/srclib/pcre/testdata/testinput5 @@ -0,0 +1,118 @@ +/-- Because of problems with Perl 5.6 in handling UTF-8 vs non UTF-8 --/ +/-- strings automatically, do not use the \x{} construct except with --/ +/-- patterns that have the /8 option set, and don't use them without! --/ + +/a.b/8 + acb + a\x7fb + a\x{100}b + *** Failers + a\nb + +/a(.{3})b/8 + a\x{4000}xyb + a\x{4000}\x7fyb + a\x{4000}\x{100}yb + *** Failers + a\x{4000}b + ac\ncb + +/a(.*?)(.)/ + a\xc0\x88b + +/a(.*?)(.)/8 + a\x{100}b + +/a(.*)(.)/ + a\xc0\x88b + +/a(.*)(.)/8 + a\x{100}b + +/a(.)(.)/ + a\xc0\x92bcd + +/a(.)(.)/8 + a\x{240}bcd + +/a(.?)(.)/ + a\xc0\x92bcd + +/a(.?)(.)/8 + a\x{240}bcd + +/a(.??)(.)/ + a\xc0\x92bcd + +/a(.??)(.)/8 + a\x{240}bcd + +/a(.{3})b/8 + a\x{1234}xyb + a\x{1234}\x{4321}yb + a\x{1234}\x{4321}\x{3412}b + *** Failers + a\x{1234}b + ac\ncb + +/a(.{3,})b/8 + a\x{1234}xyb + a\x{1234}\x{4321}yb + a\x{1234}\x{4321}\x{3412}b + axxxxbcdefghijb + a\x{1234}\x{4321}\x{3412}\x{3421}b + *** Failers + a\x{1234}b + +/a(.{3,}?)b/8 + a\x{1234}xyb + a\x{1234}\x{4321}yb + a\x{1234}\x{4321}\x{3412}b + axxxxbcdefghijb + a\x{1234}\x{4321}\x{3412}\x{3421}b + *** Failers + a\x{1234}b + +/a(.{3,5})b/8 + a\x{1234}xyb + a\x{1234}\x{4321}yb + a\x{1234}\x{4321}\x{3412}b + axxxxbcdefghijb + a\x{1234}\x{4321}\x{3412}\x{3421}b + axbxxbcdefghijb + axxxxxbcdefghijb + *** Failers + a\x{1234}b + axxxxxxbcdefghijb + +/a(.{3,5}?)b/8 + a\x{1234}xyb + a\x{1234}\x{4321}yb + a\x{1234}\x{4321}\x{3412}b + axxxxbcdefghijb + a\x{1234}\x{4321}\x{3412}\x{3421}b + axbxxbcdefghijb + axxxxxbcdefghijb + *** Failers + a\x{1234}b + axxxxxxbcdefghijb + +/^[a\x{c0}]/8 + *** Failers + \x{100} + +/(?<=aXb)cd/8 + aXbcd + +/(?<=a\x{100}b)cd/8 + a\x{100}bcd + +/(?<=a\x{100000}b)cd/8 + a\x{100000}bcd + +/(?:\x{100}){3}b/8 + \x{100}\x{100}\x{100}b + *** Failers + \x{100}\x{100}b + +/ End of testinput5 / diff --git a/srclib/pcre/testdata/testinput6 b/srclib/pcre/testdata/testinput6 new file mode 100644 index 0000000000..00748513c6 --- /dev/null +++ b/srclib/pcre/testdata/testinput6 @@ -0,0 +1,78 @@ +/\x{100}/8DM + +/\x{1000}/8DM + +/\x{10000}/8DM + +/\x{100000}/8DM + +/\x{1000000}/8DM + +/\x{4000000}/8DM + +/\x{7fffFFFF}/8DM + +/[\x{ff}]/8DM + +/[\x{100}]/8DM + +/\x{ffffffff}/8 + +/\x{100000000}/8 + +/^\x{100}a\x{1234}/8 + \x{100}a\x{1234}bcd + +/\x80/8D + +/\xff/8D + +/\x{0041}\x{2262}\x{0391}\x{002e}/D8 + \x{0041}\x{2262}\x{0391}\x{002e} + +/\x{D55c}\x{ad6d}\x{C5B4}/D8 + \x{D55c}\x{ad6d}\x{C5B4} + +/\x{65e5}\x{672c}\x{8a9e}/D8 + \x{65e5}\x{672c}\x{8a9e} + +/\x{80}/D8 + +/\x{084}/D8 + +/\x{104}/D8 + +/\x{861}/D8 + +/\x{212ab}/D8 + +/.{3,5}X/D8 + \x{212ab}\x{212ab}\x{212ab}\x{861}X + + +/.{3,5}?/D8 + \x{212ab}\x{212ab}\x{212ab}\x{861} + +/-- These tests are here rather than in testinput5 because Perl 5.6 has --/ +/-- some problems with UTF-8 support, in the area of \x{..} where the --/ +/-- value is < 255. It grumbles about invalid UTF-8 strings. --/ + +/^[a\x{c0}]b/8 + \x{c0}b + +/^([a\x{c0}]*?)aa/8 + a\x{c0}aaaa/ + +/^([a\x{c0}]*?)aa/8 + a\x{c0}aaaa/ + a\x{c0}a\x{c0}aaa/ + +/^([a\x{c0}]*)aa/8 + a\x{c0}aaaa/ + a\x{c0}a\x{c0}aaa/ + +/^([a\x{c0}]*)a\x{c0}/8 + a\x{c0}aaaa/ + a\x{c0}a\x{c0}aaa/ + +/ End of testinput6 / diff --git a/srclib/pcre/testdata/testoutput5 b/srclib/pcre/testdata/testoutput5 new file mode 100644 index 0000000000..6bb9ad31b4 --- /dev/null +++ b/srclib/pcre/testdata/testoutput5 @@ -0,0 +1,242 @@ +PCRE version 3.9 02-Jan-2002 + +/-- Because of problems with Perl 5.6 in handling UTF-8 vs non UTF-8 --/ +/-- strings automatically, do not use the \x{} construct except with --/ +No match +/-- patterns that have the /8 option set, and don't use them without! --/ +No match + +/a.b/8 + acb + 0: acb + a\x7fb + 0: a\x{7f}b + a\x{100}b + 0: a\x{100}b + *** Failers +No match + a\nb +No match + +/a(.{3})b/8 + a\x{4000}xyb + 0: a\x{4000}xyb + 1: \x{4000}xy + a\x{4000}\x7fyb + 0: a\x{4000}\x{7f}yb + 1: \x{4000}\x{7f}y + a\x{4000}\x{100}yb + 0: a\x{4000}\x{100}yb + 1: \x{4000}\x{100}y + *** Failers +No match + a\x{4000}b +No match + ac\ncb +No match + +/a(.*?)(.)/ + a\xc0\x88b + 0: a\xc0 + 1: + 2: \xc0 + +/a(.*?)(.)/8 + a\x{100}b + 0: a\x{100} + 1: + 2: \x{100} + +/a(.*)(.)/ + a\xc0\x88b + 0: a\xc0\x88b + 1: \xc0\x88 + 2: b + +/a(.*)(.)/8 + a\x{100}b + 0: a\x{100}b + 1: \x{100} + 2: b + +/a(.)(.)/ + a\xc0\x92bcd + 0: a\xc0\x92 + 1: \xc0 + 2: \x92 + +/a(.)(.)/8 + a\x{240}bcd + 0: a\x{240}b + 1: \x{240} + 2: b + +/a(.?)(.)/ + a\xc0\x92bcd + 0: a\xc0\x92 + 1: \xc0 + 2: \x92 + +/a(.?)(.)/8 + a\x{240}bcd + 0: a\x{240}b + 1: \x{240} + 2: b + +/a(.??)(.)/ + a\xc0\x92bcd + 0: a\xc0 + 1: + 2: \xc0 + +/a(.??)(.)/8 + a\x{240}bcd + 0: a\x{240} + 1: + 2: \x{240} + +/a(.{3})b/8 + a\x{1234}xyb + 0: a\x{1234}xyb + 1: \x{1234}xy + a\x{1234}\x{4321}yb + 0: a\x{1234}\x{4321}yb + 1: \x{1234}\x{4321}y + a\x{1234}\x{4321}\x{3412}b + 0: a\x{1234}\x{4321}\x{3412}b + 1: \x{1234}\x{4321}\x{3412} + *** Failers +No match + a\x{1234}b +No match + ac\ncb +No match + +/a(.{3,})b/8 + a\x{1234}xyb + 0: a\x{1234}xyb + 1: \x{1234}xy + a\x{1234}\x{4321}yb + 0: a\x{1234}\x{4321}yb + 1: \x{1234}\x{4321}y + a\x{1234}\x{4321}\x{3412}b + 0: a\x{1234}\x{4321}\x{3412}b + 1: \x{1234}\x{4321}\x{3412} + axxxxbcdefghijb + 0: axxxxbcdefghijb + 1: xxxxbcdefghij + a\x{1234}\x{4321}\x{3412}\x{3421}b + 0: a\x{1234}\x{4321}\x{3412}\x{3421}b + 1: \x{1234}\x{4321}\x{3412}\x{3421} + *** Failers +No match + a\x{1234}b +No match + +/a(.{3,}?)b/8 + a\x{1234}xyb + 0: a\x{1234}xyb + 1: \x{1234}xy + a\x{1234}\x{4321}yb + 0: a\x{1234}\x{4321}yb + 1: \x{1234}\x{4321}y + a\x{1234}\x{4321}\x{3412}b + 0: a\x{1234}\x{4321}\x{3412}b + 1: \x{1234}\x{4321}\x{3412} + axxxxbcdefghijb + 0: axxxxb + 1: xxxx + a\x{1234}\x{4321}\x{3412}\x{3421}b + 0: a\x{1234}\x{4321}\x{3412}\x{3421}b + 1: \x{1234}\x{4321}\x{3412}\x{3421} + *** Failers +No match + a\x{1234}b +No match + +/a(.{3,5})b/8 + a\x{1234}xyb + 0: a\x{1234}xyb + 1: \x{1234}xy + a\x{1234}\x{4321}yb + 0: a\x{1234}\x{4321}yb + 1: \x{1234}\x{4321}y + a\x{1234}\x{4321}\x{3412}b + 0: a\x{1234}\x{4321}\x{3412}b + 1: \x{1234}\x{4321}\x{3412} + axxxxbcdefghijb + 0: axxxxb + 1: xxxx + a\x{1234}\x{4321}\x{3412}\x{3421}b + 0: a\x{1234}\x{4321}\x{3412}\x{3421}b + 1: \x{1234}\x{4321}\x{3412}\x{3421} + axbxxbcdefghijb + 0: axbxxb + 1: xbxx + axxxxxbcdefghijb + 0: axxxxxb + 1: xxxxx + *** Failers +No match + a\x{1234}b +No match + axxxxxxbcdefghijb +No match + +/a(.{3,5}?)b/8 + a\x{1234}xyb + 0: a\x{1234}xyb + 1: \x{1234}xy + a\x{1234}\x{4321}yb + 0: a\x{1234}\x{4321}yb + 1: \x{1234}\x{4321}y + a\x{1234}\x{4321}\x{3412}b + 0: a\x{1234}\x{4321}\x{3412}b + 1: \x{1234}\x{4321}\x{3412} + axxxxbcdefghijb + 0: axxxxb + 1: xxxx + a\x{1234}\x{4321}\x{3412}\x{3421}b + 0: a\x{1234}\x{4321}\x{3412}\x{3421}b + 1: \x{1234}\x{4321}\x{3412}\x{3421} + axbxxbcdefghijb + 0: axbxxb + 1: xbxx + axxxxxbcdefghijb + 0: axxxxxb + 1: xxxxx + *** Failers +No match + a\x{1234}b +No match + axxxxxxbcdefghijb +No match + +/^[a\x{c0}]/8 + *** Failers +No match + \x{100} +No match + +/(?<=aXb)cd/8 + aXbcd + 0: cd + +/(?<=a\x{100}b)cd/8 + a\x{100}bcd + 0: cd + +/(?<=a\x{100000}b)cd/8 + a\x{100000}bcd + 0: cd + +/(?:\x{100}){3}b/8 + \x{100}\x{100}\x{100}b + 0: \x{100}\x{100}\x{100}b + *** Failers +No match + \x{100}\x{100}b +No match + +/ End of testinput5 / + diff --git a/srclib/pcre/testdata/testoutput6 b/srclib/pcre/testdata/testoutput6 new file mode 100644 index 0000000000..fcf084670f --- /dev/null +++ b/srclib/pcre/testdata/testoutput6 @@ -0,0 +1,319 @@ +PCRE version 3.9 02-Jan-2002 + +/\x{100}/8DM +Memory allocation (code space): 11 +------------------------------------------------------------------ + 0 7 Bra 0 + 3 2 \xc4\x80 + 7 7 Ket + 10 End +------------------------------------------------------------------ +Capturing subpattern count = 0 +Options: utf8 +First char = 196 +Need char = 128 + +/\x{1000}/8DM +Memory allocation (code space): 12 +------------------------------------------------------------------ + 0 8 Bra 0 + 3 3 \xe1\x80\x80 + 8 8 Ket + 11 End +------------------------------------------------------------------ +Capturing subpattern count = 0 +Options: utf8 +First char = 225 +Need char = 128 + +/\x{10000}/8DM +Memory allocation (code space): 13 +------------------------------------------------------------------ + 0 9 Bra 0 + 3 4 \xf0\x90\x80\x80 + 9 9 Ket + 12 End +------------------------------------------------------------------ +Capturing subpattern count = 0 +Options: utf8 +First char = 240 +Need char = 128 + +/\x{100000}/8DM +Memory allocation (code space): 13 +------------------------------------------------------------------ + 0 9 Bra 0 + 3 4 \xf4\x80\x80\x80 + 9 9 Ket + 12 End +------------------------------------------------------------------ +Capturing subpattern count = 0 +Options: utf8 +First char = 244 +Need char = 128 + +/\x{1000000}/8DM +Memory allocation (code space): 14 +------------------------------------------------------------------ + 0 10 Bra 0 + 3 5 \xf9\x80\x80\x80\x80 + 10 10 Ket + 13 End +------------------------------------------------------------------ +Capturing subpattern count = 0 +Options: utf8 +First char = 249 +Need char = 128 + +/\x{4000000}/8DM +Memory allocation (code space): 15 +------------------------------------------------------------------ + 0 11 Bra 0 + 3 6 \xfc\x84\x80\x80\x80\x80 + 11 11 Ket + 14 End +------------------------------------------------------------------ +Capturing subpattern count = 0 +Options: utf8 +First char = 252 +Need char = 128 + +/\x{7fffFFFF}/8DM +Memory allocation (code space): 15 +------------------------------------------------------------------ + 0 11 Bra 0 + 3 6 \xfd\xbf\xbf\xbf\xbf\xbf + 11 11 Ket + 14 End +------------------------------------------------------------------ +Capturing subpattern count = 0 +Options: utf8 +First char = 253 +Need char = 191 + +/[\x{ff}]/8DM +Memory allocation (code space): 40 +------------------------------------------------------------------ + 0 6 Bra 0 + 3 1 \xff + 6 6 Ket + 9 End +------------------------------------------------------------------ +Capturing subpattern count = 0 +Options: utf8 +First char = 255 +No need char + +/[\x{100}]/8DM +Memory allocation (code space): 40 +Failed: characters with values > 255 are not yet supported in classes at offset 7 + +/\x{ffffffff}/8 +Failed: character value in \x{...} sequence is too large at offset 11 + +/\x{100000000}/8 +Failed: character value in \x{...} sequence is too large at offset 12 + +/^\x{100}a\x{1234}/8 + \x{100}a\x{1234}bcd + 0: \x{100}a\x{1234} + +/\x80/8D +------------------------------------------------------------------ + 0 7 Bra 0 + 3 2 \xc2\x80 + 7 7 Ket + 10 End +------------------------------------------------------------------ +Capturing subpattern count = 0 +Options: utf8 +First char = 194 +Need char = 128 + +/\xff/8D +------------------------------------------------------------------ + 0 7 Bra 0 + 3 2 \xc3\xbf + 7 7 Ket + 10 End +------------------------------------------------------------------ +Capturing subpattern count = 0 +Options: utf8 +First char = 195 +Need char = 191 + +/\x{0041}\x{2262}\x{0391}\x{002e}/D8 +------------------------------------------------------------------ + 0 12 Bra 0 + 3 7 A\xe2\x89\xa2\xce\x91. + 12 12 Ket + 15 End +------------------------------------------------------------------ +Capturing subpattern count = 0 +Options: utf8 +First char = 'A' +Need char = '.' + \x{0041}\x{2262}\x{0391}\x{002e} + 0: A\x{2262}\x{391}. + +/\x{D55c}\x{ad6d}\x{C5B4}/D8 +------------------------------------------------------------------ + 0 14 Bra 0 + 3 9 \xed\x95\x9c\xea\xb5\xad\xec\x96\xb4 + 14 14 Ket + 17 End +------------------------------------------------------------------ +Capturing subpattern count = 0 +Options: utf8 +First char = 237 +Need char = 180 + \x{D55c}\x{ad6d}\x{C5B4} + 0: \x{d55c}\x{ad6d}\x{c5b4} + +/\x{65e5}\x{672c}\x{8a9e}/D8 +------------------------------------------------------------------ + 0 14 Bra 0 + 3 9 \xe6\x97\xa5\xe6\x9c\xac\xe8\xaa\x9e + 14 14 Ket + 17 End +------------------------------------------------------------------ +Capturing subpattern count = 0 +Options: utf8 +First char = 230 +Need char = 158 + \x{65e5}\x{672c}\x{8a9e} + 0: \x{65e5}\x{672c}\x{8a9e} + +/\x{80}/D8 +------------------------------------------------------------------ + 0 7 Bra 0 + 3 2 \xc2\x80 + 7 7 Ket + 10 End +------------------------------------------------------------------ +Capturing subpattern count = 0 +Options: utf8 +First char = 194 +Need char = 128 + +/\x{084}/D8 +------------------------------------------------------------------ + 0 7 Bra 0 + 3 2 \xc2\x84 + 7 7 Ket + 10 End +------------------------------------------------------------------ +Capturing subpattern count = 0 +Options: utf8 +First char = 194 +Need char = 132 + +/\x{104}/D8 +------------------------------------------------------------------ + 0 7 Bra 0 + 3 2 \xc4\x84 + 7 7 Ket + 10 End +------------------------------------------------------------------ +Capturing subpattern count = 0 +Options: utf8 +First char = 196 +Need char = 132 + +/\x{861}/D8 +------------------------------------------------------------------ + 0 8 Bra 0 + 3 3 \xe0\xa1\xa1 + 8 8 Ket + 11 End +------------------------------------------------------------------ +Capturing subpattern count = 0 +Options: utf8 +First char = 224 +Need char = 161 + +/\x{212ab}/D8 +------------------------------------------------------------------ + 0 9 Bra 0 + 3 4 \xf0\xa1\x8a\xab + 9 9 Ket + 12 End +------------------------------------------------------------------ +Capturing subpattern count = 0 +Options: utf8 +First char = 240 +Need char = 171 + +/.{3,5}X/D8 +------------------------------------------------------------------ + 0 14 Bra 0 + 3 Any{3} + 7 Any{0,2} + 11 1 X + 14 14 Ket + 17 End +------------------------------------------------------------------ +Capturing subpattern count = 0 +Options: utf8 +No first char +Need char = 'X' + \x{212ab}\x{212ab}\x{212ab}\x{861}X + 0: \x{212ab}\x{212ab}\x{212ab}\x{861}X + + +/.{3,5}?/D8 +------------------------------------------------------------------ + 0 11 Bra 0 + 3 Any{3} + 7 Any{0,2}? + 11 11 Ket + 14 End +------------------------------------------------------------------ +Capturing subpattern count = 0 +Options: utf8 +No first char +No need char + \x{212ab}\x{212ab}\x{212ab}\x{861} + 0: \x{212ab}\x{212ab}\x{212ab} + +/-- These tests are here rather than in testinput5 because Perl 5.6 has --/ +/-- some problems with UTF-8 support, in the area of \x{..} where the --/ +No match +/-- value is < 255. It grumbles about invalid UTF-8 strings. --/ +No match + +/^[a\x{c0}]b/8 + \x{c0}b + 0: \x{c0}b + +/^([a\x{c0}]*?)aa/8 + a\x{c0}aaaa/ + 0: a\x{c0}aa + 1: a\x{c0} + +/^([a\x{c0}]*?)aa/8 + a\x{c0}aaaa/ + 0: a\x{c0}aa + 1: a\x{c0} + a\x{c0}a\x{c0}aaa/ + 0: a\x{c0}a\x{c0}aa + 1: a\x{c0}a\x{c0} + +/^([a\x{c0}]*)aa/8 + a\x{c0}aaaa/ + 0: a\x{c0}aaaa + 1: a\x{c0}aa + a\x{c0}a\x{c0}aaa/ + 0: a\x{c0}a\x{c0}aaa + 1: a\x{c0}a\x{c0}a + +/^([a\x{c0}]*)a\x{c0}/8 + a\x{c0}aaaa/ + 0: a\x{c0} + 1: + a\x{c0}a\x{c0}aaa/ + 0: a\x{c0}a\x{c0} + 1: a\x{c0} + +/ End of testinput6 / + diff --git a/support/NWGNUhtdigest b/support/NWGNUhtdigest new file mode 100644 index 0000000000..1cc1c96295 --- /dev/null +++ b/support/NWGNUhtdigest @@ -0,0 +1,246 @@ +# +# Make sure all needed macro's are defined +# + +# +# Get the 'head' of the build environment if necessary. This includes default +# targets and paths to tools +# + +ifndef EnvironmentDefined +include $(AP_WORK)\build\NWGNUhead.inc +endif + +# +# These directories will be at the beginning of the include list, followed by +# INCDIRS +# +XINCDIRS += \ + $(NWOS) \ + $(AP_WORK)/srclib/apr/include \ + $(AP_WORK)/srclib/apr-util/include \ + $(AP_WORK)/srclib/apr/misc/netware \ + $(AP_WORK)/srclib/apr \ + $(EOLIST) + +# +# These flags will come after CFLAGS +# +XCFLAGS += \ + $(EOLIST) + +# +# These defines will come after DEFINES +# +XDEFINES += \ + $(EOLIST) + +# +# These flags will be added to the link.opt file +# +XLFLAGS += \ + $(EOLIST) + +# +# These values will be appended to the correct variables based on the value of +# RELEASE +# +ifeq "$(RELEASE)" "debug" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "noopt" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "release" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +# +# These are used by the link target if an NLM is being generated +# This is used by the link 'name' directive to name the nlm. If left blank +# TARGET_nlm (see below) will be used. +# +NLM_NAME = htdigest + +# +# This is used by the link '-desc ' directive. +# If left blank, NLM_NAME will be used. +# +NLM_DESCRIPTION = HT Digest Utility for NetWare + +# +# This is used by the '-threadname' directive. If left blank, +# NLM_NAME Thread will be used. +# +NLM_THREAD_NAME = htdigest + +# +# If this is specified, it will override VERSION value in +# $(AP_WORK)\build\NWGNUenvironment.inc +# +NLM_VERSION = + +# +# If this is specified, it will override the default of 64K +# +NLM_STACK_SIZE = 8192 + + +# +# If this is specified it will be used by the link '-entry' directive +# +NLM_ENTRY_SYM = _LibCPrelude + +# +# If this is specified it will be used by the link '-exit' directive +# +NLM_EXIT_SYM = _LibCPostlude + +# +# If this is specified it will be used by the link '-check' directive +# +NLM_CHECK_SYM = + +# +# If these are specified it will be used by the link '-flags' directive +# +NLM_FLAGS = AUTOUNLOAD, PSEUDOPREEMPTION + +# +# If this is specified it will be linked in with the XDCData option in the def +# file instead of the default of $(NWOS)/apache.xdc. XDCData can be disabled +# by setting APACHE_UNIPROC in the environment +# +XDCDATA = + +# +# If there is an NLM target, put it here +# +TARGET_nlm = \ + $(OBJDIR)/htdigest.nlm \ + $(EOLIST) + +# +# If there is an LIB target, put it here +# +TARGET_lib = \ + $(EOLIST) + +# +# These are the OBJ files needed to create the NLM target above. +# Paths must all use the '/' character +# +FILES_nlm_objs = \ + $(OBJDIR)/htdigest.o \ + $(EOLIST) + +# +# These are the LIB files needed to create the NLM target above. +# These will be added as a library command in the link.opt file. +# +FILES_nlm_libs = \ + libcpre.o \ + $(EOLIST) + +# +# These are the modules that the above NLM target depends on to load. +# These will be added as a module command in the link.opt file. +# +FILES_nlm_modules = \ + aprlib \ + libc \ + $(EOLIST) + +# +# If the nlm has a msg file, put it's path here +# +FILE_nlm_msg = + +# +# If the nlm has a hlp file put it's path here +# +FILE_nlm_hlp = + +# +# If this is specified, it will override $(NWOS)\copyright.txt. +# +FILE_nlm_copyright = + +# +# Any additional imports go here +# +FILES_nlm_Ximports = \ + @$(APR)/aprlib.imp \ + @libc.imp \ + $(EOLIST) + +# +# Any symbols exported to here +# +FILES_nlm_exports = \ + $(EOLIST) + +# +# These are the OBJ files needed to create the LIB target above. +# Paths must all use the '/' character +# +FILES_lib_objs = \ + $(EOLIST) + +# +# implement targets and dependancies (leave this section alone) +# + +libs :: $(OBJDIR) $(TARGET_lib) + +nlms :: libs $(TARGET_nlm) + +# +# Updated this target to create necessary directories and copy files to the +# correct place. (See $(AP_WORK)\build\NWGNUhead.inc for examples) +# +install :: nlms FORCE + +# +# Any specialized rules here +# + +# +# Include the 'tail' makefile that has targets that depend on variables defined +# in this makefile +# + +include $(AP_WORK)\build\NWGNUtail.inc + diff --git a/support/NWGNUhtpasswd b/support/NWGNUhtpasswd new file mode 100644 index 0000000000..7000529caa --- /dev/null +++ b/support/NWGNUhtpasswd @@ -0,0 +1,246 @@ +# +# Make sure all needed macro's are defined +# + +# +# Get the 'head' of the build environment if necessary. This includes default +# targets and paths to tools +# + +ifndef EnvironmentDefined +include $(AP_WORK)\build\NWGNUhead.inc +endif + +# +# These directories will be at the beginning of the include list, followed by +# INCDIRS +# +XINCDIRS += \ + $(NWOS) \ + $(AP_WORK)/srclib/apr/include \ + $(AP_WORK)/srclib/apr-util/include \ + $(AP_WORK)/srclib/apr/misc/netware \ + $(AP_WORK)/srclib/apr \ + $(EOLIST) + +# +# These flags will come after CFLAGS +# +XCFLAGS += \ + $(EOLIST) + +# +# These defines will come after DEFINES +# +XDEFINES += \ + $(EOLIST) + +# +# These flags will be added to the link.opt file +# +XLFLAGS += \ + $(EOLIST) + +# +# These values will be appended to the correct variables based on the value of +# RELEASE +# +ifeq "$(RELEASE)" "debug" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "noopt" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "release" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +# +# These are used by the link target if an NLM is being generated +# This is used by the link 'name' directive to name the nlm. If left blank +# TARGET_nlm (see below) will be used. +# +NLM_NAME = htpasswd + +# +# This is used by the link '-desc ' directive. +# If left blank, NLM_NAME will be used. +# +NLM_DESCRIPTION = HT Password Utility for NetWare + +# +# This is used by the '-threadname' directive. If left blank, +# NLM_NAME Thread will be used. +# +NLM_THREAD_NAME = htpasswd + +# +# If this is specified, it will override VERSION value in +# $(AP_WORK)\build\NWGNUenvironment.inc +# +NLM_VERSION = + +# +# If this is specified, it will override the default of 64K +# +NLM_STACK_SIZE = 8192 + + +# +# If this is specified it will be used by the link '-entry' directive +# +NLM_ENTRY_SYM = _LibCPrelude + +# +# If this is specified it will be used by the link '-exit' directive +# +NLM_EXIT_SYM = _LibCPostlude + +# +# If this is specified it will be used by the link '-check' directive +# +NLM_CHECK_SYM = + +# +# If these are specified it will be used by the link '-flags' directive +# +NLM_FLAGS = AUTOUNLOAD, PSEUDOPREEMPTION + +# +# If this is specified it will be linked in with the XDCData option in the def +# file instead of the default of $(NWOS)/apache.xdc. XDCData can be disabled +# by setting APACHE_UNIPROC in the environment +# +XDCDATA = + +# +# If there is an NLM target, put it here +# +TARGET_nlm = \ + $(OBJDIR)/htpasswd.nlm \ + $(EOLIST) + +# +# If there is an LIB target, put it here +# +TARGET_lib = \ + $(EOLIST) + +# +# These are the OBJ files needed to create the NLM target above. +# Paths must all use the '/' character +# +FILES_nlm_objs = \ + $(OBJDIR)/htpasswd.o \ + $(EOLIST) + +# +# These are the LIB files needed to create the NLM target above. +# These will be added as a library command in the link.opt file. +# +FILES_nlm_libs = \ + libcpre.o \ + $(EOLIST) + +# +# These are the modules that the above NLM target depends on to load. +# These will be added as a module command in the link.opt file. +# +FILES_nlm_modules = \ + aprlib \ + libc \ + $(EOLIST) + +# +# If the nlm has a msg file, put it's path here +# +FILE_nlm_msg = + +# +# If the nlm has a hlp file put it's path here +# +FILE_nlm_hlp = + +# +# If this is specified, it will override $(NWOS)\copyright.txt. +# +FILE_nlm_copyright = + +# +# Any additional imports go here +# +FILES_nlm_Ximports = \ + @$(APR)/aprlib.imp \ + @libc.imp \ + $(EOLIST) + +# +# Any symbols exported to here +# +FILES_nlm_exports = \ + $(EOLIST) + +# +# These are the OBJ files needed to create the LIB target above. +# Paths must all use the '/' character +# +FILES_lib_objs = \ + $(EOLIST) + +# +# implement targets and dependancies (leave this section alone) +# + +libs :: $(OBJDIR) $(TARGET_lib) + +nlms :: libs $(TARGET_nlm) + +# +# Updated this target to create necessary directories and copy files to the +# correct place. (See $(AP_WORK)\build\NWGNUhead.inc for examples) +# +install :: nlms FORCE + +# +# Any specialized rules here +# + +# +# Include the 'tail' makefile that has targets that depend on variables defined +# in this makefile +# + +include $(AP_WORK)\build\NWGNUtail.inc + diff --git a/support/NWGNUmakefile b/support/NWGNUmakefile new file mode 100644 index 0000000000..8a1aef5f41 --- /dev/null +++ b/support/NWGNUmakefile @@ -0,0 +1,245 @@ +# +# Declare the sub-directories to be built here +# + +SUBDIRS = \ + $(EOLIST) + +# +# Get the 'head' of the build environment. This includes default targets and +# paths to tools +# + +include $(AP_WORK)\build\NWGNUhead.inc + +# +# build this level's files + +# +# Make sure all needed macro's are defined +# + +# These directories will be at the beginning of the include list, followed by +# INCDIRS +# +XINCDIRS += \ + $(EOLIST) + +# +# These flags will come after CFLAGS +# +XCFLAGS += \ + $(EOLIST) + +# +# These defines will come after DEFINES +# +XDEFINES += \ + $(EOLIST) + +# +# These flags will be added to the link.opt file +# +XLFLAGS += \ + $(EOLIST) + +# +# These values will be appended to the correct variables based on the value of +# RELEASE +# +ifeq "$(RELEASE)" "debug" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "noopt" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +ifeq "$(RELEASE)" "release" +XINCDIRS += \ + $(EOLIST) + +XCFLAGS += \ + $(EOLIST) + +XDEFINES += \ + $(EOLIST) + +XLFLAGS += \ + $(EOLIST) +endif + +# +# These are used by the link target if an NLM is being generated +# This is used by the link 'name' directive to name the nlm. If left blank +# TARGET_nlm (see below) will be used. +# +NLM_NAME = + +# +# This is used by the link '-desc ' directive. +# If left blank, NLM_NAME will be used. +# +NLM_DESCRIPTION = + +# +# This is used by the '-threadname' directive. If left blank, +# NLM_NAME Thread will be used. +# +NLM_THREAD_NAME = + +# +# If this is specified, it will override VERSION value in +# $(AP_WORK)\build\NWGNUenvironment.inc +# +NLM_VERSION = + +# +# If this is specified, it will override the default of 64K +# +NLM_STACK_SIZE = + + +# +# If this is specified it will be used by the link '-entry' directive +# +NLM_ENTRY_SYM = + +# +# If this is specified it will be used by the link '-exit' directive +# +NLM_EXIT_SYM = + +# +# If this is specified it will be used by the link '-check' directive +# +NLM_CHECK_SYM = + +# +# If these are specified it will be used by the link '-flags' directive +# +NLM_FLAGS = + +# +# If this is specified it will be linked in with the XDCData option in the def +# file instead of the default of $(NWOS)/apache.xdc. XDCData can be disabled +# by setting APACHE_UNIPROC in the environment +# +XDCDATA = + +# +# If there is an NLM target, put it here +# +TARGET_nlm = \ + $(OBJDIR)/htpasswd.nlm \ + $(OBJDIR)/htdigest.nlm \ + $(EOLIST) + +# +# If there is an LIB target, put it here +# +TARGET_lib = \ + $(EOLIST) + +# +# These are the OBJ files needed to create the NLM target above. +# Paths must all use the '/' character +# +FILES_nlm_objs = \ + $(EOLIST) + +# +# These are the LIB files needed to create the NLM target above. +# These will be added as a library command in the link.opt file. +# +FILES_nlm_libs = \ + $(EOLIST) + +# +# These are the modules that the above NLM target depends on to load. +# These will be added as a module command in the link.opt file. +# +FILES_nlm_modules = \ + $(EOLIST) + +# +# If the nlm has a msg file, put it's path here +# +FILE_nlm_msg = + +# +# If the nlm has a hlp file put it's path here +# +FILE_nlm_hlp = + +# +# If this is specified, it will override $(NWOS)\copyright.txt. +# +FILE_nlm_copyright = + +# +# Any additional imports go here +# +FILES_nlm_Ximports = \ + $(EOLIST) + +# +# Any symbols exported to here +# +FILES_nlm_exports = \ + $(EOLIST) + +# +# These are the OBJ files needed to create the LIB target above. +# Paths must all use the '/' character +# +FILES_lib_objs = \ + $(EOLIST) + +# +# implement targets and dependancies (leave this section alone) +# + +libs :: $(OBJDIR) $(TARGET_lib) + +nlms :: libs $(TARGET_nlm) + +# +# Updated this target to create necessary directories and copy files to the +# correct place. (See $(AP_WORK)\build\NWGNUhead.inc for examples) +# +install :: nlms FORCE + copy $(OBJDIR)\*.nlm $(INSTALL)\Apache2\*.* + +# +# Any specialized rules here +# + +# +# Include the 'tail' makefile that has targets that depend on variables defined +# in this makefile +# + +include $(AP_WORK)\build\NWGNUtail.inc + + diff --git a/support/checkgid.c b/support/checkgid.c new file mode 100644 index 0000000000..dacec205cc --- /dev/null +++ b/support/checkgid.c @@ -0,0 +1,145 @@ +/* ==================================================================== + * The Apache Software License, Version 1.1 + * + * Copyright (c) 2001 The Apache Software Foundation. All rights + * reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * 3. The end-user documentation included with the redistribution, + * if any, must include the following acknowledgment: + * "This product includes software developed by the + * Apache Software Foundation (http://www.apache.org/)." + * Alternately, this acknowledgment may appear in the software itself, + * if and wherever such third-party acknowledgments normally appear. + * + * 4. The names "Apache" and "Apache Software Foundation" must + * not be used to endorse or promote products derived from this + * software without prior written permission. For written + * permission, please contact apache@apache.org. + * + * 5. Products derived from this software may not be called "Apache", + * nor may "Apache" appear in their name, without prior written + * permission of the Apache Software Foundation. + * + * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED + * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR + * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF + * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND + * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, + * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT + * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + * SUCH DAMAGE. + * ==================================================================== + * + * This software consists of voluntary contributions made by many + * individuals on behalf of the Apache Software Foundation. For more + * information on the Apache Software Foundation, please see + * <http://www.apache.org/>. + */ + +/* + * Given one or more group identifers on the command line (e.g., + * "httpd" or "#-1"), figure out whether they'll be valid for + * the server to use at run-time. + * + * If a groupname isn't found, or we can't setgid() to it, return + * -1. If all groups are valid, return 0. + * + * This may need to be run as the superuser for the setgid() to + * succeed; running it as any other user may result in a false + * negative. + */ + +#include "ap_config.h" +#if APR_HAVE_STDIO_H +#include <stdio.h> +#endif +#if APR_HAVE_SYS_TYPES_H +#include <sys/types.h> +#endif +#if HAVE_GRP_H +#include <grp.h> +#endif +#if APR_HAVE_UNISTD_H +#include <unistd.h> +#endif + +int main(int argc, char *argv[]) +{ + int i; + int result; + gid_t gid; + struct group *grent; + struct group fake_grent; + + /* + * Assume success. :-) + */ + result = 0; + for (i = 1; i < argc; ++i) { + char *arg; + arg = argv[i]; + + /* + * If it's from a 'Group #-1' statement, get the numeric value + * and skip the group lookup stuff. + */ + if (*arg == '#') { + gid = atoi(&arg[1]); + fake_grent.gr_gid = gid; + grent = &fake_grent; + } + else { + grent = getgrnam(arg); + } + + /* + * A NULL return means no such group was found, so we're done + * with this one. + */ + if (grent == NULL) { + fprintf(stderr, "%s: group '%s' not found\n", argv[0], arg); + result = -1; + } + else { + int check; + + /* + * See if we can switch to the numeric GID we have. If so, + * all well and good; if not, well.. + */ + gid = grent->gr_gid; + check = setgid(gid); + if (check != 0) { + fprintf(stderr, "%s: invalid group '%s'\n", argv[0], arg); + perror(argv[0]); + result = -1; + } + } + } + /* + * Worst-case return value. + */ + return result; +} +/* + * Local Variables: + * mode: C + * c-file-style: "bsd" + * End: + */ diff --git a/support/envvars-std.in b/support/envvars-std.in new file mode 100644 index 0000000000..37a8606278 --- /dev/null +++ b/support/envvars-std.in @@ -0,0 +1,10 @@ +# envvars-std - default environment variables for apachectl +# +# This file is generated from envvars-std.in +# +# the following lines are automatically uncommented for +# binary builds +#binbuild @SHLIBPATH_VAR@='@prefix@/lib/:$@SHLIBPATH_VAR@' +#binbuild export @SHLIBPATH_VAR@ +# +@OS_SPECIFIC_VARS@ diff --git a/support/htdbm.c b/support/htdbm.c new file mode 100644 index 0000000000..b9a2f47eb7 --- /dev/null +++ b/support/htdbm.c @@ -0,0 +1,627 @@ +/* ==================================================================== + * The Apache Software License, Version 1.1 + * + * Copyright (c) 2000-2001 The Apache Software Foundation. All rights + * reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * 3. The end-user documentation included with the redistribution, + * if any, must include the following acknowledgment: + * "This product includes software developed by the + * Apache Software Foundation (http://www.apache.org/)." + * Alternately, this acknowledgment may appear in the software itself, + * if and wherever such third-party acknowledgments normally appear. + * + * 4. The names "Apache" and "Apache Software Foundation" must + * not be used to endorse or promote products derived from this + * software without prior written permission. For written + * permission, please contact apache@apache.org. + * + * 5. Products derived from this software may not be called "Apache", + * nor may "Apache" appear in their name, without prior written + * permission of the Apache Software Foundation. + * + * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED + * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR + * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF + * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND + * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, + * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT + * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + * SUCH DAMAGE. + * ==================================================================== + * + * This software consists of voluntary contributions made by many + * individuals on behalf of the Apache Software Foundation. For more + * information on the Apache Software Foundation, please see + * <http://www.apache.org/>. + * + * Portions of this software are based upon public domain software + * originally written at the National Center for Supercomputing Applications, + * University of Illinois, Urbana-Champaign. + */ + +/* + * htdbm.c: simple program for manipulating DBM + * password databases for the Apache HTTP server + * + * Contributed by Mladen Turk <mturk@mappingsoft.com> + * 12 Oct 2001 + */ + +#include "apr.h" +#include "apr_lib.h" +#include "apr_strings.h" +#include "apr_file_io.h" +#include "apr_file_info.h" +#include "apr_pools.h" +#include "apr_signal.h" +#include "apr_md5.h" +#include "apr_sha1.h" +#include "apr_dbm.h" + +#if APR_HAVE_STDLIB_H +#include <stdlib.h> +#endif +#if APR_HAVE_STRING_H +#include <string.h> +#endif +#if APR_HAVE_STRINGS_H +#include <strings.h> +#endif + +#if APR_CHARSET_EBCDIC +#include "apr_xlate.h" +#endif /*APR_CHARSET_EBCDIC*/ + +#if APR_HAVE_CRYPT_H +#include <crypt.h> +#endif + + +#if !APR_CHARSET_EBCDIC +#define LF 10 +#define CR 13 +#else /*APR_CHARSET_EBCDIC*/ +#define LF '\n' +#define CR '\r' +#endif /*APR_CHARSET_EBCDIC*/ + +#define MAX_STRING_LEN 256 +#define ALG_PLAIN 0 +#define ALG_APMD5 1 +#define ALG_APSHA 2 + +#if APR_HAVE_CRYPT_H +#define ALG_CRYPT 3 +#endif + + +#define ERR_FILEPERM 1 +#define ERR_SYNTAX 2 +#define ERR_PWMISMATCH 3 +#define ERR_INTERRUPTED 4 +#define ERR_OVERFLOW 5 +#define ERR_BADUSER 6 +#define ERR_EMPTY 7 + + +typedef struct apu_htdbm_t apu_htdbm_t; + +struct apu_htdbm_t { + apr_dbm_t *dbm; + apr_pool_t *pool; +#if APR_CHARSET_EBCDIC + apr_xlate_t *to_ascii; +#endif + char *filename; + char *username; + char *userpass; + char *comment; + int create; + int rdonly; + int alg; +}; + + +#define APU_HTDBM_DECLARE(x) static x +#define APU_HTDBM_STANDALONE 1 + +#define APU_HTDBM_MAKE 0 +#define APU_HTDBM_DELETE 1 +#define APU_HTDBM_VERIFY 2 +#define APU_HTDBM_LIST 3 +#define APU_HTDBM_NOFILE 4 +#define APU_HTDBM_STDIN 5 + +APU_HTDBM_DECLARE(void) apu_htdbm_terminate(apu_htdbm_t *htdbm) +{ + + if (htdbm->dbm) + apr_dbm_close(htdbm->dbm); + htdbm->dbm = NULL; +} + +#if APU_HTDBM_STANDALONE + +static apu_htdbm_t *h; + +APU_HTDBM_DECLARE(void) apu_htdbm_interrupted(void) +{ + apu_htdbm_terminate(h); + fprintf(stderr, "htdbm Interrupted !\n"); + exit(ERR_INTERRUPTED); +} +#endif + +APU_HTDBM_DECLARE(apr_status_t) apu_htdbm_init(apr_pool_t **pool, apu_htdbm_t **hdbm) +{ + +#if APR_CHARSET_EBCDIC + apr_status_t rv; +#endif + +#if APU_HTDBM_STANDALONE + apr_initialize(); + atexit(apr_terminate); + apr_pool_create( pool, NULL); + apr_signal(SIGINT, (void (*)(int)) apu_htdbm_interrupted); + +#endif + + (*hdbm) = (apu_htdbm_t *)apr_pcalloc(*pool, sizeof(apu_htdbm_t)); + (*hdbm)->pool = *pool; + +#if APR_CHARSET_EBCDIC + rv = apr_xlate_open(to_ascii, "ISO8859-1", APR_DEFAULT_CHARSET, (*hdbm)->pool); + if (rv) { + fprintf(stderr, "apr_xlate_open(to ASCII)->%d\n", rv); + return APR_EGENERAL; + } + rv = apr_SHA1InitEBCDIC((*hdbm)->to_ascii); + if (rv) { + fprintf(stderr, "apr_SHA1InitEBCDIC()->%d\n", rv); + return APR_EGENERAL; + } + rv = apr_MD5InitEBCDIC((*hdbm)->to_ascii); + if (rv) { + fprintf(stderr, "apr_MD5InitEBCDIC()->%d\n", rv); + return APR_EGENERAL; + } +#endif /*APR_CHARSET_EBCDIC*/ + + /* Set MD5 as default */ + (*hdbm)->alg = ALG_APMD5; + return APR_SUCCESS; +} + +APU_HTDBM_DECLARE(apr_status_t) apu_htdbm_open(apu_htdbm_t *htdbm) +{ + if (htdbm->create) + return apr_dbm_open(&htdbm->dbm, htdbm->filename, APR_DBM_RWCREATE, + APR_OS_DEFAULT, htdbm->pool); + else + return apr_dbm_open(&htdbm->dbm, htdbm->filename, + htdbm->rdonly ? APR_DBM_READONLY : APR_DBM_READWRITE, + APR_OS_DEFAULT, htdbm->pool); +} + +APU_HTDBM_DECLARE(char *) ap_getword(apr_pool_t *atrans, char **line, char stop) +{ + char *pos = strrchr(*line, stop); + char *res; + + if (!pos) { + res = apr_pstrdup(atrans, *line); + *line += strlen(*line); + return res; + } + + res = apr_pstrndup(atrans, *line, pos - *line); + + while (*pos == stop) + ++pos; + *line = pos; + return res; +} + +APU_HTDBM_DECLARE(apr_status_t) apu_htdbm_save(apu_htdbm_t *htdbm, int *changed) +{ + apr_datum_t key, val; + + if (!htdbm->username) + return APR_SUCCESS; + + key.dptr = htdbm->username; + key.dsize = strlen(htdbm->username); + if (apr_dbm_exists(htdbm->dbm, key)) + *changed = 1; + + val.dsize = strlen(htdbm->userpass); + if (!htdbm->comment) + val.dptr = htdbm->userpass; + else { + val.dptr = apr_pstrcat(htdbm->pool, htdbm->userpass, ";", + htdbm->comment, NULL); + val.dsize += (strlen(htdbm->comment) + 1); + } + return apr_dbm_store(htdbm->dbm, key, val); +} + +APU_HTDBM_DECLARE(apr_status_t) apu_htdbm_del(apu_htdbm_t *htdbm) +{ + apr_datum_t key; + + key.dptr = htdbm->username; + key.dsize = strlen(htdbm->username); + if (!apr_dbm_exists(htdbm->dbm, key)) + return APR_ENOENT; + + return apr_dbm_delete(htdbm->dbm, key); +} + +APU_HTDBM_DECLARE(apr_status_t) apu_htdbm_verify(apu_htdbm_t *htdbm) +{ + apr_datum_t key, val; + char pwd[MAX_STRING_LEN] = {0}; + char *rec, *cmnt; + + key.dptr = htdbm->username; + key.dsize = strlen(htdbm->username); + if (!apr_dbm_exists(htdbm->dbm, key)) + return APR_ENOENT; + if (apr_dbm_fetch(htdbm->dbm, key, &val) != APR_SUCCESS) + return APR_ENOENT; + rec = apr_pstrndup(htdbm->pool, val.dptr, val.dsize); + cmnt = strchr(rec, ';'); + if (cmnt) + strncpy(pwd, rec, cmnt - rec); + else + strcpy(pwd, rec); + return apr_password_validate(htdbm->userpass, pwd); +} + +APU_HTDBM_DECLARE(apr_status_t) apu_htdbm_list(apu_htdbm_t *htdbm) +{ + apr_status_t rv; + apr_datum_t key, val; + char *rec, *cmnt; + char kb[MAX_STRING_LEN]; + int i = 0; + + rv = apr_dbm_firstkey(htdbm->dbm, &key); + if (rv != APR_SUCCESS) { + fprintf(stderr, "Empty database -- %s\n", htdbm->filename); + return APR_ENOENT; + } + rec = apr_pcalloc(htdbm->pool, HUGE_STRING_LEN); + + fprintf(stderr, "Dumping records from database -- %s\n", htdbm->filename); + fprintf(stderr, " %-32sComment\n", "Username"); + while (key.dptr != NULL) { + rv = apr_dbm_fetch(htdbm->dbm, key, &val); + if (rv != APR_SUCCESS) { + fprintf(stderr, "Failed getting data from %s\n", htdbm->filename); + return APR_EGENERAL; + } + strncpy(kb, key.dptr, key.dsize); + kb[key.dsize] = '\0'; + fprintf(stderr, " %-32s", kb); + strncpy(rec, val.dptr, val.dsize); + rec[val.dsize] = '\0'; + cmnt = strchr(rec, ';'); + if (cmnt) + fprintf(stderr, cmnt + 1); + fprintf(stderr, "\n"); + rv = apr_dbm_nextkey(htdbm->dbm, &key); + if (rv != APR_SUCCESS) + fprintf(stderr, "Failed getting NextKey\n"); + ++i; + } + + fprintf(stderr, "Total #records : %d\n", i); + return APR_SUCCESS; +} + +static void to64(char *s, unsigned long v, int n) +{ + static unsigned char itoa64[] = /* 0 ... 63 => ASCII - 64 */ + "./0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"; + + while (--n >= 0) { + *s++ = itoa64[v&0x3f]; + v >>= 6; + } +} + +APU_HTDBM_DECLARE(apr_status_t) apu_htdbm_make(apu_htdbm_t *htdbm) +{ + char cpw[MAX_STRING_LEN]; + char salt[9]; + + switch (htdbm->alg) { + case ALG_APSHA: + /* XXX cpw >= 28 + strlen(sha1) chars - fixed len SHA */ + apr_sha1_base64(htdbm->userpass,strlen(htdbm->userpass),cpw); + break; + + case ALG_APMD5: + (void) srand((int) time((time_t *) NULL)); + to64(&salt[0], rand(), 8); + salt[8] = '\0'; + apr_md5_encode((const char *)htdbm->userpass, (const char *)salt, + cpw, sizeof(cpw)); + break; + case ALG_PLAIN: + /* XXX this len limitation is not in sync with any HTTPd len. */ + apr_cpystrn(cpw,htdbm->userpass,sizeof(cpw)); + break; +#if APR_HAVE_CRYPT_H + case ALG_CRYPT: + (void) srand((int) time((time_t *) NULL)); + to64(&salt[0], rand(), 8); + salt[8] = '\0'; + apr_cpystrn(cpw, (char *)crypt(htdbm->userpass, salt), sizeof(cpw) - 1); + fprintf(stderr, "CRYPT is now depriciated, use MD5 instead !\n"); +#endif + default: + break; + } + htdbm->userpass = apr_pstrdup(htdbm->pool, cpw); + return APR_SUCCESS; +} + +APU_HTDBM_DECLARE(apr_status_t) apu_htdbm_valid_username(apu_htdbm_t *htdbm) +{ + if (!htdbm->username || (strlen(htdbm->username) > 64) || (strlen(htdbm->username) < 1)) { + fprintf(stderr, "Invalid username length\n"); + return APR_EINVAL; + } + if (strchr(htdbm->username, ':')) { + fprintf(stderr, "Username contains invalid characters\n"); + return APR_EINVAL; + } + return APR_SUCCESS; +} + +static void htdbm_usage(void) +{ + +#if APR_HAVE_CRYPT_H +#define CRYPT_OPTION "d" +#else +#define CRYPT_OPTION "" +#endif + fprintf(stderr, "htdbm -- program for manipulating DBM password databases.\n\n"); + fprintf(stderr, "Usage: htdbm [-cm"CRYPT_OPTION"pstvx] database username\n"); + fprintf(stderr, " -b[cm"CRYPT_OPTION"ptsv] database username password\n"); + fprintf(stderr, " -n[m"CRYPT_OPTION"pst] username\n"); + fprintf(stderr, " -nb[m"CRYPT_OPTION"pst] username password\n"); + fprintf(stderr, " -v[m"CRYPT_OPTION"ps] database username\n"); + fprintf(stderr, " -vb[m"CRYPT_OPTION"ps] database username password\n"); + fprintf(stderr, " -x[m"CRYPT_OPTION"ps] database username\n"); + fprintf(stderr, " -l database\n"); + fprintf(stderr, "Options:\n"); + fprintf(stderr, " -b Use the password from the command line rather" + "than prompting for it.\n"); + fprintf(stderr, " -c Create a new database.\n"); + fprintf(stderr, " -n Don't update database; display results on stdout.\n"); + fprintf(stderr, " -m Force MD5 encryption of the password (default).\n"); +#if APR_HAVE_CRYPT_H + fprintf(stderr, " -d Force CRYPT encryption of the password (now depriciated).\n"); +#endif + fprintf(stderr, " -p Do not encrypt the password (plaintext).\n"); + fprintf(stderr, " -s Force SHA encryption of the password.\n"); + fprintf(stderr, " -l Display usernames from database on stdout.\n"); + fprintf(stderr, " -t The last param is username comment.\n"); + fprintf(stderr, " -v Verify the username/password.\n"); + fprintf(stderr, " -x Remove the username record from database.\n"); + exit(ERR_SYNTAX); + +} + + +int main(int argc, const char *argv[]) +{ + apr_pool_t *pool; + apr_status_t rv; + apr_size_t l; + char pwi[MAX_STRING_LEN]; + char pwc[MAX_STRING_LEN]; + char errbuf[MAX_STRING_LEN]; + const char *arg; + int need_file = 1; + int need_user = 1; + int need_pwd = 1; + int need_cmnt = 0; + int pwd_supplied = 0; + int changed; + int cmd = APU_HTDBM_MAKE; + int i; + int args_left = 2; + + if ((rv = apu_htdbm_init(&pool, &h)) != APR_SUCCESS) { + fprintf(stderr, "Unable to initialize htdbm terminating!\n"); + apr_strerror(rv, errbuf, sizeof(errbuf)); + exit(1); + } + /* + * Preliminary check to make sure they provided at least + * three arguments, we'll do better argument checking as + * we parse the command line. + */ + if (argc < 3) + htdbm_usage(); + /* + * Go through the argument list and pick out any options. They + * have to precede any other arguments. + */ + for (i = 1; i < argc; i++) { + arg = argv[i]; + if (*arg != '-') + break; + + while (*++arg != '\0') { + switch (*arg) { + case 'b': + pwd_supplied = 1; + need_pwd = 0; + args_left++; + break; + case 'c': + h->create = 1; + break; + case 'n': + need_file = 0; + cmd = APU_HTDBM_NOFILE; + args_left--; + break; + case 'l': + need_pwd = 0; + need_user = 0; + cmd = APU_HTDBM_LIST; + h->rdonly = 1; + args_left--; + break; + case 't': + need_cmnt = 1; + args_left++; + break; + case 'v': + h->rdonly = 1; + cmd = APU_HTDBM_VERIFY; + break; + case 'x': + need_pwd = 0; + cmd = APU_HTDBM_DELETE; + break; + case 'm': + h->alg = ALG_APMD5; + break; + case 'p': + h->alg = ALG_PLAIN; + break; + case 's': + h->alg = ALG_APSHA; + break; +#if APR_HAVE_CRYPT_H + case 'd': + h->alg = ALG_CRYPT; + break; +#endif + default: + htdbm_usage(); + break; + } + } + } + /* + * Make sure we still have exactly the right number of arguments left + * (the filename, the username, and possibly the password if -b was + * specified). + */ + if ((argc - i) != args_left) + htdbm_usage(); + + if (!need_file) + i--; + else { + h->filename = apr_pstrdup(h->pool, argv[i]); + if ((rv = apu_htdbm_open(h)) != APR_SUCCESS) { + fprintf(stderr, "Error oppening database %s\n", argv[i]); + apr_strerror(rv, errbuf, sizeof(errbuf)); + exit(ERR_FILEPERM); + } + } + if (need_user) { + h->username = apr_pstrdup(pool, argv[i+1]); + if (apu_htdbm_valid_username(h) != APR_SUCCESS) + exit(ERR_BADUSER); + } + if (pwd_supplied) + h->userpass = apr_pstrdup(pool, argv[i+2]); + + if (need_pwd) { + l = sizeof(pwc); + if (apr_password_get("Enter password : ", pwi, &l) != APR_SUCCESS) { + fprintf(stderr, "Password too long\n"); + exit(ERR_OVERFLOW); + } + l = sizeof(pwc); + if (apr_password_get("Re-type password : ", pwc, &l) != APR_SUCCESS) { + fprintf(stderr, "Password too long\n"); + exit(ERR_OVERFLOW); + } + if (strcmp(pwi, pwc) != 0) { + fprintf(stderr, "Password verification error\n"); + exit(ERR_PWMISMATCH); + } + + h->userpass = apr_pstrdup(pool, pwi); + } + if (need_cmnt && pwd_supplied) + h->comment = apr_pstrdup(pool, argv[i+3]); + else if (need_cmnt) + h->comment = apr_pstrdup(pool, argv[i+2]); + + switch (cmd) { + case APU_HTDBM_VERIFY: + if ((rv = apu_htdbm_verify(h)) != APR_SUCCESS) { + if(rv == APR_ENOENT) { + fprintf(stderr, "The user '%s' cold not be found in database\n", h->username); + exit(ERR_BADUSER); + } + else { + fprintf(stderr, "Password mismatch for user '%s'\n", h->username); + exit(ERR_PWMISMATCH); + } + } + else + fprintf(stderr, "Password validated for user '%s'\n", h->username); + break; + case APU_HTDBM_DELETE: + if (apu_htdbm_del(h) != APR_SUCCESS) { + fprintf(stderr, "Cannot find user '%s' in database\n", h->username); + exit(ERR_BADUSER); + } + h->username = NULL; + changed = 1; + break; + case APU_HTDBM_LIST: + apu_htdbm_list(h); + break; + default: + apu_htdbm_make(h); + break; + + } + if (need_file && !h->rdonly) { + if ((rv = apu_htdbm_save(h, &changed)) != APR_SUCCESS) { + apr_strerror(rv, errbuf, sizeof(errbuf)); + exit(ERR_FILEPERM); + } + fprintf(stdout, "Database %s %s.\n", h->filename, + h->create ? "created" : (changed ? "modified" : "updated")); + } + if (cmd == APU_HTDBM_NOFILE) + fprintf(stderr, "%s:%s\n", h->username, h->userpass); + apu_htdbm_terminate(h); + apr_terminate(); + + return 0; /* Supress compiler warning. */ +} diff --git a/support/htdbm.dsp b/support/htdbm.dsp new file mode 100644 index 0000000000..613c52fd02 --- /dev/null +++ b/support/htdbm.dsp @@ -0,0 +1,123 @@ +# Microsoft Developer Studio Project File - Name="htdbm" - Package Owner=<4> +# Microsoft Developer Studio Generated Build File, Format Version 6.00 +# ** DO NOT EDIT ** + +# TARGTYPE "Win32 (x86) Console Application" 0x0103 + +CFG=htdbm - Win32 Debug +!MESSAGE This is not a valid makefile. To build this project using NMAKE, +!MESSAGE use the Export Makefile command and run +!MESSAGE +!MESSAGE NMAKE /f "htdbm.mak". +!MESSAGE +!MESSAGE You can specify a configuration when running NMAKE +!MESSAGE by defining the macro CFG on the command line. For example: +!MESSAGE +!MESSAGE NMAKE /f "htdbm.mak" CFG="htdbm - Win32 Debug" +!MESSAGE +!MESSAGE Possible choices for configuration are: +!MESSAGE +!MESSAGE "htdbm - Win32 Release" (based on "Win32 (x86) Console Application") +!MESSAGE "htdbm - Win32 Debug" (based on "Win32 (x86) Console Application") +!MESSAGE + +# Begin Project +# PROP AllowPerConfigDependencies 0 +# PROP Scc_ProjName "" +# PROP Scc_LocalPath "" +CPP=cl.exe +RSC=rc.exe + +!IF "$(CFG)" == "htdbm - Win32 Release" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 0 +# PROP BASE Output_Dir "Release" +# PROP BASE Intermediate_Dir "Release" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 0 +# PROP Output_Dir "Release" +# PROP Intermediate_Dir "Release" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MD /W3 /O2 /D "WIN32" /D "NDEBUG" /D "_CONSOLE" /D "_MBCS" /D "APR_DECLARE_STATIC" /D "APU_DECLARE_STATIC" /FD /c +# ADD CPP /nologo /MD /W3 /O2 /I "../srclib/apr/include" /I "../srclib/apr-util/include" /D "NDEBUG" /D "WIN32" /D "_CONSOLE" /D "APR_DECLARE_STATIC" /D "APU_DECLARE_STATIC" /Fd"Release/htdbm" /FD /c +# ADD BASE RSC /l 0x409 /d "NDEBUG" +# ADD RSC /l 0x409 /d "NDEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib advapi32.lib wsock32.lib ws2_32.lib /nologo /subsystem:console /map /machine:I386 +# ADD LINK32 kernel32.lib advapi32.lib wsock32.lib ws2_32.lib /nologo /subsystem:console /map /machine:I386 + +!ELSEIF "$(CFG)" == "htdbm - Win32 Debug" + +# PROP BASE Use_MFC 0 +# PROP BASE Use_Debug_Libraries 1 +# PROP BASE Output_Dir "Debug" +# PROP BASE Intermediate_Dir "Debug" +# PROP BASE Target_Dir "" +# PROP Use_MFC 0 +# PROP Use_Debug_Libraries 1 +# PROP Output_Dir "Debug" +# PROP Intermediate_Dir "Debug" +# PROP Ignore_Export_Lib 0 +# PROP Target_Dir "" +# ADD BASE CPP /nologo /MDd /W3 /GX /Zi /Od /D "WIN32" /D "_DEBUG" /D "_CONSOLE" /D "_MBCS" /D "APR_DECLARE_STATIC" /D "APU_DECLARE_STATIC" /FD /c +# ADD CPP /nologo /MDd /W3 /GX /Zi /Od /I "../srclib/apr/include" /I "../srclib/apr-util/include" /D "_DEBUG" /D "WIN32" /D "_CONSOLE" /D "APR_DECLARE_STATIC" /D "APU_DECLARE_STATIC" /Fd"Debug/htdbm" /FD /c +# ADD BASE RSC /l 0x409 /d "_DEBUG" +# ADD RSC /l 0x409 /d "_DEBUG" +BSC32=bscmake.exe +# ADD BASE BSC32 /nologo +# ADD BSC32 /nologo +LINK32=link.exe +# ADD BASE LINK32 kernel32.lib advapi32.lib wsock32.lib ws2_32.lib /nologo /subsystem:console /incremental:no /map /debug /machine:I386 +# ADD LINK32 kernel32.lib advapi32.lib wsock32.lib ws2_32.lib /nologo /subsystem:console /incremental:no /map /debug /machine:I386 + +!ENDIF + +# Begin Target + +# Name "htdbm - Win32 Release" +# Name "htdbm - Win32 Debug" +# Begin Source File + +SOURCE=.\htdbm.c +# End Source File +# Begin Source File + +SOURCE=.\htdbm.rc +# End Source File +# Begin Source File + +SOURCE=..\build\win32\win32ver.awk + +!IF "$(CFG)" == "htdbm - Win32 Release" + +# PROP Ignore_Default_Tool 1 +# Begin Custom Build - Creating Version Resource +InputPath=..\build\win32\win32ver.awk + +".\htdbm.rc" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)" + awk -f ../build/win32/win32ver.awk htdbm "htdbm Utility" ../include/ap_release.h > .\htdbm.rc + +# End Custom Build + +!ELSEIF "$(CFG)" == "htdbm - Win32 Debug" + +# PROP Ignore_Default_Tool 1 +# Begin Custom Build - Creating Version Resource +InputPath=..\build\win32\win32ver.awk + +".\htdbm.rc" : $(SOURCE) "$(INTDIR)" "$(OUTDIR)" + awk -f ../build/win32/win32ver.awk htdbm "htdbm Utility" ../include/ap_release.h > .\htdbm.rc + +# End Custom Build + +!ENDIF + +# End Source File +# End Target +# End Project diff --git a/support/utilitiesnw.def b/support/utilitiesnw.def new file mode 100644 index 0000000000..426b8c96be --- /dev/null +++ b/support/utilitiesnw.def @@ -0,0 +1,3 @@ +MODULE APRLIB.NLM +MODULE LIBC.NLM + |
