Core functions

Overview

mod_core module provides implementation of features that are used in Helicon Ape as a whole.

Quick start

##
## The following code enables most detailed logging for Ape
## put it in the httpd.conf
Loglevel debug
ErrorLog error.log

##
## use htaccess.txt instead of .htaccess
## put it in the httpd.conf
AccessFileName htaccess.txt

##
## put it in the httpd.conf
Options +StopOnError +ShowErrorInResponse

Related articles and topics

• Helicon Ape Overview
• Context and processing order
• NTFS permissions requirements
• Helicon Ape License Manager
• Helicon Ape mod_proxy: proxy-server inside IIS

Directives

AccessFileName

AccessFileName directive specifies a list of file names that Helicon Ape will consider the names of distributed configurations. Default file name is .htaccess . Helicon Ape will only load the first found file in this list.

When any changes are applied to the configuration file it will be reloaded automatically upon the next request to the server.

Note! If you are about to change default configuration file name using AccessFileName directive, you'll need to write rules to protect them manually.

Syntax

AccessFileName .htaccess|filename [filename] [...]

Example

To protect configuration files starting from .ht the following piece of code will be written in your httpd.conf upon installation:

<Files ~ ^.ht>
	RewriteEngine on
	RewriteRule . - [F]
</Files>

AllowOverride

AllowOverride directive declares which directives in distributed . htaccess files can override parent level directives ( httpd.conf ). This directive also enables or disables . htaccess files for specific virtual host (web site) or directory.

Syntax

AllowOverride All|None|directive-type [directive-type] [...]

The following values are supported:

• AuthConfig - allows to use authorization directives (AuthGroupFile, AuthName, AuthType, AuthUserFile, Require, etc.).
• FileInfo - allows to use directives controlling document types, document meta data, mod_rewrite directives (RewriteEngine, RewriteOptions, RewriteBase, RewriteCond, RewriteRule).
• Indexes - allows to use directives controlling directory indexing.
• Limit - allows to use directives controlling host access (Allow, Deny and Order).
• Options[=Option,...] - allows to use directives controlling specific directory features. An equal sign may be given followed by a comma-separated lists of options that may be set using the Options command.
• All value enables .htaccess file and all directives in it.
• None disables all .htaccess files and directives.

This directive is inheritable. This means if you specify AllowOverride none for some directory, .htaccess files will also be disabled for all subdirectories.

Note! AllowOverride function has the default value of All . AllowOverride None is usually necessary only on high-load servers, when you need to stop processing of .htaccess files inside specific locations:

Example

AllowOverride none
<VirtualHost onesite.com www.onesite.com>
	AllowOverride all
</VirtualHost>

AuthName

AuthName directive sets the name of the authorization realm for the directory. This realm is needed for the user to know which username and password to send. AuthName has a single argument - auth-domain . If the realm name contains spaces, it must be enclosed into quotation marks. It must be accompanied by AuthType and Require directives, and directives such as AuthUserFile and AuthGroupFile to work.

Syntax

AuthName auth-domain

Example

AuthName "Secret"

The string set to AuthName will appear in the password dialog provided by most browsers.

AuthType

AuthType directive allows to choose between Basic and Digest authentication.

To implement authentication you must also use the AuthName and Require directives. In addition, the server must have an authentication -provider module such as mod_authn_file and an authorization module such as mod_authz_user .

Syntax

AuthType Basic|Digest

Example

#choose Basic authentication type 
AuthType Basic

ErrorDocument

ErrorDocument directive defines the document that will be shown to the client upon error.

Syntax

ErrorDocument error-code document

Description

• document parameter may be specified either relative to the document root (starting with slash) or as a full URL (starting with protocol, domain name, etc.). Alternatively, you may ask a browser to display custom error description.

Example

ErrorDocument 500 http://www.domain.com/cgi-bin/tester
ErrorDocument 404 /custom_error_page.htm
ErrorDocument 403 "Sorry, the access is forbidden"

Additionally, the special value "default" can be used to tell Ape use standard hardcoded message. Usually, it's not necessary to specify this explicitly, unless you need different behavior in different contexts.

Example

ErrorDocument 404 /cgi-bin/bad_urls.pl

<Directory /web/docs>
ErrorDocument 404 default
</Directory>

Note that when you specify an ErrorDocument that points to a remote URL (fully qualified path), Ape 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 implies 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 URL validity based on the status code. In addition, if you use remote URL in ErrorDocument 401 , the client will not know whether to prompt the user for a password since it will not receive the 401 status code. Therefore, if you use an ErrorDocument 401 directive, it must refer to a local document.

ErrorLog

ErrorLog directive sets the name of the file to which the server will log errors it encounters. If the file-path is not absolute, it is assumed to be relative to the ServerRoot . Write permissions for IIS_IUSRS group or account running IIS paalication pool should for Ape to be able to write logs.

Syntax

ErrorLog log_file_path optionalParameter1 value optionalParameter2 value

By default logs are written in /log directory inside Helicon Ape installation folder. Optional parameters of the directive:

• archiveAboveSize - Size in kilobytes above which log files will be automatically archived.
• maxArchiveFiles - Maximum number of archive files that should be kept. Default: 9
• archiveNumbering - Way file archives are numbered. Possible values:
  • Rolling - Rolling style numbering (the most recent is always #0 then #1, ..., #N.
  • Sequence - Sequence style numbering. The most recent archive has the highest number.
  • Date - Date style numbering. The date is formatted according to the value of archiveDateFormat.
• archiveEvery - Indicates whether to automatically archive log files every time the specified time passes. Possible values:
  • Day - Archive daily.
  • Hour - Archive every hour.
  • Minute - Archive every minute.
  • Month - Archive every month.
  • None - Don't archive based on time.
  • Year - Archive every year.

Example

ErrorLog c:/inetpub/logs/Ape_logs/error.log

ErrorLog logs/error.log archiveEvery Day archiveNumbering Date

FreeSites

FreeSites directive is used to specify for which sites (up to 3!) Ape free licenses will be applied.

id1, id2, id3 are the identifiers of the sites in IIS.

Syntax

FreeSites #id1 #id2 #id3

Example

FreeSites #id123 #id456 #id789

See also

RegistrationName , RegistrationCode

Include

Include directive allows inclusion of other configuration files from within the server configuration files. The file-path specified may be an absolute path, or may be relative to the ApeRoot directory.

Syntax

Include file-path|directory-path

Example

Include /ape/conf/file.conf
Include conf/file.conf

LogLevel

LogLevel directive adjusts the verbosity of the messages recorded in the error logs. The following values are possible:

Syntax

LogLevel none|emerg|alert|crit|error|warn|notice|info|debug

• none — Log nothing
• emerg — Emergencies - system is unusable
• alert — Action must be taken immediately
• crit — Critical Conditions
• error — Error conditions
• warn — Warning conditions
• notice — Normal but significant condition
• info — Informational records
• debug — Debug-level messages

Example

#enable datailed log
LogLevel debug

Example

#disable log for the example.com
<VirtualHost www.example.com>
    LogLevel none
</VirtualHost>

Options

Options directive controls which server features are available in a particular directory.

Syntax

Options All [+|-]option [[+|-]option] [...]

Description

• option parameter may be set to None , in which case none of the extra features are enabled, or one or more of the following:
  • All (default) - all supported options are enabled
  • ExecCGI (currently not supported in Ape)
  • FollowSymLinks (currently not supported in Ape)
  • Includes (currently not supported in Ape)
  • IncludesNOEXEC (currently not supported in Ape)
  • Indexes (currently not supported in Ape)
  • MultiViews (currently not supported in Ape)
  • ShowErrorInResponse (Helicon Ape specific option) - show detailed error explanation

    This parameter allows to make error page more informative by adding detailed error description to the page.

    By default, Ape will append explanation of all errors that occurred during request processing to Ape error.log and to the browser error page.

    Note! This parameter will take effect only when the Detailed Error option is selected in IIS Manager -> Error Pages -> Edit Feature Settings...

  • StopOnError (Helicon Ape specific option) - regulates whether to ignore unknown directives or give out 500 error

    This parameter regulates whether Helicon Ape should ignore unknown directives in its configs or give out the 500 error.

    By default, having found the syntax error in config Ape will stop request processing.

    Note! This parameter will take effect only when the Detailed Error option is selected in IIS Manager -> Error Pages -> Edit Feature Settings...

  • FileChangesEventedMode (Helicon Ape specific option) - watch for .htaccess and other file changes using ReadDirectoryChangesW Windows API. Offers best performance and resource economy, but may be sensitive for "List folder content" NTFS permissions and some other restrictions. Disable this option if changes are not monitored correctly. When disabled, file changes will be monitored using poll method.
  • SymLinksIfOwnerMatch (currently not supported in Ape)
  • NeverChangeServerVariables prohibit Ape from changing IIS server variables when using SetEnv and similar directives. This is needed to address IIS 8.5 bug that crashes IIS upon some server variable modification. This option is enabled by default on IIS 8.5 machines and disabled on others. When enabled environment variables are still avaialble in Ape context, but to obtain environment variable value in application code you need to request HTTP headers with "X-EnvironmentVariableName" naming agreement.

Example

#force Ape to append explanation of error(s) that occurred during request processing
#Note! We recommend to use this setting only for testing purposes
Options +StopOnError +ShowErrorInResponse

Example

#force Ape to ignore syntax errors in config
#Attention! We do not recommend to use this setting as it leads to unnoticed typos
Options -StopOnError

RegistrationCode

RegistrationCode directive is used to specify Ape registration code for the specific content.

Note! RegistrationCode and RegistrationName directives enable Ape for the context they are located in.

Syntax

RegistrationCode= code

Example

RegistrationName= name
RegistrationCode= 11111-22222-33333-44444

See also

RegistrationName , FreeSites

RegistrationName

RegistrationName directive is used to specify Ape registration name for the specific content.

Note! RegistrationCode and RegistrationName directives enable Ape for the context they are located in.

Syntax

RegistrationName= name

Example

RegistrationName= name
RegistrationCode= 11111-22222-33333-44444

See also

RegistrationCode , FreeSites

Require

Require directive selects which authenticated users can access a resource. The restrictions are processed by authorization modules.

Syntax

Require entity-name [entity-name] [...]

Example

#Only named users can access the resource
Require user userid1 userid2
#Only users in the named groups can access the resource
Require group groupname1 groupname2
#All valid users can access the resource
Require valid-user

Satisfy

Satisfy directive defines access policy if both Allow and Require directives are used (i.e. a particular area is restricted by both username/password and client host address).

Syntax

Satisfy Any|All

Description

• All (default) — both correct address and valid username/password are required.
• Any — either correct address or valid username/password is sufficient to be granted access.

Example

Require valid-user
Allow from 192.168.1
Satisfy Any

SetInputFilter

SetInputFilter directive activates the name filter. If there are multiple filters to activate, semicolons must be put between the names.

Syntax

SetInputFilter name [;name]

Example

SetInputFilter <mod_replace>

Note! mod_replace and mod_filter do not have predefined filter names; they shall be specified explicitly (see corresponding docs articles).

SetOutputFilter

SetOutputFilter directive activates the name filter. If there are multiple filters to activate, semicolons must be put between the names.

Syntax

SetOutputFilter name [;name]

Example

SetOutputFilter gzip;hotlink;linkfreeze;<mod_replace>;<mod_filter>

Note! mod_replace and mod_filter do not have predefined filter names; they shall be specified explicitly (see corresponding docs articles).

<Directory>

<Directory> ... </Directory> tag is used to group directives that will be applied to the specific file system directory and sub-directories. Wildcard characters '?' and '*' are allowed. Regular expressions can also be used with prepended ~ character.

Be careful with directory-path arguments: They have to literally match the file system path which is used to access files. Directives applied to the particular <Directory> will not be applied to files accessed from that directory via a different path, i.e. via different symbolic links. Only fully qualified file paths are allowed.

Syntax

<Directory directory-path> ... </Directory>

Example

<Directory C:/inetpub/>
	AllowOverride None
</Directory>

<Directory C:/inetpub/home/>
	AllowOverride FileInfo
</Directory>

<Directory ~ "C:/inetpub/wwwroot/.*/[0-9]{3}">
	# ... directives here ...
</Directory> 

<DirectoryMatch>

<DirectoryMatch> ... </DirectoryMatch> is used to enclose a group of directives which will be applied only to the specified file system directory and its sub-directories. This directive works exactly as <Directory ~> .

Syntax

<DirectoryMatch regex> ... </DirectoryMatch>

Example

<DirectoryMatch "^/www/(.+/)?[0-9]{3}">
	# ... directives here ...
</DirectoryMatch> 

<Files>

<Files> directive limits the scope of enclosed directives by filename. The filename argument should include a filename, it supports '?' and '*' wildcards and regular expressions with prepended ~ character.

Syntax

<Files filename> ... </Files>

Example

<Files index.*>
	# ... directives here ...
</Files>

<Files ~ "\.(gif|jpe?g|png)$">
	# ... directives here ...
</Files>

<FilesMatch>

<FilesMatch> directive does exactly the same as <Files ~> .

Syntax

<Files filename> ... </Files>

Example

<FilesMatch regex> ... </FilesMatch>

<IfModule>

<IfModule> section is used to mark directives that are dependant on the presence of a specific module.

The test in <IfModule> section may be performed in two ways:

module
!module

In the first case the directives will only be processed if the module named module is included in Helicon Ape. The second case implies the reverse situation and processes the directives only if module is not included.

Syntax

<IfModule [!]module-file|module-identifier> ... </IfModule>

Example

<IfModule rewrite_module>
    RewriteEngine On
    ...
</FilesMatch>

<Limit>

<Limit> section allows to restrict the effect of the access controls to the nominated HTTP methods.

Methods include: GET, POST, PUT, DELETE, CONNECT, OPTIONS, PATCH, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK and more.

Note! The method name is case-sensitive.

Note! If GET is used, HEAD requests will also be restricted. The TRACE method cannot be limited.

Syntax

<Limit method [method] ... > ... </Limit>

Example

<Limit POST PUT DELETE>
	Require valid-user
</Limit>

<LimitExcept>

<LimitExcept> section is used to enclose a group of access control directives which will be applied to any HTTP access method not listed in the arguments. This directive has reverse effect to <Limit> directive.

Syntax

<LimitExcept method [method] ... > ... </LimitExcept>

Example

<LimitExcept POST GET>
	Require valid-user
</LimitExcept>

<Location>

<Location> ... </Location> tag is used to group directives that will apply to specific URL or virtual path. <Location> sections operate completely outside the file system thus these directives should not be used to control access to file system locations since several different URLs may map to the same file system location.

Syntax

<Location URL-path|URL> ... </Location>

Description

• URL-path is a virtual path in the form /path/. Protocol, hostname, port and query string may be lacking. URL-path may include wildcards '?' and '*' or regular expression starting with ~ character.

Example

<Location /directory>
	# ... rules go here
</Location>

<Location />
	# ... more rules go here
</Location>

<LocationMatch>

<LocationMatch> directive does exactly the same as <Location ~> .

Syntax

<LocationMatch regex> ... </LocationMatch>

Example

<LocationMatch "/(home|section)/bin">
# ... rules go here
</LocationMatch> 

<Proxy>

<Proxy> section may include directives that will apply only to matching proxied content. Wildcards are possible.

Note! mod_proxy is required to make <Proxy> directive working.

Syntax

<Proxy wildcard-url> ...</Proxy>

Example

Below is an example to allow hosts only from somenet.example.com access content via your proxy server:

<Proxy *>
	Order deny,allow
	Deny from all
	Allow from somenet.example.com
</Proxy>

Example

Here's an example to process all files in foo directory of example.com through the INCLUDES filter when they are sent through proxy server:

<Proxy http://example.com/foo/*>
	SetOutputFilter INCLUDES
</Proxy>

<ProxyMatch>

<ProxyMatch> directive is identical to <Proxy> directive, except that it matches URLs using regular expressions.

Syntax

<ProxyMatch regex> ...</ProxyMatch>

<VirtualHost>

<VirtualHost> ... </VirtualHost> tag is used to group directives that will be applied to the specific virtual host.

Syntax

<VirtualHost addr[:port] [addr[:port]] ...> 
    ... 
</VirtualHost>

Description

• addr may be one of the following:
  
  • Specific IP address;
  • Fully qualified domain name;
  • The string _default_ , which will match all unattended requests.

Example

RewriteEngine off
AllowOverride none
<VirtualHost onesite.com www.onesite.com>
	RewriteEngine on
	AllowOverride all
</VirtualHost>